@endora-commerce/contracts 0.100.0

package/dist/email.js

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+/**
+ * The `email` module's published contract (D-59, issue #114; extended by
+ * feature 075's Phase P).
+ *
+ * `email` owns no route, no entity and no worker: it is two registrations —
+ * the platform's outbound transport, and the durable record of what became of
+ * each message that left through it.
+ *
+ * The delivery recorder lives here rather than in the module because a second
+ * module reads it: `transactional_emails` decides `suppressed` above the
+ * transport and records that decision itself, so the shape is a boundary and
+ * not an internal. Feature 075 FR-001 — a type-only reach into another
+ * module's `services/` is still a reach.
+ *
+ * `EmailMailerPort` joins it for the same reason at a larger scale:
+ * thirty-two import sites across eight modules named `Mailer` /
+ * `MailerSendInput` at `email/services/mailer.ts`, which makes it the single
+ * largest contract in the sweep and the one with the smallest surface — two
+ * shapes and one method.
+ */
+/** What became of one outbound message. */
+export const emailDeliveryStatusSchema = z.enum(['sent', 'suppressed', 'failed']);
+/**
+ * Why a recorded message did not go out; absent for a delivered one.
+ *
+ * The split down the middle is the load-bearing part: the first two are the
+ * platform deliberately not sending, the last three are a message that was
+ * meant to go out and did not. An operator reading the record has to be able to
+ * tell a configuration from an outage, and since feature 074 shipped per-e-mail
+ * deactivation, "not sent" stopped being the same as "broken".
+ */
+export const emailDeliveryReasonSchema = z.enum([
+    /** Suppressed: the operator switched this e-mail off. */
+    'deactivated',
+    /** Suppressed: the transport had already accepted this message id. */
+    'duplicate_message_id',
+    /** Failed: the transport raised. */
+    'transport_error',
+    /** Failed: no transport is wired in this composition. */
+    'no_transport',
+    /** Failed: no template exists for this code. */
+    'no_definition',
+]);
+//# sourceMappingURL=email.js.map

package/dist/email.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email.js","sourceRoot":"","sources":["../src/email.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,2CAA2C;AAC3C,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAC;AAGlF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,IAAI,CAAC;IAC9C,yDAAyD;IACzD,aAAa;IACb,sEAAsE;IACtE,sBAAsB;IACtB,oCAAoC;IACpC,iBAAiB;IACjB,yDAAyD;IACzD,cAAc;IACd,gDAAgD;IAChD,eAAe;CAChB,CAAC,CAAC"}

