@iveri/contracts 0.1.0 → 0.3.0

package/dist/cjs/enum/user-permission.enum.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Every action a principal can be granted in an Iveri tenant, across every service.
+ *
+ * A permission is a **contract**, not an implementation detail: `iveri-identity-api` stores
+ * members on role rows and resolves them into access tokens, every other service reads them
+ * out of that token to authorize a request, and the frontend's `<RequirePermission>` branches
+ * on the same values. A member's wire value therefore never changes, and a member is never
+ * removed while issued tokens can still carry it — removing one silently downgrades every
+ * live session holding it. Adding one is a minor version.
+ *
+ * **One catalogue for the whole platform, deliberately.** Identity validates custom-role input
+ * against this list, so a permission it has never heard of cannot be granted. A service that
+ * defined its own enum locally would find its permissions unassignable.
+ *
+ * Values are `<resource>:<action>` — or `<service>:<resource>:<action>` where a resource name
+ * would otherwise collide across services — lowercase, so a token payload is readable in a
+ * log and a wildcard match (`role:*`) stays possible if we ever need one.
+ */
+export declare enum UserPermission {
+    TENANT_READ = "tenant:read",
+    TENANT_UPDATE = "tenant:update",
+    /** Schedules the tenant for deletion. Owner-only; there is no undo path built yet. */
+    TENANT_DELETE = "tenant:delete",
+    USER_READ = "user:read",
+    USER_INVITE = "user:invite",
+    USER_UPDATE = "user:update",
+    USER_REMOVE = "user:remove",
+    MEMBERSHIP_READ = "membership:read",
+    /** Suspend or reactivate someone's access without deleting their account. */
+    MEMBERSHIP_UPDATE = "membership:update",
+    /**
+     * Change which roles a membership holds. Separate from `MEMBERSHIP_UPDATE` because
+     * granting roles is privilege escalation and deserves its own gate.
+     */
+    MEMBERSHIP_ASSIGN_ROLE = "membership:assign-role",
+    ROLE_READ = "role:read",
+    ROLE_CREATE = "role:create",
+    ROLE_UPDATE = "role:update",
+    ROLE_DELETE = "role:delete",
+    API_KEY_READ = "api-key:read",
+    API_KEY_ISSUE = "api-key:issue",
+    API_KEY_REVOKE = "api-key:revoke",
+    /** Read endpoint configuration. Never exposes the signing secret. */
+    CONDUIT_ENDPOINT_READ = "conduit:endpoint:read",
+    CONDUIT_ENDPOINT_CREATE = "conduit:endpoint:create",
+    CONDUIT_ENDPOINT_UPDATE = "conduit:endpoint:update",
+    CONDUIT_ENDPOINT_DELETE = "conduit:endpoint:delete",
+    /**
+     * List and read captured requests, **including their raw bodies and headers**. Captures
+     * hold whatever a provider sent — order details, message contents, personal data — so
+     * this is closer to a data-export permission than a config one.
+     */
+    CONDUIT_CAPTURE_READ = "conduit:capture:read",
+    CONDUIT_CAPTURE_DELETE = "conduit:capture:delete",
+    /**
+     * Resend a captured request to an arbitrary URL. Separate from `CONDUIT_CAPTURE_READ`
+     * because it makes an outbound request from our infrastructure with a body the caller
+     * controls, which is a materially different power from reading a row.
+     */
+    CONDUIT_REPLAY_EXECUTE = "conduit:replay:execute",
+    CONDUIT_PROVIDER_READ = "conduit:provider:read",
+    /** Define or amend a custom provider manifest — signature scheme, headers, handshake. */
+    CONDUIT_PROVIDER_MANAGE = "conduit:provider:manage"
+}
+/**
+ * Every member, for seeding the owner role and validating custom-role input.
+ *
+ * Frozen because it is shared mutable state in a browser bundle otherwise: one caller sorting
+ * it in place reorders it for everyone.
+ */
+export declare const ALL_USER_PERMISSIONS: readonly UserPermission[];
+//# sourceMappingURL=user-permission.enum.d.ts.map

