@mohasinac/appkit 4.38.0 → 4.39.0

package/dist/_internal/client/features/digital-code/CodeRevealPanel.d.ts

@@ -1,6 +1,25 @@
 import React from "react";
+/**
+ * What the buyer was actually delivered.
+ *
+ * A "digital code" listing delivers digital CONTENT — a redemption string is
+ * only its commonest shape. `contentKind` is optional and absent means `"code"`,
+ * so a delivery recorded before assets existed renders exactly as it always did.
+ */
 export interface RevealedCode {
-    code: string;
+    contentKind?: "code" | "image" | "file";
+    /** Present only for `contentKind: "code"`. */
+    code?: string;
+    /**
+     * Present for the asset kinds. Points at the AUTHENTICATED download route,
+     * never at Storage and never at `/media/` — see the route's own header for
+     * why that distinction is the whole security model here.
+     */
+    downloadUrl?: string;
+    fileName?: string;
+    contentType?: string;
+    /** Seller-authored redemption help, carried by the reveal response. */
+    redemptionInstructions?: string;
     orderId: string;
     claimedAt?: Date | string;
     expiresAt?: Date | string;

package/dist/_internal/client/features/digital-code/CodeRevealPanel.js

@@ -36,5 +36,25 @@ export function CodeRevealPanel({ orderId, redemptionInstructions, fetchCode, })
         setCopied(true);
         setTimeout(() => setCopied(false), 2000);
     }
-    return (_jsx(Div, { className: `border border-border bg-muted/40 ${__P.p4}`, rounded: "lg", children: _jsxs(Stack, { gap: "sm", children: [_jsx(Text, { weight: "medium", children: "Your Digital Code" }), !revealed ? (_jsxs(Stack, { gap: "sm", children: [error && _jsx(Text, { className: "text-destructive", size: "sm", children: error }), _jsx(Button, { type: "button", variant: "primary", size: "lg", isLoading: pending, disabled: pending, onClick: handleReveal, className: "w-full", children: "Reveal Code" })] })) : (_jsxs(Stack, { gap: "sm", children: [_jsxs(Row, { textSize: "lg", className: "border border-border bg-background font-mono", padding: "inlineSm", align: "center", gap: "sm", rounded: "md", children: [_jsx(Span, { className: "flex-1 select-all", children: revealed.code }), _jsx(Button, { type: "button", variant: "ghost", size: "sm", onClick: handleCopy, className: "shrink-0", children: copied ? "Copied!" : "Copy" })] }), redemptionInstructions && (_jsx(Text, { className: "text-muted-foreground", size: "sm", children: redemptionInstructions }))] }))] }) }));
+    return (_jsx(Div, { className: `border border-border bg-muted/40 ${__P.p4}`, rounded: "lg", children: _jsxs(Stack, { gap: "sm", children: [_jsx(Text, { weight: "medium", children: revealed && (revealed.contentKind ?? "code") !== "code"
+                        ? "Your Digital Content"
+                        : "Your Digital Code" }), !revealed ? (_jsxs(Stack, { gap: "sm", children: [error && _jsx(Text, { className: "text-destructive", size: "sm", children: error }), _jsx(Button, { type: "button", variant: "primary", size: "lg", isLoading: pending, disabled: pending, onClick: handleReveal, className: "w-full", children: "Reveal Code" })] })) : (_jsxs(Stack, { gap: "sm", children: [(revealed.contentKind ?? "code") === "code" ? (_jsxs(Row, { textSize: "lg", className: "border border-border bg-background font-mono", padding: "inlineSm", align: "center", gap: "sm", rounded: "md", children: [_jsx(Span, { className: "flex-1 select-all", children: revealed.code }), _jsx(Button, { type: "button", variant: "ghost", size: "sm", onClick: handleCopy, className: "shrink-0", children: copied ? "Copied!" : "Copy" })] })) : (
+                        /*
+                         * 🛑 A LINK, not an <img>/<MediaImage>. Rendering the asset inline
+                         * would need a URL a browser can GET without our session
+                         * semantics, and this one is a `private, no-store` authenticated
+                         * download that always answers `Content-Disposition: attachment`.
+                         * An <img src> pointed at it would show a broken image, and
+                         * "fixing" that by moving the bytes somewhere renderable is
+                         * precisely what publishes a paid good — see the download route's
+                         * header.
+                         *
+                         * Not a <Button onClick={fetch}> either: a same-origin anchor lets
+                         * the browser own the download, including resume and the file
+                         * name, and never materialises the bytes in JS memory.
+                         */
+                        _jsxs(Row, { className: "border border-border bg-background", padding: "inlineSm", align: "center", gap: "sm", rounded: "md", children: [_jsx(Span, { className: "flex-1 truncate", children: revealed.fileName ?? "Your download" }), _jsx(Button, { type: "button", variant: "primary", size: "sm", className: "shrink-0", onClick: () => {
+                                        if (revealed.downloadUrl)
+                                            window.location.assign(revealed.downloadUrl);
+                                    }, children: "Download" })] })), (redemptionInstructions ?? revealed.redemptionInstructions) && (_jsx(Text, { className: "text-muted-foreground", size: "sm", children: redemptionInstructions ?? revealed.redemptionInstructions }))] }))] }) }));
 }

