@foir/sdk 0.5.0 → 0.8.0

package/dist/transport/foir-http.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Foir HTTP transport core — the `graphql`-free half of `graphql/foir-request.ts`.
+ *
+ * Everything here is shared by BOTH public data surfaces:
+ *
+ *   - `@foir/sdk/client` — `foirRequest`, which prints a `TypedDocumentNode` and
+ *     POSTs it to `/graphql`. Needs `graphql` for `print`.
+ *   - `@foir/sdk/data`   — `createFoirClient`, which prints a document from a
+ *     selection tree and must not pull `graphql` into a storefront bundle at
+ *     all. Printing a pre-resolved tree is string building.
+ *
+ * The split exists so the second one is possible. The Foir-specific transport
+ * concerns — which api key is in play, the preview schema channel header, the
+ * optional customer bearer, and the `FoirRequestError` shape — are identical on
+ * both, and duplicating them is exactly how the two surfaces would drift. So
+ * they live here once and `foir-request.ts` re-exports them unchanged; the only
+ * thing that stayed behind is the part that needs `print`.
+ *
+ * `fetch` only, no Node built-ins, and no module-level cache — the reasoning at
+ * the top of `graphql/foir-request.ts` applies verbatim: a shared cache on a
+ * stateless multi-tenant edge worker is a cross-tenant hazard.
+ */
+export interface FoirEnv {
+    PLATFORM_API_URL?: string;
+    PLATFORM_API_KEY?: string;
+    PLATFORM_PREVIEW_API_KEY?: string;
+    FOIR_PREVIEW?: string;
+}
+/**
+ * Returns true when `FOIR_PREVIEW=true` is set in the environment.
+ *
+ * Preview is selected at the environment level, not per-request: load a
+ * preview env file that sets `FOIR_PREVIEW=true` + a `sk_…`
+ * `PLATFORM_PREVIEW_API_KEY` with `drafts:read` instead of the default env.
+ * The site-wide mode keeps draft semantics consistent — every loader sees
+ * the same preview/published view of the world. Intended for non-production
+ * surfaces only.
+ */
+export declare function isFoirPreview(env: FoirEnv): boolean;
+/**
+ * The api key a request should carry for this env: the `sk_` preview key when
+ * `FOIR_PREVIEW=true` (it is the one with `drafts:read`), the `pk_` key
+ * otherwise. Returns `undefined` when neither is configured, so the caller can
+ * raise the "add them to .env" error with its own wording.
+ */
+export declare function resolveFoirApiKey(env: FoirEnv): string | undefined;
+/**
+ * The machine-readable codes Foir puts in `extensions.code`. Stable contract —
+ * the platform's own note on them says never rename — so branching on these is
+ * the supported way to tell one failure from another.
+ *
+ * Note what is NOT here: there is no code for a missing record. A read that
+ * finds nothing resolves the field to `null` with no `errors` entry at all,
+ * because an absent record is an answer rather than a failure. `NOT_FOUND` only
+ * appears when a mutation names something that does not exist.
+ */
+export type FoirErrorCode = 'INVALID_ARGUMENT' | 'NOT_FOUND' | 'ALREADY_EXISTS' | 'FAILED_PRECONDITION' | 'PERMISSION_DENIED' | 'UNAUTHENTICATED' | 'RATE_LIMITED' | 'TIMEOUT' | 'UNAVAILABLE' | 'CANCELED' | 'INTERNAL';
+export interface FoirErrorExtensions {
+    /** Stable machine-readable code. Branch on this, never on `message`. */
+    code?: FoirErrorCode | string;
+    /** Correlation id. Quote it in a support request. */
+    requestId?: string;
+    /** On `RATE_LIMITED`: whole seconds to wait. Never less than 1. */
+    retryAfter?: number;
+    [key: string]: unknown;
+}
+export interface FoirGraphQLErrorItem {
+    message: string;
+    path?: Array<string | number>;
+    extensions?: FoirErrorExtensions;
+}
+/** What the `X-RateLimit-*` headers said on the response that carried them. */
+export interface FoirRateLimitSnapshot {
+    /** Requests allowed per window for this credential. */
+    limit: number;
+    /** Requests left in the current window. */
+    remaining: number;
+    /** Unix seconds at which the window resets. */
+    resetAt: number;
+}
+export declare class FoirRequestError extends Error {
+    /** HTTP status code, when the request failed at the HTTP layer. */
+    readonly status?: number;
+    /** GraphQL errors, when the request failed with a no-data error envelope. */
+    readonly graphQLErrors?: ReadonlyArray<FoirGraphQLErrorItem>;
+    readonly cause?: unknown;
+    constructor(message: string, options?: {
+        cause?: unknown;
+        status?: number;
+        graphQLErrors?: ReadonlyArray<FoirGraphQLErrorItem>;
+    });
+    /**
+     * The code of the first error, if the response carried one.
+     *
+     * A getter rather than a stored field so it stays correct for an error
+     * constructed anywhere, including by a caller in a test.
+     */
+    get code(): FoirErrorCode | string | undefined;
+    /** The correlation id, if the response carried one. */
+    get requestId(): string | undefined;
+    /**
+     * Whether retrying this request could succeed.
+     *
+     * The 429 is the one that has to be in here and is easy to leave out: it sits
+     * among the 4xx statuses that are otherwise permanent, so a policy written as
+     * "retry 5xx, never retry 4xx" excludes exactly the failure that clears on its
+     * own. A storefront wrote that policy, its key saturated, and every read
+     * failed on the first attempt for an hour.
+     */
+    get retryable(): boolean;
+    /**
+     * How long to wait before retrying, in milliseconds, when the server said.
+     * Undefined when it did not, which means the caller picks its own backoff.
+     */
+    get retryAfterMs(): number | undefined;
+}
+/** True when the failure is Foir refusing on rate. */
+export declare function isFoirRateLimited(err: unknown): err is FoirRequestError;
+/**
+ * True when the credential was rejected. Distinguished from
+ * {@link isFoirRateLimited} because the two want opposite responses: a bad key
+ * is never going to start working, and retrying it just spends allowance.
+ */
+export declare function isFoirUnauthenticated(err: unknown): err is FoirRequestError;
+/** True when the credential is valid but not permitted to do this. */
+export declare function isFoirForbidden(err: unknown): err is FoirRequestError;
+/**
+ * True when a MUTATION named something that does not exist.
+ *
+ * Reads do not produce this. A read for a record that is not there resolves the
+ * field to `null` and returns no error at all, so `data.page === null` is the
+ * check for a missing page — not a catch.
+ */
+export declare function isFoirNotFound(err: unknown): err is FoirRequestError;
+/**
+ * Read the `X-RateLimit-*` headers off a response, when it carried them.
+ *
+ * The presence check is not defensive padding. `Number(null)` is 0, not NaN, so
+ * reading a missing header through `Number` alone yields a perfectly plausible
+ * snapshot saying zero requests remain — on every response from anything that
+ * does not set these headers, including a cache or a proxy in front of Foir. An
+ * app wired to warn on a low remaining count would then warn constantly, which
+ * is how a rate-limit alarm becomes noise people mute.
+ */
+export declare function readFoirRateLimit(headers: Headers): FoirRateLimitSnapshot | undefined;
+/**
+ * Seconds the server asked the caller to wait, from a 429's `Retry-After`
+ * header. Undefined when absent or unparseable.
+ *
+ * Read alongside `extensions.retryAfter`, which carries the same number in the
+ * body; the header is the one available when the body is unreadable.
+ */
+export declare function readFoirRetryAfterMs(headers: Headers): number | undefined;
+export interface FoirRequestOptions {
+    /**
+     * Customer bearer token. api-public still needs the `x-api-key` to resolve
+     * the project; the bearer adds the customer identity for self-scoped reads
+     * (e.g. `myProfile`). Used by `@foir/sdk/auth`'s post-login profile fetch.
+     */
+    bearerToken?: string;
+    /**
+     * Called with the `X-RateLimit-*` headers of every response, successful or
+     * not, and with `undefined` when a response carried none.
+     *
+     * Exists because those headers have always been on the wire and nothing has
+     * ever read them. A key can be at 200 of 10,000 remaining for twenty minutes
+     * before it starts refusing, and the only place that number appears is a
+     * header the SDK was throwing away. Log it, and you find out before your site
+     * does.
+     */
+    onRateLimit?: (snapshot: FoirRateLimitSnapshot | undefined) => void;
+}
+/**
+ * Supplies the current customer bearer. Sync or async so consumers can read a
+ * cookie session (Hydrogen/Remix), a KV store, an in-memory value, etc. Returns
+ * the token when signed in, or `null`/`undefined` when signed out.
+ *
+ * Lives here rather than beside `createFoirContentClient` because both data
+ * surfaces bind a session the same way, and a second copy of this alias is how
+ * they would end up accepting subtly different things.
+ */
+export type FoirTokenProvider = () => string | null | undefined | Promise<string | null | undefined>;
+export interface FoirHeaderInput {
+    apiKey: string;
+    /**
+     * Opt into the draft *schema* channel (`X-Foir-Schema-Channel: draft`) so
+     * freshly pushed model changes (new fields, new models) are visible at
+     * runtime — otherwise selections on draft-only fields are silently stripped
+     * and surface as confusing "fragment never used" errors. The header has no
+     * effect under public keys (the server ignores it), so it is safe to send
+     * whenever the caller is in preview.
+     */
+    draftChannel?: boolean;
+    bearerToken?: string;
+    /** Caller-supplied extras, applied last so a caller can override. */
+    extra?: Readonly<Record<string, string>>;
+}
+/**
+ * The exact header set every Foir data-plane request carries. Single
+ * definition on purpose: `/graphql` and `/cdn/graphql` authenticate identically,
+ * and a header that exists on one surface but not the other is a per-surface
+ * authorization difference nobody would notice until it mattered.
+ */
+export declare function buildFoirHeaders(input: FoirHeaderInput): Record<string, string>;
+/**
+ * Build a `/v1/...` URL from whatever the caller put in `apiUrl`.
+ *
+ * Tolerates the three things people actually pass: an origin, an origin with a
+ * trailing slash, and the conventional `PLATFORM_API_URL` value
+ * (`https://api.foir.dev/graphql`).
+ *
+ * Lives here rather than beside one of its callers because three surfaces now
+ * turn an `apiUrl` into a path on the API origin — `@foir/sdk/data`'s `/graphql`,
+ * `@foir/sdk/server`'s `/v1/events`, and anything that follows — and the
+ * tolerated inputs are a property of the config field, not of the endpoint. A
+ * second copy would accept a slightly different set, and the difference would
+ * only ever show up as one surface rejecting a `PLATFORM_API_URL` the other
+ * accepted. `data/transport.ts` re-exports it under its published name.
+ */
+export declare function foirApiEndpoint(apiUrl: string, path: `/${string}`): string;
+export interface FoirResponseEnvelope<T> {
+    data?: T;
+    errors?: Array<FoirGraphQLErrorItem>;
+}
+/**
+ * Unwrap a Foir `{ data, errors }` envelope.
+ *
+ * GraphQL can return partial data alongside errors; when data is present the
+ * errors are logged and the data returned (callers handle nulls), and we only
+ * throw when there is no data at all. Both Foir data-plane routes — `/graphql`
+ * and `/cdn/graphql` — hand their document to the same executor, so the two
+ * return this envelope and get the same treatment.
+ */
+export declare function readFoirEnvelope<T>(json: FoirResponseEnvelope<T>): T;