package/dist/cjs/enum/user-permission.enum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-permission.enum.d.ts","sourceRoot":"","sources":["../../../src/enum/user-permission.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,oBAAY,cAAc;IAItB,WAAW,gBAAgB;IAC3B,aAAa,kBAAkB;IAC/B,sFAAsF;IACtF,aAAa,kBAAkB;IAG/B,SAAS,cAAc;IACvB,WAAW,gBAAgB;IAC3B,WAAW,gBAAgB;IAC3B,WAAW,gBAAgB;IAG3B,eAAe,oBAAoB;IACnC,6EAA6E;IAC7E,iBAAiB,sBAAsB;IACvC;;;OAGG;IACH,sBAAsB,2BAA2B;IAGjD,SAAS,cAAc;IACvB,WAAW,gBAAgB;IAC3B,WAAW,gBAAgB;IAC3B,WAAW,gBAAgB;IAG3B,YAAY,iBAAiB;IAC7B,aAAa,kBAAkB;IAC/B,cAAc,mBAAmB;IAKjC,qEAAqE;IACrE,qBAAqB,0BAA0B;IAC/C,uBAAuB,4BAA4B;IACnD,uBAAuB,4BAA4B;IACnD,uBAAuB,4BAA4B;IAGnD;;;;OAIG;IACH,oBAAoB,yBAAyB;IAC7C,sBAAsB,2BAA2B;IAGjD;;;;OAIG;IACH,sBAAsB,2BAA2B;IAGjD,qBAAqB,0BAA0B;IAC/C,yFAAyF;IACzF,uBAAuB,4BAA4B;CACtD;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,cAAc,EAAiD,CAAC"}

