npm package: @selwise/widget
Description: Selwise storefront widget runtime for CDN and npm integrations.
Latest version: 1.0.8

# @selwise/widget

Selwise storefront runtime for CDN and npm integrations.

## Install

```bash
npm install @selwise/widget
```

## Integration Models

- CDN script mode (auto-init, global runtime)
- npm instance mode (explicit lifecycle ownership)

## Quick Start (npm)

```ts
import Selwise from '@selwise/widget';

const widget = new Selwise();
await widget.init({
  siteKey: 'YOUR_SITE_KEY',
  apiUrl: 'https://api.selwise.com/api/v1',
  exposeGlobal: true,
});
```

## Quick Start (CDN)

```html
<script
  src="https://widget.selwise.com/client.js"
  data-site-key="YOUR_SITE_KEY"
  data-api-url="https://api.selwise.com/api/v1"
></script>
```

## Lifecycle Ownership

Use one shared instance per app shell in npm mode.

```ts
let widget: Selwise | null = null;

export async function ensureSelwise(siteKey: string, apiUrl: string) {
  if (widget) return widget;

  widget = new Selwise();
  await widget.init({ siteKey, apiUrl, exposeGlobal: true });
  return widget;
}

export function disposeSelwise() {
  widget?.destroy();
  widget = null;
}
```

## Public API Surface

| Method | Notes |
| --- | --- |
| `init(config)` | Initializes runtime config and identity state. |
| `destroy()` | Cleans up active runtime resources. |
| `track(name, args?)` | Sends canonical events through event queue. |
| `trackOrder(order)` | Sends order attribution payload. |
| `identify(userId, metadata?)` | Links visitor to known user identity. |
| `setTraits(traits)` | Updates profile traits without identity switch. |
| `getSiteUserId()` | Returns identified site user id if available. |
| `getVisitorId()` | Returns visitor id. |
| `getSessionId()` | Returns session id. |
| `getJourneyId()` | Returns active journey id or null. |
| `getJourneyState()` | Returns journey debug snapshot. |
| `endJourney()` | Rotates journey context. |
| `getVariant(experimentId)` | Returns assignment payload for experiment. |
| `getExperimentVariant(experimentId)` | Returns assigned variant id. |
| `getActiveExperiments()` | Returns active assignment list. |
| `pushDataLayer(data)` | Pushes structured data-layer payload. |
| `getDataLayer()` | Reads data-layer snapshot. |
| `getConsentState()` | Reads consent categories state. |
| `grantConsent(categories?)` | Grants selected consent categories. |
| `revokeConsent(categories?)` | Revokes selected consent categories. |

## Event Example

```ts
widget.track('product_view', {
  entityType: 'product',
  entityId: 'SKU-123',
  metadata: { productItemCode: 'SKU-123', title: 'Runner Pro', price: 149.9 },
});

await widget.trackOrder({
  orderId: 'ORDER-1001',
  currency: 'SITE_CURRENCY', // ISO-4217 uppercase (e.g. EUR, USD, TRY)
  total: 149.9,
  items: [{ productItemCode: 'SKU-123', quantity: 1, unitPrice: 149.9 }],
});
```

## Common Errors

1. `window.Selwise` missing in npm mode.
- Set `exposeGlobal: true` if global API compatibility is required.

2. Duplicate events/widgets.
- Multiple instances are being initialized in app shell.

3. `init()` appears no-op.
- Called in server runtime or with invalid/missing `siteKey`.

## Documentation

- [Installation](https://docs.selwise.com/getting-started/installation/)
- [Platform Playbooks](https://docs.selwise.com/getting-started/platform-playbooks/)
- [npm Integration](https://docs.selwise.com/getting-started/npm-integration/)
- [CDN Integration](https://docs.selwise.com/getting-started/cdn-integration/)
- [Public API](https://docs.selwise.com/client-api/public-api/)
- [Event Cookbook](https://docs.selwise.com/client-api/event-cookbook/)
- [Verification](https://docs.selwise.com/getting-started/verification/)
- [Troubleshooting](https://docs.selwise.com/getting-started/integration-troubleshooting/)

## License

MIT, see [LICENSE](./LICENSE).