package/dist/transport/persisted-query.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Automatic persisted queries and the shared read lane — the `graphql`-free half
+ * of `graphql/cdn-route.ts`.
+ *
+ * Split out for the same reason `foir-http.ts` was split out of
+ * `graphql/foir-request.ts`: two surfaces need it and only one of them may
+ * import `graphql`. `@foir/sdk/client` prints a `TypedDocumentNode` and then
+ * hashes the text; `@foir/sdk/data` builds the text itself from a selection tree
+ * and must not drag the GraphQL parser into a storefront bundle. Everything
+ * below operates on a document STRING, so it belongs to neither.
+ *
+ * `graphql/cdn-route.ts` re-exports all of it unchanged, so that module's public
+ * surface is exactly what it always was; the only thing that stayed behind is
+ * the part that needs `print`.
+ */
+/**
+ * The shared, cacheable read path. Same schema, same executor, same auth as
+ * `/graphql` — what differs is that a CDN in front of the caller can store the
+ * response, because the request is a GET and the credential is in the URL.
+ */
+export declare const FOIR_CDN_GRAPHQL_PATH = "/cdn/graphql";
+/** The APQ handshake object, in Apollo's shape because every client uses it. */
+export declare function persistedQueryExtension(hash: string): {
+    persistedQuery: {
+        version: number;
+        sha256Hash: string;
+    };
+};
+/**
+ * Build the shared-endpoint URL for a read.
+ *
+ * The credential goes in the URL deliberately: a shared cache keys on the URL
+ * alone, so a key that rode only in a header would let two callers with
+ * different reach collide on one entry and be served each other's body. The
+ * server enforces this and names the refusal `NOT_SHAREABLE` with
+ * `condition: "credential"` when the key arrives only as a header.
+ */
+export declare function buildCdnUrl(endpoint: string, apiKey: string, hash: string, variables?: unknown): string;
+/**
+ * SHA-256 of the document text, hex encoded — the identity a persisted query is
+ * stored and retrieved under.
+ *
+ * Web Crypto rather than a bundled implementation: it is present in every
+ * runtime this SDK targets (workers, edge, Node 18+) and adds nothing to the
+ * caller's bundle. Reached through `globalThis`, never `import 'crypto'`, so
+ * the edge-safety assertion on `@foir/sdk/data`'s import graph still holds.
+ */
+export declare function documentHash(documentText: string): Promise<string>;
+/** The code the server answers with when it has never seen this hash. */
+export declare const PERSISTED_QUERY_NOT_FOUND = "PERSISTED_QUERY_NOT_FOUND";
+/** The code the shared endpoint refuses with, so a caller knows to retry. */
+export declare const NOT_SHAREABLE = "NOT_SHAREABLE";
+/**
+ * Whether a response carries any of the handshake codes above.
+ *
+ * The response is CLONED before the body is read. A Response body can only be
+ * consumed once, and reading it here to inspect the code would leave the caller
+ * holding an empty stream on every successful read — turning a working fast
+ * path into silent data loss.
+ *
+ * Status is deliberately not part of the test. A persisted-query miss comes back
+ * **HTTP 200** with an errors array (verified against deployed dev), while a
+ * shareability refusal comes back 400; keying on the code alone reads both.
+ *
+ * Several codes at once rather than one call per code, because both callers ask
+ * about two and each call costs another clone and another parse of the same body.
+ */
+export declare function hasFoirErrorCode(res: Response, ...codes: string[]): Promise<boolean>;

