@mszr/idb-dux 1.0.0

package/LICENSE

@@ -0,0 +1,194 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other transformations
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or designated in writing by the copyright owner as "Not a
+      Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by the combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a cross-claim
+      or counterclaim in a lawsuit) alleging that the Work or any
+      Contribution embodied within the Work constitutes direct or contributory
+      patent infringement, then any patent licenses granted to You under
+      this License for that Work shall terminate as of the date such
+      litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or in addition to the
+          NOTICE text from the Work, provided that such additional
+          attribution notices cannot be construed as modifying the License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, copy, modify, merge,
+      publish, distribute, sublicense, and/or sell copies of the
+      Contribution, either on an inclusive basis or on an exclusive
+      agreement, as You see fit.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may offer such
+      obligations only on Your own behalf and on Your sole responsibility,
+      not on behalf of any other Contributor, and only if You agree to
+      indemnify, defend, and hold each Contributor harmless for any
+      liability incurred by, or claims asserted against, such Contributor
+      by reason of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format in question. Please also
+      include a URL to the license text so that recipients of your work
+      can look it up easily.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,84 @@
+# @mszr/idb-dux
+
+**A DX/UX-first reimagining of the InstantDB developer experience.**
+
+dux keeps Instant's backend intact but rebuilds the authoring and client surface around a single question: *what would feel most delightful to use?*
+
+## Highlights
+
+🔮 **Typed perms authoring** — `definePerms` replaces stringly-typed CEL with a schema-aware TypeScript surface. Write rules against real field names and link traversals; it compiles to exactly what Instant accepts. Completions, narrowing, and type errors on the authoring side — before anything reaches the backend.
+
+⛱️ **One registration, project-wide types** — register your schema once next to `defineSchema` and every `Idb*` type utility knows it project-wide. No `SomeUtil<AppSchema, 'namespace', { /* finally my shape */ }>` threading — just `IdbQueryEntity<'todos', { assignee: {} }>`.
+
+🍬 **`q` — a typed query builder that goes anywhere** — write queries in stores, composables, utilities, and factory callbacks and get completions, field validation, and operator checking at every level. The query object is fully typed before it ever reaches a `useQuery` or `query` call.
+
+👽 **Typed tx and linking** — official linking requires `lookup('email', val)` with no validation on the field name or value type. dux's `.link()` knows your schema: link labels are suggested, and field-matched linking (`.link({ 'assignee.email': val })`) is narrowed to the linked namespace's field types, and validated.
+
+🎈 **Errors at the cursor, not the console** — the wrong field name, invalid operator, or unknown namespace underlines exactly where the mistake is, with a message that says what's wrong and points you in the right direction. Completions and diagnostics are regression-tested with `selenita` so your DX has the same guarantees as runtime behaviors.
+
+💫 **Results without ceremony** — query scopes arrive typed and normalized: arrays are never `undefined`; `$only` narrows a scope to `T | undefined` so you never reach for `?.[0]`; `$as` and `$m` let you reshape in the query instead of after it.
+
+👻 **SSR-resilient by default** — every hook returns safe inert state on the server and activates full subscriptions on the client. Zero configuration. Full support incoming when upstream marks SSR stable.
+
+## Install
+
+```bash
+npm install @mszr/idb-dux
+```
+
+`@instantdb/core` comes along as a dependency. Everything else is an **optional peer** you add only for the entrypoints you use:
+
+```bash
+npm install vue                          # for /vue
+npm install @instantdb/admin             # for /admin
+npm install @instantdb/webhooks          # for /webhooks
+npm install @instantdb/admin @instantdb/webhooks h3   # for /nuxt
+```
+
+The root and `/perms` need no peers.
+
+## The shape
+
+One package, six entrypoints. The root is the framework-agnostic foundation; everything else is a thin overlay on it.
+
+| Entrypoint | What it is |
+|---|---|
+| `@mszr/idb-dux` | schema authoring (`defineSchema`, `i`), query authoring (`q`), typed tx, the `Idb*` type utilities |
+| `@mszr/idb-dux/perms` | typed CEL authoring (`definePerms`) — compiles to the rules object Instant already accepts |
+| `@mszr/idb-dux/admin` | the full server surface over `@instantdb/admin` |
+| `@mszr/idb-dux/webhooks` | webhook handling + management — admin-free by design |
+| `@mszr/idb-dux/vue` | the Vue client: `init`, `defineDb`, the enhanced db, components — SSR-resilient by default |
+| `@mszr/idb-dux/nuxt` | utils for nuxt server: `defineServerKit`, `defineAuthSyncHandler`, `defineWebhookHandler` |
+
+`sideEffects: false` and disjoint module graphs mean a Vue-only app pays zero bytes for the server planes, and a webhook-only worker installs nothing from the Vue stack. Subpath-only dependencies (`vue`, `h3`, `@instantdb/admin`, `@instantdb/webhooks`) are optional peers — you install only what your entrypoints need.
+
+## A taste
+
+```ts
+// Queries destructure directly — no unwrapping, no ?? [] massaging
+const { workspace, todos } = db.useQuery({
+  workspaces: { $: { where: { id: workspaceId }, $only } }, // Workspace | undefined (automagically singularized, customizable)
+  todos: {}, // Todo[] — never undefined
+})
+```
+
+```ts
+// One declaration; every Idb* type utility and `q` know your schema project-wide
+declare module '@mszr/idb-dux' {
+  interface IdbRegister { schema: typeof schema }
+}
+```
+
+## The one hard contract
+
+**dux owes behavioral compatibility to Instant's backend, not API compatibility to Instant's SDKs.** Everything dux emits — schema shapes for the CLI, perms CEL, wire queries — is something Instant already accepts. Inside that envelope, dux is free to reimagine the ergonomics.
+
+## Development
+
+The public `idb-dux` repo is the package and demo face, not the standalone development workspace. Build, test, release, and demo-resolution commands live in the dux maintainer workspace inside the Instant fork: `client/packages/dux` ([public link](https://github.com/mareszhar/instant/tree/dux/client/packages/dux) | [local fork path](..)).
+
+## Docs
+
+- `dux-vision.md` ([public link](https://github.com/mareszhar/instant/blob/dux/client/packages/dux/docs/dux-vision.md) | [local fork path](../docs/dux-vision.md)) — philosophy, architecture, scope, roadmap
+- `dux-conventions.md` ([public link](https://github.com/mareszhar/instant/blob/dux/client/packages/dux/docs/dux-conventions.md) | [local fork path](../docs/dux-conventions.md)) — vocabulary and naming law
+- `dux-spec-*.md` ([public link](https://github.com/mareszhar/instant/tree/dux/client/packages/dux/docs) | [local fork path](../docs)) — one spec per entrypoint, plus the maintainer manual

package/dist/commonjs/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/commonjs/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/commonjs/admin/index.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * `@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`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createInstantRouteHandler = exports.init = exports.IdbAdminClient = exports.lookup = exports.id = exports.IdbError = exports.IdbApiError = void 0;
+// The branded error family — `e instanceof IdbError` (the admin fetch path
+// throws `IdbApiError`, which extends `IdbError`).
+var errors_js_1 = require("../errors.js");
+Object.defineProperty(exports, "IdbApiError", { enumerable: true, get: function () { return errors_js_1.IdbApiError; } });
+Object.defineProperty(exports, "IdbError", { enumerable: true, get: function () { return errors_js_1.IdbError; } });
+// Re-exports — official names kept at the boundary.
+var index_js_1 = require("../tx/index.js");
+Object.defineProperty(exports, "id", { enumerable: true, get: function () { return index_js_1.id; } });
+Object.defineProperty(exports, "lookup", { enumerable: true, get: function () { return index_js_1.lookup; } });
+var init_js_1 = require("./init.js");
+Object.defineProperty(exports, "IdbAdminClient", { enumerable: true, get: function () { return init_js_1.IdbAdminClient; } });
+Object.defineProperty(exports, "init", { enumerable: true, get: function () { return init_js_1.init; } });
+// 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).
+var admin_1 = require("@instantdb/admin");
+Object.defineProperty(exports, "createInstantRouteHandler", { enumerable: true, get: function () { return admin_1.createInstantRouteHandler; } });
+//# sourceMappingURL=index.js.map

package/dist/commonjs/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,0CAAoD;AAA3C,wGAAA,WAAW,OAAA;AAAE,qGAAA,QAAQ,OAAA;AAI9B,oDAAoD;AACpD,2CAA2C;AAAlC,8FAAA,EAAE,OAAA;AAAE,kGAAA,MAAM,OAAA;AACnB,qCAAgD;AAAvC,yGAAA,cAAc,OAAA;AAAE,+FAAA,IAAI,OAAA;AAuB7B,6EAA6E;AAC7E,6EAA6E;AAC7E,mEAAmE;AACnE,0CAKyB;AAJvB,kHAAA,yBAAyB,OAAA","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/commonjs/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/commonjs/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/commonjs/admin/init.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdbAdminClient = void 0;
+exports.init = init;
+const admin_1 = require("@instantdb/admin");
+const index_js_1 = require("../query/index.js");
+const index_js_2 = require("../tx/index.js");
+const query_js_1 = require("./query.js");
+const webhooks_js_1 = require("./webhooks.js");
+/** The full server surface — the dux data plane over `@instantdb/admin`. */
+class IdbAdminClient {
+    /** The schema-typed tx chain — shared machinery with `/vue` ([root §5]). */
+    tx = (0, index_js_2.typedTx)();
+    #official;
+    #schema;
+    #webhooks;
+    constructor(official, schema) {
+        this.#official = official;
+        this.#schema = (0, index_js_1.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) => (0, query_js_1.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) => (0, query_js_1.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((0, index_js_1.toWireQuery)(query), opts);
+        return {
+            result: (0, index_js_1.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 ??= (0, webhooks_js_1.adminWebhooks)({
+            appId: this.#official.config.appId,
+            adminToken: this.#official.config.adminToken,
+            apiURI: this.#official.config.apiURI,
+        }));
+    }
+}
+exports.IdbAdminClient = IdbAdminClient;
+/**
+ * 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: {} }))
+ */
+function init(config) {
+    const official = (0, admin_1.init)(config);
+    return new IdbAdminClient(official, config.schema);
+}
+//# sourceMappingURL=init.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../../src/admin/init.ts"],"names":[],"mappings":";;;AAsJA,oBAKC;AA5HD,4CAAoD;AACpD,gDAA2E;AAC3E,6CAAwC;AACxC,yCAAwD;AACxD,+CAA6C;AAI7C,4EAA4E;AAC5E,MAAa,cAAc;IACzB,4EAA4E;IAC5D,EAAE,GAAa,IAAA,kBAAO,GAAK,CAAA;IAElC,SAAS,CAAe;IACxB,OAAO,CAAW;IAC3B,SAAS,CAA4B;IAErC,YAAY,QAAuB,EAAE,MAA6B;QAChE,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAA;QACzB,IAAI,CAAC,OAAO,GAAG,IAAA,wBAAa,EAAC,MAAM,CAAC,CAAA;IACtC,CAAC;IAED,6BAA6B;IAE7B;;;;OAIG;IACH,KAAK,GAAG,CACN,KAAQ,EACR,IAAyB,EACI,EAAE,CAC/B,IAAA,mBAAQ,EAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,OAAO,EAAE,KAA4B,EAAE,IAAI,CAExE,CAAA;IAEH;;;OAGG;IACH,cAAc,GAAG,CACf,KAAQ,EACR,EAAuC,EACvC,IAAyB,EACG,EAAE,CAC9B,IAAA,4BAAiB,EAAO,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,OAAO,EAAE,KAA4B,EAAE,EAAE,EAAE,IAAI,CAAC,CAAA;IAE/F,+BAA+B;IAE/B,oFAAoF;IACpF,QAAQ,GAAG,CAAC,MAAiD,EAAmC,EAAE,CAChG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,MAAa,CAAC,CAAA;IAExC;;;OAGG;IACH,UAAU,GAAG,KAAK,EAChB,KAAQ,EACR,IAAgC,EAC8C,EAAE;QAChF,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,UAAU,CAC9D,IAAA,sBAAW,EAAC,KAA4B,CAAQ,EAChD,IAAW,CACZ,CAAA;QACD,OAAO;YACL,MAAM,EAAE,IAAA,sBAAW,EAAC,MAAM,EAAE,KAA4B,EAAE,IAAI,CAAC,OAAO,CAAuB;YAC7F,YAAY;SACb,CAAA;IACH,CAAC,CAAA;IAED,iFAAiF;IACjF,aAAa,GAAG,CACd,MAAiD,EACjD,IAAgC,EACM,EAAE,CACxC,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,MAAa,EAAE,IAAW,CAAC,CAAA;IAE1D,qCAAqC;IAErC,+FAA+F;IAC/F,MAAM,GAAG,CAAC,IAA2B,EAAqB,EAAE,CAC1D,IAAI,cAAc,CAAI,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAkB,EAAE,IAAI,CAAC,OAAO,CAAC,CAAA;IAEnF,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAA;IAC5B,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAA;IAC/B,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAA;IAC/B,CAAC;IAED,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAA;IAC7B,CAAC;IAED,+DAA+D;IAC/D,IAAI,QAAQ;QACV,OAAO,CAAC,IAAI,CAAC,SAAS,KAAK,IAAA,2BAAa,EAAI;YAC1C,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK;YAClC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,UAAU;YAC5C,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM;SACrC,CAAC,CAAC,CAAA;IACL,CAAC;CACF;AApGD,wCAoGC;AAED;;;;;;;GAOG;AACH,SAAgB,IAAI,CAClB,MAAyB;IAEzB,MAAM,QAAQ,GAAG,IAAA,YAAS,EAAW,MAAa,CAAkB,CAAA;IACpE,OAAO,IAAI,cAAc,CAAI,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAA;AACvD,CAAC","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/commonjs/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/commonjs/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/commonjs/admin/query.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runQuery = runQuery;
+exports.runSubscribeQuery = runSubscribeQuery;
+const index_js_1 = require("../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: (0, index_js_1.shapeResult)(payload.data, query, schema) };
+}
+/** Run a one-shot read and shape the result. */
+async function runQuery(official, schema, query, opts) {
+    const data = await official.query((0, index_js_1.toWireQuery)(query), opts);
+    return (0, index_js_1.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.
+ */
+function runSubscribeQuery(official, schema, query, cb, opts) {
+    const wire = (0, index_js_1.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/commonjs/admin/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../../../src/admin/query.ts"],"names":[],"mappings":";;AA+BA,4BAQC;AAMD,8CAiCC;AAhED,gDAA4D;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,IAAA,sBAAW,EAAC,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,CAAA;AACvE,CAAC;AAED,gDAAgD;AACzC,KAAK,UAAU,QAAQ,CAC5B,QAAoB,EACpB,MAAiB,EACjB,KAAgB,EAChB,IAA2B;IAE3B,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,IAAA,sBAAW,EAAC,KAAK,CAAQ,EAAE,IAAW,CAAC,CAAA;IACzE,OAAO,IAAA,sBAAW,EAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,CAAA;AACzC,CAAC;AAED;;;GAGG;AACH,SAAgB,iBAAiB,CAC/B,QAAoB,EACpB,MAAiB,EACjB,KAAgB,EAChB,EAAkD,EAClD,IAA2B;IAE3B,MAAM,IAAI,GAAG,IAAA,sBAAW,EAAC,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"]}