![Nami SDK logo](https://cdn.namiml.com/brand/sdk/Nami-SDK@0.5x.png)

# Nami Web SDK

Nami is easy subscriptions & in-app purchases, with powerful built-in paywalls and A/B testing.

 This library helps you easily offer in-app purchases and subscriptions.
  - No IAP code to write.
  - Focus on your app experience.
  - All edge cases are handled and no server is required.
  - Includes is powerful built-in paywalls templates
  - Update paywalls easily using a browser-based paywall CMS.
  - Conduct paywall A/B tests, to improve your conversion rate.
  - Robust subscription analytics, webhooks, and much more.

Requires an account with Nami ML. See https://www.namiml.com/pricing for more details and to create a free account.

## Getting started with Nami's Web SDK

### Install the Web SDK in your project

You can install the SDK via NPM or Yarn

```
npm install @namiml/web-sdk --save
```

```
yarn add @namiml/web-sdk
```

Example apps showing how to use the SDK are available in our [Nami Web SDK repo](https://github.com/namiml/nami-web-sdk).

More information on configuring and using the SDK is available in our docs at [https://learn.namiml.com](https://learn.namiml.com).

## Testing

Unit tests live in `tests/unit/` and mirror the `src/` directory structure. Run them with:

```bash
yarn test
```

### Test infrastructure

The suite uses two transformers side-by-side, each with a distinct role:

| Tool | Role | What it handles |
|---|---|---|
| **ts-jest** | TypeScript transformer | All `.ts` test files and source files — compiles TypeScript to CommonJS for Jest |
| **babel-jest** | JavaScript transformer | Third-party ESM packages from `node_modules` (Lit, `@open-wc`, `@esm-bundle/chai`, `lodash-es`, etc.) that Jest cannot run as-is because they ship as native ES modules |
| **@open-wc/testing** | Web Component test utilities | `fixture()` for rendering Lit components into a real jsdom DOM, `elementUpdated()` for awaiting Lit update cycles, and semantic DOM diff assertions (`expect(el).dom.to.equal(…)`) |

`transformIgnorePatterns` in `jest.config.mjs` lists the packages that babel-jest must transform (all others in `node_modules` are skipped). `babel.config.jest.cjs` configures the babel presets and plugins used for those transformations.

### Strategy for new tests

- **Pure logic** (services, repositories, utilities, managers): use ts-jest only. Import the class under test directly. No `@open-wc/testing` needed.
- **Web Components** (anything in `src/components/`): use `fixture()` from `@open-wc/testing` to mount the component in jsdom and `elementUpdated()` to wait for Lit's render cycle before asserting. See any existing file in `tests/unit/components/` for the pattern.
- Do not add new packages to `transformIgnorePatterns` without also verifying that `babel.config.jest.cjs` can transform them. New ESM-only packages may require additional babel plugins.

## Legacy support

To support older browsers, import our side-effect module before you import the SDK. It installs the necessary polyfills and shims, allowing the main entry point to stay the same for every app.

- ESM:
  ```js
  import '@namiml/web-sdk/legacy-support';
  import { Nami } from '@namiml/web-sdk';
  ```
- CommonJS:
  ```js
  require('@namiml/web-sdk/legacy-support');
  const { Nami } = require('@namiml/web-sdk');
  ```

Modern apps that do not target legacy environments can simply import the default entry:

```js
import { Nami } from '@namiml/web-sdk';
```

This keeps the modern bundle slim, while letting you opt into additional support only when you need it.