package/dist/envelopes.d.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+/** Successful item-response envelope. Example: `{ data: { id: '…', … } }`. */
+export declare function dataEnvelope<T extends z.ZodTypeAny>(inner: T): z.ZodObject<{
+    data: T;
+}, z.core.$strip>;
+/** Successful collection-response envelope with cursor pagination. */
+export declare function collectionEnvelope<T extends z.ZodTypeAny>(inner: T): z.ZodObject<{
+    data: z.ZodArray<T>;
+    pagination: z.ZodObject<{
+        cursor: z.ZodNullable<z.ZodString>;
+        hasMore: z.ZodBoolean;
+        limit: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+//# sourceMappingURL=envelopes.d.ts.map

package/dist/envelopes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelopes.d.ts","sourceRoot":"","sources":["../src/envelopes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,KAAK,EAAE,CAAC;;kBAI5D;AAED,sEAAsE;AACtE,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,KAAK,EAAE,CAAC;;;;;;;kBAKlE"}

package/dist/envelopes.js

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+import { paginationSchema } from './pagination.js';
+/** Successful item-response envelope. Example: `{ data: { id: '…', … } }`. */
+export function dataEnvelope(inner) {
+    return z.object({
+        data: inner,
+    });
+}
+/** Successful collection-response envelope with cursor pagination. */
+export function collectionEnvelope(inner) {
+    return z.object({
+        data: z.array(inner),
+        pagination: paginationSchema,
+    });
+}
+//# sourceMappingURL=envelopes.js.map

package/dist/envelopes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelopes.js","sourceRoot":"","sources":["../src/envelopes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEnD,8EAA8E;AAC9E,MAAM,UAAU,YAAY,CAAyB,KAAQ;IAC3D,OAAO,CAAC,CAAC,MAAM,CAAC;QACd,IAAI,EAAE,KAAK;KACZ,CAAC,CAAC;AACL,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,kBAAkB,CAAyB,KAAQ;IACjE,OAAO,CAAC,CAAC,MAAM,CAAC;QACd,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC;QACpB,UAAU,EAAE,gBAAgB;KAC7B,CAAC,CAAC;AACL,CAAC"}

package/dist/environment-inputs.d.ts

@@ -0,0 +1,306 @@
+/**
+ * The environment-input declaration — what a running Endora needs, said once.
+ *
+ * Normative: `specs/117-instance-bring-up/contracts/environment-inputs.md`
+ * §1–§2, FR-001 and FR-005.
+ *
+ * ## Why the shape lives here
+ *
+ * Three programs read a declaration and none of them may author a second copy
+ * of it (D-100): `endora new instance` and `endora new storefront` (which
+ * values to resolve and write), `endora doctor` (which values to require and
+ * what their absence costs), and the reconciliation check. Four *authors*
+ * write one — the platform, each application, and every module in its own
+ * manifest — so the shape is a contract before it is anybody's data, which is
+ * what `packages/contracts` is for.
+ *
+ * ## `describes` carries both languages inline, and that is a decision
+ *
+ * §R1.1 puts this prose in the translation boundary's case 1 — the reader's
+ * language is resolvable when the sentence is composed — and says a module's
+ * ships in its own bundle. **A bundle is not reachable here.** The first
+ * reader is a CLI on a client's machine: it loads no `_i18n` reconciler, has
+ * no settings store to ask, and the *platform's* inputs have no owning
+ * module whose bundle they could sit in. So the sentence ships as `{ en, pl }`
+ * on the declaration itself, which satisfies the owner's translation policy
+ * (English by default, a Polish bundle beside it, English as the fallback)
+ * with the one mechanism a standalone program can read. The check holds both
+ * languages to a non-empty sentence, so a single-language declaration is a
+ * finding rather than a silent English-only input.
+ *
+ * ## There is deliberately no `default` field
+ *
+ * §R1.3. A declaration that could carry a default would become the seventieth
+ * home of an invented value, blessed by a contract — which is the exact thing
+ * the provenance line's `defaulted=0` exists to make impossible. The absence
+ * is load-bearing, not an omission.
+ *
+ * ## `consumers` scopes `requirement`; it does not merely describe it
+ *
+ * `specs/118-instance-member-selection/` establishes that an instance may
+ * deliberately omit a member — its admin being the ruled case (D-215). That
+ * member is absent when the operator declines it, or when
+ * `@endora-commerce/admin-shell` does not **resolve** at the version being
+ * installed (`specs/110-instance-repository/contracts/instance-tree.md` §2.4).
+ * This comment read *"while `@endora-commerce/admin-shell` does not exist"*
+ * until 2026-09-13, by which time `packages/admin-shell` did — a premise about
+ * the tree, written into a source file where nothing re-derives it. An input
+ * no written member reads is not "required and missing"; it is **not in this
+ * run's population at all**, which is what keeps the provenance line to four
+ * outcomes instead of five.
+ *
+ * **Scope by declared consumer, never by name.** Measured on this tree, the
+ * name-based rule is wrong on two of the three inputs that mention the admin:
+ *
+ *   * `VITE_API_BASE_URL` — read by `admin/src` alone. Dropped with the
+ *     member.
+ *   * `ADMIN_BASE_URL` — read by the **backend** (`mfa`, when it composes the
+ *     links it mails). Its *value* names the admin; its consumer is the
+ *     backend, and it matters **more** when the admin is on another host.
+ *   * `CORS_ALLOWED_ORIGINS` — read by the backend
+ *     (`packages/platform/src/http/server.ts`), and its value has to name the
+ *     admin's origin for the admin to work at all.
+ *
+ * Two of those three would be dropped by any rule keyed on the spelling.
+ */
+import { z } from 'zod';
+/**
+ * The trees that read an environment value.
+ *
+ * A value read by more than one is a value those trees must **agree** about,
+ * and under D-195 and D-207 two of the three are the client's own
+ * repositories — so the agreement cannot be checked from inside any one of
+ * them. That is `environment-inputs.md` §5's subject and the derivation is
+ * this field, never a table (R5.1, R5.4).
+ */
+export declare const ENVIRONMENT_CONSUMERS: readonly ["backend", "admin", "storefront"];
+export declare const EnvironmentConsumerSchema: z.ZodEnum<{
+    admin: "admin";
+    backend: "backend";
+    storefront: "storefront";
+}>;
+export type EnvironmentConsumer = z.infer<typeof EnvironmentConsumerSchema>;
+/**
+ * A sentence in every language the platform ships, on the declaration itself.
+ *
+ * See the header for why this is not a bundle key. Both members are required:
+ * "ships `en` and `pl`" enforced by the type rather than by anybody
+ * remembering, in the idiom the storefront's own `Record<MessageKey, string>`
+ * uses.
+ */
+export declare const LocalizedSentenceSchema: z.ZodObject<{
+    en: z.ZodString;
+    pl: z.ZodString;
+}, z.core.$strip>;
+export type LocalizedSentence = z.infer<typeof LocalizedSentenceSchema>;
+/**
+ * Required, conditionally required, or optional — and the middle term is the
+ * one that matters (§R1.2).
+ *
+ * `requiredWhen` is a predicate over **another input**: `MEILISEARCH_URL` is
+ * required iff `CATALOG_SEARCH_BACKEND=meilisearch`, and without the predicate
+ * a doctor would demand a service two thirds of deployments do not run.
+ *
+ * `optional` carries **what is lost**, never the word "optional". An operator
+ * deciding whether to set `SETTINGS_SECRET_ENCRYPTION_KEY` needs to read
+ * *"secret settings cannot be read or written"*, which is the fact; that the
+ * boot survives without it is not.
+ */
+export declare const EnvironmentRequirementSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"required">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"requiredWhen">;
+    input: z.ZodString;
+    equals: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"optional">;
+    without: z.ZodObject<{
+        en: z.ZodString;
+        pl: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>], "kind">;
+export type EnvironmentRequirement = z.infer<typeof EnvironmentRequirementSchema>;
+/**
+ * Who declares the input, which is what `foreign-input` is asked against.
+ *
+ * A module declaring an input another module owns is two answers to one
+ * question waiting to disagree, so ownership is a field rather than an
+ * inference from where the file sits.
+ */
+export declare const EnvironmentInputOwnerSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"platform">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"application">;
+    application: z.ZodEnum<{
+        admin: "admin";
+        backend: "backend";
+        storefront: "storefront";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"module">;
+    moduleId: z.ZodString;
+}, z.core.$strip>], "kind">;
+export type EnvironmentInputOwner = z.infer<typeof EnvironmentInputOwnerSchema>;
+/** One entry per environment variable a running platform reads (§1). */
+export declare const EnvironmentInputSchema: z.ZodObject<{
+    name: z.ZodString;
+    describes: z.ZodObject<{
+        en: z.ZodString;
+        pl: z.ZodString;
+    }, z.core.$strip>;
+    requirement: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"required">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"requiredWhen">;
+        input: z.ZodString;
+        equals: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"optional">;
+        without: z.ZodObject<{
+            en: z.ZodString;
+            pl: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>], "kind">;
+    secret: z.ZodBoolean;
+    generable: z.ZodBoolean;
+    owner: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"platform">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"application">;
+        application: z.ZodEnum<{
+            admin: "admin";
+            backend: "backend";
+            storefront: "storefront";
+        }>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"module">;
+        moduleId: z.ZodString;
+    }, z.core.$strip>], "kind">;
+    consumers: z.ZodArray<z.ZodEnum<{
+        admin: "admin";
+        backend: "backend";
+        storefront: "storefront";
+    }>>;
+    addressOf: z.ZodNullable<z.ZodEnum<{
+        admin: "admin";
+        backend: "backend";
+        storefront: "storefront";
+    }>>;
+}, z.core.$strip>;
+export type EnvironmentInput = z.infer<typeof EnvironmentInputSchema>;
+/** A whole declaration, as an application or the platform publishes it. */
+export declare const EnvironmentInputsSchema: z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    describes: z.ZodObject<{
+        en: z.ZodString;
+        pl: z.ZodString;
+    }, z.core.$strip>;
+    requirement: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"required">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"requiredWhen">;
+        input: z.ZodString;
+        equals: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"optional">;
+        without: z.ZodObject<{
+            en: z.ZodString;
+            pl: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>], "kind">;
+    secret: z.ZodBoolean;
+    generable: z.ZodBoolean;
+    owner: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"platform">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"application">;
+        application: z.ZodEnum<{
+            admin: "admin";
+            backend: "backend";
+            storefront: "storefront";
+        }>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"module">;
+        moduleId: z.ZodString;
+    }, z.core.$strip>], "kind">;
+    consumers: z.ZodArray<z.ZodEnum<{
+        admin: "admin";
+        backend: "backend";
+        storefront: "storefront";
+    }>>;
+    addressOf: z.ZodNullable<z.ZodEnum<{
+        admin: "admin";
+        backend: "backend";
+        storefront: "storefront";
+    }>>;
+}, z.core.$strip>>;
+/**
+ * Is this input in the population of a run that writes exactly these members?
+ *
+ * The `specs/118-instance-member-selection/` scoping, as one predicate. An
+ * input whose declared consumers are all outside the written set is **out of
+ * the population**: not resolved, not prompted for, not counted, not refused.
+ *
+ * Reading it the other way — "required, and therefore missing" — is what would
+ * force a fifth provenance outcome, because such an input can be neither
+ * `defaulted` (there is nothing to invent) nor honestly reported as resolved.
+ */
+export declare function isReadByAnyOf(input: EnvironmentInput, members: readonly EnvironmentConsumer[]): boolean;
+/**
+ * The declared inputs a run over these members actually has to answer for.
+ *
+ * Order is the declaration's, which is the order a prompt asks in
+ * (`input-resolution.md` §1: "in the declared order"). Sorting here would put
+ * the sequence in a comparator rather than in the hands of whoever wrote the
+ * declaration, and the first thing an operator is asked would then depend on
+ * an alphabet.
+ */
+export declare function scopeToMembers(inputs: readonly EnvironmentInput[], members: readonly EnvironmentConsumer[]): readonly EnvironmentInput[];
+/**
+ * Several authors' declarations, as the one population a reader has to answer.
+ *
+ * The four authors of `EnvironmentInput` are the platform, each application and
+ * every module in its own manifest, and nothing joins them: a scaffolded
+ * instance reads the platform's declaration **and** the manifest of every module
+ * it installed, and a doctor run against that instance reads the same pair. Two
+ * programs computing that join separately is two answers waiting to disagree,
+ * which is why the join is here rather than in either of them.
+ *
+ * **First author wins, and order is the first declaration's.** A name that
+ * migrates between authors is the case that happens — feature 121 moved
+ * `MEILISEARCH_URL` out of a module and into the platform, and a module may not
+ * describe a name the platform declares — so during such a move the platform's
+ * sentence is the one an operator reads, and the module's stale copy is shadowed
+ * rather than duplicated. Callers therefore pass the platform's declaration
+ * first. Across authors a shared name is expected and is **not** a finding;
+ * `check:env-inputs` says so, and this function is that rule's consequence
+ * rather than a second opinion about it.
+ */
+export declare function unionEnvironmentInputs(declarations: readonly (readonly EnvironmentInput[])[]): readonly EnvironmentInput[];
+/**
+ * The variables whose value is the address of `member`, in declaration order.
+ *
+ * One derivation, because the two programs that ask are `endora new storefront`
+ * — telling an author which variables to point at their backend — and the
+ * acceptance criterion, which points those same variables at the backend it
+ * booted. Deriving it twice is two answers waiting to disagree, and that is not
+ * hypothetical: the criterion once configured `PUBLIC_API_BASE_URL`, a name no
+ * file in the storefront reads, and its boot assertion measured the compiled-in
+ * fallback for a whole investigation.
+ *
+ * The population is the declaration handed in, so it is the **copy's** answer
+ * about the copy — under D-195 a client's storefront is theirs, declaring what
+ * it reads — and never a list compiled into either program.
+ */
+export declare function addressVariablesFor(inputs: readonly EnvironmentInput[], member: EnvironmentConsumer): readonly string[];
+/**
+ * Is this input required, given what the rest of the environment holds?
+ *
+ * `requiredWhen` is resolved against the **resolved** values rather than
+ * against `process.env`, so a condition can be answered by a flag the operator
+ * has just supplied — which is the case that happens: a run that sets
+ * `CATALOG_SEARCH_BACKEND=meilisearch` on its command line must be asked for
+ * `MEILISEARCH_URL` in the same run, not in the next one.
+ */
+export declare function isRequiredGiven(input: EnvironmentInput, values: Readonly<Record<string, string | undefined>>): boolean;
+//# sourceMappingURL=environment-inputs.d.ts.map

package/dist/environment-inputs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment-inputs.d.ts","sourceRoot":"","sources":["../src/environment-inputs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,6CAA8C,CAAC;AAEjF,eAAO,MAAM,yBAAyB;;;;EAAgC,CAAC;AACvE,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB;;;iBAGlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;2BAcvC,CAAC;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAElF;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;2BAItC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,wEAAwE;AACxE,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkDjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,2EAA2E;AAC3E,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAAkC,CAAC;AAEvE;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,gBAAgB,EACvB,OAAO,EAAE,SAAS,mBAAmB,EAAE,GACtC,OAAO,CAET;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,SAAS,gBAAgB,EAAE,EACnC,OAAO,EAAE,SAAS,mBAAmB,EAAE,GACtC,SAAS,gBAAgB,EAAE,CAE7B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,SAAS,CAAC,SAAS,gBAAgB,EAAE,CAAC,EAAE,GACrD,SAAS,gBAAgB,EAAE,CAQ7B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,gBAAgB,EAAE,EACnC,MAAM,EAAE,mBAAmB,GAC1B,SAAS,MAAM,EAAE,CAEnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,gBAAgB,EACvB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,GACnD,OAAO,CAST"}