> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cesto.co/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript API

> The Cesto loader class: construct once, call invest() inside a click handler, hold the session.

`@cesto/web-sdk` exports one class and one helper. This page covers the class; the helper
is documented under [Script tag](https://docs.cesto.co/web-sdk/script-tag.md).

```bash theme={null}
npm install @cesto/web-sdk
```

```ts theme={null}
import { Cesto, bindInvestButtons } from '@cesto/web-sdk';
```

The package ships ESM, CJS, and an IIFE bundle, is side-effect free, and has no runtime
dependencies beyond the protocol types.

## `new Cesto(config)`

```ts theme={null}
const cesto = new Cesto({
  apiKey: 'cesto_pk_your_key',
  theme: { scheme: 'dark' },          // default for every invest() from this instance
});
```

| Option | Type | Default | Meaning |
| - | - | - | - |
| `apiKey` | `string` | — | **Required.** Publishable key (`cesto_pk_…`). Public by design |
| `baseUrl` | `string` | `https://app.cesto.co` | Invest app origin |
| `theme` | `InvestTheme` | — | Default theme; per-call values override it field by field |

The constructor throws if `apiKey` is missing, and throws if `baseUrl` is not a `cesto.co`
origin (or `localhost` / `127.0.0.1` for development). Constructing also warms DNS and TLS
to the app origin, so the first open doesn't pay the handshake — build the instance at
module scope, not inside the click handler.

Reuse one instance per key. It tracks the currently open session, so a second `invest()`
call while one is open focuses the existing surface instead of opening a second one.

## `cesto.invest(options)`

Opens the invest flow and returns an [`InvestSession`](#investsession).

```ts theme={null}
button.addEventListener('click', () => {
  const session = cesto.invest({
    basket: 'golden-age',
    amountUsd: 100,
    mode: 'dialog',
    theme: { accent: '#00CC55' },
    onSuccess: (e) => analytics.track('invest', e),
    onError: (e) => console.error(e.code, e.message),
    onClose: () => setPending(false),
  });
});
```

| Option | Type | Default | Meaning |
| - | - | - | - |
| `basket` | `string` | — | **Required.** Basket slug, or product UUID |
| `amountUsd` | `number` | — | USD prefill. Validated against the basket minimum inside the flow |
| `mode` | `'dialog' \| 'popup'` | `'dialog'` | Presentation. See [Modes](https://docs.cesto.co/web-sdk/modes.md) |
| `theme` | `InvestTheme` | — | Merged over the constructor default, field by field |
| callbacks | — | — | See [Events](https://docs.cesto.co/web-sdk/events.md) |

> [!WARNING]
>
> Call `invest()` **synchronously** inside the click handler. In popup mode it calls
> `window.open` directly, and in dialog mode the
> [popup fallback](https://docs.cesto.co/web-sdk/modes.md#automatic-popup-fallback) may need to. An `await` or a
> timer between the click and the call breaks the user-gesture chain and the browser blocks
> the window.

### `InvestSession`

```ts theme={null}
interface InvestSession {
  focus(): void;   // brings the popup window forward; focuses the iframe in dialog mode
  close(): void;   // tears down the surface and fires onClose (once)
  readonly isOpen: boolean;
}
```

`close()` only dismisses the surface. An execution already in flight continues server-side
— closing the dialog is not a cancel.

> [!NOTE]
>
> If the popup was blocked *and* the fallback navigation ran, `invest()` returns an inert
> session: `isOpen` is `false` and `focus()` / `close()` do nothing. There is no window left
> to control. See [Troubleshooting](https://docs.cesto.co/web-sdk/troubleshooting.md#the-popup-was-blocked).

## `bindInvestButtons(options)`

Declarative binding for `[data-cesto-invest]` elements. Returns the number of elements
newly bound. Full reference: [Script tag](https://docs.cesto.co/web-sdk/script-tag.md#binding-manually).

## Types

Every type is exported for your own signatures:

```ts theme={null}
import type {
  CestoConfig,
  InvestOptions,
  InvestMode,          // 'dialog' | 'popup'
  InvestTheme,
  InvestSession,
  InvestCallbacks,
  InvestSuccessEvent,        // { basket, amountUsd, status }
  InvestScheduledEvent,      // { basket, scheduledFor }
  InvestErrorEvent,          // { code, message }
  InvestVerifiedEvent,       // { partner }
  InvestPositionClosedEvent, // { basket, positionId?, status }
  InvestHandoffEvent,        // { reason }
  BindInvestButtonsOptions,
} from '@cesto/web-sdk';
```

## A complete example

```ts theme={null}
import { Cesto, type InvestSuccessEvent } from '@cesto/web-sdk';

// Module scope: constructed once, warms the connection before any click.
const cesto = new Cesto({
  apiKey: import.meta.env.VITE_CESTO_PK,
  theme: { accent: '#00CC55', background: '#091313', scheme: 'dark' },
});

const button = document.querySelector<HTMLButtonElement>('#invest')!;
const status = document.querySelector<HTMLElement>('#status')!;

function onInvested(event: InvestSuccessEvent) {
  status.textContent = `Invested $${event.amountUsd} in ${event.basket}.`;
  analytics.track('cesto_invest_success', event);
}

button.addEventListener('click', () => {
  button.setAttribute('aria-busy', 'true');

  cesto.invest({
    basket: button.dataset.basket!,
    amountUsd: 100,
    onVerified: ({ partner }) => console.debug('[cesto] verified for', partner),
    onSuccess: onInvested,
    onScheduled: ({ scheduledFor }) => {
      status.textContent = scheduledFor
        ? `Market closed — queued for ${new Date(scheduledFor).toLocaleString()}.`
        : 'Market closed — queued for the next open.';
    },
    onError: ({ code, message }) => {
      status.textContent = `Something went wrong (${code}).`;
      console.error('[cesto]', code, message);
    },
    // Fires on dismissal, including after a success. Never treat it as failure.
    onClose: () => button.removeAttribute('aria-busy'),
  });
});
```

## Next

> [card] [Events](https://docs.cesto.co/web-sdk/events.md)
>
> Every callback, its payload, and how often it fires.

> [card] [Modes](https://docs.cesto.co/web-sdk/modes.md)
>
> Dialog vs popup, the fallback, and the login handoffs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.