@mohasinac/appkit 4.62.0 → 4.63.0

package/dist/_internal/server/features/dashboard/data.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The one read a dashboard hub or landing page needs.
+ *
+ * ## 🛑 Read on the SERVER, not fetched from the client
+ *
+ * The plan named an endpoint — `/api/dashboard/attention` — and the shape it
+ * asked for is "one read covering every section", which this is. It is read
+ * here instead because every one of these pages is **already per-request**:
+ * `admin/layout.tsx` and `store/layout.tsx` `await getServerSessionUser()`, so
+ * the whole subtree is dynamic with or without an endpoint (§ "…a dynamic API
+ * in a DASHBOARD layout is the correct lever").
+ *
+ * An endpoint would therefore have added a SECOND billed invocation per hub
+ * visit to fetch data the page's own render could already have, which is
+ * exactly the shape of Root Cause #94 — a client fetch that reads as free in
+ * review and bills per mount. There is no endpoint, and one should not be added
+ * unless something outside a dashboard page needs these numbers.
+ *
+ * ## Two reads, and both fail OPEN
+ *
+ * `navConfig` decides which nav entries an admin has switched off, and the hub
+ * must agree with the sidebar about that — so it is read rather than ignored.
+ * On failure it resolves to `undefined`, which means "nothing is disabled" and
+ * shows MORE cards than it should. That is the right direction: a disabled nav
+ * entry is a configuration choice rather than a permission, and the page behind
+ * every card still enforces its own route guard. Hiding sections because a
+ * settings read blipped would be the damaging failure.
+ *
+ * The counts fail to `null` per card — see `attention.ts`, which exists to
+ * explain why `0` is the one answer a badge must never invent.
+ */
+import { type DashboardHubSection } from "../../../shared/features/dashboard/hub-sections";
+import type { SidebarNavGroup } from "../../../shared/features/layout/types";
+import { type AttentionCounts } from "./attention";
+export interface DashboardHubData {
+    /** Permission- and toggle-filtered, in nav order. Never empty-group padded. */
+    sections: DashboardHubSection[];
+    counts: AttentionCounts;
+}
+/**
+ * Resolve the sections a viewer may see, plus their attention counts.
+ *
+ * @param groups the portal's nav groups, unfiltered — this applies the filter
+ * @param permissions `null` means admin (the convention `filterNavGroups` owns)
+ * @param storeId the viewer's store SLUG, for seller-scoped counts
+ */
+export declare function getDashboardHubData(groups: readonly SidebarNavGroup[], permissions: string[] | null | undefined, storeId?: string): Promise<DashboardHubData>;

package/dist/_internal/server/features/dashboard/data.js

@@ -0,0 +1,82 @@
+/**
+ * The one read a dashboard hub or landing page needs.
+ *
+ * ## 🛑 Read on the SERVER, not fetched from the client
+ *
+ * The plan named an endpoint — `/api/dashboard/attention` — and the shape it
+ * asked for is "one read covering every section", which this is. It is read
+ * here instead because every one of these pages is **already per-request**:
+ * `admin/layout.tsx` and `store/layout.tsx` `await getServerSessionUser()`, so
+ * the whole subtree is dynamic with or without an endpoint (§ "…a dynamic API
+ * in a DASHBOARD layout is the correct lever").
+ *
+ * An endpoint would therefore have added a SECOND billed invocation per hub
+ * visit to fetch data the page's own render could already have, which is
+ * exactly the shape of Root Cause #94 — a client fetch that reads as free in
+ * review and bills per mount. There is no endpoint, and one should not be added
+ * unless something outside a dashboard page needs these numbers.
+ *
+ * ## Two reads, and both fail OPEN
+ *
+ * `navConfig` decides which nav entries an admin has switched off, and the hub
+ * must agree with the sidebar about that — so it is read rather than ignored.
+ * On failure it resolves to `undefined`, which means "nothing is disabled" and
+ * shows MORE cards than it should. That is the right direction: a disabled nav
+ * entry is a configuration choice rather than a permission, and the page behind
+ * every card still enforces its own route guard. Hiding sections because a
+ * settings read blipped would be the damaging failure.
+ *
+ * The counts fail to `null` per card — see `attention.ts`, which exists to
+ * explain why `0` is the one answer a badge must never invent.
+ */
+import { cache } from "react";
+import { safeRead } from "../../../../errors/safe-read.js";
+import { siteSettingsRepository } from "../../../../features/admin/repository/site-settings.repository.js";
+import { filterNavGroups } from "../../../client/features/layout/filterNavItems.js";
+import { hubSections, } from "../../../shared/features/dashboard/hub-sections.js";
+import { collectAttentionCounts } from "./attention.js";
+/**
+ * `navConfig` alone, cached per request.
+ *
+ * `React.cache` because a landing page renders the hub once but a hub page may
+ * also want the section list for its own heading, and the narrowest shared call
+ * is the one to cache (§ "`React.cache` discipline" — cache the repository
+ * read, not the viewer-specific wrapper around it, or two call sites with
+ * different arguments dedupe nothing).
+ */
+const getNavConfig = cache(async () => safeRead(async () => {
+    const settings = (await siteSettingsRepository.getSingleton());
+    return settings?.navConfig;
+}, {
+    route: "dashboard-hub",
+    key: "navConfig",
+    fallback: undefined,
+}));
+/**
+ * Resolve the sections a viewer may see, plus their attention counts.
+ *
+ * @param groups the portal's nav groups, unfiltered — this applies the filter
+ * @param permissions `null` means admin (the convention `filterNavGroups` owns)
+ * @param storeId the viewer's store SLUG, for seller-scoped counts
+ */
+export async function getDashboardHubData(groups, permissions, storeId) {
+    const navConfig = await getNavConfig();
+    /*
+     * Filter FIRST, then count — the visible ids are the scope (see
+     * `collectAttentionCounts`). Doing it the other way round costs an employee
+     * five queries to render one card, and computes figures from collections
+     * their permission set does not cover.
+     *
+     * Sequential rather than parallel with the settings read for the same
+     * reason: the second call's input is the first call's output. Two
+     * round trips, inside Rule #6's ~3.
+     */
+    const sections = hubSections(filterNavGroups([...groups], navConfig, permissions));
+    const visibleItemIds = sections.flatMap((s) => s.items.map((i) => i.id).filter(Boolean));
+    const counts = await safeRead(() => collectAttentionCounts(visibleItemIds, storeId), {
+        route: "dashboard-hub",
+        key: "attention",
+        fallback: {},
+    });
+    return { sections, counts };
+}

package/dist/_internal/server/features/inventory/reservations.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Hold stock for something that is not an order yet.
+ *
+ * ## What this is for
+ *
+ * The plan's Part 6 (shared purchase) names this "the largest hidden cost",
+ * and it is the only one of its three prerequisites that had NOTHING behind
+ * it. See the schema file for why the existing order-keyed mechanism cannot
+ * serve a multi-day arrangement.
+ *
+ * ## 🛑 Every function here moves the row and the counter TOGETHER
+ *
+ * `availableQuantity` is what a buyer can take; the gap between it and
+ * `stockQuantity` is the outstanding hold (`resolveStockResync`'s own words).
+ * A reservation row written without the decrement holds nothing at all, and a
+ * decrement written without a row is a hold nothing can expire — so both
+ * happen inside ONE `runTransaction`, with the product read inside it so two
+ * concurrent reserves cannot both see the same `availableQuantity`.
+ *
+ * ## 🛑 Firestore wants every READ before every WRITE
+ *
+ * So `endReservation` reads the reservation AND the product up front, even
+ * on the consume path where the product read is thrown away. The natural
+ * shape — read the reservation, decide, then read the product — throws
+ * `Firestore transactions require all reads to be executed before all
+ * writes`, and only at runtime, which is exactly the class of fault
+ * `restoreStockForOrder`'s header already warns about one directory over.
+ *
+ * ## Why it writes `availableQuantity` EXPLICITLY
+ *
+ * `ProductRepository.update`'s `resolveStockResync` returns `{}` the moment a
+ * write names `availableQuantity` — deliberately, so the checkout decrement,
+ * the stock-restore job and `updateAvailableQuantity` stay authoritative over
+ * their own number. This is a fourth member of that set and takes the same
+ * deal: it is the one deciding the value, so the resync must keep its hands
+ * off it. (These writes go through the raw collection rather than the
+ * repository for the same reason `deriveTaxonomy` reads categories through
+ * `this.db` — a transaction needs the ref, not a repository method.)
+ */
+import { type ReservationHolderKind, type StockReservationDocument } from "../../../../features/inventory/schemas/stock-reservation";
+export interface ReserveStockInput {
+    productId: string;
+    quantity: number;
+    holderKind: ReservationHolderKind;
+    holderId: string;
+    createdBy: string;
+    /** Defaults to `RESERVATION_DEFAULT_TTL_HOURS`; capped at the 30-day ceiling. */
+    ttlHours?: number;
+}
+/**
+ * Take a hold. Returns the reservation id.
+ *
+ * 🛑 Refuses rather than over-reserving. A seller's stock is a real number of
+ * real objects, so "reserve 5, only 3 left" is a **409** — the request is
+ * well-formed and the world moved, which is the same distinction the lottery
+ * config write makes for a slot somebody has already pulled.
+ */
+export declare function reserveStock(input: ReserveStockInput): Promise<string>;
+/**
+ * End a hold and PUT THE UNITS BACK — the holder changed their mind, an admin
+ * took it back, or the sweep found it expired.
+ */
+export declare function releaseReservation(reservationId: string, opts?: {
+    status?: "released" | "expired";
+    reason?: string;
+}): Promise<void>;
+/**
+ * End a hold and KEEP the units off the shelf — the arrangement completed and
+ * an order now owns them.
+ *
+ * 🛑 This is the one path that must NOT restore. The order's own decrement is
+ * what holds the units from here, so restoring first would hand the same
+ * stock to the next buyer for the moment between the two writes — and if the
+ * order write never lands, restoring would have been right. That race is why
+ * the caller should place the order and consume in one flow it can reason
+ * about; this function exists so it can do that rather than calling release
+ * and hoping.
+ */
+export declare function consumeReservation(reservationId: string): Promise<void>;
+/**
+ * Release every hold a holder owns. Used when a shared purchase is cancelled
+ * or abandoned — the arrangement knows its own id, and should not have to
+ * remember which reservations it took.
+ */
+export declare function releaseReservationsForHolder(holderKind: ReservationHolderKind, holderId: string, reason?: string): Promise<number>;
+/**
+ * The sweep. Expire every hold past its `expiresAt` and restore its units.
+ *
+ * 🛑 Bounded, and the bound is REPORTED. A silent cap reads as "nothing left
+ * to expire" on the one run where it mattered — the same lie a truncated
+ * recount tells (Root Cause #102).
+ */
+export declare function expireDueReservations(limit?: number): Promise<{
+    scanned: number;
+    expired: number;
+    truncated: boolean;
+}>;
+/** Units currently held on a product, for an admin explaining an unbuyable listing. */
+export declare function activeReservationsForProduct(productId: string): Promise<StockReservationDocument[]>;

package/dist/_internal/server/features/inventory/reservations.js

@@ -0,0 +1,273 @@
+/**
+ * Hold stock for something that is not an order yet.
+ *
+ * ## What this is for
+ *
+ * The plan's Part 6 (shared purchase) names this "the largest hidden cost",
+ * and it is the only one of its three prerequisites that had NOTHING behind
+ * it. See the schema file for why the existing order-keyed mechanism cannot
+ * serve a multi-day arrangement.
+ *
+ * ## 🛑 Every function here moves the row and the counter TOGETHER
+ *
+ * `availableQuantity` is what a buyer can take; the gap between it and
+ * `stockQuantity` is the outstanding hold (`resolveStockResync`'s own words).
+ * A reservation row written without the decrement holds nothing at all, and a
+ * decrement written without a row is a hold nothing can expire — so both
+ * happen inside ONE `runTransaction`, with the product read inside it so two
+ * concurrent reserves cannot both see the same `availableQuantity`.
+ *
+ * ## 🛑 Firestore wants every READ before every WRITE
+ *
+ * So `endReservation` reads the reservation AND the product up front, even
+ * on the consume path where the product read is thrown away. The natural
+ * shape — read the reservation, decide, then read the product — throws
+ * `Firestore transactions require all reads to be executed before all
+ * writes`, and only at runtime, which is exactly the class of fault
+ * `restoreStockForOrder`'s header already warns about one directory over.
+ *
+ * ## Why it writes `availableQuantity` EXPLICITLY
+ *
+ * `ProductRepository.update`'s `resolveStockResync` returns `{}` the moment a
+ * write names `availableQuantity` — deliberately, so the checkout decrement,
+ * the stock-restore job and `updateAvailableQuantity` stay authoritative over
+ * their own number. This is a fourth member of that set and takes the same
+ * deal: it is the one deciding the value, so the resync must keep its hands
+ * off it. (These writes go through the raw collection rather than the
+ * repository for the same reason `deriveTaxonomy` reads categories through
+ * `this.db` — a transaction needs the ref, not a repository method.)
+ */
+import { getAdminDb } from "../../../../providers/db-firebase/index.js";
+import { ValidationError } from "../../../../errors/validation-error.js";
+import { NotFoundError } from "../../../../errors/not-found-error.js";
+import { ConflictError } from "../../../../errors/conflict-error.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+import { serverLogger } from "../../../../monitoring/server-logger.js";
+import { PRODUCT_COLLECTION } from "../../../../features/products/schemas/firestore.js";
+import { STOCK_RESERVATION_FIELDS } from "../../../../constants/field-names.js";
+import { RESERVATION_DEFAULT_TTL_HOURS, RESERVATION_MAX_TTL_HOURS, STOCK_RESERVATION_COLLECTION, } from "../../../../features/inventory/schemas/stock-reservation.js";
+/**
+ * Take a hold. Returns the reservation id.
+ *
+ * 🛑 Refuses rather than over-reserving. A seller's stock is a real number of
+ * real objects, so "reserve 5, only 3 left" is a **409** — the request is
+ * well-formed and the world moved, which is the same distinction the lottery
+ * config write makes for a slot somebody has already pulled.
+ */
+export async function reserveStock(input) {
+    const quantity = Math.floor(input.quantity);
+    if (!Number.isFinite(quantity) || quantity < 1) {
+        throw new ValidationError("Reserve at least one unit.");
+    }
+    const ttlHours = clampTtl(input.ttlHours);
+    const db = getAdminDb();
+    const productRef = db.collection(PRODUCT_COLLECTION).doc(input.productId);
+    const reservationRef = db.collection(STOCK_RESERVATION_COLLECTION).doc();
+    await db.runTransaction(async (tx) => {
+        const snap = await tx.get(productRef);
+        if (!snap.exists)
+            throw new NotFoundError("Product not found.");
+        const available = readAvailable(snap.data());
+        if (available < quantity) {
+            throw new ConflictError(`Only ${Math.max(0, available)} left — cannot hold ${quantity}.`);
+        }
+        const now = new Date();
+        const doc = {
+            productId: input.productId,
+            quantity,
+            holderKind: input.holderKind,
+            holderId: input.holderId,
+            createdBy: input.createdBy,
+            status: "held",
+            expiresAt: new Date(now.getTime() + ttlHours * 60 * 60 * 1000),
+            createdAt: now,
+            updatedAt: now,
+        };
+        tx.set(reservationRef, doc);
+        tx.update(productRef, { availableQuantity: available - quantity, updatedAt: now });
+    });
+    return reservationRef.id;
+}
+/**
+ * End a hold and PUT THE UNITS BACK — the holder changed their mind, an admin
+ * took it back, or the sweep found it expired.
+ */
+export async function releaseReservation(reservationId, opts = {}) {
+    await endReservation(reservationId, opts.status ?? "released", true, opts.reason);
+}
+/**
+ * End a hold and KEEP the units off the shelf — the arrangement completed and
+ * an order now owns them.
+ *
+ * 🛑 This is the one path that must NOT restore. The order's own decrement is
+ * what holds the units from here, so restoring first would hand the same
+ * stock to the next buyer for the moment between the two writes — and if the
+ * order write never lands, restoring would have been right. That race is why
+ * the caller should place the order and consume in one flow it can reason
+ * about; this function exists so it can do that rather than calling release
+ * and hoping.
+ */
+export async function consumeReservation(reservationId) {
+    await endReservation(reservationId, "consumed", false);
+}
+/**
+ * Release every hold a holder owns. Used when a shared purchase is cancelled
+ * or abandoned — the arrangement knows its own id, and should not have to
+ * remember which reservations it took.
+ */
+export async function releaseReservationsForHolder(holderKind, holderId, reason) {
+    const db = getAdminDb();
+    const snap = await db
+        .collection(STOCK_RESERVATION_COLLECTION)
+        .where(STOCK_RESERVATION_FIELDS.HOLDER_KIND, "==", holderKind)
+        .where(STOCK_RESERVATION_FIELDS.HOLDER_ID, "==", holderId)
+        .where(STOCK_RESERVATION_FIELDS.STATUS, "==", "held")
+        .get();
+    let released = 0;
+    for (const doc of snap.docs) {
+        try {
+            await endReservation(doc.id, "released", true, reason);
+            released += 1;
+        }
+        catch (error) {
+            const normalized = normalizeError(error);
+            /*
+             * One bad row must not strand the rest. A holder with eight holds and
+             * one deleted product should still get the other seven back.
+             */
+            serverLogger.warn("releaseReservationsForHolder: skipped one", {
+                reservationId: doc.id,
+                message: normalized.message,
+            });
+        }
+    }
+    return released;
+}
+/**
+ * The sweep. Expire every hold past its `expiresAt` and restore its units.
+ *
+ * 🛑 Bounded, and the bound is REPORTED. A silent cap reads as "nothing left
+ * to expire" on the one run where it mattered — the same lie a truncated
+ * recount tells (Root Cause #102).
+ */
+export async function expireDueReservations(limit = 200) {
+    const db = getAdminDb();
+    const snap = await db
+        .collection(STOCK_RESERVATION_COLLECTION)
+        .where(STOCK_RESERVATION_FIELDS.STATUS, "==", "held")
+        .where(STOCK_RESERVATION_FIELDS.EXPIRES_AT, "<=", new Date())
+        .orderBy(STOCK_RESERVATION_FIELDS.EXPIRES_AT, "asc")
+        .limit(limit)
+        .get();
+    let expired = 0;
+    for (const doc of snap.docs) {
+        try {
+            await endReservation(doc.id, "expired", true, "TTL elapsed");
+            expired += 1;
+        }
+        catch (error) {
+            const normalized = normalizeError(error);
+            serverLogger.warn("expireDueReservations: skipped one", {
+                reservationId: doc.id,
+                message: normalized.message,
+            });
+        }
+    }
+    return { scanned: snap.size, expired, truncated: snap.size === limit };
+}
+/** Units currently held on a product, for an admin explaining an unbuyable listing. */
+export async function activeReservationsForProduct(productId) {
+    const db = getAdminDb();
+    const snap = await db
+        .collection(STOCK_RESERVATION_COLLECTION)
+        .where(STOCK_RESERVATION_FIELDS.PRODUCT_ID, "==", productId)
+        .where(STOCK_RESERVATION_FIELDS.STATUS, "==", "held")
+        .get();
+    return snap.docs.map((d) => ({ id: d.id, ...d.data() }));
+}
+function clampTtl(hours) {
+    if (hours === undefined)
+        return RESERVATION_DEFAULT_TTL_HOURS;
+    if (!Number.isFinite(hours) || hours <= 0) {
+        throw new ValidationError("A hold must last longer than zero hours.");
+    }
+    return Math.min(hours, RESERVATION_MAX_TTL_HOURS);
+}
+/**
+ * 🛑 `?? stockQuantity` and NOT `?? 0`.
+ *
+ * `availableQuantity` is optional on rows written before it existed, and
+ * treating an absent value as zero would refuse every reservation on a
+ * fully-stocked legacy listing — a sold-out answer for a product that has
+ * stock, which reads as a stock bug rather than a schema gap.
+ */
+function readAvailable(data) {
+    const product = (data ?? {});
+    return product.availableQuantity ?? product.stockQuantity ?? 0;
+}
+/**
+ * The one write path. Every transition goes through here so the
+ * row-and-counter pairing cannot be forgotten by a new caller — the same
+ * argument `deriveLinePrice` makes inside the cart repository.
+ */
+async function endReservation(reservationId, status, restore, reason) {
+    const db = getAdminDb();
+    const reservationRef = db.collection(STOCK_RESERVATION_COLLECTION).doc(reservationId);
+    await db.runTransaction(async (tx) => {
+        const snap = await tx.get(reservationRef);
+        if (!snap.exists)
+            throw new NotFoundError("Reservation not found.");
+        const reservation = snap.data();
+        /*
+         * 🛑 Idempotent by STATUS, not by a flag. The sweep and a manual release
+         * can reach the same row in the same second; a second restore would
+         * invent units that do not exist, which is worse than a hold that lingers
+         * one sweep longer.
+         */
+        if (reservation.status !== "held")
+            return;
+        /*
+         * Read the product BEFORE the first write, even when `restore` is false
+         * and the value is discarded — see this file's header. One wasted read on
+         * the consume path buys a function whose transaction shape cannot be
+         * broken by a later edit reordering the branches.
+         */
+        const productRef = db.collection(PRODUCT_COLLECTION).doc(reservation.productId);
+        const productSnap = restore ? await tx.get(productRef) : null;
+        const now = new Date();
+        tx.update(reservationRef, {
+            status,
+            endedAt: now,
+            updatedAt: now,
+            ...(reason ? { endedReason: reason } : {}),
+        });
+        if (!restore)
+            return;
+        if (!productSnap?.exists) {
+            /*
+             * The product is gone, so there is no counter to restore — but the row
+             * still has to close, or the sweep retries it forever. Recorded rather
+             * than thrown: an orphaned hold is a data problem, not a reason to fail
+             * the release of the others beside it.
+             */
+            serverLogger.warn("endReservation: product missing, counter not restored", {
+                reservationId,
+                productId: reservation.productId,
+            });
+            return;
+        }
+        const product = productSnap.data();
+        const available = readAvailable(product);
+        const stock = product.stockQuantity ?? available;
+        /*
+         * 🛑 Clamped at `stockQuantity`. A seller who lowered stock while units
+         * were held would otherwise get an `availableQuantity` ABOVE their own
+         * stock on release — a listing offering more than exists, which is the
+         * one direction a stock bug must never go.
+         */
+        tx.update(productRef, {
+            availableQuantity: Math.min(stock, available + reservation.quantity),
+            updatedAt: now,
+        });
+    });
+}

package/dist/_internal/server/features/invoicing/allocate.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Allocating a number from a gapless series (Phase 7, D12).
+ *
+ * ## The whole design in one paragraph
+ *
+ * One transaction does three things: read the (series, FY) counter, `.create()`
+ * an allocation claim keyed on the subject, and write `lastNumber + 1`. Any one
+ * of the three failing rolls back all of them, so there is no state where a
+ * number was consumed without being recorded, and no state where a subject
+ * holds two numbers.
+ *
+ * ## 🛑 Why the claim is INSIDE the transaction
+ *
+ * The obvious shape is "check whether this order already has a number, then
+ * allocate". That is a read-then-write race: two concurrent triggers both read
+ * "no number", both allocate, and the order ends up with two — one of which is
+ * a permanent gap in a series an auditor reads.
+ *
+ * `.create()` inside the transaction makes it impossible rather than unlikely.
+ * A duplicate attempt fails the transaction, and the caller treats that as
+ * "already allocated" and reads the existing number back. This is the fourth
+ * use of that primitive in this codebase (refund claims, the gateway-event
+ * inbox, the gateway-order claim), and the one with the least recoverable
+ * failure mode.
+ *
+ * ## 🛑 Allocate on `paymentStatus → paid`, never at order creation
+ *
+ * COD and manual orders are created `pending`. Numbering at creation burns a
+ * number on every abandoned order, and *gapless* means those gaps are
+ * unexplainable — "that one was abandoned" is not an answer an auditor accepts
+ * for a missing invoice number.
+ */
+import { type InvoiceSeriesKind } from "../../../../features/invoicing/schemas/firestore";
+export interface AllocateSeriesNumberInput {
+    kind: InvoiceSeriesKind;
+    /**
+     * What the number is FOR, and the idempotency key.
+     *
+     * An invoice passes the order id. A credit note passes
+     * `${orderId}_${refundId}`, because an order may have several.
+     */
+    subjectId: string;
+    orderId: string;
+    /** Defaults to now. Injectable so a backfill can issue into a past FY. */
+    at?: Date;
+}
+export interface AllocateSeriesNumberResult {
+    number: string;
+    fy: string;
+    sequence: number;
+    /** True when this call did the allocating; false when it found an existing one. */
+    allocated: boolean;
+}
+/**
+ * Allocate (or return the already-allocated) number for one subject.
+ *
+ * 🛑 Idempotent and NOT best-effort. It throws rather than returning a
+ * sentinel, because every caller's correct response to "we could not number
+ * this" is to leave the order un-invoiced and retry — a caller that treated
+ * failure as "no number needed" would produce a paid order with no invoice,
+ * silently.
+ */
+export declare function allocateSeriesNumber(input: AllocateSeriesNumberInput): Promise<AllocateSeriesNumberResult>;