Type Reference

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

Core SDK

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

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

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

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

i18n types

import type {
  Locale,
  PartialTranslationMessages,
  TranslationMessageKey,
} from "@fanfare-io/fanfare-sdk-react";

Use TranslationMessageKey to keep overrides aligned with SDK message keys.

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.

// 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 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.

Start Here

Core SDK

Components

Shopify

Examples

Reference

Core SDK

Journey types

Theme types

i18n types

Widget types

Shopify types

Public-only contract

​Core SDK

​Journey types

​Theme types

​i18n types

​Widget types

​Shopify types

​Public-only contract

Core SDK

Journey types

Theme types

i18n types

Widget types

Shopify types

Public-only contract