@endora-commerce/contracts 0.100.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Endora sp. z o.o. and the Endora Commerce contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,34 @@
+<!-- Generated by `pnpm --filter backend run manifests:generate`. Delete this line to take the file over; a README without it is never regenerated. -->
+
+# @endora-commerce/contracts
+
+Source-of-truth Zod schemas shared across backend, storefront, admin (Principle V). The backend regenerates its live OpenAPI document from these at startup.
+
+## What this is
+
+A shared library package of **Endora Commerce**, the modular B2B/B2C commerce platform. It declares no module manifest, so the platform composes nothing from it: what is published here is what the platform and the modules built on it compile against.
+
+## Entry points
+
+- `@endora-commerce/contracts`
+- `@endora-commerce/contracts/*`
+
+## Depends on
+
+**Bundled dependencies**
+
+- `zod` ^4.2.0
+
+## What the tarball carries
+
+- `dist/` — the compiled JavaScript and its type declarations
+
+## Install
+
+```bash
+pnpm add @endora-commerce/contracts
+```
+
+## Licence
+
+MIT — the text is in `LICENSE`, beside this file.

package/dist/actor.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The **actor** a request carries: who is asking, as four kinds and nothing
+ * else (`specs/110-instance-repository/` T118b).
+ *
+ * ## Why it is here rather than in `@endora-commerce/mod-auth`
+ *
+ * `auth` resolves the actor and writes it onto the request, so the shape lived
+ * beside that implementation — and the Fastify augmentation that puts it on
+ * `FastifyRequest` lived there with it. That made every reader of
+ * `request.actor` a consumer of a module: `backend/src/composition.ts` named
+ * `@endora-commerce/mod-auth/backend` for a type it erases at build time, the
+ * platform restated the shape structurally in four places because D-52/D-53
+ * forbids it the import, and a packaged module read it through a hand-written
+ * cast per module.
+ *
+ * The blocker on relocating it was believed to be `Session`: `auth`'s own
+ * barrel said moving the augmentation *"would take `Session` with it"*, because
+ * `ActorCustomer` and `ActorAdmin` each carried the ORM entity. Measured across
+ * `packages/`, `backend/`, `admin/` and `storefront/`, **no file outside
+ * `packages/modules/auth/` ever read `actor.session`** — `composition.ts` alone
+ * reads `kind`, `adminUserId`, `organizationId`, `customerAccountId`,
+ * `impersonatorAdminUserId` and `apiKeyId`, and `.session` not once. So the
+ * field was written by the auth plugin on every request and read by nobody, and
+ * dropping it is what lets the vocabulary sit in a package that imports neither
+ * Fastify nor the ORM.
+ *
+ * A consumer that needs the *session* asks `auth` for it — `AuthSessionPort`
+ * and `AuthSessionReadPort` in `./auth.js` are that surface, and they carry
+ * `AuthSessionRecord` rather than the entity.
+ *
+ * ## Where the Fastify augmentation lives
+ *
+ * Not here. `@endora-commerce/contracts` declares no dependency on Fastify, for
+ * the reason `RequireCustomerGuard` and `AdminActorPromotion` are in the
+ * platform's `kernel/ports/require-admin.ts` rather than in this package. The
+ * `declare module 'fastify'` block that adds `actor` and `adminActor` to
+ * `FastifyRequest` is `@endora-commerce/platform`'s
+ * (`src/http/request-actor.ts`), on the `./http` subpath.
+ */
+/** No identified caller. The fail-closed end of every audience question. */
+export interface ActorAnonymous {
+    kind: 'anonymous';
+}
+export interface ActorCustomer {
+    kind: 'customer';
+    customerAccountId: string;
+    /**
+     * The buyer's Organization (Principle XI). Nullable at this seam rather than
+     * by design: every transacting customer has one — `organization_id` is
+     * `NOT NULL` and an individual is backed by a personal organisation — but the
+     * auth plugin stamps `''` when no resolver is wired, and a guest-style
+     * account predating feature 026 can still present without one. A consumer
+     * that requires an Organization asserts it (`customerContextResolver`).
+     */
+    organizationId: string | null;
+    /** Non-null when a Supplier employee is acting on behalf of this Customer. */
+    impersonatorAdminUserId: string | null;
+}
+export interface ActorAdmin {
+    kind: 'admin';
+    adminUserId: string;
+}
+/**
+ * An integration authenticated by a bearer key (feature 062). All three binding
+ * fields are set for a **bound** distributor key and absent for a legacy
+ * unbound one: the tenant-context mapping derives single-org scope from them
+ * and the sales-channel resolver pins the channel, failing closed on a header
+ * that names a different one.
+ */
+export interface ActorApiKey {
+    kind: 'api_key';
+    apiKeyId: string;
+    scopes: string[];
+    organizationId?: string | null;
+    salesChannelId?: string | null;
+    customerAccountId?: string | null;
+}
+export type Actor = ActorAnonymous | ActorCustomer | ActorAdmin | ActorApiKey;
+//# sourceMappingURL=actor.d.ts.map

