@zyno-io/zynosales-ecommerce-sdk

Framework-neutral TypeScript SDK for ZynoSales embedded ecommerce storefronts.

The package owns catalog reads, cart persistence, checkout workflows, payment recovery, and lifecycle hooks. Your website owns rendering, routing, styling, and Stripe Elements. Sales remains authoritative for money, tax, discounts, shipping, and order status.

Install

yarn add @zyno-io/zynosales-ecommerce-sdk
# or: npm install @zyno-io/zynosales-ecommerce-sdk
# or: pnpm add @zyno-io/zynosales-ecommerce-sdk

Requires Node.js 22+ for package tooling. Browser runtimes need fetch.

Quick start

import { createZynoSales } from '@zyno-io/zynosales-ecommerce-sdk';

const storefront = createZynoSales({ publishableKey: 'zs_pk_...' });

const products = await storefront.catalog.getProducts();
await storefront.cart.restore();

const firstProduct = products[0];
if (firstProduct) {
    await storefront.cart.add({ productId: firstProduct.id, qty: 1 });
}

storefront.cart.subscribe(snapshot => {
    // Render snapshot.cart, snapshot.isBusy, and snapshot.lastError.
});

What the SDK provides

| Surface | Responsibility | | --- | --- | | storefront.catalog | Product list/detail reads with an explicit in-memory list cache | | storefront.cart | Create, restore, mutate, and abandon a persistent cart | | storefront.checkout | Buyer, address, shipping, discounts, card setup, recovery | | storefront.getConfig() | Runtime capabilities, currency, and Stripe browser settings | | Hooks | onCartChanged, beforePayment, afterOrderCompleted |

It does not ship UI components, CSS, routing, Stripe.js, or checkout markup.

Membership products support tier selection, mixed carts, purchaser billing details, recurring-term acceptance, and reusable card setup for free introductory periods. beginCardPayment() returns CardCheckoutSetup | null; branch on setupIntentId to choose Stripe's SetupIntent or PaymentIntent confirmation flow. See the checkout guide and Stripe guide.

Documentation

• Get started
• Install and configure
• Load products
• Create and manage a cart
• Build checkout
• Stripe and order completion
• Lifecycle hooks
• State, recovery, and errors
• Server handoff
• API reference

Local development

yarn install
yarn test
yarn docs:dev

See examples/vanilla-storefront for a minimal call-sequence reference.