@ttt-productions/media-processing-core 0.8.8 → 0.8.9

package/dist/server/gcs-errors.d.ts

@@ -1,6 +1,9 @@
 /**
- * True when a Cloud Storage call failed because the object does not exist. The Admin
- * SDK reports it as a numeric or string `404` code, or only in the message.
+ * True when a storage read or delete failed because the object does not exist, from
+ * either backend this package's stores use. The Cloud Storage Admin SDK reports it as a
+ * numeric or string `404` code, or only in the message ("No such object"); the R2 store
+ * throws an `R2StorageError` whose message carries the S3 `NoSuchKey` error code. Any
+ * other failure — an R2 `NoSuchBucket` included — is not an object-not-found.
  */
 export declare function isObjectNotFoundError(e: unknown): boolean;
 //# sourceMappingURL=gcs-errors.d.ts.map

package/dist/server/gcs-errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gcs-errors.d.ts","sourceRoot":"","sources":["../../src/server/gcs-errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAGzD"}
+{"version":3,"file":"gcs-errors.d.ts","sourceRoot":"","sources":["../../src/server/gcs-errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAGzD"}

package/dist/server/gcs-errors.js

@@ -1,9 +1,12 @@
 /**
- * True when a Cloud Storage call failed because the object does not exist. The Admin
- * SDK reports it as a numeric or string `404` code, or only in the message.
+ * True when a storage read or delete failed because the object does not exist, from
+ * either backend this package's stores use. The Cloud Storage Admin SDK reports it as a
+ * numeric or string `404` code, or only in the message ("No such object"); the R2 store
+ * throws an `R2StorageError` whose message carries the S3 `NoSuchKey` error code. Any
+ * other failure — an R2 `NoSuchBucket` included — is not an object-not-found.
  */
 export function isObjectNotFoundError(e) {
     const err = e;
-    return err?.code === 404 || err?.code === "404" || /No such object/i.test(String(err?.message));
+    return err?.code === 404 || err?.code === "404" || /No such object|NoSuchKey/i.test(String(err?.message));
 }
 //# sourceMappingURL=gcs-errors.js.map

package/dist/server/gcs-errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"gcs-errors.js","sourceRoot":"","sources":["../../src/server/gcs-errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,CAAU;IAC9C,MAAM,GAAG,GAAG,CAA6D,CAAC;IAC1E,OAAO,GAAG,EAAE,IAAI,KAAK,GAAG,IAAI,GAAG,EAAE,IAAI,KAAK,KAAK,IAAI,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC;AAClG,CAAC","sourcesContent":["/**\n * True when a Cloud Storage call failed because the object does not exist. The Admin\n * SDK reports it as a numeric or string `404` code, or only in the message.\n */\nexport function isObjectNotFoundError(e: unknown): boolean {\n  const err = e as { code?: unknown; message?: unknown } | null | undefined;\n  return err?.code === 404 || err?.code === \"404\" || /No such object/i.test(String(err?.message));\n}\n"]}
+{"version":3,"file":"gcs-errors.js","sourceRoot":"","sources":["../../src/server/gcs-errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,CAAU;IAC9C,MAAM,GAAG,GAAG,CAA6D,CAAC;IAC1E,OAAO,GAAG,EAAE,IAAI,KAAK,GAAG,IAAI,GAAG,EAAE,IAAI,KAAK,KAAK,IAAI,2BAA2B,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC;AAC5G,CAAC","sourcesContent":["/**\n * True when a storage read or delete failed because the object does not exist, from\n * either backend this package's stores use. The Cloud Storage Admin SDK reports it as a\n * numeric or string `404` code, or only in the message (\"No such object\"); the R2 store\n * throws an `R2StorageError` whose message carries the S3 `NoSuchKey` error code. Any\n * other failure — an R2 `NoSuchBucket` included — is not an object-not-found.\n */\nexport function isObjectNotFoundError(e: unknown): boolean {\n  const err = e as { code?: unknown; message?: unknown } | null | undefined;\n  return err?.code === 404 || err?.code === \"404\" || /No such object|NoSuchKey/i.test(String(err?.message));\n}\n"]}

package/dist/server/index.d.ts

@@ -2,4 +2,5 @@ export * from "./storage-ops.js";
 export * from "./firebase-media-io.js";
 export * from "./pending-media.js";
 export * from "./staged-object.js";
+export * from "./gcs-errors.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC"}

package/dist/server/index.js

@@ -2,4 +2,5 @@ export * from "./storage-ops.js";
 export * from "./firebase-media-io.js";
 export * from "./pending-media.js";
 export * from "./staged-object.js";
+export * from "./gcs-errors.js";
 //# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC","sourcesContent":["export * from \"./storage-ops.js\";\nexport * from \"./firebase-media-io.js\";\nexport * from \"./pending-media.js\";\nexport * from \"./staged-object.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC","sourcesContent":["export * from \"./storage-ops.js\";\nexport * from \"./firebase-media-io.js\";\nexport * from \"./pending-media.js\";\nexport * from \"./staged-object.js\";\nexport * from \"./gcs-errors.js\";\n"]}

package/dist/server/staged-object.d.ts

@@ -18,6 +18,15 @@ export type StagedUploadMetadataRead = {
  * failure throws.
  */
 export declare function readStagedUploadMetadata(bucket: Bucket, storagePath: string): Promise<StagedUploadMetadataRead>;
+/**
+ * The staged object's generation from metadata the caller already fetched, as a string
+ * (GCS generations exceed 2^53) — the one normalization `readStagedObjectGeneration`
+ * applies, for a processor that already holds the object's metadata and must not read
+ * it again. `undefined` when the metadata carries no generation (the emulator may not).
+ */
+export declare function stagedObjectGenerationFromMetadata(metadata: {
+    generation?: string | number | null;
+}): string | undefined;
 export interface ReadStagedObjectGenerationOptions {
     /** Called when the generation cannot be read (the caller logs it); reads then stay unpinned. */
     onReadFailure?: (error: unknown) => void;

package/dist/server/staged-object.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"staged-object.d.ts","sourceRoot":"","sources":["../../src/server/staged-object.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE/C,sFAAsF;AACtF,MAAM,WAAW,oBAAoB;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED,MAAM,MAAM,wBAAwB,GAChC;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,oBAAoB,CAAA;CAAE,GAC/C;IAAE,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAErB;;;;GAIG;AACH,wBAAsB,wBAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAQrH;AAED,MAAM,WAAW,iCAAiC;IAChD,gGAAgG;IAChG,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC1C;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,0BAA0B,CAC9C,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,OAAO,GAAE,iCAAsC,GAC9C,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAU7B;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAEnF"}
+{"version":3,"file":"staged-object.d.ts","sourceRoot":"","sources":["../../src/server/staged-object.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE/C,sFAAsF;AACtF,MAAM,WAAW,oBAAoB;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED,MAAM,MAAM,wBAAwB,GAChC;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,oBAAoB,CAAA;CAAE,GAC/C;IAAE,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAErB;;;;GAIG;AACH,wBAAsB,wBAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAQrH;AAED;;;;;GAKG;AACH,wBAAgB,kCAAkC,CAAC,QAAQ,EAAE;IAC3D,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CACrC,GAAG,MAAM,GAAG,SAAS,CAGrB;AAED,MAAM,WAAW,iCAAiC;IAChD,gGAAgG;IAChG,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC1C;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,0BAA0B,CAC9C,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,OAAO,GAAE,iCAAsC,GAC9C,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAS7B;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAEnF"}

package/dist/server/staged-object.js

@@ -18,6 +18,16 @@ export async function readStagedUploadMetadata(bucket, storagePath) {
         throw e;
     }
 }
+/**
+ * The staged object's generation from metadata the caller already fetched, as a string
+ * (GCS generations exceed 2^53) — the one normalization `readStagedObjectGeneration`
+ * applies, for a processor that already holds the object's metadata and must not read
+ * it again. `undefined` when the metadata carries no generation (the emulator may not).
+ */
+export function stagedObjectGenerationFromMetadata(metadata) {
+    const { generation } = metadata;
+    return generation === undefined || generation === null ? undefined : String(generation);
+}
 /**
  * The staged object's current generation, as a string (GCS generations exceed 2^53).
  *
@@ -34,8 +44,7 @@ export async function readStagedObjectGeneration(bucket, storagePath, options =
         return undefined;
     try {
         const [metadata] = await bucket.file(storagePath).getMetadata();
-        const generation = metadata.generation;
-        return generation === undefined || generation === null ? undefined : String(generation);
+        return stagedObjectGenerationFromMetadata(metadata);
     }
     catch (e) {
         options.onReadFailure?.(e);

package/dist/server/staged-object.js.map

@@ -1 +1 @@
-{"version":3,"file":"staged-object.js","sourceRoot":"","sources":["../../src/server/staged-object.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,+EAA+E;AAC/E,oEAAoE;AAEpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAexD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAAC,MAAc,EAAE,WAAmB;IAChF,IAAI,CAAC;QACH,MAAM,CAAC,QAAQ,CAAC,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,WAAW,EAAE,CAAC;QAChE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IACnC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,qBAAqB,CAAC,CAAC,CAAC;YAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QACtD,MAAM,CAAC,CAAC;IACV,CAAC;AACH,CAAC;AAOD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,MAAc,EACd,WAA+B,EAC/B,UAA6C,EAAE;IAE/C,IAAI,CAAC,WAAW;QAAE,OAAO,SAAS,CAAC;IACnC,IAAI,CAAC;QACH,MAAM,CAAC,QAAQ,CAAC,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,WAAW,EAAE,CAAC;QAChE,MAAM,UAAU,GAAG,QAAQ,CAAC,UAAU,CAAC;QACvC,OAAO,UAAU,KAAK,SAAS,IAAI,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAC1F,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,CAAC;QAC3B,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,UAA8B;IACzE,OAAO,UAAU,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,UAAU,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;AACzD,CAAC","sourcesContent":["// Admin-SDK reads of a STAGED upload object (the client-written staging copy a\n// processor reads from). The accept-time verdict over the metadata is the pure\n// `verifyStagedUploadMetadata` in `@ttt-productions/media-schemas`.\n\nimport { isObjectNotFoundError } from \"./gcs-errors.js\";\nimport type { Bucket } from \"./storage-ops.js\";\n\n/** The stored-object metadata fields these reads use (the Admin SDK returns more). */\nexport interface StagedObjectMetadata {\n  contentType?: string;\n  size?: string | number;\n  generation?: string | number;\n  [field: string]: unknown;\n}\n\nexport type StagedUploadMetadataRead =\n  | { found: true; metadata: StagedObjectMetadata }\n  | { found: false };\n\n/**\n * Read a staged object's stored metadata (`contentType`, `size`, `generation`, …) for\n * `verifyStagedUploadMetadata`. A missing object is `{ found: false }`; any other read\n * failure throws.\n */\nexport async function readStagedUploadMetadata(bucket: Bucket, storagePath: string): Promise<StagedUploadMetadataRead> {\n  try {\n    const [metadata] = await bucket.file(storagePath).getMetadata();\n    return { found: true, metadata };\n  } catch (e) {\n    if (isObjectNotFoundError(e)) return { found: false };\n    throw e;\n  }\n}\n\nexport interface ReadStagedObjectGenerationOptions {\n  /** Called when the generation cannot be read (the caller logs it); reads then stay unpinned. */\n  onReadFailure?: (error: unknown) => void;\n}\n\n/**\n * The staged object's current generation, as a string (GCS generations exceed 2^53).\n *\n * This is the one value that pins every later read of the staged bytes — the processing\n * download, a moderation scan, a hash — to the SAME immutable object, so \"processed\n * bytes == scanned bytes == hashed bytes\" holds even if the staging path were\n * overwritten (a pinned read resolves exactly the captured generation). Returns\n * `undefined` when no path is given, the object reports no generation (the emulator may\n * not), or the read fails — best effort: callers fall back to unpinned reads, and a\n * create-only staging rule stays the primary defense.\n */\nexport async function readStagedObjectGeneration(\n  bucket: Bucket,\n  storagePath: string | undefined,\n  options: ReadStagedObjectGenerationOptions = {},\n): Promise<string | undefined> {\n  if (!storagePath) return undefined;\n  try {\n    const [metadata] = await bucket.file(storagePath).getMetadata();\n    const generation = metadata.generation;\n    return generation === undefined || generation === null ? undefined : String(generation);\n  } catch (e) {\n    options.onReadFailure?.(e);\n    return undefined;\n  }\n}\n\n/**\n * A `gs://` URI pinned to a captured generation (`gs://bucket/path#<generation>`), so a\n * service reading by URI (a moderation scan) reads the same bytes the processor did.\n * Without a generation it is the bare URI.\n */\nexport function pinnedGcsUri(gcsUri: string, generation: string | undefined): string {\n  return generation ? `${gcsUri}#${generation}` : gcsUri;\n}\n"]}
+{"version":3,"file":"staged-object.js","sourceRoot":"","sources":["../../src/server/staged-object.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,+EAA+E;AAC/E,oEAAoE;AAEpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAexD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAAC,MAAc,EAAE,WAAmB;IAChF,IAAI,CAAC;QACH,MAAM,CAAC,QAAQ,CAAC,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,WAAW,EAAE,CAAC;QAChE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IACnC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,qBAAqB,CAAC,CAAC,CAAC;YAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QACtD,MAAM,CAAC,CAAC;IACV,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kCAAkC,CAAC,QAElD;IACC,MAAM,EAAE,UAAU,EAAE,GAAG,QAAQ,CAAC;IAChC,OAAO,UAAU,KAAK,SAAS,IAAI,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;AAC1F,CAAC;AAOD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,MAAc,EACd,WAA+B,EAC/B,UAA6C,EAAE;IAE/C,IAAI,CAAC,WAAW;QAAE,OAAO,SAAS,CAAC;IACnC,IAAI,CAAC;QACH,MAAM,CAAC,QAAQ,CAAC,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,WAAW,EAAE,CAAC;QAChE,OAAO,kCAAkC,CAAC,QAAQ,CAAC,CAAC;IACtD,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,CAAC;QAC3B,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,UAA8B;IACzE,OAAO,UAAU,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,UAAU,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;AACzD,CAAC","sourcesContent":["// Admin-SDK reads of a STAGED upload object (the client-written staging copy a\n// processor reads from). The accept-time verdict over the metadata is the pure\n// `verifyStagedUploadMetadata` in `@ttt-productions/media-schemas`.\n\nimport { isObjectNotFoundError } from \"./gcs-errors.js\";\nimport type { Bucket } from \"./storage-ops.js\";\n\n/** The stored-object metadata fields these reads use (the Admin SDK returns more). */\nexport interface StagedObjectMetadata {\n  contentType?: string;\n  size?: string | number;\n  generation?: string | number;\n  [field: string]: unknown;\n}\n\nexport type StagedUploadMetadataRead =\n  | { found: true; metadata: StagedObjectMetadata }\n  | { found: false };\n\n/**\n * Read a staged object's stored metadata (`contentType`, `size`, `generation`, …) for\n * `verifyStagedUploadMetadata`. A missing object is `{ found: false }`; any other read\n * failure throws.\n */\nexport async function readStagedUploadMetadata(bucket: Bucket, storagePath: string): Promise<StagedUploadMetadataRead> {\n  try {\n    const [metadata] = await bucket.file(storagePath).getMetadata();\n    return { found: true, metadata };\n  } catch (e) {\n    if (isObjectNotFoundError(e)) return { found: false };\n    throw e;\n  }\n}\n\n/**\n * The staged object's generation from metadata the caller already fetched, as a string\n * (GCS generations exceed 2^53) — the one normalization `readStagedObjectGeneration`\n * applies, for a processor that already holds the object's metadata and must not read\n * it again. `undefined` when the metadata carries no generation (the emulator may not).\n */\nexport function stagedObjectGenerationFromMetadata(metadata: {\n  generation?: string | number | null;\n}): string | undefined {\n  const { generation } = metadata;\n  return generation === undefined || generation === null ? undefined : String(generation);\n}\n\nexport interface ReadStagedObjectGenerationOptions {\n  /** Called when the generation cannot be read (the caller logs it); reads then stay unpinned. */\n  onReadFailure?: (error: unknown) => void;\n}\n\n/**\n * The staged object's current generation, as a string (GCS generations exceed 2^53).\n *\n * This is the one value that pins every later read of the staged bytes — the processing\n * download, a moderation scan, a hash — to the SAME immutable object, so \"processed\n * bytes == scanned bytes == hashed bytes\" holds even if the staging path were\n * overwritten (a pinned read resolves exactly the captured generation). Returns\n * `undefined` when no path is given, the object reports no generation (the emulator may\n * not), or the read fails — best effort: callers fall back to unpinned reads, and a\n * create-only staging rule stays the primary defense.\n */\nexport async function readStagedObjectGeneration(\n  bucket: Bucket,\n  storagePath: string | undefined,\n  options: ReadStagedObjectGenerationOptions = {},\n): Promise<string | undefined> {\n  if (!storagePath) return undefined;\n  try {\n    const [metadata] = await bucket.file(storagePath).getMetadata();\n    return stagedObjectGenerationFromMetadata(metadata);\n  } catch (e) {\n    options.onReadFailure?.(e);\n    return undefined;\n  }\n}\n\n/**\n * A `gs://` URI pinned to a captured generation (`gs://bucket/path#<generation>`), so a\n * service reading by URI (a moderation scan) reads the same bytes the processor did.\n * Without a generation it is the bare URI.\n */\nexport function pinnedGcsUri(gcsUri: string, generation: string | undefined): string {\n  return generation ? `${gcsUri}#${generation}` : gcsUri;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttt-productions/media-processing-core",
-  "version": "0.8.8",
+  "version": "0.8.9",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ttt-productions/ttt-packages.git",