pyric 0.0.1 → 0.1.0-alpha.8

package/dist/storage/service.d.ts

@@ -0,0 +1,139 @@
+import type { Sandbox, SandboxContext } from 'pyric/sandbox';
+import type { FirebaseApp } from 'firebase/app';
+import * as fb from 'firebase/storage';
+import { type StorageBackend } from './persistence.js';
+import { type StorageRules } from './rules.js';
+/**
+ * Hidden property on every {@link FirebaseStorage} handle. Carries
+ * the target discriminator so free functions can route between
+ * sandbox + prod backends without consumer-visible API differences.
+ */
+export declare const TARGET_SYMBOL: unique symbol;
+/**
+ * Sandbox target — IDB-backed, identity from `SandboxContext`, rules
+ * enforced in-process via `enforce.ts`.
+ */
+export interface SandboxTarget {
+    readonly kind: 'sandbox';
+    readonly sandbox: Sandbox;
+    readonly context: SandboxContext;
+    readonly bucket: string;
+    readonly servicePromise: Promise<StorageService>;
+    /**
+     * Rules-bypass admin plane. `true` only on handles minted by the
+     * INTERNAL {@link getAdminStorageSandbox} factory (exported via
+     * `pyric/storage/internal`, never the public surface): operations
+     * on an admin handle skip rule evaluation entirely — the storage
+     * mirror of `getAdminFirestore` / `getAdminDatabase`. The public
+     * modular surface stays rules-honest; this exists so hosts (the
+     * SharedWorker's `actAs: { mode: 'admin' }` lens) can serve
+     * firebase-admin semantics against the same shared store.
+     */
+    readonly admin?: boolean;
+}
+/**
+ * Prod target — delegates to `firebase/storage`. The user's Firebase
+ * Auth identity flows naturally through the underlying SDK; we don't
+ * touch rules (they're enforced server-side).
+ */
+export interface ProdTarget {
+    readonly kind: 'prod';
+    readonly app: FirebaseApp;
+    readonly fbStorage: fb.FirebaseStorage;
+    readonly bucket: string;
+}
+export type Target = SandboxTarget | ProdTarget;
+/**
+ * Public opaque handle. Carries a {@link Target} via
+ * {@link TARGET_SYMBOL}; never inspected by consumer code, which
+ * interacts with storage only through {@link ref} and the operation
+ * free functions.
+ */
+export interface FirebaseStorage {
+    readonly [TARGET_SYMBOL]: Target;
+}
+/**
+ * Internal sandbox service — owns the IDB connection + parsed rules.
+ * Only constructed inside the sandbox `getStorageSandbox` path.
+ */
+export declare class StorageService {
+    readonly backend: StorageBackend;
+    readonly rules: StorageRules | null;
+    constructor(backend: StorageBackend, rules?: StorageRules | null);
+}
+/** Options for {@link getStorageSandbox}. */
+export interface StorageOptions {
+    /**
+     * Bucket identifier recorded on uploaded metadata. v1 has a
+     * single implicit bucket and does not enforce cross-bucket
+     * isolation — passing different values per call is accepted and
+     * round-trips in metadata, but the data store is shared.
+     */
+    bucket?: string;
+    /**
+     * Override the IndexedDB database name. Production callers do
+     * NOT pass this; they inherit the default `pyric-storage`. Tests
+     * pass per-case unique names so state doesn't leak between runs.
+     * Only takes effect on the FIRST call per `Sandbox`.
+     */
+    dbName?: string;
+    /**
+     * Storage rules source. Parsed eagerly so a malformed string
+     * throws at config time. Only honored on the FIRST call per
+     * `Sandbox`.
+     */
+    rules?: string;
+}
+/** Options for {@link getStorageProd}. */
+export interface ProdStorageOptions {
+    /**
+     * Override the gs:// bucket the handle binds to. Defaults to the
+     * project's primary bucket (whatever `app.options.storageBucket`
+     * names). Pass a custom bucket name (`gs://my-extra-bucket`) to
+     * target a non-default bucket.
+     */
+    bucket?: string;
+}
+/**
+ * Construct (or return cached) a sandbox-backed `FirebaseStorage`
+ * handle. Accepts either a bare `Sandbox` (anonymous identity wired
+ * up via `sandbox.withAuth(null)`) or an explicit `SandboxContext`.
+ * Idempotent on `SandboxContext` identity.
+ */
+export declare function getStorageSandbox(target: Sandbox | SandboxContext, options?: StorageOptions): FirebaseStorage;
+/**
+ * INTERNAL (exported via `pyric/storage/internal` only) — construct
+ * (or return cached) the rules-BYPASS admin `FirebaseStorage` handle
+ * for a sandbox. Shares the SAME `StorageService` (one IDB store, one
+ * ruleset) as every rules-honest handle on that sandbox; only rule
+ * evaluation is skipped (see {@link SandboxTarget.admin}). Bucket /
+ * dbName / rules options follow the same first-call-per-`Sandbox`
+ * semantics as {@link getStorageSandbox}.
+ *
+ * This is the storage mirror of `getAdminFirestore` /
+ * `getAdminDatabase` — the handle the SharedWorker host resolves for
+ * `actAs: { mode: 'admin' }` storage ops (firebase-admin semantics
+ * over the bridge). Deliberately NOT on the public `pyric/storage`
+ * surface so the modular API stays rules-honest.
+ */
+export declare function getAdminStorageSandbox(sandbox: Sandbox, options?: StorageOptions): FirebaseStorage;
+/**
+ * Construct a `FirebaseStorage` handle backed by a real Firebase
+ * project. The user's Firebase Auth identity flows naturally into
+ * rule evaluation via the SDK's standard auth-state subscription —
+ * Pyric doesn't manage the auth handshake, mirroring how
+ * `firebase/storage`'s own `getStorage(app)` works.
+ */
+export declare function getStorageProd(app: FirebaseApp, options?: ProdStorageOptions): FirebaseStorage;
+/**
+ * Internal — extract the {@link Target} from a handle. Throws on
+ * objects that weren't produced by a factory in this module.
+ */
+export declare function targetOf(storage: FirebaseStorage): Target;
+/**
+ * Internal — fetch the backing `StorageService` promise for a
+ * sandbox handle. Throws when called on a prod handle (prod ops
+ * never need a service; this helper is sandbox-only).
+ */
+export declare function getStorageService(storage: FirebaseStorage): Promise<StorageService>;
+//# sourceMappingURL=service.d.ts.map

