pyric 0.0.1 → 0.1.0-alpha.8

package/dist/sandbox/admin-compat.js

@@ -0,0 +1,19 @@
+/**
+ * `pyric/sandbox/admin-compat` — chainable Admin-shaped Firestore
+ * wrapper backed by `LocalEnvironment`.
+ *
+ * This is the surface that mirrors `firebase-admin/firestore` (the
+ * Admin Node SDK) so test + agent code that's written against the
+ * chainable Admin shape — `db.collection('x').doc('y').get()` etc. —
+ * can run unmodified against the in-process sandbox.
+ *
+ * `pyric-admin` imports from here directly rather than reaching across
+ * packages for its substrate.
+ *
+ * Exported as a separate subpath (not via `/internal`) because the
+ * admin-compat surface has its own `DocumentData` / `Transaction` /
+ * etc. types that would collide with the local-environment exports
+ * already on `/internal`.
+ */
+export * from './firestore/admin-compat/index.js';
+//# sourceMappingURL=admin-compat.js.map

package/dist/sandbox/admin-compat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-compat.js","sourceRoot":"","sources":["../../src/sandbox/admin-compat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,cAAc,mCAAmC,CAAC"}

package/dist/sandbox/admin-firestore/error-translation.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Translate compat-layer errors (`FirestoreCompatError`) into the
+ * sandbox layer's unified `SandboxError`, attaching whatever structured
+ * `denialContext` is recoverable from the underlying simulator output.
+ *
+ * Why a translation layer at all:
+ *
+ *   The compat impl throws `FirestoreCompatError` because it has to
+ *   look like an Admin SDK `FirestoreError` for the production-shaped
+ *   surface to feel right. The sandbox layer wants one error class
+ *   (`SandboxError`) covering every service so callers can write
+ *   `if (err instanceof SandboxError && err.code === 'permission-
+ *   denied') { ... }` regardless of which service produced the throw.
+ *
+ *   The translation also stitches sandbox-known context (the active
+ *   auth identity, sourced from `SandboxContext`) and best-effort
+ *   recovered context (the underlying `debugMessages`, recovered from
+ *   the error's stitched-together message) into `denialContext`.
+ *
+ * `denialContext.rule` (line + expression) is left undefined: the
+ * rules AST does not currently carry source positions, so neither line
+ * numbers nor the original expression string are reliably available
+ * after evaluation.
+ *
+ * The recursive `wrapWithErrorTranslation` Proxy applies translation
+ * uniformly across the Firestore handle and every object returned from
+ * its methods (DocumentRef, Query, WriteBatch, Transaction). It also
+ * stashes the owning {@link SandboxContext} on every wrapped value via
+ * the {@link CONTEXT_SYMBOL} hidden property — `onSnapshot` reads it
+ * back to capture the right auth at listener registration.
+ */
+import type { SandboxContext } from 'pyric/sandbox';
+/**
+ * Hidden property on every wrapped object that returns the
+ * `SandboxContext` that produced it. Used by `onSnapshot` to recover
+ * the right auth from a ref produced via `db.doc(path)` /
+ * `db.collection(path)` regardless of how many contexts share the
+ * underlying sandbox. Symbol so it never collides with a real property.
+ */
+export declare const CONTEXT_SYMBOL: unique symbol;
+/**
+ * Late-bound reference to the free `onSnapshot(ref, ...args)` function
+ * from `index.ts`. Synthesized into wrapped refs as a `.onSnapshot(...)`
+ * chainable method (see {@link wrapWithErrorTranslation}).
+ *
+ * Why late binding: the Proxy wrapper here is consumed from `index.ts`,
+ * and that's where the free `onSnapshot` is defined. Statically
+ * importing it back would create a circular module init order. The
+ * registration call lives at the bottom of `index.ts`, after
+ * `onSnapshot` is fully declared.
+ */
+type OnSnapshotImpl = (ref: unknown, ...args: unknown[]) => () => void;
+/**
+ * Register the free `onSnapshot` function so wrapped refs can synthesize
+ * a chainable `.onSnapshot(...)` method that delegates to it. Called
+ * once at module init from `index.ts`.
+ */
+export declare function registerOnSnapshotImpl(fn: OnSnapshotImpl): void;
+/**
+ * Convert a compat error into a `SandboxError` with attached
+ * `denialContext`. Non-compat errors fall through unchanged so callers
+ * still see (e.g.) a TypeError thrown from user code.
+ */
+export declare function toSandboxError(err: unknown, ctx: SandboxContext): unknown;
+/**
+ * Wrap an object so that every function call on it (and on its
+ * function-call returns) gets `try/catch` and `Promise.catch`
+ * translation through {@link toSandboxError}.
+ *
+ * Property reads that aren't functions pass through. Function returns
+ * that aren't objects pass through. Object returns are recursively
+ * wrapped — this is what makes `db.doc('x').get()` translate even
+ * though the wrapper only directly intercepts `db`'s own methods.
+ *
+ * Method-chaining identity (`b.set(x).update(y)`) is preserved through
+ * a per-call fresh proxy: each chain step returns a wrapped view of
+ * the underlying impl's `this`, which has the same delegate behavior.
+ *
+ * Every wrapped object also exposes `[CONTEXT_SYMBOL]` returning the
+ * owning {@link SandboxContext}; `onSnapshot` reads this to recover
+ * the right auth at registration regardless of how many contexts
+ * share the underlying sandbox.
+ */
+export declare function wrapWithErrorTranslation<T extends object>(target: T, ctx: SandboxContext): T;
+export {};
+//# sourceMappingURL=error-translation.d.ts.map

package/dist/sandbox/admin-firestore/error-translation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-translation.d.ts","sourceRoot":"","sources":["../../../src/sandbox/admin-firestore/error-translation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAOpD;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,EAAE,OAAO,MAAwC,CAAC;AAE7E;;;;;;;;;;GAUG;AACH,KAAK,cAAc,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,MAAM,IAAI,CAAC;AAGvE;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,cAAc,GAAG,IAAI,CAE/D;AAsDD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAyBzE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,SAAS,MAAM,EACvD,MAAM,EAAE,CAAC,EACT,GAAG,EAAE,cAAc,GAClB,CAAC,CAqDH"}

package/dist/sandbox/admin-firestore/error-translation.js

@@ -0,0 +1,204 @@
+/**
+ * Translate compat-layer errors (`FirestoreCompatError`) into the
+ * sandbox layer's unified `SandboxError`, attaching whatever structured
+ * `denialContext` is recoverable from the underlying simulator output.
+ *
+ * Why a translation layer at all:
+ *
+ *   The compat impl throws `FirestoreCompatError` because it has to
+ *   look like an Admin SDK `FirestoreError` for the production-shaped
+ *   surface to feel right. The sandbox layer wants one error class
+ *   (`SandboxError`) covering every service so callers can write
+ *   `if (err instanceof SandboxError && err.code === 'permission-
+ *   denied') { ... }` regardless of which service produced the throw.
+ *
+ *   The translation also stitches sandbox-known context (the active
+ *   auth identity, sourced from `SandboxContext`) and best-effort
+ *   recovered context (the underlying `debugMessages`, recovered from
+ *   the error's stitched-together message) into `denialContext`.
+ *
+ * `denialContext.rule` (line + expression) is left undefined: the
+ * rules AST does not currently carry source positions, so neither line
+ * numbers nor the original expression string are reliably available
+ * after evaluation.
+ *
+ * The recursive `wrapWithErrorTranslation` Proxy applies translation
+ * uniformly across the Firestore handle and every object returned from
+ * its methods (DocumentRef, Query, WriteBatch, Transaction). It also
+ * stashes the owning {@link SandboxContext} on every wrapped value via
+ * the {@link CONTEXT_SYMBOL} hidden property — `onSnapshot` reads it
+ * back to capture the right auth at listener registration.
+ */
+import { FirestoreCompatError } from 'pyric/sandbox/admin-compat';
+import { SandboxError, } from 'pyric/sandbox';
+/**
+ * Hidden property on every wrapped object that returns the
+ * `SandboxContext` that produced it. Used by `onSnapshot` to recover
+ * the right auth from a ref produced via `db.doc(path)` /
+ * `db.collection(path)` regardless of how many contexts share the
+ * underlying sandbox. Symbol so it never collides with a real property.
+ */
+export const CONTEXT_SYMBOL = Symbol('pyric/sandbox/context');
+let onSnapshotImpl = null;
+/**
+ * Register the free `onSnapshot` function so wrapped refs can synthesize
+ * a chainable `.onSnapshot(...)` method that delegates to it. Called
+ * once at module init from `index.ts`.
+ */
+export function registerOnSnapshotImpl(fn) {
+    onSnapshotImpl = fn;
+}
+/**
+ * Heuristic: the wrapped object is a Firestore ref
+ * (DocumentReference, CollectionReference, or chained Query). Used
+ * to gate the synthesized `.onSnapshot` shim so the method only
+ * appears on values where a chainable `.onSnapshot` actually makes
+ * sense.
+ *
+ * - `DocumentReference` exposes `path` publicly.
+ * - `CollectionReference` exposes `path` publicly.
+ * - Chained `Query` (the result of `.where()/.orderBy()/.limit()`)
+ *   keeps `collectionPath` as a TypeScript-protected field on the
+ *   underlying `QueryImpl`. Protected is a TS-only restriction; at
+ *   runtime the field is readable, so the lookup matches.
+ *
+ * Snapshots, batches, transactions, and the Firestore handle itself
+ * carry neither, so the shim correctly skips them.
+ */
+function isRefLike(obj) {
+    const o = obj;
+    return (typeof o.path === 'string' && o.path.length > 0)
+        || (typeof o.collectionPath === 'string' && o.collectionPath.length > 0);
+}
+/**
+ * Pull a list of denial reasons out of a compat-error message. Two
+ * formats produced by the underlying SDK are handled:
+ *
+ *   1. Stitched-multi  — `"get denied: Rule #0 → deny; Simulated: DENY"`.
+ *      Produced by the `throwFromDenial` fallback path when the
+ *      simulator didn't attach a typed `error` (rare today; reserved
+ *      for future use). Split after the first `": "` and on `"; "`.
+ *
+ *   2. Plain typed     — `"get tickets/T-1 denied by rules"`. Produced
+ *      when the simulator returns a typed `error` (`makeError(...)`).
+ *      No structured sub-reasons; surface the whole message as a
+ *      single-element list so callers get something machine-readable.
+ *
+ * The list is never empty for a non-empty error message, so callers
+ * don't need to special-case "no reasons available."
+ */
+function recoverReasons(message) {
+    const trimmed = message.trim();
+    if (!trimmed)
+        return [];
+    const firstColon = trimmed.indexOf(': ');
+    if (firstColon !== -1) {
+        const tail = trimmed.slice(firstColon + 2).trim();
+        const parts = tail.split('; ').map(s => s.trim()).filter(s => s.length > 0);
+        if (parts.length > 0)
+            return parts;
+    }
+    return [trimmed];
+}
+/**
+ * Convert a compat error into a `SandboxError` with attached
+ * `denialContext`. Non-compat errors fall through unchanged so callers
+ * still see (e.g.) a TypeError thrown from user code.
+ */
+export function toSandboxError(err, ctx) {
+    if (!(err instanceof FirestoreCompatError))
+        return err;
+    const code = err.code;
+    if (code !== 'permission-denied') {
+        return new SandboxError(code, err.message);
+    }
+    const denialContext = {
+        auth: ctx.auth,
+        reasons: recoverReasons(err.message),
+    };
+    const sim = err.simError;
+    if (sim?.request) {
+        const r = sim.request;
+        denialContext.request = {
+            method: r.method,
+            path: r.path,
+            ...(r.resourceData ? { resourceData: r.resourceData } : {}),
+        };
+    }
+    if (sim?.resource) {
+        denialContext.resource = { data: sim.resource.data, exists: sim.resource.exists };
+    }
+    return new SandboxError(code, err.message, denialContext);
+}
+/**
+ * Wrap an object so that every function call on it (and on its
+ * function-call returns) gets `try/catch` and `Promise.catch`
+ * translation through {@link toSandboxError}.
+ *
+ * Property reads that aren't functions pass through. Function returns
+ * that aren't objects pass through. Object returns are recursively
+ * wrapped — this is what makes `db.doc('x').get()` translate even
+ * though the wrapper only directly intercepts `db`'s own methods.
+ *
+ * Method-chaining identity (`b.set(x).update(y)`) is preserved through
+ * a per-call fresh proxy: each chain step returns a wrapped view of
+ * the underlying impl's `this`, which has the same delegate behavior.
+ *
+ * Every wrapped object also exposes `[CONTEXT_SYMBOL]` returning the
+ * owning {@link SandboxContext}; `onSnapshot` reads this to recover
+ * the right auth at registration regardless of how many contexts
+ * share the underlying sandbox.
+ */
+export function wrapWithErrorTranslation(target, ctx) {
+    return new Proxy(target, {
+        get(t, prop, receiver) {
+            // Hidden context recovery — must come before any other property
+            // resolution. Symbol-keyed so it can't collide with real props.
+            if (prop === CONTEXT_SYMBOL)
+                return ctx;
+            // Synthesize a chainable `.onSnapshot(...)` method on every
+            // ref-shaped wrapped value. The underlying compat ref doesn't
+            // define this method (the package's canonical surface is the
+            // free `onSnapshot(ref, ...)` function); the shim is here so
+            // `db.collection(path).where(...).onSnapshot(cb)` style chains
+            // work too. Both forms route through the same listener.
+            //
+            // Gate: only when (a) the impl is registered, (b) the underlying
+            // doesn't already define `onSnapshot`, and (c) the underlying is
+            // ref-like — so we don't accidentally attach the method to
+            // snapshots, batches, transactions, the Firestore handle, etc.
+            if (prop === 'onSnapshot' &&
+                onSnapshotImpl !== null &&
+                !(prop in t) &&
+                isRefLike(t)) {
+                // Pass `receiver` (the Proxy) rather than `t` so the free
+                // `onSnapshot` reads CONTEXT_SYMBOL through the wrapper.
+                return (...args) => onSnapshotImpl(receiver, ...args);
+            }
+            const value = Reflect.get(t, prop, receiver);
+            if (typeof value !== 'function')
+                return value;
+            // Bind to the original `t` so internal `this` references inside
+            // the delegate stay coherent.
+            return function (...args) {
+                let result;
+                try {
+                    result = value.apply(t, args);
+                }
+                catch (e) {
+                    throw toSandboxError(e, ctx);
+                }
+                if (result instanceof Promise) {
+                    return result
+                        .then((v) => (v && typeof v === 'object' ? wrapWithErrorTranslation(v, ctx) : v))
+                        .catch((e) => { throw toSandboxError(e, ctx); });
+                }
+                if (result && typeof result === 'object') {
+                    return wrapWithErrorTranslation(result, ctx);
+                }
+                return result;
+            };
+        },
+    });
+}
+//# sourceMappingURL=error-translation.js.map

package/dist/sandbox/admin-firestore/error-translation.js.map

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

package/dist/sandbox/admin-firestore/index.d.ts

@@ -0,0 +1,169 @@
+/**
+ * `pyric-admin` — Admin-SDK-shaped chainable Firestore adapter for
+ * the Pyric sandbox.
+ *
+ * `getFirestore(ctx)` returns a `SandboxFirestore` whose operations
+ * run under the context's auth identity and against the underlying
+ * `LocalEnvironment` of the context's sandbox. Idempotent — a second
+ * call with the same `SandboxContext` returns the same wrapper.
+ *
+ * Wraps the `pyric/sandbox/admin-compat` implementation.
+ * Per-operation methods construct a fresh delegate so a
+ * `sandbox.reset()` (which swaps the underlying environment) is
+ * picked up on the next operation. Refs returned from the wrapper
+ * (`DocumentReference`, `Query`) are bound to whichever environment
+ * was live when they were obtained — re-acquire them after reset to
+ * avoid stale-state confusion.
+ */
+import type { CollectionReference, DocumentData, DocumentReference, Firestore, Query, SnapshotListenerOptions } from 'pyric/sandbox/admin-compat';
+import type { LintResult } from 'pyric/rules';
+import { type Sandbox, type SandboxContext } from 'pyric/sandbox';
+export type { AuthState, Sandbox, SandboxContext, } from 'pyric/sandbox';
+export { SandboxError } from 'pyric/sandbox';
+export type { AggregateField, AggregateQuerySnapshot, AggregateSpec, Filter, CollectionReference, DocumentData, DocumentReference, DocumentSnapshot as AdminDocumentSnapshot, FieldValueSentinel, Firestore, OrderDirection, Query, QueryDocumentSnapshot as AdminQueryDocumentSnapshot, QuerySnapshot as AdminQuerySnapshot, SetOptions, Transaction, WhereFilterOp, WriteBatch, } from 'pyric/sandbox/admin-compat';
+export type { LintResult, LintWarning, RulesMetrics } from 'pyric/rules';
+export { FieldValue, Timestamp } from 'pyric/sandbox/admin-compat';
+export type { LiveDocumentSnapshot as DocumentSnapshot, LiveQueryDocumentSnapshot as QueryDocumentSnapshot, LiveQuerySnapshot as QuerySnapshot, DocumentChange, DocumentChangeType, DocChangesOptions, SnapshotMetadata, } from 'pyric/sandbox/admin-compat';
+/**
+ * Mirrors `firebase/firestore`'s `SnapshotListenOptions`. The
+ * `includeMetadataChanges` flag is accepted for API parity but has no
+ * observable effect in the sandbox: there's no offline cache and no
+ * pending-writes window, so `metadata.fromCache` and
+ * `metadata.hasPendingWrites` are always `false` (snapshot-listeners.ts section 6).
+ */
+export type SnapshotListenOptions = SnapshotListenerOptions;
+/**
+ * Internal channel for the modular `pyric/firestore` layer to mark a
+ * listener as live (identity follows `sandbox.currentUser`) vs frozen
+ * (`getFirestore(ctx)`, pinned identity). The chainable adapter sees only
+ * a `SandboxContext` per call and can't tell the two apart on its own — the
+ * live-vs-frozen distinction lives one layer up. The modular `onSnapshot`
+ * stamps this symbol onto the options object it forwards; {@link onSnapshot}
+ * here reads + strips it and threads the boolean into
+ * `LocalEnvironment.addSnapshotListener`'s `followsCurrentUser` parameter.
+ *
+ * Symbol-keyed (not a named field) so it never collides with a real
+ * `SnapshotListenOptions` field and never leaks to consumer code.
+ */
+export declare const FOLLOWS_CURRENT_USER: unique symbol;
+/**
+ * Returned from `onSnapshot`. Calling it deregisters the listener and
+ * stops further callback invocations. Idempotent.
+ */
+export type Unsubscribe = () => void;
+/**
+ * Observer form accepted by `onSnapshot`. Mirrors `firebase/firestore`'s
+ * `PartialObserver<T>` shape — any subset of the three handlers. `complete`
+ * is accepted for shape parity but never fires in the sandbox: the local
+ * listener stream has no terminal state.
+ */
+export interface SnapshotObserver<T> {
+    next?: (snapshot: T) => void;
+    error?: (error: unknown) => void;
+    complete?: () => void;
+}
+/**
+ * Sandbox-extended Firestore handle. Adds three sandbox-only methods
+ * on top of the production-shaped {@link Firestore} surface:
+ *
+ *   - {@link SandboxFirestore.setRules} — replace the active ruleset
+ *     for subsequent operations.
+ *   - {@link SandboxFirestore.seed} — replace stored documents with a
+ *     fresh seed map (rules are preserved).
+ *   - {@link SandboxFirestore.snapshot} — capture all stored documents
+ *     as a path-keyed map.
+ *
+ * These have no production analog. They use sandbox vocabulary
+ * (`setRules`, `seed`, `snapshot`) deliberately so a reader can't
+ * confuse them with Firebase deployment semantics.
+ */
+export interface SandboxFirestore extends Firestore {
+    /**
+     * Replace the active ruleset. Returns the lint result so callers can
+     * surface warnings; if the source has parse-level errors, the rules
+     * are not swapped (consistent with `LocalEnvironment.deployRules`).
+     */
+    setRules(rules: string): LintResult;
+    /**
+     * Replace stored documents with a new seed map. Active rules are
+     * preserved. Pass an empty `documents` map (or omit it) to clear
+     * state without touching rules.
+     */
+    seed(options?: {
+        documents?: Record<string, DocumentData>;
+    }): LintResult;
+    /**
+     * Capture every stored document as a `{ [path]: data }` map. Reads
+     * from the live state and is independent of rules.
+     */
+    snapshot(): Record<string, DocumentData>;
+}
+/**
+ * Resolve the Firestore service handle for a context. Idempotent —
+ * subsequent calls with the same context return the same wrapper.
+ *
+ * Requires a `SandboxContext`, never a bare `Sandbox`. Anonymous is
+ * `sandbox.withAuth(null)`, written explicitly — every call site
+ * states identity.
+ *
+ * @example
+ * ```ts
+ * import { initializeSandbox } from 'pyric/sandbox';
+ * import { getFirestore } from 'pyric-admin/firestore';
+ *
+ * const sandbox = initializeSandbox();
+ * const db = getFirestore(sandbox.withAuth({ uid: 'alice' }));
+ * db.setRules(MY_RULES);
+ * db.seed({ documents: { 'tickets/T-1': { ... } } });
+ *
+ * // Different identity? Different context, same data.
+ * const dbAsBob = getFirestore(sandbox.withAuth({ uid: 'bob' }));
+ * ```
+ */
+export declare function getFirestore(ctx: SandboxContext): SandboxFirestore;
+/**
+ * Resolve a **rules-bypassing** Firestore handle for a context — the
+ * Pyric Studio admin lens (Gap #2). Same chainable `SandboxFirestore`
+ * surface as {@link getFirestore}, but every operation it issues (reads,
+ * writes, queries, batches, transactions) SKIPS security-rule evaluation
+ * and is treated as ALLOW. This is the modular/chainable-shaped sibling of
+ * the path-string `sandbox.admin.*` bypass — it reuses the exact same
+ * `LocalEnvironment` bypass execution path (`bypassRules` on the op),
+ * rather than reimplementing it.
+ *
+ * Storage preconditions still apply (a `create` on an existing doc still
+ * fails `already-exists`, matching real Firestore admin), and the same
+ * `request`/`write` events fire + listeners wake, so the change shows up
+ * live and on the traffic log (stamped as an admin-bypass read/write).
+ *
+ * Use for "edit anything as admin" surfaces (Studio F2). For rules-applied
+ * impersonation ("act as this user"), use `getFirestore(sandbox.withAuth({
+ * uid }))` instead — that path is unchanged.
+ *
+ * @example
+ * ```ts
+ * import { initializeSandbox } from 'pyric/sandbox';
+ * import { getFirestore, getAdminFirestore } from 'pyric-admin/firestore';
+ *
+ * const sandbox = initializeSandbox();
+ * getFirestore(sandbox.withAuth(null)).setRules('...deny everything...');
+ *
+ * // Denied under rules:
+ * await getFirestore(sandbox.withAuth({ uid: 'alice' }))
+ *   .doc('locked/x').set({ a: 1 }); // throws permission-denied
+ *
+ * // Bypasses rules:
+ * await getAdminFirestore(sandbox).doc('locked/x').set({ a: 1 }); // ok
+ * ```
+ */
+export declare function getAdminFirestore(ctx: SandboxContext): SandboxFirestore;
+export declare function getAdminFirestore(sandbox: Sandbox): SandboxFirestore;
+export declare function onSnapshot(reference: DocumentReference, observer: SnapshotObserver<import('pyric/sandbox/admin-compat').LiveDocumentSnapshot>): Unsubscribe;
+export declare function onSnapshot(reference: DocumentReference, options: SnapshotListenOptions, observer: SnapshotObserver<import('pyric/sandbox/admin-compat').LiveDocumentSnapshot>): Unsubscribe;
+export declare function onSnapshot(reference: DocumentReference, onNext: (snapshot: import('pyric/sandbox/admin-compat').LiveDocumentSnapshot) => void, onError?: (error: unknown) => void, onCompletion?: () => void): Unsubscribe;
+export declare function onSnapshot(reference: DocumentReference, options: SnapshotListenOptions, onNext: (snapshot: import('pyric/sandbox/admin-compat').LiveDocumentSnapshot) => void, onError?: (error: unknown) => void, onCompletion?: () => void): Unsubscribe;
+export declare function onSnapshot(reference: Query | CollectionReference, observer: SnapshotObserver<import('pyric/sandbox/admin-compat').LiveQuerySnapshot>): Unsubscribe;
+export declare function onSnapshot(reference: Query | CollectionReference, options: SnapshotListenOptions, observer: SnapshotObserver<import('pyric/sandbox/admin-compat').LiveQuerySnapshot>): Unsubscribe;
+export declare function onSnapshot(reference: Query | CollectionReference, onNext: (snapshot: import('pyric/sandbox/admin-compat').LiveQuerySnapshot) => void, onError?: (error: unknown) => void, onCompletion?: () => void): Unsubscribe;
+export declare function onSnapshot(reference: Query | CollectionReference, options: SnapshotListenOptions, onNext: (snapshot: import('pyric/sandbox/admin-compat').LiveQuerySnapshot) => void, onError?: (error: unknown) => void, onCompletion?: () => void): Unsubscribe;
+//# sourceMappingURL=index.d.ts.map

package/dist/sandbox/admin-firestore/index.d.ts.map

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