JavaScript API

@cesto/web-sdk exports one class and one helper. This page covers the class; the helper is documented under Script tag.

npm install @cesto/web-sdk

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)`

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.

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
`theme`	`InvestTheme`	—	Merged over the constructor default, field by field
callbacks	—	—	See Events

Call invest() synchronously inside the click handler. In popup mode it calls window.open directly, and in dialog mode the 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`

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.

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.

`bindInvestButtons(options)`

Declarative binding for [data-cesto-invest] elements. Returns the number of elements newly bound. Full reference: Script tag.

Types

Every type is exported for your own signatures:

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

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'),
  });
});

Events

Every callback, its payload, and how often it fires.

Modes

Dialog vs popup, the fallback, and the login handoffs.

Get started

Widgets

Web SDK

Server SDK

JavaScript API

`new Cesto(config)`

`cesto.invest(options)`

`InvestSession`

`bindInvestButtons(options)`

Types

A complete example

Next

Events

Modes

​new Cesto(config)

​cesto.invest(options)

​InvestSession

​bindInvestButtons(options)

​Types

​A complete example

​Next

Events

Modes

`new Cesto(config)`

`cesto.invest(options)`

`InvestSession`

`bindInvestButtons(options)`

Types

A complete example

Next