@mszr/idb-dux 1.0.0

package/dist/esm/webhooks/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `@mszr/idb-dux/webhooks` — webhook handling and management.
+ *
+ * Optional-config `init`, `defineWebhookHandlers`, the pipeline verbs
+ * (`verify`/`fetchPayload`/`dispatch`/`process`/`processNode`), and `manager`.
+ * Admin-free by design: handling needs no admin token.
+ *
+ * Spec: `../../../docs/dux-spec-webhooks.md`.
+ */
+export { IdbApiError, IdbError } from '../errors.js';
+export type { IdbIssue } from '../errors.js';
+export { defineWebhookHandlers } from './defineWebhookHandlers.js';
+export { init } from './init.js';
+export type { IdbWebhook, IdbWebhookAction, IdbWebhookAttempt, IdbWebhookBody, IdbWebhookChange, IdbWebhookConfig, IdbWebhookCreate, IdbWebhookEvent, IdbWebhookEventsPage, IdbWebhookEventStatus, IdbWebhookHandlers, IdbWebhookManager, IdbWebhookNodeOpts, IdbWebhookNodeRequest, IdbWebhookPayload, IdbWebhooks, IdbWebhookStatus, IdbWebhookUpdate, IdbWebhookVerifyOpts, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/webhooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/webhooks/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AACpD,YAAY,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA;AAClE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,YAAY,EACV,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,YAAY,CAAA"}

package/dist/esm/webhooks/index.js

@@ -0,0 +1,14 @@
+/**
+ * `@mszr/idb-dux/webhooks` — webhook handling and management.
+ *
+ * Optional-config `init`, `defineWebhookHandlers`, the pipeline verbs
+ * (`verify`/`fetchPayload`/`dispatch`/`process`/`processNode`), and `manager`.
+ * Admin-free by design: handling needs no admin token.
+ *
+ * Spec: `../../../docs/dux-spec-webhooks.md`.
+ */
+// The branded error family — `e instanceof IdbError` (verify/fetch can throw).
+export { IdbApiError, IdbError } from '../errors.js';
+export { defineWebhookHandlers } from './defineWebhookHandlers.js';
+export { init } from './init.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/webhooks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/webhooks/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,+EAA+E;AAC/E,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAEpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA;AAClE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA","sourcesContent":["/**\n * `@mszr/idb-dux/webhooks` — webhook handling and management.\n *\n * Optional-config `init`, `defineWebhookHandlers`, the pipeline verbs\n * (`verify`/`fetchPayload`/`dispatch`/`process`/`processNode`), and `manager`.\n * Admin-free by design: handling needs no admin token.\n *\n * Spec: `../../../docs/dux-spec-webhooks.md`.\n */\n// The branded error family — `e instanceof IdbError` (verify/fetch can throw).\nexport { IdbApiError, IdbError } from '../errors.js'\nexport type { IdbIssue } from '../errors.js'\nexport { defineWebhookHandlers } from './defineWebhookHandlers.js'\nexport { init } from './init.js'\nexport type {\n  IdbWebhook,\n  IdbWebhookAction,\n  IdbWebhookAttempt,\n  IdbWebhookBody,\n  IdbWebhookChange,\n  IdbWebhookConfig,\n  IdbWebhookCreate,\n  IdbWebhookEvent,\n  IdbWebhookEventsPage,\n  IdbWebhookEventStatus,\n  IdbWebhookHandlers,\n  IdbWebhookManager,\n  IdbWebhookNodeOpts,\n  IdbWebhookNodeRequest,\n  IdbWebhookPayload,\n  IdbWebhooks,\n  IdbWebhookStatus,\n  IdbWebhookUpdate,\n  IdbWebhookVerifyOpts,\n} from './types.js'\n"]}

package/dist/esm/webhooks/init.d.ts

@@ -0,0 +1,13 @@
+import type { IdbSchema } from '../schema/defineSchema.js';
+import type { IdbRegisteredSchema } from '../schema/register.js';
+import type { IdbWebhookConfig, IdbWebhooks } from './types.js';
+/**
+ * Create a webhook handle. Call with no config to handle webhooks; pass
+ * `appId` + `adminToken` to also manage subscriptions.
+ *
+ * @example
+ *   const webhooks = init()
+ *   await webhooks.process(handlers, request) // verify → fetch → dispatch
+ */
+export declare function init<S extends IdbSchema = IdbRegisteredSchema>(config?: IdbWebhookConfig): IdbWebhooks<S>;
+//# sourceMappingURL=init.d.ts.map

package/dist/esm/webhooks/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/webhooks/init.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AAC1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAsB,WAAW,EAAE,MAAM,YAAY,CAAA;AAGnF;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,SAAS,GAAG,mBAAmB,EAC5D,MAAM,CAAC,EAAE,gBAAgB,GACxB,WAAW,CAAC,CAAC,CAAC,CAkBhB"}

package/dist/esm/webhooks/init.js

@@ -0,0 +1,36 @@
+import { Webhooks } from '@instantdb/webhooks';
+/**
+ * Create a webhook handle. Call with no config to handle webhooks; pass
+ * `appId` + `adminToken` to also manage subscriptions.
+ *
+ * @example
+ *   const webhooks = init()
+ *   await webhooks.process(handlers, request) // verify → fetch → dispatch
+ */
+export function init(config) {
+    const wh = new Webhooks({
+        appId: config?.appId,
+        adminToken: config?.adminToken,
+        apiURI: config?.apiURI,
+    });
+    return {
+        manager: wh.manager,
+        verify: (input, opts) => input instanceof Request
+            ? wh.validateRequest(input, opts)
+            : wh.validate(input.signature, input.body, opts),
+        fetchPayload: body => wh.fetchPayloads(body),
+        dispatch: (handlers, payload) => wh.processPayload(official(handlers), payload),
+        process: (handlers, request, opts) => wh.processRequest(official(handlers), request, opts),
+        processNode: (handlers, req, opts) => wh.processNodeRequest(official(handlers), req, opts),
+    };
+}
+/**
+ * The handler-map seam: a dux handler map *is* an official `WebhookHandlers`
+ * (the compat-target test proves it on a concrete schema). The generic `S`
+ * can't carry that proof through `exactOptionalPropertyTypes`, so the rename is
+ * asserted here, once, at the boundary.
+ */
+function official(handlers) {
+    return handlers;
+}
+//# sourceMappingURL=init.js.map

package/dist/esm/webhooks/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../../src/webhooks/init.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAE9C;;;;;;;GAOG;AACH,MAAM,UAAU,IAAI,CAClB,MAAyB;IAEzB,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAI;QACzB,KAAK,EAAE,MAAM,EAAE,KAAK;QACpB,UAAU,EAAE,MAAM,EAAE,UAAU;QAC9B,MAAM,EAAE,MAAM,EAAE,MAAM;KACvB,CAAC,CAAA;IAEF,OAAO;QACL,OAAO,EAAE,EAAE,CAAC,OAAO;QACnB,MAAM,EAAE,CAAC,KAA8E,EAAE,IAAI,EAAE,EAAE,CAC/F,KAAK,YAAY,OAAO;YACtB,CAAC,CAAC,EAAE,CAAC,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC;YACjC,CAAC,CAAC,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC;QACpD,YAAY,EAAE,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC;QAC5C,QAAQ,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,CAAC,EAAE,CAAC,cAAc,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;QAC/E,OAAO,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,cAAc,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC;QAC1F,WAAW,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,kBAAkB,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC;KAC3F,CAAA;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAS,QAAQ,CACf,QAA+B;IAE/B,OAAO,QAAyC,CAAA;AAClD,CAAC","sourcesContent":["/**\n * Optional-config `init` — composes `@instantdb/webhooks` and renames its\n * verbs at the boundary (dux-spec-webhooks.md §3, §5). Handling needs no\n * config; `appId` + `adminToken` unlock the `manager`.\n */\nimport type { WebhookHandlers } from '@instantdb/webhooks'\nimport type { IdbSchema } from '../schema/defineSchema.js'\nimport type { IdbRegisteredSchema } from '../schema/register.js'\nimport type { IdbWebhookConfig, IdbWebhookHandlers, IdbWebhooks } from './types.js'\nimport { Webhooks } from '@instantdb/webhooks'\n\n/**\n * Create a webhook handle. Call with no config to handle webhooks; pass\n * `appId` + `adminToken` to also manage subscriptions.\n *\n * @example\n *   const webhooks = init()\n *   await webhooks.process(handlers, request) // verify → fetch → dispatch\n */\nexport function init<S extends IdbSchema = IdbRegisteredSchema>(\n  config?: IdbWebhookConfig,\n): IdbWebhooks<S> {\n  const wh = new Webhooks<S>({\n    appId: config?.appId,\n    adminToken: config?.adminToken,\n    apiURI: config?.apiURI,\n  })\n\n  return {\n    manager: wh.manager,\n    verify: (input: Request | { signature: string, body: string | (() => Promise<string>) }, opts) =>\n      input instanceof Request\n        ? wh.validateRequest(input, opts)\n        : wh.validate(input.signature, input.body, opts),\n    fetchPayload: body => wh.fetchPayloads(body),\n    dispatch: (handlers, payload) => wh.processPayload(official(handlers), payload),\n    process: (handlers, request, opts) => wh.processRequest(official(handlers), request, opts),\n    processNode: (handlers, req, opts) => wh.processNodeRequest(official(handlers), req, opts),\n  }\n}\n\n/**\n * The handler-map seam: a dux handler map *is* an official `WebhookHandlers`\n * (the compat-target test proves it on a concrete schema). The generic `S`\n * can't carry that proof through `exactOptionalPropertyTypes`, so the rename is\n * asserted here, once, at the boundary.\n */\nfunction official<S extends IdbSchema>(\n  handlers: IdbWebhookHandlers<S>,\n): WebhookHandlers<S> {\n  return handlers as unknown as WebhookHandlers<S>\n}\n"]}

package/dist/esm/webhooks/types.d.ts

@@ -0,0 +1,136 @@
+/**
+ * The `IdbWebhook*` boundary module — every rename from `@instantdb/webhooks`
+ * lives here and nowhere else (wrap-and-map, dux-spec-workspace.md §5.1).
+ *
+ * Two kinds of types live side by side:
+ *
+ * - **aliases** for shapes with no entity content (`IdbWebhook`, the manager,
+ *   the op payloads, the unions): pure renames over the official types, so
+ *   upstream changes ride in for free and break loudly at the wrap points.
+ * - **authored-fresh** for the handler surface (`IdbWebhookChange`,
+ *   `IdbWebhookHandlers`): a change's `before`/`after` is the same
+ *   `IdbEntity<'ns'>` a query and a tx speak — one entity type everywhere, by
+ *   construction (dux-spec-webhooks.md §2). `WebhookEntity` is dropped — it
+ *   resolves to `IdbEntity` already.
+ *
+ * Everything is registration-typed — no schema generic at any call site, with
+ * the trailing escape-hatch param for multi-schema tools.
+ */
+import type { CreateWebhookParams, UpdateWebhookParams, WebhookAction, WebhookAttempt, WebhookBody, WebhookEventInfo, WebhookEventsPage, WebhookEventStatus, WebhookInfo, WebhookPayload, Webhooks, WebhooksManager, WebhookStatus } from '@instantdb/webhooks';
+import type { IdbSchema } from '../schema/defineSchema.js';
+import type { IdbRegisteredSchema } from '../schema/register.js';
+import type { IdbEntity, IdbNamespaceName } from '../schema/types.js';
+/** A configured webhook subscription. */
+export type IdbWebhook = WebhookInfo;
+/** A single delivery event for a webhook. */
+export type IdbWebhookEvent = WebhookEventInfo;
+/** One HTTP delivery attempt of an event. */
+export type IdbWebhookAttempt = WebhookAttempt;
+/** A page of delivery events. */
+export type IdbWebhookEventsPage = WebhookEventsPage;
+/** The verified delivery pointer `verify` returns — `payloadUrl` + `token`. */
+export type IdbWebhookBody = WebhookBody;
+/** The write actions a webhook can deliver. */
+export type IdbWebhookAction = WebhookAction;
+/** Whether a webhook is currently delivering events. */
+export type IdbWebhookStatus = WebhookStatus;
+/** A delivery event's stage in the retry lifecycle. */
+export type IdbWebhookEventStatus = WebhookEventStatus;
+/** The `manager.create` payload. */
+export type IdbWebhookCreate<S extends IdbSchema = IdbRegisteredSchema> = CreateWebhookParams<S>;
+/** The `manager.update` payload — every field optional. */
+export type IdbWebhookUpdate<S extends IdbSchema = IdbRegisteredSchema> = UpdateWebhookParams<S>;
+/** The delivered batch of changes for one webhook event. */
+export type IdbWebhookPayload<S extends IdbSchema = IdbRegisteredSchema> = WebhookPayload<S>;
+/** Subscription CRUD + delivery-event inspection. Method names verbatim. */
+export type IdbWebhookManager<S extends IdbSchema = IdbRegisteredSchema> = WebhooksManager<S>;
+/** One change shaped per action: the `before`/`after` an action carries. */
+type ChangeFor<S extends IdbSchema, NS extends IdbNamespaceName<S>, Action extends IdbWebhookAction> = Action extends 'create' ? {
+    namespace: NS;
+    id: string;
+    action: 'create';
+    before: null;
+    after: IdbEntity<NS, S>;
+    idempotencyKey: string;
+} : Action extends 'update' ? {
+    namespace: NS;
+    id: string;
+    action: 'update';
+    before: IdbEntity<NS, S>;
+    after: IdbEntity<NS, S>;
+    idempotencyKey: string;
+} : {
+    namespace: NS;
+    id: string;
+    action: 'delete';
+    before: IdbEntity<NS, S>;
+    after: null;
+    idempotencyKey: string;
+};
+/**
+ * One entity change a webhook delivers — `namespace`, `action`, and the
+ * `before`/`after` entities (`IdbEntity<'ns'>`, the same type queries and tx
+ * speak). Narrow with the optional `NS`/`Action` params; left wide it's the
+ * discriminated union over every namespace and action a `$default` handler
+ * sees. (Replaces the official `WebhookPayloadRecord` + `WebhookPayloadRecordFor`
+ * pair — one utility, optional narrowing, the `IdbEntity` pattern.)
+ */
+export type IdbWebhookChange<NS extends IdbNamespaceName<S> = IdbNamespaceName, Action extends IdbWebhookAction = IdbWebhookAction, S extends IdbSchema = IdbRegisteredSchema> = NS extends IdbNamespaceName<S> ? Action extends IdbWebhookAction ? ChangeFor<S, NS, Action> : never : never;
+type IdbWebhookHandlerFn<S extends IdbSchema, NS extends IdbNamespaceName<S>, Action extends IdbWebhookAction> = (change: IdbWebhookChange<NS, Action, S>) => unknown | Promise<unknown>;
+/**
+ * The handler map: `namespace.action`, a per-namespace `$default`, and a
+ * top-level `$default`. Authored as a plain object literal — contextual typing
+ * narrows each handler's `change` per namespace and action, so the official
+ * `typedHandlers`/`combineHandlers` ceremony dissolves ([§4](./dux-spec-webhooks.md#4-authoring--definewebhookhandlers)).
+ */
+export type IdbWebhookHandlers<S extends IdbSchema = IdbRegisteredSchema> = {
+    [NS in IdbNamespaceName<S>]?: {
+        [A in IdbWebhookAction | '$default']?: IdbWebhookHandlerFn<S, NS, A extends IdbWebhookAction ? A : IdbWebhookAction>;
+    };
+} & {
+    $default?: IdbWebhookHandlerFn<S, IdbNamespaceName<S>, IdbWebhookAction>;
+};
+/**
+ * `init` config. Optional in full — handling needs none. `appId` +
+ * `adminToken` unlock the `manager`; `apiURI` is for self-hosting.
+ */
+export interface IdbWebhookConfig {
+    appId?: string | null | undefined;
+    adminToken?: string | null | undefined;
+    apiURI?: string | null | undefined;
+}
+/** Tolerance/clock options shared by `verify` and `process`. */
+export type IdbWebhookVerifyOpts = NonNullable<Parameters<Webhooks<IdbSchema>['validateRequest']>[1]>;
+/** The Node `IncomingMessage`-shaped request `processNode` accepts. */
+export type IdbWebhookNodeRequest = Parameters<Webhooks<IdbSchema>['processNodeRequest']>[1];
+/** `processNode` options — `verify` options plus a raw-body override. */
+export type IdbWebhookNodeOpts = NonNullable<Parameters<Webhooks<IdbSchema>['processNodeRequest']>[2]>;
+/**
+ * The webhook handle `init` returns. The pipeline verbs are always present;
+ * `manager` requires `appId` + `adminToken` and throws if used without them.
+ */
+export interface IdbWebhooks<S extends IdbSchema = IdbRegisteredSchema> {
+    /** Subscription CRUD + event inspection. Requires `appId` + `adminToken`. */
+    manager: IdbWebhookManager<S>;
+    /**
+     * Cryptographically verify a delivery and return its `payloadUrl` + `token`.
+     * Pass the `Request`, or the raw `{ signature, body }` for custom flows.
+     */
+    verify: {
+        (request: Request, opts?: IdbWebhookVerifyOpts): Promise<IdbWebhookBody>;
+        (input: {
+            signature: string;
+            body: string | (() => Promise<string>);
+        }, opts?: IdbWebhookVerifyOpts): Promise<IdbWebhookBody>;
+    };
+    /** Fetch the payload a verified delivery references. */
+    fetchPayload: (body: IdbWebhookBody) => Promise<IdbWebhookPayload<S>>;
+    /** Route each change in a payload to its handler. */
+    dispatch: (handlers: IdbWebhookHandlers<S>, payload: IdbWebhookPayload<S>) => Promise<void>;
+    /** The one-liner: verify → fetch payload → dispatch (Web `Request`). */
+    process: (handlers: IdbWebhookHandlers<S>, request: Request, opts?: IdbWebhookVerifyOpts) => Promise<void>;
+    /** `process` for a Node `IncomingMessage` (raw-body rules preserved). */
+    processNode: (handlers: IdbWebhookHandlers<S>, req: IdbWebhookNodeRequest, opts?: IdbWebhookNodeOpts) => Promise<void>;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/webhooks/types.d.ts.map

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

package/dist/esm/webhooks/types.js

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

package/dist/esm/webhooks/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/webhooks/types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * The `IdbWebhook*` boundary module — every rename from `@instantdb/webhooks`\n * lives here and nowhere else (wrap-and-map, dux-spec-workspace.md §5.1).\n *\n * Two kinds of types live side by side:\n *\n * - **aliases** for shapes with no entity content (`IdbWebhook`, the manager,\n *   the op payloads, the unions): pure renames over the official types, so\n *   upstream changes ride in for free and break loudly at the wrap points.\n * - **authored-fresh** for the handler surface (`IdbWebhookChange`,\n *   `IdbWebhookHandlers`): a change's `before`/`after` is the same\n *   `IdbEntity<'ns'>` a query and a tx speak — one entity type everywhere, by\n *   construction (dux-spec-webhooks.md §2). `WebhookEntity` is dropped — it\n *   resolves to `IdbEntity` already.\n *\n * Everything is registration-typed — no schema generic at any call site, with\n * the trailing escape-hatch param for multi-schema tools.\n */\nimport type {\n  CreateWebhookParams,\n  UpdateWebhookParams,\n  WebhookAction,\n  WebhookAttempt,\n  WebhookBody,\n  WebhookEventInfo,\n  WebhookEventsPage,\n  WebhookEventStatus,\n  WebhookInfo,\n  WebhookPayload,\n  Webhooks,\n  WebhooksManager,\n  WebhookStatus,\n} from '@instantdb/webhooks'\nimport type { IdbSchema } from '../schema/defineSchema.js'\nimport type { IdbRegisteredSchema } from '../schema/register.js'\nimport type { IdbEntity, IdbNamespaceName } from '../schema/types.js'\n\n// ==========\n// aliases — official shapes, dux names\n\n/** A configured webhook subscription. */\nexport type IdbWebhook = WebhookInfo\n/** A single delivery event for a webhook. */\nexport type IdbWebhookEvent = WebhookEventInfo\n/** One HTTP delivery attempt of an event. */\nexport type IdbWebhookAttempt = WebhookAttempt\n/** A page of delivery events. */\nexport type IdbWebhookEventsPage = WebhookEventsPage\n/** The verified delivery pointer `verify` returns — `payloadUrl` + `token`. */\nexport type IdbWebhookBody = WebhookBody\n/** The write actions a webhook can deliver. */\nexport type IdbWebhookAction = WebhookAction\n/** Whether a webhook is currently delivering events. */\nexport type IdbWebhookStatus = WebhookStatus\n/** A delivery event's stage in the retry lifecycle. */\nexport type IdbWebhookEventStatus = WebhookEventStatus\n\n/** The `manager.create` payload. */\nexport type IdbWebhookCreate<S extends IdbSchema = IdbRegisteredSchema>\n  = CreateWebhookParams<S>\n/** The `manager.update` payload — every field optional. */\nexport type IdbWebhookUpdate<S extends IdbSchema = IdbRegisteredSchema>\n  = UpdateWebhookParams<S>\n\n/** The delivered batch of changes for one webhook event. */\nexport type IdbWebhookPayload<S extends IdbSchema = IdbRegisteredSchema>\n  = WebhookPayload<S>\n\n/** Subscription CRUD + delivery-event inspection. Method names verbatim. */\nexport type IdbWebhookManager<S extends IdbSchema = IdbRegisteredSchema>\n  = WebhooksManager<S>\n\n// ==========\n// the change — authored fresh over IdbEntity\n\n/** One change shaped per action: the `before`/`after` an action carries. */\ntype ChangeFor<\n  S extends IdbSchema,\n  NS extends IdbNamespaceName<S>,\n  Action extends IdbWebhookAction,\n> = Action extends 'create'\n  ? { namespace: NS, id: string, action: 'create', before: null, after: IdbEntity<NS, S>, idempotencyKey: string }\n  : Action extends 'update'\n    ? { namespace: NS, id: string, action: 'update', before: IdbEntity<NS, S>, after: IdbEntity<NS, S>, idempotencyKey: string }\n    : { namespace: NS, id: string, action: 'delete', before: IdbEntity<NS, S>, after: null, idempotencyKey: string }\n\n/**\n * One entity change a webhook delivers — `namespace`, `action`, and the\n * `before`/`after` entities (`IdbEntity<'ns'>`, the same type queries and tx\n * speak). Narrow with the optional `NS`/`Action` params; left wide it's the\n * discriminated union over every namespace and action a `$default` handler\n * sees. (Replaces the official `WebhookPayloadRecord` + `WebhookPayloadRecordFor`\n * pair — one utility, optional narrowing, the `IdbEntity` pattern.)\n */\nexport type IdbWebhookChange<\n  NS extends IdbNamespaceName<S> = IdbNamespaceName,\n  Action extends IdbWebhookAction = IdbWebhookAction,\n  S extends IdbSchema = IdbRegisteredSchema,\n> = NS extends IdbNamespaceName<S>\n  ? Action extends IdbWebhookAction\n    ? ChangeFor<S, NS, Action>\n    : never\n  : never\n\n// ==========\n// handlers — authored fresh so changes resolve to IdbWebhookChange\n\ntype IdbWebhookHandlerFn<\n  S extends IdbSchema,\n  NS extends IdbNamespaceName<S>,\n  Action extends IdbWebhookAction,\n> = (change: IdbWebhookChange<NS, Action, S>) => unknown | Promise<unknown>\n\n/**\n * The handler map: `namespace.action`, a per-namespace `$default`, and a\n * top-level `$default`. Authored as a plain object literal — contextual typing\n * narrows each handler's `change` per namespace and action, so the official\n * `typedHandlers`/`combineHandlers` ceremony dissolves ([§4](./dux-spec-webhooks.md#4-authoring--definewebhookhandlers)).\n */\nexport type IdbWebhookHandlers<S extends IdbSchema = IdbRegisteredSchema> = {\n  [NS in IdbNamespaceName<S>]?: {\n    [A in IdbWebhookAction | '$default']?: IdbWebhookHandlerFn<\n      S,\n      NS,\n      A extends IdbWebhookAction ? A : IdbWebhookAction\n    >\n  }\n} & {\n  $default?: IdbWebhookHandlerFn<S, IdbNamespaceName<S>, IdbWebhookAction>\n}\n\n// ==========\n// init config + the handle\n\n/**\n * `init` config. Optional in full — handling needs none. `appId` +\n * `adminToken` unlock the `manager`; `apiURI` is for self-hosting.\n */\nexport interface IdbWebhookConfig {\n  appId?: string | null | undefined\n  adminToken?: string | null | undefined\n  apiURI?: string | null | undefined\n}\n\n/** Tolerance/clock options shared by `verify` and `process`. */\nexport type IdbWebhookVerifyOpts = NonNullable<\n  Parameters<Webhooks<IdbSchema>['validateRequest']>[1]\n>\n\n/** The Node `IncomingMessage`-shaped request `processNode` accepts. */\nexport type IdbWebhookNodeRequest = Parameters<\n  Webhooks<IdbSchema>['processNodeRequest']\n>[1]\n\n/** `processNode` options — `verify` options plus a raw-body override. */\nexport type IdbWebhookNodeOpts = NonNullable<\n  Parameters<Webhooks<IdbSchema>['processNodeRequest']>[2]\n>\n\n/**\n * The webhook handle `init` returns. The pipeline verbs are always present;\n * `manager` requires `appId` + `adminToken` and throws if used without them.\n */\nexport interface IdbWebhooks<S extends IdbSchema = IdbRegisteredSchema> {\n  /** Subscription CRUD + event inspection. Requires `appId` + `adminToken`. */\n  manager: IdbWebhookManager<S>\n  /**\n   * Cryptographically verify a delivery and return its `payloadUrl` + `token`.\n   * Pass the `Request`, or the raw `{ signature, body }` for custom flows.\n   */\n  verify: {\n    (request: Request, opts?: IdbWebhookVerifyOpts): Promise<IdbWebhookBody>\n    (\n      input: { signature: string, body: string | (() => Promise<string>) },\n      opts?: IdbWebhookVerifyOpts,\n    ): Promise<IdbWebhookBody>\n  }\n  /** Fetch the payload a verified delivery references. */\n  fetchPayload: (body: IdbWebhookBody) => Promise<IdbWebhookPayload<S>>\n  /** Route each change in a payload to its handler. */\n  dispatch: (\n    handlers: IdbWebhookHandlers<S>,\n    payload: IdbWebhookPayload<S>,\n  ) => Promise<void>\n  /** The one-liner: verify → fetch payload → dispatch (Web `Request`). */\n  process: (\n    handlers: IdbWebhookHandlers<S>,\n    request: Request,\n    opts?: IdbWebhookVerifyOpts,\n  ) => Promise<void>\n  /** `process` for a Node `IncomingMessage` (raw-body rules preserved). */\n  processNode: (\n    handlers: IdbWebhookHandlers<S>,\n    req: IdbWebhookNodeRequest,\n    opts?: IdbWebhookNodeOpts,\n  ) => Promise<void>\n}\n"]}

package/package.json

@@ -0,0 +1,149 @@
+{
+  "name": "@mszr/idb-dux",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "A DX/UX-first reimagining of the InstantDB developer experience",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/mareszhar/idb-dux",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mareszhar/idb-dux.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mareszhar/idb-dux/issues"
+  },
+  "sideEffects": false,
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/commonjs/index.d.ts",
+        "default": "./dist/commonjs/index.js"
+      }
+    },
+    "./vue": {
+      "import": {
+        "types": "./dist/esm/vue/index.d.ts",
+        "default": "./dist/esm/vue/index.js"
+      },
+      "require": {
+        "types": "./dist/commonjs/vue/index.d.ts",
+        "default": "./dist/commonjs/vue/index.js"
+      }
+    },
+    "./perms": {
+      "import": {
+        "types": "./dist/esm/perms/index.d.ts",
+        "default": "./dist/esm/perms/index.js"
+      },
+      "require": {
+        "types": "./dist/commonjs/perms/index.d.ts",
+        "default": "./dist/commonjs/perms/index.js"
+      }
+    },
+    "./admin": {
+      "import": {
+        "types": "./dist/esm/admin/index.d.ts",
+        "default": "./dist/esm/admin/index.js"
+      },
+      "require": {
+        "types": "./dist/commonjs/admin/index.d.ts",
+        "default": "./dist/commonjs/admin/index.js"
+      }
+    },
+    "./webhooks": {
+      "import": {
+        "types": "./dist/esm/webhooks/index.d.ts",
+        "default": "./dist/esm/webhooks/index.js"
+      },
+      "require": {
+        "types": "./dist/commonjs/webhooks/index.d.ts",
+        "default": "./dist/commonjs/webhooks/index.js"
+      }
+    },
+    "./nuxt": {
+      "import": {
+        "types": "./dist/esm/nuxt/index.d.ts",
+        "default": "./dist/esm/nuxt/index.js"
+      },
+      "require": {
+        "types": "./dist/commonjs/nuxt/index.d.ts",
+        "default": "./dist/commonjs/nuxt/index.js"
+      }
+    }
+  },
+  "main": "./dist/commonjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/commonjs/index.d.ts",
+  "tshy": {
+    "selfLink": false,
+    "main": true,
+    "module": true,
+    "project": "./tsconfig.build.json",
+    "exclude": [
+      "src/**/*.test.ts",
+      "src/**/*.test-d.ts",
+      "src/test-support/**"
+    ],
+    "exports": {
+      "./package.json": "./package.json",
+      ".": "./src/index.ts",
+      "./vue": "./src/vue/index.ts",
+      "./perms": "./src/perms/index.ts",
+      "./admin": "./src/admin/index.ts",
+      "./webhooks": "./src/webhooks/index.ts",
+      "./nuxt": "./src/nuxt/index.ts"
+    }
+  },
+  "files": [
+    "!dist/**/*.test-d.*",
+    "!dist/**/*.test.*",
+    "!dist/**/test-support/**",
+    "dist"
+  ],
+  "peerDependencies": {
+    "@instantdb/admin": "1.0.49",
+    "@instantdb/webhooks": "1.0.49",
+    "h3": "^1.15.0",
+    "vue": "^3.5.0"
+  },
+  "peerDependenciesMeta": {
+    "@instantdb/admin": {
+      "optional": true
+    },
+    "@instantdb/webhooks": {
+      "optional": true
+    },
+    "h3": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@instantdb/core": "1.0.49",
+    "@instantdb/version": "1.0.49"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.2",
+    "@instantdb/admin": "1.0.49",
+    "@instantdb/platform": "1.0.49",
+    "@instantdb/resumable-stream": "1.0.49",
+    "@instantdb/vue": "1.0.49",
+    "@instantdb/webhooks": "1.0.49",
+    "@mszr/selenita": "^0.2.2",
+    "@types/node": "^25.9.3",
+    "@vue/test-utils": "^2.4.10",
+    "h3": "^1.15.3",
+    "jsdom": "^29.1.1",
+    "tshy": "^4.1.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6",
+    "vue": "^3.5.34"
+  }
+}