package/dist/_internal/client/features/digital-code/DigitalContentPoolManager.d.ts

@@ -0,0 +1,40 @@
+import React from "react";
+/**
+ * The seller's view of what a digital-code listing will actually deliver.
+ *
+ * 🛑 WHY THIS COMPONENT HAD TO EXIST FOR THE FEATURE TO WORK AT ALL. The pool
+ * at `products/{id}/codes` is what `claimDigitalCodeForOrder` hands a buyer, and
+ * until 2026-09-14 nothing in the product could write to it — its one route
+ * answered 501. So the pool was always empty, every purchase logged "code pool
+ * exhausted" and completed anyway, and the buyer's reveal panel 404'd. Shipping
+ * the routes without this surface would have left the same gap one layer up: a
+ * working API nobody can reach is Root Cause #37's shape.
+ *
+ * Edit mode only — a pool is keyed on a product id, which does not exist until
+ * the listing has been created once.
+ */
+export interface PoolEntry {
+    id: string;
+    contentKind: "code" | "image" | "file";
+    status: string;
+    fileName?: string;
+    orderId?: string;
+    claimedAt?: string;
+    createdAt?: string;
+}
+export interface DigitalContentPoolManagerProps {
+    productId: string;
+    /**
+     * Injected so this component never hard-codes an API path — the same contract
+     * `CodeRevealPanel` uses. The consumer owns the transport.
+     */
+    api: {
+        list: (productId: string) => Promise<PoolEntry[]>;
+        addCodes: (productId: string, codes: string[]) => Promise<unknown>;
+        addAsset: (productId: string, file: File) => Promise<unknown>;
+        remove: (productId: string, entryId: string) => Promise<unknown>;
+    };
+    /** Non-image files are staff-only to upload; hide the affordance otherwise. */
+    canUploadFiles?: boolean;
+}
+export declare function DigitalContentPoolManager({ productId, api, canUploadFiles, }: DigitalContentPoolManagerProps): React.JSX.Element;

package/dist/_internal/client/features/digital-code/DigitalContentPoolManager.js

