@endora-commerce/contracts 0.100.0

package/dist/sales-channels.js

@@ -0,0 +1,285 @@
+// Sales Channels module — feature 005 contract surface.
+// Single file with logical sections (matching the convention used by every
+// other module in @endora-commerce/contracts):
+//   (1) Identity primitives (channel code, summary, detail).
+//   (2) Resolver middleware contract (header / query schemas).
+//   (3) Admin HTTP request/response schemas (list / detail / create / edit
+//       / lifecycle).
+//   (4) Membership endpoints (the bidirectional channel-side / entity-side
+//       routes; one shape, used by all 10 entity types).
+//   (5) Storefront / public read-only schemas.
+//   (6) Audit-action constants — free-form action strings written through
+//       the existing AuditLogService.
+//   (7) Attribution registry — the contribution seam that answers "who still
+//       points at this channel?" before a delete (feature 075, D-87).
+// See specs/005-sales-channels/contracts/sales-channels-005.contract.md
+// for the prose contract and the error-code references in `errors.ts`.
+import { z } from 'zod';
+import { isoDateTimeSchema, uuidSchema } from './common.js';
+// ---------------------------------------------------------------------------
+// (1) Identity primitives
+// ---------------------------------------------------------------------------
+/**
+ * Machine-friendly Sales Channel code. Lower-case, starts with a letter,
+ * may contain digits, hyphens, and underscores. Stored as `varchar(32)`
+ * (foundation 001).
+ */
+export const SalesChannelCodeSchema = z
+    .string()
+    .min(1)
+    .max(32)
+    .regex(/^[a-z][a-z0-9_-]*$/, 'sales channel code must be lowercase machine-friendly');
+/** i18n display name keyed by language code, e.g. `{ en: 'Default' }`. */
+export const SalesChannelNameSchema = z
+    .record(z.string(), z.string())
+    .refine((o) => Object.keys(o).length > 0, 'name must include at least one locale');
+/** Short summary returned in list views. */
+export const SalesChannelSummarySchema = z.object({
+    id: uuidSchema,
+    code: SalesChannelCodeSchema,
+    name: SalesChannelNameSchema,
+    active: z.boolean(),
+    systemDefault: z.boolean(),
+    defaultLanguage: z.string(),
+    defaultCurrency: z.string(),
+    themeCode: z.string().nullable(),
+    logoAssetId: uuidSchema.nullable(),
+    version: z.number().int().positive(),
+    createdAt: isoDateTimeSchema,
+    updatedAt: isoDateTimeSchema,
+});
+/** Full detail returned by the admin GET-by-code endpoint. */
+export const SalesChannelDetailSchema = SalesChannelSummarySchema.extend({
+    languages: z.array(z.string()).min(1),
+    currencies: z.array(z.string()).min(1),
+    /** Resolved through the assets module on response; nullable when no logo set. */
+    logoUrl: z.string().url().nullable(),
+});
+// ---------------------------------------------------------------------------
+// (2) Resolver middleware contract
+// ---------------------------------------------------------------------------
+/** `X-Sales-Channel: <code>` header schema. */
+export const SalesChannelHeaderSchema = z.object({
+    'x-sales-channel': SalesChannelCodeSchema.optional(),
+});
+/**
+ * `?salesChannel=<code>` query parameter schema. Used by storefront SSR
+ * paths and link-shareable previews; ignored on `/api/v1/admin/*` paths
+ * by the resolver middleware to prevent cross-channel admin bleed.
+ */
+export const SalesChannelQuerySchema = z.object({
+    salesChannel: SalesChannelCodeSchema.optional(),
+});
+// ---------------------------------------------------------------------------
+// (3) Admin HTTP request/response schemas
+// ---------------------------------------------------------------------------
+const themeCodeRe = /^[a-z][a-z0-9_-]*$/;
+/** Body shape for POST /api/v1/admin/sales-channels. */
+export const SalesChannelCreateBodySchema = z
+    .object({
+    code: SalesChannelCodeSchema,
+    name: SalesChannelNameSchema,
+    logoAssetId: uuidSchema.nullable().optional(),
+    themeCode: z
+        .string()
+        .regex(themeCodeRe, 'theme code must be lowercase machine-friendly')
+        .nullable()
+        .optional(),
+    languages: z.array(z.string()).min(1),
+    defaultLanguage: z.string(),
+    currencies: z.array(z.string()).min(1),
+    defaultCurrency: z.string(),
+    active: z.boolean().optional().default(true),
+})
+    .superRefine((v, ctx) => {
+    if (!v.languages.includes(v.defaultLanguage)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['defaultLanguage'],
+            message: 'defaultLanguage must be one of languages',
+        });
+    }
+    if (!v.currencies.includes(v.defaultCurrency)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['defaultCurrency'],
+            message: 'defaultCurrency must be one of currencies',
+        });
+    }
+});
+/**
+ * Body shape for PATCH /api/v1/admin/sales-channels/{code}. Every field optional.
+ *
+ * `code` is accepted only when it repeats the channel's current code: a channel's
+ * code is written once, at creation, and is immutable afterwards — on every
+ * channel, not only the system default. A code is an identity other systems hold
+ * onto (`SALES_CHANNEL_HOST_MAP`, cached storefront responses, integration
+ * configuration), so changing it renames something those systems cannot follow.
+ * A different value is refused with 422 `SALES_CHANNEL_CODE_IMMUTABLE`; the field
+ * stays in the shape so the refusal is explicit rather than a silently stripped
+ * property that answers 200 and changes nothing. A mistyped code is fixed by
+ * creating the channel again under the right code and deleting the old one —
+ * for the default channel, after moving the flag off it with `set-default`.
+ * The `name` stays freely editable.
+ */
+export const SalesChannelUpdateBodySchema = z
+    .object({
+    code: SalesChannelCodeSchema.optional(),
+    name: SalesChannelNameSchema.optional(),
+    logoAssetId: uuidSchema.nullable().optional(),
+    themeCode: z.string().regex(themeCodeRe).nullable().optional(),
+    languages: z.array(z.string()).min(1).optional(),
+    defaultLanguage: z.string().optional(),
+    currencies: z.array(z.string()).min(1).optional(),
+    defaultCurrency: z.string().optional(),
+    active: z.boolean().optional(),
+})
+    .superRefine((v, ctx) => {
+    if (v.defaultLanguage !== undefined && v.languages && !v.languages.includes(v.defaultLanguage)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['defaultLanguage'],
+            message: 'defaultLanguage must be one of languages',
+        });
+    }
+    if (v.defaultCurrency !== undefined && v.currencies && !v.currencies.includes(v.defaultCurrency)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['defaultCurrency'],
+            message: 'defaultCurrency must be one of currencies',
+        });
+    }
+});
+/**
+ * Body shape for POST /api/v1/admin/sales-channels/{code}/set-default.
+ *
+ * The target is the path parameter, so the body carries nothing today. It is
+ * declared rather than omitted because the endpoint is a state transition, not a
+ * patch: an operator's client sends `{}` and any later option (a reason, a
+ * scheduled cut-over) lands here instead of on the query string.
+ */
+export const SalesChannelSetDefaultBodySchema = z.object({});
+/**
+ * Response shape for POST /api/v1/admin/sales-channels/{code}/set-default.
+ *
+ * `changed` is false when the target already held the flag — promoting the
+ * current default is a no-op success, not an error, so a double-click and a
+ * retried request both answer 200 with the same body. `previousDefaultCode` is
+ * the code that held the flag before the call, which on the no-op path is the
+ * target's own code; it names the channel a subsequent `set-default` would move
+ * the flag back to.
+ */
+export const SalesChannelSetDefaultResponseSchema = z.object({
+    channel: SalesChannelDetailSchema,
+    previousDefaultCode: SalesChannelCodeSchema.nullable(),
+    changed: z.boolean(),
+});
+/** Response shape for GET /api/v1/admin/sales-channels (paginated list). */
+export const SalesChannelListResponseSchema = z.object({
+    items: z.array(SalesChannelSummarySchema),
+    page: z.number().int().nonnegative(),
+    pageSize: z.number().int().positive(),
+    total: z.number().int().nonnegative(),
+});
+// ---------------------------------------------------------------------------
+// (4) Membership endpoints (bidirectional)
+// ---------------------------------------------------------------------------
+/** Channel-scoped entity types tracked by the M:N membership service. */
+export const ChannelMemberEntityTypeSchema = z.enum([
+    'product',
+    'category',
+    'payment-method',
+    'delivery-method',
+    'organization',
+    'tax',
+    'customer',
+    'promotion',
+    'cms-page',
+]);
+/** `GET /api/v1/admin/sales-channels/{code}/{entityType}` — list members. */
+export const ChannelMembershipListResponseSchema = z.object({
+    channels: z.array(SalesChannelSummarySchema),
+});
+/** `GET /api/v1/admin/{entityType}/{id}/sales-channels` — list channels of an entity. */
+export const EntityMembershipListResponseSchema = z.object({
+    entityType: ChannelMemberEntityTypeSchema,
+    entityId: uuidSchema,
+    channels: z.array(SalesChannelSummarySchema),
+});
+// ---------------------------------------------------------------------------
+// (5) Storefront / public read-only
+// ---------------------------------------------------------------------------
+/**
+ * `GET /api/v1/storefront/sales-channel` — what the storefront app fetches
+ * on first paint to know its theme / language / currency.
+ *
+ * Deliberately drops `id`, `active`, `systemDefault`, and `version`
+ * (admin-only fields).
+ */
+export const PublicSalesChannelSchema = z.object({
+    code: SalesChannelCodeSchema,
+    name: SalesChannelNameSchema,
+    defaultLanguage: z.string(),
+    defaultCurrency: z.string(),
+    languages: z.array(z.string()),
+    currencies: z.array(z.string()),
+    themeCode: z.string().nullable(),
+    logoUrl: z.string().url().nullable(),
+});
+/** Response envelope of `GET /api/v1/storefront/sales-channel`. */
+export const PublicSalesChannelResponseSchema = z.object({
+    data: PublicSalesChannelSchema,
+});
+/**
+ * **The platform no longer holds a list of storefront themes** — owner ruling
+ * D-199, implemented by `specs/102-storefront-theme-discovery/`.
+ *
+ * `STOREFRONT_THEME_CODES`, `StorefrontThemeCodeSchema`, `StorefrontThemeCode`,
+ * `DEFAULT_STOREFRONT_THEME_CODE` and `isStorefrontThemeCode` used to live here
+ * and are gone. A theme is a token set a **third party** may publish as an
+ * ordinary npm package, so no set this repository can compile is the whole set:
+ * the answer belongs to the storefront instance that has the packages
+ * installed, and it is generated in that instance's own tree
+ * (`storefront/lib/theme/`).
+ *
+ * The **write** schemas above are unchanged and must stay so. They have never
+ * used the enum: `themeCodeRe` is the whole validation, and a backend that
+ * refused a code it has never heard of would make the field unusable for
+ * exactly the deployments it exists for. `PublicSalesChannelSchema.themeCode`
+ * is likewise unchanged — the wire shape gains and loses nothing.
+ *
+ * What an unknown code does is the storefront's answer and is unchanged too:
+ * it renders the instance's default rather than blank, reports the code once
+ * per process, marks the document with `data-theme-requested`, never writes the
+ * value back and never guesses at a near match. See
+ * `specs/102-storefront-theme-discovery/contracts/theme-package.md` for what a
+ * theme author ships, and `contracts/instance-theme-registry.md` for how an
+ * instance discovers its own.
+ */
+// ---------------------------------------------------------------------------
+// (6) Audit-action constants
+// ---------------------------------------------------------------------------
+/**
+ * Action strings written by `SalesChannelsService` / `SalesChannelMembershipService`
+ * through the existing `AuditLogService.record({ action, ... })`. They are
+ * free-form strings (the audit log uses `action: string`, not an enum)
+ * but every consumer should use these constants so a typo can't drift.
+ */
+export const SALES_CHANNEL_AUDIT_ACTIONS = {
+    IDENTITY_CHANGED: 'sales_channel.identity.changed',
+    MEMBERSHIP_CHANGED: 'sales_channel.membership.changed',
+    LIFECYCLE_CHANGED: 'sales_channel.lifecycle.changed',
+};
+export const SalesChannelAuditActionSchema = z.enum([
+    SALES_CHANNEL_AUDIT_ACTIONS.IDENTITY_CHANGED,
+    SALES_CHANNEL_AUDIT_ACTIONS.MEMBERSHIP_CHANGED,
+    SALES_CHANNEL_AUDIT_ACTIONS.LIFECYCLE_CHANGED,
+]);
+export const SalesChannelLifecycleOpSchema = z.enum([
+    'deactivated',
+    'activated',
+    'deleted',
+    'system-default-promoted',
+]);
+export const SalesChannelMembershipOpSchema = z.enum(['add', 'remove']);
+//# sourceMappingURL=sales-channels.js.map