package/dist/cjs/enum/user-permission.enum.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALL_USER_PERMISSIONS = exports.UserPermission = void 0;
+/**
+ * Every action a principal can be granted in an Iveri tenant, across every service.
+ *
+ * A permission is a **contract**, not an implementation detail: `iveri-identity-api` stores
+ * members on role rows and resolves them into access tokens, every other service reads them
+ * out of that token to authorize a request, and the frontend's `<RequirePermission>` branches
+ * on the same values. A member's wire value therefore never changes, and a member is never
+ * removed while issued tokens can still carry it — removing one silently downgrades every
+ * live session holding it. Adding one is a minor version.
+ *
+ * **One catalogue for the whole platform, deliberately.** Identity validates custom-role input
+ * against this list, so a permission it has never heard of cannot be granted. A service that
+ * defined its own enum locally would find its permissions unassignable.
+ *
+ * Values are `<resource>:<action>` — or `<service>:<resource>:<action>` where a resource name
+ * would otherwise collide across services — lowercase, so a token payload is readable in a
+ * log and a wildcard match (`role:*`) stays possible if we ever need one.
+ */
+var UserPermission;
+(function (UserPermission) {
+    // ══ iveri-identity-api ═══════════════════════════════════════════════════
+    // ── Tenant ──────────────────────────────────────────────────────────────
+    UserPermission["TENANT_READ"] = "tenant:read";
+    UserPermission["TENANT_UPDATE"] = "tenant:update";
+    /** Schedules the tenant for deletion. Owner-only; there is no undo path built yet. */
+    UserPermission["TENANT_DELETE"] = "tenant:delete";
+    // ── User ────────────────────────────────────────────────────────────────
+    UserPermission["USER_READ"] = "user:read";
+    UserPermission["USER_INVITE"] = "user:invite";
+    UserPermission["USER_UPDATE"] = "user:update";
+    UserPermission["USER_REMOVE"] = "user:remove";
+    // ── Membership ──────────────────────────────────────────────────────────
+    UserPermission["MEMBERSHIP_READ"] = "membership:read";
+    /** Suspend or reactivate someone's access without deleting their account. */
+    UserPermission["MEMBERSHIP_UPDATE"] = "membership:update";
+    /**
+     * Change which roles a membership holds. Separate from `MEMBERSHIP_UPDATE` because
+     * granting roles is privilege escalation and deserves its own gate.
+     */
+    UserPermission["MEMBERSHIP_ASSIGN_ROLE"] = "membership:assign-role";
+    // ── Role ────────────────────────────────────────────────────────────────
+    UserPermission["ROLE_READ"] = "role:read";
+    UserPermission["ROLE_CREATE"] = "role:create";
+    UserPermission["ROLE_UPDATE"] = "role:update";
+    UserPermission["ROLE_DELETE"] = "role:delete";
+    // ── API key ─────────────────────────────────────────────────────────────
+    UserPermission["API_KEY_READ"] = "api-key:read";
+    UserPermission["API_KEY_ISSUE"] = "api-key:issue";
+    UserPermission["API_KEY_REVOKE"] = "api-key:revoke";
+    // ══ conduit-api ══════════════════════════════════════════════════════════
+    // ── Endpoint ────────────────────────────────────────────────────────────
+    /** Read endpoint configuration. Never exposes the signing secret. */
+    UserPermission["CONDUIT_ENDPOINT_READ"] = "conduit:endpoint:read";
+    UserPermission["CONDUIT_ENDPOINT_CREATE"] = "conduit:endpoint:create";
+    UserPermission["CONDUIT_ENDPOINT_UPDATE"] = "conduit:endpoint:update";
+    UserPermission["CONDUIT_ENDPOINT_DELETE"] = "conduit:endpoint:delete";
+    // ── Capture ─────────────────────────────────────────────────────────────
+    /**
+     * List and read captured requests, **including their raw bodies and headers**. Captures
+     * hold whatever a provider sent — order details, message contents, personal data — so
+     * this is closer to a data-export permission than a config one.
+     */
+    UserPermission["CONDUIT_CAPTURE_READ"] = "conduit:capture:read";
+    UserPermission["CONDUIT_CAPTURE_DELETE"] = "conduit:capture:delete";
+    // ── Replay ──────────────────────────────────────────────────────────────
+    /**
+     * Resend a captured request to an arbitrary URL. Separate from `CONDUIT_CAPTURE_READ`
+     * because it makes an outbound request from our infrastructure with a body the caller
+     * controls, which is a materially different power from reading a row.
+     */
+    UserPermission["CONDUIT_REPLAY_EXECUTE"] = "conduit:replay:execute";
+    // ── Provider ────────────────────────────────────────────────────────────
+    UserPermission["CONDUIT_PROVIDER_READ"] = "conduit:provider:read";
+    /** Define or amend a custom provider manifest — signature scheme, headers, handshake. */
+    UserPermission["CONDUIT_PROVIDER_MANAGE"] = "conduit:provider:manage";
+})(UserPermission || (exports.UserPermission = UserPermission = {}));
+/**
+ * Every member, for seeding the owner role and validating custom-role input.
+ *
+ * Frozen because it is shared mutable state in a browser bundle otherwise: one caller sorting
+ * it in place reorders it for everyone.
+ */
+exports.ALL_USER_PERMISSIONS = Object.freeze(Object.values(UserPermission));
+//# sourceMappingURL=user-permission.enum.js.map

