@endora-commerce/contracts 0.100.0

package/dist/settings.js

@@ -0,0 +1,337 @@
+// Settings module — feature 004 contract surface.
+// Holds three logical sections in one file (matching the convention used by
+// every other module in @endora-commerce/contracts):
+//   (1) Setting value-type Zod registry.
+//   (2) Module manifest schemas — the cross-module registration contract that
+//       any backend module may use to declare its setting groups and settings
+//       (see specs/004-settings-module/contracts/settings-004.contract.md, A).
+//   (3) Admin HTTP request/response schemas (section C).
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// (1) Value types
+// ---------------------------------------------------------------------------
+export const SettingValueTypeSchema = z.enum([
+    'string',
+    'number',
+    'boolean',
+    'json',
+    'string_list',
+    'secret',
+    // Feature 058 — references a saved credential configuration by its code,
+    // constrained to one configuration type (see `configurationType` below).
+    'credential_ref',
+]);
+/**
+ * Returns the Zod schema corresponding to a setting's declared `valueType`.
+ * Callers supplying their own narrower schema to `SettingsService.get<T>()`
+ * still get the looser per-type validation through this helper at write time.
+ *
+ * `secret` accepts a plain string on write (the backend encrypts before
+ * persisting — feature 043 / FR-021); read endpoints never return it.
+ */
+export function valueSchemaForType(t) {
+    switch (t) {
+        case 'string':
+            return z.string();
+        case 'number':
+            return z.number();
+        case 'boolean':
+            return z.boolean();
+        case 'json':
+            return z.unknown();
+        case 'string_list':
+            return z.array(z.string());
+        case 'secret':
+            return z.string();
+        case 'credential_ref':
+            // The stored value is a configuration code (or '' when not configured).
+            return z.string();
+    }
+}
+// ---------------------------------------------------------------------------
+// (2) Module manifest
+// ---------------------------------------------------------------------------
+const groupCodeRe = /^[a-z][a-z0-9_]{0,118}[a-z0-9]$/;
+/**
+ * Setting code shape. Exported because feature 073's module activation block
+ * (`ModuleActivationSchema` in `modules.ts`) declares the code of an ordinary
+ * Setting row and must validate it identically.
+ */
+export const settingCodeRe = /^[a-z][a-z0-9_][a-z0-9_.]*[a-z0-9]$/;
+const moduleCodeRe = /^[a-z][a-z0-9_]{0,118}[a-z0-9]$/;
+export const GroupManifestEntrySchema = z.object({
+    code: z.string().regex(groupCodeRe),
+    name: z.string().min(1).max(200),
+    /**
+     * Sales-channel scope by `sales_channels.code`. Omit (or empty) to mean
+     * "applies to all channels" (R-5 / FR-004).
+     */
+    salesChannelCodes: z.array(z.string()).optional(),
+    /**
+     * Reserved for the built-in `general` group only — other modules MUST NOT
+     * set this to `true`. The reconciler refuses such manifests at boot.
+     */
+    isSystemProtected: z.boolean().optional(),
+});
+export const SettingManifestEntrySchema = z
+    .object({
+    code: z.string().regex(settingCodeRe),
+    name: z.string().min(1).max(200),
+    description: z.string().max(2000).optional(),
+    /** Defaults to `'general'` when omitted. */
+    groupCode: z.string().optional(),
+    valueType: SettingValueTypeSchema,
+    defaultValue: z.unknown(),
+    /**
+     * Stored `default_value`s this manifest's current `defaultValue`
+     * supersedes (feature 078, D-95.3).
+     *
+     * `ManifestReconciler` refuses a `defaultValue` change as breaking, because
+     * a silent default change alters behaviour for every deployment that never
+     * overrode it. Declaring the prior value is how a module says which change
+     * is intended and bounded: a stored default equal to one of these is
+     * updated to the new one at boot, and anything else still throws
+     * `BreakingChangeRejected`. Same shape, and the same self-healing argument,
+     * as the sanctioned `string` → `secret` valueType upgrade.
+     */
+    previousDefaultValues: z.array(z.unknown()).optional(),
+    salesChannelCodes: z.array(z.string()).optional(),
+    /**
+     * Closed list of allowed values for a `string` setting. When present the
+     * setting behaves like an enum: the admin renders a dropdown instead of a
+     * free-text input and the backend rejects any value outside the list. Only
+     * valid for `valueType: 'string'`; the `defaultValue` must be one of the
+     * options.
+     */
+    enumOptions: z.array(z.string().min(1)).min(1).optional(),
+    /**
+     * Feature 058 — the configuration type a `credential_ref` setting is
+     * constrained to (e.g. `'llm'`). REQUIRED when `valueType === 'credential_ref'`
+     * and forbidden otherwise. The admin renders a picker of matching
+     * configurations; the backend never interprets provider meaning.
+     */
+    configurationType: z.string().min(1).optional(),
+    /**
+     * When true, the setting is registered and remains fully readable/writable
+     * through its owning module's dedicated surface (e.g. the PWA settings
+     * page), but is excluded from the generic admin Settings screen so it is
+     * managed in exactly one place. A group whose settings are all hidden does
+     * not appear in the generic Settings list at all.
+     */
+    hidden: z.boolean().optional(),
+})
+    .refine((s) => s.valueType !== 'secret' || s.defaultValue === '', {
+    message: "A 'secret' setting's defaultValue must be the empty string — manifests can never ship a real credential.",
+    path: ['defaultValue'],
+})
+    .refine((s) => s.enumOptions === undefined || s.valueType === 'string', {
+    message: "enumOptions is only supported for valueType 'string'.",
+    path: ['enumOptions'],
+})
+    .refine((s) => (s.valueType === 'credential_ref') === (s.configurationType !== undefined), {
+    message: "configurationType is required for valueType 'credential_ref' and forbidden otherwise.",
+    path: ['configurationType'],
+})
+    .refine((s) => s.enumOptions === undefined ||
+    (typeof s.defaultValue === 'string' && s.enumOptions.includes(s.defaultValue)), {
+    message: 'An enum setting defaultValue must be one of its enumOptions.',
+    path: ['defaultValue'],
+});
+export const ModuleSettingsManifestSchema = z.object({
+    moduleCode: z.string().regex(moduleCodeRe),
+    groups: z.array(GroupManifestEntrySchema).default([]),
+    settings: z.array(SettingManifestEntrySchema).default([]),
+});
+/**
+ * Identity-with-validation helper for module authors. Modules export a single
+ * constant with `defineModuleSettingsManifest({...})`; this gives them full
+ * TypeScript inference and the reconciler can ingest the value directly.
+ */
+export function defineModuleSettingsManifest(m) {
+    return ModuleSettingsManifestSchema.parse(m);
+}
+// ---------------------------------------------------------------------------
+// (3) Admin HTTP
+// ---------------------------------------------------------------------------
+export const SettingValueByChannelSchema = z.object({
+    salesChannelId: z.uuid(),
+    salesChannelCode: z.string(),
+    value: z.unknown(),
+    /**
+     * Secret settings only (feature 043 / FR-021): `value` is redacted to
+     * `null` on every read; `isSet` tells the UI whether a value exists.
+     * Absent for non-secret settings.
+     */
+    isSet: z.boolean().optional(),
+    updatedAt: z.iso.datetime(),
+});
+export const SettingDtoSchema = z.object({
+    id: z.uuid(),
+    code: z.string(),
+    name: z.string(),
+    description: z.string().nullable(),
+    valueType: SettingValueTypeSchema,
+    ownerModule: z.string(),
+    salesChannelCodes: z.array(z.string()),
+    /**
+     * Closed list of allowed values for an enum-style `string` setting (manifest
+     * `enumOptions`). Empty/absent for ordinary free-text settings; when present
+     * the admin renders a dropdown bound to these values.
+     */
+    enumOptions: z.array(z.string()).nullish(),
+    /**
+     * Feature 058 — for a `credential_ref` setting, the configuration type the
+     * reference is constrained to (e.g. `'llm'`); the admin filters the config
+     * picker by this. Null/absent for every other value type.
+     */
+    configurationType: z.string().nullish(),
+    /**
+     * Manifest-declared default value (immutable; surfaces in `defaultValue`).
+     */
+    defaultValue: z.unknown(),
+    /**
+     * Platform-wide global override the admin has set, or `null` when the
+     * admin has not customised it. Resolver chain when reading a value:
+     *   per-channel SettingValue row → globalValue (when non-null) → defaultValue.
+     * "All channels" admin writes update this field only and leave per-channel
+     * rows untouched.
+     */
+    globalValue: z.unknown().nullable(),
+    /**
+     * Secret settings only (feature 043 / FR-021): `defaultValue` and
+     * `globalValue` are redacted to `null` on every read; this flag tells the
+     * UI whether a global override exists. Absent for non-secret settings.
+     */
+    globalValueIsSet: z.boolean().optional(),
+    valuesByChannel: z.array(SettingValueByChannelSchema),
+    /**
+     * Server-computed effective version (= `max(setting.updatedAt,
+     * max(values.updatedAt))`). Echo back as `expectedVersion` on PUT
+     * /:code/value to detect concurrent edits — matches the ETag header
+     * returned by the detail endpoint.
+     */
+    version: z.iso.datetime(),
+    /**
+     * Feature 073 — `false` when the owning module is not effectively present.
+     * The value is still read (off is not uninstall: the stored configuration
+     * survives), but every write against it is refused (FR-033). Classified per
+     * setting rather than per group because the module's own activation control
+     * stays writable while it is off, so a group-level filter would either hide
+     * the control or render the whole group.
+     */
+    editable: z.boolean().optional(),
+    /**
+     * Feature 073 — this setting **is** its module's activation control: the
+     * single exception that stays writable while the module is off, and the one
+     * setting the ordinary write path refuses (the audited Command owns it).
+     */
+    activationControl: z.boolean().optional(),
+});
+export const SettingGroupDtoSchema = z.object({
+    id: z.uuid(),
+    code: z.string(),
+    name: z.string(),
+    isSystemProtected: z.boolean(),
+    ownerModule: z.string(),
+    salesChannelCodes: z.array(z.string()),
+    settings: z.array(SettingDtoSchema),
+});
+export const SettingsListResponseSchema = z.object({
+    groups: z.array(SettingGroupDtoSchema),
+});
+export const SettingsListQuerySchema = z.object({
+    groupCode: z.string().optional(),
+});
+export const SetValueAllRequestSchema = z.object({
+    scope: z.literal('all'),
+    value: z.unknown(),
+});
+export const SetValueSubsetRequestSchema = z.object({
+    scope: z.literal('subset'),
+    salesChannelCodes: z.array(z.string()).min(1),
+    value: z.unknown(),
+});
+export const SetValueRequestSchema = z.discriminatedUnion('scope', [
+    SetValueAllRequestSchema,
+    SetValueSubsetRequestSchema,
+]);
+export const ResetValueQuerySchema = z.object({
+    /** Comma-separated list; omit to reset for every channel. */
+    salesChannelCodes: z.string().optional(),
+});
+export const GroupCreateRequestSchema = z.object({
+    code: z.string().regex(groupCodeRe),
+    name: z.string().min(1).max(200),
+    salesChannelCodes: z.array(z.string()).optional(),
+});
+export const GroupUpdateRequestSchema = z.object({
+    name: z.string().min(1).max(200).optional(),
+    salesChannelCodes: z.array(z.string()).optional(),
+});
+export const SettingDetailResponseSchema = SettingDtoSchema;
+// ---------------------------------------------------------------------------
+// (4) Storefront shop-information surface
+// ---------------------------------------------------------------------------
+/**
+ * Public shop / company contact information resolved for the active sales
+ * channel. Backs the storefront footer, the 404 "need help?" block and the
+ * contact form. Every field is a string; an unset (or not-yet-registered)
+ * setting resolves to an empty string so the storefront can decide what to
+ * render. The contact-form recipient list is intentionally omitted — it is
+ * an internal routing concern, not public information.
+ */
+export const ShopInfoSchema = z.object({
+    name: z.string(),
+    address: z.string(),
+    contactEmail: z.string(),
+    supportEmail: z.string(),
+    phone: z.string(),
+});
+export const ShopInfoResponseSchema = z.object({ data: ShopInfoSchema });
+// ---------------------------------------------------------------------------
+// (5) Cache administration (maintenance)
+// ---------------------------------------------------------------------------
+/**
+ * A clearable cache namespace surfaced in the admin "Clear cache" page. `key`
+ * is the stable identifier the client sends back to clear it; `label` and
+ * `description` are human-readable (English defaults — the admin localises via
+ * the `settings.cache.namespace.<key>.*` i18n keys).
+ */
+export const CacheNamespaceDtoSchema = z.object({
+    key: z.string(),
+    label: z.string(),
+    description: z.string(),
+});
+export const CacheNamespacesResponseSchema = z.object({
+    data: z.array(CacheNamespaceDtoSchema),
+    /** False when no Redis cache is wired (clearing is a no-op). */
+    cacheEnabled: z.boolean(),
+});
+export const ClearCacheRequestSchema = z.object({
+    /** Namespace keys to clear, or the literal `"all"` for every namespace. */
+    namespaces: z.union([z.literal('all'), z.array(z.string()).min(1)]),
+});
+export const ClearedCacheNamespaceSchema = z.object({
+    key: z.string(),
+    deletedKeysCount: z.number().int().nonnegative(),
+});
+export const ClearCacheResultSchema = z.object({
+    data: z.object({
+        cleared: z.array(ClearedCacheNamespaceSchema),
+        totalDeletedKeys: z.number().int().nonnegative(),
+    }),
+});
+// ---------------------------------------------------------------------------
+// (6) Storefront home-page configuration
+// ---------------------------------------------------------------------------
+/**
+ * Resolved storefront home-page configuration for the active sales channel.
+ * `cmsPageSlug` is the CMS page slug an operator chose as the home page, or
+ * null when none is configured (the storefront then renders its built-in
+ * landing page).
+ */
+export const HomepageConfigSchema = z.object({
+    cmsPageSlug: z.string().nullable(),
+});
+export const HomepageConfigResponseSchema = z.object({ data: HomepageConfigSchema });
+//# sourceMappingURL=settings.js.map

