sinfactura-types 1.10.554 → 1.10.555

package/dist/brands.d.ts

@@ -1,9 +1,26 @@
 declare global {
-    /** Write shape for brand create/update — carries the transient photo controls. */
+    /**
+     * Write shape for brand create/update — carries the transient photo controls.
+     *
+     * `name` is required on a create and optional on an update (send the diff
+     * plus `brandId`). An update of an unknown `brandId` is `404
+     * BRAND_NOT_FOUND`, never an upsert. An empty `description` or `website`
+     * clears it; omitting a field leaves it unchanged.
+     *
+     * A create may carry an `Idempotency-Key` header: the same key and body
+     * answer the same `brandId`, a changed body under that key is `422
+     * IDEMPOTENCY_KEY_REUSE`.
+     */
     type BrandUpsertInput = Partial<Brand> & PhotoUploadControls;
     interface Brand {
         storeId: string;
         brandId: string;
+        /**
+         * Display name, trimmed, 1..200 characters. Unique per store, disabled
+         * brands included, compared after Unicode NFKC, trimming, collapsing
+         * whitespace and lower-casing — accents are kept, so `Niño` and `Nino`
+         * are different brands.
+         */
         name: string;
         photoURL?: string;
         /** @deprecated Request-only upload control, never persisted or returned — use `BrandUpsertInput.photoData`. */
@@ -13,6 +30,37 @@ declare global {
         isFather: boolean;
         father?: string;
         disabled: boolean;
+        /**
+         * URL slug, unique per store: `^[a-z0-9]+(?:-[a-z0-9]+)*$`, at most 80
+         * characters. Minted from `name` on a create, and on an update of a row
+         * that has none only when that update carries `name`; suffixed `-2`,
+         * `-3`… on a clash; a rename never changes it. An explicit value is never
+         * suffixed.
+         */
+        slug?: string;
+        /** At most 2000 characters. */
+        description?: string;
+        /** An absolute `https:` URL without credentials, at most 2048 characters. Never fetched by the api. */
+        website?: string;
     }
+    /** Every code a `POST /brands` identity or lookup check can refuse with. */
+    type BrandErrorCode = 'BRAND_NOT_FOUND' | 'BRAND_NAME_TAKEN' | 'BRAND_SLUG_TAKEN' | 'INVALID_SLUG' | 'BRAND_IDENTITY_CHECK_INCOMPLETE' | 'BRAND_WRITE_CONFLICT';
+    /**
+     * The body of a refused `POST /brands`. Statuses: `BRAND_NOT_FOUND` · 404,
+     * `INVALID_SLUG` · 400, every other code · 409.
+     *
+     * - `BRAND_NAME_TAKEN` — another brand of the store, enabled or disabled,
+     *   has the same name after normalization.
+     * - `BRAND_SLUG_TAKEN` — another brand holds the slug, or won the race for
+     *   a minted one.
+     * - `BRAND_IDENTITY_CHECK_INCOMPLETE` — the store has more brands than one
+     *   uniqueness check reads; nothing was written.
+     * - `BRAND_WRITE_CONFLICT` — the brand changed while it was being saved;
+     *   nothing was written and the request is safe to retry.
+     */
+    type BrandRefusal = {
+        message: string;
+        error: BrandErrorCode;
+    };
 }
 export {};

package/dist/cjs/product.js

@@ -1,6 +1,51 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PRODUCT_POST_ERROR_CODES = void 0;
+exports.PRODUCT_POST_ERROR_CODES = exports.PRODUCT_EXPORT_ERROR_CODES = exports.PRODUCT_CATALOG_EXPORT_COLUMNS = void 0;
+/**
+ * The CSV header of `GET /products?mode=export`, in file order.
+ *
+ * The first block uses the bulk-import row keys, so a column means the same thing
+ * in both directions: `prices` and `sellableOn` are JSON arrays, `barcode` is the
+ * primary barcode. The last block is read-only — the import ignores it:
+ * `productId`, `currentStock` (stock now, not an opening balance), `minStock` and
+ * `updatedAt` (ms epoch).
+ */
+exports.PRODUCT_CATALOG_EXPORT_COLUMNS = [
+    'sku',
+    'name',
+    'description',
+    'categoryId',
+    'brandId',
+    'currency',
+    'cost',
+    'ivaType',
+    'prices',
+    'barcode',
+    'limit',
+    'zone',
+    'isService',
+    'isNew',
+    'disabled',
+    'sellableOn',
+    'weightGrams',
+    'lengthMm',
+    'widthMm',
+    'heightMm',
+    'productId',
+    'currentStock',
+    'minStock',
+    'updatedAt',
+];
+/**
+ * Every refusal `GET /products?mode=export` answers, beyond the cross-cutting
+ * `GATING_ERROR_CODES` (the `importExport` entitlement among them):
+ *
+ * - `ADMIN_REQUIRED` · 403 — the caller is neither ADMIN nor MANAGER.
+ * - `ROLE_FORBIDDEN` · 403 — a print agent or an accountant.
+ * - `VALIDATION_FAILED` · 400 — a filter outside the grammar.
+ * - `INVALID_CURSOR` · 400 — a `startKey` this store did not mint.
+ */
+exports.PRODUCT_EXPORT_ERROR_CODES = ['ADMIN_REQUIRED', 'ROLE_FORBIDDEN', 'VALIDATION_FAILED', 'INVALID_CURSOR'];
 /**
  * Every refusal `POST /products` answers on a single-product create or edit —
  * the body with no `mode`, `stacks/lambdas/products/_post.ts` behind

package/dist/product.d.ts

@@ -13,6 +13,54 @@ declare global {
         /** Requested IDs absent, hidden, disabled or unpriceable; never unresolved reads. */
         unavailableProductIds: string[];
     }
