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

# Cards.js API Reference

> Every exported type, class, component, and hook in @dakota-xyz/cards-js and its React binding

<Warning>
  **Cards is available in sandbox only while we finish development.** Dakota enables Cards per
  account. The Cards endpoints are in the [API reference](/api-reference/introduction), marked
  **Sandbox only**. Endpoints, fields, and flows can still change before release.
</Warning>

The package has three entry points:

* `@dakota-xyz/cards-js` — the framework-free core.
* `@dakota-xyz/cards-js/react` — the React binding. It needs `react >= 18`.
* `@dakota-xyz/cards-js/styles.css` — the default stylesheet.

This page documents the public surface. For task-oriented guidance, see the [integration guide](/documentation/cards/cards-js/integration-guide) and [theming](/documentation/cards/cards-js/theming).

## `@dakota-xyz/cards-js` (core)

### `class DakotaCards`

The client. Create one per app and reuse it.

```ts theme={null}
new DakotaCards(options: DakotaCardsOptions)
```

| Member | Signature | Description |
| - | - | - |
| `cardDetails` | `(options?: CardDetailsOptions) => CardDetailsHandle` | Create a card-details handle. |

```ts theme={null}
interface DakotaCardsOptions {
  environment: Environment;   // 'sandbox' | 'production'
  fetchSession: FetchSession; // client-wide default; overridable per handle
}
```

### `class CardDetailsHandle`

Controls one card. Get it from `cards.cardDetails(...)` — you do not construct it yourself.

| Member | Signature | Description |
| - | - | - |
| `state` | `get state(): CardDetailsState` | Current lifecycle state. |
| `mount` | `(targets: CardFieldTargets) => Promise<void>` | Paint the masked face into the target nodes. Call once. No network. |
| `reveal` | `() => Promise<void>` | Mint a session and show the real values. Resolves once revealed. |
| `mask` | `() => void` | Re-mask a revealed card. No-op unless the state is `revealed`. |
| `on` | `<K extends keyof CardDetailsEvents>(event: K, handler: (p: CardDetailsEvents[K]) => void) => () => void` | Subscribe. Returns an unsubscribe function. |
| `destroy` | `() => void` | Tear down all frames and listeners. Terminal. |

```ts theme={null}
type CardDetailsState = 'idle' | 'mounting' | 'masked' | 'revealing' | 'revealed' | 'destroyed';

type CardField = 'pan' | 'cvv' | 'expiryMonth' | 'expiryYear';
type CardFieldTargets = Partial<Record<CardField, string | HTMLElement>>; // CSS selector or element

interface CardDetailsOptions {
  last4?: string;                 // shown in the masked PAN placeholder
  fetchSession?: FetchSession;    // overrides the client default for this handle
  theme?: CardTheme;              // text styles propagated into the value frames
  autoMaskMs?: number;            // upper bound on the reveal window
  strings?: Partial<CardStrings>; // i18n overrides
}
```

### Events

`CardDetailsEvents` maps each event name to its payload.

