@mohasinac/appkit 4.52.5 → 4.53.1

package/dist/_internal/server/features/sticker-trace/promote-to-listings.js

@@ -0,0 +1,264 @@
+/*
+ * WHY: The tracer ends at extracted geometry and a promoted run's full-size
+ *      part PNGs. This is what makes that worth doing — the whole sheet becomes
+ *      one listing, each unique cut becomes its own, and they are grouped so a
+ *      buyer takes any mix ("the sheet, no; six of B; one of D").
+ * WHAT: `promoteStickerSheetToListings` — sheet → one parent product + N child
+ *       products in one product group.
+ *
+ * 🛑 DISTINCT FROM `promoteRun`, and the names are close enough to matter.
+ *   · `POST .../runs/{runId}/promote`  → `promoteRun`: run → SHEET. Renders
+ *     full-res parts and exports, sets `activeRunId`. Stays inside the tracer.
+ *   · `POST .../promote-to-listings`   → this: SHEET → MARKETPLACE. Creates
+ *     products. Runs once per sheet, after the above.
+ * Calling this without the first is refused, because `SheetPart.assetPath` is
+ * only written by the `mode: "full"` shard path.
+ *
+ * 🛑 ZERO BYTES ARE COPIED for the watermarked display image. A `mediaAssets`
+ * row pointing at the EXISTING private part PNG is enough: the row is what
+ * mints `/media/{shortId}`, and the proxy watermarks on read because the row is
+ * written with `watermarkedAt` absent. Clean original for the cut file,
+ * watermarked copy for the marketplace, one object. Object count is metered
+ * separately from bytes, which is the whole reason the thumb atlas exists.
+ *
+ * EXPORTS: PromoteToListingsInput, PromoteToListingsResult,
+ *          promoteStickerSheetToListings
+ *
+ * @tag domain:sticker-trace,products
+ * @tag layer:server
+ * @tag pattern:none
+ * @tag access:server
+ * @tag consumers:api/admin/sticker-sheets
+ * @tag sideEffects:firestore
+ */
+import { ValidationError } from "../../../../errors/validation-error.js";
+import { serverLogger } from "../../../../monitoring/server-logger.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+import { productRepository } from "../../../../repositories/index.js";
+import { mediaAssetsRepository } from "../../../../features/media/repository/media-assets.repository.js";
+import { stickerSheetsRepository } from "../../../../features/sticker-trace/repository/sticker-sheets.repository.js";
+/** A part that becomes its own listing: unique, and actually rendered. */
+function isListableUniquePart(part) {
+    /*
+     * `duplicateOf` is proposed by perceptual hash and CONFIRMED BY A HUMAN, so
+     * trusting it is safe by design — that confirmation step exists precisely so
+     * this decision can be mechanical. Two stickers that merely look alike at
+     * thumbnail size are common on these sheets.
+     */
+    return part.duplicateOf === undefined;
+}
+/**
+ * Refuse loudly, before writing anything, if the sheet is not ready.
+ *
+ * 🛑 A half-promoted sheet is the "wrong data, no error" failure this whole
+ * plan exists to avoid: some parts listed, some silently missing, and nothing
+ * anywhere saying so. Every precondition is therefore checked UP FRONT and the
+ * whole promotion refused — not checked per part inside the loop, which would
+ * leave the first N written.
+ */
+function assertPromotable(sheet) {
+    if (!sheet.activeRunId) {
+        throw new ValidationError(`"${sheet.title}" has no accepted run yet. Accept a run first, then promote it to listings.`);
+    }
+    const parts = sheet.parts ?? [];
+    if (parts.length === 0) {
+        throw new ValidationError(`"${sheet.title}" has no parts. Trace it and accept a run first.`);
+    }
+    const unique = parts.filter(isListableUniquePart);
+    if (unique.length === 0) {
+        throw new ValidationError(`Every part on "${sheet.title}" is marked a duplicate of another, so there is nothing to list.`);
+    }
+    /*
+     * `assetPath` absent means the accepted run was never PROMOTED — the
+     * full-resolution PNGs do not exist. Naming the parts rather than saying
+     * "not ready": the admin's next action is different depending on whether it
+     * is all of them (promote the run) or a few (the shard that rendered those
+     * failed, so retry).
+     */
+    const unrendered = unique.filter((p) => !p.assetPath);
+    if (unrendered.length > 0) {
+        throw new ValidationError(`${unrendered.length} of ${unique.length} parts on "${sheet.title}" have no full-resolution image yet` +
+            ` (${unrendered.slice(0, 5).map((p) => `#${p.ordinal}`).join(", ")}${unrendered.length > 5 ? ", …" : ""}).` +
+            ` Accept & render the run before promoting it to listings.`);
+    }
+    return unique;
+}
+/**
+ * Register the public, WATERMARKED display copy of one part.
+ *
+ * Reuses an existing row when the part already has one, so re-promoting a sheet
+ * does not mint a second slug for the same object and orphan the first.
+ */
+async function ensurePartMediaSlug(sheet, part, actorUid) {
+    if (part.mediaShortId)
+        return part.mediaShortId;
+    if (!part.assetPath)
+        return undefined;
+    try {
+        const asset = await mediaAssetsRepository.createAsset(
+        /*
+         * A content-derived slug, matching every other media slug in the app.
+         * `createAsset` appends a random suffix on collision, so two sheets with
+         * the same title cannot overwrite each other's parts.
+         */
+        `sticker-part-${sheet.id}-${String(part.ordinal).padStart(3, "0")}`, {
+            /*
+             * 🛑 The SAME path as the clean original. This is the no-byte-copy
+             * mechanism, and it is only safe because of the two fields below.
+             */
+            storagePath: part.assetPath,
+            uploadedBy: actorUid,
+            contentType: "image/png",
+            /*
+             * Not measured. The row's `size` is used by the media usage meter, not
+             * for serving, and reading the object's metadata here would cost a
+             * Storage round trip per part — 60 on a full sheet — for a number the
+             * sticker feature already reports from `measureSheetBytes`.
+             */
+            size: 0,
+            isPublic: true,
+            status: "finalized",
+            contextType: "sticker-part",
+            /*
+             * 🛑 `watermarkedAt` is DELIBERATELY ABSENT, and it is the whole design.
+             * The proxy skips its sharp composite only when that field is set — so
+             * leaving it unset means `/media/{shortId}` watermarks this object on
+             * every read, while `assetPath` behind a signed URL stays clean. Set it
+             * here and the marketplace would serve the unwatermarked printable
+             * original, which is the one outcome this must never produce.
+             */
+        });
+        return asset.id;
+    }
+    catch (err) {
+        const e = normalizeError(err);
+        /*
+         * Non-fatal. A part with no public slug still lists — it falls back to no
+         * image rather than blocking the whole promotion — and the admin can
+         * re-promote to fill it in. Failing the sheet over one media row would be
+         * the worse trade.
+         */
+        serverLogger.warn("sticker-promote: media row failed for part", {
+            sheetId: sheet.id,
+            ordinal: part.ordinal,
+            error: e.message,
+        });
+        return undefined;
+    }
+}
+export async function promoteStickerSheetToListings(input) {
+    const sheet = await stickerSheetsRepository.findByIdOrFail(input.sheetId);
+    const unique = assertPromotable(sheet);
+    const allParts = sheet.parts ?? [];
+    /*
+     * Media rows first, before any product write.
+     *
+     * The images are what a listing is FOR, so resolving them up front means a
+     * product is never created pointing at nothing. Sequential rather than
+     * `Promise.all`: `createAsset` does a read-then-write collision check, and 60
+     * of those in parallel is 120 concurrent operations against Rule #6's budget
+     * for an admin action that is not latency-sensitive.
+     */
+    const slugByOrdinal = new Map();
+    for (const part of unique) {
+        const slug = await ensurePartMediaSlug(sheet, part, input.actorUid);
+        if (slug)
+            slugByOrdinal.set(part.ordinal, slug);
+    }
+    const partImage = (part) => {
+        const slug = slugByOrdinal.get(part.ordinal);
+        return slug ? `/media/${slug}` : "";
+    };
+    /*
+     * The parent: the whole sheet.
+     *
+     * 🛑 `madeToOrder: true`. A sheet that has been cut into parts has no stock
+     * of its own — it is printed when ordered — so without the flag the parent is
+     * unbuyable at quantity 0 and vanishes from the default availability scope,
+     * taking the group's entry point with it.
+     */
+    const parent = (await productRepository.create({
+        title: sheet.title,
+        description: `The complete ${sheet.title} sheet. Individual stickers from this sheet are listed separately — ` +
+            `pick any mix from the group below.`,
+        categorySlugs: [],
+        price: input.sheetPrice,
+        currency: "INR",
+        stockQuantity: 0,
+        madeToOrder: true,
+        mainImage: unique[0] ? partImage(unique[0]) : "",
+        images: unique.slice(0, 4).map(partImage).filter(Boolean),
+        status: "draft",
+        storeId: input.storeId,
+        featured: false,
+        tags: ["stickers"],
+        condition: "new",
+        listingType: "stickers",
+        groupTitle: sheet.title,
+        sourceStickerSheetId: sheet.id,
+    }));
+    /*
+     * `startGroup` sets `groupId = slug`, so the group id IS the parent's slug —
+     * which is why the parent must exist before any child can name it.
+     */
+    const parentSlug = parent.slug ?? parent.id;
+    await productRepository.startGroup(parent.id, parentSlug);
+    const children = [];
+    for (const part of unique) {
+        const child = (await productRepository.create({
+            title: `${sheet.title} — ${part.name}`,
+            description: `A single kiss-cut sticker from the ${sheet.title} sheet.`,
+            categorySlugs: [],
+            price: input.partPrice,
+            currency: "INR",
+            stockQuantity: 0,
+            // Same reasoning as the parent: a cut sticker is printed on order.
+            madeToOrder: true,
+            mainImage: partImage(part),
+            images: [partImage(part)].filter(Boolean),
+            status: "draft",
+            storeId: input.storeId,
+            featured: false,
+            tags: ["stickers"],
+            condition: "new",
+            listingType: "stickers",
+            sourceStickerSheetId: sheet.id,
+            sourceStickerPartOrdinal: part.ordinal,
+        }));
+        children.push(child);
+    }
+    /*
+     * 🛑 ONE batch link, via `linkChildrenToGroup`. Calling `linkChildToGroup` in
+     * a loop was the bug this phase had to fix first: it spread the CALLER's
+     * in-memory `parent.groupChildSlugs`, so N children produced exactly one
+     * entry — every iteration computing `[...stale, child]` from the same
+     * pre-loop snapshot, last write winning. Each child still got its own
+     * `groupId`, so nothing errored and `findAllByGroupId` found them all while
+     * the parent claimed one member.
+     */
+    await productRepository.linkChildrenToGroup({ ...parent, groupId: parentSlug }, children);
+    /*
+     * Write the slugs back onto the sheet so a re-promote reuses them.
+     *
+     * 🛑 Mapped over ALL parts, keyed on `ordinal`, never on array index — and
+     * `assertPromotable` filtered to unique parts, so a plain `.map()` over
+     * `unique` here would DROP every duplicate part from the sheet. The duplicate
+     * rows carry `duplicateOf` and real geometry and must survive.
+     */
+    const updatedParts = allParts.map((p) => {
+        const slug = slugByOrdinal.get(p.ordinal);
+        return slug ? { ...p, mediaShortId: slug } : p;
+    });
+    await stickerSheetsRepository.update(sheet.id, { parts: updatedParts });
+    serverLogger.info("sticker-promote: sheet promoted to listings", {
+        sheetId: sheet.id,
+        parentId: parent.id,
+        children: children.length,
+        skippedDuplicates: allParts.length - unique.length,
+    });
+    return {
+        parentId: parent.id,
+        childIds: children.map((c) => c.id),
+        skippedDuplicates: allParts.length - unique.length,
+    };
+}

