@fireworkhq/web-sdk-types

TypeScript type definitions for the Firework Web SDK.

Install

npm install --save-dev @fireworkhq/web-sdk-types

Usage

Import types

import type {
  EventType,
  Api_Video,
  Api_Product,
  FwnSDK,
  CartUpdatedCallback,
} from '@fireworkhq/web-sdk-types';

Window & JSX augmentation

To get typed window._fwn and <fw-player> JSX elements, add a triple-slash reference or import the globals entry:

/// <reference types="@fireworkhq/web-sdk-types/globals" />

or in a .d.ts file:

import '@fireworkhq/web-sdk-types/globals';

This augments the global Window interface with _fwn: FwnSDK, adds all fw-* web components to JSX.IntrinsicElements on both the global JSX namespace (React 18 and below) and the one React 19 exports, and augments DocumentEventMap so document.addEventListener hands you a typed event.detail for every event in FwEventPayloadMap.

The globals entry has to be loaded explicitly, once, somewhere your tsconfig.json picks up — a root .d.ts file, or a layout or entry module. Pointing at the package with "types": "./index.d.ts" alone does not apply it.

Examples

Listen to custom events:

With the globals entry loaded, event.detail is typed for you — no cast, and a typo in a field name is a compile error:

/// <reference types="@fireworkhq/web-sdk-types/globals" />

document.addEventListener('fw:video:start', (e) => {
  console.log('Playing:', e.detail.video?.caption);
  console.log('At:', e.detail.extra?.progress);
});

The detail shape for a given event is also exported directly, which is useful when the handler is defined elsewhere:

import type { FwEventDetail } from '@fireworkhq/web-sdk-types';

function onVideoStart(detail: FwEventDetail<'fw:video:start'>) {
  console.log(detail.video?.caption, detail.widget_id);
}

Two caveats. Only the events in FwEventPayloadMap are typed; the rest still arrive as a plain Event and need the old cast:

import type { WidgetRenderOutcomeDetail } from '@fireworkhq/web-sdk-types';

document.addEventListener('fw:widget:render-outcome', (e) => {
  const detail = (e as CustomEvent<WidgetRenderOutcomeDetail>).detail;
  if (detail.status === 'empty') console.log('No videos for', detail.type);
});

And a misspelled event name still compiles, because addEventListener accepts any string by design. To get a compile error on the name itself, annotate it with EventType first:

import type { EventType } from '@fireworkhq/web-sdk-types';

const started: EventType = 'fw:video:start';

Configure shopping cart:

/// <reference types="@fireworkhq/web-sdk-types/globals" />

document.addEventListener('fw:ready', () => {
  window._fwn.shopping.configureCart({ url: '/cart', currency: 'USD' });
  window._fwn.shopping.onCartUpdated(async ({ productUnit, quantity }) => {
    await api.updateCart(productUnit.unit_ext_id, quantity);
    return quantity;
  });
});

Use web components in JSX/TSX:

/// <reference types="@fireworkhq/web-sdk-types/globals" />

export const VideoFeed = () => (
  <fw-embed-feed channel="demo" mode="row" per_page="6" />
);

What's included

| Category | Key types | |---|---| | Events | EventType, EventTypeReady, WidgetRenderOutcomeDetail | | Event payloads | FwEventPayloadMap, FwEventDetail, FwEventSessionEnvelope, FwPlayerInjectedFields | | Video | Api_Video, Api_Video_Type, FlowInteraction | | Product | Api_Product, Api_Product_Unit, Api_Product_Image | | Feed | Api_Feed, Api_Feed_FeedItem, FeedApiParams | | Interaction | Api_Interaction, Api_Video_InteractionTypeEnum | | Shopping | CartConfiguration, CartUpdatedCallback, ProductsLoadedCallback | | SDK | FwnSDK, FwnPlayer, FwnWidget, FwnShoppingApi | | Builders | ProductBuilder, ProductUnitBuilder, ProductImageBuilder | | Interrupts | PlayerInterruptEvent, WidgetInterruptEvent | | Elements | FwPlayerProps, FwEmbedFeedProps, FwStoryblockProps, … |

Versioning

The Firework Web SDK is loaded from the CDN without a version, so every site runs whatever fwn.js is currently live. These types describe that current runtime rather than any pinned SDK build, which means the useful thing to do is stay on the latest release:

npm install --save-dev @fireworkhq/web-sdk-types@latest

The package version is plain semver and describes changes to the types:

| Change | Bump | |---|---| | An exported member is removed, renamed, or retyped incompatibly | major | | A new exported member or optional property is added | minor | | Docs, comments, or a correction that does not change the surface | patch |

Maintaining

The published surface in index.d.ts is hand-written, and a conformance suite keeps it honest: every exported type is asserted against the runtime type it describes in src/, so the two cannot drift apart unnoticed.

yarn typecheck      # compiles the published types, and usage.ts against them
yarn conformance    # fails if the published types no longer match src/
yarn drift-report   # key-by-key breakdown of what differs

usage.ts exercises the published types the way a consumer sees them — only index.d.ts and globals.d.ts, nothing from src/. The globals entry augments Window and DocumentEventMap, which collides with the app's own declarations of both, so it cannot be loaded into the conformance program.

CI runs the conformance suite on changes to src/** as well as to this package, so a change to a runtime type that invalidates a published type fails the pull request that introduces it.

Because the types describe a curated subset, a runtime type may carry fields this package deliberately does not expose; that is allowed. What is not allowed is exposing a field the runtime does not have, or typing an exposed field differently from the runtime.

Publishing

Publishing runs from GitHub Actions on a published GitHub release, using npm trusted publishing (OIDC), so no token secret is involved and provenance is attached automatically.

packages/web-sdk-types/package.json is the single source of truth for the published version: bump it in the pull request that changes the types. A CI check enforces this. The publish job is a no-op when that version already exists on npm, so unrelated releases do not republish the package.

To publish outside of a release, run the workflow manually (Actions → 📦 web-sdk-types → Run workflow); it publishes whatever version package.json currently declares.

One-time setup

Trusted publishing cannot perform a package's first publish: the trusted publisher is configured in the package's settings on npmjs.com, and those settings only exist once the package does. So before the workflow can work, someone with publish rights on the @fireworkhq scope has to:

1. Publish the initial version manually — npm publish --access public from this directory, after npm login.
2. On npmjs.com, open Settings for @fireworkhq/web-sdk-types and add a trusted publisher: repository loopsocial/zeffo, workflow web-sdk-types.yml, no environment.

Every publish after that runs from CI with no token.