@cavuno/board 4.56.1 → 4.56.2

package/CHANGELOG.md

@@ -3,6 +3,54 @@
 This changelog records changes that affect Board API compatibility, exported
 types, runtime behavior, or supported integration patterns.
 
+## 4.57.0 — 2026-10-28
+
+- Digital products. `board.products` lists a board's products (`list`, with
+  `q`, `price`, `sort` and cursor pages), reads a product page (`get`) and its
+  reviews (`reviews`), and starts a purchase (`checkout`): a free product
+  returns `status: 'complete'` with the download page path, a paid one an
+  embedded Stripe Checkout mount kit (`status: 'open'`) that lasts 30 minutes;
+  read it back after Stripe returns the buyer with `getCheckout`.
+- A product page carries `descriptionHtml`, the seller's formatted
+  description as sanitized HTML (headings, lists, quotes, dividers, links and
+  the board's own images), with `description` as its plain text; and
+  `salesCount`, set only when the seller shows the number of sales. Each row
+  of `details` (`ProductDetailRow`) names its `kind`: `text` rows carry
+  `value`; `check` rows are yes/no facts with `checked`, to show as a tick
+  or a cross.
+- `board.purchases` serves the download page by purchase token: `get`,
+  `confirmEmail` (shared links), `download` (a signed link per file),
+  `downloadAll` (one ZIP), `review`, `resend` ("email me this link again",
+  always accepted) and `mine` (the signed-in user's library). Responses that
+  pass the shared-link check return `confirmationToken`; pass it back as the
+  `confirmationToken` option (the `X-Cavuno-Purchase-Confirmation` header,
+  exported as `PURCHASE_CONFIRMATION_HEADER`). The page's
+  `downloadAllAvailable` says whether to offer Download all: the ready files
+  must total at most 500 MB, and above that `downloadAll` is refused with
+  `409 purchase_download_all_unavailable` and nothing counted.
+- Paths and route roles: `productPath(slug)`, `purchasePath(token)`,
+  `BOARD_PATHS.products` (`/products`) and `BOARD_PATHS.mePurchases`
+  (`/me/purchases`), with the route manifest roles `product`, `purchase`,
+  `products` and `mePurchases`.
+- New error codes for products and purchases, listed in
+  `BOARD_API_ERROR_CODES`: `products_not_found`,
+  `product_checkout_not_found`, `product_reviews_disabled`,
+  `product_sold_out`, `product_email_invalid`, `product_email_blocked`,
+  `product_amount_below_minimum`, `product_amount_invalid`,
+  `product_answers_invalid`, `purchases_not_found`,
+  `purchase_file_not_found`, `purchase_unavailable`,
+  `purchase_access_removed`, `purchase_awaiting_payment`,
+  `purchase_refunded`, `purchase_email_confirmation_required`,
+  `purchase_email_mismatch`, `purchase_file_preparing`,
+  `purchase_download_limit_reached`, `purchase_review_invalid` and
+  `purchase_download_all_unavailable`. A file out of downloads is
+  `409 purchase_download_limit_reached`, a permanent limit rather than a rate
+  limit, so `isRateLimited` is false for it and `isConflict` is true.
+
+## 4.56.2 — 2026-10-28
+
+- No changes to Board API types or runtime behavior.
+
 ## 4.56.1 — 2026-10-28
 
 - Market suggestions from `search.suggest` carry `displayName` and

package/dist/{_spec-DS4-nx__.d.mts → _spec-CDYDY0hB.d.mts}

@@ -2292,6 +2292,174 @@ interface components {
             /** @description The `token` query parameter from the invite link (`/employers/invites/accept?token=…`). */
             token: string;
         };
+        ProductCard: {
+            /** @enum {string} */
+            object: "product";
+            slug: string;
+            name: string;
+            summary: string | null;
+            coverImageUrl: string | null;
+            price: components["schemas"]["ProductPrice"];
+            rating: components["schemas"]["ProductRatingSummary"];
+            soldOut: boolean;
+            /** @description The product page path on the board (its route manifest words). */
+            url: string;
+        };
+        ProductCheckout: {
+            /** @enum {string} */
+            object: "product_checkout";
+            /**
+             * @description `complete`: a free claim was recorded; send the buyer to `downloadUrl`. `open`: mount the embedded Stripe Checkout with the mount kit fields.
+             * @enum {string}
+             */
+            status: "complete" | "open";
+            /** @description `complete` only: the download page path on the board, with its token. */
+            downloadUrl: string | null;
+            /** @description `complete` only: the purchase token for `GET /purchases/{token}`. */
+            purchaseToken: string | null;
+            sessionId: string | null;
+            /** @description `open` only: the Checkout Session client secret. The session expires after 30 minutes. */
+            clientSecret: string | null;
+            /** @description `open` only: the board’s connected Stripe account. */
+            stripeAccountId: string | null;
+            /** @description `open` only: the Stripe publishable key for `loadStripe`. */
+            publishableKey: string | null;
+        };
+        ProductCheckoutBody: {
+            /** @description Where the download link and receipt are sent. */
+            email: string;
+            /**
+             * @description Answers to the product’s `questions`, by question id.
+             * @default []
+             */
+            answers: {
+                questionId: string;
+                value: string | boolean;
+            }[];
+            /** @description Pay what you want: the amount the buyer chose, in cents. Omit to let the buyer choose on the Stripe page. `0` on a $0+ product claims it for free. */
+            amountCents?: number;
+            /** @description Free products: also subscribe the email to the board’s job alerts. Show it unticked. */
+            jobAlertOptIn?: boolean;
+            /** @description Paid products: the relative path Stripe returns the buyer to (`session_id` is appended). Defaults to the product page. */
+            returnPath?: string;
+            /** @description Honeypot. Render it hidden and leave it empty; a filled value is answered like a success and nothing is recorded or sent. */
+            website?: string;
+        };
+        ProductCheckoutStatus: {
+            /** @enum {string} */
+            object: "product_checkout_status";
+            /**
+             * @description `awaiting_payment` until the payment webhook lands (poll briefly), then `paid` with the download page.
+             * @enum {string}
+             */
+            status: "awaiting_payment" | "paid" | "free" | "access_removed";
+            /** @description `paid` only: the download page path on the board, with its token. */
+            downloadUrl: string | null;
+            /** @description `paid` only: the purchase token for `GET /purchases/{token}`. */
+            purchaseToken: string | null;
+        };
+        ProductDetail: {
+            /** @enum {string} */
+            object: "product";
+            slug: string;
+            name: string;
+            /** @description Plain-text description. When `descriptionHtml` is set, this is its text. */
+            description: string | null;
+            /** @description Formatted description as sanitized HTML: `h2`, `h3`, `p`, `br`, `strong`, `em`, `u`, `s`, `ul`, `ol`, `li`, `blockquote`, `hr`, `a` (`rel="noopener nofollow ugc"`, new tab) and `img` (images uploaded to this board only). `null` when the seller wrote none; show `description` instead. */
+            descriptionHtml: string | null;
+            summary: string | null;
+            /** @description Operator facts shown on the product page. */
+            details: components["schemas"]["ProductDetailRow"][];
+            images: string[];
+            price: components["schemas"]["ProductPrice"];
+            soldOut: boolean;
+            /** @description Sales so far, when the seller shows the number of sales; otherwise `null`. */
+            salesCount: number | null;
+            refundPolicy: string | null;
+            questions: components["schemas"]["ProductQuestion"][];
+            contents: {
+                displayName: string;
+                description: string | null;
+                /** @enum {string} */
+                kind: "file" | "link";
+                /** @description File extension (`pdf`, `zip`, …) or `link`. */
+                fileType: string;
+                pageCount: number | null;
+                sizeBytes: number | null;
+            }[];
+            facts: {
+                fileCount: number;
+                linkCount: number;
+                fileTypes: string[];
+                pageCount: number | null;
+                totalSizeBytes: number;
+            };
+            /** @description `false` for an unlisted (link-only) product: keep it out of listings, sitemaps and search indexes. */
+            isListed: boolean;
+            ratingsEnabled: boolean;
+            rating: {
+                average: number | null;
+                count: number;
+                /** @description Counted reviews per star, 1 star first. */
+                histogram: number[];
+            } | null;
+            /** @description The product page path on the board. */
+            url: string;
+        };
+        /** @description A facts box row: `text` shows `value`; `check` is a yes/no row shown as a tick or a cross. */
+        ProductDetailRow: {
+            /** @enum {string} */
+            kind: "text";
+            label: string;
+            value: string;
+        } | {
+            /** @enum {string} */
+            kind: "check";
+            label: string;
+            /** @description Yes/no: show a tick for `true` and a cross for `false`, not a word. */
+            checked: boolean;
+        };
+        ProductPrice: {
+            /**
+             * @description `free`: claimed with an email. `fixed`: one price. `pay_what_you_want`: the buyer chooses at least `minimumCents`.
+             * @enum {string}
+             */
+            kind: "free" | "fixed" | "pay_what_you_want";
+            /** @description Lowercase ISO currency code; `null` for free products. */
+            currency: string | null;
+            /** @description The price (fixed), the minimum (pay what you want), or 0 (free). */
+            amountCents: number;
+            minimumCents?: number;
+            suggestedCents?: number | null;
+        };
+        ProductQuestion: {
+            id: string;
+            /** @enum {string} */
+            kind: "text" | "checkbox" | "dropdown";
+            label: string;
+            required: boolean;
+            /** @description Dropdown choices; `null` for the other kinds. */
+            options: string[] | null;
+        };
+        /** @description `null` when ratings are off for the product. */
+        ProductRatingSummary: {
+            /** @description Average stars, 1 to 5; `null` with no counted reviews. */
+            average: number | null;
+            count: number;
+        } | null;
+        ProductReview: {
+            id: string;
+            /** @enum {string} */
+            object: "product_review";
+            stars: number;
+            comment: string | null;
+            displayName: string | null;
+            /** @description The operator’s public reply. */
+            reply: string | null;
+            replyAt: string | null;
+            createdAt: string;
+            updatedAt: string;
+        };
         ProfileChoiceList: {
             data: {
                 id: string;
@@ -3169,6 +3337,148 @@ interface components {
             /** @description The board password. */
             password: string;
         };
+        Purchase: {
+            /** @enum {string} */
+            object: "purchase";
+            /** @enum {string} */
+            status: "awaiting_payment" | "paid" | "free";
+            product: {
+                slug: string;
+                name: string;
+                thankYouMessage: string | null;
+            };
+            email: string;
+            purchasedAt: string;
+            amountCents: number;
+            currency: string;
+            /** @description Downloads allowed per file. */
+            downloadCap: number;
+            files: ({
+                /** @enum {string} */
+                kind: "file";
+                fileId: string;
+                displayName: string;
+                description: string | null;
+                contentType: string | null;
+                sizeBytes: number | null;
+                pageCount: number | null;
+                /**
+                 * @description `preparing`: the buyer’s personal stamped copy is being made (they are emailed when it is ready). `limit_reached`: no downloads left.
+                 * @enum {string}
+                 */
+                state: "ready" | "preparing" | "limit_reached";
+                downloadsUsed: number;
+                downloadsLeft: number;
+                /** @description The buyer gets their own stamped copy of this PDF. */
+                stamped: boolean;
+            } | {
+                /** @enum {string} */
+                kind: "link";
+                fileId: string;
+                displayName: string;
+                description: string | null;
+                url: string;
+            })[];
+            /** @description Whether to offer Download all: a file is ready to download and the ready files total at most 500 MB. Above 500 MB the buyer downloads the files one by one. */
+            downloadAllAvailable: boolean;
+            /** @enum {string} */
+            stamping: "off" | "ready" | "preparing";
+            /** @description The Stripe receipt or paid invoice; `null` for free claims. */
+            receiptUrl: string | null;
+            refundPolicy: string | null;
+            ratingsEnabled: boolean;
+            /** @description The buyer’s own review, if any. */
+            review: {
+                stars: number;
+                comment: string | null;
+                displayName: string | null;
+                hidden: boolean;
+                reply: string | null;
+                updatedAt: string;
+            } | null;
+            purchaseToken: string;
+            /** @description Send it back in `X-Cavuno-Purchase-Confirmation` on later requests for this purchase; `null` when the request already carried it. */
+            confirmationToken: string | null;
+        };
+        PurchaseConfirmBody: {
+            email: string;
+        };
+        PurchaseConfirmation: {
+            /** @enum {string} */
+            object: "purchase_confirmation";
+            confirmationToken: string;
+        };
+        PurchaseDownload: {
+            /** @enum {string} */
+            object: "purchase_download";
+            /** @description A signed, short-lived link that downloads as an attachment. */
+            url: string;
+            expiresAt: string;
+            /** @description The name it downloads under: the file's `displayName`, with the file's extension added when that name has none. */
+            fileName: string;
+            downloadsLeft: number;
+            confirmationToken: string | null;
+        };
+        PurchaseDownloadAll: {
+            /** @enum {string} */
+            object: "purchase_download_all";
+            /** @description A short-lived link to the streamed ZIP of every ready file. */
+            url: string;
+            expiresAt: string;
+            fileCount: number;
+            totalBytes: number;
+            /** @description File ids left out while their stamped copy is made. */
+            preparing: string[];
+            /** @description File ids left out because no downloads are left. */
+            limitReached: string[];
+            confirmationToken: string | null;
+        };
+        PurchaseResendBody: {
+            email: string;
+            /** @description Only this product’s purchases; omit for all of them. */
+            productSlug?: string;
+            /** @description Honeypot. Render it hidden and leave it empty. */
+            website?: string;
+        };
+        PurchaseResendResult: {
+            /** @enum {string} */
+            object: "purchase_resend";
+            /** @enum {boolean} */
+            accepted: true;
+        };
+        PurchaseReviewBody: {
+            stars: number;
+            comment?: string;
+            /** @description The name shown with the review; omit to stay anonymous. */
+            displayName?: string;
+        };
+        PurchaseReviewResult: {
+            id: string;
+            /** @enum {string} */
+            object: "purchase_review";
+            /** @description Whether the stars count toward the product rating. */
+            counted: boolean;
+        };
+        PurchaseSummary: {
+            id: string;
+            /** @enum {string} */
+            object: "purchase_summary";
+            product: {
+                slug: string;
+                name: string;
+                coverImageUrl: string | null;
+            };
+            /** @enum {string} */
+            status: "paid" | "free";
+            purchasedAt: string;
+            amountCents: number;
+            currency: string;
+            /** @description `false` while the product cannot be delivered (taken down, or the board is closed). */
+            available: boolean;
+            purchaseToken: string;
+            /** @description The download page path on the board. */
+            downloadUrl: string;
+        };
         ReadReceipt: {
             /** @enum {string} */
             object: "read_receipt";