@tabcommerceio/buy-together-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tab commerce technologies llc
+
+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.

package/README.md

@@ -0,0 +1,180 @@
+# Product Bundle SDK
+
+`@tabcommerceio/buy-together-sdk` provides the Product Bundle storefront workflow:
+Offer lookup, exact Variant re-quotes, verified **Add bundle**, and independent
+Bundle event delivery. It is browser-targeted ESM with TypeScript declarations
+and no runtime dependencies. It does not import or mount the Cross Sell SDK.
+
+## Install and choose the SDK
+
+```bash
+npm install @tabcommerceio/buy-together-sdk
+```
+
+Use `@tabcommerceio/cross-sell-sdk` for individual recommendations and Cross Sell
+tracking. Use this package for Product Bundle Offers. An Online Store can use
+both packages, with separate clients, roots, tokens, and event observers.
+
+`1.0.0` is the first public release of the current component-based contract.
+It replaces the repository's earlier experimental role-based API: components
+are identified by `component_id`, and every purchasable selection carries a
+short `quote_expires_at`. Code using older workspace builds must migrate all
+component tuples and implement the re-quote flow below. The package name stays
+`buy-together-sdk`; a product display-name change does not require an npm rename.
+
+## Before connecting
+
+Use the installed shop's actual App Proxy path; the examples use the development
+path `/apps/tab-cross-sell-dev`. Requests run in the shopper's Online Store
+browser through Shopify's signed proxy. Do not put Admin API credentials into
+browser code. Resolve and quote require the shop's `api_access` entitlement
+(currently Optimize, or an otherwise eligible enabled plan).
+
+An Offer is a peer Product set. Every member Product can be its PDP source.
+The server owns eligible variants, contextual prices, totals, tokens, and the
+Bundle instance identity. Never calculate a replacement quote in the browser.
+The current protocol accepts two to four distinct component Products.
+
+## Custom UI: resolve, re-quote, add
+
+The following controller uses public exports only. Bind your option controls to
+`chooseVariants`, refresh displayed totals from its returned Offer, and enable
+Add only when `canAdd()` is true. Disable option controls while Add is running.
+Each selection contains **every** component tuple, including unchanged members.
+Replace the example country, currency, proxy path, slot, and locale root with
+current shop facts. Use `offer_ids` instead of `slot_key` when selecting explicit
+Offers; never send both selectors.
+
+```ts
+import {
+  init,
+  createQuoteRequestFence,
+  type BundleOffer,
+  type BundleQuoteSelection,
+} from '@tabcommerceio/buy-together-sdk'
+
+const client = init({ proxyBase: '/apps/tab-cross-sell-dev' })
+const context = { country: 'US' }
+const cart = { currency: 'USD' }
+const routeRoot = '/' // Use the shop's Shopify.routes.root, e.g. '/fr/'.
+const fence = createQuoteRequestFence()
+const resolved = await client.resolve({ slot_key: 'summer-bundles', context, cart })
+let tokenSource: BundleOffer | null = resolved?.offers[0] ?? null
+let ready: BundleOffer | null = tokenSource
+let adding = false
+let needsCartRecovery = false
+
+export function canAdd(): boolean {
+  return !adding && !needsCartRecovery && ready !== null &&
+    Date.parse(ready.quote_expires_at) > Date.now()
+}
+
+export async function chooseVariants(selections: BundleQuoteSelection[]) {
+  if (!tokenSource || adding || needsCartRecovery) return null
+  const tracking_token = tokenSource.tracking_token
+  ready = null // The previous selection cannot remain purchasable.
+  const attempt = fence.begin() // Aborts and invalidates the previous request.
+  const result = await client.quote({ tracking_token, selections, context, cart }, attempt.signal)
+  if (!fence.isCurrent(attempt)) return null
+  if (!result?.eligible || !result.offer) return null
+  tokenSource = result.offer
+  ready = result.offer
+  return ready // Render these server-returned totals and selected variants.
+}
+
+export async function addSelectedBundle() {
+  if (!canAdd() || !ready) return null
+  adding = true
+  try {
+    const result = await client.addAll(ready, { routeRoot })
+    if (result.status === 'added') {
+      ready = null
+      tokenSource = null // Resolve again before starting another Bundle instance.
+    } else if (result.status === 'recoverable_error') {
+      needsCartRecovery = true
+      ready = null
+      window.location.assign(`${routeRoot}cart`)
+    }
+    return result
+  } finally {
+    adding = false
+  }
+}
+
+export function destroyBundleUI() {
+  fence.cancel()
+  client.destroy()
+}
+```
+
+Read a component's eligible `variants` to construct its selected
+`{ component_id, product_id, variant_id }` tuple. Pass only the latest eligible
+server Offer to `addAll()`. Preserve its `bundle_instance_id` and tracking token;
+never mint a replacement instance after the server has signed it. Re-resolve
+when the live Offer is stale. Update country/cart facts and re-resolve when the
+shopper's market or currency changes.
+
+### Add outcomes
+
+| Status | Meaning and next action |
+|---|---|
+| `added` | Both the add response and a fresh cart read prove the exact component/property tuples. Refresh your cart UI; resolve a new instance for another add. |
+| `failed` | A fresh read proves a clean no-op. Let the shopper retry only with a still-valid quote. |
+| `compensated` | Partial instance lines were removed and the clean result was verified. A deliberate retry with a valid quote is safe. |
+| `recoverable_error` | The cart outcome could not be proven. Stop retries and navigate to a fresh cart; do not mint another request/instance to retry blindly. |
+
+The SDK sends one Shopify Ajax `/cart/add.js` multi-item request with the five
+`_tab_bundle_*` private properties. Its compensation targets only lines from
+that exact instance/token. It queues `add_to_cart` only after full cart proof;
+custom consumers must not send a duplicate event. Resolve/quote return `null`
+for transport failures; an ineligible quote must leave Add disabled.
+
+## Rendering and tracking
+
+`resolvePDP()` returns server-rendered HTML. `mountPDP()` inserts that HTML,
+fences overlapping mounts, and observes impressions. Its request requires the
+currently selected source Product/Variant GIDs and a new `crypto.randomUUID()`
+instance **before** requesting a signed fragment. It does not wire custom UI
+option/add handlers: those remain the host's responsibility. The official
+Theme App Block bundles its own interaction controller and needs no npm install.
+
+For custom cards, use `createBundleImpressionObserver` with an observe target
+containing the actual Offer's `offer_id`, `tracking_token`, and `request_id`;
+forward its `onImpression` payload to `client.track`. The public observer enforces
+50% visibility for 500 ms and excludes hidden-tab time. Track clicks with the
+same Offer identity. `client.flush()` drains queued events, and
+`client.destroy()` releases client resources; disconnect any observer you create
+separately. No Bundle root or event belongs to the Cross Sell client.
+
+In browsers `init` uses the page's document/window for visibility and pagehide
+flushes. Explicit refs are only needed for custom environments.
+
+## Using both packages
+
+```ts
+import { init as initCrossSell } from '@tabcommerceio/cross-sell-sdk'
+import { init as initBundles } from '@tabcommerceio/buy-together-sdk'
+
+const proxyBase = '/apps/tab-cross-sell-dev'
+const crossSell = initCrossSell({ proxyBase })
+const bundles = initBundles({ proxyBase })
+// Bind each client to its own cards and event identities.
+// On teardown: crossSell.destroy(); bundles.destroy().
+```
+
+The public ESM API supplies data/commerce primitives for your own markup. The
+internal official Theme IIFE is built separately as
+`tab-buy-together-storefront.js` and is excluded from this npm package. After a
+proven official add it synchronizes the theme cart and emits
+`tab:buy-together:cart-changed`; custom ESM consumers refresh their own cart UI.
+
+## Maintainer release
+
+Source: `tabcommerce/tab-cross-sell`, directory `packages/web/buy-together-sdk`.
+The shared workflow `publish-cross-sell-sdk.yml` publishes exact manifest
+versions for both SDKs from `main` using package-scoped npm Trusted Publishing.
+The initial publication requires an authenticated package owner; configure the
+Bundle package's trust binding after that first publish. Local validation uses
+`pnpm publish:buy-together:dry`; the authorized manual release command is
+`pnpm publish:buy-together`. See `scripts/release/README.md` in the repository
+for digest, authentication, tagging, and post-publication checks.