package/dist/actor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor.d.ts","sourceRoot":"","sources":["../src/actor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,4EAA4E;AAC5E,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,WAAW,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,UAAU,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;;;;;;OAOG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,8EAA8E;IAC9E,uBAAuB,EAAE,MAAM,GAAG,IAAI,CAAC;CACxC;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED,MAAM,MAAM,KAAK,GAAG,cAAc,GAAG,aAAa,GAAG,UAAU,GAAG,WAAW,CAAC"}

package/dist/actor.js

@@ -0,0 +1,41 @@
+/**
+ * The **actor** a request carries: who is asking, as four kinds and nothing
+ * else (`specs/110-instance-repository/` T118b).
+ *
+ * ## Why it is here rather than in `@endora-commerce/mod-auth`
+ *
+ * `auth` resolves the actor and writes it onto the request, so the shape lived
+ * beside that implementation — and the Fastify augmentation that puts it on
+ * `FastifyRequest` lived there with it. That made every reader of
+ * `request.actor` a consumer of a module: `backend/src/composition.ts` named
+ * `@endora-commerce/mod-auth/backend` for a type it erases at build time, the
+ * platform restated the shape structurally in four places because D-52/D-53
+ * forbids it the import, and a packaged module read it through a hand-written
+ * cast per module.
+ *
+ * The blocker on relocating it was believed to be `Session`: `auth`'s own
+ * barrel said moving the augmentation *"would take `Session` with it"*, because
+ * `ActorCustomer` and `ActorAdmin` each carried the ORM entity. Measured across
+ * `packages/`, `backend/`, `admin/` and `storefront/`, **no file outside
+ * `packages/modules/auth/` ever read `actor.session`** — `composition.ts` alone
+ * reads `kind`, `adminUserId`, `organizationId`, `customerAccountId`,
+ * `impersonatorAdminUserId` and `apiKeyId`, and `.session` not once. So the
+ * field was written by the auth plugin on every request and read by nobody, and
+ * dropping it is what lets the vocabulary sit in a package that imports neither
+ * Fastify nor the ORM.
+ *
+ * A consumer that needs the *session* asks `auth` for it — `AuthSessionPort`
+ * and `AuthSessionReadPort` in `./auth.js` are that surface, and they carry
+ * `AuthSessionRecord` rather than the entity.
+ *
+ * ## Where the Fastify augmentation lives
+ *
+ * Not here. `@endora-commerce/contracts` declares no dependency on Fastify, for
+ * the reason `RequireCustomerGuard` and `AdminActorPromotion` are in the
+ * platform's `kernel/ports/require-admin.ts` rather than in this package. The
+ * `declare module 'fastify'` block that adds `actor` and `adminActor` to
+ * `FastifyRequest` is `@endora-commerce/platform`'s
+ * (`src/http/request-actor.ts`), on the `./http` subpath.
+ */
+export {};
+//# sourceMappingURL=actor.js.map

