platform-types 1.10.766 → 1.10.767

package/dist/account.d.ts

@@ -324,8 +324,11 @@ declare global {
      * `DATE_RANGE_INCOMPLETE`) before format (`DATE_MALFORMED`) before semantics
      * (`DATE_RANGE_INVERTED`, `DATE_RANGE_TOO_WIDE`).
      *
-     * ⚠️ The storefront twin can only ever return `DATE_MALFORMED`: it reads no
-     * `from`/`to`, having no store-wide branch to window.
+     * ⚠️ The storefront twin reads no `from`/`to`, having no store-wide branch
+     * to window. Its `GET /account` returns `DATE_MALFORMED` (for `date` or
+     * `until`) and `DATE_RANGE_INVERTED` (`until` before `date`). The storefront
+     * `GET /orders` and `GET /invoices` return the same two codes, for `until`
+     * only (see {@link WebOrdersQuery}, {@link WebInvoicesQuery}).
      */
     type AccountDateRangeError = 'DATE_AND_RANGE_EXCLUSIVE' | 'DATE_RANGE_INCOMPLETE' | 'DATE_MALFORMED' | 'DATE_RANGE_INVERTED' | 'DATE_RANGE_TOO_WIDE';
     /**
@@ -345,13 +348,15 @@ declare global {
      * - `INVALID_CURSOR` — **400.** The `?startKey=` did not decode, or decoded to
      *   a cursor for another store or another customer, one whose own key sits
      *   outside the statement's key range at either end, or one whose pins do not
-     *   hold. ⚠️ **There are TWO pins.** `balanceDate` must not be absent,
+     *   hold. ⚠️ **There are THREE pins.** `balanceDate` must not be absent,
      *   non-numeric or raised past the cursor's own key; `date` must EQUAL the
      *   `?date=` of the request spending the cursor, because it is the boundary
      *   both statement reads are split on — changing it mid-walk would read the
      *   same rows through a different filter and silently skip or repeat every row
-     *   the move crossed. A client that wants a different window starts a new walk
-     *   with no cursor. ⚠️ Never
+     *   the move crossed; and `until` must EQUAL the request's `?until=`, or the
+     *   open-end sentinel `99991231` when the request sends none (a cursor minted
+     *   before `until` existed carries no such pin and is refused once). A client
+     *   that wants a different window starts a new walk with no cursor. ⚠️ Never
      *   "restart from page one" on this: a client cannot tell a silent restart
      *   from a legitimate first page, so a paging loop re-reads from the top and
      *   appends every row twice. Discard the cursor and ask the user.
@@ -367,6 +372,56 @@ declare global {
      *   computes no sum.
      */
     type AccountStatementError = 'INVALID_CURSOR' | 'CUSTOMER_LEDGER_TRUNCATED';
