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

# Type Reference

> High-level public types used by SDK integrations.

This page summarizes the public types most customer integrations need. Use your editor's TypeScript support for the full generated definitions.

## Core SDK

```ts theme={null}
import type {
  FanfareConfig,
  FanfareSDK,
} from "@fanfare-io/fanfare-sdk-core";
```

| Type            | Purpose                                                                                     |
| --------------- | ------------------------------------------------------------------------------------------- |
| `FanfareConfig` | Initialization options for `init()` (the default export of `@fanfare-io/fanfare-sdk-core`). |
| `FanfareSDK`    | Main SDK instance with `auth`, `journeys`, `challenges`, `beacon`, and `destroy()`.         |

## Journey types

```ts theme={null}
import type {
  AccessCodeSubmitResult,
  JourneyHandle,
  JourneySnapshot,
  JourneyView,
  SequenceView,
  WaitlistAttachmentView,
} from "@fanfare-io/fanfare-sdk-core/experiences";
```

| Type                     | Purpose                                                                                                                                                                                                                                    |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `JourneyHandle`          | Handle returned by `sdk.journeys.get(experienceId)`.                                                                                                                                                                                       |
| `JourneyView`            | Primary UI and action surface.                                                                                                                                                                                                             |
| `JourneySnapshot`        | Serializable, discriminated snapshot read from `snapshot$` for client persistence, cross-tab restore, and diagnostics. Render from `view$` (`JourneyView`); actions live only on the view, never on the snapshot.                          |
| `SequenceView`           | Routed sequence render view, discriminated by `phase` (and `mechanism`). Exposes only the actions legal in the current phase — for example `enter()`, `bid()`, `book()`, or `claim()` — plus the live `display$` atom while participating. |
| `WaitlistAttachmentView` | Scheduled-phase attachment on a sequence view (`SequenceView.waitlist`). Carries `status` and `join()` / `leave()`; it never grants access and is cleared once the distribution opens.                                                     |
| `AccessCodeSubmitResult` | Result of `RoutedView.submitAccessCode(code)`: `{ outcome: "advanced"; sequenceId }`, `{ outcome: "unchanged" }`, or `{ outcome: "gated" }`. Only `"advanced"` commits the code.                                                           |

## Theme types

```ts theme={null}
import type {
  BrandTheme,
  WidgetVariant,
} from "@fanfare-io/fanfare-sdk-core/theme";
```

`WidgetVariant` is one of `default`, `retro`, `rounded`, or `clean`.

## i18n types

```ts theme={null}
import type {
  Locale,
  PartialTranslationMessages,
  TranslationMessageKey,
} from "@fanfare-io/fanfare-sdk-react";
```

Use `TranslationMessageKey` to keep overrides aligned with SDK message keys.

## Widget types

```ts theme={null}
import type {
  ExperienceRenderProps,
  ExperienceWidgetProps,
  ExperienceWidgetSlots,
} from "@fanfare-io/fanfare-sdk-react";
```

Use these when building wrappers around `ExperienceWidget` or sharing slot definitions across pages.

## Shopify types

The storefront integration types most Shopify (Hydrogen/Oxygen, Next, Remix) integrations need. These come from the SSR-safe root barrel, which imports zero React; the provider and hooks live in `@fanfare-io/fanfare-sdk-shopify/react`.

```ts theme={null}
// Isomorphic root barrel — the checkout vocabulary + config types.
import type {
  ClaimResult,
  FanfareGatedCheckoutResult,
  GatedLine,
  ProductGID,
  ShopifyProductRef,
  VariantGID,
} from "@fanfare-io/fanfare-sdk-shopify";
// React subpath — the hook surface.
import type {
  FanfareCartAdapter,
  FanfareClaimInput,
  FanfareGatedCheckoutInput,
  UseFanfareCheckoutResult,
} from "@fanfare-io/fanfare-sdk-shopify/react";
```

| Type                              | Purpose                                                                                                                                                                                                               |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GatedLine`                       | The purchase intent: `{ shopifyProductId, merchandiseId, quantity }`. `shopifyProductId` is a `ProductGID` (the gate's policy anchor); `merchandiseId` is a `VariantGID` (Shopify's `cartLinesAdd` id). Both branded. |
| `ProductGID` / `VariantGID`       | Branded Shopify GID strings; build with the `productGid` / `variantGid` constructors so a transposition fails to compile.                                                                                             |
| `FanfareGatedCheckoutResult`      | The closed result of `gatedCheckout`: success (`{ cart, checkoutUrl, expDate }`) or a typed failure (`code` / `retryable` / `kind`, plus `retry()` on `add_line_failed`).                                             |
| `FanfareCartAdapter<TCart>`       | Your cart I/O — `createCart` / `addLine` / `readCart` — passed to `useFanfareCheckout`.                                                                                                                               |
| `FanfareGatedCheckoutInput`       | `{ gatedLine, ungatedLines? }` — what to check out (only `gatedLine` is policy-checked).                                                                                                                              |
| `UseFanfareCheckoutResult<TCart>` | The `useFanfareCheckout` return: `{ gatedCheckout, claim, pending }`.                                                                                                                                                 |
| `FanfareClaimInput`               | `{ cartId, purchase }` — the object form of the advanced `claim`.                                                                                                                                                     |
| `ClaimResult`                     | The advanced `claim` result: `{ ok, expDate }` or `{ ok: false, reason }`.                                                                                                                                            |
| `ShopifyProductRef`               | `{ handle, id }` — how `useFanfareExperience` / `FanfareCheckoutGate` reference a product.                                                                                                                            |

See the [Shopify quickstart](/sdk/shopify/quickstart) for end-to-end setup.

## Public-only contract

The types above are the contract your application should depend on. Avoid reaching into internals or building behavior from fields that are not exported through these public package paths.