+    /** Anonymous Web GET /products related read; the tenant comes from the public store context. */
+    interface PublicRelatedProductsInput {
+        mode: 'related';
+        /** Canonical id of the product page the suggestions are for. */
+        productId: string;
+    }
+    /**
+     * The computed associations for one product, resolved at read time against the
+     * public projection: at most 10 products, in the model's ranked order, each
+     * visible, enabled, priceable and sellable on the storefront.
+     *
+     * ⚠️ `data: []` covers both "no model computed yet" and "every suggestion is
+     * currently not offered"; the distinction and every figure stay on the
+     * operator `GET /products?mode=associations`. An anchor that is not offered
+     * answers 404 `PRODUCT_NOT_FOUND`; an incomplete read 503
+     * `PRODUCT_LOOKUP_INCOMPLETE`, never a partial list.
+     */
+    interface PublicRelatedProductsResponse {
+        message: string;
+        /** Current public price/projection and online stock, best suggestion first. */
+        data: Partial<Product>[];
+    }
+    /**
+     * Anonymous Web GET /products composed discovery; the tenant comes from the
+     * public store context. Every filter is optional and they AND-compose.
+     */
+    interface PublicProductDiscoverInput {
+        mode: 'discover';
+        /** Free text, ≤100 chars; every token must appear in the product's search term. */
+        search?: string;
+        /** Exact primary category; descendants are not included. */
+        categoryId?: string;
+        brandId?: string;
+        /** Only products with a promo window open now. */
+        inOffer?: 'true';
+        /** Only products the online stock authority can sell now; services always pass. */
+        inStock?: 'true';
+        /** The previous response's `LastEvaluatedKey`, under the SAME filters; else 400 INVALID_CURSOR. */
+        startKey?: string;
+    }
+    /** One page of a discovery walk; `data` can be empty while `LastEvaluatedKey` is set. */
+    interface PublicProductDiscoverResponse {
+        message: string;
+        /** Public price/projection and online stock, in index order. */
+        data: Partial<Product>[];
+        /** Present while rows remain; absent means the walk is complete. */
+        LastEvaluatedKey?: string;
+    }
     /** Write shape for product create/update — carries the transient picture-removal control. */
     type ProductUpsertInput = Partial<Product> & {
         /** Request-only: pictures to delete; the BE removes them from storage and from `pictures[]`. */
@@ -745,7 +793,78 @@ declare global {
         /** Ranked and truncated server-side. May be shorter than the ids requested. */
         data: ProductAssociations[];
     }
+    /**
+     * `GET /products?mode=export` — the filters it accepts, with the operator
+     * listing's (`GET /products`) meaning: an absent `disabled` means enabled-only,
+     * `all` adds the disabled rows, `true` is only those. Any other listing parameter
+     * is refused 400 `VALIDATION_FAILED` rather than ignored. ADMIN or MANAGER,
+     * behind the `importExport` entitlement.
+     */
+    interface ProductCatalogExportQuery {
+        mode: 'export';
+        categoryId?: string;
+        brandId?: string;
+        search?: string;
+        disabled?: 'true' | 'false' | 'all';
+        stock?: 'out' | 'low';
+        inOffer?: 'true' | 'false';
+        /** `nextStartKey` from an incomplete export, to export the rest. */
+        startKey?: string;
+    }
+    /**
+     * One export: a `;`-separated UTF-8 CSV (with BOM), stored privately and handed
+     * out as a short-lived download link. The header row is
+     * {@link PRODUCT_CATALOG_EXPORT_COLUMNS}; an empty cell means the field is absent,
+     * never zero. A text cell starting with `=`, `+`, `-`, `@`, tab, CR or `'` is
+     * written with one extra leading `'` so a spreadsheet opens it as text; stripping
+     * one leading `'` from such a cell restores it exactly. Numbers use `.` as the
+     * decimal separator and are never prefixed.
+     */
+    interface ProductCatalogExport {
+        /** Presigned GET; valid until `expiresAt`. Ask for a new export after that. */
+        url: string;
+        fileName: string;
+        /** ms epoch. */
+        expiresAt: number;
+        /** ms epoch the rows were read at. */
+        generatedAt: number;
+        rowCount: number;
+        /**
+         * `false` when the read stopped before the end of the selection. The file then
+         * holds only the rows before the stop, its name ends in `-parcial`, and
+         * `nextStartKey` exports the rest.
+         */
+        complete: boolean;
+        nextStartKey?: string;
+        columns: ProductCatalogExportColumn[];
+    }
+    interface ProductCatalogExportResponse {
+        message: string;
+        data: ProductCatalogExport;
+    }
+    type ProductCatalogExportColumn = (typeof PRODUCT_CATALOG_EXPORT_COLUMNS)[number];
 }