package/dist/storage/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/storage/service.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EAAqB,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AASlE;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,OAAO,MAAuC,CAAC;AAE3E;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IACjD;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,EAAE,CAAC,eAAe,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,MAAM,GAAG,aAAa,GAAG,UAAU,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;GAGG;AACH,qBAAa,cAAc;IAEvB,QAAQ,CAAC,OAAO,EAAE,cAAc;IAChC,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;gBAD1B,OAAO,EAAE,cAAc,EACvB,KAAK,GAAE,YAAY,GAAG,IAAW;CAE7C;AAED,6CAA6C;AAC7C,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,0CAA0C;AAC1C,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAyED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,OAAO,GAAG,cAAc,EAChC,OAAO,GAAE,cAAmB,GAC3B,eAAe,CAoCjB;AAKD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,cAAmB,GAC3B,eAAe,CAqBjB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,WAAW,EAChB,OAAO,GAAE,kBAAuB,GAC/B,eAAe,CAQjB;AAWD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAQzD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAMnF"}

package/dist/storage/service.js

@@ -0,0 +1,241 @@
+/**
+ * Service module — handles, factories, and target-discriminated
+ * routing. Mirrors `pyric/firestore`'s dual-target shape so the same
+ * playground (or any consumer) can switch from a `pyric/sandbox`-
+ * backed IDB store to a real Firebase Storage bucket by swapping the
+ * factory call.
+ *
+ * The public `FirebaseStorage` handle is opaque — it carries a
+ * `TARGET_SYMBOL` field pointing to an internal `Target` discriminator
+ * that every operation reads to decide between the sandbox path
+ * (IDB + rules-eval) and the prod path (delegate to `firebase/storage`).
+ *
+ * Caching:
+ *
+ * - **Per `Sandbox`** — the IDB-backed `StorageService` is shared.
+ *   Two `getStorageSandbox` calls on the same sandbox hit the same
+ *   backend.
+ * - **Per `SandboxContext`** — the sandbox `FirebaseStorage` handle
+ *   is identity-stable. `getStorageSandbox(ctx)` twice returns the
+ *   same object.
+ * - **Prod** — each `getStorageProd(app)` returns a fresh handle.
+ *   `firebase/storage` itself caches per-app under the hood, so this
+ *   is cheap; we don't add a layer.
+ *
+ * Internal access:
+ *
+ * `getStorageService(storage)` returns the backing
+ * `Promise<StorageService>` for sandbox handles. Throws on prod
+ * handles — prod ops never need it.
+ */
+import { SandboxContextImpl } from 'pyric/sandbox';
+import * as fb from 'firebase/storage';
+import { openStorageBackend } from './persistence.js';
+import { parseStorageRules } from './rules.js';
+/**
+ * Default sandbox bucket identifier. v1 has a single implicit
+ * bucket; the field is recorded on every uploaded metadata record
+ * so consumer code can round-trip it.
+ */
+const DEFAULT_BUCKET = 'pyric-default';
+/**
+ * Hidden property on every {@link FirebaseStorage} handle. Carries
+ * the target discriminator so free functions can route between
+ * sandbox + prod backends without consumer-visible API differences.
+ */
+export const TARGET_SYMBOL = Symbol('pyric/storage/target');
+/**
+ * Internal sandbox service — owns the IDB connection + parsed rules.
+ * Only constructed inside the sandbox `getStorageSandbox` path.
+ */
+export class StorageService {
+    backend;
+    rules;
+    constructor(backend, rules = null) {
+        this.backend = backend;
+        this.rules = rules;
+    }
+}
+// ─── Caches (sandbox-only — prod relies on firebase/storage's caching) ─
+/** One `StorageService` per `Sandbox`. */
+const SERVICES = new WeakMap();
+/** One sandbox `FirebaseStorage` handle per `SandboxContext`. */
+const SANDBOX_HANDLES = new WeakMap();
+/**
+ * One anonymous handle per bare `Sandbox`. `Sandbox.withAuth(null)`
+ * mints a FRESH `SandboxContext` on every call, so the per-context
+ * cache above would miss for the bare-`Sandbox` convenience path —
+ * `getStorageSandbox(sandbox)` twice returned two different handles
+ * (ST-B3). Caching on the `Sandbox` keeps that path identity-stable,
+ * matching the documented "handle is identity-stable per Sandbox".
+ */
+const BARE_SANDBOX_HANDLES = new WeakMap();
+/**
+ * The rules SOURCE each sandbox's service was opened with (`null` when
+ * opened without rules). Late-config detection: rules are honored only on
+ * the FIRST storage call per `Sandbox`, so silently discarding a LATER,
+ * DIFFERENT `rules` option would be a silent rules wipe — {@link
+ * ensureService} throws instead. Re-supplying the IDENTICAL source stays
+ * fine (idempotent multi-handle construction, e.g. per-user contexts).
+ */
+const SERVICE_RULES_SOURCE = new WeakMap();
+/**
+ * Get (or open) the ONE per-sandbox `StorageService`. Loud on the
+ * silent-rules-wipe hazard: when the service is already open and the
+ * caller supplies a `rules` source differing from the one it was opened
+ * with (including "opened without rules"), this throws — configure rules
+ * on the first storage call for the sandbox instead.
+ */
+function ensureService(sandbox, options, caller) {
+    const existing = SERVICES.get(sandbox);
+    if (existing) {
+        const openedWith = SERVICE_RULES_SOURCE.get(sandbox) ?? null;
+        if (options.rules !== undefined && options.rules !== openedWith) {
+            throw new Error(`pyric/storage: ${caller} received a rules source, but this sandbox's storage ` +
+                `service is already open ${openedWith === null ? 'without rules' : 'with a different rules source'} ` +
+                '— rules are honored only on the FIRST storage call per Sandbox, so these rules ' +
+                'would be silently discarded. Configure rules on the first storage call for this sandbox.');
+        }
+        return existing;
+    }
+    const rules = options.rules ? parseStorageRules(options.rules) : null;
+    const servicePromise = openStorageBackend(options.dbName).then((backend) => new StorageService(backend, rules));
+    SERVICES.set(sandbox, servicePromise);
+    SERVICE_RULES_SOURCE.set(sandbox, options.rules ?? null);
+    return servicePromise;
+}
+/**
+ * Type predicate distinguishing `SandboxContext` from `Sandbox`. We
+ * use the class-identity test (every real `SandboxContext` is a
+ * `SandboxContextImpl`) so the TS narrowing works downstream.
+ */
+function isContext(target) {
+    return target instanceof SandboxContextImpl;
+}
+/**
+ * Construct (or return cached) a sandbox-backed `FirebaseStorage`
+ * handle. Accepts either a bare `Sandbox` (anonymous identity wired
+ * up via `sandbox.withAuth(null)`) or an explicit `SandboxContext`.
+ * Idempotent on `SandboxContext` identity.
+ */
+export function getStorageSandbox(target, options = {}) {
+    const fromBareSandbox = !isContext(target);
+    const sandbox = isContext(target) ? target.sandbox : target;
+    // Open (or fetch) the ONE per-sandbox service FIRST — before any handle
+    // cache fast-path — so a late, differing `rules` option throws instead of
+    // being silently discarded (see ensureService).
+    const servicePromise = ensureService(sandbox, options, 'getStorageSandbox');
+    // Fast path: a repeat bare-`Sandbox` call returns the cached
+    // anonymous handle (the per-context cache below can't catch it
+    // because `withAuth(null)` mints a fresh context each time). Like
+    // the per-context path, bucket/dbName options are honored only on
+    // the FIRST call per Sandbox.
+    if (fromBareSandbox) {
+        const cachedBare = BARE_SANDBOX_HANDLES.get(sandbox);
+        if (cachedBare)
+            return cachedBare;
+    }
+    const ctx = isContext(target) ? target : target.withAuth(null);
+    const bucket = options.bucket ?? DEFAULT_BUCKET;
+    const cached = SANDBOX_HANDLES.get(ctx);
+    if (cached)
+        return cached;
+    const sandboxTarget = {
+        kind: 'sandbox',
+        sandbox,
+        context: ctx,
+        bucket,
+        servicePromise,
+    };
+    const handle = Object.freeze({ [TARGET_SYMBOL]: sandboxTarget });
+    SANDBOX_HANDLES.set(ctx, handle);
+    if (fromBareSandbox)
+        BARE_SANDBOX_HANDLES.set(sandbox, handle);
+    return handle;
+}
+/** One rules-bypass admin handle per `Sandbox` (internal admin plane). */
+const ADMIN_SANDBOX_HANDLES = new WeakMap();
+/**
+ * INTERNAL (exported via `pyric/storage/internal` only) — construct
+ * (or return cached) the rules-BYPASS admin `FirebaseStorage` handle
+ * for a sandbox. Shares the SAME `StorageService` (one IDB store, one
+ * ruleset) as every rules-honest handle on that sandbox; only rule
+ * evaluation is skipped (see {@link SandboxTarget.admin}). Bucket /
+ * dbName / rules options follow the same first-call-per-`Sandbox`
+ * semantics as {@link getStorageSandbox}.
+ *
+ * This is the storage mirror of `getAdminFirestore` /
+ * `getAdminDatabase` — the handle the SharedWorker host resolves for
+ * `actAs: { mode: 'admin' }` storage ops (firebase-admin semantics
+ * over the bridge). Deliberately NOT on the public `pyric/storage`
+ * surface so the modular API stays rules-honest.
+ */
+export function getAdminStorageSandbox(sandbox, options = {}) {
+    // Service first (late differing `rules` must throw, even on a cache hit).
+    const servicePromise = ensureService(sandbox, options, 'getAdminStorageSandbox');
+    const cached = ADMIN_SANDBOX_HANDLES.get(sandbox);
+    if (cached)
+        return cached;
+    const sandboxTarget = {
+        kind: 'sandbox',
+        sandbox,
+        // Anonymous context: the admin plane has no acting user. Rules are
+        // bypassed, so the context identity only feeds event provenance
+        // (`auth: null` — same as an anonymous caller).
+        context: sandbox.withAuth(null),
+        bucket: options.bucket ?? DEFAULT_BUCKET,
+        servicePromise,
+        admin: true,
+    };
+    const handle = Object.freeze({ [TARGET_SYMBOL]: sandboxTarget });
+    ADMIN_SANDBOX_HANDLES.set(sandbox, handle);
+    return handle;
+}
+/**
+ * Construct a `FirebaseStorage` handle backed by a real Firebase
+ * project. The user's Firebase Auth identity flows naturally into
+ * rule evaluation via the SDK's standard auth-state subscription —
+ * Pyric doesn't manage the auth handshake, mirroring how
+ * `firebase/storage`'s own `getStorage(app)` works.
+ */
+export function getStorageProd(app, options = {}) {
+    const fbStorage = options.bucket ? fb.getStorage(app, options.bucket) : fb.getStorage(app);
+    // The bucket field is sourced from the SDK's resolved bucket, not
+    // the option, so `gs://` prefixes / overrides round-trip correctly
+    // in metadata.
+    const bucket = fbRefBucket(fbStorage);
+    const prodTarget = { kind: 'prod', app, fbStorage, bucket };
+    return Object.freeze({ [TARGET_SYMBOL]: prodTarget });
+}
+/**
+ * The bucket name from a `firebase/storage` handle, read off the
+ * root reference. `fb.ref(storage)` returns the root ref whose
+ * `bucket` field is the canonical bucket name.
+ */
+function fbRefBucket(fbStorage) {
+    return fb.ref(fbStorage).bucket;
+}
+/**
+ * Internal — extract the {@link Target} from a handle. Throws on
+ * objects that weren't produced by a factory in this module.
+ */
+export function targetOf(storage) {
+    const t = storage[TARGET_SYMBOL];
+    if (!t) {
+        throw new TypeError('pyric/storage: not a FirebaseStorage handle — was it produced by getStorageSandbox or getStorageProd?');
+    }
+    return t;
+}
+/**
+ * Internal — fetch the backing `StorageService` promise for a
+ * sandbox handle. Throws when called on a prod handle (prod ops
+ * never need a service; this helper is sandbox-only).
+ */
+export function getStorageService(storage) {
+    const target = targetOf(storage);
+    if (target.kind !== 'sandbox') {
+        throw new Error('getStorageService called on a prod-target handle — sandbox-only API');
+    }
+    return target.servicePromise;
+}
+//# sourceMappingURL=service.js.map