package/dist/_internal/server/features/sticker-trace/promote.d.ts

@@ -0,0 +1,23 @@
+export interface PromoteRunInput {
+    sheetId: string;
+    runId: string;
+    promotedBy: string;
+}
+export interface PromoteRunResult {
+    sheetId: string;
+    runId: string;
+    /** How many shards will render full-resolution parts. */
+    shardCount: number;
+    partCount: number;
+}
+/**
+ * Accept a run and start the full-resolution render.
+ *
+ * 🛑 It refuses a run that did not SUCCEED. Promoting a failed or still-running
+ * run would copy a partial `parts[]` onto the sheet and set `activeRunId` to
+ * it — the sheet would then confidently show an incomplete result, with the
+ * run's own status the only contradiction and nothing surfacing it.
+ */
+export declare function promoteStickerTraceRun(input: PromoteRunInput): Promise<PromoteRunResult>;
+/** Whether this run is already the sheet's accepted result. */
+export declare function isRunPromoted(sheetId: string, runId: string): Promise<boolean>;

package/dist/_internal/server/features/sticker-trace/promote.js

@@ -0,0 +1,193 @@
+/*
+ * WHY: An exploratory run produces vector geometry and ~20 KB review
+ *      thumbnails — about 1 MB. Full-resolution parts and the print exports
+ *      cost roughly 500 MB a sheet, which is the difference between ~52 sheets
+ *      in 5 GB and about 8. So they are rendered ONCE, for the run the operator
+ *      actually chose, and this is that moment.
+ * WHAT: Accept a run as the sheet's current result, and fan out a full-
+ *       resolution render of its parts.
+ *
+ * 🛑 `promoteRun` and `markPromoted` have existed since P4 with ZERO callers.
+ * This is their first one. Anything that looked like it already worked —
+ * `isPromoted` in the run list, `promotedPartCount` in the adapter — was
+ * reading fields nothing has ever written.
+ *
+ * 🛑 TWO DIFFERENT THINGS ARE CALLED "PROMOTE" IN THIS FEATURE AND THEY MUST
+ * NOT BE CONFLATED:
+ *   - THIS one promotes a RUN onto its SHEET: the sheet now shows that run's
+ *     parts, and full-res renders are produced.
+ *   - Part Two's `promoteStickerSheetToListings` promotes a SHEET into
+ *     marketplace PRODUCTS.
+ * The second depends on the first, because `SheetPart.assetPath` does not
+ * exist until a run has been promoted here.
+ *
+ * EXPORTS: PromoteRunInput, PromoteRunResult, promoteStickerTraceRun
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:server
+ * @tag pattern:none
+ * @tag access:server
+ * @tag consumers:api/admin/sticker-sheets
+ * @tag sideEffects:firestore,rtdb
+ */
+import { ValidationError } from "../../../../errors/validation-error.js";
+import { stickerSheetsRepository } from "../../../../features/sticker-trace/repository/sticker-sheets.repository.js";
+import { stickerTraceRunsRepository } from "../../../../features/sticker-trace/repository/sticker-trace-runs.repository.js";
+import { TraceRunStatusValues } from "../../../../features/sticker-trace/schemas/firestore.js";
+import { serverLogger } from "../../../../monitoring/index.js";
+import { createShardTasks, planShards } from "./fanout.js";
+import { emitProgress } from "./progress.js";
+import { readRunGeometry } from "./storage.js";
+/**
+ * Promote fans out no wider than the trace did.
+ *
+ * A full-resolution part is a decode, a rasterise and a PNG encode at native
+ * size, so the shard budget is the same 1 GiB / 300 s. More shards than
+ * `maxInstances` (8) queue rather than run, and each one is a Firestore write
+ * plus an invocation.
+ */
+const MAX_PROMOTE_SHARDS = 8;
+/**
+ * Accept a run and start the full-resolution render.
+ *
+ * 🛑 It refuses a run that did not SUCCEED. Promoting a failed or still-running
+ * run would copy a partial `parts[]` onto the sheet and set `activeRunId` to
+ * it — the sheet would then confidently show an incomplete result, with the
+ * run's own status the only contradiction and nothing surfacing it.
+ */
+export async function promoteStickerTraceRun(input) {
+    const [sheet, run] = await Promise.all([
+        stickerSheetsRepository.findByIdOrFail(input.sheetId),
+        stickerTraceRunsRepository.findByIdOrFail(input.runId),
+    ]);
+    /*
+     * The run must belong to THIS sheet. Both ids are caller-supplied, so this is
+     * the only place the pairing can be checked — without it, promoting run X of
+     * sheet A onto sheet B would copy A's parts onto B and point B's
+     * `activeRunId` at a run that is not its own.
+     */
+    if (run.sheetId !== input.sheetId) {
+        throw new ValidationError("That run belongs to a different sheet.", {
+            runId: "Run and sheet do not match.",
+        });
+    }
+    if (run.status !== TraceRunStatusValues.SUCCEEDED) {
+        throw new ValidationError(`Only a successful run can be promoted — this one is ${run.status}.`, { runId: "Re-run it, or promote a different attempt." });
+    }
+    /*
+     * 🛑 The parts come from `geometry.json`, NOT from the run document — the run
+     * carries only `partCount`. That is deliberate: sixty Bézier outlines would
+     * approach Firestore's 1 MiB document limit, which is why the geometry is an
+     * artifact in the first place.
+     */
+    const geometry = await readRunGeometry(input.runId, input.sheetId);
+    /*
+     * Millimetres only when the scan's dpi can be trusted.
+     *
+     * The geometry is in WORKING raster pixels while `dpi` describes the
+     * ORIGINAL, so the two are bridged by the downscale factor. Skipping that
+     * bridge is the subtle version of the same error the commit panel nearly
+     * shipped: every figure would be wrong by exactly the downscale ratio, and
+     * every one of them would look plausible.
+     */
+    const workingToOriginal = sheet.widthPx > 0 && geometry.workingSize.width > 0
+        ? sheet.widthPx / geometry.workingSize.width
+        : null;
+    const pxPerMm = sheet.dpi && sheet.dpi > 0 && workingToOriginal !== null
+        ? (sheet.dpi / 25.4) / workingToOriginal
+        : null;
+    /*
+     * 🛑 `groupIndex` is 0 for every part, because geometry.json does not carry a
+     * per-part cluster assignment. On a single-sheet scan that is simply correct.
+     * On a multi-sheet scan it is NOT, and it is warned about rather than quietly
+     * written — a wrong group index renders every part under one tab, which looks
+     * like a tidy result instead of a lost distinction.
+     */
+    if ((run.groupCount ?? 1) > 1) {
+        serverLogger.warn("Promoting a multi-sheet run; parts carry groupIndex 0", {
+            runId: input.runId,
+            sheetId: input.sheetId,
+            groupCount: run.groupCount,
+        });
+    }
+    const parts = geometry.parts.map((g) => {
+        const bboxMm = pxPerMm
+            ? {
+                x: g.bbox.x / pxPerMm,
+                y: g.bbox.y / pxPerMm,
+                width: g.bbox.width / pxPerMm,
+                height: g.bbox.height / pxPerMm,
+            }
+            : null;
+        return {
+            ordinal: g.ordinal,
+            // The schema's own default: the ordinal, renameable by an admin later.
+            name: String(g.ordinal),
+            groupIndex: 0,
+            bboxPx: g.bbox,
+            bboxMm,
+            // Derived from the same measurement, so it is withheld on the same terms.
+            areaMm2: bboxMm ? Math.round(bboxMm.width * bboxMm.height * 100) / 100 : null,
+        };
+    });
+    if (parts.length === 0) {
+        throw new ValidationError("That run produced no parts, so there is nothing to promote.", { runId: "Tune the parameters and try another attempt." });
+    }
+    /*
+     * Sheet first, fan-out second.
+     *
+     * The sheet's `parts[]` and geometry are what every review surface reads, and
+     * they are complete the moment the run succeeded — the fan-out only adds
+     * full-resolution PNGs. Promoting the document first means an operator sees
+     * the accepted result immediately, and a fan-out that fails leaves a sheet
+     * that is correct but missing downloads, rather than a run marked accepted on
+     * a sheet still showing the previous one.
+     */
+    await stickerSheetsRepository.promoteRun(input.sheetId, input.runId, {
+        parts,
+        groupCount: run.groupCount ?? 1,
+        artifacts: run.artifacts ?? {},
+    });
+    const ordinals = parts.map((p) => p.ordinal);
+    const shards = planShards(ordinals, MAX_PROMOTE_SHARDS);
+    /*
+     * 🛑 `mode: "full"` is what makes these DIFFERENT task documents from the
+     * trace's. `shardTaskId` keys on the mode precisely so this does not `set()`
+     * over `{runId}__part__{i}` — which would be an update, would not fire
+     * `documentCreated`, and would leave the promote silently doing nothing.
+     */
+    const shardCount = await createShardTasks({
+        runId: input.runId,
+        sheetId: input.sheetId,
+        mode: "full",
+        shards,
+    });
+    /*
+     * Best-effort, like every other progress write. The channel is the live bar;
+     * the durable record is the run document, which `markPromoted` writes when
+     * the finalizer completes. A failed ping must never fail a promotion that
+     * has already written Firestore.
+     */
+    await emitProgress({
+        runId: input.runId,
+        stage: "parts",
+        pct: 0,
+        partsDone: 0,
+        partsTotal: parts.length,
+        shardsDone: 0,
+        shardsTotal: shardCount,
+        message: `Rendering ${parts.length} part(s) at full resolution`,
+        level: "info",
+    });
+    return {
+        sheetId: input.sheetId,
+        runId: input.runId,
+        shardCount,
+        partCount: parts.length,
+    };
+}
+/** Whether this run is already the sheet's accepted result. */
+export async function isRunPromoted(sheetId, runId) {
+    const sheet = await stickerSheetsRepository.findById(sheetId);
+    return sheet?.activeRunId === runId;
+}

