@mszr/idb-dux 1.0.0

package/dist/commonjs/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/commonjs/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/commonjs/webhooks/types.js

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

package/dist/commonjs/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/dist/esm/admin/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `@mszr/idb-dux/admin` — the full server surface.
+ *
+ * `init` owns `@instantdb/admin` (optional peer); shaped `query` +
+ * `subscribeQuery`, typed tx and debug, `asUser`, the pass-throughs, and
+ * `adminDb.webhooks`. Framework-agnostic, token-scoped, never bundled
+ * client-side.
+ *
+ * Spec: `../../../docs/dux-spec-admin.md`.
+ */
+export { IdbApiError, IdbError } from '../errors.js';
+export type { IdbIssue } from '../errors.js';
+export type { IdbRoomPresence } from '../schema/index.js';
+export { id, lookup } from '../tx/index.js';
+export { IdbAdminClient, init } from './init.js';
+export type { IdbAdminCheckResult, IdbAdminConfig, IdbAdminDebugQueryOpts, IdbAdminDebugTransactOpts, IdbAdminDebugTransactResult, IdbAdminImpersonation, IdbAdminTransactResult, IdbAuthUser, IdbQuerySessionInfo, IdbQuerySubscription, IdbQuerySubscriptionCallback, IdbQuerySubscriptionPayload, IdbReadableStream, IdbStorageDeleteResult, IdbStorageFileOpts, IdbStorageUploadResult, IdbStreamReadOpts, IdbStreamWriteOpts, IdbSubscriptionReadyState, IdbWritableStream, } from './types.js';
+export { createInstantRouteHandler, type InstantRouteHandlerBody, type InstantRouteHandlerPayloadByType, type InstantRouteHandlerType, } from '@instantdb/admin';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/admin/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AACpD,YAAY,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAE5C,YAAY,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAEzD,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAC3C,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChD,YAAY,EACV,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,yBAAyB,EACzB,2BAA2B,EAC3B,qBAAqB,EACrB,sBAAsB,EACtB,WAAW,EACX,mBAAmB,EACnB,oBAAoB,EACpB,4BAA4B,EAC5B,2BAA2B,EAC3B,iBAAiB,EACjB,sBAAsB,EACtB,kBAAkB,EAClB,sBAAsB,EACtB,iBAAiB,EACjB,kBAAkB,EAClB,yBAAyB,EACzB,iBAAiB,GAClB,MAAM,YAAY,CAAA;AAInB,OAAO,EACL,yBAAyB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,gCAAgC,EACrC,KAAK,uBAAuB,GAC7B,MAAM,kBAAkB,CAAA"}

package/dist/esm/admin/index.js

@@ -0,0 +1,21 @@
+/**
+ * `@mszr/idb-dux/admin` — the full server surface.
+ *
+ * `init` owns `@instantdb/admin` (optional peer); shaped `query` +
+ * `subscribeQuery`, typed tx and debug, `asUser`, the pass-throughs, and
+ * `adminDb.webhooks`. Framework-agnostic, token-scoped, never bundled
+ * client-side.
+ *
+ * Spec: `../../../docs/dux-spec-admin.md`.
+ */
+// The branded error family — `e instanceof IdbError` (the admin fetch path
+// throws `IdbApiError`, which extends `IdbError`).
+export { IdbApiError, IdbError } from '../errors.js';
+// Re-exports — official names kept at the boundary.
+export { id, lookup } from '../tx/index.js';
+export { IdbAdminClient, init } from './init.js';
+// The official first-party route handler, re-exported for apps that want the
+// official cookie shape ([dux-spec-nuxt.md §3]) — and the only path by which
+// `/nuxt` reaches it (the official package enters via this layer).
+export { createInstantRouteHandler, } from '@instantdb/admin';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/admin/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,2EAA2E;AAC3E,mDAAmD;AACnD,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAIpD,oDAAoD;AACpD,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAC3C,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAuBhD,6EAA6E;AAC7E,6EAA6E;AAC7E,mEAAmE;AACnE,OAAO,EACL,yBAAyB,GAI1B,MAAM,kBAAkB,CAAA","sourcesContent":["/**\n * `@mszr/idb-dux/admin` — the full server surface.\n *\n * `init` owns `@instantdb/admin` (optional peer); shaped `query` +\n * `subscribeQuery`, typed tx and debug, `asUser`, the pass-throughs, and\n * `adminDb.webhooks`. Framework-agnostic, token-scoped, never bundled\n * client-side.\n *\n * Spec: `../../../docs/dux-spec-admin.md`.\n */\n\n// The branded error family — `e instanceof IdbError` (the admin fetch path\n// throws `IdbApiError`, which extends `IdbError`).\nexport { IdbApiError, IdbError } from '../errors.js'\nexport type { IdbIssue } from '../errors.js'\n// Schema-rooted room type extractor — `rooms.getPresence` reads against it.\nexport type { IdbRoomPresence } from '../schema/index.js'\n// Re-exports — official names kept at the boundary.\nexport { id, lookup } from '../tx/index.js'\nexport { IdbAdminClient, init } from './init.js'\nexport type {\n  IdbAdminCheckResult,\n  IdbAdminConfig,\n  IdbAdminDebugQueryOpts,\n  IdbAdminDebugTransactOpts,\n  IdbAdminDebugTransactResult,\n  IdbAdminImpersonation,\n  IdbAdminTransactResult,\n  IdbAuthUser,\n  IdbQuerySessionInfo,\n  IdbQuerySubscription,\n  IdbQuerySubscriptionCallback,\n  IdbQuerySubscriptionPayload,\n  IdbReadableStream,\n  IdbStorageDeleteResult,\n  IdbStorageFileOpts,\n  IdbStorageUploadResult,\n  IdbStreamReadOpts,\n  IdbStreamWriteOpts,\n  IdbSubscriptionReadyState,\n  IdbWritableStream,\n} from './types.js'\n// The official first-party route handler, re-exported for apps that want the\n// official cookie shape ([dux-spec-nuxt.md §3]) — and the only path by which\n// `/nuxt` reaches it (the official package enters via this layer).\nexport {\n  createInstantRouteHandler,\n  type InstantRouteHandlerBody,\n  type InstantRouteHandlerPayloadByType,\n  type InstantRouteHandlerType,\n} from '@instantdb/admin'\n"]}

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