package/dist/transport/retry.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Retry for the Foir data plane.
+ *
+ * It lives in the SDK rather than in a docs snippet because the snippet was
+ * getting written wrong. The rule everyone reaches for — retry 5xx, never retry
+ * 4xx — is right about every 4xx except the one that matters: a 429 means the
+ * key has spent its hourly allowance, the request is fine, and it will succeed
+ * once the window moves. A storefront implemented that rule faithfully, covering
+ * 502/503/504 only, and when its key saturated every read failed on the first
+ * attempt for a full hour. The reads it failed were rendering pages, and the
+ * pages came out empty.
+ *
+ * So the policy is: retry on no-response, on 5xx, and on 429 — and when the
+ * server said how long to wait, wait that long instead of guessing.
+ */
+import { FoirRequestError } from './foir-http';
+export interface FoirRetryPolicy {
+    /**
+     * Total attempts including the first. 1 disables retrying without needing a
+     * separate flag, which is what makes "off" expressible in the same shape.
+     */
+    attempts?: number;
+    /** Base delay for exponential backoff, in ms. Default 200. */
+    baseDelayMs?: number;
+    /**
+     * Ceiling on any single wait, in ms. Default 20_000.
+     *
+     * A rate-limit window is an hour, so a `Retry-After` on a saturated key can
+     * be most of one — far longer than a page render can wait. Capping it means a
+     * retry is attempted rather than the caller blocking for 40 minutes, and if
+     * that attempt fails too the error surfaces, which is the honest outcome. A
+     * caller that genuinely can wait sets a larger cap.
+     */
+    maxDelayMs?: number;
+    /** Called before each wait. For logging; must not throw. */
+    onRetry?: (info: {
+        attempt: number;
+        delayMs: number;
+        error: FoirRequestError;
+    }) => void;
+    /** Injectable sleep, so tests do not spend real seconds. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * How long to wait before attempt N+1, or null when this error should not be
+ * retried at all.
+ *
+ * Exported so a caller running its own loop gets the same answer as the built-in
+ * one; two implementations of "is this worth retrying" is how the 429 gets left
+ * out of one of them.
+ */
+export declare function foirRetryDelayMs(error: unknown, attempt: number, policy?: FoirRetryPolicy): number | null;
+/**
+ * Run `fn`, retrying transient Foir failures.
+ *
+ * Deliberately takes a thunk rather than wrapping a specific request shape, so
+ * the same policy covers `/graphql`, `/cdn/graphql` and anything either grows
+ * later. Non-Foir errors propagate untouched on the first throw — this is not a
+ * general-purpose retry helper and should not become one.
+ */
+export declare function withFoirRetry<T>(fn: () => Promise<T>, policy?: FoirRetryPolicy): Promise<T>;

package/dist/types/index.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Public type definitions for the Editor SDK.
+ */
+export type { EditorPlacement } from '../server/types.js';
+/** Data provided by the host when the editor initializes. */
+export interface EditorInit {
+    values: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    modelKey: string;
+    recordId: string;
+    naturalKey?: string;
+    versionId: string | null;
+    variantKey: string | null;
+    locale: string | null;
+    schema: unknown;
+    mode: 'edit' | 'readonly';
+    theme: 'light' | 'dark';
+    /** Secret API key for public API access. */
+    apiKey: string;
+    /** Public API GraphQL endpoint URL (provided by host). */
+    apiUrl: string;
+    /** Config connection domain (e.g. my-store.myshopify.com) */
+    connectionDomain?: string;
+    /** How this editor is rendered in the admin UI. */
+    configMode?: 'editor' | 'sidebar';
+    /** Currently selected field keys (sidebar mode). */
+    selectedFieldKeys?: string[];
+    /** Available fields for selection (sidebar mode). */
+    selectableFields?: Array<{
+        key: string;
+        label: string;
+        type: string;
+    }>;
+    /** Locale context (sidebar mode). */
+    localeContext?: LocaleContext | null;
+}
+/** Locale context passed by the host for sidebar editors. */
+export interface LocaleContext {
+    currentLocale: string;
+    sourceLocale: string;
+    isTranslating: boolean;
+    locales: Array<{
+        code: string;
+        displayName: string;
+        isDefault: boolean;
+    }>;
+}
+/** Value exposed by the EditorProvider context. */
+export interface EditorContextValue {
+    /** Whether the editor has received init data from the host. */
+    isReady: boolean;
+    /** Initial data from the host (available after init). */
+    init: EditorInit | null;
+    /** Current host theme. */
+    theme: 'light' | 'dark';
+    /** Platform GraphQL client (available after init). */
+    client: PlatformClient;
+    /** Send complete form values to the host (full replacement). */
+    updateValues: (values: Record<string, unknown>) => void;
+    /** Send a single field update to the host. */
+    updateField: (path: string, value: unknown) => void;
+    /** Request the host to save the current values. */
+    requestSave: () => void;
+    /** Request the host to publish the current version. */
+    requestPublish: () => void;
+    /** Report iframe height for auto-resize. */
+    resize: (height: number) => void;
+    /** Report dirty state (unsaved changes). */
+    setDirty: (isDirty: boolean) => void;
+    /** Request the host to navigate to an admin path. */
+    requestNavigate: (path: string) => void;
+    /** Request the host to execute a platform operation. Returns the result.
+     * `mode` controls whether the platform waits for the operation to complete
+     * ('sync') or returns immediately after queueing ('async'). Defaults to 'sync'. */
+    requestOperation: (operationKey: string, input?: Record<string, unknown>, options?: {
+        mode?: 'sync' | 'async';
+    }) => Promise<{
+        success: boolean;
+        result?: unknown;
+        error?: {
+            code: string;
+            message: string;
+        };
+    }>;
+    /** Editor mode ('editor' or 'sidebar'). */
+    configMode: 'editor' | 'sidebar';
+    /** Currently selected field keys (sidebar mode). */
+    selectedFieldKeys: string[];
+    /** Available fields for selection (sidebar mode). */
+    selectableFields: Array<{
+        key: string;
+        label: string;
+        type: string;
+    }>;
+    /** Locale context (sidebar mode). */
+    localeContext: LocaleContext | null;
+}
+/** Options for creating a PlatformClient. */
+export interface PlatformClientOptions {
+    /** GraphQL endpoint URL. */
+    apiUrl: string;
+    /** API key for authentication. */
+    apiKey: string;
+}
+/** A minimal GraphQL error shape. */
+export interface GraphQLError {
+    message: string;
+    locations?: Array<{
+        line: number;
+        column: number;
+    }>;
+    path?: Array<string | number>;
+    extensions?: Record<string, unknown>;
+}
+/** Response shape from a GraphQL query/mutation. */
+export interface GraphQLResponse<T = Record<string, unknown>> {
+    data: T | null;
+    errors?: GraphQLError[];
+}
+/** Fetch-based GraphQL client for platform API calls. */
+export interface PlatformClient {
+    /** Execute a GraphQL query or mutation. */
+    query<T = Record<string, unknown>>(query: string, variables?: Record<string, unknown>): Promise<GraphQLResponse<T>>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foir/sdk",
-  "version": "0.5.0",
+  "version": "0.8.0",
   "description": "Official Foir SDK — editor iframe client + server-side platform helpers",
   "type": "module",
   "publishConfig": {
@@ -14,45 +14,61 @@
       "import": "./dist/index.js"
     },
     "./server": {
-      "types": "./dist/server.d.ts",
+      "types": "./dist/server/index.d.ts",
       "import": "./dist/server.js"
     },
     "./client": {
-      "types": "./dist/client.d.ts",
+      "types": "./dist/graphql/client.d.ts",
       "import": "./dist/client.js"
     },
+    "./data": {
+      "types": "./dist/data/index.d.ts",
+      "import": "./dist/data.js"
+    },
     "./media": {
-      "types": "./dist/media.d.ts",
+      "types": "./dist/media/index.d.ts",
       "import": "./dist/media.js"
     },
     "./content": {
-      "types": "./dist/content.d.ts",
+      "types": "./dist/content/index.d.ts",
       "import": "./dist/content.js"
     },
     "./auth": {
-      "types": "./dist/auth.d.ts",
+      "types": "./dist/auth/index.d.ts",
       "import": "./dist/auth.js"
     },
+    "./auth/session": {
+      "types": "./dist/auth/session-client.d.ts",
+      "import": "./dist/auth-session.js"
+    },
     "./react": {
-      "types": "./dist/react.d.ts",
+      "types": "./dist/react/index.d.ts",
       "import": "./dist/react.js"
     },
     "./next": {
-      "types": "./dist/next.d.ts",
+      "types": "./dist/next/index.d.ts",
       "import": "./dist/next.js"
     },
     "./push": {
-      "types": "./dist/push.d.ts",
+      "types": "./dist/push/index.d.ts",
       "import": "./dist/push.js"
     },
     "./realtime": {
-      "types": "./dist/realtime.d.ts",
+      "types": "./dist/realtime/index.d.ts",
       "import": "./dist/realtime.js"
     },
     "./codegen": {
       "types": "./dist/codegen/index.d.ts",
       "import": "./dist/codegen/index.js"
     },
+    "./codegen/item-registry": {
+      "types": "./dist/codegen/item-registry.d.ts",
+      "import": "./dist/codegen/item-registry.js"
+    },
+    "./codegen/item-scaffold": {
+      "types": "./dist/codegen/item-scaffold.d.ts",
+      "import": "./dist/codegen/item-scaffold.js"
+    },
     "./codegen/block-registry": {
       "types": "./dist/codegen/block-registry.d.ts",
       "import": "./dist/codegen/block-registry.js"
@@ -63,7 +79,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "CHANGELOG.md"
   ],
   "keywords": [
     "foir",
@@ -119,16 +136,20 @@
   },
   "devDependencies": {
     "@graphql-codegen/cli": "^5.0.7",
+    "@testing-library/react": "^16.2.0",
     "@types/react": "^19.2.0",
     "@types/react-dom": "^19.2.0",
+    "@types/ws": "^8.5.13",
     "blurhash": "^2.0.5",
     "graphql": "^16.10.0",
     "hls.js": "^1.6.16",
+    "jsdom": "^27.0.0",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "tsup": "^8.5.1",
     "typescript": "5.9.2",
     "vitest": "^3.2.4",
+    "ws": "^8.18.0",
     "y-websocket": "^3.0.0",
     "yjs": "^13.6.30"
   },
@@ -136,8 +157,9 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
+    "build": "tsup && tsc -p tsconfig.build.json && node scripts/assert-export-types.mjs && node scripts/assert-public-exports.mjs",
+    "snapshot:exports": "node scripts/assert-public-exports.mjs --update",
+    "dev": "node scripts/dev-watch.mjs",
     "check-types": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest watch",