@wildo-ai/saas-models 1.1.5 → 1.1.6

package/dist/esm/inbound/inbound-delivery.shared.schemas.js

@@ -0,0 +1,449 @@
+/**
+ * Inbound deliveries — the durable record of every verified message an application RECEIVED from
+ * another system, and the named vocabularies the inbound pipeline speaks (#1596).
+ *
+ * ## What an inbound delivery is
+ *
+ * A webhook POST (or, later, another inbound channel) that arrived at the application, passed
+ * signature verification, and was written here BEFORE anything acted on it. The row is three things
+ * at once, like its outbound twin `m2mWebhookDeliveryLog`:
+ *
+ *  1. the DEDUPLICATION LEDGER — `(sourceKey, dedupKey)` is unique, so one provider event causes at
+ *     most one handler run however many times the provider retries it (a Redis claim cannot promise
+ *     that: its TTL is shorter than a provider's retry window — Stripe retries for three days);
+ *  2. the WORK QUEUE the dispatch worker drains — `status` + `nextAttemptAt`;
+ *  3. the OPERATOR'S LOG — an administrator lists deliveries, sees why one is `DEAD`, and replays it.
+ *
+ * ## Why it is polymorphic over ORGANIZATION and APPLICATION
+ *
+ * A delivery's payload usually carries a client organization's personal data. Storing the row in its
+ * resolved organization's variant means it is erased with that organization (COMPOSITION,
+ * `onParentDelete: IMMEDIATE`) and is visible to that organization's administrator — the same
+ * tenant-segregation argument as the outbound delivery log. A delivery that resolves to no
+ * organization (an APPLICATION-scope handler, or an `UNROUTABLE` delivery) lives in the application
+ * variant.
+ *
+ * The consequence, stated rather than hidden: the two variants are two tables, so the unique index is
+ * per variant. The pipeline therefore resolves scope BEFORE inserting, and checks the other variant
+ * for the same key first. See `inbound-delivery-store.backend.service.ts` for the residual that
+ * leaves (two concurrent copies of one event resolving to different scopes in the same instant).
+ *
+ * @see engine/saas-models/src/notifications/m2m/m2m-webhook-delivery-log.shared.schemas.ts — the
+ *   outbound twin this is modelled on.
+ */
+import { z } from 'zod';
+import { addDataCategories } from '@wildo-ai/zod-decorators';
+import { PersonalDataCategory } from '../compliance/privacy/personal-data-category.shared.schemas.js';
+import { declarePolymorphicSchemas, optOutPolymorphicAutoBusinessKey, } from '../resources/utils/resource-polymorphism.schemas.js';
+import { CoreResourceType, coreResourceShared_FieldIdentifier, } from '../resources/resources.shared.core.definitions.js';
+import { InboundChannelKind, InboundSenderAssurance } from './inbound-channels.shared.schemas.js';
+// =============================================================================
+// NAMED VOCABULARIES
+// =============================================================================
+/**
+ * Where an inbound delivery came from — decides which route receives it and who owns its
+ * verification.
+ */
+export var InboundSourceKind;
+(function (InboundSourceKind) {
+    /**
+     * A PROVIDER declared the endpoint (`Hook_Endpoint` under `WEBHOOK_ORIGINATOR`) and owns its
+     * verification — Stripe's SDK `constructEvent`, for one. Route: `POST /webhooks/{providerRef}/{endpointKey}`.
+     */
+    InboundSourceKind["PROVIDER_ENDPOINT"] = "provider_endpoint";
+    /**
+     * The APPLICATION declared the endpoint on a handler and chose an engine-owned verification
+     * scheme. Route: `POST /webhooks/app/{endpointKey}` — the provider ref `app` is reserved so the
+     * two route families can never collide.
+     */
+    InboundSourceKind["APPLICATION_ENDPOINT"] = "application_endpoint";
+    /**
+     * A message received on an inbound CHANNEL (#1630) — email today — routed to an organization and
+     * handed to the channel handler selected for it. The handler names the channel, never the provider
+     * that received the message: that is the application's `EMAIL_INBOUND` selection.
+     */
+    InboundSourceKind["CHANNEL"] = "channel";
+})(InboundSourceKind || (InboundSourceKind = {}));
+/**
+ * Which scope a handler's deliveries run in. Declared by the handler, enforced by the pipeline: a
+ * delivery never runs in a scope its handler did not declare, and nothing ever FALLS BACK to the
+ * application scope.
+ */
+export var InboundHandlerScopeMode;
+(function (InboundHandlerScopeMode) {
+    /**
+     * Every delivery must resolve to one organization. One that does not is `UNROUTABLE` — recorded,
+     * audited, acknowledged with 200 and never run. It is NOT run at application scope, because the
+     * handler was written for a tenant and application scope would give it every tenant.
+     */
+    InboundHandlerScopeMode["ORGANIZATION_REQUIRED"] = "organization_required";
+    /** Deliveries run at application scope; no organization is resolved. */
+    InboundHandlerScopeMode["APPLICATION"] = "application";
+    /**
+     * The handler's `resolveScope` decides per delivery, because the source's events genuinely belong to
+     * different scopes (billing: a subscription event belongs to an organization's billing account, or to one
+     * person's). `resolveScope` must answer one of {@link InboundResolvedScopeKind}; there is no default.
+     *
+     * The handler is admitted to exactly the scopes it declares `actingRoles` for, and must declare at least
+     * one (#1629). A resolver answering a scope the handler holds no roles in makes the delivery `UNROUTABLE`
+     * (`SCOPE_NOT_ADMITTED_BY_HANDLER`). The `USER` scope is reachable only through this mode.
+     */
+    InboundHandlerScopeMode["RESOLVED_PER_DELIVERY"] = "resolved_per_delivery";
+})(InboundHandlerScopeMode || (InboundHandlerScopeMode = {}));
+/** What scope resolution concluded for one delivery. */
+export var InboundResolvedScopeKind;
+(function (InboundResolvedScopeKind) {
+    InboundResolvedScopeKind["ORGANIZATION"] = "organization";
+    InboundResolvedScopeKind["APPLICATION"] = "application";
+    /**
+     * The delivery belongs to ONE person — their personal (`USER_SELF`) data, such as a personal billing
+     * account (#1629). The handler acts with its declared `actingRoles.user` (application roles, since
+     * personal resources gate on them), confined to that person's rows. The person is the delivery's SCOPE:
+     * nobody authenticated as them. Stored in the application variant, where the application's operators
+     * see it.
+     */
+    InboundResolvedScopeKind["USER"] = "user";
+    /** No admissible scope — the delivery is recorded and acknowledged, never run. */
+    InboundResolvedScopeKind["UNROUTABLE"] = "unroutable";
+})(InboundResolvedScopeKind || (InboundResolvedScopeKind = {}));
+/**
+ * The engine-owned signature schemes an APPLICATION endpoint may declare. Each is implemented by the
+ * engine; an application picks one and supplies a secret. A scheme is added with its first user.
+ */
+export var InboundVerificationScheme;
+(function (InboundVerificationScheme) {
+    /**
+     * Svix (also used by Resend and the Standard Webhooks convention): HMAC-SHA256 over
+     * `{id}.{timestamp}.{body}` with a base64 `whsec_` secret, a versioned space-delimited signature
+     * header, and a five-minute timestamp window.
+     */
+    InboundVerificationScheme["SVIX_V1"] = "svix_v1";
+    /**
+     * HMAC-SHA256 of the raw body (or of `{timestamp}.{body}` when a timestamp header is declared)
+     * carried in one declared header.
+     */
+    InboundVerificationScheme["HMAC_SHA256_HEADER"] = "hmac_sha256_header";
+})(InboundVerificationScheme || (InboundVerificationScheme = {}));
+/** How an {@link InboundVerificationScheme.HMAC_SHA256_HEADER} signature is encoded in its header. */
+export var HmacSignatureEncoding;
+(function (HmacSignatureEncoding) {
+    HmacSignatureEncoding["HEX"] = "hex";
+    HmacSignatureEncoding["BASE64"] = "base64";
+})(HmacSignatureEncoding || (HmacSignatureEncoding = {}));
+/**
+ * The lifecycle of one stored delivery.
+ *
+ * ```
+ * RECEIVED → PROCESSING → PROCESSED
+ *                       → RETRY_SCHEDULED → PROCESSING → …
+ *                       → DEAD            (attempts or window exhausted)
+ * DEAD → RECEIVED                         (operator replay, justified and audited)
+ * UNROUTABLE                              (terminal: no admissible scope, never run)
+ * ```
+ */
+export var InboundDeliveryStatus;
+(function (InboundDeliveryStatus) {
+    /** Verified and stored; waiting for the dispatch worker. */
+    InboundDeliveryStatus["RECEIVED"] = "received";
+    /** A worker holds it and is running the handler. */
+    InboundDeliveryStatus["PROCESSING"] = "processing";
+    /** The last attempt failed; `nextAttemptAt` says when the next one runs. */
+    InboundDeliveryStatus["RETRY_SCHEDULED"] = "retry_scheduled";
+    /** The handler completed. Terminal. */
+    InboundDeliveryStatus["PROCESSED"] = "processed";
+    /** Every attempt the handler's retry policy allows has failed. Terminal until an operator replays it. */
+    InboundDeliveryStatus["DEAD"] = "dead";
+    /** No admissible scope was resolved, so the handler never ran. Terminal. */
+    InboundDeliveryStatus["UNROUTABLE"] = "unroutable";
+})(InboundDeliveryStatus || (InboundDeliveryStatus = {}));
+/** Statuses a row never leaves on its own — the retention clock starts at the instant a row reaches one. */
+export const INBOUND_DELIVERY_TERMINAL_STATUSES = Object.freeze([
+    InboundDeliveryStatus.PROCESSED,
+    InboundDeliveryStatus.DEAD,
+    InboundDeliveryStatus.UNROUTABLE,
+]);
+/** Why an inbound request was refused BEFORE it became a delivery. Carried on `INBOUND_DELIVERY_REJECTED`. */
+export var InboundDeliveryRejectionReason;
+(function (InboundDeliveryRejectionReason) {
+    /** The signature did not verify under the configured secret, or was absent. */
+    InboundDeliveryRejectionReason["SIGNATURE_INVALID"] = "signature_invalid";
+    /** The signed timestamp is outside the scheme's window — a stale or replayed message. */
+    InboundDeliveryRejectionReason["TIMESTAMP_OUT_OF_WINDOW"] = "timestamp_out_of_window";
+    /** No verification secret is configured, so nothing can be verified. */
+    InboundDeliveryRejectionReason["SECRET_NOT_CONFIGURED"] = "secret_not_configured";
+    /** The body exceeds the endpoint's `maxBodyBytes`. */
+    InboundDeliveryRejectionReason["BODY_TOO_LARGE"] = "body_too_large";
+    /** The endpoint accepts `application/json` only. */
+    InboundDeliveryRejectionReason["UNSUPPORTED_MEDIA_TYPE"] = "unsupported_media_type";
+    /** The body verified but is not what the handler declared (not JSON, or its payload schema refused it). */
+    InboundDeliveryRejectionReason["MALFORMED"] = "malformed";
+})(InboundDeliveryRejectionReason || (InboundDeliveryRejectionReason = {}));
+/** Why a verified delivery was never run. Carried on the row and on `INBOUND_DELIVERY_UNROUTABLE`. */
+export var InboundDeliveryUnroutableReason;
+(function (InboundDeliveryUnroutableReason) {
+    /** An `ORGANIZATION_REQUIRED` handler's resolver found no organization. */
+    InboundDeliveryUnroutableReason["NO_ORGANIZATION_RESOLVED"] = "no_organization_resolved";
+    /** The handler's `resolveScope` itself answered `UNROUTABLE`. */
+    InboundDeliveryUnroutableReason["RESOLVER_DECLARED_UNROUTABLE"] = "resolver_declared_unroutable";
+    /** A resolver answered a scope the handler's scope mode does not admit. */
+    InboundDeliveryUnroutableReason["SCOPE_NOT_ADMITTED_BY_HANDLER"] = "scope_not_admitted_by_handler";
+    /** The resolver named an organization that does not exist. */
+    InboundDeliveryUnroutableReason["ORGANIZATION_NOT_FOUND"] = "organization_not_found";
+    /**
+     * The resolver named an organization whose status confers no authority (suspended, marked for
+     * deletion). Its own members could not act there either, so a handler must not.
+     */
+    InboundDeliveryUnroutableReason["ORGANIZATION_WITHOUT_AUTHORITY"] = "organization_without_authority";
+    /**
+     * A channel message arrived on a reply token that belongs to ANOTHER organization than the one its
+     * address routed to (#1630, I12). Either a misconfiguration or an attempt to reach across tenants; in
+     * both cases it must not run in either.
+     */
+    InboundDeliveryUnroutableReason["REPLY_TOKEN_OF_ANOTHER_ORGANIZATION"] = "reply_token_of_another_organization";
+    /** The resolver named a person who does not exist (#1629). */
+    InboundDeliveryUnroutableReason["USER_NOT_FOUND"] = "user_not_found";
+    /**
+     * The resolver named a person whose status confers no authority (anything but active). They could not
+     * act on their own data either, so a handler must not act on it for them (#1629).
+     */
+    InboundDeliveryUnroutableReason["USER_WITHOUT_AUTHORITY"] = "user_without_authority";
+    /** An email recipient no route reaches: no reply token, client mailbox, verified organization domain or shared-domain slug matched it (#1600). */
+    InboundDeliveryUnroutableReason["EMAIL_ADDRESS_NOT_ROUTED"] = "email_address_not_routed";
+    /** An email recipient on a claimed organization domain that is not VERIFIED — pending, failed or suspended (#1600, E3). */
+    InboundDeliveryUnroutableReason["EMAIL_DOMAIN_NOT_VERIFIED"] = "email_domain_not_verified";
+    /**
+     * An email recipient on a client mailbox whose authority does not hold right now: the relationship is not ACTIVE,
+     * or the domain is not VERIFIED, or it is not the firm's (#1600, E4).
+     */
+    InboundDeliveryUnroutableReason["CLIENT_MAILBOX_NOT_AUTHORIZED"] = "client_mailbox_not_authorized";
+    /** An email recipient on the shared domain whose slug belonged to a DELETED organization (#1600, L3). */
+    InboundDeliveryUnroutableReason["SHARED_DOMAIN_SLUG_TOMBSTONED"] = "shared_domain_slug_tombstoned";
+})(InboundDeliveryUnroutableReason || (InboundDeliveryUnroutableReason = {}));
+/** How the wait between a handler's failed attempts grows. */
+export var InboundRetryBackoffKind;
+(function (InboundRetryBackoffKind) {
+    /** `baseSeconds × 2^(attempt−1)`, capped at `maxSeconds`. The default: a failing dependency gets room to recover. */
+    InboundRetryBackoffKind["EXPONENTIAL"] = "exponential";
+    /** `baseSeconds` every time. */
+    InboundRetryBackoffKind["FIXED"] = "fixed";
+})(InboundRetryBackoffKind || (InboundRetryBackoffKind = {}));
+/** The outcome of one handler attempt, recorded on the row. */
+export var InboundDeliveryAttemptOutcome;
+(function (InboundDeliveryAttemptOutcome) {
+    InboundDeliveryAttemptOutcome["PROCESSED"] = "processed";
+    InboundDeliveryAttemptOutcome["FAILED"] = "failed";
+})(InboundDeliveryAttemptOutcome || (InboundDeliveryAttemptOutcome = {}));
+// =============================================================================
+// VERIFICATION CONFIGURATION (declared by an APPLICATION endpoint)
+// =============================================================================
+export const InboundSvixVerificationConfigSchema = z.strictObject({
+    scheme: z.literal(InboundVerificationScheme.SVIX_V1).systemEnum('InboundVerificationScheme'),
+});
+export const InboundHmacSha256HeaderVerificationConfigSchema = z.strictObject({
+    scheme: z.literal(InboundVerificationScheme.HMAC_SHA256_HEADER).systemEnum('InboundVerificationScheme'),
+    /** Header carrying the signature, e.g. `x-hub-signature-256`. Matched case-insensitively. */
+    signatureHeader: z.string().min(1),
+    encoding: z.enum(HmacSignatureEncoding).systemEnum('HmacSignatureEncoding'),
+    /**
+     * A literal the sender puts in front of the signature, e.g. `sha256=`. Stripped before comparison;
+     * a header that does not start with it is refused.
+     */
+    signaturePrefix: z.string().min(1).optional(),
+    /**
+     * Header carrying the send time in seconds since the epoch. When declared, the SIGNED content is
+     * `{timestamp}.{rawBody}` and the timestamp must fall within `toleranceSeconds` of now.
+     *
+     * A timestamp that is checked but not signed would be a control that does nothing: whoever
+     * replays a captured message rewrites the header too. So declaring one changes what is signed.
+     */
+    timestampHeader: z.string().min(1).optional(),
+    /** Window for `timestampHeader`, in seconds. Defaults to 300 (five minutes). */
+    toleranceSeconds: z.number().int().positive().max(3600).optional(),
+});
+/** The verification an APPLICATION endpoint declares. Discriminated on `scheme`. */
+export const InboundVerificationConfigSchema = z.discriminatedUnion('scheme', [
+    InboundSvixVerificationConfigSchema,
+    InboundHmacSha256HeaderVerificationConfigSchema,
+]);
+/** Engine default for an application endpoint's body cap: 256 KB. Per endpoint, never per route prefix. */
+export const INBOUND_APPLICATION_ENDPOINT_DEFAULT_MAX_BODY_BYTES = 256 * 1024;
+/** The provider ref reserved for application endpoints: `/webhooks/app/{endpointKey}`. */
+export const INBOUND_APPLICATION_ENDPOINT_PROVIDER_REF = 'app';
+// =============================================================================
+// STORED DELIVERY
+// =============================================================================
+/** The scope a stored delivery resolved to. Discriminated on `kind`; never absent. */
+export const InboundDeliveryResolvedScopeSchema = z.discriminatedUnion('kind', [
+    z.strictObject({
+        kind: z
+            .literal(InboundResolvedScopeKind.ORGANIZATION)
+            .systemEnum('InboundResolvedScopeKind')
+            .describe('The delivery resolved to one organization and runs in that organization.'),
+        organizationId: z.string().min(1),
+    }),
+    z.strictObject({
+        kind: z
+            .literal(InboundResolvedScopeKind.APPLICATION)
+            .systemEnum('InboundResolvedScopeKind')
+            .describe('The delivery runs at application scope, with no organization.'),
+    }),
+    z.strictObject({
+        kind: z
+            .literal(InboundResolvedScopeKind.USER)
+            .systemEnum('InboundResolvedScopeKind')
+            .describe('The delivery belongs to one person and runs on that person\'s own data, with the handler\'s roles; nobody signed in as them.'),
+        userId: z.string().min(1).describe('The person the delivery belongs to.'),
+    }),
+    z.strictObject({
+        kind: z
+            .literal(InboundResolvedScopeKind.UNROUTABLE)
+            .systemEnum('InboundResolvedScopeKind')
+            .describe('No admissible scope was resolved, so the handler never runs this delivery.'),
+        reason: z
+            .enum(InboundDeliveryUnroutableReason)
+            .systemEnum('InboundDeliveryUnroutableReason')
+            .describe('Why no admissible scope was resolved.'),
+    }),
+]);
+export const InboundDeliveryAttemptSchema = z.strictObject({
+    at: z.date().describe('When the attempt ended.'),
+    outcome: z
+        .enum(InboundDeliveryAttemptOutcome)
+        .systemEnum('InboundDeliveryAttemptOutcome')
+        .describe('Whether the handler completed (`processed`) or failed (`failed`) on this attempt.'),
+    /** A classified code, never the error message: a message can quote the payload. */
+    errorCode: z
+        .string()
+        .max(200)
+        .optional()
+        .describe('For a failed attempt, a classified error code — the error type and message reference joined by a colon, or the error name. Never the error message, which could quote the payload. At most 200 characters.'),
+});
+export const InboundDeliveryReplaySchema = z.strictObject({
+    /** The user who replayed the delivery. */
+    by: z.string().min(1).describe('The id of the user who replayed the delivery.'),
+    at: z.date().describe('When the delivery was replayed.'),
+    justification: z.string().min(1).max(2000).describe('Why the delivery was replayed, as written by that user. Also recorded on the audit trail.'),
+});
+const INBOUND_DELIVERY_SCOPE_VARIANTS = [
+    {
+        parentResourceType: CoreResourceType.ORGANIZATIONS,
+        parentFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.ORGANIZATIONS],
+        isPrimaryScope: true,
+    },
+    {
+        parentResourceType: CoreResourceType.APPLICATION,
+        parentFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.APPLICATION],
+        isPrimaryScope: true,
+    },
+];
+/**
+ * One stored delivery. Written by the pipeline only (CREATE and UPDATE are REPOSITORY_ONLY); an
+ * administrator reads it and may REPLAY a `DEAD` one.
+ */
+export const InboundDeliveryBaseSchema = z.object({
+    _id: z.string().min(1).isPrimaryKey().isSummaryField(),
+    sourceKind: z.enum(InboundSourceKind).systemEnum('InboundSourceKind').isSummaryField(),
+    /**
+     * The source's stable identity: `{providerRef}:{endpointKey}`, with `app` as the provider ref of an
+     * application endpoint. Half of the dedup key.
+     */
+    sourceKey: z.string().min(1).isDBIndexed().isSummaryField(),
+    /** The handler that owns the delivery — the `ref` it was declared with. */
+    handlerRef: z.string().min(1).isDBIndexed().isSummaryField(),
+    /**
+     * The provider's delivery id (`svix-id`, Stripe's event id), or the handler's `dedupKey`. The other
+     * half of the unique key: one event, one run.
+     */
+    dedupKey: z.string().min(1).max(512).isSummaryField(),
+    /** Deliveries sharing a non-null ordering key run one at a time, in receive order. */
+    orderingKey: z.string().min(1).max(512).isDBIndexed().nullable().default(null),
+    /** The id the provider signed, when its scheme carries one. */
+    providerDeliveryId: z.string().max(512).optional(),
+    /** When the provider says it signed the message, when the scheme carries a timestamp. */
+    signedAt: z.date().optional(),
+    receivedAt: z.date().isDBIndexed().isSummaryField(),
+    /**
+     * The exact bytes that were verified, base64-encoded. Kept because a replay must run the handler on
+     * what was actually signed, not on a re-serialization of it. USER_CONTENT: a delivery carries
+     * whatever the sending system put in it, which is routinely a client's personal data.
+     */
+    rawBody: addDataCategories(z.string(), PersonalDataCategory.USER_CONTENT),
+    /** Only the headers the verification scheme and the handler need; never cookies or authorization. */
+    headers: z.record(z.string(), z.string()).default({}),
+    resolvedScope: InboundDeliveryResolvedScopeSchema,
+    /**
+     * The channel the delivery arrived on (#1630). `WEBHOOK` for every endpoint delivery (#1596) — derived,
+     * never declared — and the default, which is EXACT for every row stored before channels existed: only
+     * signed endpoint deliveries were ever stored.
+     */
+    channel: z.enum(InboundChannelKind).systemEnum('InboundChannelKind').default(InboundChannelKind.WEBHOOK).isSummaryField()
+        .describe('The channel the delivery arrived on: a signed webhook, or a received email.'),
+    /**
+     * How much is known about who sent it, on the channel's own ladder. `SOURCE_SIGNED` for a webhook — a
+     * delivery is stored only after its signature verified — and the default for the same reason as above.
+     * Identification only: it grants the handler nothing.
+     */
+    senderAssurance: z.enum(InboundSenderAssurance).systemEnum('InboundSenderAssurance').default(InboundSenderAssurance.SOURCE_SIGNED)
+        .describe('How much is known about who sent the message, on its channel\'s own ladder. It identifies the sender and grants the handler nothing.'),
+    /** The conversation thread a channel delivery was correlated into; null for a webhook. */
+    threadId: z.string().isDBIndexed().nullable().default(null)
+        .describe('The conversation thread the message was recorded in; null for a webhook delivery.'),
+    status: z
+        .enum(InboundDeliveryStatus)
+        .systemEnum('InboundDeliveryStatus')
+        .default(InboundDeliveryStatus.RECEIVED)
+        .isDBIndexed()
+        .isSummaryField(),
+    /**
+     * Attempts started, ever. Incremented by every lease, so it is also the FENCING token: a worker
+     * whose lease expired and was taken over can no longer settle the row, because the takeover moved
+     * the count. Never reset — a replay starts a new budget instead (see `budgetBaseAttemptCount`).
+     */
+    attemptCount: z.number().int().nonnegative().default(0).isSummaryField(),
+    /** The attempts' outcomes, oldest first. */
+    attempts: z.array(InboundDeliveryAttemptSchema).default([]),
+    /** When the next attempt may start; set while `RECEIVED` or `RETRY_SCHEDULED`. */
+    nextAttemptAt: z.date().isDBIndexed().nullable().default(null),
+    /** While `PROCESSING`: when a worker that stopped answering loses the row to the sweep. */
+    leaseExpiresAt: z.date().isDBIndexed().nullable().default(null),
+    /**
+     * The start of the current retry budget: receipt, or the last replay. The handler's retry window
+     * is measured from here, so a replay after the handler is fixed gets a whole policy again.
+     */
+    budgetStartedAt: z.date(),
+    /** `attemptCount` when the current budget started; attempts in the budget are the difference. */
+    budgetBaseAttemptCount: z.number().int().nonnegative().default(0),
+    /** Set when the row reached a terminal status — the retention clock's start point. */
+    /*
+     * `.isDBIndexed()` sits on the INNER type on these four nullable-with-default fields. That placement
+     * was required until #1647: behind two wrappers a decorator used to stop on the middle wrapper, and the
+     * PostgreSQL planner reads the innermost type, so the index was silently not planned (#1644). Mirroring
+     * now reaches the leaf either way; the placement is kept because it states the index on the type indexed.
+     */
+    terminalAt: z.date().isDBIndexed().nullable().default(null),
+    replays: z.array(InboundDeliveryReplaySchema).default([]),
+    createdAt: z
+        .date()
+        .default(() => new Date())
+        .isDBIndexed()
+        .excludeFromCreate()
+        .excludeFromUpdate(),
+    updatedAt: z
+        .date()
+        .default(() => new Date())
+        .excludeFromCreate()
+        .excludeFromUpdate(),
+}).businessKeySet(['sourceKey', 'dedupKey']);
+/**
+ * Yields `organizationInboundDeliveries` (FK `organizationId`) and `applicationInboundDeliveries`
+ * (FK `applicationId`). Many rows per scope, so the singleton business-key default is opted out of;
+ * the row's identity is the `(sourceKey, dedupKey)` set above.
+ */
+export const inboundDeliveryPolymorphicDeclaration = declarePolymorphicSchemas({
+    baseResourceType: 'inboundDeliveries',
+    baseFieldIdentifier: 'inboundDeliveryId',
+    baseEnumKey: 'INBOUND_DELIVERIES',
+    baseSchema: InboundDeliveryBaseSchema,
+    variants: INBOUND_DELIVERY_SCOPE_VARIANTS.map(optOutPolymorphicAutoBusinessKey),
+});
+//# sourceMappingURL=inbound-delivery.shared.schemas.js.map