| Event | Payload | Fires when |
| - | - | - |
| `ready` | `void` | The masked face has mounted. |
| `revealing` | `void` | A reveal attempt started. Drive your loading treatment from this event. |
| `revealed` | `void` | The real values are showing. |
| `masked` | `void` | The card returned to the masked face: `mask()` was called, or a reveal attempt failed. |
| `expired` | `void` | The reveal window ended and the SDK auto-masked. |
| `copied` | `CopiedPayload` | The cardholder copied a field. |
| `error` | `unknown` | **Reserved** — held for future out-of-band failures, and never emitted in this version. All current errors reject the returned promise or, for `invalid_theme`, throw from `cardDetails()`. See [Errors](#errors). |

```ts theme={null}
interface CopiedPayload { field: CardField; success: boolean; }
```

<Note>
  Errors are **not** delivered as events. `mount()` and `reveal()` reject with a `DakotaCardsError`, so handle them with `try/catch`. `cardDetails()` throws `invalid_theme` synchronously when a `theme` value is not concrete.
</Note>

### Sessions

```ts theme={null}
type FetchSession = (ctx: SessionRequestContext) => Promise<RevealSession>;

interface SessionRequestContext {
  sessionType: SessionType;
  origin: string; // window.location.origin at reveal time
}

interface RevealSession {
  session: string;
  expiresAt: string; // RFC 3339
  provider?: string; // reserved; omit
}

type SessionType = 'card_details';
type Environment = 'sandbox' | 'production';
```

### Errors

```ts theme={null}
class DakotaCardsError extends Error {
  readonly code: ErrorCode;
  readonly retryable: boolean;
  readonly diagnosticId?: string; // upstream request id, when available
}

function isDakotaCardsError(e: unknown): e is DakotaCardsError;

type ErrorCode =
  | 'session_fetch_failed'
  | 'session_rejected'
  | 'origin_mismatch'
  | 'mount_target_not_found'
  | 'invalid_state'
  | 'invalid_theme'
  | 'reveal_failed';
```

The SDK creates these errors. You catch them — you do not construct them. See the [error-code table](/documentation/cards/cards-js/integration-guide#error-codes) for when each code occurs and which codes are retryable.

### Theming & strings types

```ts theme={null}
interface CardTheme {
  color?: string;
  fontFamily?: string;
  fontSize?: string;
  fontWeight?: string;
  letterSpacing?: string;
}

interface CardStrings {
  validThru: string;
  cvvLabel: string;
  panPlaceholder: string; // e.g. '•••• •••• •••• {last4}'
  revealedAnnouncement: string;
  maskedAnnouncement: string;
}
```

See [theming](/documentation/cards/cards-js/theming) for defaults and behaviour.

## `@dakota-xyz/cards-js/react`

The React entry point re-exports `DakotaCards`, `CardDetailsHandle`, and the card types its own signatures use. Import `FetchSession`, the error types, and the theming types from the core entry point.

### `<DakotaCardsProvider>`

Supplies a `DakotaCards` client to the component tree.

```tsx theme={null}
<DakotaCardsProvider client={client}>{children}</DakotaCardsProvider>
```

```ts theme={null}
function DakotaCardsProvider(input: { client: DakotaCards; children: ReactNode }): JSX.Element;
```

### `useDakotaCards()`

```ts theme={null}
function useDakotaCards(): DakotaCards;
```

Returns the client from the nearest provider. Throws if it is used outside one.

### `<CardDetails>` and `useCardDetails`

`<CardDetails>` renders the `.dk-card` recipe and exposes reveal and mask through a ref.

```tsx theme={null}
const CardDetails: ForwardRefExoticComponent<CardDetailsProps & RefAttributes<CardDetailsHandleRef>>;

interface CardDetailsProps extends CardDetailsOptions {
  fields?: CardField[]; // which fields to bind; defaults to all four
  className?: string;
}

interface CardDetailsHandleRef {
  reveal: () => Promise<void>;
  mask: () => void;
}
```

`<CardDetails>` always renders all four value slots and their captions from the `.dk-card` recipe. `fields` only selects which of those slots the SDK **binds** — mounts the masked face into, and reveals. Slots you omit still render, as empty captioned placeholders. To render a genuinely partial layout, with fewer slots on the page, use the headless `useCardDetails` hook and lay out only the fields you want.

`useCardDetails` is the headless form: you render the recipe yourself and wire the refs.

```ts theme={null}
function useCardDetails(options?: CardDetailsOptions & { fields?: CardField[] }): UseCardDetailsResult;

interface UseCardDetailsResult {
  readonly refs: Partial<Record<CardField, RefCallback<HTMLElement>>>;
  readonly state: CardDetailsState;
  readonly handle: { readonly current: CardDetailsHandle | null };
  readonly reveal: () => Promise<void>;
  readonly mask: () => void;
}
```

When you render your own markup, some CSS rules are load-bearing. See [Custom markup](/documentation/cards/cards-js/theming#custom-markup-the-headless-hook).