pyric-admin 0.1.0-alpha.21 → 0.1.0-alpha.24

package/dist/storage/index.d.ts

@@ -7,10 +7,10 @@
  *
  *   - **Remote sandbox path** — a handle branded by `@pyric/cli`'
  *     `connectRemoteSandbox()`/`remoteSandbox()` relays every data
- *     operation over the bridge to the browser-hosted SharedWorker's
- *     object store (admin lens pinned — rules bypass). Single bucket;
- *     8 MiB per-op byte cap; `getSignedUrl` stays the local stub. See
- *     the remote arm section below.
+ *     operation to the sandbox's host (admin lens pinned — rules bypass).
+ *     Bytes move over the host's HTTP byte route when it has one, and as
+ *     frames when it does not (a browser tab's SharedWorker). Single bucket;
+ *     `getSignedUrl` stays the local stub. See the remote arm section below.
  *
  *   - **Sandbox path** — returns an in-process {@link Storage} backed
  *     by an in-memory `Map<bucketName, Map<path, FileEntry>>`. State
@@ -23,16 +23,24 @@
  *       - `storage.bucket(name?)` → {@link Bucket}-shaped handle
  *       - `bucket.file(path)` → {@link File}-shaped handle
  *       - `file.save(data, options?)` — `Buffer | string | Uint8Array`
- *       - `file.download(options?)` → `[Buffer]`
+ *       - `file.download(options?)` → `[Buffer]`, whole or `start..end`
+ *       - `file.createReadStream(options?)`, whole or `start..end`
+ *       - `file.createWriteStream(options?)`
+ *       - `file.getMetadata()` / `file.setMetadata(metadata)`: settable fields
+ *         and custom metadata; a custom key set to `null` is removed
+ *       - `getDownloadURL(file)`: mints a token into
+ *         `firebaseStorageDownloadTokens` when the file has none. The Node
+ *         host returns its HTTP URL; elsewhere the URL is a `data:` URI
  *       - `file.delete()` — idempotent
  *       - `file.exists()` → `[boolean]`
  *       - `file.getSignedUrl(options)` → `['pyric-sandbox-storage://…']`
  *
  *     **Deferred in the sandbox backend** (throws `"not implemented in
- *     pyric-admin/storage sandbox backend"`): streaming uploads
- *     (`createWriteStream`), resumable uploads, signed cookies, IAM
- *     policies, lifecycle rules, ACLs, copy/move, notifications.
+ *     pyric-admin/storage sandbox backend"`): resumable uploads, signed
+ *     cookies, IAM policies, lifecycle rules, ACLs, copy/move,
+ *     notifications.
  */
+import { Readable, Writable } from 'node:stream';
 import { type PyricAdminApp } from '../app/index.js';
 /**
  * `pyric-admin/storage`'s sandbox `Storage` handle. It exposes the subset
@@ -64,9 +72,9 @@ export interface Bucket {
  * / getSignedUrl, etc.) so common consumer code retains the familiar shape.
  *
  * The sandbox backend implements the methods documented here. Any
- * other `File` method from `@google-cloud/storage` (`createWriteStream`,
- * `createReadStream`, `copy`, `move`, `setMetadata` beyond the basic
- * `save` options, etc.) throws on the sandbox path — see module header.
+ * other `File` method from `@google-cloud/storage` (`copy`, `move`,
+ * `setMetadata` beyond the basic `save` options, etc.) is not implemented
+ * on the sandbox path — see module header.
  */
 export interface File {
     /** Name (path) of the file within its bucket. */
@@ -82,11 +90,30 @@ export interface File {
      */
     save(data: Buffer | string | Uint8Array, options?: SaveOptions): Promise<void>;
     /**
-     * Read the file's bytes. Returns a `[Buffer]` tuple to mirror
-     * `@google-cloud/storage`'s `File.download` (which returns
-     * `[Buffer, ...]`). Throws if the file does not exist.
+     * Read the file's bytes, or the inclusive range `start..end` of them.
+     * Returns a `[Buffer]` tuple to mirror `@google-cloud/storage`'s
+     * `File.download` (which returns `[Buffer, ...]`). Throws if the file
+     * does not exist.
      */
     download(options?: DownloadOptions): Promise<[Buffer]>;
+    /**
+     * A readable stream of the file's bytes, or of the inclusive range
+     * `start..end`. A missing file surfaces as the stream's error.
+     */
+    createReadStream(options?: CreateReadStreamOptions): Readable;
+    /**
+     * A writable stream whose bytes replace the file's content once the
+     * stream finishes, as {@link File.save} does.
+     */
+    createWriteStream(options?: CreateWriteStreamOptions): Writable;
+    /** The file's metadata, as a `[metadata]` tuple. Throws if the file does not exist. */
+    getMetadata(): Promise<[FileMetadata]>;
+    /**
+     * Change the file's metadata: the named settable fields, and the custom
+     * keys under `metadata`, where `null` removes a key and the others stay.
+     * Removing `firebaseStorageDownloadTokens` revokes the file's download URL.
+     */
+    setMetadata(metadata: FileMetadataUpdate): Promise<[FileMetadata]>;
     /**
      * Remove the file from its bucket. Idempotent — deleting a missing
      * file is a no-op (matches `@google-cloud/storage`'s
@@ -127,9 +154,49 @@ export interface SaveOptions {
 }
 /** Options bag for {@link File.download}. Subset of `@google-cloud/storage`'s `DownloadOptions`. */
 export interface DownloadOptions {
+    /** First byte to read, inclusive. */
+    start?: number;
+    /** Last byte to read, inclusive. */
+    end?: number;
     /** The sandbox accepts but ignores `validation`. */
     validation?: 'md5' | 'crc32c' | boolean;
 }
+/** Options bag for {@link File.createReadStream}. Subset of `@google-cloud/storage`'s `CreateReadStreamOptions`. */
+export type CreateReadStreamOptions = DownloadOptions;
+/** Options bag for {@link File.createWriteStream}. Subset of `@google-cloud/storage`'s `CreateWriteStreamOptions`. */
+export interface CreateWriteStreamOptions {
+    /** Stored alongside the file, as {@link SaveOptions.metadata} is. */
+    metadata?: Record<string, unknown>;
+    /** Content type stored on the file. */
+    contentType?: string;
+}
+/** Settable fields the sandbox keeps, besides custom metadata. */
+declare const SETTABLE_FIELDS: readonly ["contentType", "cacheControl", "contentDisposition", "contentEncoding", "contentLanguage"];
+type SettableField = (typeof SETTABLE_FIELDS)[number];
+/** A file's metadata. Subset of `@google-cloud/storage`'s `FileMetadata`. */
+export interface FileMetadata {
+    name: string;
+    bucket: string;
+    generation: string;
+    metageneration: string;
+    /** Size in bytes, as a decimal string. */
+    size: string;
+    timeCreated: string;
+    updated: string;
+    contentType?: string;
+    cacheControl?: string;
+    contentDisposition?: string;
+    contentEncoding?: string;
+    contentLanguage?: string;
+    md5Hash?: string;
+    /** Custom metadata, including `firebaseStorageDownloadTokens` once the file has a download URL. Absent when there is none. */
+    metadata?: Record<string, string>;
+}
+/** What {@link File.setMetadata} takes. Subset of `@google-cloud/storage`'s `FileMetadata`. */
+export type FileMetadataUpdate = Partial<Pick<FileMetadata, SettableField>> & {
+    /** Custom keys to set; `null` removes a key. Values are stored as strings. */
+    metadata?: Record<string, string | number | boolean | null>;
+};
 /** Options bag for {@link File.getSignedUrl}. Mirrors `@google-cloud/storage`'s shape. */
 export interface GetSignedUrlOptions {
     /** `'read' | 'write' | 'delete' | 'resumable'`. Sandbox stamps it into the URL only as a hint. */
@@ -157,8 +224,13 @@ export type StorageApp = PyricAdminApp;
  */
 export declare function getStorage(app?: StorageApp): Storage;
 /**
- * Link-compatible mirror of `firebase-admin/storage`'s `getDownloadURL(file)`.
- * Returns a deterministic sandbox storage stub URL from `file.getSignedUrl()`.
+ * Mirror of `firebase-admin/storage`'s `getDownloadURL(file)`. A file without
+ * a download token gets one in `firebaseStorageDownloadTokens`, as production
+ * mints it. On the Node host the URL is its HTTP byte route URL, which serves
+ * ranges and stops working when the token is removed. In process and on a
+ * SharedWorker host there is no HTTP origin, so the URL is a `data:` URI that
+ * carries the bytes.
  */
 export declare function getDownloadURL(file: File): Promise<string>;
+export {};
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AASH,OAAO,EAGL,KAAK,aAAa,EAEnB,MAAM,iBAAiB,CAAC;AAKzB;;;;;;GAMG;AACH,MAAM,WAAW,OAAO;IACtB;;;OAGG;IACH,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,MAAM;IACrB,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,IAAI;IACnB,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;;OAMG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/E;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IACvD;;;;OAIG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,qGAAqG;IACrG,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAC7B;;;;;;OAMG;IACH,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;CAC/D;AAED,4FAA4F;AAC5F,MAAM,WAAW,WAAW;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,oGAAoG;AACpG,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,UAAU,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAC;CACzC;AAED,0FAA0F;AAC1F,MAAM,WAAW,mBAAmB;IAClC,kGAAkG;IAClG,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,WAAW,CAAC;IAClD;;;;OAIG;IACH,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CACjC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,aAAa,CAAC;AAEvC;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,CAAC,EAAE,UAAU,GAAG,OAAO,CAuBpD;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAGhE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"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"}