package/dist/cjs/enum/user-permission.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-permission.enum.js","sourceRoot":"","sources":["../../../src/enum/user-permission.enum.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,IAAY,cAkEX;AAlED,WAAY,cAAc;IACtB,4EAA4E;IAE5E,2EAA2E;IAC3E,6CAA2B,CAAA;IAC3B,iDAA+B,CAAA;IAC/B,sFAAsF;IACtF,iDAA+B,CAAA;IAE/B,2EAA2E;IAC3E,yCAAuB,CAAA;IACvB,6CAA2B,CAAA;IAC3B,6CAA2B,CAAA;IAC3B,6CAA2B,CAAA;IAE3B,2EAA2E;IAC3E,qDAAmC,CAAA;IACnC,6EAA6E;IAC7E,yDAAuC,CAAA;IACvC;;;OAGG;IACH,mEAAiD,CAAA;IAEjD,2EAA2E;IAC3E,yCAAuB,CAAA;IACvB,6CAA2B,CAAA;IAC3B,6CAA2B,CAAA;IAC3B,6CAA2B,CAAA;IAE3B,2EAA2E;IAC3E,+CAA6B,CAAA;IAC7B,iDAA+B,CAAA;IAC/B,mDAAiC,CAAA;IAEjC,4EAA4E;IAE5E,2EAA2E;IAC3E,qEAAqE;IACrE,iEAA+C,CAAA;IAC/C,qEAAmD,CAAA;IACnD,qEAAmD,CAAA;IACnD,qEAAmD,CAAA;IAEnD,2EAA2E;IAC3E;;;;OAIG;IACH,+DAA6C,CAAA;IAC7C,mEAAiD,CAAA;IAEjD,2EAA2E;IAC3E;;;;OAIG;IACH,mEAAiD,CAAA;IAEjD,2EAA2E;IAC3E,iEAA+C,CAAA;IAC/C,yFAAyF;IACzF,qEAAmD,CAAA;AACvD,CAAC,EAlEW,cAAc,8BAAd,cAAc,QAkEzB;AAED;;;;;GAKG;AACU,QAAA,oBAAoB,GAA8B,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC"}

package/dist/cjs/type/api-response.type.d.ts

@@ -1,18 +1,5 @@
 import type { ErrorCode } from '../enum/error-code.enum.js';
 import type { Maybe } from './nil.type.js';