@@ -0,0 +1,67 @@
+/**
+ * `/admin` setup and the composed admin db. dux's `init` owns
+ * `@instantdb/admin` as an optional peer — apps never construct an official
+ * admin db to hand in ([dux-spec-admin.md §2]). `IdbAdminClient` wraps the
+ * official instance: the data plane is shaped, tx/debug carry the schema-typed
+ * machinery, and every pass-through keeps its official verb.
+ *
+ * `asUser` rebuilds the same wrapper over the scoped official instance, which
+ * is what keeps every treatment intact on the permission-scoped db.
+ */
+import type { InstantAdminDatabase } from '@instantdb/admin';
+import type { IdbQueryData, IdbQueryOptions, IdbValidQuery } from '../query/index.js';
+import type { IdbSchema } from '../schema/defineSchema.js';
+import type { IdbRegisteredSchema } from '../schema/register.js';
+import type { IdbTx, IdbTxChunkInput } from '../tx/index.js';
+import type { IdbWebhooks } from '../webhooks/index.js';
+import type { IdbAdminCheckResult, IdbAdminConfig, IdbAdminDebugQueryOpts, IdbAdminDebugTransactOpts, IdbAdminDebugTransactResult, IdbAdminImpersonation, IdbAdminTransactResult, IdbQuerySubscription, IdbQuerySubscriptionCallback } from './types.js';
+type OfficialDb<S extends IdbSchema> = InstantAdminDatabase<S, false>;
+/** The full server surface — the dux data plane over `@instantdb/admin`. */
+export declare class IdbAdminClient<S extends IdbSchema = IdbRegisteredSchema> {
+    #private;
+    /** The schema-typed tx chain — shared machinery with `/vue` ([root §5]). */
+    readonly tx: IdbTx<S>;
+    constructor(official: OfficialDb<S>, schema: IdbSchema | undefined);
+    /**
+     * Read once. Destructure top-level scopes directly — full shaping
+     * (`$only`/`$at`/`$as`/`$m`, array normalization, singularization) per the
+     * root spec. `opts` carries schema-typed `ruleParams`.
+     */
+    query: <const Q extends IdbValidQuery<Q, S>>(query: Q, opts?: IdbQueryOptions<S>) => Promise<IdbQueryData<Q, S>>;
+    /**
+     * Live-subscribe with the same per-emission shaping. Pass a callback, or
+     * iterate the handle with `for await`; `close()` stops it.
+     */
+    subscribeQuery: <const Q extends IdbValidQuery<Q, S>>(query: Q, cb?: IdbQuerySubscriptionCallback<Q, S>, opts?: IdbQueryOptions<S>) => IdbQuerySubscription<Q, S>;
+    /** Write data — the typed tx chain, schema-typed `ruleParams`, dot-path `.link`. */
+    transact: (chunks: IdbTxChunkInput<S> | IdbTxChunkInput<S>[]) => Promise<IdbAdminTransactResult>;
+    /**
+     * Like `query`, but returns permission-check debug info alongside the shaped
+     * result. Requires a user/guest context — call it on an `asUser` db.
+     */
+    debugQuery: <const Q extends IdbValidQuery<Q, S>>(query: Q, opts?: IdbAdminDebugQueryOpts<S>) => Promise<{
+        result: IdbQueryData<Q, S>;
+        checkResults: IdbAdminCheckResult[];
+    }>;
+    /** Like `transact`, but writes nothing — returns permission-check debug info. */
+    debugTransact: (chunks: IdbTxChunkInput<S> | IdbTxChunkInput<S>[], opts?: IdbAdminDebugTransactOpts) => Promise<IdbAdminDebugTransactResult>;
+    /** Scope every read/write to a user, guest, or token — same dux surface, permission-scoped. */
+    asUser: (opts: IdbAdminImpersonation) => IdbAdminClient<S>;
+    get auth(): OfficialDb<S>['auth'];
+    get storage(): OfficialDb<S>['storage'];
+    get streams(): OfficialDb<S>['streams'];
+    get rooms(): OfficialDb<S>['rooms'];
+    /** Webhook handling + management, admin-token wired ([§5]). */
+    get webhooks(): IdbWebhooks<S>;
+}
+/**
+ * Create the admin db. `appId` + `adminToken` + `schema` is the usual setup;
+ * the schema unlocks shaping and typed `ruleParams`.
+ *
+ * @example
+ *   const adminDb = init({ appId, adminToken, schema })
+ *   const { workspaces } = await adminDb.query(q({ workspaces: {} }))
+ */
+export declare function init<S extends IdbSchema = IdbRegisteredSchema>(config: IdbAdminConfig<S>): IdbAdminClient<S>;
+export {};
+//# sourceMappingURL=init.d.ts.map

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

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

