@ttt-productions/media-processing-core 0.8.16 → 0.8.18

package/dist/server/gcs-errors.js

@@ -1,15 +1,7 @@
-import { R2StorageError } from "./r2-retry.js";
-/**
- * True when a storage read or delete failed because the object does not exist, from
- * either backend this package's stores use, decided from structured fields only — never
- * from message text, which a library may rewrite and which carries no contract. The R2
- * store's `R2StorageError` answers with status `404` and S3 error code `NoSuchKey`, which
- * tells a missing key from a missing bucket (`NoSuchBucket`); the Cloud Storage Admin SDK
- * answers with the numeric HTTP code `404`.
- */
+import { R2StorageError } from './r2-retry.js';
 export function isObjectNotFoundError(e) {
     if (e instanceof R2StorageError)
-        return e.status === 404 && e.s3ErrorCode === "NoSuchKey";
+        return e.status === 404 && e.s3ErrorCode === 'NoSuchKey';
     return e?.code === 404;
 }
 //# 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,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,CAAU;IAC9C,IAAI,CAAC,YAAY,cAAc;QAAE,OAAO,CAAC,CAAC,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,WAAW,KAAK,WAAW,CAAC;IAC1F,OAAQ,CAA2C,EAAE,IAAI,KAAK,GAAG,CAAC;AACpE,CAAC","sourcesContent":["import { R2StorageError } from \"./r2-retry.js\";\n\n/**\n * True when a storage read or delete failed because the object does not exist, from\n * either backend this package's stores use, decided from structured fields only — never\n * from message text, which a library may rewrite and which carries no contract. The R2\n * store's `R2StorageError` answers with status `404` and S3 error code `NoSuchKey`, which\n * tells a missing key from a missing bucket (`NoSuchBucket`); the Cloud Storage Admin SDK\n * answers with the numeric HTTP code `404`.\n */\nexport function isObjectNotFoundError(e: unknown): boolean {\n  if (e instanceof R2StorageError) return e.status === 404 && e.s3ErrorCode === \"NoSuchKey\";\n  return (e as { code?: unknown } | null | undefined)?.code === 404;\n}\n"]}