package/dist/index.d.ts

@@ -0,0 +1,335 @@
+/** One neutral member Product resolved to the exact Variant for this Offer. */
+type BundleComponent = {
+    component_id: string;
+    product_id: string;
+    variant_id: string;
+};
+type BundleEligibleVariant = {
+    variant_id: string;
+    title: string;
+    option_values: string[];
+    available: boolean;
+    price: BundleMoney;
+};
+/** Display snapshot returned only by the agency/API resolve route. */
+type BundleResolvedComponent = BundleComponent & {
+    product_title: string;
+    image_url?: string;
+    options: string[];
+    variants: BundleEligibleVariant[];
+};
+type BundleMoney = {
+    amount: string;
+    currency: string;
+};
+/** Minimum cart identity needed to safely add one exact Bundle Offer. */
+type BundleCartOffer = {
+    offer_id: string;
+    tracking_token: string;
+    components: BundleComponent[];
+    /**
+     * The exact instance UUID signed into tracking_token by the rendered route.
+     * Add bundle must use this value verbatim; it must never mint a replacement.
+     */
+    bundle_instance_id: string;
+    /** Server-enforced short authorization window for this exact selection. */
+    quote_expires_at: string;
+};
+type BundleCartLine = {
+    product_id?: string;
+    variant_id?: string;
+    quantity?: number;
+};
+/** Current contextual facts accepted by the Bundle storefront routes. */
+type BundleCartContext = {
+    currency: string;
+    lines?: BundleCartLine[];
+};
+type BundleRequestContext = {
+    country: string;
+};
+/**
+ * Official PDP route: the selected source Product and Variant. Every member
+ * Product can be the source; the selected Variant determines that member's
+ * cart line while the server resolves first-available Variants for the other
+ * neutral members.
+ */
+type BundlePDPRenderedRequest = {
+    source_product_id: string;
+    source_variant_id: string;
+    /** Client-generated UUID supplied before token issuance. */
+    bundle_instance_id: string;
+    context: BundleRequestContext;
+    cart: BundleCartContext;
+};
+/** Agency/API route: exactly one selector (slot_key or offer_ids). */
+type BundleResolveRequest = {
+    slot_key: string;
+    offer_ids?: never;
+    limit?: number;
+    context: BundleRequestContext;
+    cart: BundleCartContext;
+} | {
+    slot_key?: never;
+    offer_ids: string[];
+    limit?: number;
+    context: BundleRequestContext;
+    cart: BundleCartContext;
+};
+/** Fully validated agency/API resolve Offer. */
+type BundleOffer = Omit<BundleCartOffer, 'components'> & {
+    campaign_id: string;
+    publish_version_id: string;
+    campaign_version: number;
+    revision: number;
+    position: number;
+    name: string;
+    message: string;
+    components: BundleResolvedComponent[];
+    regular_total: BundleMoney;
+    offer_total: BundleMoney;
+    savings: BundleMoney;
+    request_id: string;
+    surface: 'pdp' | 'api_slot' | 'api_offer_ids';
+    slot_key?: string;
+};
+type BundleQuoteSelection = BundleComponent;
+type BundleQuoteRequest = {
+    /** Previously issued capability; Offer identity and surface come only from its verified claims. */
+    tracking_token: string;
+    selections: BundleQuoteSelection[];
+    context: BundleRequestContext;
+    cart: BundleCartContext;
+};
+type BundleQuoteResponse = {
+    request_id: string;
+    eligible: boolean;
+    reason?: 'stale_offer' | 'invalid_selection' | 'temporarily_unavailable';
+    offer?: BundleOffer;
+};
+type BundleResolveResponse = {
+    request_id: string;
+    offers: BundleOffer[];
+};
+type BundleRenderedResponse = {
+    html: string;
+    request_id: string;
+};
+type BundleEventType = 'impression' | 'click' | 'add_to_cart';
+type BundleTrackInput = {
+    event_type: BundleEventType;
+    tracking_token: string;
+    offer_id: string;
+    request_id: string;
+    attrs?: Record<string, unknown>;
+    event_id?: string;
+    occurred_at?: string;
+};
+type BundleStorefrontEvent = Required<Pick<BundleTrackInput, 'event_id' | 'occurred_at'>> & Omit<BundleTrackInput, 'event_id' | 'occurred_at'>;
+type FetchLike = (input: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+    keepalive?: boolean;
+    credentials?: RequestCredentials;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+}>;
+type CartLineLike = {
+    id?: string | number;
+    key?: string;
+    quantity?: number;
+    properties?: Record<string, unknown> | null;
+};
+type ObserveTarget = {
+    element: Element;
+    tracking_token: string;
+    offer_id: string;
+    request_id: string;
+};
+type VisibilityEvidence = {
+    ratio: number;
+    duration_ms: number;
+};
+
+/**
+ * `failed` is a proven clean no-op: a successful fresh cart read showed that
+ * nothing of this instance reached the cart, so no compensation ran.
+ * `compensated` means partially written lines were zeroed.
+ * `recoverable_error` covers every unproven outcome: instance lines whose
+ * cart/update.js compensation failed, and double network failures where the
+ * add may have been accepted but the cart read could not prove either way.
+ * Callers must not blind-retry a `recoverable_error` as if it were `failed`.
+ */
+type BundleAddResult = {
+    status: 'added';
+} | {
+    status: 'failed';
+} | {
+    status: 'compensated';
+} | {
+    status: 'recoverable_error';
+};
+type AddBundleToCartOptions = {
+    offer: BundleCartOffer;
+    fetchImpl?: FetchLike;
+    track: (input: BundleTrackInput) => void;
+    /** Injectable for deterministic tests; defaults to crypto.randomUUID(). */
+    createId?: () => string;
+    /** Shopify.routes.root, e.g. `/` or `/fr/`. */
+    routeRoot?: string;
+    onAdded?: () => void | Promise<void>;
+    /** Injectable epoch milliseconds for quote-expiry tests. */
+    now?: () => number;
+};
+/**
+ * Adds every exact signed component in one Shopify Ajax Cart request. It does
+ * not optimistically track success: the add response *and* a fresh cart read
+ * must both prove each exact Variant/private-property tuple.
+ */
+declare function addBundleToCart(options: AddBundleToCartOptions): Promise<BundleAddResult>;
+
+type BuyTogetherInitOptions = {
+    proxyBase: string;
+    fetchImpl?: FetchLike;
+    flushIntervalMs?: number;
+    flushThreshold?: number;
+    createEventId?: () => string;
+    now?: () => number;
+    documentRef?: Document;
+    windowRef?: Window;
+    IntersectionObserverImpl?: typeof IntersectionObserver;
+};
+type BundleMountPDPOptions = {
+    root: Element;
+    request: BundlePDPRenderedRequest;
+    signal?: AbortSignal;
+};
+type BuyTogetherClient = {
+    resolve: (request: BundleResolveRequest, signal?: AbortSignal) => Promise<BundleResolveResponse | null>;
+    resolvePDP: (request: BundlePDPRenderedRequest, signal?: AbortSignal) => Promise<BundleRenderedResponse | null>;
+    quote: (request: BundleQuoteRequest, signal?: AbortSignal) => Promise<BundleQuoteResponse | null>;
+    mountPDP: (options: BundleMountPDPOptions) => Promise<() => void>;
+    addAll: (offer: BundleCartOffer, options?: Omit<AddBundleToCartOptions, 'offer' | 'track' | 'fetchImpl'>) => Promise<BundleAddResult>;
+    track: (input: BundleTrackInput) => void;
+    flush: () => Promise<void>;
+    destroy: () => void;
+};
+/**
+ * The Bundle renderer has independent data attributes. Do not make a card
+ * trackable from Cross Sell provenance or from generic product markup.
+ */
+declare function collectBundleObserveTargets(root: Element): ObserveTarget[];
+declare function init(options: BuyTogetherInitOptions): BuyTogetherClient;
+
+declare const MAX_BUNDLE_EVENTS_BATCH = 100;
+type BundleEventQueueOptions = {
+    proxyBase?: string;
+    fetchImpl?: FetchLike;
+    createEventId?: () => string;
+    now?: () => number;
+    onEnqueued?: (count: number) => void;
+};
+/**
+ * Deliberately separate from the Cross Sell queue: Bundle event payloads carry
+ * Offer identity and are delivered only to the Bundle event route.
+ */
+declare function createBundleEventQueue(options?: BundleEventQueueOptions): {
+    track: (input: BundleTrackInput) => BundleStorefrontEvent;
+    enqueue: (event: BundleStorefrontEvent) => void;
+    flush: () => Promise<void>;
+    pending: () => BundleStorefrontEvent[];
+};
+
+type BundleFlushControllerOptions = {
+    flush: () => Promise<void>;
+    intervalMs?: number;
+    threshold?: number;
+    setIntervalImpl?: (callback: () => void, intervalMs: number) => number | ReturnType<typeof setInterval>;
+    clearIntervalImpl?: (handle: number | ReturnType<typeof setInterval>) => void;
+    documentRef?: Document;
+    windowRef?: Window;
+};
+/** Page-lifecycle delivery coordinator owned solely by the Bundle event queue. */
+declare function createBundleFlushController(options: BundleFlushControllerOptions): {
+    start: () => void;
+    stop: () => void;
+    flushNow: () => Promise<void>;
+    notifyEnqueued(count: number): void;
+};
+
+declare const BUNDLE_IMPRESSION_MIN_RATIO = 0.5;
+declare const BUNDLE_IMPRESSION_MIN_DURATION_MS = 500;
+type BundleImpressionPayload = {
+    tracking_token: string;
+    offer_id: string;
+    request_id: string;
+    attrs: {
+        visibility: VisibilityEvidence;
+    };
+};
+type BundleImpressionObserverOptions = {
+    onImpression: (payload: BundleImpressionPayload) => void;
+    IntersectionObserverImpl?: typeof IntersectionObserver;
+    now?: () => number;
+    setTimeoutImpl?: (callback: () => void, delayMs: number) => number | ReturnType<typeof setTimeout>;
+    clearTimeoutImpl?: (handle: number | ReturnType<typeof setTimeout>) => void;
+    documentRef?: Document;
+};
+/** Independent 50%/500ms Bundle observer, never shared with Cross Sell. */
+declare function createBundleImpressionObserver(options: BundleImpressionObserverOptions): {
+    observe: (_items: ObserveTarget[]) => void;
+    disconnect: () => void;
+    seenTokens: () => Set<string>;
+};
+
+type PDPRequestSequencerOptions<Request, Result> = {
+    resolve: (request: Request, signal: AbortSignal) => Promise<Result | null>;
+    /** Called synchronously for every source-variant change. */
+    onClear: () => void;
+    /** Only receives results that still belong to the current request. */
+    onResult: (result: Result) => void;
+};
+/**
+ * Keeps PDP output tied to the currently selected variant. A variation switch
+ * immediately removes stale bundle content, aborts the old fetch, and fences
+ * late responses by monotonically increasing request generation.
+ */
+declare function createPDPRequestSequencer<Request, Result>(options: PDPRequestSequencerOptions<Request, Result>): {
+    run: (request: Request) => Promise<Result | null>;
+    cancel: () => void;
+};
+
+type QuoteAttempt = {
+    revision: number;
+    signal: AbortSignal;
+};
+/** One-lane quote fence: every new selection aborts and invalidates its predecessor. */
+declare function createQuoteRequestFence(): {
+    begin(): QuoteAttempt;
+    isCurrent(attempt: QuoteAttempt): boolean;
+    cancel(): void;
+};
+
+type ResolveOptions = {
+    /** App Proxy base, e.g. `/apps/tab-cross-sell-dev`. */
+    proxyBase: string;
+    fetchImpl?: FetchLike;
+    signal?: AbortSignal;
+};
+/**
+ * Reject malformed selector requests before they cross the App Proxy. This is
+ * defense-in-depth; customer-api repeats all selector validation authoritatively.
+ */
+declare function isValidBundleResolveRequest(request: BundleResolveRequest): boolean;
+/** Agency SDK resolve; failed/invalid response remains an empty integration. */
+declare function resolveBundleOffers(request: BundleResolveRequest, options: ResolveOptions): Promise<BundleResolveResponse | null>;
+/** Official PDP-only rendered resolve. It does not accept slots or explicit IDs. */
+declare function resolveBundlePDP(request: BundlePDPRenderedRequest, options: ResolveOptions): Promise<BundleRenderedResponse | null>;
+/** Re-quotes one exact selection; malformed/stale responses never become addable. */
+declare function quoteBundleOffer(request: BundleQuoteRequest, options: ResolveOptions): Promise<BundleQuoteResponse | null>;
+
+export { type AddBundleToCartOptions, BUNDLE_IMPRESSION_MIN_DURATION_MS, BUNDLE_IMPRESSION_MIN_RATIO, type BundleAddResult, type BundleCartContext, type BundleCartLine, type BundleCartOffer, type BundleComponent, type BundleEligibleVariant, type BundleEventType, type BundleMoney, type BundleMountPDPOptions, type BundleOffer, type BundlePDPRenderedRequest, type BundleQuoteRequest, type BundleQuoteResponse, type BundleQuoteSelection, type BundleRenderedResponse, type BundleRequestContext, type BundleResolveRequest, type BundleResolveResponse, type BundleResolvedComponent, type BundleStorefrontEvent, type BundleTrackInput, type BuyTogetherClient, type BuyTogetherInitOptions, type CartLineLike, type FetchLike, MAX_BUNDLE_EVENTS_BATCH, type ObserveTarget, type VisibilityEvidence, addBundleToCart, collectBundleObserveTargets, createBundleEventQueue, createBundleFlushController, createBundleImpressionObserver, createPDPRequestSequencer, createQuoteRequestFence, init, isValidBundleResolveRequest, quoteBundleOffer, resolveBundleOffers, resolveBundlePDP };