persuit-sdk

Browser SDK for sending storefront and ecommerce events to Persuit.

The package can be installed from the public npm registry or loaded directly from npm-backed CDNs such as unpkg and jsDelivr.

Install

npm install persuit-sdk

pnpm add persuit-sdk

Codex Skill

The npm package includes the install-ui-sdk Codex skill for adding Persuit tracking to storefronts.

npx persuit-sdk install-skill

To update an existing local copy, run:

npx persuit-sdk install-skill --force

The command installs the skill into ${CODEX_HOME:-~/.codex}/skills/install-ui-sdk.

Module Usage

import { init } from "persuit-sdk";

const persuit = init({
  workspaceId: "workspace_x",
  endpoint: "https://api.example.com/v1/events",
});

await persuit.pageViewed();
await persuit.productAddedToCart({
  product_id: "sku_123",
  quantity: 1,
  value: 49,
  currency: "USD",
});

CDN Usage

Pin the package version in production.

<script src="https://unpkg.com/[email protected]"></script>
<script>
  const persuit = window.Persuit.init({
    workspaceId: "workspace_x",
    endpoint: "https://api.example.com/v1/events",
  });

  persuit.pageViewed();
</script>

jsDelivr also works:

<script src="https://cdn.jsdelivr.net/npm/[email protected]"></script>

Configuration

init({
  workspaceId: "workspace_x",
  endpoint: "https://api.example.com/v1/events",
  debug: false,
  requestTimeoutMs: 5000,
  cidTtlMs: 7 * 24 * 60 * 60 * 1000,
});

• workspaceId is required and safe to expose in browser code.
• endpoint defaults to /v1/events on the current origin.
• debug logs failed sends to the browser console.
• requestTimeoutMs controls the ingestion request timeout.
• cidTtlMs controls how long a cid query parameter is persisted.

Events

The client exposes helpers for standard ecommerce events:

await persuit.pageViewed();
await persuit.productViewed({ product_id: "sku_123" });
await persuit.productAddedToCart({ product_id: "sku_123", quantity: 1 });
await persuit.productRemovedFromCart({ product_id: "sku_123", quantity: 1 });
await persuit.cartViewed({ cart_id: "cart_123" });
await persuit.checkoutStarted({ cart_id: "cart_123" });
await persuit.checkoutCompleted({ checkout_id: "checkout_123" });
await persuit.paymentInfoAdded({ checkout_id: "checkout_123" });
await persuit.orderCompleted({ order_id: "order_123", value: 49 });
await persuit.orderCancelled({ order_id: "order_123" });
await persuit.productSearched({ query: "shoes" });
await persuit.collectionViewed({ collection_id: "summer" });

Identify contact details as soon as they are known, even before the store has a stable user id:

await persuit.identify({
  email: "[email protected]",
  name: "Maria Silva",
});

When a stable user id is available, include it with the same contact details. The SDK sends user_id, email, and phone as identifiers on this and later events; profile fields such as name are sent as event properties.

await persuit.identify({
  user_id: "user_123",
  email: "[email protected]",
  phone: "+5511999999999",
  name: "Maria Silva",
  plan: "starter",
});

The legacy identify(userId, traits) form is still supported:

await persuit.identify("user_123", {
  plan: "starter",
});

Send custom events with custom(name, properties). The SDK adds the custom: prefix when it is omitted.

await persuit.custom("coupon_applied", {
  coupon: "WELCOME10",
});

Avoid sending passwords, payment tokens, raw card data, or unnecessary personal data in event properties.

Types

The package includes TypeScript declarations and exports the public event types.

import type { EventName, EventProperties, PersuitClient } from "persuit-sdk";

Publishing

The package is configured for public npm publishing with publishConfig.access = "public".

pnpm --filter persuit-sdk test
npm pack --dry-run
npm publish --access public