@@ -0,0 +1,67 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useState } from "react";
+import { normalizeError } from "../../../../errors/normalize";
+import { Alert, Button, Div, Row, Span, Stack, Text } from "../../../../ui";
+import { FilePickerButton } from "../../../../ui/components/FilePickerButton";
+import { FieldTextarea } from "../../../../ui/forms/FieldTextarea";
+const KIND_LABEL = {
+    code: "Code",
+    image: "QR / image",
+    file: "File",
+};
+export function DigitalContentPoolManager({ productId, api, canUploadFiles = false, }) {
+    const [entries, setEntries] = useState(null);
+    const [bulk, setBulk] = useState("");
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState(null);
+    const refresh = useCallback(async () => {
+        try {
+            setEntries(await api.list(productId));
+            setError(null);
+        }
+        catch (e) {
+            /*
+             * Surface it. An empty list and a failed list look identical, and "this
+             * listing has no codes" is exactly the wrong thing to tell a seller whose
+             * pool is full — the same confusion that made the 501 invisible.
+             */
+            setError(normalizeError(e).message || "Could not load the pool.");
+            setEntries([]);
+        }
+    }, [api, productId]);
+    useEffect(() => {
+        void refresh();
+    }, [refresh]);
+    async function run(fn) {
+        setBusy(true);
+        setError(null);
+        try {
+            await fn();
+            await refresh();
+        }
+        catch (e) {
+            setError(normalizeError(e).message || "That did not work.");
+        }
+        finally {
+            setBusy(false);
+        }
+    }
+    const available = (entries ?? []).filter((e) => e.status === "available").length;
+    const claimed = (entries ?? []).filter((e) => e.status === "claimed").length;
+    return (_jsxs(Stack, { gap: "md", children: [_jsx(Alert, { variant: "info", children: "Whatever you add here is what a buyer receives after paying. A listing with an empty pool can still be bought \u2014 and the buyer gets nothing \u2014 so add at least one entry before publishing." }), error && _jsx(Alert, { variant: "error", children: error }), _jsxs(Row, { gap: "md", align: "center", children: [_jsxs(Text, { size: "sm", children: [_jsx(Span, { weight: "semibold", children: available }), " available"] }), _jsxs(Text, { size: "sm", color: "muted", children: [_jsx(Span, { weight: "semibold", children: claimed }), " already delivered"] })] }), _jsx(FieldTextarea, { name: "bulkCodes", label: "Add codes", value: bulk, onChange: setBulk, rows: 4, placeholder: "ONE-CODE-PER-LINE\nANOTHER-CODE" }), _jsx(Text, { size: "xs", color: "muted", children: "One per line. Blank lines and duplicates within the paste are ignored." }), _jsxs(Row, { gap: "sm", children: [_jsx(Button, { type: "button", variant: "primary", size: "sm", isLoading: busy, disabled: busy || bulk.trim().length === 0, onClick: () => {
+                            // De-duplicate the paste itself. Re-pasting a list is the obvious
+                            // way to double a pool by accident, and a duplicated code is a
+                            // second buyer receiving something already sold.
+                            const codes = [
+                                ...new Set(bulk
+                                    .split("\n")
+                                    .map((l) => l.trim())
+                                    .filter(Boolean)),
+                            ];
+                            void run(async () => {
+                                await api.addCodes(productId, codes);
+                                setBulk("");
+                            });
+                        }, children: "Add codes" }), _jsx(FilePickerButton, { variant: "secondary", size: "sm", disabled: busy, accept: canUploadFiles ? undefined : "image/*", onFile: (file) => void run(() => api.addAsset(productId, file)), children: canUploadFiles ? "Upload QR or file" : "Upload QR image" })] }), _jsx(Div, { children: entries === null ? (_jsx(Text, { size: "sm", color: "muted", children: "Loading\u2026" })) : entries.length === 0 ? (_jsx(Text, { size: "sm", color: "muted", children: "Nothing in the pool yet." })) : (_jsx(Stack, { gap: "xs", children: entries.map((e) => (_jsxs(Row, { gap: "sm", align: "center", justify: "between", children: [_jsxs(Text, { size: "sm", children: [KIND_LABEL[e.contentKind], e.fileName ? ` — ${e.fileName}` : "", _jsxs(Span, { color: "muted", children: [" \u00B7 ", e.status] })] }), e.status !== "claimed" && (_jsx(Button, { type: "button", variant: "ghost", size: "sm", disabled: busy, onClick: () => void run(() => api.remove(productId, e.id)), children: "Remove" }))] }, e.id))) })) })] }));
+}

package/dist/_internal/server/features/checkout/actions.js

@@ -73,6 +73,24 @@ async function claimDigitalCodeForOrder(db, productId, orderId, userId, opts) {
         });
         claimed = true;
     });