package/dist/sales-channels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sales-channels.js","sourceRoot":"","sources":["../src/sales-channels.ts"],"names":[],"mappings":"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"}

package/dist/scope-notice.d.ts

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+/**
+ * Why a listing came back empty, when "empty" and "nothing exists" are not the
+ * same statement (feature 087, owner decision of 2026-08-29).
+ *
+ * `customerFilterCond`'s `allowed-set` arm refuses **every** row of a
+ * `@CustomerScoped` table that carries no `organization_id`, because no row in
+ * such a table is inside a scoped actor's authority (FR-011). The refusal is
+ * correct. What is not correct is the silence: the client receives `[]`, which
+ * is indistinguishable from "there is nothing here", and an operator reading it
+ * concludes something false about the **data** rather than something true about
+ * their own reach.
+ *
+ * So the server says which of the two it meant. The notice is **derived** —
+ * the filter records that it emitted the refusing predicate, and the host's
+ * request hook puts the code on the response envelope — so no route sets a flag
+ * and no screen has to be remembered. It stops being emitted, everywhere at
+ * once and with no edit, on the day a table gains its column and the same arm
+ * starts granting.
+ *
+ * It is a *notice*, never an error: the response is a 200 with a truthful body.
+ */
+export declare const SCOPE_NOTICE_CODES: {
+    /**
+     * The records this surface lists carry no organization at all yet, so a
+     * viewer confined to a set of organizations can be shown none of them. The
+     * operator-facing sentences live in the `core` i18n bundle under
+     * `scopeNotice.organizationAttributionPending.*`.
+     */
+    readonly ORGANIZATION_ATTRIBUTION_PENDING: "ORGANIZATION_ATTRIBUTION_PENDING";
+};
+export declare const scopeNoticeCodeSchema: z.ZodEnum<{
+    ORGANIZATION_ATTRIBUTION_PENDING: "ORGANIZATION_ATTRIBUTION_PENDING";
+}>;
+export type ScopeNoticeCode = z.infer<typeof scopeNoticeCodeSchema>;
+/**
+ * The envelope slot the notice occupies: `meta.scopeNotice`, on any successful
+ * response. `meta` is the one place the three surfaces this covers could share
+ * — their bodies are `{ data, meta }`, `{ data }` and a bare page object — and
+ * the key is absent rather than null when there is nothing to say.
+ */
+export declare const scopeNoticeMetaSchema: z.ZodObject<{
+    scopeNotice: z.ZodOptional<z.ZodEnum<{
+        ORGANIZATION_ATTRIBUTION_PENDING: "ORGANIZATION_ATTRIBUTION_PENDING";
+    }>>;
+}, z.core.$strip>;
+export type ScopeNoticeMeta = z.infer<typeof scopeNoticeMetaSchema>;
+/** The envelope shape a client reads the notice out of. */
+export interface ScopeNoticeEnvelope {
+    readonly meta?: {
+        readonly scopeNotice?: ScopeNoticeCode;
+    } | undefined;
+}
+/**
+ * Read the notice off any response body, or `null` when the body carries none.
+ * Written here rather than per client so that "what a notice looks like on the
+ * wire" has one definition on both sides of the boundary.
+ */
+export declare function scopeNoticeOf(response: unknown): ScopeNoticeCode | null;
+//# sourceMappingURL=scope-notice.d.ts.map

