@reblu/site-contracts 1.13.0 → 1.15.0

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # @reblu/site-contracts
 
+## 1.15.0
+
+### Minor Changes
+
+- 614e826: Shop checkout: full-invoice opt-in and the buyer's identifier (REB-73).
+
+  `ShopCheckoutInput` gains the optional `wantsFullInvoice` flag, and
+  `ShopBillingInput` the optional `billingIdType` (`NIF` for a Spanish
+  NIF/NIE/CIF; `02` EU VAT id, `03` passport, `04` ID document of the country
+  of residence, `05` residence certificate, `06` other document) and
+  `billingIdCountry` (ISO 3166-1 alpha-2, required for `02`–`06`). A full
+  invoice needs the identifier, the billing name and a billing address; without
+  the identifier the invoice is simplified.
+
+  `ShopErrorCode` gains two checkout codes, both answered before any payment:
+  `BILLING_DATA_REQUIRED` (HTTP 422, `details.field: 'billing'`) when the
+  opt-in, or a total over the tenant's simplified-invoice cap, comes without
+  those three; and `INVOICING_NOT_READY` (HTTP 503) when the shop cannot issue
+  invoices yet. Existing clients that send only `billing.billingNif` keep
+  working: its type is derived from the billing address country.
+
+- 614e826: Shop checkout: no full-invoice opt-in on a shop that issues no invoices (REB-73).
+  - `ShopErrorCode` gains `FULL_INVOICE_UNAVAILABLE` (HTTP 422,
+    `details.field: 'wantsFullInvoice'`): `wantsFullInvoice: true` sent to a shop
+    whose invoicing is off (`ShopConfig.simplifiedInvoiceCapCents` is `null`) is
+    refused before any payment instead of succeeding without an invoice. Clients
+    that never send the opt-in are unaffected. The union is additive: a SITE
+    with an exhaustive `switch` over `ShopErrorCode` (or a
+    `Record<ShopErrorCode, …>`) must add the new member when it upgrades.
+  - `@reblu/site-blocks`: new `shopIssuesInvoices(config)`; `FullInvoiceFields`
+    takes `issuesInvoices` (default `true`) and renders nothing when it is
+    `false`, and `toCheckoutInvoiceFields(value, overCap, issuesInvoices)`
+    returns no opt-in and no billing block then. Default Spanish copy for the
+    new code in `getShopErrorMessage`.
+
+- 614e826: Shop: the order's invoice and the simplified-invoice cap (REB-73).
+  - `ShopOrder` gains the optional `invoice: { number, url } | null`
+    (`ShopOrderInvoice`): once the sale invoice is issued, its number and the
+    shop's authenticated client-portal route that serves it — never a signed
+    URL, so the link does not expire; the buyer signs in to open it.
+  - `ShopConfig` gains `simplifiedInvoiceCapCents` (cents, never above the legal
+    300000; `null` while the shop issues no invoices): above it, checkout needs
+    the buyer's identifier, name and billing address.
+  - `@reblu/site-blocks`: new drop-in `OrderInvoiceLink`, which
+    `OrderConfirmation` now renders under a confirmed order (labels
+    `invoiceLinkLabel`/`invoiceSignInHint`), and default Spanish copy for the
+    `BILLING_DATA_REQUIRED`/`INVOICING_NOT_READY` checkout codes in
+    `getShopErrorMessage`.
+
+## 1.14.0
+
+### Minor Changes
+
+- 92e0f6f: Add the `header` slot to `Cta['slot']` (`'header' | 'hero' | 'blog-end' | 'services' | 'contact' | 'sticky-mobile' | 'footer'`), so a SITE can drive its persistent header CTA from nexus via `GET /api/site/ctas?slot=header`.
+- b75f066: Deprecate `ShopCheckEmailInput` and `ShopEmailCheck` (REB-834). `POST /api/site/shop/check-email` was an account-enumeration oracle on the tenant's customer list; it now always answers `{ exists: false }`. Never branch UI on `exists`. Both types are removed in the next major.
+
 ## 1.13.0
 
 ### Minor Changes