+{"version":3,"file":"gcs-errors.js","sourceRoot":"","sources":["../../src/server/gcs-errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,MAAM,UAAU,qBAAqB,CAAC,CAAU;IAC9C,IAAI,CAAC,YAAY,cAAc;QAAE,OAAO,CAAC,CAAC,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,WAAW,KAAK,WAAW,CAAC;IAC1F,OAAQ,CAA2C,EAAE,IAAI,KAAK,GAAG,CAAC;AACpE,CAAC","sourcesContent":["import { R2StorageError } from './r2-retry.js';\n\nexport function isObjectNotFoundError(e: unknown): boolean {\n  if (e instanceof R2StorageError) return e.status === 404 && e.s3ErrorCode === 'NoSuchKey';\n  return (e as { code?: unknown } | null | undefined)?.code === 404;\n}\n"]}

package/dist/server/index.d.ts

@@ -1,7 +1,8 @@
-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";
-export * from "./download-token.js";
+export * from './storage-ops.js';
+export { R2StorageError } from './r2-retry.js';
+export * from './firebase-media-io.js';
+export * from './pending-media.js';
+export * from './staged-object.js';
+export * from './gcs-errors.js';
+export * from './download-token.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;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC"}

package/dist/server/index.js

@@ -1,7 +1,8 @@
-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";
-export * from "./download-token.js";
+export * from './storage-ops.js';
+export { R2StorageError } from './r2-retry.js';
+export * from './firebase-media-io.js';
+export * from './pending-media.js';
+export * from './staged-object.js';
+export * from './gcs-errors.js';
+export * from './download-token.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;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,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\";\nexport * from \"./download-token.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC","sourcesContent":["export * from './storage-ops.js';\nexport { R2StorageError } from './r2-retry.js';\nexport * from './firebase-media-io.js';\nexport * from './pending-media.js';\nexport * from './staged-object.js';\nexport * from './gcs-errors.js';\nexport * from './download-token.js';\n"]}

package/dist/server/pending-media.d.ts

@@ -1,6 +1,5 @@
-import type { DocumentReference, DocumentSnapshot, Firestore, Transaction } from "firebase-admin/firestore";
-import { type ClaimablePendingMedia, type PendingMediaClaimOutcome, type PendingMediaClaimPolicy, type PendingMediaFinalizeResult, type PendingMediaTerminalStatus } from "@ttt-productions/media-schemas";
-/** The app's pending-media row schema — anything with zod's `safeParse` shape. */
+import type { DocumentReference, DocumentSnapshot, Firestore, Transaction } from 'firebase-admin/firestore';
+import { type ClaimablePendingMedia, type PendingMediaClaimOutcome, type PendingMediaClaimPolicy, type PendingMediaFinalizeResult, type PendingMediaTerminalStatus } from '@ttt-productions/media-schemas';
 export interface PendingMediaRowParser<TRow> {
     safeParse(data: unknown): {
         success: true;
@@ -12,54 +11,24 @@ export interface PendingMediaRowParser<TRow> {
 export interface ClaimPendingMediaOptions<TRow> {
     schema: PendingMediaRowParser<TRow>;
     policy: PendingMediaClaimPolicy;
-    /** Epoch ms; defaults to `Date.now()`. */
     now?: number;
 }
-/**
- * Claim a row for processing inside `transaction`, driven by the CURRENT row (never a
- * frozen event snapshot). Reads before any write. A row that no longer parses is
- * `missing` and never dispatched: a corrupt row must not drive the processor.
- */
 export declare function claimPendingMediaForProcessing<TRow extends ClaimablePendingMedia>(transaction: Transaction, pendingMediaRef: DocumentReference, options: ClaimPendingMediaOptions<TRow>): Promise<PendingMediaClaimOutcome<TRow>>;
 export interface PendingMediaFinalizeContext {
     targetStatus: PendingMediaTerminalStatus;
-    /** True when the row failed schema validation and is being failed as unparsable. */
     unparsable: boolean;
 }
-/**
- * Caller-owned writes that must commit atomically with a terminal transition, and only
- * when it applies (releasing a quota reservation, for example — exactly once, because
- * the compare-and-set gates it). It runs in the transaction's READ phase and may
- * `transaction.get`; it returns the WRITE-phase step, or undefined when there is nothing
- * to write. The step runs after the terminal write, and its return value is surfaced as
- * the outcome's `extra`.
- */
 export type PendingMediaExtraWrites<TExtra> = (transaction: Transaction, snapshot: DocumentSnapshot, context: PendingMediaFinalizeContext) => Promise<(() => TExtra) | undefined>;
 export interface FinalizePendingMediaOptions<TExtra> {
-    /** Merged into the terminal fields (`result`, `errorCategory`, `errorMessage`, …). */
     extraFields?: Record<string, unknown>;
     extraWrites?: PendingMediaExtraWrites<TExtra>;
-    /** Epoch ms; defaults to `Date.now()`. */
     now?: number;
 }
 export interface PendingMediaFinalizeOutcome<TExtra> extends PendingMediaFinalizeResult {
-    /** What the extra writes returned — present only on `applied`, when they wrote. */
     extra?: TExtra;
 }
-/**
- * Compare-and-set finalize inside the caller's transaction: re-read the row, decide,
- * and write the terminal fields (plus any extra writes) only on `applied`. An
- * already-terminal row is never overwritten. Reads-before-writes holds as long as the
- * caller has issued no write on `transaction` yet.
- */
+/** The caller must not have written on `transaction` yet: a Firestore transaction reads before its first write. */
 export declare function finalizePendingMediaInTransaction<TExtra = never>(transaction: Transaction, ref: DocumentReference, targetStatus: PendingMediaTerminalStatus, options?: FinalizePendingMediaOptions<TExtra>): Promise<PendingMediaFinalizeOutcome<TExtra>>;
-/** Standalone compare-and-set finalize, in its own transaction. */
 export declare function finalizePendingMedia<TExtra = never>(db: Firestore, ref: DocumentReference, targetStatus: PendingMediaTerminalStatus, options?: FinalizePendingMediaOptions<TExtra>): Promise<PendingMediaFinalizeOutcome<TExtra>>;
-/**
- * Fail a row that no longer passes schema validation, so the transition table cannot
- * be applied (it may carry no readable `status`). One transaction: the row is failed —
- * with any extra writes — only while it has no status or a `pending` / `processing`
- * one, so an already-terminal row is never touched and extra writes run exactly once.
- */
 export declare function finalizeUnparsablePendingMedia<TExtra = never>(db: Firestore, ref: DocumentReference, options?: FinalizePendingMediaOptions<TExtra>): Promise<void>;
 //# sourceMappingURL=pending-media.d.ts.map

package/dist/server/pending-media.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pending-media.d.ts","sourceRoot":"","sources":["../../src/server/pending-media.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5G,OAAO,EAML,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,0BAA0B,EAC/B,KAAK,0BAA0B,EAChC,MAAM,gCAAgC,CAAC;AAMxC,kFAAkF;AAClF,MAAM,WAAW,qBAAqB,CAAC,IAAI;IACzC,SAAS,CAAC,IAAI,EAAE,OAAO,GAAG;QAAE,OAAO,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,OAAO,EAAE,KAAK,CAAA;KAAE,CAAC;CAC9E;AAED,MAAM,WAAW,wBAAwB,CAAC,IAAI;IAC5C,MAAM,EAAE,qBAAqB,CAAC,IAAI,CAAC,CAAC;IACpC,MAAM,EAAE,uBAAuB,CAAC;IAChC,0CAA0C;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAsB,8BAA8B,CAAC,IAAI,SAAS,qBAAqB,EACrF,WAAW,EAAE,WAAW,EACxB,eAAe,EAAE,iBAAiB,EAClC,OAAO,EAAE,wBAAwB,CAAC,IAAI,CAAC,GACtC,OAAO,CAAC,wBAAwB,CAAC,IAAI,CAAC,CAAC,CAWzC;AAMD,MAAM,WAAW,2BAA2B;IAC1C,YAAY,EAAE,0BAA0B,CAAC;IACzC,oFAAoF;IACpF,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,uBAAuB,CAAC,MAAM,IAAI,CAC5C,WAAW,EAAE,WAAW,EACxB,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,2BAA2B,KACjC,OAAO,CAAC,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC;AAEzC,MAAM,WAAW,2BAA2B,CAAC,MAAM;IACjD,sFAAsF;IACtF,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,WAAW,CAAC,EAAE,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAC9C,0CAA0C;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,2BAA2B,CAAC,MAAM,CAAE,SAAQ,0BAA0B;IACrF,mFAAmF;IACnF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAsB,iCAAiC,CAAC,MAAM,GAAG,KAAK,EACpE,WAAW,EAAE,WAAW,EACxB,GAAG,EAAE,iBAAiB,EACtB,YAAY,EAAE,0BAA0B,EACxC,OAAO,GAAE,2BAA2B,CAAC,MAAM,CAAM,GAChD,OAAO,CAAC,2BAA2B,CAAC,MAAM,CAAC,CAAC,CAW9C;AAED,mEAAmE;AACnE,wBAAgB,oBAAoB,CAAC,MAAM,GAAG,KAAK,EACjD,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,iBAAiB,EACtB,YAAY,EAAE,0BAA0B,EACxC,OAAO,GAAE,2BAA2B,CAAC,MAAM,CAAM,GAChD,OAAO,CAAC,2BAA2B,CAAC,MAAM,CAAC,CAAC,CAE9C;AAED;;;;;GAKG;AACH,wBAAsB,8BAA8B,CAAC,MAAM,GAAG,KAAK,EACjE,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,iBAAiB,EACtB,OAAO,GAAE,2BAA2B,CAAC,MAAM,CAAM,GAChD,OAAO,CAAC,IAAI,CAAC,CAYf"}
+{"version":3,"file":"pending-media.d.ts","sourceRoot":"","sources":["../../src/server/pending-media.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,SAAS,EACT,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAML,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,0BAA0B,EAC/B,KAAK,0BAA0B,EAChC,MAAM,gCAAgC,CAAC;AAExC,MAAM,WAAW,qBAAqB,CAAC,IAAI;IACzC,SAAS,CAAC,IAAI,EAAE,OAAO,GAAG;QAAE,OAAO,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,OAAO,EAAE,KAAK,CAAA;KAAE,CAAC;CAC9E;AAED,MAAM,WAAW,wBAAwB,CAAC,IAAI;IAC5C,MAAM,EAAE,qBAAqB,CAAC,IAAI,CAAC,CAAC;IACpC,MAAM,EAAE,uBAAuB,CAAC;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,wBAAsB,8BAA8B,CAAC,IAAI,SAAS,qBAAqB,EACrF,WAAW,EAAE,WAAW,EACxB,eAAe,EAAE,iBAAiB,EAClC,OAAO,EAAE,wBAAwB,CAAC,IAAI,CAAC,GACtC,OAAO,CAAC,wBAAwB,CAAC,IAAI,CAAC,CAAC,CAezC;AAED,MAAM,WAAW,2BAA2B;IAC1C,YAAY,EAAE,0BAA0B,CAAC;IACzC,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,MAAM,uBAAuB,CAAC,MAAM,IAAI,CAC5C,WAAW,EAAE,WAAW,EACxB,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,2BAA2B,KACjC,OAAO,CAAC,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC;AAEzC,MAAM,WAAW,2BAA2B,CAAC,MAAM;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,WAAW,CAAC,EAAE,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAC9C,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,2BAA2B,CAAC,MAAM,CAAE,SAAQ,0BAA0B;IACrF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,mHAAmH;AACnH,wBAAsB,iCAAiC,CAAC,MAAM,GAAG,KAAK,EACpE,WAAW,EAAE,WAAW,EACxB,GAAG,EAAE,iBAAiB,EACtB,YAAY,EAAE,0BAA0B,EACxC,OAAO,GAAE,2BAA2B,CAAC,MAAM,CAAM,GAChD,OAAO,CAAC,2BAA2B,CAAC,MAAM,CAAC,CAAC,CAqB9C;AAED,wBAAgB,oBAAoB,CAAC,MAAM,GAAG,KAAK,EACjD,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,iBAAiB,EACtB,YAAY,EAAE,0BAA0B,EACxC,OAAO,GAAE,2BAA2B,CAAC,MAAM,CAAM,GAChD,OAAO,CAAC,2BAA2B,CAAC,MAAM,CAAC,CAAC,CAI9C;AAED,wBAAsB,8BAA8B,CAAC,MAAM,GAAG,KAAK,EACjE,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,iBAAiB,EACtB,OAAO,GAAE,2BAA2B,CAAC,MAAM,CAAM,GAChD,OAAO,CAAC,IAAI,CAAC,CAkBf"}

package/dist/server/pending-media.js

@@ -1,53 +1,33 @@
-// Admin-SDK transaction wrappers for the pending-media lifecycle. The decisions are the
-// pure ones in `@ttt-productions/media-schemas` (`decidePendingMediaClaim`,
-// `decidePendingMediaFinalize`); these read the CURRENT row inside a transaction,
-// decide, and write. Everything app-specific is injected: the row's `DocumentReference`
-// (so no collection name lives here), the row schema, the claim policy, the extra
-// writes a terminal transition carries, and the clock.
-import { buildPendingMediaTerminalFields, decidePendingMediaClaim, decidePendingMediaFinalize, isPendingMediaNonTerminalStatus, PendingMediaStatusSchema, } from "@ttt-productions/media-schemas";
-/**
- * Claim a row for processing inside `transaction`, driven by the CURRENT row (never a
- * frozen event snapshot). Reads before any write. A row that no longer parses is
- * `missing` and never dispatched: a corrupt row must not drive the processor.
- */
+import { buildPendingMediaTerminalFields, decidePendingMediaClaim, decidePendingMediaFinalize, isPendingMediaNonTerminalStatus, PendingMediaStatusSchema, } from '@ttt-productions/media-schemas';
 export async function claimPendingMediaForProcessing(transaction, pendingMediaRef, options) {
     const snap = await transaction.get(pendingMediaRef);
     if (!snap.exists)
-        return { kind: "missing" };
+        return { kind: 'missing' };
     const parsed = options.schema.safeParse(snap.data());
     if (!parsed.success)
-        return { kind: "missing" };
+        return { kind: 'missing' };
     const { outcome, write } = decidePendingMediaClaim(parsed.data, options.now ?? Date.now(), options.policy);
     // Spread into a literal: the Admin SDK's update() wants an UpdateData-compatible object.
     if (write)
         transaction.update(pendingMediaRef, { ...write });
     return outcome;
 }
-/**
- * Compare-and-set finalize inside the caller's transaction: re-read the row, decide,
- * and write the terminal fields (plus any extra writes) only on `applied`. An
- * already-terminal row is never overwritten. Reads-before-writes holds as long as the
- * caller has issued no write on `transaction` yet.
- */
+/** The caller must not have written on `transaction` yet: a Firestore transaction reads before its first write. */
 export async function finalizePendingMediaInTransaction(transaction, ref, targetStatus, options = {}) {
     const snap = await transaction.get(ref);
     const result = decidePendingMediaFinalize(snap.exists ? (snap.data() ?? {}) : undefined, targetStatus);
-    if (result.decision !== "applied")
+    if (result.decision !== 'applied')
         return result;
-    const applyExtra = await options.extraWrites?.(transaction, snap, { targetStatus, unparsable: false });
+    const applyExtra = await options.extraWrites?.(transaction, snap, {
+        targetStatus,
+        unparsable: false,
+    });
     transaction.update(ref, buildPendingMediaTerminalFields(targetStatus, options.extraFields ?? {}, options.now ?? Date.now()));
     return applyExtra ? { ...result, extra: applyExtra() } : result;
 }
-/** Standalone compare-and-set finalize, in its own transaction. */
 export function finalizePendingMedia(db, ref, targetStatus, options = {}) {
     return db.runTransaction((transaction) => finalizePendingMediaInTransaction(transaction, ref, targetStatus, options));
 }
-/**
- * Fail a row that no longer passes schema validation, so the transition table cannot
- * be applied (it may carry no readable `status`). One transaction: the row is failed —
- * with any extra writes — only while it has no status or a `pending` / `processing`
- * one, so an already-terminal row is never touched and extra writes run exactly once.
- */
 export async function finalizeUnparsablePendingMedia(db, ref, options = {}) {
     await db.runTransaction(async (transaction) => {
         const snap = await transaction.get(ref);
@@ -57,7 +37,10 @@ export async function finalizeUnparsablePendingMedia(db, ref, options = {}) {
         if (status !== undefined && !isPendingMediaNonTerminalStatus(status))
             return;
         const failed = PendingMediaStatusSchema.enum.failed;
-        const applyExtra = await options.extraWrites?.(transaction, snap, { targetStatus: failed, unparsable: true });
+        const applyExtra = await options.extraWrites?.(transaction, snap, {
+            targetStatus: failed,
+            unparsable: true,
+        });
         transaction.update(ref, buildPendingMediaTerminalFields(failed, options.extraFields ?? {}, options.now ?? Date.now()));
         applyExtra?.();
     });

package/dist/server/pending-media.js.map

@@ -1 +1 @@
-{"version":3,"file":"pending-media.js","sourceRoot":"","sources":["../../src/server/pending-media.ts"],"names":[],"mappings":"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","sourcesContent":["// Admin-SDK transaction wrappers for the pending-media lifecycle. The decisions are the\n// pure ones in `@ttt-productions/media-schemas` (`decidePendingMediaClaim`,\n// `decidePendingMediaFinalize`); these read the CURRENT row inside a transaction,\n// decide, and write. Everything app-specific is injected: the row's `DocumentReference`\n// (so no collection name lives here), the row schema, the claim policy, the extra\n// writes a terminal transition carries, and the clock.\n\nimport type { DocumentReference, DocumentSnapshot, Firestore, Transaction } from \"firebase-admin/firestore\";\nimport {\n  buildPendingMediaTerminalFields,\n  decidePendingMediaClaim,\n  decidePendingMediaFinalize,\n  isPendingMediaNonTerminalStatus,\n  PendingMediaStatusSchema,\n  type ClaimablePendingMedia,\n  type PendingMediaClaimOutcome,\n  type PendingMediaClaimPolicy,\n  type PendingMediaFinalizeResult,\n  type PendingMediaTerminalStatus,\n} from \"@ttt-productions/media-schemas\";\n\n// ---------------------------------------------------------------------------\n// Claim\n// ---------------------------------------------------------------------------\n\n/** The app's pending-media row schema — anything with zod's `safeParse` shape. */\nexport interface PendingMediaRowParser<TRow> {\n  safeParse(data: unknown): { success: true; data: TRow } | { success: false };\n}\n\nexport interface ClaimPendingMediaOptions<TRow> {\n  schema: PendingMediaRowParser<TRow>;\n  policy: PendingMediaClaimPolicy;\n  /** Epoch ms; defaults to `Date.now()`. */\n  now?: number;\n}\n\n/**\n * Claim a row for processing inside `transaction`, driven by the CURRENT row (never a\n * frozen event snapshot). Reads before any write. A row that no longer parses is\n * `missing` and never dispatched: a corrupt row must not drive the processor.\n */\nexport async function claimPendingMediaForProcessing<TRow extends ClaimablePendingMedia>(\n  transaction: Transaction,\n  pendingMediaRef: DocumentReference,\n  options: ClaimPendingMediaOptions<TRow>,\n): Promise<PendingMediaClaimOutcome<TRow>> {\n  const snap = await transaction.get(pendingMediaRef);\n  if (!snap.exists) return { kind: \"missing\" };\n\n  const parsed = options.schema.safeParse(snap.data());\n  if (!parsed.success) return { kind: \"missing\" };\n\n  const { outcome, write } = decidePendingMediaClaim(parsed.data, options.now ?? Date.now(), options.policy);\n  // Spread into a literal: the Admin SDK's update() wants an UpdateData-compatible object.\n  if (write) transaction.update(pendingMediaRef, { ...write });\n  return outcome;\n}\n\n// ---------------------------------------------------------------------------\n// Finalize\n// ---------------------------------------------------------------------------\n\nexport interface PendingMediaFinalizeContext {\n  targetStatus: PendingMediaTerminalStatus;\n  /** True when the row failed schema validation and is being failed as unparsable. */\n  unparsable: boolean;\n}\n\n/**\n * Caller-owned writes that must commit atomically with a terminal transition, and only\n * when it applies (releasing a quota reservation, for example — exactly once, because\n * the compare-and-set gates it). It runs in the transaction's READ phase and may\n * `transaction.get`; it returns the WRITE-phase step, or undefined when there is nothing\n * to write. The step runs after the terminal write, and its return value is surfaced as\n * the outcome's `extra`.\n */\nexport type PendingMediaExtraWrites<TExtra> = (\n  transaction: Transaction,\n  snapshot: DocumentSnapshot,\n  context: PendingMediaFinalizeContext,\n) => Promise<(() => TExtra) | undefined>;\n\nexport interface FinalizePendingMediaOptions<TExtra> {\n  /** Merged into the terminal fields (`result`, `errorCategory`, `errorMessage`, …). */\n  extraFields?: Record<string, unknown>;\n  extraWrites?: PendingMediaExtraWrites<TExtra>;\n  /** Epoch ms; defaults to `Date.now()`. */\n  now?: number;\n}\n\nexport interface PendingMediaFinalizeOutcome<TExtra> extends PendingMediaFinalizeResult {\n  /** What the extra writes returned — present only on `applied`, when they wrote. */\n  extra?: TExtra;\n}\n\n/**\n * Compare-and-set finalize inside the caller's transaction: re-read the row, decide,\n * and write the terminal fields (plus any extra writes) only on `applied`. An\n * already-terminal row is never overwritten. Reads-before-writes holds as long as the\n * caller has issued no write on `transaction` yet.\n */\nexport async function finalizePendingMediaInTransaction<TExtra = never>(\n  transaction: Transaction,\n  ref: DocumentReference,\n  targetStatus: PendingMediaTerminalStatus,\n  options: FinalizePendingMediaOptions<TExtra> = {},\n): Promise<PendingMediaFinalizeOutcome<TExtra>> {\n  const snap = await transaction.get(ref);\n  const result = decidePendingMediaFinalize(snap.exists ? (snap.data() ?? {}) : undefined, targetStatus);\n  if (result.decision !== \"applied\") return result;\n\n  const applyExtra = await options.extraWrites?.(transaction, snap, { targetStatus, unparsable: false });\n  transaction.update(\n    ref,\n    buildPendingMediaTerminalFields(targetStatus, options.extraFields ?? {}, options.now ?? Date.now()),\n  );\n  return applyExtra ? { ...result, extra: applyExtra() } : result;\n}\n\n/** Standalone compare-and-set finalize, in its own transaction. */\nexport function finalizePendingMedia<TExtra = never>(\n  db: Firestore,\n  ref: DocumentReference,\n  targetStatus: PendingMediaTerminalStatus,\n  options: FinalizePendingMediaOptions<TExtra> = {},\n): Promise<PendingMediaFinalizeOutcome<TExtra>> {\n  return db.runTransaction((transaction) => finalizePendingMediaInTransaction(transaction, ref, targetStatus, options));\n}\n\n/**\n * Fail a row that no longer passes schema validation, so the transition table cannot\n * be applied (it may carry no readable `status`). One transaction: the row is failed —\n * with any extra writes — only while it has no status or a `pending` / `processing`\n * one, so an already-terminal row is never touched and extra writes run exactly once.\n */\nexport async function finalizeUnparsablePendingMedia<TExtra = never>(\n  db: Firestore,\n  ref: DocumentReference,\n  options: FinalizePendingMediaOptions<TExtra> = {},\n): Promise<void> {\n  await db.runTransaction(async (transaction) => {\n    const snap = await transaction.get(ref);\n    if (!snap.exists) return;\n    const status = (snap.data() as { status?: unknown } | undefined)?.status;\n    if (status !== undefined && !isPendingMediaNonTerminalStatus(status)) return;\n\n    const failed = PendingMediaStatusSchema.enum.failed;\n    const applyExtra = await options.extraWrites?.(transaction, snap, { targetStatus: failed, unparsable: true });\n    transaction.update(ref, buildPendingMediaTerminalFields(failed, options.extraFields ?? {}, options.now ?? Date.now()));\n    applyExtra?.();\n  });\n}\n"]}
+{"version":3,"file":"pending-media.js","sourceRoot":"","sources":["../../src/server/pending-media.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  DocumentReference,\n  DocumentSnapshot,\n  Firestore,\n  Transaction,\n} from 'firebase-admin/firestore';\nimport {\n  buildPendingMediaTerminalFields,\n  decidePendingMediaClaim,\n  decidePendingMediaFinalize,\n  isPendingMediaNonTerminalStatus,\n  PendingMediaStatusSchema,\n  type ClaimablePendingMedia,\n  type PendingMediaClaimOutcome,\n  type PendingMediaClaimPolicy,\n  type PendingMediaFinalizeResult,\n  type PendingMediaTerminalStatus,\n} from '@ttt-productions/media-schemas';\n\nexport interface PendingMediaRowParser<TRow> {\n  safeParse(data: unknown): { success: true; data: TRow } | { success: false };\n}\n\nexport interface ClaimPendingMediaOptions<TRow> {\n  schema: PendingMediaRowParser<TRow>;\n  policy: PendingMediaClaimPolicy;\n  now?: number;\n}\n\nexport async function claimPendingMediaForProcessing<TRow extends ClaimablePendingMedia>(\n  transaction: Transaction,\n  pendingMediaRef: DocumentReference,\n  options: ClaimPendingMediaOptions<TRow>,\n): Promise<PendingMediaClaimOutcome<TRow>> {\n  const snap = await transaction.get(pendingMediaRef);\n  if (!snap.exists) return { kind: 'missing' };\n\n  const parsed = options.schema.safeParse(snap.data());\n  if (!parsed.success) return { kind: 'missing' };\n\n  const { outcome, write } = decidePendingMediaClaim(\n    parsed.data,\n    options.now ?? Date.now(),\n    options.policy,\n  );\n  // Spread into a literal: the Admin SDK's update() wants an UpdateData-compatible object.\n  if (write) transaction.update(pendingMediaRef, { ...write });\n  return outcome;\n}\n\nexport interface PendingMediaFinalizeContext {\n  targetStatus: PendingMediaTerminalStatus;\n  unparsable: boolean;\n}\n\nexport type PendingMediaExtraWrites<TExtra> = (\n  transaction: Transaction,\n  snapshot: DocumentSnapshot,\n  context: PendingMediaFinalizeContext,\n) => Promise<(() => TExtra) | undefined>;\n\nexport interface FinalizePendingMediaOptions<TExtra> {\n  extraFields?: Record<string, unknown>;\n  extraWrites?: PendingMediaExtraWrites<TExtra>;\n  now?: number;\n}\n\nexport interface PendingMediaFinalizeOutcome<TExtra> extends PendingMediaFinalizeResult {\n  extra?: TExtra;\n}\n\n/** The caller must not have written on `transaction` yet: a Firestore transaction reads before its first write. */\nexport async function finalizePendingMediaInTransaction<TExtra = never>(\n  transaction: Transaction,\n  ref: DocumentReference,\n  targetStatus: PendingMediaTerminalStatus,\n  options: FinalizePendingMediaOptions<TExtra> = {},\n): Promise<PendingMediaFinalizeOutcome<TExtra>> {\n  const snap = await transaction.get(ref);\n  const result = decidePendingMediaFinalize(\n    snap.exists ? (snap.data() ?? {}) : undefined,\n    targetStatus,\n  );\n  if (result.decision !== 'applied') return result;\n\n  const applyExtra = await options.extraWrites?.(transaction, snap, {\n    targetStatus,\n    unparsable: false,\n  });\n  transaction.update(\n    ref,\n    buildPendingMediaTerminalFields(\n      targetStatus,\n      options.extraFields ?? {},\n      options.now ?? Date.now(),\n    ),\n  );\n  return applyExtra ? { ...result, extra: applyExtra() } : result;\n}\n\nexport function finalizePendingMedia<TExtra = never>(\n  db: Firestore,\n  ref: DocumentReference,\n  targetStatus: PendingMediaTerminalStatus,\n  options: FinalizePendingMediaOptions<TExtra> = {},\n): Promise<PendingMediaFinalizeOutcome<TExtra>> {\n  return db.runTransaction((transaction) =>\n    finalizePendingMediaInTransaction(transaction, ref, targetStatus, options),\n  );\n}\n\nexport async function finalizeUnparsablePendingMedia<TExtra = never>(\n  db: Firestore,\n  ref: DocumentReference,\n  options: FinalizePendingMediaOptions<TExtra> = {},\n): Promise<void> {\n  await db.runTransaction(async (transaction) => {\n    const snap = await transaction.get(ref);\n    if (!snap.exists) return;\n    const status = (snap.data() as { status?: unknown } | undefined)?.status;\n    if (status !== undefined && !isPendingMediaNonTerminalStatus(status)) return;\n\n    const failed = PendingMediaStatusSchema.enum.failed;\n    const applyExtra = await options.extraWrites?.(transaction, snap, {\n      targetStatus: failed,\n      unparsable: true,\n    });\n    transaction.update(\n      ref,\n      buildPendingMediaTerminalFields(failed, options.extraFields ?? {}, options.now ?? Date.now()),\n    );\n    applyExtra?.();\n  });\n}\n"]}

package/dist/server/r2-retry.d.ts

@@ -1,71 +1,29 @@
-/** TOTAL attempts (initial + retries) — three totals means at most TWO delays. */
 export declare const R2_REQUEST_MAX_ATTEMPTS = 3;
-/** Base delay for full-jitter exponential backoff. */
 export declare const R2_RETRY_BASE_DELAY_MS = 250;
-/** Ceiling on the exponential backoff (before jitter). */
 export declare const R2_RETRY_MAX_BACKOFF_MS = 5000;
-/** Hard cap on an honored server `Retry-After` so one response can't eat the
- *  caller's whole timeout budget. */
 export declare const R2_RETRY_AFTER_CAP_MS = 30000;
-/** HTTP statuses treated as transient and safe to retry. */
 export declare const R2_RETRYABLE_STATUSES: ReadonlySet<number>;
-export type R2RetryableOperation = "putFile" | "copy" | "readToFile" | "deleteCopy";
-/** Every R2 store operation an `R2StorageError` can name; `delete` never retries. */
-export type R2Operation = R2RetryableOperation | "delete";
-/** Deterministic seams for tests; production defaults are internal (see below). */
+export type R2RetryableOperation = 'putFile' | 'copy' | 'readToFile' | 'deleteCopy';
+export type R2Operation = R2RetryableOperation | 'delete';
 export interface R2RetrySeams {
-    /** Resolve after `ms` milliseconds. */
     sleep: (ms: number) => Promise<void>;
-    /** Uniform random in [0, 1). */
     random: () => number;
-    /** Epoch-millisecond clock — keeps HTTP-date `Retry-After` tests off wall-clock. */
     now: () => number;
 }
-/** Production seam defaults. */
 export declare function defaultR2RetrySeams(): R2RetrySeams;
-/**
- * True only for recognized transient transport failures. An explicit
- * `AbortError` and deterministic local-filesystem errors always return false —
- * an abort must never become another attempt.
- */
 export declare function isRetryableTransportError(err: unknown): boolean;
-/**
- * Parse a `Retry-After` header value into a non-negative millisecond delay.
- * Supports both the delta-seconds form (`"120"`) and the HTTP-date form
- * (`"Wed, 21 Oct 2015 07:28:00 GMT"`). Returns null when absent/unparseable.
- * An HTTP-date in the past clamps to 0.
- */
 export declare function parseRetryAfterMs(headerValue: string | null | undefined, nowMs: number): number | null;
-/**
- * Compute the pre-next-attempt delay. If the failed response carries a valid
- * `Retry-After`, honor it (capped, no backoff added on top). Otherwise use
- * full-jitter exponential backoff: `random(0, min(maxBackoff, base * 2^retryIndex))`.
- */
 export declare function computeR2DelayMs(params: {
     response: Response | null;
-    /** 0-based index of the retry about to happen (0 for the first retry). */
     retryIndex: number;
     seams: R2RetrySeams;
 }): number;
-/**
- * Thrown when an R2 operation fails: a retried operation exhausts its attempts or
- * hits a non-retryable response, or a one-shot delete fails. Carries
- * operation/bucket/key/attempt/status context, the S3 error code parsed from the
- * response body, and the bounded body itself as properties — never credentials,
- * authorization headers, or full signed URLs. Callers classify it from those
- * properties, never from the message.
- *
- * The message names only the operation, the attempts, the status, and the S3 error
- * code. The bucket, the key, and the raw body — which can echo either — stay out of
- * it, so an escaping error never carries an object key to monitoring.
- */
 export declare class R2StorageError extends Error {
     readonly operation: R2Operation;
     readonly bucket: string;
     readonly key: string;
     readonly attempts: number;
     readonly status?: number;
-    /** The S3 `<Code>` of the response body (`NoSuchKey`, `PreconditionFailed`, …), when it had one. */
     readonly s3ErrorCode?: string;
     readonly responseText?: string;
     constructor(params: {
@@ -79,18 +37,12 @@ export declare class R2StorageError extends Error {
     });
 }
 export type R2AttemptResult<T> = {
-    kind: "success";
+    kind: 'success';
     value: T;
 } | {
-    kind: "response";
+    kind: 'response';
     response: Response;
 };
-/**
- * Drive up to `R2_REQUEST_MAX_ATTEMPTS` attempts of a single storage operation.
- * `runAttempt` builds a FRESH signed request each call and returns either a
- * success value or the raw `Response` for the driver to classify. Thrown errors
- * are classified: only recognized transient transport failures are retried.
- */
 export declare function fetchWithR2Retry<T>(params: {
     operation: R2RetryableOperation;
     bucket: string;

package/dist/server/r2-retry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"r2-retry.d.ts","sourceRoot":"","sources":["../../src/server/r2-retry.ts"],"names":[],"mappings":"AAiBA,kFAAkF;AAClF,eAAO,MAAM,uBAAuB,IAAI,CAAC;AACzC,sDAAsD;AACtD,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAC1C,0DAA0D;AAC1D,eAAO,MAAM,uBAAuB,OAAQ,CAAC;AAC7C;qCACqC;AACrC,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAE5C,4DAA4D;AAC5D,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,MAAM,CAA2C,CAAC;AAElG,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,MAAM,GAAG,YAAY,GAAG,YAAY,CAAC;AAEpF,qFAAqF;AACrF,MAAM,MAAM,WAAW,GAAG,oBAAoB,GAAG,QAAQ,CAAC;AAE1D,mFAAmF;AACnF,MAAM,WAAW,YAAY;IAC3B,uCAAuC;IACvC,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,gCAAgC;IAChC,MAAM,EAAE,MAAM,MAAM,CAAC;IACrB,oFAAoF;IACpF,GAAG,EAAE,MAAM,MAAM,CAAC;CACnB;AAED,gCAAgC;AAChC,wBAAgB,mBAAmB,IAAI,YAAY,CAMlD;AAsDD;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAwB/D;AAMD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiBtG;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IACvC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC1B,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,YAAY,CAAC;CACrB,GAAG,MAAM,CAYT;AAMD;;;;;;;;;;;GAWG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,oGAAoG;IACpG,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;gBAEnB,MAAM,EAAE;QAClB,SAAS,EAAE,WAAW,CAAC;QACvB,MAAM,EAAE,MAAM,CAAC;QACf,GAAG,EAAE,MAAM,CAAC;QACZ,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CAgBF;AAWD,MAAM,MAAM,eAAe,CAAC,CAAC,IACzB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAC7B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,CAAC;AAyB7C;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE;IAChD,SAAS,EAAE,oBAAoB,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,YAAY,CAAC;IACpB,UAAU,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;CACpE,GAAG,OAAO,CAAC,CAAC,CAAC,CAoCb"}
+{"version":3,"file":"r2-retry.d.ts","sourceRoot":"","sources":["../../src/server/r2-retry.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,uBAAuB,IAAI,CAAC;AACzC,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAC1C,eAAO,MAAM,uBAAuB,OAAQ,CAAC;AAC7C,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAE5C,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,MAAM,CAA2C,CAAC;AAElG,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,MAAM,GAAG,YAAY,GAAG,YAAY,CAAC;AAEpF,MAAM,MAAM,WAAW,GAAG,oBAAoB,GAAG,QAAQ,CAAC;AAE1D,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,EAAE,MAAM,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,MAAM,CAAC;CACnB;AAED,wBAAgB,mBAAmB,IAAI,YAAY,CAMlD;AA8CD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAmB/D;AAED,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACtC,KAAK,EAAE,MAAM,GACZ,MAAM,GAAG,IAAI,CAef;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IACvC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,YAAY,CAAC;CACrB,GAAG,MAAM,CAYT;AAED,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;gBAEnB,MAAM,EAAE;QAClB,SAAS,EAAE,WAAW,CAAC;QACvB,MAAM,EAAE,MAAM,CAAC;QACf,GAAG,EAAE,MAAM,CAAC;QACZ,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CAkBF;AAMD,MAAM,MAAM,eAAe,CAAC,CAAC,IAC3B;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,CAAC;AAqB3E,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE;IAChD,SAAS,EAAE,oBAAoB,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,YAAY,CAAC;IACpB,UAAU,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;CACpE,GAAG,OAAO,CAAC,CAAC,CAAC,CA+Bb"}