package/dist/storage/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../src/storage/service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAGnD,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,EAAE,kBAAkB,EAAuB,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EAAE,iBAAiB,EAAqB,MAAM,YAAY,CAAC;AAElE;;;;GAIG;AACH,MAAM,cAAc,GAAG,eAAe,CAAC;AAEvC;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAkB,MAAM,CAAC,sBAAsB,CAAC,CAAC;AAiD3E;;;GAGG;AACH,MAAM,OAAO,cAAc;IAEd;IACA;IAFX,YACW,OAAuB,EACvB,QAA6B,IAAI;QADjC,YAAO,GAAP,OAAO,CAAgB;QACvB,UAAK,GAAL,KAAK,CAA4B;IACzC,CAAC;CACL;AAqCD,0EAA0E;AAE1E,0CAA0C;AAC1C,MAAM,QAAQ,GAAG,IAAI,OAAO,EAAoC,CAAC;AAEjE,iEAAiE;AACjE,MAAM,eAAe,GAAG,IAAI,OAAO,EAAmC,CAAC;AAEvE;;;;;;;GAOG;AACH,MAAM,oBAAoB,GAAG,IAAI,OAAO,EAA4B,CAAC;AAErE;;;;;;;GAOG;AACH,MAAM,oBAAoB,GAAG,IAAI,OAAO,EAA0B,CAAC;AAEnE;;;;;;GAMG;AACH,SAAS,aAAa,CACpB,OAAgB,EAChB,OAAuB,EACvB,MAAc;IAEd,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACvC,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,UAAU,GAAG,oBAAoB,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;QAC7D,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,IAAI,OAAO,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;YAChE,MAAM,IAAI,KAAK,CACb,kBAAkB,MAAM,uDAAuD;gBAC7E,2BAA2B,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,+BAA+B,GAAG;gBACrG,iFAAiF;gBACjF,0FAA0F,CAC7F,CAAC;QACJ,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,iBAAiB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACtE,MAAM,cAAc,GAAG,kBAAkB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,CAC5D,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,cAAc,CAAC,OAAO,EAAE,KAAK,CAAC,CAChD,CAAC;IACF,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;IACtC,oBAAoB,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC;IACzD,OAAO,cAAc,CAAC;AACxB,CAAC;AAED;;;;GAIG;AACH,SAAS,SAAS,CAAC,MAAgC;IACjD,OAAO,MAAM,YAAY,kBAAkB,CAAC;AAC9C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAgC,EAChC,UAA0B,EAAE;IAE5B,MAAM,eAAe,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC3C,MAAM,OAAO,GAAY,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;IAErE,wEAAwE;IACxE,0EAA0E;IAC1E,gDAAgD;IAChD,MAAM,cAAc,GAAG,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,mBAAmB,CAAC,CAAC;IAE5E,6DAA6D;IAC7D,+DAA+D;IAC/D,kEAAkE;IAClE,kEAAkE;IAClE,8BAA8B;IAC9B,IAAI,eAAe,EAAE,CAAC;QACpB,MAAM,UAAU,GAAG,oBAAoB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACrD,IAAI,UAAU;YAAE,OAAO,UAAU,CAAC;IACpC,CAAC;IAED,MAAM,GAAG,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC/D,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,cAAc,CAAC;IAEhD,MAAM,MAAM,GAAG,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACxC,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,MAAM,aAAa,GAAkB;QACnC,IAAI,EAAE,SAAS;QACf,OAAO;QACP,OAAO,EAAE,GAAG;QACZ,MAAM;QACN,cAAc;KACf,CAAC;IACF,MAAM,MAAM,GAAoB,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,aAAa,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC;IAClF,eAAe,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,eAAe;QAAE,oBAAoB,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC/D,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,0EAA0E;AAC1E,MAAM,qBAAqB,GAAG,IAAI,OAAO,EAA4B,CAAC;AAEtE;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAgB,EAChB,UAA0B,EAAE;IAE5B,0EAA0E;IAC1E,MAAM,cAAc,GAAG,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,wBAAwB,CAAC,CAAC;IAEjF,MAAM,MAAM,GAAG,qBAAqB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAClD,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,MAAM,aAAa,GAAkB;QACnC,IAAI,EAAE,SAAS;QACf,OAAO;QACP,mEAAmE;QACnE,gEAAgE;QAChE,gDAAgD;QAChD,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;QAC/B,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,cAAc;QACxC,cAAc;QACd,KAAK,EAAE,IAAI;KACZ,CAAC;IACF,MAAM,MAAM,GAAoB,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,aAAa,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC;IAClF,qBAAqB,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC3C,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,GAAgB,EAChB,UAA8B,EAAE;IAEhC,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IAC3F,kEAAkE;IAClE,mEAAmE;IACnE,eAAe;IACf,MAAM,MAAM,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;IACtC,MAAM,UAAU,GAAe,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;IACxE,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,aAAa,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC;AACxD,CAAC;AAED;;;;GAIG;AACH,SAAS,WAAW,CAAC,SAA6B;IAChD,OAAO,EAAE,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC;AAClC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,OAAwB;IAC/C,MAAM,CAAC,GAAI,OAAwC,CAAC,aAAa,CAAC,CAAC;IACnE,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,IAAI,SAAS,CACjB,uGAAuG,CACxG,CAAC;IACJ,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAwB;IACxD,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;IACjC,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,qEAAqE,CAAC,CAAC;IACzF,CAAC;IACD,OAAO,MAAM,CAAC,cAAc,CAAC;AAC/B,CAAC"}

