@bacano/sdk 1.0.0

package/AUTHENTICATION.md

@@ -0,0 +1,365 @@
+# Storefront Buyer Authentication
+
+This document is the canonical authentication contract for storefronts built
+with `@bacano/sdk`. It is shipped with the package so a developer or coding
+agent can integrate buyer accounts without access to the Bacano monorepo.
+
+## Ownership Boundary
+
+Each Bacano website has its own Clerk application. This gives the same email
+address an independent account and password in different storefronts.
+
+Clerk owns:
+
+- sign-up and sign-in;
+- passwords and password recovery;
+- email verification;
+- session refresh, MFA, OAuth, and passkeys when enabled.
+
+Bacano owns:
+
+- mapping the verified Clerk user to a customer of the exact website;
+- guest and authenticated carts;
+- checkout and order ownership;
+- customer profile and web order history;
+- company and website isolation.
+
+The storefront owns presentation only. It may use Clerk components or a custom
+UI backed by Clerk's official SDK. Passwords and verification codes must go
+directly from the browser to Clerk. They must never be sent to Bacano or
+`@bacano/sdk`.
+
+## Security Invariants
+
+- Never put a Clerk secret key, Bacano admin secret, or internal API key in the
+  browser.
+- Never store the Clerk access token in `localStorage`. Clerk owns its session.
+- Give Bacano a token provider function, not a captured token.
+- Never send `clientId`, `companyId`, or a claimed buyer identity from checkout.
+  Bacano derives identity from the verified token.
+- Never associate a guest purchase with an account only because emails match.
+- Never query Hasura directly from a storefront.
+- Always configure and send the exact Bacano `websiteSlug`.
+- Always preserve the real storefront `Origin`, including protocol and port.
+
+Bacano validates the explicit website slug, request `Origin`, token signature,
+Clerk issuer, and the JWT `azp` authorized party before producing tenant-scoped
+Hasura claims. The slug selects the website; Origin proves that the caller is
+allowed to use it.
+
+## Public Website Bootstrap
+
+The Clerk publishable key is website-specific and safe for browser use. Load it
+at runtime instead of hardcoding one global Clerk application:
+
+```ts
+import { getWebsitePublicConfig } from "@bacano/sdk";
+
+const website = await getWebsitePublicConfig({
+  apiUrl: process.env.NEXT_PUBLIC_BACANO_API_URL!,
+  websiteSlug: process.env.NEXT_PUBLIC_BACANO_WEBSITE_SLUG!,
+  // Required for server-side calls. Browsers provide their own Origin.
+  origin: "https://store.example.com",
+});
+
+console.log(website.slug);
+console.log(website.buyerAccountsEnabled);
+console.log(website.clerkPublishableKey);
+```
+
+The response exposes only browser-safe website data. Clerk secret keys and
+JWKS configuration never leave Bacano.
+
+If `buyerAccountsEnabled` is false or `clerkPublishableKey` is null, keep the
+storefront in guest mode. Catalog, cart, and guest checkout remain available.
+
+## Next.js And React
+
+Install the official Clerk integration used by the storefront framework. For
+Next.js:
+
+```bash
+pnpm add @clerk/nextjs
+```
+
+Mount `BacanoProvider` inside the website-specific `ClerkProvider`:
+
+```tsx
+"use client";
+
+import { ClerkProvider, useAuth } from "@clerk/nextjs";
+import { BacanoProvider } from "@bacano/sdk/react";
+import type { ReactNode } from "react";
+
+function StorefrontBacanoProvider({ children }: { children: ReactNode }) {
+  const { getToken } = useAuth();
+
+  return (
+    <BacanoProvider
+      config={{
+        apiUrl: process.env.NEXT_PUBLIC_BACANO_API_URL!,
+        websiteSlug: process.env.NEXT_PUBLIC_BACANO_WEBSITE_SLUG!,
+        getAccessToken: () => getToken(),
+      }}
+    >
+      {children}
+    </BacanoProvider>
+  );
+}
+
+export function StorefrontProviders({
+  publishableKey,
+  children,
+}: {
+  publishableKey: string;
+  children: ReactNode;
+}) {
+  return (
+    <ClerkProvider publishableKey={publishableKey}>
+      <StorefrontBacanoProvider>{children}</StorefrontBacanoProvider>
+    </ClerkProvider>
+  );
+}
+```
+
+Do not call `getToken()` once during initialization and retain its result. The
+SDK calls `getAccessToken` for every request so Clerk can refresh or replace
+the session token.
+
+## Framework-Agnostic Client
+
+The same contract works without React:
+
+```ts
+import { createBacanoClient } from "@bacano/sdk";
+
+const client = createBacanoClient({
+  apiUrl: "https://api.bacanoerp.com",
+  websiteSlug: "my-store",
+  getAccessToken: async () => clerkSession?.getToken() ?? null,
+});
+
+await client.init();
+```
+
+The SDK intentionally does not expose `login`, `register`, `logout`, or
+password methods. Use the official Clerk SDK for those operations.
+
+## Guest And Authenticated Behavior
+
+Guest buyer:
+
+- can browse, use the cart, and submit checkout;
+- does not receive an account silently;
+- can use the public order lookup token returned by checkout.
+
+Authenticated buyer:
+
+- uses the same cart and checkout methods;
+- is associated by Bacano from verified Hasura session variables;
+- can read and update their Bacano customer profile;
+- can read only their own `WEB` orders for the exact website.
+
+Checkout code is identical in both modes:
+
+```ts
+const result = await client.checkout.submit({
+  contact: {
+    firstName: "Maria",
+    lastName: "Perez",
+    email: "maria@example.com",
+    cellphone: "+573001234567",
+  },
+  fulfillmentFamily: "SHIPPING",
+  address,
+  shippingQuoteId,
+  paymentMethodId,
+});
+```
+
+Do not add a `clientId` to the checkout payload. If Clerk has an active
+session, the SDK sends its token automatically. Otherwise checkout remains a
+guest checkout.
+
+If checkout collects a mobile/WhatsApp number that is not yet in the Bacano
+profile, synchronize it explicitly through the authenticated profile API:
+
+```ts
+await client.profile.update({ cellphone: contact.phone });
+await client.checkout.submit({
+  contact,
+  fulfillmentFamily: "SHIPPING",
+  address,
+  shippingQuoteId,
+  paymentMethodId,
+});
+```
+
+This is an explicit commercial-profile update, not identity matching. Checkout
+never accepts `clientId`; Bacano associates the order from the verified Clerk
+token. Guest checkout continues without this call or an access token.
+
+## Deferred Account Activation From Checkout
+
+A guest may explicitly request an account without interrupting payment or
+email verification during checkout:
+
+```ts
+const result = await client.checkout.submit({
+  contact,
+  fulfillmentFamily: "SHIPPING",
+  address,
+  shippingQuoteId,
+  paymentMethodId,
+  buyerAccountOptIn: true,
+});
+
+console.log(result.buyerAccountInvitationRequested);
+```
+
+`buyerAccountOptIn` is only a consent signal. After Bacano validates and
+persists a real guest order, it queues the Clerk application invitation and
+returns the checkout response without waiting for Clerk. The invitation does
+not depend on payment approval: pending bank transfers, cash on delivery and
+payment-session orders are eligible as soon as the order exists. Invalid
+checkout attempts that never create an order do not send invitations. Failed
+invitation delivery never rolls back or changes the order.
+
+After Clerk verifies the buyer and accepts the activation reference, Bacano
+atomically assigns the order to that website-scoped buyer and fills only
+missing commercial profile fields from the persisted checkout snapshot. This
+includes name, mobile and primary shipping address. Existing profile data is
+preserved, and the authenticated email always comes from Clerk rather than the
+checkout payload.
+
+The storefront must show this option only after the buyer explicitly checks a
+label such as "Crear mi cuenta para consultar este pedido después". Do not
+preselect it. If the buyer is already authenticated, Bacano ignores the option
+and associates the order from the verified Clerk token instead.
+
+The invitation redirects to the website's configured activation path (default
+`/crear-cuenta`) with Clerk's `__clerk_ticket` query parameter. That page must
+complete Clerk's official invitation flow. After Clerk establishes a session,
+make an authenticated SDK request such as `client.profile.get()`. Bacano then
+links the order using the backend-issued activation reference, the exact
+website and company, and Clerk's verified primary email. The storefront never
+sends an order claim, email match, invitation id, password, code, or secret.
+
+`buyerAccountInvitationRequested` confirms that Bacano durably accepted the
+request; it does not mean the email has already been delivered, that the buyer
+has activated the account, or that payment was approved.
+
+## Profile And Orders
+
+These methods require an authenticated Clerk session:
+
+```ts
+const profile = await client.profile.get();
+const addresses = await client.profile.getAddresses();
+
+await client.profile.update({
+  name: "Ada",
+  lastname: "Lovelace",
+  cellphone: "+573001234567",
+  address: "Carrera 10 # 20-30",
+  addressComplement: "Apto 401",
+  countryCode: "CO",
+  departmentId: "68",
+  municipalityId: "68001",
+});
+
+const orders = await client.orders.list({ limit: 20, offset: 0 });
+const order = await client.orders.get(orders[0].id);
+```
+
+Account pages must handle an expired or missing Clerk session by asking the
+buyer to sign in again. They must not fall back to a public GraphQL query.
+
+`profile.email` is the verified primary email synchronized by Bacano directly
+from Clerk. It is read-only: storefronts must not send email, passwords,
+verification codes, tokens, or any other identity secret to `profile.update()`.
+
+Use `cellphone` as the canonical mobile/WhatsApp number in E.164 format
+(`+573001234567`). `phone` is reserved for an optional secondary or
+national-format telephone number. A WhatsApp opt-in, if added later, must be a
+separate consent field rather than another alias for the same number.
+
+Calling `profile.update()` repeatedly is safe: it updates the authenticated
+buyer's existing party and never creates or matches customers by email.
+
+`profile.getAddresses()` resolves the customer exclusively from the verified
+Clerk token and current website. It returns only checkout-ready commercial
+(`PRIMARY`) and saved delivery (`SHIPPING`) addresses whose department and
+municipality are canonical. Incomplete legacy addresses are omitted so the
+storefront requests location again instead of matching it by text. Use
+`departmentId`/`municipalityId` directly when pre-filling checkout and quoting
+shipping; do not send a `clientId`.
+
+## Server Rendering And Static Sites
+
+Public catalog and content requests may run without an access token.
+
+For an authenticated server-side request, use Clerk's server auth API to
+provide a token for that request and forward the storefront's exact `Origin`.
+Never reuse one buyer token across requests or cache authenticated responses
+between users.
+
+Static storefronts should initialize Clerk in the browser from the public
+website bootstrap. Do not bake Clerk secret keys or buyer tokens into static
+output.
+
+## Required Configuration
+
+Before testing a website:
+
+1. Bacano website auth provisioning must be `READY`.
+2. The website must contain its Clerk publishable key and JWKS URL.
+3. The storefront origin must be configured in Bacano.
+4. The same origin must be allowed by Clerk.
+5. Redirect URLs for sign-in, sign-up, verification, and recovery must match
+   the storefront environment.
+6. Local origins must include the exact port.
+
+## Acceptance Checklist
+
+Guest mode:
+
+- catalog and content load;
+- cart persists;
+- checkout succeeds without creating an account.
+
+Account mode:
+
+- sign-up and email verification succeed through Clerk;
+- sign-in, refresh, sign-out, and password recovery work;
+- authenticated checkout appears in `orders.list()`;
+- profile reads and updates work.
+
+Isolation:
+
+- a token issued for another Clerk application is rejected;
+- a token with a different `azp` origin is rejected;
+- buyers cannot read another website's orders;
+- POS and physical-store orders never appear in the storefront account.
+
+Regression:
+
+- guest checkout still works after Clerk is enabled;
+- deferred account opt-in does not delay or fail checkout;
+- an accepted invitation exposes its order only after an authenticated SDK
+  request completes the secure claim;
+- payment-session flows still work;
+- catalog, content, media, and public order lookup remain public where
+  intended.
+
+## Deliberately Unsupported
+
+- Silent account creation from checkout contact fields.
+- Claiming old guest orders by email match alone.
+- Sharing one Clerk account or password across independent websites.
+- Storefront-managed JWT persistence.
+- Direct Hasura access from the storefront.
+
+Only orders carrying an explicit deferred-account opt-in can be claimed later,
+and Bacano performs that claim from backend-issued invitation metadata plus a
+verified Clerk identity.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pulpo Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.