@endora-commerce/contracts 0.100.0

package/dist/analytics.js

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+import { isoDateTimeSchema, uuidSchema } from './common.js';
+/**
+ * Analytics event contracts (US10 / FR-110, FR-111).
+ *
+ * Storefront and admin emit a small, fixed set of event types into the
+ * platform; backend persists them and exposes aggregated read paths for the
+ * admin dashboard. Forwarding to an external analytics tool (e.g. GA4) is
+ * a separate config-flagged path that consumes the same events.
+ */
+export const analyticsEventTypeSchema = z.enum([
+    'product.viewed',
+    'product.added_to_cart',
+    'cart.abandoned',
+    'order.placed',
+    'search.performed',
+    'filter.clicked',
+    'category.viewed',
+]);
+/**
+ * A single inbound analytics event. The shape is intentionally permissive
+ * inside `properties` — the storefront chooses what to send per event type.
+ */
+export const ingestAnalyticsEventSchema = z.object({
+    type: analyticsEventTypeSchema,
+    occurredAt: isoDateTimeSchema.optional(),
+    salesChannelId: uuidSchema.optional(),
+    customerAccountId: uuidSchema.optional(),
+    organizationId: uuidSchema.optional(),
+    sessionId: z.string().min(1).max(64).optional(),
+    properties: z.record(z.string(), z.unknown()).optional(),
+});
+/**
+ * Storefront sends events in batches to amortise HTTP overhead.
+ */
+export const ingestAnalyticsBatchRequestSchema = z.object({
+    events: z.array(ingestAnalyticsEventSchema).min(1).max(100),
+});
+export const ingestAnalyticsBatchResponseSchema = z.object({
+    accepted: z.number().int().nonnegative(),
+    rejected: z
+        .array(z.object({
+        index: z.number().int().nonnegative(),
+        reason: z.string(),
+    }))
+        .default([]),
+});
+/**
+ * Admin aggregation read paths.
+ */
+export const analyticsSummaryQuerySchema = z.object({
+    from: isoDateTimeSchema,
+    to: isoDateTimeSchema,
+    salesChannelId: uuidSchema.optional(),
+});
+export const analyticsDailyPointSchema = z.object({
+    day: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'YYYY-MM-DD'),
+    type: analyticsEventTypeSchema,
+    count: z.number().int().nonnegative(),
+});
+export const analyticsSummaryResponseSchema = z.object({
+    totalsByType: z.array(z.object({
+        type: analyticsEventTypeSchema,
+        count: z.number().int().nonnegative(),
+    })),
+    daily: z.array(analyticsDailyPointSchema),
+});
+//# sourceMappingURL=analytics.js.map

package/dist/analytics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.js","sourceRoot":"","sources":["../src/analytics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE5D;;;;;;;GAOG;AAEH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,IAAI,CAAC;IAC7C,gBAAgB;IAChB,uBAAuB;IACvB,gBAAgB;IAChB,cAAc;IACd,kBAAkB;IAClB,gBAAgB;IAChB,iBAAiB;CAClB,CAAC,CAAC;AAGH;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,IAAI,EAAE,wBAAwB;IAC9B,UAAU,EAAE,iBAAiB,CAAC,QAAQ,EAAE;IACxC,cAAc,EAAE,UAAU,CAAC,QAAQ,EAAE;IACrC,iBAAiB,EAAE,UAAU,CAAC,QAAQ,EAAE;IACxC,cAAc,EAAE,UAAU,CAAC,QAAQ,EAAE;IACrC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE;IAC/C,UAAU,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;CACzD,CAAC,CAAC;AAGH;;GAEG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,CAAC,CAAC,MAAM,CAAC;IACxD,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;CAC5D,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,kCAAkC,GAAG,CAAC,CAAC,MAAM,CAAC;IACzD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IACxC,QAAQ,EAAE,CAAC;SACR,KAAK,CACJ,CAAC,CAAC,MAAM,CAAC;QACP,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QACrC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;KACnB,CAAC,CACH;SACA,OAAO,CAAC,EAAE,CAAC;CACf,CAAC,CAAC;AAGH;;GAEG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,IAAI,EAAE,iBAAiB;IACvB,EAAE,EAAE,iBAAiB;IACrB,cAAc,EAAE,UAAU,CAAC,QAAQ,EAAE;CACtC,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,qBAAqB,EAAE,YAAY,CAAC;IAC1D,IAAI,EAAE,wBAAwB;IAC9B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;CACtC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,CAAC,MAAM,CAAC;IACrD,YAAY,EAAE,CAAC,CAAC,KAAK,CACnB,CAAC,CAAC,MAAM,CAAC;QACP,IAAI,EAAE,wBAAwB;QAC9B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;KACtC,CAAC,CACH;IACD,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,yBAAyB,CAAC;CAC1C,CAAC,CAAC"}