package/dist/actor.js.map

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

package/dist/addresses.d.ts

@@ -0,0 +1,134 @@
+/**
+ * `addresses` module contracts — the in-process port surface (feature 075,
+ * Phase P).
+ *
+ * Ten inbound sites, split six-four: `orders` and `organizations` type
+ * themselves against `AddressService` to create, list and delete an
+ * organisation's addresses, and four read the `Address` entity directly —
+ * `orders` snapshotting one onto a placed order, `customers` serialising one,
+ * `quick_order` resolving a buyer's default.
+ *
+ * Plain TypeScript rather than Zod: these describe in-process calls. The HTTP
+ * shapes are `organizations.ts`' business, because that module serves the
+ * customer-facing address routes over this module's table.
+ */
+export type AddressKindValue = 'delivery' | 'billing';
+/**
+ * An address as it crosses a module boundary — a plain shape, never the ORM
+ * entity (FR-011).
+ *
+ * Every address belongs to an organisation, and there is no other kind: the
+ * Organization is the one tenant concept (Principle XI), and a B2C buyer's
+ * personal organisation holds theirs.
+ */
+export interface AddressRecord {
+    id: string;
+    organizationId: string;
+    kind: AddressKindValue;
+    recipientName: string;
+    street: string;
+    city: string;
+    postalCode: string;
+    country: string;
+    phone: string | null;
+    isDefault: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+    deletedAt: Date | null;
+}
+export interface CreateAddressInput {
+    kind: AddressKindValue;
+    recipientName: string;
+    street: string;
+    city: string;
+    postalCode: string;
+    country: string;
+    phone?: string;
+    isDefault?: boolean;
+}
+export type UpdateAddressInput = Partial<{
+    recipientName: string;
+    street: string;
+    city: string;
+    postalCode: string;
+    country: string;
+    phone: string;
+    isDefault: boolean;
+}>;
+/**
+ * Container name: `addressReadPort`. Owner: `addresses`.
+ *
+ * The four direct entity reads. `findById` is scoped by organisation on
+ * purpose: every caller already knows whose address it is asking for, and
+ * doing the check in one query is what stops it being forgotten.
+ *
+ * **`liveOnly` defaults to `false`: a by-id read returns a soft-deleted
+ * address.** The two lookups differ from the two lists on purpose — an address
+ * is soft-deleted, and `findById` / `findByIds` are how a caller resolves an id
+ * something else already stored, where "the row is gone" and "the row was
+ * deleted after it was referenced" are different answers and only the second is
+ * renderable. `listForOrganization` and `findDefault` are the opposite case —
+ * they are choosing an address to use *now* — so they filter `deletedAt: null`
+ * unconditionally and take no flag at all.
+ *
+ * The consequence, said plainly because it is one careless cut from a product
+ * change: a consumer replacing a hand-written `deletedAt: null` filter with
+ * `findById` and dropping the filter as "now redundant" reinstates deleted
+ * addresses. Pass `{ liveOnly: true }` whenever the answer feeds a choice
+ * rather than a rendering — all three call sites in the tree do
+ * (`orders/services/order-service.ts:989,1093,1096`). The record also carries
+ * `deletedAt`, so a caller that must tell the two apart can (Phase-P
+ * unreached-port audit, A8).
+ *
+ * **Owner off:** the seam fails closed — resolving this port throws
+ * `ModuleDisabledError` and the call answers 503 `MODULE_DISABLED`, so nothing
+ * half-executes. Whether `addresses` 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 AddressReadPort {
+    findById(organizationId: string, addressId: string, options?: {
+        liveOnly?: boolean;
+    }): Promise<AddressRecord | null>;
+    findByIds(organizationId: string, addressIds: readonly string[], options?: {
+        liveOnly?: boolean;
+    }): Promise<AddressRecord[]>;
+    /** An organisation's addresses, optionally of one kind, default first. */
+    listForOrganization(organizationId: string, kind?: AddressKindValue): Promise<AddressRecord[]>;
+    /** The organisation's default address of that kind, or `null`. */
+    findDefault(organizationId: string, kind: AddressKindValue): Promise<AddressRecord | null>;
+}
+/**
+ * Container name: `addressServicePort`. Owner: `addresses`.
+ *
+ * (It said `addressService` until issue #192, and that name **is** registered:
+ * it is the `AddressService` **class**, whose methods return `Address`
+ * entities. `Address` is structurally assignable to `AddressRecord`, so a
+ * consumer copying the old name out of this comment gets entities across the
+ * boundary behind a record-shaped type and `tsc` says nothing — the mapping
+ * `createAddressServicePort` performs is exactly what it skips. Two consumers
+ * followed it, `orders/backend.ts` and `organizations/backend.ts`; issue #195
+ * re-pointed both at `addressServicePort` under D-98.1, which ruled the call
+ * site wrong rather than this shape — every one of their six call sites reads
+ * fields or `.id` off the result, so the snapshot record is all any of them
+ * ever needed. The class registration stays for the module's own use.)
+ *
+ * The write surface `orders` and `organizations` reach. The
+ * one-default-per-kind invariant and the country-code validation stay on this
+ * side of the port, where they already are — `createAddress` validates the
+ * country against `dictionaries` before it writes, and a caller cannot be
+ * trusted to remember that.
+ *
+ * **Owner off:** the seam fails closed — resolving this port throws
+ * `ModuleDisabledError` and the call answers 503 `MODULE_DISABLED`, so nothing
+ * half-executes. Whether `addresses` 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 AddressServicePort {
+    list(organizationId: string, kind?: AddressKindValue): Promise<AddressRecord[]>;
+    createAddress(organizationId: string, input: CreateAddressInput): Promise<AddressRecord>;
+    updateAddress(organizationId: string, addressId: string, patch: UpdateAddressInput): Promise<AddressRecord>;
+    deleteAddress(organizationId: string, addressId: string): Promise<void>;
+}
+//# sourceMappingURL=addresses.d.ts.map

package/dist/addresses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addresses.d.ts","sourceRoot":"","sources":["../src/addresses.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,SAAS,CAAC;AAEtD;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,gBAAgB,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,gBAAgB,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,MAAM,kBAAkB,GAAG,OAAO,CAAC;IACvC,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CACN,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAC/B,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IACjC,SAAS,CACP,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAC/B,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IAC5B,0EAA0E;IAC1E,mBAAmB,CACjB,cAAc,EAAE,MAAM,EACtB,IAAI,CAAC,EAAE,gBAAgB,GACtB,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IAC5B,kEAAkE;IAClE,WAAW,CACT,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,cAAc,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IAChF,aAAa,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACzF,aAAa,CACX,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,aAAa,CAAC,CAAC;IAC1B,aAAa,CAAC,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzE"}

package/dist/addresses.js

@@ -0,0 +1,16 @@
+/**
+ * `addresses` module contracts — the in-process port surface (feature 075,
+ * Phase P).
+ *
+ * Ten inbound sites, split six-four: `orders` and `organizations` type
+ * themselves against `AddressService` to create, list and delete an
+ * organisation's addresses, and four read the `Address` entity directly —
+ * `orders` snapshotting one onto a placed order, `customers` serialising one,
+ * `quick_order` resolving a buyer's default.
+ *
+ * Plain TypeScript rather than Zod: these describe in-process calls. The HTTP
+ * shapes are `organizations.ts`' business, because that module serves the
+ * customer-facing address routes over this module's table.
+ */
+export {};
+//# sourceMappingURL=addresses.js.map

package/dist/addresses.js.map

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