@bacano/sdk 1.1.15 → 1.1.17

package/README.md

@@ -112,6 +112,12 @@ Commercial forms and newsletter subscriptions must follow
 Bacano owns consent evidence, identity resolution, attribution and idempotent
 lead capture through the SDK.
 
+Website forms defined and published from Bacano use the additive contract in
+[`STOREFRONT_FORMS.md`](./STOREFRONT_FORMS.md). Storefronts can mount the
+official `BacanoForm` renderer or consume the same typed definition through
+`useBacanoForm()` without GraphQL, HTML stored in the database or a rebuild
+after each publication.
+
 Static and hybrid stores must also follow
 [`STOREFRONT_PERFORMANCE.md`](./STOREFRONT_PERFORMANCE.md). It defines the
 official build bootstrap, live-state refresh, responsive media and request

package/STOREFRONT_FORMS.md

@@ -0,0 +1,147 @@
+# Formularios de websites
+
+Los formularios públicos de Bacano son definiciones tipadas y versionadas. El
+storefront decide dónde se muestran y cómo lucen; Bacano controla su estructura,
+estado y validaciones. La definición nunca contiene HTML ni JavaScript arbitrario.
+
+## Renderer oficial para React
+
+Monta un único `BacanoProvider` global y usa la key pública configurada en el ERP:
+
+```tsx
+import { BacanoForm } from "@bacano/sdk/react/forms";
+
+export function ContactForm() {
+  return (
+    <BacanoForm
+      formKey="contacto"
+      classNames={{ root: "contact-form", field: "contact-field" }}
+    />
+  );
+}
+```
+
+`BacanoForm` soporta campos directos, secciones visuales y pasos reales,
+validación nativa, opciones manuales, Listas de Content y el envío oficial de
+respuestas. Si se
+omite `onSubmit`, utiliza el mismo `BacanoClient` global, genera una clave
+idempotente estable y llama `client.forms.submitResponse(...)`. Un formulario
+pausado muestra su mensaje de indisponibilidad y deja de operar sin reconstruir
+el storefront.
+
+## Estructura del formulario
+
+La definición tiene tres niveles explícitos:
+
+- `fields`: campos directos de un formulario continuo.
+- `sections`: agrupaciones visuales opcionales dentro del formulario continuo.
+- `steps`: etapas reales de un formulario multipaso. Cada paso puede contener
+  campos directos y secciones.
+
+Un formulario continuo puede tener campos, secciones o ambos. Cuando existen
+pasos, `fields` y `sections` de la raíz deben estar vacíos: todo el contenido
+pertenece a un paso. Las secciones no crean navegación ni cambian el envío; los
+pasos sí muestran avance y controles para continuar o regresar. Un formulario
+también puede existir sin secciones ni pasos, usando únicamente campos directos.
+
+`onSubmit` permanece disponible para experiencias personalizadas. No debe
+usarse para llamar GraphQL, endpoints internos ni crear una persistencia
+paralela.
+
+## Renderer personalizado
+
+```tsx
+import { useBacanoState } from "@bacano/sdk/react";
+import { useBacanoForm } from "@bacano/sdk/react/forms";
+
+export function BrandedContactForm() {
+  const { client } = useBacanoState();
+  const { form, loading, error, refresh } = useBacanoForm("contacto");
+
+  if (loading || !client) return null;
+  if (error || !form) return <p>Formulario no disponible.</p>;
+  if (form.status === "PAUSED") {
+    return <p>{form.definition.unavailableMessage}</p>;
+  }
+
+  const submit = async (values: Record<string, string | string[] | boolean>) =>
+    client.forms.submitResponse({
+      formKey: form.key,
+      formVersion: form.version,
+      definitionHash: form.definitionHash,
+      idempotencyKey: crypto.randomUUID(),
+      values,
+    });
+
+  return <CustomRenderer definition={form.definition} onSubmit={submit} />;
+}
+```
+
+El renderer personalizado puede cambiar componentes y estilos, pero debe usar
+los campos, keys, opciones y validaciones entregados por el SDK. No debe crear
+un segundo cliente, resolver el website nuevamente ni usar GraphQL directo.
+
+## Next.js y Static First
+
+Obtén la definición durante el build o desde un Server Component usando el
+mismo cliente configurado para el website. Después entrégala al renderer como
+`initialForm`:
+
+```tsx
+const initialForm = await bacano.forms.getDefinition("contacto");
+
+return (
+  <BacanoForm
+    formKey="contacto"
+    initialForm={initialForm}
+  />
+);
+```
+
+Así, el HTML inicial contiene el formulario aunque JavaScript todavía no haya
+hidratado. El provider global reutiliza esa definición y la revalida en runtime
+para reflejar una publicación o pausa sin rebuild. No ocultes el formulario
+estático detrás de un `loadingFallback` global ni crees otro `BacanoClient` para
+consultarlo.
+
+## Contrato operativo
+
+- `DRAFT`: no es público.
+- `ACTIVE`: entrega la última versión publicada.
+- `PAUSED`: conserva definición y mensaje, pero no acepta nuevos envíos.
+- `ARCHIVED`: deja de ser público y conserva auditoría.
+- Publicar crea una versión inmutable; editar modifica únicamente el borrador.
+- Los cambios publicados se revalidan en runtime y no requieren rebuild.
+- La revalidación usa caché corta y ETag; una falla temporal no elimina una
+  definición válida que ya fue generada estáticamente.
+- Una Lista de Content se resuelve en Bacano. El storefront recibe opciones
+  públicas listas para renderizar.
+- Cada envío incluye la versión y huella exactas de la definición publicada.
+  Una página desactualizada recibe `FORM_VERSION_MISMATCH` y debe refrescar.
+- `idempotencyKey` identifica un intento lógico. Repetir la misma clave y el
+  mismo contenido devuelve la respuesta existente; reutilizarla con otro
+  contenido se rechaza.
+- Bacano deriva empresa y website desde `websiteSlug`; el storefront no envía
+  identificadores internos ni controla el tenant.
+- La API vuelve a validar tipos, requeridos, rangos y opciones de listas. La
+  validación del navegador mejora la experiencia, pero no es autoritativa.
+- URL, referidor y atribución se sanean. Las respuestas y datos personales no
+  se escriben en logs.
+- Una falla futura de correo, CRM o automatización no revierte la respuesta.
+- `CAPTURE_LEAD` se procesa en una fase posterior. Toda respuesta se conserva
+  primero y de forma independiente.
+
+## Checklist mínimo del storefront
+
+- Usar un solo `BacanoProvider` y el cliente global ya inicializado.
+- Renderizar con `BacanoForm` o con `useBacanoForm`; nunca copiar la definición
+  a un esquema local ni consultar GraphQL directamente.
+- Entregar `initialForm` cuando la página se genera de forma estática.
+- Respetar `ACTIVE`, `PAUSED`, versión y `definitionHash` sin inferir estados.
+- Mantener una `idempotencyKey` estable durante los reintentos del mismo envío.
+- Probar formulario activo, pausado, inexistente, versión desactualizada,
+  reintento idempotente y error de red.
+- Confirmar en Bacano que una respuesta real quedó persistida antes de aprobar
+  el flujo; no basta con mostrar el mensaje de éxito del navegador.
+- No prometer correo, lead, solicitud o automatización mientras la capacidad no
+  esté implementada y activa en Bacano.