package/dist/settings.js.map

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

package/dist/shipments.d.ts

@@ -0,0 +1,140 @@
+/**
+ * `shipments` module contracts — the in-process port surface (feature 075,
+ * Phase P).
+ *
+ * One inbound site, and it is the delivery-side twin of the one `payments`
+ * published in wave 1: the order-confirmation e-mail renders a shipping line,
+ * and `orders` reaches this module's renderer registry for it.
+ *
+ * Plain TypeScript rather than Zod: this describes an in-process call. The
+ * module's HTTP shapes live in `shipping-methods.ts`, which is
+ * `delivery_methods`' contracts file and covers the shipment record too.
+ */
+import type { ShipmentStatus } from './shipping-methods.js';
+/** What the order-confirmation e-mail knows about the shipping method. */
+export interface ShippingEmailContext {
+    /** Resolved display name of the shipping method. */
+    name: string;
+    /** Flat surcharge (`price`) applied for this method, in the order currency. */
+    cost: number;
+    currency: string;
+}
+/**
+ * Container name: `shippingEmailRendererPort`. Owner: `shipments`.
+ *
+ * A shipping adapter may register a custom renderer under a key (feature 035,
+ * FR-016/FR-017); when none is registered the platform default is used, so the
+ * shipping section always renders.
+ *
+ * `orders` reaches the resolver today and then calls the function it gets
+ * back. The port collapses those two steps for the reason its payment twin
+ * gives: a consumer that resolved a renderer and got `undefined` would have to
+ * hold a copy of the default text, and two copies of a default are how a
+ * default stops being one.
+ *
+ * Bodies are plain text (see `EmailMailerSendInput.text`), so a renderer is a
+ * `(ctx) => string` builder rather than a component.
+ *
+ * **Owner off:** the seam fails closed — resolving this port throws
+ * `ModuleDisabledError` and the call answers 503 `MODULE_DISABLED`, so nothing
+ * half-executes. Whether `shipments` has an off state at all is its manifest's
+ * `activation` to say, not this line's: a module declaring
+ * `nonDeactivatable` never enters one.
+ */
+export interface ShippingEmailRendererPort {
+    render(rendererKey: string | null, ctx: ShippingEmailContext): string;
+}
+/**
+ * Container name: `shipmentUsagePort`. Owner: `shipments`.
+ *
+ * "Has this delivery method ever shipped anything?" — the one question
+ * `delivery_methods` has to ask before it deletes a method row (feature 035,
+ * FR-003; feature 077, D-87).
+ *
+ * It asked it in raw SQL until feature 075 drained the shard:
+ * `select count(*) from "shipments" where "delivery_method_id" = ?`, inside the
+ * delete Command's own transaction. The statement named no import specifier, so
+ * the boundary it crossed compiled and returned rows.
+ *
+ * **`shipments.delivery_method_id` carries no foreign key** — the table was
+ * created without one — so this count is the only thing standing between a
+ * delete and permanently orphaned shipment history. That is why the answer is
+ * asked of the owner rather than approximated, and why the caller refuses the
+ * delete when it cannot get one.
+ *
+ * The count runs on this module's own `EntityManager`, so it is outside any
+ * transaction the caller has open. That costs nothing here: `shipments` is a
+ * table the delete transaction never writes, so there is no write of its own
+ * for the read to be blind to, and the race a cross-module read cannot close —
+ * a shipment created between the count and the commit — was equally open to the
+ * in-transaction statement this replaced, which took no lock either.
+ *
+ * **Owner off:** `delivery_methods` decides this module's presence *before* it
+ * resolves the port and refuses the delete with a sentence naming this module,
+ * rather than resolving a gate and catching it — see its manifest's
+ * `nonBindingDependencies` entry. The edge is non-binding because `shipments`
+ * declares `delivery_methods`, so declaring it back closes a cycle, and
+ * acknowledging it would make `shipments` unswitchable for as long as delivery
+ * methods are present.
+ */
+export interface ShipmentUsagePort {
+    /** How many shipment rows — of any status — reference this delivery method. */
+    countForDeliveryMethod(deliveryMethodId: string): Promise<number>;
+}
+/**
+ * One shipment attempt as it crosses a module boundary — a plain shape, never
+ * the ORM entity (FR-011).
+ *
+ * `providerDetails` is the carrier envelope the adapter deposited. It stays
+ * opaque here for the reason the order's `shippingAdapterData` does: only the
+ * adapter that wrote it knows its shape, and the reader that needs it is that
+ * same adapter reading back what it wrote.
+ */
+export interface ShipmentRecord {
+    id: string;
+    orderId: string;
+    deliveryMethodId: string;
+    status: ShipmentStatus;
+    externalReference: string | null;
+    providerDetails: Record<string, unknown> | null;
+    failureReason: string | null;
+    attemptNo: number;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Container name: `shipmentReadPort`. Owner: `shipments`.
+ *
+ * "What state is this shipment in, and which carrier reference does it carry?"
+ * — the question a carrier module asks twice: when an inbound webhook names
+ * only the carrier's own id, and when an admin asks for the label of an
+ * attempt it opened.
+ *
+ * Published for feature 068. `inpost` answered both by loading this module's
+ * `Shipment` entity directly, which its cross-module ledger recorded as debt
+ * with exactly this port as the retiring condition. It is a **read**, so it is
+ * a method here and not an `EntityManager`-taking apply port: handing a read a
+ * transaction handle re-opens a write seam to serve it.
+ *
+ * `findByExternalReference` is not a duplicate of `findById`. A carrier that
+ * signs nothing and names only its own id has to be correlated, and until the
+ * first `receive_shipment` lands, `externalReference` is where the adapter put
+ * that id — after it, a tracking number replaces it. The lookup is an indexed
+ * equality read, and the caller is expected to have its own correlation table
+ * for everything after the first event.
+ *
+ * **Owner off:** the seam fails closed — resolving this port throws
+ * `ModuleDisabledError` and the call answers 503 `MODULE_DISABLED`. That is the
+ * right answer for both callers: a label for a shipment the platform will not
+ * read, and a carrier callback the platform cannot apply, are both operations
+ * that must not half-execute.
+ */
+export interface ShipmentReadPort {
+    findById(id: string): Promise<ShipmentRecord | null>;
+    /**
+     * The most recent attempt carrying `reference`, or null. Newest first, so a
+     * reference re-used across attempts answers with the live one.
+     */
+    findByExternalReference(reference: string): Promise<ShipmentRecord | null>;
+}
+//# sourceMappingURL=shipments.d.ts.map

package/dist/shipments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shipments.d.ts","sourceRoot":"","sources":["../src/shipments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,0EAA0E;AAC1E,MAAM,WAAW,oBAAoB;IACnC,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,yBAAyB;IACxC,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,oBAAoB,GAAG,MAAM,CAAC;CACvE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,WAAW,iBAAiB;IAChC,+EAA+E;IAC/E,sBAAsB,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACnE;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,cAAc,CAAC;IACvB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAChD,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACrD;;;OAGG;IACH,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;CAC5E"}

package/dist/shipments.js

@@ -0,0 +1,14 @@
+/**
+ * `shipments` module contracts — the in-process port surface (feature 075,
+ * Phase P).
+ *
+ * One inbound site, and it is the delivery-side twin of the one `payments`
+ * published in wave 1: the order-confirmation e-mail renders a shipping line,
+ * and `orders` reaches this module's renderer registry for it.
+ *
+ * Plain TypeScript rather than Zod: this describes an in-process call. The
+ * module's HTTP shapes live in `shipping-methods.ts`, which is
+ * `delivery_methods`' contracts file and covers the shipment record too.
+ */
+export {};
+//# sourceMappingURL=shipments.js.map

package/dist/shipments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shipments.js","sourceRoot":"","sources":["../src/shipments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}