+    /**
+     * How the storefront statement PDF (`GET /account?mode=pdf`) can REFUSE,
+     * beyond {@link AccountDateRangeError} (same window validation as the JSON
+     * page) and `CUSTOMER_LEDGER_TRUNCATED` (the same 503 envelope). Neither
+     * prints a partial PDF — a statement with missing rows prints wrong running
+     * balances.
+     *
+     * - `ACCOUNT_STATEMENT_PDF_TOO_LONG` — **422.** More movements than one PDF
+     *   prints (3000), the server's drain budget ran out before the walk ended,
+     *   or too little time was left to render before the 29 s gateway ceiling.
+     *   The shopper fixes it by narrowing `date`/`until`; no operator ERROR row.
+     * - `ACCOUNT_STATEMENT_PDF_INCOMPLETE` — **503.** Rows are missing that no
+     *   cursor can fetch (the JSON page's `incomplete`), the store's ledger
+     *   currency could not be read, or (defensively — no path to it is known) a
+     *   cursor the server's own drain minted was refused on resume. The shopper cannot fix it. The operator sees one
+     *   deduplicated ERROR row per cause per customer per day
+     *   (`ACCOUNT_STATEMENT_PDF_INCOMPLETE#{cause}#{customerId}`) — except the
+     *   legacy bare-row cut, already recorded as
+     *   `ACCOUNT_BARE_ROWS_TRUNCATED#{customerId}` by the statement read itself.
+     *   Expected, not a crash: a client should not report it as an exception.
+     */
+    type AccountStatementPdfError = 'ACCOUNT_STATEMENT_PDF_TOO_LONG' | 'ACCOUNT_STATEMENT_PDF_INCOMPLETE';
+    /**
+     * The query string of the storefront `GET /account` (CUSTOMER token). The
+     * customer is the token's, never a query value.
+     *
+     * An EMPTY value is the same as an absent one.
+     */
+    interface WebAccountQuery {
+        /**
+         * `YYYYMMDD`, Buenos Aires. The opening-balance boundary: "Saldo anterior"
+         * is the balance before midnight of this day, and movements WRITTEN from
+         * then on are listed. Defaults to today. Every front end sends `19700101`
+         * for the whole ledger.
+         */
+        date?: string;
+        /** The previous page's `LastEvaluatedKey`. See {@link AccountStatementPaging}. */
+        startKey?: string;
+        /**
+         * `YYYYMMDD`, Buenos Aires, INCLUSIVE: movements written through
+         * 23:59:59.999 of this day are listed, later ones are not. Absent means
+         * open-ended. It bounds only the listed half — the opening balance is
+         * unchanged — so the closing figure is the balance as of the end of `until`.
+         * Rows are windowed by when they were WRITTEN (`createdAt`), as for `date`.
+         * `400 DATE_MALFORMED` if not a real calendar day; `400 DATE_RANGE_INVERTED`
+         * if before `date` (`until === date` is one day). No span cap. Pinned in the
+         * cursor: repeat it on every page.
+         */
+        until?: string;
+    }
     /**
      * How a customer statement PAGES.
      *
@@ -386,11 +441,20 @@ declare global {
      * - It also pins `date`, so **every page of one walk must be requested with
      *   the same `?date=`**. A different one is `400 INVALID_CURSOR`, not a
      *   re-anchored page: `date` is the boundary both reads are split on.
+     * - And it pins `until` (storefront only), so **every page of one walk
+     *   repeats the same `?until=`** — or none, on every page. A change is
+     *   `400 INVALID_CURSOR`.
      * - ⚠️ **A page may be EMPTY and still carry a cursor.** The listing read has
      *   a page budget and a wall-clock budget, and it can spend either on rows the
-     *   `dated` filter discards before it matches anything. An empty page beside a
+     *   `createdAt` filter discards before it matches anything. An empty page beside a
      *   `LastEvaluatedKey` means "keep paging", never "drained" — the cursor's
      *   ABSENCE is the only end-of-walk signal.
+     * - ⚠️ **`?mode=pdf` does not page.** The storefront `GET /account?mode=pdf`
+     *   drains the whole window server-side from page one (`?startKey=` is
+     *   ignored) and answers `{ data: 'data:application/pdf;base64,…' }` — the
+     *   envelope of the order and invoice PDFs — or one of
+     *   {@link AccountStatementPdfError}. Any other `mode`, absent included, is
+     *   the JSON page described here.
      * - A cursor is bound to its STORE and its CUSTOMER and cannot be spent
      *   against either another. It is **not** bound to the surface: an
      *   operator-minted cursor is spendable on the storefront and vice versa,

package/dist/invoice.d.ts

@@ -54,6 +54,32 @@ declare global {
         /** The AUTHORITATIVE amount, as declared — never re-derived from `baseImp × alic`. */
         importe: number;
     }
+    /**
+     * The query string of the storefront `GET /invoices` (CUSTOMER token): the
+     * shopper's own authorized invoices, newest first. The customer is the
+     * token's, never a query value.
+     */
+    interface WebInvoicesQuery {
+        /**
+         * `YYYYMMDD` lower bound on the voucher's `dated`, inclusive. Defaults to
+         * one Buenos Aires calendar month before today, the day clamped to that
+         * month's last day (31 Mar → 28/29 Feb). Shape-checked only.
+         */
+        since?: string;
+        /** Rows READ per page, 1–1000 (default 1000). A page may come back short or empty beside a cursor. */
+        Limit?: string;
+        /** The previous page's `LastEvaluatedKey` (a raw sort key, not pinned to `since`/`until`). */
+        offSet?: string;
+        /**
+         * `YYYYMMDD` upper bound on `dated`, INCLUSIVE. Absent or empty means
+         * open-ended. `400 DATE_MALFORMED` if not a real calendar day;
+         * `400 DATE_RANGE_INVERTED` if before `since`. A tight window makes short
+         * and empty pages beside a cursor more frequent — the cursor stays the only
+         * keep-paging signal. Changing it mid-walk re-filters the remaining rows;
+         * restart the walk instead.
+         */
+        until?: string;
+    }
     interface Invoice extends CurrencyRateProvenance {
         storeId: string;
         invoiceId: string;

package/dist/order.d.ts

@@ -435,6 +435,24 @@ declare global {
         province?: string;
         phone?: string;
     }
+    /**
+     * The query string of the storefront `GET /orders` (CUSTOMER token). The
+     * customer is the token's, never a query value.
+     */
+    interface WebOrdersQuery {
+        /** `YYYYMMDD` lower bound on `deliveredDate`, inclusive. Defaults to today (Buenos Aires). */
+        date?: string;
+        /** A point read of one of the caller's own orders; `date`/`until` are ignored. */
+        orderId?: string;
+        /**
+         * `YYYYMMDD` upper bound on `deliveredDate`, INCLUSIVE. Absent or empty
+         * means open-ended. `400 DATE_MALFORMED` if not a real calendar day;
+         * `400 DATE_RANGE_INVERTED` if before `date` (so send both — `date`
+         * defaults to today). ⚠️ It never hides PENDING orders: they carry no
+         * delivery day to window and are always returned, whatever the window.
+         */
+        until?: string;
+    }
     interface Order extends CurrencyRateProvenance, CurrencyRateFreshness {
         storeId: string;
         orderId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "platform-types",
-	"version": "1.10.766",
+	"version": "1.10.767",
 	"description": "Shared wire and entity contracts for the platform.",
 	"type": "module",
 	"main": "dist/index.js",