package/client.d.ts

@@ -1,4 +1,4 @@
-import type { BacanoClientConfig, BacanoClientContext, Brand, Cart, CartItem, CatalogAttributeList, CatalogCategoryList, CatalogPageResult, CheckoutResult, CheckoutSubmission, ContentEntry, CustomerAddress, CustomerProfile, CustomerProfileUpdate, GetAttributeListOptions, GetCatalogPageOptions, GetCategoryListOptions, GetContentOptions, GetOrdersOptions, GetProductFiltersOptions, GetProductRecommendationsOptions, GetProductSeoEntriesOptions, GetProductsOptions, GetSearchSuggestionsOptions, GetStaticCatalogBootstrapOptions, GetStaticCatalogSnapshotOptions, Order, Product, ProductAvailability, ProductCategory, ProductContentBlock, ProductFilters, ProductRecommendationsResult, ProductSeoEntriesResult, ProductVariantLiveState, PublicOrder, PublicOrderLookupInput, SearchSuggestion, StartGuestCheckoutInput, StaticCatalogBootstrap, StaticCatalogSnapshot, WaitForPublicOrderPaymentInput, WebsiteCampaignCaptureInput, WebsiteCampaignCaptureResult, WebsiteCheckoutAddress, WebsiteCheckoutItem, WebsiteCouponActionResult, WebsiteDeliveryOption, WebsiteFreeShippingProgress, WebsiteFulfillmentFamily, WebsiteGuestContact, WebsiteLocationOptions, WebsitePaymentMethod, WebsitePaymentOption, WebsitePaymentSessionResult, WebsiteShippingPolicy, WebsiteShippingQuote } from "./types";
+import type { BacanoClientConfig, BacanoClientContext, Brand, Cart, CartItem, CatalogAttributeList, CatalogCategoryList, CatalogPageResult, CheckoutResult, CheckoutSubmission, ContentEntry, CustomerAddress, CustomerProfile, CustomerProfileUpdate, GetAttributeListOptions, GetCatalogPageOptions, GetCategoryListOptions, GetContentOptions, GetOrdersOptions, GetProductFiltersOptions, GetProductRecommendationsOptions, GetProductSeoEntriesOptions, GetProductsOptions, GetSearchSuggestionsOptions, GetStaticCatalogBootstrapOptions, GetStaticCatalogSnapshotOptions, Order, Product, ProductAvailability, ProductCategory, ProductContentBlock, ProductFilters, ProductRecommendationsResult, ProductSeoEntriesResult, ProductVariantLiveState, PublicOrder, PublicOrderLookupInput, SearchSuggestion, StartGuestCheckoutInput, StaticCatalogBootstrap, StaticCatalogSnapshot, WaitForPublicOrderPaymentInput, WebsiteCampaignCaptureInput, WebsiteCampaignCaptureResult, WebsiteCheckoutAddress, WebsiteCheckoutItem, WebsiteCouponActionResult, WebsiteDeliveryOption, WebsiteFormResponseInput, WebsiteFormResponseResult, WebsiteFreeShippingProgress, WebsiteFulfillmentFamily, WebsiteGuestContact, WebsiteLocationOptions, WebsitePaymentMethod, WebsitePaymentOption, WebsitePaymentSessionResult, WebsitePublishedForm, WebsiteShippingPolicy, WebsiteShippingQuote } from "./types";
 export interface BacanoClient {
     /** Initialize the client and resolve its website context. */
     init(): Promise<void>;
@@ -34,6 +34,13 @@ export interface BacanoClient {
         getByTag(tag: string, opts?: GetContentOptions): Promise<ContentEntry[]>;
         getForProduct(productId: string, opts?: GetContentOptions): Promise<ProductContentBlock[]>;
     };
+    forms: {
+        /** Returns the current published definition or null when it is unavailable. */
+        getDefinition(formKey: string, options?: {
+            force?: boolean;
+        }): Promise<WebsitePublishedForm | null>;
+        submitResponse(input: WebsiteFormResponseInput): Promise<WebsiteFormResponseResult>;
+    };
     cart: {
         getOrCreate(contact?: WebsiteGuestContact, fulfillmentFamily?: WebsiteFulfillmentFamily): Promise<Cart>;
         startCheckout(input: StartGuestCheckoutInput): Promise<Cart>;

package/index.cjs

@@ -66,10 +66,10 @@ var WebsiteError = class extends Error {
   }
 };
 var RateLimitError = class extends WebsiteError {
-  constructor(message, retryAfterSeconds) {
+  constructor(message, retryAfterSeconds2) {
     super(message, "RATE_LIMITED", {
       status: 429,
-      retryAfterSeconds
+      retryAfterSeconds: retryAfterSeconds2
     });
     this.name = "RateLimitError";
   }
@@ -6115,6 +6115,171 @@ function createWebsiteMarketingRuntime(options) {
   };
 }
 
+// libs/sdk/src/modules/forms.ts
+function retryAfterSeconds(response) {
+  const value = Number(response.headers.get("Retry-After") ?? "1");
+  return Number.isFinite(value) && value >= 0 ? Math.ceil(value) : 1;
+}
+function isFormKey(value) {
+  return /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value);
+}
+function createFormsModule(apiUrl, websiteSlug, getContext) {
+  const cache = /* @__PURE__ */ new Map();
+  function getServerOrigin() {
+    if (typeof window !== "undefined") return null;
+    const domain = getContext().domain?.trim();
+    if (!domain) return null;
+    try {
+      return new URL(domain.includes("://") ? domain : `https://${domain}`).origin;
+    } catch {
+      return null;
+    }
+  }
+  return {
+    async getDefinition(formKey, options) {
+      const normalizedKey = formKey.trim();
+      if (!isFormKey(normalizedKey)) {
+        throw new WebsiteError(
+          "formKey has an invalid format",
+          "INVALID_FORM_KEY"
+        );
+      }
+      const cached = cache.get(normalizedKey);
+      if (!options?.force && cached && cached.expiresAt > Date.now()) {
+        return cached.value;
+      }
+      const url = new URL(
+        `${apiUrl.replace(/\/+$/, "")}/api/v1/website/forms/definition`
+      );
+      url.searchParams.set("websiteSlug", websiteSlug);
+      url.searchParams.set("formKey", normalizedKey);
+      let response;
+      try {
+        const serverOrigin = getServerOrigin();
+        const headers = new Headers();
+        if (serverOrigin) headers.set("Origin", serverOrigin);
+        if (cached?.etag) headers.set("If-None-Match", cached.etag);
+        response = await fetch(url, {
+          ...serverOrigin || cached?.etag ? { headers } : {},
+          ...options?.force ? { cache: "no-cache" } : {}
+        });
+      } catch (error) {
+        throw new WebsiteError(
+          `Could not load the website form: ${error instanceof Error ? error.message : String(error)}`,
+          "NETWORK_ERROR"
+        );
+      }
+      if (response.status === 304 && cached) {
+        cache.set(normalizedKey, {
+          ...cached,
+          expiresAt: Date.now() + 3e4
+        });
+        return cached.value;
+      }
+      if (response.status === 404) {
+        cache.set(normalizedKey, {
+          etag: null,
+          expiresAt: Date.now() + 15e3,
+          value: null
+        });
+        return null;
+      }
+      if (response.status === 429) {
+        throw new RateLimitError(
+          "Rate limit exceeded. Please try again later.",
+          retryAfterSeconds(response)
+        );
+      }
+      if (!response.ok) {
+        throw new WebsiteError(
+          `Could not load the website form (status ${response.status})`,
+          response.status === 403 ? "ORIGIN_NOT_ALLOWED" : "FORM_DEFINITION_ERROR",
+          { status: response.status }
+        );
+      }
+      const value = await response.json();
+      if (value.schemaVersion !== 1 || value.key !== normalizedKey || !Array.isArray(value.definition?.fields) || !Array.isArray(value.definition?.sections) || !Array.isArray(value.definition?.steps)) {
+        throw new WebsiteError(
+          "Website form returned an invalid definition",
+          "INVALID_FORM_DEFINITION"
+        );
+      }
+      cache.set(normalizedKey, {
+        etag: response.headers.get("ETag"),
+        expiresAt: Date.now() + 3e4,
+        value
+      });
+      return value;
+    },
+    async submitResponse(input) {
+      const normalizedKey = input.formKey.trim();
+      if (!isFormKey(normalizedKey)) {
+        throw new WebsiteError(
+          "formKey has an invalid format",
+          "INVALID_FORM_KEY"
+        );
+      }
+      const context = getContext();
+      const attribution = getWebsiteMarketingAttribution(context.websiteId);
+      const pageUrl = typeof window !== "undefined" ? window.location.href : void 0;
+      const referrerUrl = typeof document !== "undefined" && document.referrer ? document.referrer : void 0;
+      let response;
+      try {
+        response = await fetch(
+          `${apiUrl.replace(/\/+$/, "")}/api/v1/website/forms/responses`,
+          {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+              websiteSlug,
+              formKey: normalizedKey,
+              formVersion: input.formVersion,
+              definitionHash: input.definitionHash,
+              idempotencyKey: input.idempotencyKey,
+              source: input.source ?? "WEBSITE",
+              values: input.values,
+              pageUrl,
+              referrerUrl,
+              attribution: attribution ? serializeWebsiteMarketingAttribution(attribution) : null,
+              honeypot: input.honeypot ?? ""
+            })
+          }
+        );
+      } catch (error) {
+        throw new WebsiteError(
+          `Could not submit the website form: ${error instanceof Error ? error.message : String(error)}`,
+          "NETWORK_ERROR"
+        );
+      }
+      if (response.status === 429) {
+        throw new RateLimitError(
+          "Rate limit exceeded. Please try again later.",
+          retryAfterSeconds(response)
+        );
+      }
+      const result = await response.json().catch(() => null);
+      if (!response.ok) {
+        throw new WebsiteError(
+          result?.message ?? `Could not submit the website form (status ${response.status})`,
+          result?.code ?? (response.status === 403 ? "ORIGIN_NOT_ALLOWED" : "FORM_RESPONSE_ERROR"),
+          { status: response.status }
+        );
+      }
+      if (typeof result?.accepted !== "boolean" || typeof result.message !== "string") {
+        throw new WebsiteError(
+          "Website form returned an invalid response",
+          "INVALID_RESPONSE"
+        );
+      }
+      return {
+        accepted: result.accepted,
+        responseId: typeof result.responseId === "string" ? result.responseId : null,
+        message: result.message
+      };
+    }
+  };
+}
+
 // libs/sdk/src/modules/marketing.ts
 function readRetryAfter(response) {
   const value = Number(response.headers.get("Retry-After") ?? "1");
@@ -6641,6 +6806,7 @@ function createBacanoClient(config) {
     config.websiteSlug,
     getContext
   );
+  const formsModule = createFormsModule(apiUrl, config.websiteSlug, getContext);
   return {
     async init() {
       if (context) return;
@@ -6693,6 +6859,10 @@ function createBacanoClient(config) {
       getByTag: contentModule.getByTag.bind(contentModule),
       getForProduct: contentModule.getForProduct.bind(contentModule)
     },
+    forms: {
+      getDefinition: formsModule.getDefinition.bind(formsModule),
+      submitResponse: formsModule.submitResponse.bind(formsModule)
+    },
     cart: {
       getOrCreate: cartModule.getOrCreate.bind(cartModule),
       startCheckout: cartModule.startCheckout.bind(cartModule),

package/index.d.ts

@@ -7,4 +7,4 @@ export type { MediaResponsiveSource, MediaResponsiveSourceOptions, MediaTransfor
 export { buildStorageContentMediaUrls, buildStorageFileUrl, buildStorageMediaUrls, buildStorageResponsiveSources, buildStorageTransformedFileUrl, formatMediaSrcSet, } from "./media";
 export { getWebsiteContextFromPublicConfig, getWebsitePublicConfig, } from "./modules/auth";
 export { getPrimaryProductImage, getProductDetailVariants, getProductImages, getProductMediaByKind, getProductMediaKind, getProductVideos, resolveProductPricing, } from "./modules/catalog";
-export type { AccessTokenProvider, AttributeFilter, BacanoClientConfig, BacanoClientContext, Brand, Cart, CartItem, CatalogAttributeList, CatalogAttributeListFilters, CatalogAttributeListItem, CatalogAttributeListValue, CatalogCategoryList, CatalogCategoryListItem, CatalogCategoryListItemSourceType, CheckoutResult, CheckoutSubmission, ContentEntry, ContentJson, ContentMedia, ContentTypeSummary, CustomerAddress, CustomerAddressType, CustomerProfile, CustomerProfileUpdate, GetAttributeListOptions, GetCategoryListOptions, GetContentOptions, GetOrdersOptions, GetProductFiltersOptions, GetProductSeoEntriesOptions, GetProductsOptions, GetSearchSuggestionsOptions, GetStaticCatalogBootstrapOptions, GetStaticCatalogSnapshotOptions, GetWebsitePublicConfigOptions, Order, OrderItem, Product, ProductAttribute, ProductAvailability, ProductCategory, ProductContentBlock, ProductFilters, ProductMedia, ProductMediaKind, ProductOptionGroup, ProductOptionGroupMember, ProductPrice, ProductPriceType, ProductRelatedProduct, ProductSeoEntriesResult, ProductSeoEntry, ProductSortBy, ProductSpecification, ProductSpecificationFacet, ProductSpecificationField, ProductSpecificationFilterSelection, ProductSpecificationMeasure, ProductSpecificationOption, ProductSpecificationSection, ProductSubcategory, ProductVariant, ProductVariantLiveState, ProductVariantPricing, PublicOrder, PublicOrderDeliverySummary, PublicOrderItem, PublicOrderLookupInput, PublicOrderPaymentSummary, ResolvedWebsitePublicConfig, SearchSuggestion, StartGuestCheckoutInput, StaticCatalogBootstrap, StaticCatalogSnapshot, VariantAttribute, WaitForPublicOrderPaymentInput, WebsiteBrandingMedia, WebsiteBrandingPublicConfig, WebsiteCampaignCaptureContact, WebsiteCampaignCaptureInput, WebsiteCampaignCaptureResult, WebsiteCampaignCaptureSource, WebsiteCheckoutAddress, WebsiteCheckoutItem, WebsiteCouponActionResult, WebsiteDeliveryOption, WebsiteDepartmentOption, WebsiteFreeShippingProgress, WebsiteFulfillmentFamily, WebsiteGuestContact, WebsiteLegalPublicConfig, WebsiteLocationOptions, WebsiteMunicipalityOption, WebsitePaymentMethod, WebsitePaymentMode, WebsitePaymentOption, WebsitePaymentOptionMethod, WebsitePaymentSessionResult, WebsitePickupInfo, WebsitePublicConfig, WebsiteShippingPolicy, WebsiteShippingQuote, } from "./types";
+export type { AccessTokenProvider, AttributeFilter, BacanoClientConfig, BacanoClientContext, Brand, Cart, CartItem, CatalogAttributeList, CatalogAttributeListFilters, CatalogAttributeListItem, CatalogAttributeListValue, CatalogCategoryList, CatalogCategoryListItem, CatalogCategoryListItemSourceType, CheckoutResult, CheckoutSubmission, ContentEntry, ContentJson, ContentMedia, ContentTypeSummary, CustomerAddress, CustomerAddressType, CustomerProfile, CustomerProfileUpdate, GetAttributeListOptions, GetCategoryListOptions, GetContentOptions, GetOrdersOptions, GetProductFiltersOptions, GetProductSeoEntriesOptions, GetProductsOptions, GetSearchSuggestionsOptions, GetStaticCatalogBootstrapOptions, GetStaticCatalogSnapshotOptions, GetWebsitePublicConfigOptions, Order, OrderItem, Product, ProductAttribute, ProductAvailability, ProductCategory, ProductContentBlock, ProductFilters, ProductMedia, ProductMediaKind, ProductOptionGroup, ProductOptionGroupMember, ProductPrice, ProductPriceType, ProductRelatedProduct, ProductSeoEntriesResult, ProductSeoEntry, ProductSortBy, ProductSpecification, ProductSpecificationFacet, ProductSpecificationField, ProductSpecificationFilterSelection, ProductSpecificationMeasure, ProductSpecificationOption, ProductSpecificationSection, ProductSubcategory, ProductVariant, ProductVariantLiveState, ProductVariantPricing, PublicOrder, PublicOrderDeliverySummary, PublicOrderItem, PublicOrderLookupInput, PublicOrderPaymentSummary, ResolvedWebsitePublicConfig, SearchSuggestion, StartGuestCheckoutInput, StaticCatalogBootstrap, StaticCatalogSnapshot, VariantAttribute, WaitForPublicOrderPaymentInput, WebsiteBrandingMedia, WebsiteBrandingPublicConfig, WebsiteCampaignCaptureContact, WebsiteCampaignCaptureInput, WebsiteCampaignCaptureResult, WebsiteCampaignCaptureSource, WebsiteCheckoutAddress, WebsiteCheckoutItem, WebsiteCouponActionResult, WebsiteDeliveryOption, WebsiteDepartmentOption, WebsiteFormAction, WebsiteFormDefinition, WebsiteFormField, WebsiteFormFieldType, WebsiteFormOption, WebsiteFormOptionSource, WebsiteFormResponseInput, WebsiteFormResponseResult, WebsiteFormResponseSource, WebsiteFormResponseValue, WebsiteFormSection, WebsiteFormStatus, WebsiteFormStep, WebsiteFreeShippingProgress, WebsiteFulfillmentFamily, WebsiteGuestContact, WebsiteLegalPublicConfig, WebsiteLocationOptions, WebsiteMunicipalityOption, WebsitePaymentMethod, WebsitePaymentMode, WebsitePaymentOption, WebsitePaymentOptionMethod, WebsitePaymentSessionResult, WebsitePickupInfo, WebsitePublicConfig, WebsitePublishedForm, WebsiteShippingPolicy, WebsiteShippingQuote, } from "./types";

package/index.js

@@ -12,10 +12,10 @@ var WebsiteError = class extends Error {
   }
 };
 var RateLimitError = class extends WebsiteError {
-  constructor(message, retryAfterSeconds) {
+  constructor(message, retryAfterSeconds2) {
     super(message, "RATE_LIMITED", {
       status: 429,
-      retryAfterSeconds
+      retryAfterSeconds: retryAfterSeconds2
     });
     this.name = "RateLimitError";
   }
@@ -6061,6 +6061,171 @@ function createWebsiteMarketingRuntime(options) {
   };
 }
 
+// libs/sdk/src/modules/forms.ts
+function retryAfterSeconds(response) {
+  const value = Number(response.headers.get("Retry-After") ?? "1");
+  return Number.isFinite(value) && value >= 0 ? Math.ceil(value) : 1;
+}
+function isFormKey(value) {
+  return /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value);
+}
+function createFormsModule(apiUrl, websiteSlug, getContext) {
+  const cache = /* @__PURE__ */ new Map();
+  function getServerOrigin() {
+    if (typeof window !== "undefined") return null;
+    const domain = getContext().domain?.trim();
+    if (!domain) return null;
+    try {
+      return new URL(domain.includes("://") ? domain : `https://${domain}`).origin;
+    } catch {
+      return null;
+    }
+  }
+  return {
+    async getDefinition(formKey, options) {
+      const normalizedKey = formKey.trim();
+      if (!isFormKey(normalizedKey)) {
+        throw new WebsiteError(
+          "formKey has an invalid format",
+          "INVALID_FORM_KEY"
+        );
+      }
+      const cached = cache.get(normalizedKey);
+      if (!options?.force && cached && cached.expiresAt > Date.now()) {
+        return cached.value;
+      }
+      const url = new URL(
+        `${apiUrl.replace(/\/+$/, "")}/api/v1/website/forms/definition`
+      );
+      url.searchParams.set("websiteSlug", websiteSlug);
+      url.searchParams.set("formKey", normalizedKey);
+      let response;
+      try {
+        const serverOrigin = getServerOrigin();
+        const headers = new Headers();
+        if (serverOrigin) headers.set("Origin", serverOrigin);
+        if (cached?.etag) headers.set("If-None-Match", cached.etag);
+        response = await fetch(url, {
+          ...serverOrigin || cached?.etag ? { headers } : {},
+          ...options?.force ? { cache: "no-cache" } : {}
+        });
+      } catch (error) {
+        throw new WebsiteError(
+          `Could not load the website form: ${error instanceof Error ? error.message : String(error)}`,
+          "NETWORK_ERROR"
+        );
+      }
+      if (response.status === 304 && cached) {
+        cache.set(normalizedKey, {
+          ...cached,
+          expiresAt: Date.now() + 3e4
+        });
+        return cached.value;
+      }
+      if (response.status === 404) {
+        cache.set(normalizedKey, {
+          etag: null,
+          expiresAt: Date.now() + 15e3,
+          value: null
+        });
+        return null;
+      }
+      if (response.status === 429) {
+        throw new RateLimitError(
+          "Rate limit exceeded. Please try again later.",
+          retryAfterSeconds(response)
+        );
+      }
+      if (!response.ok) {
+        throw new WebsiteError(
+          `Could not load the website form (status ${response.status})`,
+          response.status === 403 ? "ORIGIN_NOT_ALLOWED" : "FORM_DEFINITION_ERROR",
+          { status: response.status }
+        );
+      }
+      const value = await response.json();
+      if (value.schemaVersion !== 1 || value.key !== normalizedKey || !Array.isArray(value.definition?.fields) || !Array.isArray(value.definition?.sections) || !Array.isArray(value.definition?.steps)) {
+        throw new WebsiteError(
+          "Website form returned an invalid definition",
+          "INVALID_FORM_DEFINITION"
+        );
+      }
+      cache.set(normalizedKey, {
+        etag: response.headers.get("ETag"),
+        expiresAt: Date.now() + 3e4,
+        value
+      });
+      return value;
+    },
+    async submitResponse(input) {
+      const normalizedKey = input.formKey.trim();
+      if (!isFormKey(normalizedKey)) {
+        throw new WebsiteError(
+          "formKey has an invalid format",
+          "INVALID_FORM_KEY"
+        );
+      }
+      const context = getContext();
+      const attribution = getWebsiteMarketingAttribution(context.websiteId);
+      const pageUrl = typeof window !== "undefined" ? window.location.href : void 0;
+      const referrerUrl = typeof document !== "undefined" && document.referrer ? document.referrer : void 0;
+      let response;
+      try {
+        response = await fetch(
+          `${apiUrl.replace(/\/+$/, "")}/api/v1/website/forms/responses`,
+          {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+              websiteSlug,
+              formKey: normalizedKey,
+              formVersion: input.formVersion,
+              definitionHash: input.definitionHash,
+              idempotencyKey: input.idempotencyKey,
+              source: input.source ?? "WEBSITE",
+              values: input.values,
+              pageUrl,
+              referrerUrl,
+              attribution: attribution ? serializeWebsiteMarketingAttribution(attribution) : null,
+              honeypot: input.honeypot ?? ""
+            })
+          }
+        );
+      } catch (error) {
+        throw new WebsiteError(
+          `Could not submit the website form: ${error instanceof Error ? error.message : String(error)}`,
+          "NETWORK_ERROR"
+        );
+      }
+      if (response.status === 429) {
+        throw new RateLimitError(
+          "Rate limit exceeded. Please try again later.",
+          retryAfterSeconds(response)
+        );
+      }
+      const result = await response.json().catch(() => null);
+      if (!response.ok) {
+        throw new WebsiteError(
+          result?.message ?? `Could not submit the website form (status ${response.status})`,
+          result?.code ?? (response.status === 403 ? "ORIGIN_NOT_ALLOWED" : "FORM_RESPONSE_ERROR"),
+          { status: response.status }
+        );
+      }
+      if (typeof result?.accepted !== "boolean" || typeof result.message !== "string") {
+        throw new WebsiteError(
+          "Website form returned an invalid response",
+          "INVALID_RESPONSE"
+        );
+      }
+      return {
+        accepted: result.accepted,
+        responseId: typeof result.responseId === "string" ? result.responseId : null,
+        message: result.message
+      };
+    }
+  };
+}
+
 // libs/sdk/src/modules/marketing.ts
 function readRetryAfter(response) {
   const value = Number(response.headers.get("Retry-After") ?? "1");
@@ -6587,6 +6752,7 @@ function createBacanoClient(config) {
     config.websiteSlug,
     getContext
   );
+  const formsModule = createFormsModule(apiUrl, config.websiteSlug, getContext);
   return {
     async init() {
       if (context) return;
@@ -6639,6 +6805,10 @@ function createBacanoClient(config) {
       getByTag: contentModule.getByTag.bind(contentModule),
       getForProduct: contentModule.getForProduct.bind(contentModule)
     },
+    forms: {
+      getDefinition: formsModule.getDefinition.bind(formsModule),
+      submitResponse: formsModule.submitResponse.bind(formsModule)
+    },
     cart: {
       getOrCreate: cartModule.getOrCreate.bind(cartModule),
       startCheckout: cartModule.startCheckout.bind(cartModule),

package/modules/forms.d.ts

@@ -0,0 +1,9 @@
+import type { BacanoClientContext, WebsiteFormResponseInput, WebsiteFormResponseResult, WebsitePublishedForm } from "../types";
+export interface GetWebsiteFormOptions {
+    force?: boolean;
+}
+export interface FormsModule {
+    getDefinition(formKey: string, options?: GetWebsiteFormOptions): Promise<WebsitePublishedForm | null>;
+    submitResponse(input: WebsiteFormResponseInput): Promise<WebsiteFormResponseResult>;
+}
+export declare function createFormsModule(apiUrl: string, websiteSlug: string, getContext: () => BacanoClientContext): FormsModule;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bacano/sdk",
-  "version": "1.1.15",
+  "version": "1.1.17",
   "description": "TypeScript SDK for building websites on the Bacano ERP",
   "main": "./index.cjs",
   "module": "./index.js",
@@ -37,6 +37,11 @@
       "types": "./react/preview.d.ts",
       "import": "./react/preview.js",
       "require": "./react/preview.cjs"
+    },
+    "./react/forms": {
+      "types": "./react/forms.d.ts",
+      "import": "./react/forms.js",
+      "require": "./react/forms.cjs"
     }
   },
   "sideEffects": false,

package/react/form-field-control.d.ts

@@ -0,0 +1,10 @@
+import type { WebsiteFormField } from "../types";
+import type { BacanoFormValues } from "./forms";
+type BacanoFormValue = BacanoFormValues[string];
+export declare function BacanoFormFieldControl(props: {
+    field: WebsiteFormField;
+    className?: string;
+    value: BacanoFormValue;
+    onChange(value: BacanoFormValue): void;
+}): import("react").JSX.Element;
+export {};