package/dist/esm/inbound/inbound-delivery.shared.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbound-delivery.shared.schemas.js","sourceRoot":"","sources":["../../../../src/inbound/inbound-delivery.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Inbound deliveries — the durable record of every verified message an application RECEIVED from\n * another system, and the named vocabularies the inbound pipeline speaks (#1596).\n *\n * ## What an inbound delivery is\n *\n * A webhook POST (or, later, another inbound channel) that arrived at the application, passed\n * signature verification, and was written here BEFORE anything acted on it. The row is three things\n * at once, like its outbound twin `m2mWebhookDeliveryLog`:\n *\n *  1. the DEDUPLICATION LEDGER — `(sourceKey, dedupKey)` is unique, so one provider event causes at\n *     most one handler run however many times the provider retries it (a Redis claim cannot promise\n *     that: its TTL is shorter than a provider's retry window — Stripe retries for three days);\n *  2. the WORK QUEUE the dispatch worker drains — `status` + `nextAttemptAt`;\n *  3. the OPERATOR'S LOG — an administrator lists deliveries, sees why one is `DEAD`, and replays it.\n *\n * ## Why it is polymorphic over ORGANIZATION and APPLICATION\n *\n * A delivery's payload usually carries a client organization's personal data. Storing the row in its\n * resolved organization's variant means it is erased with that organization (COMPOSITION,\n * `onParentDelete: IMMEDIATE`) and is visible to that organization's administrator — the same\n * tenant-segregation argument as the outbound delivery log. A delivery that resolves to no\n * organization (an APPLICATION-scope handler, or an `UNROUTABLE` delivery) lives in the application\n * variant.\n *\n * The consequence, stated rather than hidden: the two variants are two tables, so the unique index is\n * per variant. The pipeline therefore resolves scope BEFORE inserting, and checks the other variant\n * for the same key first. See `inbound-delivery-store.backend.service.ts` for the residual that\n * leaves (two concurrent copies of one event resolving to different scopes in the same instant).\n *\n * @see engine/saas-models/src/notifications/m2m/m2m-webhook-delivery-log.shared.schemas.ts — the\n *   outbound twin this is modelled on.\n */\n\nimport { z } from 'zod';\nimport { addDataCategories } from '@wildo-ai/zod-decorators';\nimport { PersonalDataCategory } from '../compliance/privacy/personal-data-category.shared.schemas';\nimport {\n  declarePolymorphicSchemas,\n  optOutPolymorphicAutoBusinessKey,\n  type PolymorphicVariantDefinition,\n} from '../resources/utils/resource-polymorphism.schemas';\nimport {\n  CoreResourceType,\n  coreResourceShared_FieldIdentifier,\n} from '../resources/resources.shared.core.definitions';\nimport { InboundChannelKind, InboundSenderAssurance } from './inbound-channels.shared.schemas';\n\n// =============================================================================\n// NAMED VOCABULARIES\n// =============================================================================\n\n/**\n * Where an inbound delivery came from — decides which route receives it and who owns its\n * verification.\n */\nexport enum InboundSourceKind {\n  /**\n   * A PROVIDER declared the endpoint (`Hook_Endpoint` under `WEBHOOK_ORIGINATOR`) and owns its\n   * verification — Stripe's SDK `constructEvent`, for one. Route: `POST /webhooks/{providerRef}/{endpointKey}`.\n   */\n  PROVIDER_ENDPOINT = 'provider_endpoint',\n  /**\n   * The APPLICATION declared the endpoint on a handler and chose an engine-owned verification\n   * scheme. Route: `POST /webhooks/app/{endpointKey}` — the provider ref `app` is reserved so the\n   * two route families can never collide.\n   */\n  APPLICATION_ENDPOINT = 'application_endpoint',\n  /**\n   * A message received on an inbound CHANNEL (#1630) — email today — routed to an organization and\n   * handed to the channel handler selected for it. The handler names the channel, never the provider\n   * that received the message: that is the application's `EMAIL_INBOUND` selection.\n   */\n  CHANNEL = 'channel',\n}\n\n/**\n * Which scope a handler's deliveries run in. Declared by the handler, enforced by the pipeline: a\n * delivery never runs in a scope its handler did not declare, and nothing ever FALLS BACK to the\n * application scope.\n */\nexport enum InboundHandlerScopeMode {\n  /**\n   * Every delivery must resolve to one organization. One that does not is `UNROUTABLE` — recorded,\n   * audited, acknowledged with 200 and never run. It is NOT run at application scope, because the\n   * handler was written for a tenant and application scope would give it every tenant.\n   */\n  ORGANIZATION_REQUIRED = 'organization_required',\n  /** Deliveries run at application scope; no organization is resolved. */\n  APPLICATION = 'application',\n  /**\n   * The handler's `resolveScope` decides per delivery, because the source's events genuinely belong to\n   * different scopes (billing: a subscription event belongs to an organization's billing account, or to one\n   * person's). `resolveScope` must answer one of {@link InboundResolvedScopeKind}; there is no default.\n   *\n   * The handler is admitted to exactly the scopes it declares `actingRoles` for, and must declare at least\n   * one (#1629). A resolver answering a scope the handler holds no roles in makes the delivery `UNROUTABLE`\n   * (`SCOPE_NOT_ADMITTED_BY_HANDLER`). The `USER` scope is reachable only through this mode.\n   */\n  RESOLVED_PER_DELIVERY = 'resolved_per_delivery',\n}\n\n/** What scope resolution concluded for one delivery. */\nexport enum InboundResolvedScopeKind {\n  ORGANIZATION = 'organization',\n  APPLICATION = 'application',\n  /**\n   * The delivery belongs to ONE person — their personal (`USER_SELF`) data, such as a personal billing\n   * account (#1629). The handler acts with its declared `actingRoles.user` (application roles, since\n   * personal resources gate on them), confined to that person's rows. The person is the delivery's SCOPE:\n   * nobody authenticated as them. Stored in the application variant, where the application's operators\n   * see it.\n   */\n  USER = 'user',\n  /** No admissible scope — the delivery is recorded and acknowledged, never run. */\n  UNROUTABLE = 'unroutable',\n}\n\n/**\n * The engine-owned signature schemes an APPLICATION endpoint may declare. Each is implemented by the\n * engine; an application picks one and supplies a secret. A scheme is added with its first user.\n */\nexport enum InboundVerificationScheme {\n  /**\n   * Svix (also used by Resend and the Standard Webhooks convention): HMAC-SHA256 over\n   * `{id}.{timestamp}.{body}` with a base64 `whsec_` secret, a versioned space-delimited signature\n   * header, and a five-minute timestamp window.\n   */\n  SVIX_V1 = 'svix_v1',\n  /**\n   * HMAC-SHA256 of the raw body (or of `{timestamp}.{body}` when a timestamp header is declared)\n   * carried in one declared header.\n   */\n  HMAC_SHA256_HEADER = 'hmac_sha256_header',\n}\n\n/** How an {@link InboundVerificationScheme.HMAC_SHA256_HEADER} signature is encoded in its header. */\nexport enum HmacSignatureEncoding {\n  HEX = 'hex',\n  BASE64 = 'base64',\n}\n\n/**\n * The lifecycle of one stored delivery.\n *\n * ```\n * RECEIVED → PROCESSING → PROCESSED\n *                       → RETRY_SCHEDULED → PROCESSING → …\n *                       → DEAD            (attempts or window exhausted)\n * DEAD → RECEIVED                         (operator replay, justified and audited)\n * UNROUTABLE                              (terminal: no admissible scope, never run)\n * ```\n */\nexport enum InboundDeliveryStatus {\n  /** Verified and stored; waiting for the dispatch worker. */\n  RECEIVED = 'received',\n  /** A worker holds it and is running the handler. */\n  PROCESSING = 'processing',\n  /** The last attempt failed; `nextAttemptAt` says when the next one runs. */\n  RETRY_SCHEDULED = 'retry_scheduled',\n  /** The handler completed. Terminal. */\n  PROCESSED = 'processed',\n  /** Every attempt the handler's retry policy allows has failed. Terminal until an operator replays it. */\n  DEAD = 'dead',\n  /** No admissible scope was resolved, so the handler never ran. Terminal. */\n  UNROUTABLE = 'unroutable',\n}\n\n/** Statuses a row never leaves on its own — the retention clock starts at the instant a row reaches one. */\nexport const INBOUND_DELIVERY_TERMINAL_STATUSES: readonly InboundDeliveryStatus[] = Object.freeze([\n  InboundDeliveryStatus.PROCESSED,\n  InboundDeliveryStatus.DEAD,\n  InboundDeliveryStatus.UNROUTABLE,\n]);\n\n/** Why an inbound request was refused BEFORE it became a delivery. Carried on `INBOUND_DELIVERY_REJECTED`. */\nexport enum InboundDeliveryRejectionReason {\n  /** The signature did not verify under the configured secret, or was absent. */\n  SIGNATURE_INVALID = 'signature_invalid',\n  /** The signed timestamp is outside the scheme's window — a stale or replayed message. */\n  TIMESTAMP_OUT_OF_WINDOW = 'timestamp_out_of_window',\n  /** No verification secret is configured, so nothing can be verified. */\n  SECRET_NOT_CONFIGURED = 'secret_not_configured',\n  /** The body exceeds the endpoint's `maxBodyBytes`. */\n  BODY_TOO_LARGE = 'body_too_large',\n  /** The endpoint accepts `application/json` only. */\n  UNSUPPORTED_MEDIA_TYPE = 'unsupported_media_type',\n  /** The body verified but is not what the handler declared (not JSON, or its payload schema refused it). */\n  MALFORMED = 'malformed',\n}\n\n/** Why a verified delivery was never run. Carried on the row and on `INBOUND_DELIVERY_UNROUTABLE`. */\nexport enum InboundDeliveryUnroutableReason {\n  /** An `ORGANIZATION_REQUIRED` handler's resolver found no organization. */\n  NO_ORGANIZATION_RESOLVED = 'no_organization_resolved',\n  /** The handler's `resolveScope` itself answered `UNROUTABLE`. */\n  RESOLVER_DECLARED_UNROUTABLE = 'resolver_declared_unroutable',\n  /** A resolver answered a scope the handler's scope mode does not admit. */\n  SCOPE_NOT_ADMITTED_BY_HANDLER = 'scope_not_admitted_by_handler',\n  /** The resolver named an organization that does not exist. */\n  ORGANIZATION_NOT_FOUND = 'organization_not_found',\n  /**\n   * The resolver named an organization whose status confers no authority (suspended, marked for\n   * deletion). Its own members could not act there either, so a handler must not.\n   */\n  ORGANIZATION_WITHOUT_AUTHORITY = 'organization_without_authority',\n  /**\n   * A channel message arrived on a reply token that belongs to ANOTHER organization than the one its\n   * address routed to (#1630, I12). Either a misconfiguration or an attempt to reach across tenants; in\n   * both cases it must not run in either.\n   */\n  REPLY_TOKEN_OF_ANOTHER_ORGANIZATION = 'reply_token_of_another_organization',\n  /** The resolver named a person who does not exist (#1629). */\n  USER_NOT_FOUND = 'user_not_found',\n  /**\n   * The resolver named a person whose status confers no authority (anything but active). They could not\n   * act on their own data either, so a handler must not act on it for them (#1629).\n   */\n  USER_WITHOUT_AUTHORITY = 'user_without_authority',\n  /** An email recipient no route reaches: no reply token, client mailbox, verified organization domain or shared-domain slug matched it (#1600). */\n  EMAIL_ADDRESS_NOT_ROUTED = 'email_address_not_routed',\n  /** An email recipient on a claimed organization domain that is not VERIFIED — pending, failed or suspended (#1600, E3). */\n  EMAIL_DOMAIN_NOT_VERIFIED = 'email_domain_not_verified',\n  /**\n   * An email recipient on a client mailbox whose authority does not hold right now: the relationship is not ACTIVE,\n   * or the domain is not VERIFIED, or it is not the firm's (#1600, E4).\n   */\n  CLIENT_MAILBOX_NOT_AUTHORIZED = 'client_mailbox_not_authorized',\n  /** An email recipient on the shared domain whose slug belonged to a DELETED organization (#1600, L3). */\n  SHARED_DOMAIN_SLUG_TOMBSTONED = 'shared_domain_slug_tombstoned',\n}\n\n/** How the wait between a handler's failed attempts grows. */\nexport enum InboundRetryBackoffKind {\n  /** `baseSeconds × 2^(attempt−1)`, capped at `maxSeconds`. The default: a failing dependency gets room to recover. */\n  EXPONENTIAL = 'exponential',\n  /** `baseSeconds` every time. */\n  FIXED = 'fixed',\n}\n\n/** The outcome of one handler attempt, recorded on the row. */\nexport enum InboundDeliveryAttemptOutcome {\n  PROCESSED = 'processed',\n  FAILED = 'failed',\n}\n\n// =============================================================================\n// VERIFICATION CONFIGURATION (declared by an APPLICATION endpoint)\n// =============================================================================\n\nexport const InboundSvixVerificationConfigSchema = z.strictObject({\n  scheme: z.literal(InboundVerificationScheme.SVIX_V1).systemEnum('InboundVerificationScheme'),\n});\n\nexport const InboundHmacSha256HeaderVerificationConfigSchema = z.strictObject({\n  scheme: z.literal(InboundVerificationScheme.HMAC_SHA256_HEADER).systemEnum('InboundVerificationScheme'),\n  /** Header carrying the signature, e.g. `x-hub-signature-256`. Matched case-insensitively. */\n  signatureHeader: z.string().min(1),\n  encoding: z.enum(HmacSignatureEncoding).systemEnum('HmacSignatureEncoding'),\n  /**\n   * A literal the sender puts in front of the signature, e.g. `sha256=`. Stripped before comparison;\n   * a header that does not start with it is refused.\n   */\n  signaturePrefix: z.string().min(1).optional(),\n  /**\n   * Header carrying the send time in seconds since the epoch. When declared, the SIGNED content is\n   * `{timestamp}.{rawBody}` and the timestamp must fall within `toleranceSeconds` of now.\n   *\n   * A timestamp that is checked but not signed would be a control that does nothing: whoever\n   * replays a captured message rewrites the header too. So declaring one changes what is signed.\n   */\n  timestampHeader: z.string().min(1).optional(),\n  /** Window for `timestampHeader`, in seconds. Defaults to 300 (five minutes). */\n  toleranceSeconds: z.number().int().positive().max(3600).optional(),\n});\n\n/** The verification an APPLICATION endpoint declares. Discriminated on `scheme`. */\nexport const InboundVerificationConfigSchema = z.discriminatedUnion('scheme', [\n  InboundSvixVerificationConfigSchema,\n  InboundHmacSha256HeaderVerificationConfigSchema,\n]);\n\nexport type InboundVerificationConfig = z.infer<typeof InboundVerificationConfigSchema>;\n\n/** Engine default for an application endpoint's body cap: 256 KB. Per endpoint, never per route prefix. */\nexport const INBOUND_APPLICATION_ENDPOINT_DEFAULT_MAX_BODY_BYTES = 256 * 1024;\n\n/** The provider ref reserved for application endpoints: `/webhooks/app/{endpointKey}`. */\nexport const INBOUND_APPLICATION_ENDPOINT_PROVIDER_REF = 'app';\n\n// =============================================================================\n// STORED DELIVERY\n// =============================================================================\n\n/** The scope a stored delivery resolved to. Discriminated on `kind`; never absent. */\nexport const InboundDeliveryResolvedScopeSchema = z.discriminatedUnion('kind', [\n  z.strictObject({\n    kind: z\n      .literal(InboundResolvedScopeKind.ORGANIZATION)\n      .systemEnum('InboundResolvedScopeKind')\n      .describe('The delivery resolved to one organization and runs in that organization.'),\n    organizationId: z.string().min(1),\n  }),\n  z.strictObject({\n    kind: z\n      .literal(InboundResolvedScopeKind.APPLICATION)\n      .systemEnum('InboundResolvedScopeKind')\n      .describe('The delivery runs at application scope, with no organization.'),\n  }),\n  z.strictObject({\n    kind: z\n      .literal(InboundResolvedScopeKind.USER)\n      .systemEnum('InboundResolvedScopeKind')\n      .describe('The delivery belongs to one person and runs on that person\\'s own data, with the handler\\'s roles; nobody signed in as them.'),\n    userId: z.string().min(1).describe('The person the delivery belongs to.'),\n  }),\n  z.strictObject({\n    kind: z\n      .literal(InboundResolvedScopeKind.UNROUTABLE)\n      .systemEnum('InboundResolvedScopeKind')\n      .describe('No admissible scope was resolved, so the handler never runs this delivery.'),\n    reason: z\n      .enum(InboundDeliveryUnroutableReason)\n      .systemEnum('InboundDeliveryUnroutableReason')\n      .describe('Why no admissible scope was resolved.'),\n  }),\n]);\n\nexport type InboundDeliveryResolvedScope = z.infer<typeof InboundDeliveryResolvedScopeSchema>;\n\nexport const InboundDeliveryAttemptSchema = z.strictObject({\n  at: z.date().describe('When the attempt ended.'),\n  outcome: z\n    .enum(InboundDeliveryAttemptOutcome)\n    .systemEnum('InboundDeliveryAttemptOutcome')\n    .describe('Whether the handler completed (`processed`) or failed (`failed`) on this attempt.'),\n  /** A classified code, never the error message: a message can quote the payload. */\n  errorCode: z\n    .string()\n    .max(200)\n    .optional()\n    .describe(\n      'For a failed attempt, a classified error code — the error type and message reference joined by a colon, or the error name. Never the error message, which could quote the payload. At most 200 characters.',\n    ),\n});\n\nexport type InboundDeliveryAttempt = z.infer<typeof InboundDeliveryAttemptSchema>;\n\nexport const InboundDeliveryReplaySchema = z.strictObject({\n  /** The user who replayed the delivery. */\n  by: z.string().min(1).describe('The id of the user who replayed the delivery.'),\n  at: z.date().describe('When the delivery was replayed.'),\n  justification: z.string().min(1).max(2000).describe('Why the delivery was replayed, as written by that user. Also recorded on the audit trail.'),\n});\n\nexport type InboundDeliveryReplay = z.infer<typeof InboundDeliveryReplaySchema>;\n\nconst INBOUND_DELIVERY_SCOPE_VARIANTS: PolymorphicVariantDefinition[] = [\n  {\n    parentResourceType: CoreResourceType.ORGANIZATIONS,\n    parentFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.ORGANIZATIONS],\n    isPrimaryScope: true,\n  },\n  {\n    parentResourceType: CoreResourceType.APPLICATION,\n    parentFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.APPLICATION],\n    isPrimaryScope: true,\n  },\n];\n\n/**\n * One stored delivery. Written by the pipeline only (CREATE and UPDATE are REPOSITORY_ONLY); an\n * administrator reads it and may REPLAY a `DEAD` one.\n */\nexport const InboundDeliveryBaseSchema = z.object({\n  _id: z.string().min(1).isPrimaryKey().isSummaryField(),\n\n  sourceKind: z.enum(InboundSourceKind).systemEnum('InboundSourceKind').isSummaryField(),\n  /**\n   * The source's stable identity: `{providerRef}:{endpointKey}`, with `app` as the provider ref of an\n   * application endpoint. Half of the dedup key.\n   */\n  sourceKey: z.string().min(1).isDBIndexed().isSummaryField(),\n  /** The handler that owns the delivery — the `ref` it was declared with. */\n  handlerRef: z.string().min(1).isDBIndexed().isSummaryField(),\n  /**\n   * The provider's delivery id (`svix-id`, Stripe's event id), or the handler's `dedupKey`. The other\n   * half of the unique key: one event, one run.\n   */\n  dedupKey: z.string().min(1).max(512).isSummaryField(),\n  /** Deliveries sharing a non-null ordering key run one at a time, in receive order. */\n  orderingKey: z.string().min(1).max(512).isDBIndexed().nullable().default(null),\n  /** The id the provider signed, when its scheme carries one. */\n  providerDeliveryId: z.string().max(512).optional(),\n  /** When the provider says it signed the message, when the scheme carries a timestamp. */\n  signedAt: z.date().optional(),\n  receivedAt: z.date().isDBIndexed().isSummaryField(),\n\n  /**\n   * The exact bytes that were verified, base64-encoded. Kept because a replay must run the handler on\n   * what was actually signed, not on a re-serialization of it. USER_CONTENT: a delivery carries\n   * whatever the sending system put in it, which is routinely a client's personal data.\n   */\n  rawBody: addDataCategories(z.string(), PersonalDataCategory.USER_CONTENT),\n  /** Only the headers the verification scheme and the handler need; never cookies or authorization. */\n  headers: z.record(z.string(), z.string()).default({}),\n\n  resolvedScope: InboundDeliveryResolvedScopeSchema,\n\n  /**\n   * The channel the delivery arrived on (#1630). `WEBHOOK` for every endpoint delivery (#1596) — derived,\n   * never declared — and the default, which is EXACT for every row stored before channels existed: only\n   * signed endpoint deliveries were ever stored.\n   */\n  channel: z.enum(InboundChannelKind).systemEnum('InboundChannelKind').default(InboundChannelKind.WEBHOOK).isSummaryField()\n    .describe('The channel the delivery arrived on: a signed webhook, or a received email.'),\n  /**\n   * How much is known about who sent it, on the channel's own ladder. `SOURCE_SIGNED` for a webhook — a\n   * delivery is stored only after its signature verified — and the default for the same reason as above.\n   * Identification only: it grants the handler nothing.\n   */\n  senderAssurance: z.enum(InboundSenderAssurance).systemEnum('InboundSenderAssurance').default(InboundSenderAssurance.SOURCE_SIGNED)\n    .describe('How much is known about who sent the message, on its channel\\'s own ladder. It identifies the sender and grants the handler nothing.'),\n  /** The conversation thread a channel delivery was correlated into; null for a webhook. */\n  threadId: z.string().isDBIndexed().nullable().default(null)\n    .describe('The conversation thread the message was recorded in; null for a webhook delivery.'),\n\n  status: z\n    .enum(InboundDeliveryStatus)\n    .systemEnum('InboundDeliveryStatus')\n    .default(InboundDeliveryStatus.RECEIVED)\n    .isDBIndexed()\n    .isSummaryField(),\n  /**\n   * Attempts started, ever. Incremented by every lease, so it is also the FENCING token: a worker\n   * whose lease expired and was taken over can no longer settle the row, because the takeover moved\n   * the count. Never reset — a replay starts a new budget instead (see `budgetBaseAttemptCount`).\n   */\n  attemptCount: z.number().int().nonnegative().default(0).isSummaryField(),\n  /** The attempts' outcomes, oldest first. */\n  attempts: z.array(InboundDeliveryAttemptSchema).default([]),\n  /** When the next attempt may start; set while `RECEIVED` or `RETRY_SCHEDULED`. */\n  nextAttemptAt: z.date().isDBIndexed().nullable().default(null),\n  /** While `PROCESSING`: when a worker that stopped answering loses the row to the sweep. */\n  leaseExpiresAt: z.date().isDBIndexed().nullable().default(null),\n  /**\n   * The start of the current retry budget: receipt, or the last replay. The handler's retry window\n   * is measured from here, so a replay after the handler is fixed gets a whole policy again.\n   */\n  budgetStartedAt: z.date(),\n  /** `attemptCount` when the current budget started; attempts in the budget are the difference. */\n  budgetBaseAttemptCount: z.number().int().nonnegative().default(0),\n  /** Set when the row reached a terminal status — the retention clock's start point. */\n  /*\n   * `.isDBIndexed()` sits on the INNER type on these four nullable-with-default fields. That placement\n   * was required until #1647: behind two wrappers a decorator used to stop on the middle wrapper, and the\n   * PostgreSQL planner reads the innermost type, so the index was silently not planned (#1644). Mirroring\n   * now reaches the leaf either way; the placement is kept because it states the index on the type indexed.\n   */\n  terminalAt: z.date().isDBIndexed().nullable().default(null),\n  replays: z.array(InboundDeliveryReplaySchema).default([]),\n\n  createdAt: z\n    .date()\n    .default(() => new Date())\n    .isDBIndexed()\n    .excludeFromCreate()\n    .excludeFromUpdate(),\n  updatedAt: z\n    .date()\n    .default(() => new Date())\n    .excludeFromCreate()\n    .excludeFromUpdate(),\n}).businessKeySet(['sourceKey', 'dedupKey']);\n\nexport type InboundDeliveryBase = z.infer<typeof InboundDeliveryBaseSchema>;\n\n/**\n * Yields `organizationInboundDeliveries` (FK `organizationId`) and `applicationInboundDeliveries`\n * (FK `applicationId`). Many rows per scope, so the singleton business-key default is opted out of;\n * the row's identity is the `(sourceKey, dedupKey)` set above.\n */\nexport const inboundDeliveryPolymorphicDeclaration = declarePolymorphicSchemas({\n  baseResourceType: 'inboundDeliveries',\n  baseFieldIdentifier: 'inboundDeliveryId',\n  baseEnumKey: 'INBOUND_DELIVERIES',\n  baseSchema: InboundDeliveryBaseSchema,\n  variants: INBOUND_DELIVERY_SCOPE_VARIANTS.map(optOutPolymorphicAutoBusinessKey),\n});\n"]}

package/dist/esm/inbound/inbound-endpoint-env.shared.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `WILDO_INBOUND_<ENDPOINT_KEY>__SECRET` — the ONE derivation of the environment variable that holds an
+ * application inbound endpoint's verification secret (#1596).
+ *
+ * ## Derived from the endpoint key, never authored
+ *
+ * An application endpoint is `POST /webhooks/app/{endpointKey}`, and its secret is a function of that key.
+ * The first cut let each handler name its own variable (`secretEnvVar`), which left three readers with no
+ * shared answer: the backend reading the secret, the CLI writing it into the backend's environment, and the
+ * CLI keeping it OUT of every other runtime. A variable an author names freely cannot be recognised by the
+ * last of those, so a minion would inherit a webhook signing secret it has no use for. Deriving the name is
+ * the same trade `WILDO_SOR_<NAME>__<SLOT>` makes for systems of record, and for the same reason: one
+ * function owns the spelling and every layer imports it.
+ *
+ * ## Why the name round-trips
+ *
+ * The secrets section is a flat map keyed by variable name, so the endpoint key must be recoverable from the
+ * name. An endpoint key admits only lower-case letters, digits and SINGLE hyphens
+ * ({@link INBOUND_ENDPOINT_KEY_PATTERN}), so `-` → `_` is injective and the key can never produce `__`. The
+ * only `__` in a derived name is therefore the delimiter before `SECRET`, by construction.
+ */
+/** Every inbound endpoint variable starts here, which is what makes a prefix scan possible. */
+export declare const INBOUND_ENDPOINT_ENV_PREFIX = "WILDO_INBOUND_";
+/** The suffix naming the slot. One slot today; the delimiter keeps room for another without ambiguity. */
+export declare const INBOUND_ENDPOINT_SECRET_ENV_SUFFIX = "__SECRET";
+/**
+ * The charset law for an application endpoint key: lower-case letters and digits, joined by single hyphens.
+ * Load-bearing for the round trip above, so it is shared with the handler registry rather than restated there.
+ */
+export declare const INBOUND_ENDPOINT_KEY_PATTERN: RegExp;
+/**
+ * The environment variable carrying the verification secret of the application endpoint `endpointKey`.
+ * Throws on a key outside {@link INBOUND_ENDPOINT_KEY_PATTERN}: the handler registry refuses such a key at
+ * startup, so reaching here with one means a caller skipped it, and an unparseable name is worse than a
+ * loud refusal.
+ */
+export declare function deriveInboundEndpointSecretEnvVarName(endpointKey: string): string;
+/**
+ * Recover the endpoint key from a derived variable name, or `null` when the name is not one of ours.
+ * `null` rather than a throw because the callers scan a MIXED environment, where most names are not
+ * inbound endpoint variables.
+ */
+export declare function parseInboundEndpointSecretEnvVarName(envVarName: string): {
+    readonly endpointKey: string;
+} | null;
+//# sourceMappingURL=inbound-endpoint-env.shared.d.ts.map

package/dist/esm/inbound/inbound-endpoint-env.shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbound-endpoint-env.shared.d.ts","sourceRoot":"","sources":["../../../../src/inbound/inbound-endpoint-env.shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,+FAA+F;AAC/F,eAAO,MAAM,2BAA2B,mBAAmB,CAAC;AAE5D,0GAA0G;AAC1G,eAAO,MAAM,kCAAkC,aAAa,CAAC;AAE7D;;;GAGG;AACH,eAAO,MAAM,4BAA4B,QAA+B,CAAC;AAEzE;;;;;GAKG;AACH,wBAAgB,qCAAqC,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAKjF;AAED;;;;GAIG;AACH,wBAAgB,oCAAoC,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAMhH"}

package/dist/esm/inbound/inbound-endpoint-env.shared.js

@@ -0,0 +1,57 @@
+/**
+ * `WILDO_INBOUND_<ENDPOINT_KEY>__SECRET` — the ONE derivation of the environment variable that holds an
+ * application inbound endpoint's verification secret (#1596).
+ *
+ * ## Derived from the endpoint key, never authored
+ *
+ * An application endpoint is `POST /webhooks/app/{endpointKey}`, and its secret is a function of that key.
+ * The first cut let each handler name its own variable (`secretEnvVar`), which left three readers with no
+ * shared answer: the backend reading the secret, the CLI writing it into the backend's environment, and the
+ * CLI keeping it OUT of every other runtime. A variable an author names freely cannot be recognised by the
+ * last of those, so a minion would inherit a webhook signing secret it has no use for. Deriving the name is
+ * the same trade `WILDO_SOR_<NAME>__<SLOT>` makes for systems of record, and for the same reason: one
+ * function owns the spelling and every layer imports it.
+ *
+ * ## Why the name round-trips
+ *
+ * The secrets section is a flat map keyed by variable name, so the endpoint key must be recoverable from the
+ * name. An endpoint key admits only lower-case letters, digits and SINGLE hyphens
+ * ({@link INBOUND_ENDPOINT_KEY_PATTERN}), so `-` → `_` is injective and the key can never produce `__`. The
+ * only `__` in a derived name is therefore the delimiter before `SECRET`, by construction.
+ */
+/** Every inbound endpoint variable starts here, which is what makes a prefix scan possible. */
+export const INBOUND_ENDPOINT_ENV_PREFIX = 'WILDO_INBOUND_';
+/** The suffix naming the slot. One slot today; the delimiter keeps room for another without ambiguity. */
+export const INBOUND_ENDPOINT_SECRET_ENV_SUFFIX = '__SECRET';
+/**
+ * The charset law for an application endpoint key: lower-case letters and digits, joined by single hyphens.
+ * Load-bearing for the round trip above, so it is shared with the handler registry rather than restated there.
+ */
+export const INBOUND_ENDPOINT_KEY_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/**
+ * The environment variable carrying the verification secret of the application endpoint `endpointKey`.
+ * Throws on a key outside {@link INBOUND_ENDPOINT_KEY_PATTERN}: the handler registry refuses such a key at
+ * startup, so reaching here with one means a caller skipped it, and an unparseable name is worse than a
+ * loud refusal.
+ */
+export function deriveInboundEndpointSecretEnvVarName(endpointKey) {
+    if (!INBOUND_ENDPOINT_KEY_PATTERN.test(endpointKey)) {
+        throw new Error(`"${endpointKey}" is not a valid inbound endpoint key (lower-case letters and digits, joined by single hyphens).`);
+    }
+    return `${INBOUND_ENDPOINT_ENV_PREFIX}${endpointKey.toUpperCase().replaceAll('-', '_')}${INBOUND_ENDPOINT_SECRET_ENV_SUFFIX}`;
+}
+/**
+ * Recover the endpoint key from a derived variable name, or `null` when the name is not one of ours.
+ * `null` rather than a throw because the callers scan a MIXED environment, where most names are not
+ * inbound endpoint variables.
+ */
+export function parseInboundEndpointSecretEnvVarName(envVarName) {
+    if (!envVarName.startsWith(INBOUND_ENDPOINT_ENV_PREFIX) || !envVarName.endsWith(INBOUND_ENDPOINT_SECRET_ENV_SUFFIX))
+        return null;
+    const encoded = envVarName.slice(INBOUND_ENDPOINT_ENV_PREFIX.length, envVarName.length - INBOUND_ENDPOINT_SECRET_ENV_SUFFIX.length);
+    const endpointKey = encoded.toLowerCase().replaceAll('_', '-');
+    if (!INBOUND_ENDPOINT_KEY_PATTERN.test(endpointKey) || encoded !== encoded.toUpperCase())
+        return null;
+    return { endpointKey };
+}
+//# sourceMappingURL=inbound-endpoint-env.shared.js.map