-/**
- * Envelope for a successful HTTP response.
- *
- * Every service wraps its payload in this shape, so a client can branch on
- * `success` before touching anything else and never has to guess whether a
- * 200 body is data or an error report.
- *
- * @typeParam T - the response payload type.
- */
-export interface ApiSuccessResponse<T> {
-    success: true;
-    data: T;
-}
 /**
  * The error half of {@link ApiErrorResponse}.
  *
@@ -36,8 +23,30 @@ export interface ApiErrorBody {
     correlationId?: Maybe<string>;
 }
 /**
- * Envelope for a failed HTTP response, emitted by the SDK's global exception
- * filter for every non-2xx status.
+ * Envelope for a failed response, emitted by the SDK's `GlobalExceptionFilter` for every
+ * non-2xx status.
+ *
+ * **Only errors are enveloped.** A success is the bare payload — a tenant response *is* a
+ * tenant, not a `{ success, data }` wrapper around one. So `success: false` discriminates a
+ * shape the client receives *instead of* its payload, never alongside it:
+ *
+ * ```ts
+ * const body: unknown = await response.json();
+ *
+ * if (!response.ok) {
+ *     throw new ApiError(body as ApiErrorResponse);
+ * }
+ *
+ * return body as Tenant;
+ * ```
+ *
+ * This file also declared `ApiSuccessResponse<T>` and a union over the two until 0.3.0.
+ * Nothing ever sent it: both `iveri-identity-api` and `conduit-api` register the exception
+ * filter and no success interceptor. A type describing a response no service produces is worse
+ * than no type at all — reading it, the natural thing to write is `body.data`, which is
+ * `undefined` for every call in the application. It was removed rather than made true, because
+ * bare payloads were already shipped across two services and a frontend and the envelope added
+ * nothing to the HTTP status a client must check regardless.
  */
 export interface ApiErrorResponse {
     success: false;
@@ -47,17 +56,4 @@ export interface ApiErrorResponse {
     /** Request path that produced the error, without the query string. */
     path: string;
 }
-/**
- * Discriminated union of both envelopes. Narrow on `success`:
- *
- * ```ts
- * if (!response.success) {
- *     return handle(response.error.code);
- * }
- * use(response.data);
- * ```
- *
- * @typeParam T - the payload type on the success branch.
- */
-export type ApiResponse<T> = ApiSuccessResponse<T> | ApiErrorResponse;
 //# sourceMappingURL=api-response.type.d.ts.map

package/dist/cjs/type/api-response.type.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-response.type.d.ts","sourceRoot":"","sources":["../../../src/type/api-response.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAE5D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAE3C;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACjC,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,CAAC,CAAC;CACX;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IACzB,iFAAiF;IACjF,IAAI,EAAE,SAAS,CAAC;IAEhB,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAEzC;;;OAGG;IACH,aAAa,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC7B,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,YAAY,CAAC;IAEpB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAElB,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,kBAAkB,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC"}
+{"version":3,"file":"api-response.type.d.ts","sourceRoot":"","sources":["../../../src/type/api-response.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAE5D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IACzB,iFAAiF;IACjF,IAAI,EAAE,SAAS,CAAC;IAEhB,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAEzC;;;OAGG;IACH,aAAa,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,gBAAgB;IAC7B,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,YAAY,CAAC;IAEpB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAElB,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;CAChB"}

package/dist/cjs/type/index.d.ts

@@ -1,5 +1,6 @@
 export * from './api-response.type.js';
 export * from './cursor-page.type.js';
+export * from './iso-date-time.type.js';
 export * from './nil.type.js';
 export * from './paginated.type.js';
 export * from './uuid.type.js';

package/dist/cjs/type/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/type/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/type/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC"}

package/dist/cjs/type/index.js

@@ -16,6 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./api-response.type.js"), exports);
 __exportStar(require("./cursor-page.type.js"), exports);
+__exportStar(require("./iso-date-time.type.js"), exports);
 __exportStar(require("./nil.type.js"), exports);
 __exportStar(require("./paginated.type.js"), exports);
 __exportStar(require("./uuid.type.js"), exports);

package/dist/cjs/type/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/type/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,yDAAuC;AACvC,wDAAsC;AACtC,gDAA8B;AAC9B,sDAAoC;AACpC,iDAA+B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/type/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,yDAAuC;AACvC,wDAAsC;AACtC,0DAAwC;AACxC,gDAA8B;AAC9B,sDAAoC;AACpC,iDAA+B"}

package/dist/cjs/type/iso-date-time.type.d.ts

@@ -0,0 +1,17 @@
+/**
+ * An ISO-8601 timestamp as it appears on the wire: `2026-08-02T09:41:17.312Z`.
+ *
+ * **JSON has no date type**, so every timestamp a service sends is a string, whatever the
+ * entity behind it holds. Naming that is not pedantry — it is the single most reliable way to
+ * hand-retype a backend response wrongly. A frontend interface declaring `receivedAt: Date`
+ * compiles, and every `receivedAt.getTime()` throws at runtime against a value that is really
+ * a string. `conduit-admin-web` called this out in a comment and got it right by hand; the
+ * point of putting the shapes in this package is that nobody has to.
+ *
+ * It is an alias, not a branded type, deliberately. A brand would force a cast at every
+ * boundary where a string arrives from `JSON.parse` — which is all of them — and buy nothing,
+ * since the value genuinely is an unvalidated string until someone parses it. What this alias
+ * carries is the instruction: to get a `Date`, write `new Date(value)`.
+ */
+export type IsoDateTime = string;
+//# sourceMappingURL=iso-date-time.type.d.ts.map

package/dist/cjs/type/iso-date-time.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"iso-date-time.type.d.ts","sourceRoot":"","sources":["../../../src/type/iso-date-time.type.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC"}

package/dist/cjs/type/iso-date-time.type.js

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

package/dist/cjs/type/iso-date-time.type.js.map

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

package/dist/esm/api/conduit/capture.type.d.ts

@@ -0,0 +1,70 @@
+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 { SignatureVerdict } from './signature-verdict.enum.js';
+/** A capture without its body — one row of the list. */
+export interface CaptureSummary {
+    id: UUID;
+    endpointId: UUID;
+    method: string;
+    /** Path after the ingress token. */
+    path: string;
+    /** Raw query string, without the `?`. */
+    queryString: string;
+    contentType: Nullable<string>;
+    /** Body size in bytes, as received. */
+    bodySize: number;
+    /** Hex SHA-256 of the body. Compare this against what the provider says it sent. */
+    bodySha256: string;
+    /** From `x-forwarded-for`. Advisory — a client controls it. */
+    sourceIp: Nullable<string>;
+    /**
+     * Verdict recorded **when the request arrived**. A snapshot: fixing the endpoint's secret
+     * does not rewrite it. Re-run the signature route to check against current configuration.
+     */
+    signatureVerdict: Nullable<SignatureVerdict>;
+    /** A provider's URL-verification challenge rather than a real event. */
+    isHandshake: boolean;
+    receivedAt: IsoDateTime;
+}
+/** A capture with its headers and body. `GET /api/v1/capture/:id`. */
+export interface CaptureDetail extends CaptureSummary {
+    /** Every request header, lowercase keys — including the signature headers. */
+    headers: Record<string, string | string[]>;
+    /**
+     * The body as UTF-8 when it decodes cleanly, otherwise `null`.
+     *
+     * A convenience only. `toString('utf8')` never fails — it substitutes U+FFFD for every
+     * invalid sequence — so a gzip or protobuf body would come back as convincing-looking
+     * mojibake that no longer hashes to `bodySha256`. Conduit round-trips the decode and sends
+     * `null` when it does not survive, which is the honest answer.
+     */
+    body: Nullable<string>;
+    /**
+     * The body as base64. **This is the authoritative field.** A webhook body is arbitrary
+     * bytes; base64 is the only representation that survives JSON without alteration, and the
+     * signed payload is those exact bytes.
+     */
+    bodyBase64: string;
+    /** The body was too large to inline and was read back from a spill file. */
+    isSpilled: boolean;
+}
+/** `GET /api/v1/capture`. */
+export type CapturesPage = CursorPage<CaptureSummary>;
+/**
+ * Query for `GET /api/v1/capture`.
+ *
+ * Cursor-paginated, unlike endpoints and providers: captures are appended to while they are
+ * being read — every inbound webhook lands at the top of the list, including while an operator
+ * pages through it — and offset paging drops or repeats rows under that.
+ */
+export interface GetCapturesQuery {
+    limit?: number;
+    /** Opaque cursor from the previous page's `nextCursor`. Never parse it. */
+    after?: Nullable<string>;
+    endpointId?: Nullable<UUID>;
+    method?: Nullable<string>;
+    signatureVerdict?: Nullable<SignatureVerdict>;
+}
+//# sourceMappingURL=capture.type.d.ts.map

package/dist/esm/api/conduit/capture.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.type.d.ts","sourceRoot":"","sources":["../../../../src/api/conduit/capture.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AACjE,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,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAEpE,wDAAwD;AACxD,MAAM,WAAW,cAAc;IAC3B,EAAE,EAAE,IAAI,CAAC;IACT,UAAU,EAAE,IAAI,CAAC;IAEjB,MAAM,EAAE,MAAM,CAAC;IAEf,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IAEb,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IAEpB,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE9B,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IAEjB,oFAAoF;IACpF,UAAU,EAAE,MAAM,CAAC;IAEnB,+DAA+D;IAC/D,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE3B;;;OAGG;IACH,gBAAgB,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC;IAE7C,wEAAwE;IACxE,WAAW,EAAE,OAAO,CAAC;IAErB,UAAU,EAAE,WAAW,CAAC;CAC3B;AAED,sEAAsE;AACtE,MAAM,WAAW,aAAc,SAAQ,cAAc;IACjD,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAE3C;;;;;;;OAOG;IACH,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAEvB;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB,4EAA4E;IAC5E,SAAS,EAAE,OAAO,CAAC;CACtB;AAED,6BAA6B;AAC7B,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,cAAc,CAAC,CAAC;AAEtD;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,2EAA2E;IAC3E,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAEzB,UAAU,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC5B,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC1B,gBAAgB,CAAC,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC;CACjD"}

package/dist/esm/api/conduit/capture.type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=capture.type.js.map

package/dist/esm/api/conduit/capture.type.js.map

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

package/dist/esm/api/conduit/endpoint.type.d.ts

@@ -0,0 +1,66 @@
+import type { IsoDateTime } from '../../type/iso-date-time.type.js';
+import type { Nullable } from '../../type/nil.type.js';
+import type { Paginated } from '../../type/paginated.type.js';
+import type { UUID } from '../../type/uuid.type.js';
+/**
+ * One endpoint on the wire.
+ *
+ * Carries `hasSigningSecret`, never the secret. Not a masked value, not a last-four hint — the
+ * field simply does not exist, so no future change can accidentally start populating it.
+ */
+export interface Endpoint {
+    id: UUID;
+    name: string;
+    description: Nullable<string>;
+    /** The path segment providers post to. */
+    ingressToken: string;
+    /**
+     * Path to register with the provider. Relative on purpose — the public origin is a tunnel or
+     * a load balancer this service cannot see, so the caller prepends its own.
+     */
+    ingressPath: string;
+    providerKey: Nullable<string>;
+    /** Whether a signing secret is configured. The secret itself is never returned. */
+    hasSigningSecret: boolean;
+    /** Whether a handshake verify token is configured. */
+    hasVerifyToken: boolean;
+    /** Inactive endpoints answer 410 Gone. */
+    isActive: boolean;
+    createdAt: IsoDateTime;
+    updatedAt: IsoDateTime;
+}
+/**
+ * `GET /api/v1/endpoint`. Offset-paginated, unlike captures: endpoints are a small, slow-moving
+ * collection a customer renders as numbered pages.
+ */
+export type EndpointsPage = Paginated<Endpoint>;
+/** `POST /api/v1/endpoint`. */
+export interface CreateEndpointBody {
+    name: string;
+    description?: Nullable<string>;
+    providerKey?: Nullable<string>;
+    signingSecret?: Nullable<string>;
+    verifyToken?: Nullable<string>;
+}
+/**
+ * `PATCH /api/v1/endpoint/:id`.
+ *
+ * **Secret fields have three states, not two.** Omitting one leaves the stored secret untouched;
+ * sending `null` deletes it. A form must therefore never send `''` or `null` where the user
+ * meant "I did not change this" — that silently wipes a working signing secret, and the next
+ * webhook verifies as `MISSING_SECRET` with nothing to say why.
+ */
+export interface UpdateEndpointBody {
+    name?: string;
+    description?: Nullable<string>;
+    providerKey?: Nullable<string>;
+    signingSecret?: Nullable<string>;
+    verifyToken?: Nullable<string>;
+    isActive?: boolean;
+}
+/** Query for `GET /api/v1/endpoint`. */
+export interface GetEndpointsQuery {
+    limit?: number;
+    offset?: number;
+}
+//# sourceMappingURL=endpoint.type.d.ts.map

package/dist/esm/api/conduit/endpoint.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint.type.d.ts","sourceRoot":"","sources":["../../../../src/api/conduit/endpoint.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,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACrB,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE9B,0CAA0C;IAC1C,YAAY,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE9B,mFAAmF;IACnF,gBAAgB,EAAE,OAAO,CAAC;IAE1B,sDAAsD;IACtD,cAAc,EAAE,OAAO,CAAC;IAExB,0CAA0C;IAC1C,QAAQ,EAAE,OAAO,CAAC;IAElB,SAAS,EAAE,WAAW,CAAC;IACvB,SAAS,EAAE,WAAW,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAEhD,+BAA+B;AAC/B,MAAM,WAAW,kBAAkB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACjC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACjC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,wCAAwC;AACxC,MAAM,WAAW,iBAAiB;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/dist/esm/api/conduit/endpoint.type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=endpoint.type.js.map

package/dist/esm/api/conduit/endpoint.type.js.map

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

package/dist/esm/api/conduit/handshake-kind.enum.d.ts

@@ -0,0 +1,22 @@
+/**
+ * How a provider proves the endpoint is really ours before it will send anything.
+ *
+ * **Handshakes work in inspect mode, deliberately.** Meta will not save a callback URL that
+ * does not echo `hub.challenge`, and Slack will not save one that does not echo `challenge` —
+ * so without this, the local developer tool could never be registered with the provider at all,
+ * and there would be nothing to capture. It is the one piece of ingress behaviour that is not
+ * "store and acknowledge".
+ */
+export declare enum HandshakeKind {
+    /**
+     * Provider sends `GET ?mode=subscribe&verify_token=…&challenge=…` and expects the challenge
+     * echoed back as the plain-text body. Meta (WhatsApp, Messenger, Instagram).
+     */
+    QUERY_ECHO = "query-echo",
+    /**
+     * Provider sends a JSON body carrying a trigger field and a challenge, and expects the
+     * challenge echoed in a JSON response. Slack (`type: url_verification`).
+     */
+    JSON_ECHO = "json-echo"
+}
+//# sourceMappingURL=handshake-kind.enum.d.ts.map

package/dist/esm/api/conduit/handshake-kind.enum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handshake-kind.enum.d.ts","sourceRoot":"","sources":["../../../../src/api/conduit/handshake-kind.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,oBAAY,aAAa;IACrB;;;OAGG;IACH,UAAU,eAAe;IAEzB;;;OAGG;IACH,SAAS,cAAc;CAC1B"}

package/dist/esm/api/conduit/handshake-kind.enum.js

@@ -0,0 +1,23 @@
+/**
+ * How a provider proves the endpoint is really ours before it will send anything.
+ *
+ * **Handshakes work in inspect mode, deliberately.** Meta will not save a callback URL that
+ * does not echo `hub.challenge`, and Slack will not save one that does not echo `challenge` —
+ * so without this, the local developer tool could never be registered with the provider at all,
+ * and there would be nothing to capture. It is the one piece of ingress behaviour that is not
+ * "store and acknowledge".
+ */
+export var HandshakeKind;
+(function (HandshakeKind) {
+    /**
+     * Provider sends `GET ?mode=subscribe&verify_token=…&challenge=…` and expects the challenge
+     * echoed back as the plain-text body. Meta (WhatsApp, Messenger, Instagram).
+     */
+    HandshakeKind["QUERY_ECHO"] = "query-echo";
+    /**
+     * Provider sends a JSON body carrying a trigger field and a challenge, and expects the
+     * challenge echoed in a JSON response. Slack (`type: url_verification`).
+     */
+    HandshakeKind["JSON_ECHO"] = "json-echo";
+})(HandshakeKind || (HandshakeKind = {}));
+//# sourceMappingURL=handshake-kind.enum.js.map

package/dist/esm/api/conduit/handshake-kind.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handshake-kind.enum.js","sourceRoot":"","sources":["../../../../src/api/conduit/handshake-kind.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,CAAN,IAAY,aAYX;AAZD,WAAY,aAAa;IACrB;;;OAGG;IACH,0CAAyB,CAAA;IAEzB;;;OAGG;IACH,wCAAuB,CAAA;AAC3B,CAAC,EAZW,aAAa,KAAb,aAAa,QAYxB"}

package/dist/esm/api/conduit/index.d.ts

@@ -0,0 +1,11 @@
+export * from './capture.type.js';
+export * from './endpoint.type.js';
+export * from './handshake-kind.enum.js';
+export * from './provider.type.js';
+export * from './replay.type.js';
+export * from './signature-algorithm.enum.js';
+export * from './signature-encoding.enum.js';
+export * from './signature-header-scheme.enum.js';
+export * from './signature-verdict.enum.js';
+export * from './signature.type.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/api/conduit/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/api/conduit/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,mCAAmC,CAAC;AAClD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,qBAAqB,CAAC"}

package/dist/esm/api/conduit/index.js

@@ -0,0 +1,11 @@
+export * from './capture.type.js';
+export * from './endpoint.type.js';
+export * from './handshake-kind.enum.js';
+export * from './provider.type.js';
+export * from './replay.type.js';
+export * from './signature-algorithm.enum.js';
+export * from './signature-encoding.enum.js';
+export * from './signature-header-scheme.enum.js';
+export * from './signature-verdict.enum.js';
+export * from './signature.type.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/api/conduit/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/api/conduit/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,mCAAmC,CAAC;AAClD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,qBAAqB,CAAC"}