# SDK

The SDK connects a published Plandalf offer to your own site. You can load its browser script and use HTML attributes, call the `Plandalf` class from `@plandalf/sdk`, or use `@plandalf/react`. The examples use the same offer slugs and checkout flow. [Choose an integration](https://plandalf.com/docs/guides) if you want a complete example first.

## How a checkout works

1. Publish an offer and keep its slug.
2. Open it with `present()` or render it inline with `mount()`. An HTML `data-plandalf-present` button is wired to `present()` by the browser bundle.
3. The call returns a handle. `present()` can be awaited for a [`FlowResult`](https://plandalf.com/docs/packages/sdk/interfaces/FlowResult); the handle also exposes events and `close()`. `mount()` resolves when the inline flow is ready.
4. Confirm the purchase on your server before granting access, sending tickets, or fulfilling an order.

The browser bundle initializes itself and scans `data-plandalf-*` elements when it loads. For direct calls, `plandalf.ready()` runs your callback after initialization. The package class is initialized with your organization's `apiBase`; React supplies that class through `PlandalfProvider`.

```javascript title="browser-checkout.js" lineNumbers lineNumberStart=1 highlight="2-3"
plandalf.ready(async () => {
  const handle = plandalf.present('upgrade')
  const result = await handle

  if (result.status === 'complete') {
    // Confirm access on your server before granting it.
  }
})
```

## Browser functions

Open any function below for its arguments, types, return value, source, and a code example. This list is checked against [Numi's browser entrypoint](https://github.com/plandalf/numi/blob/fc6f42b5ade3d63b71623934838a6509f17203e2/packages/sdk/src/browser.ts) when the reference is generated.

| Function | What it does |
| --- | --- |
| [`plandalf.identify()`](https://plandalf.com/docs/sdk/identify) | Set the current visitor identity. |
| [`plandalf.reset()`](https://plandalf.com/docs/sdk/reset) | Clear the current visitor identity. |
| [`plandalf.getAnonId()`](https://plandalf.com/docs/sdk/getAnonId) | Read the anonymous visitor ID. |
| [`plandalf.present()`](https://plandalf.com/docs/sdk/present) | Open an offer and get an awaitable flow handle. |
| [`plandalf.mount()`](https://plandalf.com/docs/sdk/mount) | Mount an offer in an element. |
| [`plandalf.addGate()`](https://plandalf.com/docs/sdk/addGate) | Register a named access gate. |
| [`plandalf.gate()`](https://plandalf.com/docs/sdk/gate) | Check access and present its fallback offer when needed. |
| [`plandalf.ready()`](https://plandalf.com/docs/sdk/ready) | Run a callback when the SDK instance is ready. |
| [`plandalf.promo()`](https://plandalf.com/docs/sdk/promo) | Open a live promo handle. |
| [`plandalf.from()`](https://plandalf.com/docs/sdk/from) | Find the live handle associated with an element. |

`setUser()` and `resetUser()` still work as aliases for `identify()` and `reset()`. `getInstance()` is an internal escape hatch for harnesses. The list above uses the current public names.

## Package class and React

The ES module [`Plandalf` class](https://plandalf.com/docs/packages/sdk/classes/Plandalf) supplies the underlying methods. Its reference includes `configure()`, `getIdentity()`, `getRef()`, `getSessionAge()`, `getUserToken()`, `preload()`, and `setRef()` alongside the checkout, promo, identity, and gate methods above. The class and browser object have different public surfaces: `plandalf.preload` is **not** on the browser object, and the browser `promo()` wrapper forwards only the slug.

The [React provider](https://plandalf.com/docs/packages/react/functions/PlandalfProvider) creates the SDK context for hooks such as [`usePresent()`](https://plandalf.com/docs/packages/react/functions/usePresent), [`useGate()`](https://plandalf.com/docs/packages/react/functions/useGate), and [`usePromo()`](https://plandalf.com/docs/packages/react/functions/usePromo). Their parameters and return types are in the React package sidebar. The [named SDK exports](https://plandalf.com/docs/packages/sdk) are listed under `@plandalf/sdk` in Packages.

For option fields and result shapes, open the relevant function above and follow its linked type, or browse [all package types](https://plandalf.com/docs/packages).

Source: https://plandalf.com/docs/sdk