package/dist/storage/upload.d.ts

@@ -0,0 +1,43 @@
+import { type SettableMetadata, type UploadResult } from './metadata.js';
+import type { StoredMetadata } from './persistence.js';
+import { type StorageReference } from './reference.js';
+/** `uploadString` format selector. */
+export type StringFormat = 'raw' | 'base64' | 'data_url';
+/**
+ * Upload bytes to the reference's `fullPath`. Replaces any existing
+ * object at the path. Returns the populated `FullMetadata` and the
+ * same `ref` for chaining.
+ *
+ * Throws when the reference targets the root (`fullPath === ''`) —
+ * uploads need a non-empty path, matching Firebase's
+ * `invalid-root-operation` precondition.
+ */
+export declare function uploadBytes(ref: StorageReference, data: Blob | Uint8Array | ArrayBuffer, metadata?: SettableMetadata): Promise<UploadResult>;
+/**
+ * Upload a string in one of three formats:
+ *
+ *   - `raw` (default): UTF-8 text. Defaults `contentType` to
+ *     `text/plain;charset=utf-8` if neither metadata nor the data
+ *     specify one.
+ *   - `base64`: standard base64-encoded bytes.
+ *   - `data_url`: a `data:` URL — the MIME prefix is honored as
+ *     `contentType` unless the caller overrides it explicitly.
+ */
+export declare function uploadString(ref: StorageReference, value: string, format?: StringFormat, metadata?: SettableMetadata): Promise<UploadResult>;
+/**
+ * Build the `StoredMetadata` record we'll persist alongside the
+ * blob. Server-set fields are populated here in one place so
+ * Slice 6's `getMetadata` reads a consistent shape.
+ *
+ * Exported for the rare cases where Slice 8's rule pre-check needs
+ * to materialize the about-to-write metadata to feed into the
+ * evaluator (specifically `request.resource.size` /
+ * `.contentType`).
+ */
+export declare function buildStoredMetadata(args: {
+    ref: StorageReference;
+    blob: Blob;
+    settable: SettableMetadata | undefined;
+    now?: Date;
+}): StoredMetadata;
+//# sourceMappingURL=upload.d.ts.map

package/dist/storage/upload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload.d.ts","sourceRoot":"","sources":["../../src/storage/upload.ts"],"names":[],"mappings":"AA8BA,OAAO,EAAkB,KAAK,gBAAgB,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAEzF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAW,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAIhE,sCAAsC;AACtC,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEzD;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,IAAI,GAAG,UAAU,GAAG,WAAW,EACrC,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,OAAO,CAAC,YAAY,CAAC,CAsDvB;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,gBAAgB,EACrB,KAAK,EAAE,MAAM,EACb,MAAM,GAAE,YAAoB,EAC5B,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,OAAO,CAAC,YAAY,CAAC,CAOvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,GAAG,EAAE,gBAAgB,CAAC;IACtB,IAAI,EAAE,IAAI,CAAC;IACX,QAAQ,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACvC,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ,GAAG,cAAc,CA0BjB"}