+    if (claimed) {
+        /*
+         * Re-derive both pool counters. Nothing used to do this: the claim flipped a
+         * code to `claimed` and left `digitalCode.codesAvailable` exactly as the
+         * seller had typed it, so the availability predicate — which reads that
+         * counter — could never notice a listing selling out. Counting beats
+         * decrementing here because the counter was never trustworthy to begin with
+         * (Root Cause #42).
+         *
+         * Deliberately awaited but non-fatal inside: a failed recount must not undo
+         * a claim the buyer has already paid for.
+         */
+        const { recountPool } = await import("../digital-code/pool");
+        await recountPool(productId).catch((e) => serverLogger.error("claimDigitalCode: recount failed", {
+            error: normalizeError(e).message,
+            productId,
+        }));
+    }
     if (claimed && opts?.userEmail) {
         const { sendDigitalCodeClaimedEmail } = await import("../../../../features/contact/server");
         sendDigitalCodeClaimedEmail({

package/dist/_internal/server/features/digital-code/download.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Streams the digital ASSET a buyer paid for.
+ *
+ * 🛑 WHY THIS ROUTE EXISTS AT ALL, rather than a `/media/{slug}` URL.
+ *
+ * Two independent facts make the ordinary media pipeline unusable for paid
+ * content, and either one alone would be enough:
+ *
+ *   1. `storage.rules` grants `allow read: if true` on **every object in the
+ *      bucket**. The comment above it explains why that is acceptable — the
+ *      rules are a safety net for a misconfigured client, all real access goes
+ *      through the Admin SDK — but it means Storage itself protects nothing.
+ *   2. `GET /api/media/[...slug]` performs **no authentication whatsoever**. It
+ *      is a bare exported handler with no session read, deliberately, because
+ *      its job is to serve public product photography through a watermarker.
+ *      It also resolves legacy multi-segment slugs as raw storage paths.
+ *
+ * Together: anything reachable at a `/media/` slug is world-readable, and this
+ * codebase's media filenames are content-derived and therefore guessable. A
+ * purchased QR living there would be a paid good at a predictable public URL.
+ *
+ * So the bytes live under a private prefix that mints no `mediaAssets` row (and
+ * therefore no slug), and are streamed only from here — after re-checking that
+ * the caller owns the order. That is the same shape as
+ * `GET /api/user/orders/[id]/invoice`, the one existing precedent in this
+ * codebase for a gated download.
+ */
+/** Order statuses at which delivered content may be downloaded. */
+export declare const CODE_DOWNLOAD_STATUSES: Set<string>;
+export interface CodeAssetResolution {
+    ok: boolean;
+    /** HTTP status to answer with when `ok` is false. */
+    status?: number;
+    message?: string;
+    buffer?: Buffer;
+    contentType?: string;
+    fileName?: string;
+}
+/**
+ * Resolve and read the asset for `orderId`, or explain why not.
+ *
+ * `viewerUid` is the authenticated caller. `isStaff` lets admin/moderator open a
+ * buyer's delivery for support — the same escape hatch the invoice route has.
+ */
+export declare function resolveCodeAssetForOrder(orderId: string, viewerUid: string, isStaff: boolean): Promise<CodeAssetResolution>;
+/**
+ * The response headers for a delivered asset.
+ *
+ * 🛑 `attachment`, ALWAYS — even for an image, where `inline` would be friendlier.
+ * The upload surface accepts files, `finalize`'s magic-byte check proves what a
+ * file IS but not that rendering it is safe, and an HTML document served inline
+ * from this origin is stored XSS against a signed-in buyer. `nosniff` closes the
+ * other half (a browser guessing `text/html` from content it was told was
+ * `application/octet-stream`).
+ *
+ * `private, no-store` because a shared cache must never hold one buyer's
+ * purchase — this URL is identical for every caller and only the session
+ * distinguishes them.
+ */
+export declare function codeAssetHeaders(contentType: string, fileName: string): Record<string, string>;

package/dist/_internal/server/features/digital-code/download.js

@@ -0,0 +1,128 @@
+/**
+ * Streams the digital ASSET a buyer paid for.
+ *
+ * 🛑 WHY THIS ROUTE EXISTS AT ALL, rather than a `/media/{slug}` URL.
+ *
+ * Two independent facts make the ordinary media pipeline unusable for paid
+ * content, and either one alone would be enough:
+ *
+ *   1. `storage.rules` grants `allow read: if true` on **every object in the
+ *      bucket**. The comment above it explains why that is acceptable — the
+ *      rules are a safety net for a misconfigured client, all real access goes
+ *      through the Admin SDK — but it means Storage itself protects nothing.
+ *   2. `GET /api/media/[...slug]` performs **no authentication whatsoever**. It
+ *      is a bare exported handler with no session read, deliberately, because
+ *      its job is to serve public product photography through a watermarker.
+ *      It also resolves legacy multi-segment slugs as raw storage paths.
+ *
+ * Together: anything reachable at a `/media/` slug is world-readable, and this
+ * codebase's media filenames are content-derived and therefore guessable. A
+ * purchased QR living there would be a paid good at a predictable public URL.
+ *
+ * So the bytes live under a private prefix that mints no `mediaAssets` row (and
+ * therefore no slug), and are streamed only from here — after re-checking that
+ * the caller owns the order. That is the same shape as
+ * `GET /api/user/orders/[id]/invoice`, the one existing precedent in this
+ * codebase for a gated download.
+ */
+import { getAdminDb } from "../../../../providers/db-firebase/admin";
+import { getAdminStorage } from "../../../../providers/db-firebase";
+import { normalizeError } from "../../../../errors/normalize";
+import { ORDER_FIELDS } from "../../../../constants/field-names";
+import { PRODUCT_COLLECTION, PRODUCT_CODES_SUBCOLLECTION, } from "../../../../features/products/schemas/firestore";
+/** Order statuses at which delivered content may be downloaded. */
+export const CODE_DOWNLOAD_STATUSES = new Set([
+    "confirmed",
+    "processing",
+    "delivered",
+]);
+/**
+ * Resolve and read the asset for `orderId`, or explain why not.
+ *
+ * `viewerUid` is the authenticated caller. `isStaff` lets admin/moderator open a
+ * buyer's delivery for support — the same escape hatch the invoice route has.
+ */
+export async function resolveCodeAssetForOrder(orderId, viewerUid, isStaff) {
+    const db = getAdminDb();
+    const orderSnap = await db.collection("orders").doc(orderId).get();
+    if (!orderSnap.exists) {
+        return { ok: false, status: 404, message: "Order not found" };
+    }
+    const order = orderSnap.data();
+    /*
+     * 404, not 403, when it is not your order — matching the reveal route and the
+     * order-invoice route. Answering 403 would confirm that an order with that id
+     * exists, which is a membership oracle over a guessable id space.
+     */
+    if (!isStaff && order.userId !== viewerUid) {
+        return { ok: false, status: 404, message: "Order not found" };
+    }
+    if (!CODE_DOWNLOAD_STATUSES.has(String(order.status ?? "").toLowerCase())) {
+        return {
+            ok: false,
+            status: 400,
+            message: "This order is not in a state where content can be downloaded.",
+        };
+    }
+    const productId = order.items?.[0]?.productId ?? order.productId;
+    if (!productId) {
+        return { ok: false, status: 404, message: "No content found for this order" };
+    }
+    const snap = await db
+        .collection(PRODUCT_COLLECTION)
+        .doc(productId)
+        .collection(PRODUCT_CODES_SUBCOLLECTION)
+        .where("orderId", "==", orderId)
+        .where(ORDER_FIELDS.STATUS, "==", "claimed")
+        .limit(1)
+        .get();
+    if (snap.empty) {
+        return { ok: false, status: 404, message: "No content found for this order" };
+    }
+    const entry = snap.docs[0].data();
+    if (!entry.assetPath) {
+        return {
+            ok: false,
+            status: 400,
+            message: "This delivery is a code, not a downloadable file.",
+        };
+    }
+    try {
+        const file = getAdminStorage().bucket().file(entry.assetPath);
+        const [buffer] = await file.download();
+        return {
+            ok: true,
+            buffer,
+            contentType: entry.contentType ?? "application/octet-stream",
+            fileName: entry.fileName ?? "download",
+        };
+    }
+    catch (err) {
+        void normalizeError(err);
+        return { ok: false, status: 404, message: "Content is no longer available" };
+    }
+}
+/**
+ * The response headers for a delivered asset.
+ *
+ * 🛑 `attachment`, ALWAYS — even for an image, where `inline` would be friendlier.
+ * The upload surface accepts files, `finalize`'s magic-byte check proves what a
+ * file IS but not that rendering it is safe, and an HTML document served inline
+ * from this origin is stored XSS against a signed-in buyer. `nosniff` closes the
+ * other half (a browser guessing `text/html` from content it was told was
+ * `application/octet-stream`).
+ *
+ * `private, no-store` because a shared cache must never hold one buyer's
+ * purchase — this URL is identical for every caller and only the session
+ * distinguishes them.
+ */
+export function codeAssetHeaders(contentType, fileName) {
+    // Strip anything that could break out of the quoted filename or inject a header.
+    const safeName = fileName.replace(/[^\w.\-() ]+/g, "_").slice(0, 120) || "download";
+    return {
+        "Content-Type": contentType,
+        "Content-Disposition": `attachment; filename="${safeName}"`,
+        "X-Content-Type-Options": "nosniff",
+        "Cache-Control": "private, no-store, max-age=0",
+    };
+}

package/dist/_internal/server/features/digital-code/pool.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The digital-content pool for a `digital-code` listing.
+ *
+ * 🛑 THIS IS THE MISSING HALF OF THE FEATURE. Everything downstream already
+ * existed — `claimDigitalCodeForOrder` claims one at checkout, the buyer reveals
+ * it through `GET /api/orders/{id}/code`, a refund revokes unclaimed ones — but
+ * **nothing in the codebase had ever WRITTEN a row into the pool.** The one
+ * seller-facing route returned `501 "Digital code management is not implemented
+ * yet."` So every purchase of a digital-code listing hit
+ * `serverLogger.warn("claimDigitalCode: code pool exhausted")` and returned
+ * silently, the order completed normally, and the buyer's reveal panel answered
+ * 404. The seller form even has a "Code Pool Size" field, which made the pool
+ * look populated on the listing page while it was always empty.
+ *
+ * A "digital code" delivers digital CONTENT: a redemption string, a QR image, or
+ * a file. `contentKind` says which, defaulting to `"code"` so every pre-existing
+ * document keeps its meaning with no migration.
+ */
+import { type ProductCodeContentKind } from "../../../../features/products/schemas/firestore";
+/**
+ * Where a delivered asset's bytes live.
+ *
+ * Deliberately OUTSIDE every prefix the public media proxy knows how to resolve,
+ * and no `mediaAssets` row is ever created for it — a `mediaAssets` row is what
+ * mints a `/media/{shortId}` slug, and that slug is served without
+ * authentication. No row, no slug, no public URL.
+ */
+export declare const DIGITAL_CONTENT_PREFIX = "private/digital-content";
+/**
+ * 🛑 THE PERMISSION SPLIT, and the reason it is not simply "admins only".
+ *
+ * An image is the QR/voucher case and is the whole point of widening this from
+ * strings, so a seller must be able to add one — they are the person who has it.
+ * Any OTHER file type is admin-only to upload: the upload surface accepts bytes
+ * that will later be streamed to a buyer, and a `.html` renamed `.pdf` is stored
+ * XSS the moment anything renders it inline. Narrowing who can put a non-image
+ * file into that path is the cheap half of the defence; the magic-byte check and
+ * the forced `Content-Disposition: attachment` are the other half.
+ *
+ * READ is a third thing again and is not on this axis at all: whoever may
+ * upload, only the buyer who paid for that order (or staff) may download. See
+ * `assertCanDownloadCodeAsset`.
+ */
+export declare function assertCanUploadContentKind(kind: ProductCodeContentKind, role: string | undefined): void;
+export interface AddPoolEntryInput {
+    productId: string;
+    contentKind: ProductCodeContentKind;
+    /** Required when `contentKind === "code"`. */
+    code?: string;
+    /** Required for the asset kinds — a raw Storage path under DIGITAL_CONTENT_PREFIX. */
+    assetPath?: string;
+    fileName?: string;
+    contentType?: string;
+    expiresAt?: Date;
+}
+/**
+ * Append entries to a product's pool and re-sync the two counters.
+ *
+ * `codePoolSize` and `codesAvailable` are recomputed from the subcollection, not
+ * incremented from the input — the seller form lets a human type `codePoolSize`
+ * by hand, so treating that number as authoritative would let the listing page
+ * advertise stock that does not exist. Counting is the only thing that cannot
+ * drift (Root Cause #42: a mirror is only as good as every writer of it).
+ */
+export declare function addPoolEntries(entries: AddPoolEntryInput[]): Promise<{
+    added: number;
+    available: number;
+    total: number;
+}>;
+/**
+ * Recount the pool and write both counters onto the product.
+ *
+ * 🛑 `codesAvailable` HAD NO WRITER EITHER. `claimDigitalCodeForOrder` flips a
+ * code to `claimed` and never decrements it, so the counter only ever held
+ * whatever the seed or the seller typed. Since `hasCodesAvailable()` is what the
+ * availability predicate reads, a sold-out listing stayed "available" forever and
+ * a listing that never had codes still advertised stock. Both counters are
+ * derived here, so neither can drift from the subcollection.
+ */
+export declare function recountPool(productId: string): Promise<{
+    available: number;
+    total: number;
+}>;
+/** The seller/admin view of a pool. Never returns `code` or `assetPath`. */
+export declare function listPoolEntries(productId: string): Promise<Array<{
+    id: string;
+    contentKind: ProductCodeContentKind;
+    status: string;
+    fileName?: string;
+    orderId?: string;
+    claimedAt?: string;
+    createdAt?: string;
+}>>;
+/**
+ * Remove an UNCLAIMED entry. A claimed one is somebody's purchase and deleting
+ * it would make their reveal 404 with no trace of what they bought.
+ */
+export declare function deletePoolEntry(productId: string, codeId: string): Promise<{
+    available: number;
+    total: number;
+}>;