@iveri/contracts 0.5.0 → 0.6.0

package/dist/cjs/api/conduit/connection.type.d.ts

@@ -0,0 +1,100 @@
+import type { IsoDateTime } from '../../type/iso-date-time.type.js';
+import type { Nullable } from '../../type/nil.type.js';
+import type { UUID } from '../../type/uuid.type.js';
+/**
+ * One tenant's configured instance of a connector: the credentials and the account details that
+ * turn a manifest into something that can actually send.
+ *
+ * The split is the reason a manifest can ship in the binary. A connector says "WhatsApp Cloud
+ * lives at graph.facebook.com and authenticates with a bearer token"; a connection says "and
+ * *this* is our token, for *this* phone number". One is ours and identical for everybody; the
+ * other is the customer's and is the single most sensitive thing this service holds.
+ *
+ * **No endpoint of this API returns a credential value**, in any form — not masked, not
+ * truncated, not a length. `credentialNames` answers the only question an operator has, which is
+ * whether something is configured. Same control as a destination's headers and an endpoint's
+ * signing secret, for the same reason: §11 says one leak ends the company.
+ */
+export interface Connection {
+    id: UUID;
+    /** Stable identifier a dispatch names instead of an id, so callers can be configured by name. */
+    key: string;
+    name: string;
+    description: Nullable<string>;
+    /** The manifest this connection instantiates. Built-in or tenant-defined. */
+    connectorKey: string;
+    /** Sorted. **The values are never returned by any endpoint of this API.** */
+    credentialNames: string[];
+    /**
+     * Non-secret values filling `{placeholders}` in an operation path — a phone number id, an
+     * account id, an API version.
+     *
+     * Deliberately separate from credentials rather than one map with a secrecy flag: a flag is
+     * a thing somebody sets wrong once, and the failure mode is a token in a response body.
+     * Variables are returned in full because they are the part an operator needs to check.
+     */
+    variables: Record<string, string>;
+    /**
+     * When the cached OAuth access token stops being usable, or null when there is none —
+     * either because the connector authenticates statically or because nothing has fetched one
+     * yet.
+     *
+     * The expiry is returned, the token is not. It is what makes "why is this connection
+     * failing" answerable without exposing anything.
+     */
+    accessTokenExpiresAt: Nullable<IsoDateTime>;
+    /**
+     * Why the last authentication attempt failed, or null when the last one worked.
+     *
+     * A refresh token that a provider has revoked is the most common real failure on this
+     * aggregate, and it is invisible otherwise: dispatches simply dead-letter with a 401 and
+     * nothing points at the connection.
+     */
+    lastAuthError: Nullable<string>;
+    /** Stops *new* dispatches being accepted. Does not cancel ones already queued. */
+    isActive: boolean;
+    createdAt: IsoDateTime;
+    updatedAt: IsoDateTime;
+}
+/** `GET /api/v1/connections`. Offset-paginated — a small, slow-moving collection. */
+export interface ConnectionsPage {
+    items: Connection[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+/** `POST /api/v1/connections`. */
+export interface CreateConnectionBody {
+    key: string;
+    name: string;
+    description?: Nullable<string>;
+    connectorKey: string;
+    /**
+     * Secrets this connection authenticates with. **Stored encrypted and never returned.**
+     *
+     * Which names are expected depends on the connector's auth type: an `API_KEY_HEADER`
+     * manifest names its own, an OAuth one wants `clientId`/`clientSecret` and, for the refresh
+     * grant, `refreshToken`.
+     */
+    credentials: Record<string, string>;
+    variables?: Nullable<Record<string, string>>;
+}
+/**
+ * `PATCH /api/v1/connections/:id`.
+ *
+ * **`credentials` has three states, not two.** Omitting it leaves the stored map untouched,
+ * `null` clears it, an object replaces it wholesale. A form that sends `{}` meaning "unchanged"
+ * deletes the customer's token, and the symptom is every dispatch dead-lettering on a 401.
+ *
+ * Replacing credentials also discards the cached access token: a token minted from the old
+ * client secret is not evidence that the new one works, and keeping it would hide a typo until
+ * the token happened to expire.
+ */
+export interface UpdateConnectionBody {
+    name?: string;
+    description?: Nullable<string>;
+    credentials?: Nullable<Record<string, string>>;
+    variables?: Nullable<Record<string, string>>;
+    isActive?: boolean;
+}
+//# sourceMappingURL=connection.type.d.ts.map

package/dist/cjs/api/conduit/connection.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.type.d.ts","sourceRoot":"","sources":["../../../../src/api/conduit/connection.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAEpD;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,UAAU;IACvB,EAAE,EAAE,IAAI,CAAC;IAET,iGAAiG;IACjG,GAAG,EAAE,MAAM,CAAC;IAEZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE9B,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAC;IAErB,6EAA6E;IAC7E,eAAe,EAAE,MAAM,EAAE,CAAC;IAE1B;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAElC;;;;;;;OAOG;IACH,oBAAoB,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IAE5C;;;;;;OAMG;IACH,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAEhC,kFAAkF;IAClF,QAAQ,EAAE,OAAO,CAAC;IAElB,SAAS,EAAE,WAAW,CAAC;IACvB,SAAS,EAAE,WAAW,CAAC;CAC1B;AAED,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC5B,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAClB;AAED,kCAAkC;AAClC,MAAM,WAAW,oBAAoB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;IAErB;;;;;;OAMG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEpC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAChD;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,oBAAoB;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC/C,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC7C,QAAQ,CAAC,EAAE,OAAO,CAAC;CACtB"}

package/dist/cjs/api/conduit/connection.type.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=connection.type.js.map

package/dist/cjs/api/conduit/connection.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.type.js","sourceRoot":"","sources":["../../../../src/api/conduit/connection.type.ts"],"names":[],"mappings":""}

package/dist/cjs/api/conduit/connector-auth-type.enum.d.ts

@@ -0,0 +1,42 @@
+/**
+ * How a connector proves who we are to the third-party API it fronts.
+ *
+ * This is the field that decides whether Conduit has to hold a *renewable* credential or merely
+ * a static one, and the two are very different operationally: a static key works until someone
+ * rotates it, an OAuth token stops working on a schedule and something has to notice first.
+ *
+ * The list is deliberately short. Every member is a scheme a manifest can describe entirely as
+ * data — adding a provider that uses one of these is a manifest and a credential, never a code
+ * change, which is the whole promise of §11's connector manifest. A provider needing anything
+ * else (a request-signing scheme, mutual TLS) does not get a special case bolted on here; it
+ * gets a new member, designed once, with the same "no per-provider branches" rule applied to it.
+ */
+export declare enum ConnectorAuthType {
+    /** The API is open, or the credential travels in the payload. Nothing is added to a request. */
+    NONE = "none",
+    /**
+     * A static secret sent in a header — `X-Api-Key: …`, `Authorization: Basic …`.
+     *
+     * The header name and any literal prefix come from the manifest; only the secret comes from
+     * the connection. That split is what lets one manifest serve every tenant.
+     */
+    API_KEY_HEADER = "api-key-header",
+    /** A static bearer token. Shorthand for {@link API_KEY_HEADER} with the header and prefix fixed. */
+    BEARER_STATIC = "bearer-static",
+    /**
+     * OAuth 2.0 client credentials (RFC 6749 §4.4): exchange a client id and secret for a
+     * short-lived access token, and do it again when it expires. Machine-to-machine, no user.
+     */
+    OAUTH2_CLIENT_CREDENTIALS = "oauth2-client-credentials",
+    /**
+     * OAuth 2.0 refresh token (RFC 6749 §6): a long-lived refresh token buys short-lived access
+     * tokens.
+     *
+     * **The refresh token may be rotated by the provider on every use**, and Conduit stores
+     * whichever one came back last. That single fact is why refreshing has to be serialised
+     * across replicas rather than left to race — two simultaneous refreshes rotate twice, one
+     * of the two results is stored, and the connection is dead until a human re-authorises it.
+     */
+    OAUTH2_REFRESH_TOKEN = "oauth2-refresh-token"
+}
+//# sourceMappingURL=connector-auth-type.enum.d.ts.map

package/dist/cjs/api/conduit/connector-auth-type.enum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector-auth-type.enum.d.ts","sourceRoot":"","sources":["../../../../src/api/conduit/connector-auth-type.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,oBAAY,iBAAiB;IACzB,gGAAgG;IAChG,IAAI,SAAS;IAEb;;;;;OAKG;IACH,cAAc,mBAAmB;IAEjC,oGAAoG;IACpG,aAAa,kBAAkB;IAE/B;;;OAGG;IACH,yBAAyB,8BAA8B;IAEvD;;;;;;;;OAQG;IACH,oBAAoB,yBAAyB;CAChD"}

package/dist/cjs/api/conduit/connector-auth-type.enum.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectorAuthType = void 0;
+/**
+ * How a connector proves who we are to the third-party API it fronts.
+ *
+ * This is the field that decides whether Conduit has to hold a *renewable* credential or merely
+ * a static one, and the two are very different operationally: a static key works until someone
+ * rotates it, an OAuth token stops working on a schedule and something has to notice first.
+ *
+ * The list is deliberately short. Every member is a scheme a manifest can describe entirely as
+ * data — adding a provider that uses one of these is a manifest and a credential, never a code
+ * change, which is the whole promise of §11's connector manifest. A provider needing anything
+ * else (a request-signing scheme, mutual TLS) does not get a special case bolted on here; it
+ * gets a new member, designed once, with the same "no per-provider branches" rule applied to it.
+ */
+var ConnectorAuthType;
+(function (ConnectorAuthType) {
+    /** The API is open, or the credential travels in the payload. Nothing is added to a request. */
+    ConnectorAuthType["NONE"] = "none";
+    /**
+     * A static secret sent in a header — `X-Api-Key: …`, `Authorization: Basic …`.
+     *
+     * The header name and any literal prefix come from the manifest; only the secret comes from
+     * the connection. That split is what lets one manifest serve every tenant.
+     */
+    ConnectorAuthType["API_KEY_HEADER"] = "api-key-header";
+    /** A static bearer token. Shorthand for {@link API_KEY_HEADER} with the header and prefix fixed. */
+    ConnectorAuthType["BEARER_STATIC"] = "bearer-static";
+    /**
+     * OAuth 2.0 client credentials (RFC 6749 §4.4): exchange a client id and secret for a
+     * short-lived access token, and do it again when it expires. Machine-to-machine, no user.
+     */
+    ConnectorAuthType["OAUTH2_CLIENT_CREDENTIALS"] = "oauth2-client-credentials";
+    /**
+     * OAuth 2.0 refresh token (RFC 6749 §6): a long-lived refresh token buys short-lived access
+     * tokens.
+     *
+     * **The refresh token may be rotated by the provider on every use**, and Conduit stores
+     * whichever one came back last. That single fact is why refreshing has to be serialised
+     * across replicas rather than left to race — two simultaneous refreshes rotate twice, one
+     * of the two results is stored, and the connection is dead until a human re-authorises it.
+     */
+    ConnectorAuthType["OAUTH2_REFRESH_TOKEN"] = "oauth2-refresh-token";
+})(ConnectorAuthType || (exports.ConnectorAuthType = ConnectorAuthType = {}));
+//# sourceMappingURL=connector-auth-type.enum.js.map

package/dist/cjs/api/conduit/connector-auth-type.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector-auth-type.enum.js","sourceRoot":"","sources":["../../../../src/api/conduit/connector-auth-type.enum.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;GAYG;AACH,IAAY,iBA+BX;AA/BD,WAAY,iBAAiB;IACzB,gGAAgG;IAChG,kCAAa,CAAA;IAEb;;;;;OAKG;IACH,sDAAiC,CAAA;IAEjC,oGAAoG;IACpG,oDAA+B,CAAA;IAE/B;;;OAGG;IACH,4EAAuD,CAAA;IAEvD;;;;;;;;OAQG;IACH,kEAA6C,CAAA;AACjD,CAAC,EA/BW,iBAAiB,iCAAjB,iBAAiB,QA+B5B"}

package/dist/cjs/api/conduit/connector.type.d.ts

@@ -0,0 +1,179 @@
+import type { IsoDateTime } from '../../type/iso-date-time.type.js';
+import type { Nullable } from '../../type/nil.type.js';
+import type { UUID } from '../../type/uuid.type.js';
+import type { ConnectorAuthType } from './connector-auth-type.enum.js';
+/**
+ * Credential names an OAuth manifest expects to find on a connection.
+ *
+ * Fixed rather than manifest-configurable: these are the field names RFC 6749 gives the token
+ * request, so letting a manifest rename them would only allow it to be wrong.
+ */
+export declare const CONNECTOR_CREDENTIAL_CLIENT_ID = "clientId";
+export declare const CONNECTOR_CREDENTIAL_CLIENT_SECRET = "clientSecret";
+export declare const CONNECTOR_CREDENTIAL_REFRESH_TOKEN = "refreshToken";
+/**
+ * How a connector authenticates, as data.
+ *
+ * Flat with a discriminating {@link ConnectorAuthType} and nullable fields, matching
+ * `SignatureManifest` — a discriminated union reads better in TypeScript and validates far worse
+ * as a request body, and this shape has to survive `class-validator` on the way in.
+ *
+ * **A manifest holds no secret.** It names *where* the credential goes; the credential itself
+ * lives on a connection, encrypted. That is what makes a manifest safe to return in full to
+ * anyone with `conduit:connector:read` and safe to ship in the binary.
+ */
+export interface ConnectorAuthManifest {
+    type: ConnectorAuthType;
+    /**
+     * Which credential on the connection holds the secret. `API_KEY_HEADER` only.
+     *
+     * OAuth manifests do not set it — they read the fixed names above, because those are defined
+     * by the grant rather than by us.
+     */
+    credentialKey: Nullable<string>;
+    /** Lowercase header the credential is sent in. `API_KEY_HEADER` only. */
+    headerName: Nullable<string>;
+    /** Literal text before the credential, e.g. `Bearer ` or `Basic `. Kept verbatim, spaces included. */
+    valuePrefix: Nullable<string>;
+    /** Token endpoint. `OAUTH2_*` only. Vetted against the SSRF blocklist like any other target. */
+    tokenUrl: Nullable<string>;
+    /** `scope` sent with the token request, when the provider wants one. */
+    scope: Nullable<string>;
+    /**
+     * Seconds shaved off a token's reported lifetime before it counts as expired.
+     *
+     * Not a nicety. A token that expires while a request is in flight fails with a 401 that looks
+     * exactly like a revoked credential, and the retry that would fix it is indistinguishable
+     * from one that never will. Refreshing slightly early makes that case rare instead of
+     * routine. Null falls back to the service default.
+     */
+    expirySkewSeconds: Nullable<number>;
+}
+/** {@link ConnectorAuthManifest} as sent on create/update: nullable fields may simply be omitted. */
+export interface ConnectorAuthManifestInput {
+    type: ConnectorAuthType;
+    credentialKey?: Nullable<string>;
+    headerName?: Nullable<string>;
+    valuePrefix?: Nullable<string>;
+    tokenUrl?: Nullable<string>;
+    scope?: Nullable<string>;
+    expirySkewSeconds?: Nullable<number>;
+}
+/**
+ * One thing a connector can be asked to do.
+ *
+ * A dispatch names an operation by {@link key} rather than supplying a URL, and that is the
+ * whole security model of the outbound side: a caller chooses from a list somebody with
+ * `conduit:connector:manage` wrote down, instead of naming a host Conduit will then post to.
+ * Outbound would otherwise be an open proxy with authentication attached.
+ */
+export interface ConnectorOperation {
+    /** Stable identifier a dispatch names. Lowercase kebab-case: `send-message`. */
+    key: string;
+    /** Human-readable label for the admin UI. */
+    name: string;
+    method: string;
+    /**
+     * Path appended to the connector's `baseUrl`.
+     *
+     * `{name}` placeholders are filled from the connection's variables first and the dispatch's
+     * `pathParams` second. Every placeholder must resolve, or the dispatch is refused at submit
+     * time rather than dead-lettering later — the caller is still on the phone at submit time.
+     */
+    path: string;
+    description: Nullable<string>;
+}
+/** Requests per minute, and how many may arrive at once. Applied per connection. */
+export interface ConnectorRateLimit {
+    perMinute: number;
+    burst: number;
+}
+/**
+ * When to try again, and when to stop.
+ *
+ * Per connector rather than global because providers genuinely differ: one returns 429 with a
+ * generous window, another treats a burst as abuse and blocks for an hour.
+ */
+export interface ConnectorRetryPolicy {
+    maxAttempts: number;
+    backoffBaseMs: number;
+    backoffMaxMs: number;
+    /**
+     * Statuses to retry **in addition** to the transient default set (5xx, 408, 425, 429).
+     *
+     * Additive, never subtractive: a manifest can say "this provider's 400 is transient", which
+     * is a fact about that provider, but it cannot claim a 502 is permanent — nothing about a
+     * gateway error is provider-specific and the ability to get it wrong buys nothing.
+     */
+    retryableStatuses: number[];
+    /**
+     * Statuses meaning the access token is stale.
+     *
+     * Handled once per attempt and unlike any other status: the token is discarded, refreshed,
+     * and the request is sent again immediately rather than after a backoff. A token that
+     * expired thirty seconds early is not a failing destination and should not be treated as one.
+     */
+    authFailureStatuses: number[];
+}
+/**
+ * A third-party API, described entirely as data. §11's "connector manifest".
+ *
+ * Conduit contains no `if (connector === 'whatsapp')` anywhere. Adding TikTok is a manifest and
+ * a credential; the code that sends the request never learns a provider's name.
+ */
+export interface Connector {
+    /** Null for a built-in — it is not a row and cannot be edited or deleted. */
+    id: Nullable<UUID>;
+    /** Stable identifier a connection references. Lowercase kebab-case. */
+    key: string;
+    name: string;
+    description: Nullable<string>;
+    /** Absolute https base every operation path is appended to. */
+    baseUrl: string;
+    auth: ConnectorAuthManifest;
+    operations: ConnectorOperation[];
+    /** Null means only the service-wide default applies. */
+    rateLimit: Nullable<ConnectorRateLimit>;
+    retry: ConnectorRetryPolicy;
+    /**
+     * Ships with Conduit, in code rather than as a seeded row. Override it by defining your own
+     * under the same key — resolution checks a tenant's rows first.
+     */
+    isBuiltIn: boolean;
+    /** Null for a built-in. */
+    createdAt: Nullable<IsoDateTime>;
+    /** Null for a built-in. */
+    updatedAt: Nullable<IsoDateTime>;
+}
+/** Built-ins plus whatever one customer has defined. `GET /api/v1/connectors`. */
+export interface ConnectorsList {
+    items: Connector[];
+}
+/** `POST /api/v1/connectors`. */
+export interface CreateConnectorBody {
+    key: string;
+    name: string;
+    description?: Nullable<string>;
+    baseUrl: string;
+    auth: ConnectorAuthManifestInput;
+    operations: ConnectorOperation[];
+    rateLimit?: Nullable<ConnectorRateLimit>;
+    retry?: Nullable<ConnectorRetryPolicy>;
+}
+/**
+ * `PATCH /api/v1/connectors/:id`.
+ *
+ * `operations` replaces the list wholesale — there is no per-operation patch. Merging would make
+ * "remove an operation" unexpressible, and an operation nobody can remove is a URL Conduit will
+ * post to forever.
+ */
+export interface UpdateConnectorBody {
+    name?: string;
+    description?: Nullable<string>;
+    baseUrl?: string;
+    auth?: ConnectorAuthManifestInput;
+    operations?: ConnectorOperation[];
+    rateLimit?: Nullable<ConnectorRateLimit>;
+    retry?: Nullable<ConnectorRetryPolicy>;
+}
+//# sourceMappingURL=connector.type.d.ts.map

package/dist/cjs/api/conduit/connector.type.d.ts.map

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

package/dist/cjs/api/conduit/connector.type.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONNECTOR_CREDENTIAL_REFRESH_TOKEN = exports.CONNECTOR_CREDENTIAL_CLIENT_SECRET = exports.CONNECTOR_CREDENTIAL_CLIENT_ID = void 0;
+/**
+ * Credential names an OAuth manifest expects to find on a connection.
+ *
+ * Fixed rather than manifest-configurable: these are the field names RFC 6749 gives the token
+ * request, so letting a manifest rename them would only allow it to be wrong.
+ */
+exports.CONNECTOR_CREDENTIAL_CLIENT_ID = 'clientId';
+exports.CONNECTOR_CREDENTIAL_CLIENT_SECRET = 'clientSecret';
+exports.CONNECTOR_CREDENTIAL_REFRESH_TOKEN = 'refreshToken';
+//# sourceMappingURL=connector.type.js.map

package/dist/cjs/api/conduit/connector.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector.type.js","sourceRoot":"","sources":["../../../../src/api/conduit/connector.type.ts"],"names":[],"mappings":";;;AAMA;;;;;GAKG;AACU,QAAA,8BAA8B,GAAG,UAAU,CAAC;AAC5C,QAAA,kCAAkC,GAAG,cAAc,CAAC;AACpD,QAAA,kCAAkC,GAAG,cAAc,CAAC"}

package/dist/cjs/api/conduit/dispatch-status.enum.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Where one outbound dispatch is in its life.
+ *
+ * The members mirror `DeliveryStatus` exactly, and this is deliberately **not** the same enum.
+ * The two are separate wire contracts on separate resources, and sharing one would mean a state
+ * added for the inbound queue silently appears on the outbound one's documented API — a
+ * connector-specific state has no business showing up on a webhook delivery, and vice versa.
+ * Being identical today is not a reason to make them the same type; it is just what happens when
+ * two queues share a state machine.
+ *
+ * There is no `RATE_LIMITED` member on purpose. A dispatch held back by a connector's rate limit
+ * is simply `PENDING` with a later `nextAttemptAt`, because that is exactly what it is — waiting
+ * for its next attempt time, no differently from one waiting out a backoff. A separate state
+ * would suggest an operator has something to do about it.
+ */
+export declare enum DispatchStatus {
+    /** Waiting for its next attempt time. The only state the processor claims from. */
+    PENDING = "pending",
+    /**
+     * Claimed by a replica and being attempted right now.
+     *
+     * A row stuck here past the claim timeout is assumed abandoned and reclaimed — and on this
+     * side that reclaim is genuinely dangerous, because the request may have already reached the
+     * provider. It is why every dispatch carries an idempotency key onward and why a caller must
+     * treat outbound as at-least-once too.
+     */
+    IN_FLIGHT = "in-flight",
+    /** The provider accepted it. Terminal. */
+    DELIVERED = "delivered",
+    /**
+     * Every attempt was used and none succeeded, or the failure was permanent. Terminal until an
+     * operator redrives it.
+     *
+     * **This is the dead-letter queue** — a status, not a separate resource.
+     */
+    DEAD_LETTERED = "dead-lettered",
+    /** An operator stopped it before it was sent. Terminal, and distinct from a failure. */
+    CANCELLED = "cancelled"
+}
+//# sourceMappingURL=dispatch-status.enum.d.ts.map

package/dist/cjs/api/conduit/dispatch-status.enum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch-status.enum.d.ts","sourceRoot":"","sources":["../../../../src/api/conduit/dispatch-status.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,oBAAY,cAAc;IACtB,mFAAmF;IACnF,OAAO,YAAY;IAEnB;;;;;;;OAOG;IACH,SAAS,cAAc;IAEvB,0CAA0C;IAC1C,SAAS,cAAc;IAEvB;;;;;OAKG;IACH,aAAa,kBAAkB;IAE/B,wFAAwF;IACxF,SAAS,cAAc;CAC1B"}

package/dist/cjs/api/conduit/dispatch-status.enum.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DispatchStatus = void 0;
+/**
+ * Where one outbound dispatch is in its life.
+ *
+ * The members mirror `DeliveryStatus` exactly, and this is deliberately **not** the same enum.
+ * The two are separate wire contracts on separate resources, and sharing one would mean a state
+ * added for the inbound queue silently appears on the outbound one's documented API — a
+ * connector-specific state has no business showing up on a webhook delivery, and vice versa.
+ * Being identical today is not a reason to make them the same type; it is just what happens when
+ * two queues share a state machine.
+ *
+ * There is no `RATE_LIMITED` member on purpose. A dispatch held back by a connector's rate limit
+ * is simply `PENDING` with a later `nextAttemptAt`, because that is exactly what it is — waiting
+ * for its next attempt time, no differently from one waiting out a backoff. A separate state
+ * would suggest an operator has something to do about it.
+ */
+var DispatchStatus;
+(function (DispatchStatus) {
+    /** Waiting for its next attempt time. The only state the processor claims from. */
+    DispatchStatus["PENDING"] = "pending";
+    /**
+     * Claimed by a replica and being attempted right now.
+     *
+     * A row stuck here past the claim timeout is assumed abandoned and reclaimed — and on this
+     * side that reclaim is genuinely dangerous, because the request may have already reached the
+     * provider. It is why every dispatch carries an idempotency key onward and why a caller must
+     * treat outbound as at-least-once too.
+     */
+    DispatchStatus["IN_FLIGHT"] = "in-flight";
+    /** The provider accepted it. Terminal. */
+    DispatchStatus["DELIVERED"] = "delivered";
+    /**
+     * Every attempt was used and none succeeded, or the failure was permanent. Terminal until an
+     * operator redrives it.
+     *
+     * **This is the dead-letter queue** — a status, not a separate resource.
+     */
+    DispatchStatus["DEAD_LETTERED"] = "dead-lettered";
+    /** An operator stopped it before it was sent. Terminal, and distinct from a failure. */
+    DispatchStatus["CANCELLED"] = "cancelled";
+})(DispatchStatus || (exports.DispatchStatus = DispatchStatus = {}));
+//# sourceMappingURL=dispatch-status.enum.js.map

package/dist/cjs/api/conduit/dispatch-status.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch-status.enum.js","sourceRoot":"","sources":["../../../../src/api/conduit/dispatch-status.enum.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;GAcG;AACH,IAAY,cA2BX;AA3BD,WAAY,cAAc;IACtB,mFAAmF;IACnF,qCAAmB,CAAA;IAEnB;;;;;;;OAOG;IACH,yCAAuB,CAAA;IAEvB,0CAA0C;IAC1C,yCAAuB,CAAA;IAEvB;;;;;OAKG;IACH,iDAA+B,CAAA;IAE/B,wFAAwF;IACxF,yCAAuB,CAAA;AAC3B,CAAC,EA3BW,cAAc,8BAAd,cAAc,QA2BzB"}

package/dist/cjs/api/conduit/dispatch.type.d.ts

@@ -0,0 +1,143 @@
+import type { CursorPage } from '../../type/cursor-page.type.js';
+import type { IsoDateTime } from '../../type/iso-date-time.type.js';
+import type { Nullable } from '../../type/nil.type.js';
+import type { UUID } from '../../type/uuid.type.js';
+import type { DispatchStatus } from './dispatch-status.enum.js';
+/**
+ * One outbound request Conduit has accepted responsibility for.
+ *
+ * The inbound pipeline reversed: a vertical POSTs here, Conduit persists and answers `202`, and
+ * the provider is called afterwards with retries and a dead-letter queue. The caller is released
+ * from the third party's availability entirely — which is the point, because a CRM that awaits
+ * the Graph API inline is a CRM that is down whenever Meta is.
+ *
+ * **The payload is stored as sent.** Conduit does not reshape it into a provider's format; §14
+ * rules out transforms beyond header templating, and a gateway that rewrites bodies is a gateway
+ * that has opinions about domains it must not know exist.
+ */
+export interface Dispatch {
+    id: UUID;
+    /** The connection this went out through. A loose reference — it may since have been deleted. */
+    connectionId: UUID;
+    /** Snapshotted, so the record still reads correctly after the connection is renamed. */
+    connectionKey: string;
+    connectorKey: string;
+    /** The operation named at submit time. */
+    operation: string;
+    /**
+     * Resolved when the dispatch was accepted, not read from the manifest now.
+     *
+     * Same rule as a delivery's target: editing an operation's path must not retroactively
+     * change where Conduit says it sent something.
+     */
+    targetUrl: string;
+    method: string;
+    /**
+     * The caller's own key, echoed back.
+     *
+     * Submitting twice with the same key returns the **first** dispatch rather than creating a
+     * second — which is what makes a vertical's own retry safe. Null when the caller supplied
+     * none, in which case a resubmit is a second send and that is the caller's choice.
+     */
+    idempotencyKey: Nullable<string>;
+    status: DispatchStatus;
+    attemptCount: number;
+    /** Snapshotted from the connector's retry policy when accepted. */
+    maxAttempts: number;
+    nextAttemptAt: IsoDateTime;
+    lastAttemptAt: Nullable<IsoDateTime>;
+    /** Null when no response arrived. See `lastError`. */
+    lastResponseStatus: Nullable<number>;
+    lastResponseBodyPreview: Nullable<string>;
+    lastError: Nullable<string>;
+    /** Set when an operator redrove this. */
+    redrivenByUserId: Nullable<UUID>;
+    completedAt: Nullable<IsoDateTime>;
+    createdAt: IsoDateTime;
+}
+/**
+ * One attempt at one dispatch.
+ *
+ * `wasRateLimited` is the field that stops an operator misreading the history. A dispatch held
+ * back by the connector's own limit did not fail, cost no attempt, and needs nothing done about
+ * it — but without a record it looks like a gap in the timeline, and the obvious conclusion is
+ * that the queue stalled.
+ */
+export interface DispatchAttempt {
+    id: UUID;
+    /** 1-based. Equal for two rows only when one of them was a rate-limit deferral. */
+    attemptNumber: number;
+    /** Null when no response arrived at all. */
+    responseStatus: Nullable<number>;
+    responseBodyPreview: Nullable<string>;
+    errorMessage: Nullable<string>;
+    durationMs: number;
+    isSuccess: boolean;
+    /** Recorded but not charged against the attempt budget. */
+    wasRateLimited: boolean;
+    /** Whether the access token was refreshed and the request re-sent within this attempt. */
+    didRefreshCredentials: boolean;
+    createdAt: IsoDateTime;
+}
+/** `GET /api/v1/dispatches/:id/attempts`. Oldest first — an attempt history reads as a story. */
+export interface DispatchAttemptsList {
+    items: DispatchAttempt[];
+}
+/** `GET /api/v1/dispatches`. Cursor-paginated: the collection is appended to while it is read. */
+export type DispatchesPage = CursorPage<Dispatch>;
+/** Query for `GET /api/v1/dispatches`. */
+export interface GetDispatchesQuery {
+    limit?: number;
+    /** Opaque cursor from the previous page's `nextCursor`. Never parse it. */
+    after?: Nullable<string>;
+    /** `dead-lettered` is the DLQ view. The DLQ is a filter, not a separate resource. */
+    status?: Nullable<DispatchStatus>;
+    connectionId?: Nullable<UUID>;
+    operation?: Nullable<string>;
+}
+/**
+ * `POST /api/v1/dispatches` — the request a vertical makes to send something.
+ *
+ * Note what is **not** here: no URL, no host, no arbitrary headers. The caller picks a connection
+ * and an operation, both of which someone configured deliberately, and Conduit derives the
+ * target. Accepting a URL would make this an authenticated open proxy sitting inside our network.
+ */
+export interface SubmitDispatchBody {
+    /** Which connection to send through, by its tenant-scoped key. */
+    connectionKey: string;
+    /** Which of the connector's operations to invoke, by key. */
+    operation: string;
+    /** The request body, sent to the provider as-is. */
+    payload: Record<string, unknown>;
+    /**
+     * Values for `{placeholders}` in the operation's path that the connection does not supply.
+     *
+     * Percent-encoded into the path, so a value cannot introduce a path segment or a query
+     * string and steer the request at a different endpoint of the same host.
+     */
+    pathParams?: Nullable<Record<string, string>>;
+    /** Appended to the resolved URL. Values are encoded. */
+    query?: Nullable<Record<string, string>>;
+    /**
+     * The caller's idempotency key, scoped to the tenant.
+     *
+     * **Strongly recommended.** Without one, a vertical that times out submitting and retries
+     * sends the customer two messages. With one, the second submit returns the first dispatch.
+     */
+    idempotencyKey?: Nullable<string>;
+}
+/**
+ * `202 Accepted` from `POST /api/v1/dispatches`.
+ *
+ * Deliberately not the full {@link Dispatch}: at this moment the only true facts are that it was
+ * accepted and where to look next. Returning a status the caller might treat as an outcome
+ * invites exactly the synchronous coupling this endpoint exists to remove.
+ */
+export interface SubmitDispatchResponse {
+    id: UUID;
+    status: DispatchStatus;
+    /** True when this submit matched an existing idempotency key and created nothing. */
+    isDuplicate: boolean;
+    createdAt: IsoDateTime;
+}
+//# sourceMappingURL=dispatch.type.d.ts.map