package/dist/scope-notice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-notice.d.ts","sourceRoot":"","sources":["../src/scope-notice.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,kBAAkB;IAC7B;;;;;OAKG;;CAEK,CAAC;AAEX,eAAO,MAAM,qBAAqB;;EAA+C,CAAC;AAClF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;;;;iBAEhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,2DAA2D;AAC3D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,eAAe,CAAA;KAAE,GAAG,SAAS,CAAC;CACxE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,OAAO,GAAG,eAAe,GAAG,IAAI,CAMvE"}

package/dist/scope-notice.js

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+/**
+ * Why a listing came back empty, when "empty" and "nothing exists" are not the
+ * same statement (feature 087, owner decision of 2026-08-29).
+ *
+ * `customerFilterCond`'s `allowed-set` arm refuses **every** row of a
+ * `@CustomerScoped` table that carries no `organization_id`, because no row in
+ * such a table is inside a scoped actor's authority (FR-011). The refusal is
+ * correct. What is not correct is the silence: the client receives `[]`, which
+ * is indistinguishable from "there is nothing here", and an operator reading it
+ * concludes something false about the **data** rather than something true about
+ * their own reach.
+ *
+ * So the server says which of the two it meant. The notice is **derived** —
+ * the filter records that it emitted the refusing predicate, and the host's
+ * request hook puts the code on the response envelope — so no route sets a flag
+ * and no screen has to be remembered. It stops being emitted, everywhere at
+ * once and with no edit, on the day a table gains its column and the same arm
+ * starts granting.
+ *
+ * It is a *notice*, never an error: the response is a 200 with a truthful body.
+ */
+export const SCOPE_NOTICE_CODES = {
+    /**
+     * The records this surface lists carry no organization at all yet, so a
+     * viewer confined to a set of organizations can be shown none of them. The
+     * operator-facing sentences live in the `core` i18n bundle under
+     * `scopeNotice.organizationAttributionPending.*`.
+     */
+    ORGANIZATION_ATTRIBUTION_PENDING: 'ORGANIZATION_ATTRIBUTION_PENDING',
+};
+export const scopeNoticeCodeSchema = z.enum(['ORGANIZATION_ATTRIBUTION_PENDING']);
+/**
+ * The envelope slot the notice occupies: `meta.scopeNotice`, on any successful
+ * response. `meta` is the one place the three surfaces this covers could share
+ * — their bodies are `{ data, meta }`, `{ data }` and a bare page object — and
+ * the key is absent rather than null when there is nothing to say.
+ */
+export const scopeNoticeMetaSchema = z.object({
+    scopeNotice: scopeNoticeCodeSchema.optional(),
+});
+/**
+ * Read the notice off any response body, or `null` when the body carries none.
+ * Written here rather than per client so that "what a notice looks like on the
+ * wire" has one definition on both sides of the boundary.
+ */
+export function scopeNoticeOf(response) {
+    if (typeof response !== 'object' || response === null)
+        return null;
+    const meta = response.meta;
+    if (typeof meta !== 'object' || meta === null)
+        return null;
+    const code = meta.scopeNotice;
+    return scopeNoticeCodeSchema.safeParse(code).success ? code : null;
+}
+//# sourceMappingURL=scope-notice.js.map

package/dist/scope-notice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-notice.js","sourceRoot":"","sources":["../src/scope-notice.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC;;;;;OAKG;IACH,gCAAgC,EAAE,kCAAkC;CAC5D,CAAC;AAEX,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,kCAAkC,CAAC,CAAC,CAAC;AAGlF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,WAAW,EAAE,qBAAqB,CAAC,QAAQ,EAAE;CAC9C,CAAC,CAAC;AAQH;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,QAAiB;IAC7C,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACnE,MAAM,IAAI,GAAI,QAA+B,CAAC,IAAI,CAAC;IACnD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC3D,MAAM,IAAI,GAAI,IAAkC,CAAC,WAAW,CAAC;IAC7D,OAAO,qBAAqB,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAE,IAAwB,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1F,CAAC"}