package/README.md

@@ -30,6 +30,13 @@ async function getPosts(): Promise<{ data: BlogPostListItem[] }> {
 Pair it with `@reblu/site-client` for a typed client that already knows these
 shapes.
 
+### Editable CTAs — slots
+
+`Cta['slot']` is the union of placements a CTA can be configured for in nexus:
+`'header' | 'hero' | 'blog-end' | 'services' | 'contact' | 'sticky-mobile' |
+'footer'`. `GET /api/site/ctas?slot=header` returns the active CTAs of the
+persistent header; `@reblu/site-next`'s `EditableCta` renders them drop-in.
+
 ### Page blocks — canonical shape (REB-849 / REB-851 / REB-852 / REB-854)
 
 `GET /api/site/pages/[slug]` (`PageDetail`) returns BOTH `sections[]` (legacy,

package/dist/index.d.cts

@@ -71,7 +71,7 @@ export type ContactFormSubmission = {    id: string;    createdAt: string;}
 
 export type CookieBanner = {    enabled: boolean;    title: string | null;    body: string | null;    acceptLabel: string | null;    rejectLabel: string | null;    manageLabel: string | null;    policyUrl: string | null;}
 
-export type Cta = {    id: string;    slot: "hero" | "blog-end" | "services" | "contact" | "sticky-mobile" | "footer";    label: string;    href: string;    sortOrder: number;    abVariant: string | null;    analyticsId: string;}
+export type Cta = {    id: string;    slot: "header" | "hero" | "blog-end" | "services" | "contact" | "sticky-mobile" | "footer";    label: string;    href: string;    sortOrder: number;    abVariant: string | null;    analyticsId: string;}
 
 export type CustomFieldDefinition = {    id: string;    entityType: "page" | "product";    key: string;    label: string;    valueType: "boolean" | "text" | "select" | "multiselect";    options: {        value: string;        label: string;    }[];    isFilterable: boolean;    showInDetail: boolean;    unit: string | null;    sortOrder: number;}
 
@@ -145,7 +145,7 @@ export type ShopAddressInput = {    firstName: string;    lastName: string;    s
 
 export type ShopApplyDiscountInput = {    code: string;    orderSubtotal: number;    customerEmail?: string | undefined;}
 
-export type ShopBillingInput = {    billingName: string;    billingNif?: string | undefined;    billingEmail?: string | undefined;    billingAddress?: {        firstName: string;        lastName: string;        street: string;        city: string;        postalCode: string;        region?: string | undefined;        country?: string | undefined;        phone?: string | null | undefined;    } | undefined;}
+export type ShopBillingInput = {    billingName: string;    billingNif?: string | undefined;    billingIdType?: "NIF" | "02" | "03" | "04" | "05" | "06" | undefined;    billingIdCountry?: string | undefined;    billingEmail?: string | undefined;    billingAddress?: {        firstName: string;        lastName: string;        street: string;        city: string;        postalCode: string;        region?: string | undefined;        country?: string | undefined;        phone?: string | null | undefined;    } | undefined;}
 
 export type ShopBundleComponent = {    quantity: number;    component: {        id: string;        name: string;        slug: string;        price: number;    };}
 
@@ -159,25 +159,37 @@ export type ShopCartValidationItem = {    productId: string;    name: string;
 
 export type ShopCategory = {    id: string;    name: string;    slug: string;    description: string | null;    imageUrl: string | null;    parentId: string | null;    sortOrder: number;}
 
+/**
+ * @deprecated REB-834 — `POST /api/site/shop/check-email` no longer reveals
+ * whether an account exists. Do not call it; removed in the next major.
+ */
 export type ShopCheckEmailInput = {    email: string;}
 
-export type ShopCheckoutInput = {    items: {        productId: string;        quantity: number;        variantId?: string | null | undefined;    }[];    customerEmail: string;    customerName: string;    successUrl: string;    cancelUrl: string;    customerPhone?: string | null | undefined;    discountCode?: string | undefined;    shippingAddress?: {        firstName: string;        lastName: string;        street: string;        city: string;        postalCode: string;        region?: string | undefined;        country?: string | undefined;        phone?: string | null | undefined;    } | undefined;    billing?: {        billingName: string;        billingNif?: string | undefined;        billingEmail?: string | undefined;        billingAddress?: {            firstName: string;            lastName: string;            street: string;            city: string;            postalCode: string;            region?: string | undefined;            country?: string | undefined;            phone?: string | null | undefined;        } | undefined;    } | undefined;}
+export type ShopCheckoutInput = {    items: {        productId: string;        quantity: number;        variantId?: string | null | undefined;    }[];    customerEmail: string;    customerName: string;    successUrl: string;    cancelUrl: string;    customerPhone?: string | null | undefined;    discountCode?: string | undefined;    shippingAddress?: {        firstName: string;        lastName: string;        street: string;        city: string;        postalCode: string;        region?: string | undefined;        country?: string | undefined;        phone?: string | null | undefined;    } | undefined;    billing?: {        billingName: string;        billingNif?: string | undefined;        billingIdType?: "NIF" | "02" | "03" | "04" | "05" | "06" | undefined;        billingIdCountry?: string | undefined;        billingEmail?: string | undefined;        billingAddress?: {            firstName: string;            lastName: string;            street: string;            city: string;            postalCode: string;            region?: string | undefined;            country?: string | undefined;            phone?: string | null | undefined;        } | undefined;    } | undefined;    wantsFullInvoice?: boolean | undefined;}
 
 export type ShopCheckoutSession = {    url: string;    sessionId: string;}
 
-export type ShopConfig = {    shopName: string | null;    defaultLowStockThreshold: number;    currencyCode: string;    stripePublishableKey: string | null;    stripeTestPublishableKey: string | null;    stripeTestMode: boolean;    shippingEnabled: boolean;    pickupEnabled: boolean;    taxEnabled: boolean;    taxIncludedInPrice: boolean;    productTrustItems?: {        [x: string]: unknown;        icon: (string & {}) | "shipping" | "returns" | "secure-payment" | "support" | "gift" | "pickup" | "warranty" | "quality";        text: string;    }[] | null | undefined;}
+export type ShopConfig = {    shopName: string | null;    defaultLowStockThreshold: number;    currencyCode: string;    stripePublishableKey: string | null;    stripeTestPublishableKey: string | null;    stripeTestMode: boolean;    shippingEnabled: boolean;    pickupEnabled: boolean;    taxEnabled: boolean;    taxIncludedInPrice: boolean;    simplifiedInvoiceCapCents?: number | null | undefined;    productTrustItems?: {        [x: string]: unknown;        icon: (string & {}) | "shipping" | "returns" | "secure-payment" | "support" | "gift" | "pickup" | "warranty" | "quality";        text: string;    }[] | null | undefined;}
 
 export type ShopDiscountApplication = {    valid: boolean;    discount: number;    type: "PERCENTAGE" | "FIXED" | null;    code: string | null;    error?: string | undefined;}
 
+/**
+ * @deprecated REB-834 — `exists` is always `false`. Never branch UI on it:
+ * the checkout always offers «Iniciar sesión o continuar como invitado» and
+ * the server links the order to an existing account after payment. Removed
+ * in the next major.
+ */
 export type ShopEmailCheck = {    exists: boolean;}
 
-export type ShopErrorCode = "STOCK_CHANGED" | "PRICE_CHANGED" | "PRODUCT_UNAVAILABLE" | "DISCOUNT_INVALID" | "SHIPPING_UNAVAILABLE" | "INVALID_INPUT" | "STORE_DISABLED" | "PAYMENT_PROVIDER_ERROR" | "INTERNAL_ERROR"
+export type ShopErrorCode = "STOCK_CHANGED" | "PRICE_CHANGED" | "PRODUCT_UNAVAILABLE" | "DISCOUNT_INVALID" | "SHIPPING_UNAVAILABLE" | "INVALID_INPUT" | "STORE_DISABLED" | "PAYMENT_PROVIDER_ERROR" | "INTERNAL_ERROR" | "BILLING_DATA_REQUIRED" | "INVOICING_NOT_READY" | "FULL_INVOICE_UNAVAILABLE"
 
 export type ShopFacets = {    taxonomies: {        key: string;        label: string;        showAsBadge: boolean;        selectionMode: "single" | "multiple";        terms: {            slug: string;            name: string;            count: number;        }[];    }[];    attributes: {        key: string;        label: string;        valueType: "boolean" | "text" | "select" | "multiselect";        options: {            value: string;            label: string;            count: number;        }[];    }[];    price: {        min: number;        max: number;    };    onSale: {        count: number;    };}
 
 export type ShopInventoryRef = {    stockQuantity: number;    reservedQuantity: number;    lowStockThreshold: number | null;}
 
-export type ShopOrder = {    id: string;    orderNumber: string;    status: "PENDING" | "CONFIRMED" | "PROCESSING" | "SHIPPED" | "DELIVERED" | "CANCELLED" | "REFUNDED";    paymentStatus: "PENDING" | "REFUNDED" | "PAID" | "FAILED" | "PARTIALLY_REFUNDED";    customerEmail: string;    total: number;    items: {        product: {            id: string;            name: string;            slug: string;        };        quantity: number;        unitPrice: number;        total: number;        variant?: {            id: string;            name: string;        } | null | undefined;    }[];}
+export type ShopOrder = {    id: string;    orderNumber: string;    status: "PENDING" | "CONFIRMED" | "PROCESSING" | "SHIPPED" | "DELIVERED" | "CANCELLED" | "REFUNDED";    paymentStatus: "PENDING" | "REFUNDED" | "PAID" | "FAILED" | "PARTIALLY_REFUNDED";    customerEmail: string;    total: number;    items: {        product: {            id: string;            name: string;            slug: string;        };        quantity: number;        unitPrice: number;        total: number;        variant?: {            id: string;            name: string;        } | null | undefined;    }[];    invoice?: {        number: string;        url: string;    } | null | undefined;}
+
+export type ShopOrderInvoice = {    number: string;    url: string;}
 
 export type ShopOrderItem = {    product: {        id: string;        name: string;        slug: string;    };    quantity: number;    unitPrice: number;    total: number;    variant?: {        id: string;        name: string;    } | null | undefined;}
 

package/dist/index.d.ts

@@ -71,7 +71,7 @@ export type ContactFormSubmission = {    id: string;    createdAt: string;}
 
 export type CookieBanner = {    enabled: boolean;    title: string | null;    body: string | null;    acceptLabel: string | null;    rejectLabel: string | null;    manageLabel: string | null;    policyUrl: string | null;}
 
-export type Cta = {    id: string;    slot: "hero" | "blog-end" | "services" | "contact" | "sticky-mobile" | "footer";    label: string;    href: string;    sortOrder: number;    abVariant: string | null;    analyticsId: string;}
+export type Cta = {    id: string;    slot: "header" | "hero" | "blog-end" | "services" | "contact" | "sticky-mobile" | "footer";    label: string;    href: string;    sortOrder: number;    abVariant: string | null;    analyticsId: string;}
 
 export type CustomFieldDefinition = {    id: string;    entityType: "page" | "product";    key: string;    label: string;    valueType: "boolean" | "text" | "select" | "multiselect";    options: {        value: string;        label: string;    }[];    isFilterable: boolean;    showInDetail: boolean;    unit: string | null;    sortOrder: number;}
 
@@ -145,7 +145,7 @@ export type ShopAddressInput = {    firstName: string;    lastName: string;    s
 
 export type ShopApplyDiscountInput = {    code: string;    orderSubtotal: number;    customerEmail?: string | undefined;}
 
-export type ShopBillingInput = {    billingName: string;    billingNif?: string | undefined;    billingEmail?: string | undefined;    billingAddress?: {        firstName: string;        lastName: string;        street: string;        city: string;        postalCode: string;        region?: string | undefined;        country?: string | undefined;        phone?: string | null | undefined;    } | undefined;}
+export type ShopBillingInput = {    billingName: string;    billingNif?: string | undefined;    billingIdType?: "NIF" | "02" | "03" | "04" | "05" | "06" | undefined;    billingIdCountry?: string | undefined;    billingEmail?: string | undefined;    billingAddress?: {        firstName: string;        lastName: string;        street: string;        city: string;        postalCode: string;        region?: string | undefined;        country?: string | undefined;        phone?: string | null | undefined;    } | undefined;}
 
 export type ShopBundleComponent = {    quantity: number;    component: {        id: string;        name: string;        slug: string;        price: number;    };}
 
@@ -159,25 +159,37 @@ export type ShopCartValidationItem = {    productId: string;    name: string;
 
 export type ShopCategory = {    id: string;    name: string;    slug: string;    description: string | null;    imageUrl: string | null;    parentId: string | null;    sortOrder: number;}
 
+/**
+ * @deprecated REB-834 — `POST /api/site/shop/check-email` no longer reveals
+ * whether an account exists. Do not call it; removed in the next major.
+ */
 export type ShopCheckEmailInput = {    email: string;}
 
-export type ShopCheckoutInput = {    items: {        productId: string;        quantity: number;        variantId?: string | null | undefined;    }[];    customerEmail: string;    customerName: string;    successUrl: string;    cancelUrl: string;    customerPhone?: string | null | undefined;    discountCode?: string | undefined;    shippingAddress?: {        firstName: string;        lastName: string;        street: string;        city: string;        postalCode: string;        region?: string | undefined;        country?: string | undefined;        phone?: string | null | undefined;    } | undefined;    billing?: {        billingName: string;        billingNif?: string | undefined;        billingEmail?: string | undefined;        billingAddress?: {            firstName: string;            lastName: string;            street: string;            city: string;            postalCode: string;            region?: string | undefined;            country?: string | undefined;            phone?: string | null | undefined;        } | undefined;    } | undefined;}
+export type ShopCheckoutInput = {    items: {        productId: string;        quantity: number;        variantId?: string | null | undefined;    }[];    customerEmail: string;    customerName: string;    successUrl: string;    cancelUrl: string;    customerPhone?: string | null | undefined;    discountCode?: string | undefined;    shippingAddress?: {        firstName: string;        lastName: string;        street: string;        city: string;        postalCode: string;        region?: string | undefined;        country?: string | undefined;        phone?: string | null | undefined;    } | undefined;    billing?: {        billingName: string;        billingNif?: string | undefined;        billingIdType?: "NIF" | "02" | "03" | "04" | "05" | "06" | undefined;        billingIdCountry?: string | undefined;        billingEmail?: string | undefined;        billingAddress?: {            firstName: string;            lastName: string;            street: string;            city: string;            postalCode: string;            region?: string | undefined;            country?: string | undefined;            phone?: string | null | undefined;        } | undefined;    } | undefined;    wantsFullInvoice?: boolean | undefined;}
 
 export type ShopCheckoutSession = {    url: string;    sessionId: string;}
 
-export type ShopConfig = {    shopName: string | null;    defaultLowStockThreshold: number;    currencyCode: string;    stripePublishableKey: string | null;    stripeTestPublishableKey: string | null;    stripeTestMode: boolean;    shippingEnabled: boolean;    pickupEnabled: boolean;    taxEnabled: boolean;    taxIncludedInPrice: boolean;    productTrustItems?: {        [x: string]: unknown;        icon: (string & {}) | "shipping" | "returns" | "secure-payment" | "support" | "gift" | "pickup" | "warranty" | "quality";        text: string;    }[] | null | undefined;}
+export type ShopConfig = {    shopName: string | null;    defaultLowStockThreshold: number;    currencyCode: string;    stripePublishableKey: string | null;    stripeTestPublishableKey: string | null;    stripeTestMode: boolean;    shippingEnabled: boolean;    pickupEnabled: boolean;    taxEnabled: boolean;    taxIncludedInPrice: boolean;    simplifiedInvoiceCapCents?: number | null | undefined;    productTrustItems?: {        [x: string]: unknown;        icon: (string & {}) | "shipping" | "returns" | "secure-payment" | "support" | "gift" | "pickup" | "warranty" | "quality";        text: string;    }[] | null | undefined;}
 
 export type ShopDiscountApplication = {    valid: boolean;    discount: number;    type: "PERCENTAGE" | "FIXED" | null;    code: string | null;    error?: string | undefined;}
 
+/**
+ * @deprecated REB-834 — `exists` is always `false`. Never branch UI on it:
+ * the checkout always offers «Iniciar sesión o continuar como invitado» and
+ * the server links the order to an existing account after payment. Removed
+ * in the next major.
+ */
 export type ShopEmailCheck = {    exists: boolean;}
 
-export type ShopErrorCode = "STOCK_CHANGED" | "PRICE_CHANGED" | "PRODUCT_UNAVAILABLE" | "DISCOUNT_INVALID" | "SHIPPING_UNAVAILABLE" | "INVALID_INPUT" | "STORE_DISABLED" | "PAYMENT_PROVIDER_ERROR" | "INTERNAL_ERROR"
+export type ShopErrorCode = "STOCK_CHANGED" | "PRICE_CHANGED" | "PRODUCT_UNAVAILABLE" | "DISCOUNT_INVALID" | "SHIPPING_UNAVAILABLE" | "INVALID_INPUT" | "STORE_DISABLED" | "PAYMENT_PROVIDER_ERROR" | "INTERNAL_ERROR" | "BILLING_DATA_REQUIRED" | "INVOICING_NOT_READY" | "FULL_INVOICE_UNAVAILABLE"
 
 export type ShopFacets = {    taxonomies: {        key: string;        label: string;        showAsBadge: boolean;        selectionMode: "single" | "multiple";        terms: {            slug: string;            name: string;            count: number;        }[];    }[];    attributes: {        key: string;        label: string;        valueType: "boolean" | "text" | "select" | "multiselect";        options: {            value: string;            label: string;            count: number;        }[];    }[];    price: {        min: number;        max: number;    };    onSale: {        count: number;    };}
 
 export type ShopInventoryRef = {    stockQuantity: number;    reservedQuantity: number;    lowStockThreshold: number | null;}
 
-export type ShopOrder = {    id: string;    orderNumber: string;    status: "PENDING" | "CONFIRMED" | "PROCESSING" | "SHIPPED" | "DELIVERED" | "CANCELLED" | "REFUNDED";    paymentStatus: "PENDING" | "REFUNDED" | "PAID" | "FAILED" | "PARTIALLY_REFUNDED";    customerEmail: string;    total: number;    items: {        product: {            id: string;            name: string;            slug: string;        };        quantity: number;        unitPrice: number;        total: number;        variant?: {            id: string;            name: string;        } | null | undefined;    }[];}
+export type ShopOrder = {    id: string;    orderNumber: string;    status: "PENDING" | "CONFIRMED" | "PROCESSING" | "SHIPPED" | "DELIVERED" | "CANCELLED" | "REFUNDED";    paymentStatus: "PENDING" | "REFUNDED" | "PAID" | "FAILED" | "PARTIALLY_REFUNDED";    customerEmail: string;    total: number;    items: {        product: {            id: string;            name: string;            slug: string;        };        quantity: number;        unitPrice: number;        total: number;        variant?: {            id: string;            name: string;        } | null | undefined;    }[];    invoice?: {        number: string;        url: string;    } | null | undefined;}
+
+export type ShopOrderInvoice = {    number: string;    url: string;}
 
 export type ShopOrderItem = {    product: {        id: string;        name: string;        slug: string;    };    quantity: number;    unitPrice: number;    total: number;    variant?: {        id: string;        name: string;    } | null | undefined;}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reblu/site-contracts",
-  "version": "1.13.0",
+  "version": "1.15.0",
   "private": false,
   "description": "Public, dependency-free TypeScript types for the Reblu SITE API (types only — no Zod, no Prisma at runtime).",
   "license": "Apache-2.0",