T2 Shop Widgets

Embeddable cart and catalog SDK for T2 Shop — a hosted commerce SaaS (product catalog, cart, stock, checkout, and payments on our infrastructure). This package is the official client for T2 Shop stores: it calls your store’s public APIs and is not a standalone, self-hosted backend.

• Documentation & getting started: t2-shop.com/docs — embed guides, dashboard setup, payments, and allowed domains.
• Service: T2 Shop is a commercial product; you need an account and store on t2-shop.com to use this SDK.

The cart runs as a Web Component in a Shadow DOM (React + Tailwind, isolated styles). Ships as ES, CJS, UMD, and IIFE bundles.

Install

Use any package manager you prefer (same package on the npm registry):

npm install @t2devs/t2shop-widget
pnpm add @t2devs/t2shop-widget
yarn add @t2devs/t2shop-widget
bun add @t2devs/t2shop-widget
deno add npm:@t2devs/t2shop-widget

For Deno, use a recent Deno with npm compatibility (deno add / npm: specifiers). Import in code as import … from "npm:@t2devs/t2shop-widget" if you manage deps manually.

Build artifacts live in lib/ after pnpm run build:prod (or use the published package).

Quick start (global script)

Load the IIFE build with a classic <script src> (not type="module"). Use an npm CDN URL (pin a version in production instead of @latest):

• jsDelivr: https://cdn.jsdelivr.net/npm/@t2devs/t2shop-widget@latest/lib/t2-shop-widgets.iife.js
• unpkg: https://unpkg.com/@t2devs/t2shop-widget@latest/lib/t2-shop-widgets.iife.js

<script src="https://cdn.jsdelivr.net/npm/@t2devs/t2shop-widget@latest/lib/t2-shop-widgets.iife.js"></script>
<script>
  T2ShopWidgets.config({
    apiBaseUrl: "https://YOUR_T2SHOP_ORIGIN",
    storeId: "YOUR_STORE_ID",
    widgets: {
      cart: {
        theme: { primaryColor: "#2563eb", mode: "light" },
        ui: { floatingPlacement: "bottom-right", floatingSize: "sm" },
        disableFloatingButton: false,
      },
    },
  });

  async function addToCart() {
    if (!T2ShopWidgets.isCartWidgetEnabled()) return;
    try {
      const line = await T2ShopWidgets.cart.addProduct({
        productId: "YOUR_PRODUCT_ID_OR_SLUG",
        variantId: "YOUR_VARIANT_ID",
        quantity: 1,
      });
      console.log(line.name, line.quantityInCart);
      T2ShopWidgets.cart.open();
    } catch (e) {
      console.error(e);
    }
  }

  // Optional — browse the public catalog (GET /api/public/v1/products)
  async function loadProducts() {
    const { items, total } = await T2ShopWidgets.products.get({
      status: "ACTIVE",
      page: 1,
      pageSize: 24,
    });
    return { items, total };
  }

  // Optional — one product + variants (GET /api/public/v1/products/:id)
  async function loadProductDetail(slugOrId) {
    return T2ShopWidgets.products.getById(slugOrId);
  }
</script>
<button type="button" onclick="addToCart()">Add to cart</button>

Static HTML without a catalog call: you can pass name, price, and optional image on addProduct with productId (and variantId if needed) so the cart skips the extra product GET for the line label.

• apiBaseUrl — Your T2 Shop site origin (same host as the dashboard).
• storeId — From the dashboard (Store → Settings).
• widgets.cart — true for defaults, or an object: theme, ui (placement / size), disableFloatingButton (true hides the built-in FAB; use cart.open() from your own UI).

Your storefront origin must be allowed for the store (trusted origins / site URL).

See examples/static-html.html for a full static page (custom cart button, subscribe, getCurrentState).

T2ShopWidgets API

| Member | Role | |--------|------| | config(options) | Required once per page: { apiBaseUrl, storeId, widgets?: { cart } }. Mounts enabled widgets and configures the shared public HTTP client. | | create(options) | Same config shape; returns an instance (see below). | | isCartWidgetEnabled() | true if the cart widget was enabled in config. | | cart | Cart widget API (below). | | products | Catalog SDK (below). |

Cart — T2ShopWidgets.cart

| Method | Description | |--------|-------------| | addProduct(payload) | Async. Adds or merges a line. Resolve product/variant via public API, or pass name + price for a static snapshot. Returns line details; throws on error (use try/catch). | | open() / close() | Cart drawer. | | getCurrentState() | Read-only snapshot: items, totalQuantity, subtotal, isDrawerOpen, isCheckoutOpen. Empty when the cart is disabled. | | subscribe(listener) | Runs when cart state changes; returns unsubscribe. Pair with getCurrentState() for custom badges when the FAB is hidden. |

Catalog — T2ShopWidgets.products

| Method | Description | |--------|-------------| | get(params?) | GET /api/public/v1/products — pagination (page, pageSize 1–100), search, status (ACTIVE / DRAFT / ARCHIVED). | | getById(idOrSlug) | Single product with variants[] for addProduct({ variantId }). |

Bundler / npm import

import { createT2ShopWidgets } from "@t2devs/t2shop-widget";

const shop = createT2ShopWidgets({
  apiBaseUrl: "https://YOUR_T2SHOP_ORIGIN",
  storeId: "YOUR_STORE_ID",
  widgets: { cart: true },
});

await shop.cart.addProduct({ productId: "…", variantId: "…", quantity: 1 });
await shop.products.get({ page: 1, pageSize: 24 });

createT2ShopWidgets returns a dedicated products client per instance. The cart runtime is still one per page; call shop.mountCart(...) if you did not pass widgets.cart in the constructor (last mount wins).

Recommended: one module exports a single createT2ShopWidgets result and import that everywhere (singleton).

License

Licensed under T2 Shop — use and redistribution follow T2 Shop’s terms for the SaaS product. Documentation: t2-shop.com/docs.