package/dist/esm/admin/init.js

@@ -0,0 +1,81 @@
+import { init as adminInit } from '@instantdb/admin';
+import { shapeResult, shapingSchema, toWireQuery } from '../query/index.js';
+import { typedTx } from '../tx/index.js';
+import { runQuery, runSubscribeQuery } from './query.js';
+import { adminWebhooks } from './webhooks.js';
+/** The full server surface — the dux data plane over `@instantdb/admin`. */
+export class IdbAdminClient {
+    /** The schema-typed tx chain — shared machinery with `/vue` ([root §5]). */
+    tx = typedTx();
+    #official;
+    #schema;
+    #webhooks;
+    constructor(official, schema) {
+        this.#official = official;
+        this.#schema = shapingSchema(schema);
+    }
+    // ----- the data plane -----
+    /**
+     * Read once. Destructure top-level scopes directly — full shaping
+     * (`$only`/`$at`/`$as`/`$m`, array normalization, singularization) per the
+     * root spec. `opts` carries schema-typed `ruleParams`.
+     */
+    query = (query, opts) => runQuery(this.#official, this.#schema, query, opts);
+    /**
+     * Live-subscribe with the same per-emission shaping. Pass a callback, or
+     * iterate the handle with `for await`; `close()` stops it.
+     */
+    subscribeQuery = (query, cb, opts) => runSubscribeQuery(this.#official, this.#schema, query, cb, opts);
+    // ----- typed tx + debug -----
+    /** Write data — the typed tx chain, schema-typed `ruleParams`, dot-path `.link`. */
+    transact = (chunks) => this.#official.transact(chunks);
+    /**
+     * Like `query`, but returns permission-check debug info alongside the shaped
+     * result. Requires a user/guest context — call it on an `asUser` db.
+     */
+    debugQuery = async (query, opts) => {
+        const { result, checkResults } = await this.#official.debugQuery(toWireQuery(query), opts);
+        return {
+            result: shapeResult(result, query, this.#schema),
+            checkResults,
+        };
+    };
+    /** Like `transact`, but writes nothing — returns permission-check debug info. */
+    debugTransact = (chunks, opts) => this.#official.debugTransact(chunks, opts);
+    // ----- asUser + pass-throughs -----
+    /** Scope every read/write to a user, guest, or token — same dux surface, permission-scoped. */
+    asUser = (opts) => new IdbAdminClient(this.#official.asUser(opts), this.#schema);
+    get auth() {
+        return this.#official.auth;
+    }
+    get storage() {
+        return this.#official.storage;
+    }
+    get streams() {
+        return this.#official.streams;
+    }
+    get rooms() {
+        return this.#official.rooms;
+    }
+    /** Webhook handling + management, admin-token wired ([§5]). */
+    get webhooks() {
+        return (this.#webhooks ??= adminWebhooks({
+            appId: this.#official.config.appId,
+            adminToken: this.#official.config.adminToken,
+            apiURI: this.#official.config.apiURI,
+        }));
+    }
+}
+/**
+ * Create the admin db. `appId` + `adminToken` + `schema` is the usual setup;
+ * the schema unlocks shaping and typed `ruleParams`.
+ *
+ * @example
+ *   const adminDb = init({ appId, adminToken, schema })
+ *   const { workspaces } = await adminDb.query(q({ workspaces: {} }))
+ */
+export function init(config) {
+    const official = adminInit(config);
+    return new IdbAdminClient(official, config.schema);
+}
+//# sourceMappingURL=init.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../../src/admin/init.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `/admin` setup and the composed admin db. dux's `init` owns\n * `@instantdb/admin` as an optional peer — apps never construct an official\n * admin db to hand in ([dux-spec-admin.md §2]). `IdbAdminClient` wraps the\n * official instance: the data plane is shaped, tx/debug carry the schema-typed\n * machinery, and every pass-through keeps its official verb.\n *\n * `asUser` rebuilds the same wrapper over the scoped official instance, which\n * is what keeps every treatment intact on the permission-scoped db.\n */\nimport type { InstantAdminDatabase } from '@instantdb/admin'\nimport type {\n  IdbQueryData,\n  IdbQueryOptions,\n  IdbValidQuery,\n} from '../query/index.js'\nimport type { IdbSchema } from '../schema/defineSchema.js'\nimport type { IdbRegisteredSchema } from '../schema/register.js'\nimport type { IdbTx, IdbTxChunkInput } from '../tx/index.js'\nimport type { IdbWebhooks } from '../webhooks/index.js'\nimport type {\n  IdbAdminCheckResult,\n  IdbAdminConfig,\n  IdbAdminDebugQueryOpts,\n  IdbAdminDebugTransactOpts,\n  IdbAdminDebugTransactResult,\n  IdbAdminImpersonation,\n  IdbAdminTransactResult,\n  IdbQuerySubscription,\n  IdbQuerySubscriptionCallback,\n} from './types.js'\nimport { init as adminInit } from '@instantdb/admin'\nimport { shapeResult, shapingSchema, toWireQuery } from '../query/index.js'\nimport { typedTx } from '../tx/index.js'\nimport { runQuery, runSubscribeQuery } from './query.js'\nimport { adminWebhooks } from './webhooks.js'\n\ntype OfficialDb<S extends IdbSchema> = InstantAdminDatabase<S, false>\n\n/** The full server surface — the dux data plane over `@instantdb/admin`. */\nexport class IdbAdminClient<S extends IdbSchema = IdbRegisteredSchema> {\n  /** The schema-typed tx chain — shared machinery with `/vue` ([root §5]). */\n  public readonly tx: IdbTx<S> = typedTx<S>()\n\n  readonly #official: OfficialDb<S>\n  readonly #schema: IdbSchema\n  #webhooks: IdbWebhooks<S> | undefined\n\n  constructor(official: OfficialDb<S>, schema: IdbSchema | undefined) {\n    this.#official = official\n    this.#schema = shapingSchema(schema)\n  }\n\n  // ----- the data plane -----\n\n  /**\n   * Read once. Destructure top-level scopes directly — full shaping\n   * (`$only`/`$at`/`$as`/`$m`, array normalization, singularization) per the\n   * root spec. `opts` carries schema-typed `ruleParams`.\n   */\n  query = <const Q extends IdbValidQuery<Q, S>>(\n    query: Q,\n    opts?: IdbQueryOptions<S>,\n  ): Promise<IdbQueryData<Q, S>> =>\n    runQuery(this.#official, this.#schema, query as Record<string, any>, opts) as Promise<\n      IdbQueryData<Q, S>\n    >\n\n  /**\n   * Live-subscribe with the same per-emission shaping. Pass a callback, or\n   * iterate the handle with `for await`; `close()` stops it.\n   */\n  subscribeQuery = <const Q extends IdbValidQuery<Q, S>>(\n    query: Q,\n    cb?: IdbQuerySubscriptionCallback<Q, S>,\n    opts?: IdbQueryOptions<S>,\n  ): IdbQuerySubscription<Q, S> =>\n    runSubscribeQuery<Q, S>(this.#official, this.#schema, query as Record<string, any>, cb, opts)\n\n  // ----- typed tx + debug -----\n\n  /** Write data — the typed tx chain, schema-typed `ruleParams`, dot-path `.link`. */\n  transact = (chunks: IdbTxChunkInput<S> | IdbTxChunkInput<S>[]): Promise<IdbAdminTransactResult> =>\n    this.#official.transact(chunks as any)\n\n  /**\n   * Like `query`, but returns permission-check debug info alongside the shaped\n   * result. Requires a user/guest context — call it on an `asUser` db.\n   */\n  debugQuery = async <const Q extends IdbValidQuery<Q, S>>(\n    query: Q,\n    opts?: IdbAdminDebugQueryOpts<S>,\n  ): Promise<{ result: IdbQueryData<Q, S>, checkResults: IdbAdminCheckResult[] }> => {\n    const { result, checkResults } = await this.#official.debugQuery(\n      toWireQuery(query as Record<string, any>) as any,\n      opts as any,\n    )\n    return {\n      result: shapeResult(result, query as Record<string, any>, this.#schema) as IdbQueryData<Q, S>,\n      checkResults,\n    }\n  }\n\n  /** Like `transact`, but writes nothing — returns permission-check debug info. */\n  debugTransact = (\n    chunks: IdbTxChunkInput<S> | IdbTxChunkInput<S>[],\n    opts?: IdbAdminDebugTransactOpts,\n  ): Promise<IdbAdminDebugTransactResult> =>\n    this.#official.debugTransact(chunks as any, opts as any)\n\n  // ----- asUser + pass-throughs -----\n\n  /** Scope every read/write to a user, guest, or token — same dux surface, permission-scoped. */\n  asUser = (opts: IdbAdminImpersonation): IdbAdminClient<S> =>\n    new IdbAdminClient<S>(this.#official.asUser(opts) as OfficialDb<S>, this.#schema)\n\n  get auth(): OfficialDb<S>['auth'] {\n    return this.#official.auth\n  }\n\n  get storage(): OfficialDb<S>['storage'] {\n    return this.#official.storage\n  }\n\n  get streams(): OfficialDb<S>['streams'] {\n    return this.#official.streams\n  }\n\n  get rooms(): OfficialDb<S>['rooms'] {\n    return this.#official.rooms\n  }\n\n  /** Webhook handling + management, admin-token wired ([§5]). */\n  get webhooks(): IdbWebhooks<S> {\n    return (this.#webhooks ??= adminWebhooks<S>({\n      appId: this.#official.config.appId,\n      adminToken: this.#official.config.adminToken,\n      apiURI: this.#official.config.apiURI,\n    }))\n  }\n}\n\n/**\n * Create the admin db. `appId` + `adminToken` + `schema` is the usual setup;\n * the schema unlocks shaping and typed `ruleParams`.\n *\n * @example\n *   const adminDb = init({ appId, adminToken, schema })\n *   const { workspaces } = await adminDb.query(q({ workspaces: {} }))\n */\nexport function init<S extends IdbSchema = IdbRegisteredSchema>(\n  config: IdbAdminConfig<S>,\n): IdbAdminClient<S> {\n  const official = adminInit<S, false>(config as any) as OfficialDb<S>\n  return new IdbAdminClient<S>(official, config.schema)\n}\n"]}

package/dist/esm/admin/query.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The admin data plane — `query` and `subscribeQuery` shaped through the same
+ * `shapeResult` the client uses ([dux-spec-admin.md §3]). The admin surface
+ * contains zero shaping logic of its own: it wires the query out (`toWireQuery`)
+ * and reshapes what comes back (`shapeResult`), so a one-shot and a
+ * subscription of the same query deliver the same shape by construction.
+ */
+import type { InstantAdminDatabase } from '@instantdb/admin';
+import type { IdbSchema } from '../schema/defineSchema.js';
+import type { IdbQuerySubscription, IdbQuerySubscriptionCallback } from './types.js';
+type AnyRecord = Record<string, any>;
+type OfficialDb = InstantAdminDatabase<any, false>;
+/** Run a one-shot read and shape the result. */
+export declare function runQuery(official: OfficialDb, schema: IdbSchema, query: AnyRecord, opts: AnyRecord | undefined): Promise<AnyRecord>;
+/**
+ * Subscribe, shaping each emission. The official callback and async-iterator
+ * contracts are preserved; only `data` is reshaped on the way through.
+ */
+export declare function runSubscribeQuery<Q, S extends IdbSchema>(official: OfficialDb, schema: IdbSchema, query: AnyRecord, cb: IdbQuerySubscriptionCallback<Q, S> | undefined, opts: AnyRecord | undefined): IdbQuerySubscription<Q, S>;
+export {};
+//# sourceMappingURL=query.d.ts.map

package/dist/esm/admin/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../src/admin/query.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AAC1D,OAAO,KAAK,EACV,oBAAoB,EACpB,4BAA4B,EAE7B,MAAM,YAAY,CAAA;AAGnB,KAAK,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;AACpC,KAAK,UAAU,GAAG,oBAAoB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;AAalD,gDAAgD;AAChD,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,UAAU,EACpB,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,SAAS,GAAG,SAAS,GAC1B,OAAO,CAAC,SAAS,CAAC,CAGpB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,CAAC,SAAS,SAAS,EACtD,QAAQ,EAAE,UAAU,EACpB,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,SAAS,EAChB,EAAE,EAAE,4BAA4B,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,SAAS,EAClD,IAAI,EAAE,SAAS,GAAG,SAAS,GAC1B,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,CA2B5B"}

package/dist/esm/admin/query.js

@@ -0,0 +1,42 @@
+import { shapeResult, toWireQuery } from '../query/index.js';
+/** Shape one subscription emission's `data`, leaving the error arm untouched. */
+function shapePayload(payload, query, schema) {
+    if (payload.type !== 'ok')
+        return payload;
+    return { ...payload, data: shapeResult(payload.data, query, schema) };
+}
+/** Run a one-shot read and shape the result. */
+export async function runQuery(official, schema, query, opts) {
+    const data = await official.query(toWireQuery(query), opts);
+    return shapeResult(data, query, schema);
+}
+/**
+ * Subscribe, shaping each emission. The official callback and async-iterator
+ * contracts are preserved; only `data` is reshaped on the way through.
+ */
+export function runSubscribeQuery(official, schema, query, cb, opts) {
+    const wire = toWireQuery(query);
+    const wrappedCb = cb
+        ? (payload) => cb(shapePayload(payload, query, schema))
+        : undefined;
+    const sub = official.subscribeQuery(wire, wrappedCb, opts);
+    async function* shaped() {
+        for await (const payload of sub)
+            yield shapePayload(payload, query, schema);
+    }
+    return {
+        close: () => sub.close(),
+        [Symbol.iterator]: () => sub[Symbol.iterator](),
+        [Symbol.asyncIterator]: () => shaped(),
+        get readyState() {
+            return sub.readyState;
+        },
+        get isClosed() {
+            return sub.isClosed;
+        },
+        get sessionInfo() {
+            return sub.sessionInfo;
+        },
+    };
+}
+//# sourceMappingURL=query.js.map

package/dist/esm/admin/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../../../src/admin/query.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAK5D,iFAAiF;AACjF,SAAS,YAAY,CACnB,OAAkB,EAClB,KAAgB,EAChB,MAAiB;IAEjB,IAAI,OAAO,CAAC,IAAI,KAAK,IAAI;QACvB,OAAO,OAAO,CAAA;IAChB,OAAO,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,CAAA;AACvE,CAAC;AAED,gDAAgD;AAChD,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,QAAoB,EACpB,MAAiB,EACjB,KAAgB,EAChB,IAA2B;IAE3B,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,WAAW,CAAC,KAAK,CAAQ,EAAE,IAAW,CAAC,CAAA;IACzE,OAAO,WAAW,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,CAAA;AACzC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAoB,EACpB,MAAiB,EACjB,KAAgB,EAChB,EAAkD,EAClD,IAA2B;IAE3B,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,CAAA;IAC/B,MAAM,SAAS,GAAG,EAAE;QAClB,CAAC,CAAC,CAAC,OAAkB,EAAE,EAAE,CACrB,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,CAAsC,CAAC;QACjF,CAAC,CAAC,SAAS,CAAA;IACb,MAAM,GAAG,GAAG,QAAQ,CAAC,cAAc,CAAC,IAAW,EAAE,SAAgB,EAAE,IAAW,CAAC,CAAA;IAE/E,KAAK,SAAS,CAAC,CAAC,MAAM;QACpB,IAAI,KAAK,EAAE,MAAM,OAAO,IAAI,GAAG;YAC7B,MAAM,YAAY,CAAC,OAAoB,EAAE,KAAK,EAAE,MAAM,CAAsC,CAAA;IAChG,CAAC;IAED,OAAO;QACL,KAAK,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,KAAK,EAAE;QACxB,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE;QAC/C,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE;QACtC,IAAI,UAAU;YACZ,OAAO,GAAG,CAAC,UAAU,CAAA;QACvB,CAAC;QACD,IAAI,QAAQ;YACV,OAAO,GAAG,CAAC,QAAQ,CAAA;QACrB,CAAC;QACD,IAAI,WAAW;YACb,OAAO,GAAG,CAAC,WAAW,CAAA;QACxB,CAAC;KACF,CAAA;AACH,CAAC","sourcesContent":["/**\n * The admin data plane — `query` and `subscribeQuery` shaped through the same\n * `shapeResult` the client uses ([dux-spec-admin.md §3]). The admin surface\n * contains zero shaping logic of its own: it wires the query out (`toWireQuery`)\n * and reshapes what comes back (`shapeResult`), so a one-shot and a\n * subscription of the same query deliver the same shape by construction.\n */\nimport type { InstantAdminDatabase } from '@instantdb/admin'\nimport type { IdbSchema } from '../schema/defineSchema.js'\nimport type {\n  IdbQuerySubscription,\n  IdbQuerySubscriptionCallback,\n  IdbQuerySubscriptionPayload,\n} from './types.js'\nimport { shapeResult, toWireQuery } from '../query/index.js'\n\ntype AnyRecord = Record<string, any>\ntype OfficialDb = InstantAdminDatabase<any, false>\n\n/** Shape one subscription emission's `data`, leaving the error arm untouched. */\nfunction shapePayload(\n  payload: AnyRecord,\n  query: AnyRecord,\n  schema: IdbSchema,\n): AnyRecord {\n  if (payload.type !== 'ok')\n    return payload\n  return { ...payload, data: shapeResult(payload.data, query, schema) }\n}\n\n/** Run a one-shot read and shape the result. */\nexport async function runQuery(\n  official: OfficialDb,\n  schema: IdbSchema,\n  query: AnyRecord,\n  opts: AnyRecord | undefined,\n): Promise<AnyRecord> {\n  const data = await official.query(toWireQuery(query) as any, opts as any)\n  return shapeResult(data, query, schema)\n}\n\n/**\n * Subscribe, shaping each emission. The official callback and async-iterator\n * contracts are preserved; only `data` is reshaped on the way through.\n */\nexport function runSubscribeQuery<Q, S extends IdbSchema>(\n  official: OfficialDb,\n  schema: IdbSchema,\n  query: AnyRecord,\n  cb: IdbQuerySubscriptionCallback<Q, S> | undefined,\n  opts: AnyRecord | undefined,\n): IdbQuerySubscription<Q, S> {\n  const wire = toWireQuery(query)\n  const wrappedCb = cb\n    ? (payload: AnyRecord) =>\n        cb(shapePayload(payload, query, schema) as IdbQuerySubscriptionPayload<Q, S>)\n    : undefined\n  const sub = official.subscribeQuery(wire as any, wrappedCb as any, opts as any)\n\n  async function* shaped(): AsyncIterableIterator<IdbQuerySubscriptionPayload<Q, S>> {\n    for await (const payload of sub)\n      yield shapePayload(payload as AnyRecord, query, schema) as IdbQuerySubscriptionPayload<Q, S>\n  }\n\n  return {\n    close: () => sub.close(),\n    [Symbol.iterator]: () => sub[Symbol.iterator](),\n    [Symbol.asyncIterator]: () => shaped(),\n    get readyState() {\n      return sub.readyState\n    },\n    get isClosed() {\n      return sub.isClosed\n    },\n    get sessionInfo() {\n      return sub.sessionInfo\n    },\n  }\n}\n"]}

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

@@ -0,0 +1,124 @@
+/**
+ * The `/admin` boundary module — every rename from `@instantdb/admin` lives
+ * here and nowhere else (wrap-and-map, dux-spec-workspace.md §5.1). Two kinds
+ * of type live side by side:
+ *
+ * - **aliases** for shapes dux keeps verbatim (`IdbAuthUser`, the storage and
+ *   stream option/result types, the debug check result): pure renames over the
+ *   official types, so upstream changes ride in for free and break loudly at
+ *   the wrap points.
+ * - **authored-fresh** for the subscription surface (`IdbQuerySubscription` and
+ *   its payload/callback): a subscription emits the *shaped* data plane, the
+ *   same `IdbQueryData<Q>` `query` returns — so its payload is dux-typed, not a
+ *   pass-through of the official `InstaQLResponse` shape.
+ *
+ * Everything is registration-typed — no schema generic at any call site, with
+ * the trailing escape-hatch param for multi-schema tools.
+ */
+import type { CreateReadStreamOpts, CreateWriteStreamOpts, DebugCheckResult, DeleteFileResponse, FileOpts, ImpersonationOpts, InstantAdminDatabase, InstantAPIError, InstantConfig, SubscriptionReadyState, UploadFileResponse, User } from '@instantdb/admin';
+import type { IdbQueryData, IdbQueryPageInfo } from '../query/index.js';
+import type { IdbSchema } from '../schema/defineSchema.js';
+import type { IdbRegisteredSchema } from '../schema/register.js';
+/**
+ * `init` config — everything the official admin SDK supports, minus
+ * `useDateObjects` (dux types `i.date()` fields as the wire format on every
+ * surface) and with `schema` typed as your registered `S`. The schema unlocks
+ * shaping and typed `ruleParams`; `apiURI` is for self-hosting.
+ */
+export type IdbAdminConfig<S extends IdbSchema = IdbRegisteredSchema> = Omit<InstantConfig<S, false>, 'useDateObjects' | 'schema'> & {
+    schema?: S;
+};
+/** The authenticated user (official `User`). */
+export type IdbAuthUser = User;
+/** The scope `asUser` accepts — a user email, an auth token, or a guest. */
+export type IdbAdminImpersonation = ImpersonationOpts;
+/** Per-file upload metadata (official `FileOpts`). */
+export type IdbStorageFileOpts = FileOpts;
+/** The result of a storage upload. */
+export type IdbStorageUploadResult = UploadFileResponse;
+/** The result of a storage delete. */
+export type IdbStorageDeleteResult = DeleteFileResponse;
+/** Options for opening a read stream. */
+export type IdbStreamReadOpts = CreateReadStreamOpts;
+/** Options for opening a write stream. */
+export type IdbStreamWriteOpts = CreateWriteStreamOpts;
+type AdminStreams = InstantAdminDatabase<IdbSchema, false>['streams'];
+/** A live readable stream of string chunks. */
+export type IdbReadableStream = ReturnType<AdminStreams['createReadStream']>;
+/** A live writable stream of string chunks. */
+export type IdbWritableStream = ReturnType<AdminStreams['createWriteStream']>;
+/** One entity's permission-check result from `debugQuery` (official `DebugCheckResult`). */
+export type IdbAdminCheckResult = DebugCheckResult;
+/** The summary `debugTransact` returns — tx id + an all-checks-ok flag. */
+export type IdbAdminDebugTransactResult = Awaited<ReturnType<InstantAdminDatabase<IdbSchema, false>['debugTransact']>>;
+/** The acknowledgement a write returns. */
+export type IdbAdminTransactResult = Awaited<ReturnType<InstantAdminDatabase<IdbSchema, false>['transact']>>;
+/** Whether a subscription's connection is open, connecting, or closed. */
+export type IdbSubscriptionReadyState = SubscriptionReadyState;
+/**
+ * Debug info about a subscription's session. Mirrors the official
+ * `SubscribeQuerySessionInfo` shape, authored fresh because that type isn't
+ * separately exported (the surrounding payload generic can't be instantiated
+ * without a concrete query to satisfy its `ValidQuery` constraint).
+ */
+export interface IdbQuerySessionInfo {
+    machineId: string;
+    sessionId: string;
+}
+/**
+ * One emission from `subscribeQuery` — `data` is the shaped data plane
+ * (`IdbQueryData<Q>`, identical to `query`'s return), so a subscription and a
+ * one-shot of the same query deliver the same shape.
+ */
+export type IdbQuerySubscriptionPayload<Q, S extends IdbSchema = IdbRegisteredSchema> = {
+    type: 'ok';
+    data: IdbQueryData<Q, S>;
+    pageInfo: IdbQueryPageInfo<Q> | undefined;
+    sessionInfo: IdbQuerySessionInfo | null;
+} | {
+    type: 'error';
+    error: InstantAPIError;
+    readyState: IdbSubscriptionReadyState;
+    isClosed: boolean;
+    sessionInfo: IdbQuerySessionInfo | null;
+};
+/** The callback form of `subscribeQuery`. */
+export type IdbQuerySubscriptionCallback<Q, S extends IdbSchema = IdbRegisteredSchema> = (payload: IdbQuerySubscriptionPayload<Q, S>) => void;
+/**
+ * A live subscription handle (official `SubscribeQueryResponse`, payloads
+ * dux-shaped). Iterate it with `for await`, or pass a callback to
+ * `subscribeQuery`; `close()` stops it.
+ */
+export interface IdbQuerySubscription<Q, S extends IdbSchema = IdbRegisteredSchema> {
+    /** Stop the subscription and close the connection. */
+    close: () => void;
+    /** Guards against synchronous iteration. */
+    [Symbol.iterator]: () => never;
+    /** Async iterator of shaped query payloads. */
+    [Symbol.asyncIterator]: () => AsyncIterableIterator<IdbQuerySubscriptionPayload<Q, S>>;
+    /** Ready state of the connection. */
+    readonly readyState: IdbSubscriptionReadyState;
+    /** `true` once closed and no more payloads will arrive. */
+    readonly isClosed: boolean;
+    /** Session debug info; `null` while the session initializes. */
+    readonly sessionInfo: IdbQuerySessionInfo | null;
+}
+/**
+ * `debugQuery` options — typed `ruleParams` plus the rules/ip/origin overrides
+ * the permission inspector accepts.
+ */
+export interface IdbAdminDebugQueryOpts<S extends IdbSchema = IdbRegisteredSchema> {
+    ruleParams?: import('../query/index.js').IdbSchemaRuleParams<S>;
+    rules?: unknown;
+    ip?: string | null | undefined;
+    origin?: string | null | undefined;
+    cardinalityInference?: boolean;
+}
+/** `debugTransact` options — rules/ip/origin overrides for the inspector. */
+export interface IdbAdminDebugTransactOpts {
+    rules?: unknown;
+    ip?: string | null | undefined;
+    origin?: string | null | undefined;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/esm/admin/types.js

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