+/**
+ * The CSV header of `GET /products?mode=export`, in file order.
+ *
+ * The first block uses the bulk-import row keys, so a column means the same thing
+ * in both directions: `prices` and `sellableOn` are JSON arrays, `barcode` is the
+ * primary barcode. The last block is read-only — the import ignores it:
+ * `productId`, `currentStock` (stock now, not an opening balance), `minStock` and
+ * `updatedAt` (ms epoch).
+ */
+export declare const PRODUCT_CATALOG_EXPORT_COLUMNS: readonly ["sku", "name", "description", "categoryId", "brandId", "currency", "cost", "ivaType", "prices", "barcode", "limit", "zone", "isService", "isNew", "disabled", "sellableOn", "weightGrams", "lengthMm", "widthMm", "heightMm", "productId", "currentStock", "minStock", "updatedAt"];
+/**
+ * Every refusal `GET /products?mode=export` answers, beyond the cross-cutting
+ * `GATING_ERROR_CODES` (the `importExport` entitlement among them):
+ *
+ * - `ADMIN_REQUIRED` · 403 — the caller is neither ADMIN nor MANAGER.
+ * - `ROLE_FORBIDDEN` · 403 — a print agent or an accountant.
+ * - `VALIDATION_FAILED` · 400 — a filter outside the grammar.
+ * - `INVALID_CURSOR` · 400 — a `startKey` this store did not mint.
+ */
+export declare const PRODUCT_EXPORT_ERROR_CODES: readonly ["ADMIN_REQUIRED", "ROLE_FORBIDDEN", "VALIDATION_FAILED", "INVALID_CURSOR"];
+export type ProductExportErrorCode = (typeof PRODUCT_EXPORT_ERROR_CODES)[number];
 /**
  * Every refusal `POST /products` answers on a single-product create or edit —
  * the body with no `mode`, `stacks/lambdas/products/_post.ts` behind

package/dist/product.js

@@ -1,3 +1,48 @@
+/**
+ * The CSV header of `GET /products?mode=export`, in file order.
+ *
+ * The first block uses the bulk-import row keys, so a column means the same thing
+ * in both directions: `prices` and `sellableOn` are JSON arrays, `barcode` is the
+ * primary barcode. The last block is read-only — the import ignores it:
+ * `productId`, `currentStock` (stock now, not an opening balance), `minStock` and
+ * `updatedAt` (ms epoch).
+ */
+export const PRODUCT_CATALOG_EXPORT_COLUMNS = [
+    'sku',
+    'name',
+    'description',
+    'categoryId',
+    'brandId',
+    'currency',
+    'cost',
+    'ivaType',
+    'prices',
+    'barcode',
+    'limit',
+    'zone',
+    'isService',
+    'isNew',
+    'disabled',
+    'sellableOn',
+    'weightGrams',
+    'lengthMm',
+    'widthMm',
+    'heightMm',
+    'productId',
+    'currentStock',
+    'minStock',
+    'updatedAt',
+];
+/**
+ * Every refusal `GET /products?mode=export` answers, beyond the cross-cutting
+ * `GATING_ERROR_CODES` (the `importExport` entitlement among them):
+ *
+ * - `ADMIN_REQUIRED` · 403 — the caller is neither ADMIN nor MANAGER.
+ * - `ROLE_FORBIDDEN` · 403 — a print agent or an accountant.
+ * - `VALIDATION_FAILED` · 400 — a filter outside the grammar.
+ * - `INVALID_CURSOR` · 400 — a `startKey` this store did not mint.
+ */
+export const PRODUCT_EXPORT_ERROR_CODES = ['ADMIN_REQUIRED', 'ROLE_FORBIDDEN', 'VALIDATION_FAILED', 'INVALID_CURSOR'];
 /**
  * Every refusal `POST /products` answers on a single-product create or edit —
  * the body with no `mode`, `stacks/lambdas/products/_post.ts` behind

package/package.json

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