@bacano/sdk 1.0.1 → 1.1.8

package/types.d.ts

@@ -1,8 +1,14 @@
+import type { WebsiteAdvertisingConsent, WebsiteMarketingAttribution } from "./marketing/types";
 export interface BacanoClientConfig {
     /** Bacano public API URL (e.g., https://api.bacanoerp.com) */
     apiUrl: string;
     /** Website slug — required tenant context for every storefront request. */
     websiteSlug: string;
+    /**
+     * Browser-safe website context already returned by `public-config`.
+     * Passing it avoids resolving the same website again through GraphQL.
+     */
+    initialContext?: BacanoClientContext;
     /** Cart session storage strategy (default: 'localStorage') */
     tokenStorage?: "localStorage" | "cookie" | "memory";
     /**
@@ -18,12 +24,163 @@ export type AccessTokenProvider = () => string | null | Promise<string | null>;
 export interface WebsitePublicConfig {
     websiteId: string;
     companyId: string;
+    /** Versioned marker for the website context embedded in public-config. */
+    contextSchemaVersion?: 1 | null;
+    chainId?: string | null;
     slug: string;
     name: string;
     domain: string | null;
+    config?: Record<string, unknown> | null;
     buyerAccountsEnabled: boolean;
     clerkPublishableKey: string | null;
     customerIdentification: WebsiteCustomerIdentificationPolicy;
+    marketing: WebsiteMarketingPublicConfig;
+    /**
+     * Optional on caller-constructed configs. `getWebsitePublicConfig()` always
+     * resolves this block, including a safe empty fallback.
+     */
+    branding?: WebsiteBrandingPublicConfig;
+    /**
+     * Optional on caller-constructed configs for compatibility with SDK 1.0.10.
+     * `getWebsitePublicConfig()` always returns this block.
+     */
+    legal?: WebsiteLegalPublicConfig;
+    /**
+     * Optional on caller-constructed configs. `getWebsitePublicConfig()` always
+     * resolves this block, including a safe disabled fallback.
+     */
+    construction?: WebsiteConstructionPublicConfig;
+    /** Public thresholds for displaying quantity-pricing guidance. */
+    volumePricing?: WebsiteVolumePricingPublicConfig;
+}
+export interface WebsiteVolumePricingPublicConfig {
+    schemaVersion: 1;
+    enabled: boolean;
+    tiers: Array<{
+        priceType: "WHOLESALE" | "WHOLESALE_2";
+        minQuantity: number;
+    }>;
+}
+export interface WebsiteBrandingMedia {
+    fileId: string;
+    name: string | null;
+    altText: string | null;
+    width: number | null;
+    height: number | null;
+    originalUrl: string;
+}
+export interface WebsiteBrandingPublicConfig {
+    schemaVersion: 1;
+    favicon: WebsiteBrandingMedia | null;
+}
+export interface WebsiteConstructionMedia {
+    fileId: string;
+    name: string | null;
+    altText: string | null;
+    width: number | null;
+    height: number | null;
+    originalUrl: string;
+    heroUrl: string;
+    responsiveSources: Array<{
+        width: number;
+        url: string;
+    }>;
+}
+export interface WebsiteConstructionPublicConfig {
+    schemaVersion: 1;
+    enabled: boolean;
+    /** True only on the canonical production domain without a valid preview. */
+    enforced: boolean;
+    previewAccessGranted: boolean;
+    title: string | null;
+    message: string | null;
+    desktopImage: WebsiteConstructionMedia | null;
+    mobileImage: WebsiteConstructionMedia | null;
+}
+export interface WebsiteLegalPublicConfig {
+    schemaVersion: 1;
+    version: number;
+    contentHash: string | null;
+    documents: {
+        terms: Record<string, unknown> | null;
+        /** Present in public-config from SDK 1.0.12; optional for older fixtures. */
+        shipping?: Record<string, unknown> | null;
+        /** Present in public-config from SDK 1.0.12; optional for older fixtures. */
+        returns?: Record<string, unknown> | null;
+        privacy: Record<string, unknown> | null;
+        cookies: Record<string, unknown> | null;
+    };
+    inquiriesChannel: string | null;
+    directMarketingConsent: {
+        version: number;
+        statement: string;
+        statementHash: string;
+    } | null;
+    cookieNotice: {
+        enabled: boolean;
+        message: string;
+        buttonLabel: string;
+    };
+}
+export type WebsiteCampaignCaptureSource = "WEBSITE" | "QR";
+export interface WebsiteCampaignCaptureContact {
+    partyKind?: "PERSON" | "COMPANY";
+    firstName?: string | null;
+    lastName?: string | null;
+    legalName?: string | null;
+    commercialName?: string | null;
+    email?: string | null;
+    phone?: string | null;
+}
+export interface WebsiteCampaignCaptureInput {
+    /** Stable public key configured for the campaign in Bacano. */
+    campaignKey: string;
+    /** Stable per-submission key. Reusing it is safe and does not duplicate data. */
+    idempotencyKey: string;
+    /** Use QR only when the current form was reached through a QR entry point. */
+    source?: WebsiteCampaignCaptureSource;
+    /** Must reflect an explicit acceptance of the website's current statement. */
+    commercialConsent: true;
+    contact: WebsiteCampaignCaptureContact;
+    /** Storefront-defined answers. Bacano stores these as an immutable snapshot. */
+    answers?: Record<string, unknown>;
+}
+export interface WebsiteCampaignCaptureResult {
+    accepted: boolean;
+    message: string;
+}
+export type ResolvedWebsitePublicConfig = WebsitePublicConfig & {
+    branding: WebsiteBrandingPublicConfig;
+    legal: WebsiteLegalPublicConfig;
+    construction: WebsiteConstructionPublicConfig;
+    volumePricing: WebsiteVolumePricingPublicConfig;
+};
+export interface WebsiteMarketingPublicConfig {
+    schemaVersion: 1;
+    enabled: boolean;
+    currencyCode: string;
+    timeZone: string;
+    attributionWindowDays: number;
+    consentPolicy: {
+        id: string;
+        version: number;
+        statement: string;
+        statementHash: string;
+    } | null;
+    destinations: {
+        ga4: {
+            measurementId: string;
+            diagnosticMode: boolean;
+        } | null;
+        meta: {
+            pixelId: string;
+            diagnosticMode: boolean;
+        } | null;
+        /** Browser-only Microsoft Clarity destination; absent in SDK <= 1.0.14. */
+        clarity?: {
+            projectId: string;
+        } | null;
+    };
 }
 export type WebsiteCustomerIdentifierType = "AUTO" | "EMAIL" | "PHONE" | "DOCUMENT";
 export interface WebsiteCustomerDocumentType {
@@ -49,6 +206,11 @@ export interface GetWebsitePublicConfigOptions {
      * header automatically and should omit this option.
      */
     origin?: string;
+    /**
+     * Short-lived signed token generated by Bacano. Storefronts should normally
+     * let `BacanoWebsiteGate` discover and manage it automatically.
+     */
+    previewToken?: string;
 }
 export interface BacanoClientContext {
     websiteId: string;
@@ -79,11 +241,68 @@ export interface Product {
     createdAt: string;
     updatedAt: string;
     variants: ProductVariant[];
+    /**
+     * Variants visible on a product detail page. Unlike `variants`, this list
+     * also preserves enabled public-price variants that are currently sold out.
+     */
+    detailVariants?: ProductVariant[];
     media: ProductMedia[];
     attributes: ProductAttribute[];
     relatedProducts: ProductRelatedProduct[];
+    optionGroup: ProductOptionGroup | null;
+    /** Public, non-empty technical specification resolved by Bacano. */
+    specification: ProductSpecification | null;
+}
+export interface ProductSpecification {
+    contentTypeId: string;
+    key: string;
+    name: string;
+    sections: ProductSpecificationSection[];
+}
+export interface ProductSpecificationSection {
+    id: string | null;
+    key: string;
+    title: string;
+    description: string | null;
+    sortOrder: number;
+    fields: ProductSpecificationField[];
+}
+export interface ProductSpecificationField {
+    id: string;
+    key: string;
+    label: string;
+    type: "text" | "number" | "measure" | "boolean" | "date" | "select" | "component";
+    sortOrder: number;
+    value: string | number | boolean | ProductSpecificationOption | ProductSpecificationOption[] | ProductSpecificationMeasure | ProductSpecificationField[];
+}
+export interface ProductSpecificationOption {
+    id: string;
+    key: string;
+    label: string;
+}
+export interface ProductSpecificationMeasure {
+    value: number;
+    unit: {
+        code: string;
+        symbol: string;
+        name: string;
+    };
 }
 export interface ProductRelatedProduct {
+    id: string;
+    productId: string;
+    slug: string | null;
+    name: string;
+    sku: string | null;
+    sortOrder: number;
+    media: ProductMedia[];
+}
+export interface ProductOptionGroup {
+    id: string;
+    title: string | null;
+    members: ProductOptionGroupMember[];
+}
+export interface ProductOptionGroupMember {
     id: string;
     productId: string;
     slug: string | null;
@@ -138,6 +357,11 @@ export interface ProductMedia {
     thumbnailUrl: string;
     cardUrl: string;
     detailUrl: string;
+    /** Width-labelled WebP candidates for responsive storefront images. */
+    responsiveSources?: Array<{
+        width: number;
+        url: string;
+    }>;
     mediaKind: ProductMediaKind;
     mimeType: string | null;
     fileName: string | null;
@@ -300,6 +524,16 @@ export interface ProductAvailability {
     productVariantId: string;
     inStock: boolean;
     label: string;
+    /** Current public purchase limit, net of active stock reservations. */
+    maxPurchasableQuantity: number;
+}
+export interface ProductVariantLiveState {
+    productVariantId: string;
+    inStock: boolean;
+    availabilityLabel: string;
+    /** Current public purchase limit, net of active stock reservations. */
+    maxPurchasableQuantity: number;
+    pricing: ProductVariantPricing;
 }
 export type ProductSortBy = "name_asc" | "name_desc" | "price_asc" | "price_desc" | "newest";
 export interface GetProductsOptions {
@@ -356,6 +590,40 @@ export interface ProductFilters {
     };
     /** Category-specific dynamic attributes — populated when categoryName is provided */
     attributes: AttributeFilter[];
+    /** Public technical facets derived from Bacano's typed index. */
+    technical: ProductSpecificationFacet[];
+}
+export interface ProductSpecificationFacet {
+    fieldId: string;
+    fieldPath: string;
+    key: string;
+    label: string;
+    type: "number" | "measure" | "boolean" | "date" | "select";
+    sectionKey: string | null;
+    unitCode: string | null;
+    min: number | null;
+    max: number | null;
+    dateFrom: string | null;
+    dateTo: string | null;
+    booleanValues: Array<{
+        value: boolean;
+        count: number;
+    }>;
+    options: Array<{
+        id: string;
+        key: string;
+        label: string;
+        count: number;
+        sortOrder: number;
+    }>;
+}
+export interface ProductSpecificationFilterSelection {
+    optionIds?: string[];
+    booleanValues?: boolean[];
+    min?: number;
+    max?: number;
+    dateFrom?: string;
+    dateTo?: string;
 }
 export interface GetProductFiltersOptions {
     /** When set, includes category-specific attribute facets */
@@ -370,6 +638,8 @@ export interface GetProductFiltersOptions {
 }
 export interface CatalogPageIncludeOptions {
     products?: boolean;
+    /** Include sold-out public variants for statically generated detail pages. */
+    detailVariants?: boolean;
     categories?: boolean;
     attributes?: boolean;
     filters?: boolean;
@@ -387,6 +657,8 @@ export interface GetCatalogPageOptions {
     minPrice?: number;
     maxPrice?: number;
     attributesBySlug?: Record<string, string[]>;
+    /** Technical filters keyed by the stable field ID exposed in facets. */
+    technicalByField?: Record<string, ProductSpecificationFilterSelection>;
     sortBy?: ProductSortBy;
     limit?: number;
     offset?: number;
@@ -443,6 +715,38 @@ export interface CatalogPageResult {
     appliedFilters: Record<string, unknown>;
     debug: CatalogPageDebug | null;
 }
+export interface GetStaticCatalogSnapshotOptions {
+    categoryListKey: string;
+    attributeListKey: string;
+    /** Products fetched per gateway request. Defaults to the server maximum. */
+    pageSize?: number;
+    /** Safety ceiling for a single build. Defaults to 10,000 products. */
+    maxProducts?: number;
+}
+export interface GetStaticCatalogBootstrapOptions extends GetStaticCatalogSnapshotOptions {
+    /** Products exposed in the initial static catalog page. Defaults to 24. */
+    initialPageSize?: number;
+    /** Stable order used by both the snapshot and its initial page. */
+    sortBy?: ProductSortBy;
+}
+export interface StaticCatalogSnapshot {
+    schemaVersion: 1;
+    snapshotId: string;
+    generatedAt: string;
+    websiteId: string;
+    products: Product[];
+    total: number;
+    pageSize: number;
+    pageCount: number;
+}
+/**
+ * Complete build snapshot plus the first renderable catalog page and facets.
+ * This avoids a second catalog request while statically generating a store.
+ */
+export interface StaticCatalogBootstrap extends StaticCatalogSnapshot {
+    bootstrapSchemaVersion: 1;
+    initialPage: CatalogPageResult;
+}
 export type ProductRecommendationSource = "manual" | "subcategory" | "category" | "attributes" | "fallback";
 export interface ProductRecommendationPricing {
     currentPriceMin: number;
@@ -482,6 +786,18 @@ export interface ContentMedia {
     thumbnailUrl?: string | null;
     cardUrl?: string | null;
     detailUrl?: string | null;
+    /** Optimized full-width editorial source, capped at the original width. */
+    heroUrl?: string | null;
+    /** Width-labelled WebP candidates for responsive storefront images. */
+    responsiveSources?: Array<{
+        width: number;
+        url: string;
+    }>;
+    /** Intrinsic dimensions of the original image when available. */
+    originalWidth?: number | null;
+    originalHeight?: number | null;
+    /** @deprecated Use originalUrl/cardUrl/detailUrl/heroUrl for the rendering context. */
+    src?: string | null;
     /** @deprecated Use originalUrl/cardUrl/detailUrl based on the rendering context. */
     url?: string | null;
 }
@@ -594,11 +910,30 @@ export interface Cart {
     status: string;
     createdAt: string;
     updatedAt: string;
+    volumePricing: CartVolumePricing;
+}
+export interface CartVolumePricing {
+    enabled: boolean;
+    eligibleQuantity: number;
+    appliedPriceType: "WHOLESALE" | "WHOLESALE_2" | null;
+    appliedMinQuantity: number | null;
+    nextPriceType: "WHOLESALE" | "WHOLESALE_2" | null;
+    nextMinQuantity: number | null;
+    remainingQuantity: number | null;
+    totalSavings?: number;
 }
 export interface CartItem {
     id: string;
     productVariantId: string;
     quantity: number;
+    unitPrice: number | null;
+    lineTotal: number | null;
+    baseUnitPrice?: number | null;
+    unitSavings?: number;
+    lineSavings?: number;
+    volumePricingEligible?: boolean;
+    resolvedPriceType: ProductPriceType | null;
+    volumePricingMinQuantity: number | null;
     productVariant: {
         sku: string;
         product: {
@@ -628,6 +963,7 @@ export interface StartGuestCheckoutInput {
     contact: WebsiteGuestContact;
     items: WebsiteCheckoutItem[];
     fulfillmentFamily?: WebsiteFulfillmentFamily;
+    marketingAttribution?: WebsiteMarketingAttribution;
 }
 export interface CheckoutSubmission {
     contact: WebsiteGuestContact;
@@ -636,6 +972,8 @@ export interface CheckoutSubmission {
     shippingQuoteId?: string;
     paymentMode?: WebsitePaymentMode;
     paymentMethodId?: string;
+    marketingAttribution?: WebsiteMarketingAttribution;
+    advertisingConsent?: WebsiteAdvertisingConsent;
     /**
      * Request an account activation email after Bacano creates a valid guest order.
      * Delivery does not depend on the order being paid.