package/dist/_internal/server/features/sticker-trace/shard.d.ts

@@ -0,0 +1,50 @@
+import type { StickerTraceTaskDocument } from "../../../../features/sticker-trace/schemas/firestore";
+import type { ImageCodec } from "../../../shared/features/sticker-trace/codec";
+import type { CutPath, Rect } from "../../../shared/features/sticker-trace/types";
+export interface ShardDeps {
+    codec: ImageCodec;
+    readScan: (assetPath: string) => Promise<Uint8Array>;
+    readGeometry: (runId: string, sheetId: string) => Promise<{
+        workingSize: Rect;
+        parts: {
+            ordinal: number;
+            bbox: Rect;
+            path: CutPath;
+        }[];
+    }>;
+    /**
+     * Rasterise one part's path into an alpha mask covering `bbox`.
+     *
+     * 🛑 Takes the PATH, not an ordinal. An ordinal carries no geometry, so a
+     * signature keyed on it could only be implemented by re-reading
+     * geometry.json for every part — sixty extra downloads per shard for data the
+     * caller already holds. And no `scale`: `bbox` is already in
+     * full-resolution pixels by the time this is called.
+     */
+    rasterise: (path: CutPath, bbox: Rect) => Promise<Uint8Array>;
+    writeArtifact: (input: {
+        sheetId: string;
+        runId: string;
+        name: string;
+        contentType: string;
+        body: Uint8Array;
+    }) => Promise<{
+        assetPath: string;
+    }>;
+}
+/**
+ * Render this shard's parts, then report done.
+ *
+ * 🛑 `mode` decides resolution, and that is the single decision keeping this
+ * feature inside the Storage allowance. `thumb` renders review thumbnails into
+ * ONE sprite atlas; `full` renders full-resolution parts and only runs when a
+ * human promotes a run. Rendering full-res on every run costs ~600 MB per
+ * sheet across a tuning session against ~95 MB — roughly 8 sheets inside 5 GB
+ * instead of 52.
+ *
+ * 🛑 The shard reports done even when a part THROWS. Leaving the counter short
+ * means the finalizer is never elected and the run sits RUNNING forever — a
+ * stuck run is worse than a run that completes reporting a bad part, because
+ * nothing sweeps it and the RTDB channel prunes within the hour.
+ */
+export declare function runShard(task: StickerTraceTaskDocument, deps: ShardDeps): Promise<void>;