package/dist/api-keys.d.ts

@@ -0,0 +1,97 @@
+import { z } from 'zod';
+/**
+ * API key contracts (US7 / FR-120, extended by feature 062 Distributor API).
+ * The plaintext bearer token is shown once at creation; only its sha256 hash
+ * is stored.
+ */
+export declare const apiKeyStatusSchema: z.ZodEnum<{
+    active: "active";
+    revoked: "revoked";
+}>;
+export type ApiKeyStatus = z.infer<typeof apiKeyStatusSchema>;
+/**
+ * Typed scope catalog (feature 062, research §R3). Enforcement stays
+ * membership-based, so stored legacy free-text scopes remain readable and
+ * enforceable — only *creation* validates against this enum.
+ *
+ * - `catalog:read`  — PIM reads (unbound) AND distributor catalog surface (bound)
+ * - `catalog:write` — PIM by-SKU upsert — UNBOUND KEYS ONLY
+ * - `orders:read`   — distributor order reads — BOUND KEYS ONLY
+ * - `orders:write`  — distributor order intake — BOUND KEYS ONLY
+ */
+export declare const apiKeyScopeSchema: z.ZodEnum<{
+    "catalog:read": "catalog:read";
+    "catalog:write": "catalog:write";
+    "orders:read": "orders:read";
+    "orders:write": "orders:write";
+}>;
+export type ApiKeyScope = z.infer<typeof apiKeyScopeSchema>;
+/**
+ * Distributor binding (feature 062, contracts/api-key-binding.md §2).
+ * All-or-none: a key is either fully bound (org + channel + designated
+ * service customer account) or fully unbound. Immutable post-create.
+ */
+export declare const apiKeyBindingSchema: z.ZodObject<{
+    organizationId: z.ZodString;
+    salesChannelId: z.ZodString;
+    customerAccountId: z.ZodString;
+}, z.core.$strip>;
+export type ApiKeyBinding = z.infer<typeof apiKeyBindingSchema>;
+export declare const apiKeySchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    lastFour: z.ZodString;
+    scopes: z.ZodArray<z.ZodString>;
+    status: z.ZodEnum<{
+        active: "active";
+        revoked: "revoked";
+    }>;
+    lastUsedAt: z.ZodNullable<z.ZodString>;
+    revokedAt: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    organizationId: z.ZodNullable<z.ZodString>;
+    salesChannelId: z.ZodNullable<z.ZodString>;
+    customerAccountId: z.ZodNullable<z.ZodString>;
+    expiresAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type ApiKey = z.infer<typeof apiKeySchema>;
+export declare const createApiKeyRequestSchema: z.ZodObject<{
+    name: z.ZodString;
+    scopes: z.ZodArray<z.ZodEnum<{
+        "catalog:read": "catalog:read";
+        "catalog:write": "catalog:write";
+        "orders:read": "orders:read";
+        "orders:write": "orders:write";
+    }>>;
+    binding: z.ZodOptional<z.ZodObject<{
+        organizationId: z.ZodString;
+        salesChannelId: z.ZodString;
+        customerAccountId: z.ZodString;
+    }, z.core.$strip>>;
+    expiresAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CreateApiKeyRequest = z.infer<typeof createApiKeyRequestSchema>;
+export declare const createApiKeyResponseSchema: z.ZodObject<{
+    apiKey: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        lastFour: z.ZodString;
+        scopes: z.ZodArray<z.ZodString>;
+        status: z.ZodEnum<{
+            active: "active";
+            revoked: "revoked";
+        }>;
+        lastUsedAt: z.ZodNullable<z.ZodString>;
+        revokedAt: z.ZodNullable<z.ZodString>;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+        organizationId: z.ZodNullable<z.ZodString>;
+        salesChannelId: z.ZodNullable<z.ZodString>;
+        customerAccountId: z.ZodNullable<z.ZodString>;
+        expiresAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    bearerToken: z.ZodString;
+}, z.core.$strip>;
+export type CreateApiKeyResponse = z.infer<typeof createApiKeyResponseSchema>;
+//# sourceMappingURL=api-keys.d.ts.map

package/dist/api-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-keys.d.ts","sourceRoot":"","sources":["../src/api-keys.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;GAIG;AAEH,eAAO,MAAM,kBAAkB;;;EAAgC,CAAC;AAChE,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB;;;;;EAK5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;;iBAK9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;iBAgBvB,CAAC;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAElD,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;iBAKpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;iBAIrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC"}

package/dist/api-keys.js

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+import { isoDateTimeSchema, uuidSchema } from './common.js';
+/**
+ * API key contracts (US7 / FR-120, extended by feature 062 Distributor API).
+ * The plaintext bearer token is shown once at creation; only its sha256 hash
+ * is stored.
+ */
+export const apiKeyStatusSchema = z.enum(['active', 'revoked']);
+/**
+ * Typed scope catalog (feature 062, research §R3). Enforcement stays
+ * membership-based, so stored legacy free-text scopes remain readable and
+ * enforceable — only *creation* validates against this enum.
+ *
+ * - `catalog:read`  — PIM reads (unbound) AND distributor catalog surface (bound)
+ * - `catalog:write` — PIM by-SKU upsert — UNBOUND KEYS ONLY
+ * - `orders:read`   — distributor order reads — BOUND KEYS ONLY
+ * - `orders:write`  — distributor order intake — BOUND KEYS ONLY
+ */
+export const apiKeyScopeSchema = z.enum([
+    'catalog:read',
+    'catalog:write',
+    'orders:read',
+    'orders:write',
+]);
+/**
+ * Distributor binding (feature 062, contracts/api-key-binding.md §2).
+ * All-or-none: a key is either fully bound (org + channel + designated
+ * service customer account) or fully unbound. Immutable post-create.
+ */
+export const apiKeyBindingSchema = z.object({
+    organizationId: uuidSchema,
+    salesChannelId: uuidSchema,
+    /** Must reference an active customer account belonging to `organizationId`. */
+    customerAccountId: uuidSchema,
+});
+export const apiKeySchema = z.object({
+    id: uuidSchema,
+    name: z.string(),
+    lastFour: z.string(),
+    scopes: z.array(z.string()),
+    status: apiKeyStatusSchema,
+    lastUsedAt: isoDateTimeSchema.nullable(),
+    revokedAt: isoDateTimeSchema.nullable(),
+    createdAt: isoDateTimeSchema,
+    updatedAt: isoDateTimeSchema,
+    // Feature 062 — additive binding/expiry fields; always present, null for
+    // unbound / non-expiring keys.
+    organizationId: uuidSchema.nullable(),
+    salesChannelId: uuidSchema.nullable(),
+    customerAccountId: uuidSchema.nullable(),
+    expiresAt: isoDateTimeSchema.nullable(),
+});
+export const createApiKeyRequestSchema = z.object({
+    name: z.string().min(1).max(160),
+    scopes: z.array(apiKeyScopeSchema).min(1),
+    binding: apiKeyBindingSchema.optional(),
+    expiresAt: isoDateTimeSchema.optional(),
+});
+export const createApiKeyResponseSchema = z.object({
+    apiKey: apiKeySchema,
+    /** The raw bearer token, only returned once at creation. */
+    bearerToken: z.string(),
+});
+//# sourceMappingURL=api-keys.js.map

package/dist/api-keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-keys.js","sourceRoot":"","sources":["../src/api-keys.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE5D;;;;GAIG;AAEH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC;AAGhE;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,IAAI,CAAC;IACtC,cAAc;IACd,eAAe;IACf,aAAa;IACb,cAAc;CACf,CAAC,CAAC;AAGH;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,cAAc,EAAE,UAAU;IAC1B,cAAc,EAAE,UAAU;IAC1B,+EAA+E;IAC/E,iBAAiB,EAAE,UAAU;CAC9B,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,EAAE,EAAE,UAAU;IACd,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC3B,MAAM,EAAE,kBAAkB;IAC1B,UAAU,EAAE,iBAAiB,CAAC,QAAQ,EAAE;IACxC,SAAS,EAAE,iBAAiB,CAAC,QAAQ,EAAE;IACvC,SAAS,EAAE,iBAAiB;IAC5B,SAAS,EAAE,iBAAiB;IAC5B,yEAAyE;IACzE,+BAA+B;IAC/B,cAAc,EAAE,UAAU,CAAC,QAAQ,EAAE;IACrC,cAAc,EAAE,UAAU,CAAC,QAAQ,EAAE;IACrC,iBAAiB,EAAE,UAAU,CAAC,QAAQ,EAAE;IACxC,SAAS,EAAE,iBAAiB,CAAC,QAAQ,EAAE;CACxC,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IAChC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACzC,OAAO,EAAE,mBAAmB,CAAC,QAAQ,EAAE;IACvC,SAAS,EAAE,iBAAiB,CAAC,QAAQ,EAAE;CACxC,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,MAAM,EAAE,YAAY;IACpB,4DAA4D;IAC5D,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;CACxB,CAAC,CAAC"}