@foir/sdk 0.5.0 → 0.7.0

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.7.0",
   "description": "Official Foir SDK — editor iframe client + server-side platform helpers",
   "type": "module",
   "publishConfig": {
@@ -14,39 +14,47 @@
       "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": {
@@ -63,7 +71,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "CHANGELOG.md"
   ],
   "keywords": [
     "foir",
@@ -136,8 +145,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",

package/dist/auth.d.ts

@@ -1,382 +0,0 @@
-import { TypedDocumentNode } from '@graphql-typed-document-node/core';
-
-/**
- * Foir GraphQL client — a single typed fetch wrapper for SSR/edge loaders.
- *
- * No GraphQL client (Apollo/urql) required: the Foir public API is a plain
- * `POST` with an `x-api-key` header, and the dominant consumers (Hydrogen on
- * Oxygen, React Router loaders, TanStack Start on CF Workers) fetch in
- * server-only loaders and render — so Apollo's `InMemoryCache`/`useQuery`
- * reactivity is dead weight, and a shared cache on a stateless multi-tenant
- * edge worker is a cross-tenant hazard. This helper carries only the
- * Foir-specific transport concerns (auth header, preview schema channel,
- * error shape). Consumers on a GraphQL client (Apollo / urql / react-query /
- * graphql-request) use the generated `TypedDocumentNode`s directly with their
- * own client and replicate the two Foir-specific headers below — the
- * `x-api-key` and, in preview, `X-Foir-Schema-Channel: draft`.
- *
- * Deduplicates the hand-copied `lib/foir/client.ts` that shipped identically
- * across the Foir storefronts.
- */
-
-interface FoirEnv {
-    PLATFORM_API_URL?: string;
-    PLATFORM_API_KEY?: string;
-    PLATFORM_PREVIEW_API_KEY?: string;
-    FOIR_PREVIEW?: string;
-}
-
-/**
- * Foir customer-auth GraphQL operations + result types.
- *
- * These are PLATFORM-STABLE primitives — `customerLogin`/`customerRegister`/
- * `customerRefreshToken`/OTP/provider login are fixed-shape operations served
- * by api-public for every project (gated per-project by the password/OTP/
- * provider flags, but identical in shape when present). Unlike per-project
- * model types, they don't vary by configured models, so the SDK owns the
- * documents directly rather than relying on the consumer's codegen.
- *
- * The project-specific customer PROFILE (e.g. `myProfile.isAdmin`) is NOT here
- * — that shape varies per project, so it stays consumer-injected (see
- * `requireAuth`'s `resolveUser`).
- */
-
-/** The common auth result every login/register/refresh mutation returns. */
-interface CustomerAuthResult {
-    token: string;
-    refreshToken: string;
-    customerId: string;
-    email: string;
-}
-/** Result of initiating a provider login — a redirect URL or an inline token. */
-interface ProviderLoginResult {
-    /** OAuth/OIDC authorization URL to redirect the user to (redirect flows). */
-    redirectUrl: string | null;
-    /** Inline access token (non-redirect provider flows). */
-    token: string | null;
-}
-/** A configured auth provider, as exposed to unauthenticated callers. */
-interface AuthProviderPublic {
-    key: string;
-    name: string;
-    /** OAUTH2 | TOKEN_SSO | SAML | OIDC | EXTERNAL */
-    type: string;
-    isDefault: boolean | null;
-}
-interface ProviderLoginInput {
-    providerKey: string;
-    email?: string;
-    returnTo?: string;
-    /** Override the provider's default redirect_uri (must be allow-listed). */
-    redirectUri?: string;
-}
-interface ProviderCallbackInput {
-    providerKey: string;
-    code?: string;
-    state?: string;
-    email?: string;
-    idToken?: string;
-}
-interface ProviderOTPVerifyInput {
-    providerKey: string;
-    email: string;
-    otp: string;
-}
-declare const CustomerLoginDocument: TypedDocumentNode<{
-    customerLogin: CustomerAuthResult;
-}, {
-    email: string;
-    password: string;
-}>;
-declare const CustomerRegisterDocument: TypedDocumentNode<{
-    customerRegister: CustomerAuthResult;
-}, {
-    email: string;
-    password: string;
-}>;
-declare const CustomerRefreshTokenDocument: TypedDocumentNode<{
-    customerRefreshToken: CustomerAuthResult;
-}, {
-    refreshToken: string;
-}>;
-declare const CustomerRequestOTPDocument: TypedDocumentNode<{
-    customerRequestOTP: boolean;
-}, {
-    email: string;
-}>;
-declare const CustomerLoginOTPDocument: TypedDocumentNode<{
-    customerLoginOTP: CustomerAuthResult;
-}, {
-    email: string;
-    otp: string;
-}>;
-declare const CustomerLoginWithProviderDocument: TypedDocumentNode<{
-    customerLoginWithProvider: ProviderLoginResult;
-}, {
-    input: ProviderLoginInput;
-}>;
-declare const CustomerProviderCallbackDocument: TypedDocumentNode<{
-    customerProviderCallback: CustomerAuthResult;
-}, {
-    input: ProviderCallbackInput;
-}>;
-declare const CustomerProviderVerifyOTPDocument: TypedDocumentNode<{
-    customerProviderVerifyOTP: CustomerAuthResult;
-}, {
-    input: ProviderOTPVerifyInput;
-}>;
-declare const AuthProvidersDocument: TypedDocumentNode<{
-    authProviders: AuthProviderPublic[];
-}, Record<string, never>>;
-
-/**
- * Foir customer auth — framework-agnostic flows, token lifecycle, and guards.
- *
- * Session I/O is injected via {@link SessionAdapter} (no Hydrogen/React-Router
- * coupling). Pre-login flows authenticate with the project `x-api-key`;
- * post-login reads add the customer bearer. The project-specific profile (e.g.
- * `isAdmin`) is resolved by a consumer-supplied `resolveUser` — the SDK never
- * hardcodes the per-project customer profile shape.
- */
-
-/** An access token + its rotating refresh token. */
-interface FoirAuthTokens {
-    token: string;
-    refreshToken: string;
-}
-/** The customer identity carried by an auth result. */
-interface FoirCustomer {
-    id: string;
-    email: string;
-}
-/** The resolved customer for a guarded surface. */
-interface FoirUser {
-    id: string;
-    email: string;
-    isAdmin: boolean;
-}
-/**
- * Injected session store. Methods may be sync or async so consumers can plug
- * in a cookie session (Hydrogen/Remix), a KV store, etc.
- */
-interface SessionAdapter {
-    get(key: string): string | null | undefined | Promise<string | null | undefined>;
-    set(key: string, value: string): void | Promise<void>;
-    unset(key: string): void | Promise<void>;
-}
-/** Login with email + password. Requires the project to have passwords enabled. */
-declare function customerLogin(env: FoirEnv, vars: {
-    email: string;
-    password: string;
-}): Promise<CustomerAuthResult>;
-/** Register a new customer with email + password. */
-declare function customerRegister(env: FoirEnv, vars: {
-    email: string;
-    password: string;
-}): Promise<CustomerAuthResult>;
-/** Request a one-time password be emailed to the customer. */
-declare function customerRequestOTP(env: FoirEnv, email: string): Promise<boolean>;
-/** Complete an OTP login. */
-declare function customerLoginOTP(env: FoirEnv, vars: {
-    email: string;
-    otp: string;
-}): Promise<CustomerAuthResult>;
-/** Rotate an access token using a refresh token. */
-declare function customerRefreshToken(env: FoirEnv, refreshToken: string): Promise<CustomerAuthResult>;
-/**
- * Initiate provider (OAuth/OIDC) login — returns a `redirectUrl` to send the
- * user to, or an inline `token` for non-redirect providers.
- */
-declare function customerLoginWithProvider(env: FoirEnv, input: ProviderLoginInput): Promise<ProviderLoginResult>;
-/** Complete a provider login from the OAuth callback (`code`/`state`). */
-declare function customerProviderCallback(env: FoirEnv, input: ProviderCallbackInput): Promise<CustomerAuthResult>;
-/** Verify an OTP issued by an external provider. */
-declare function customerProviderVerifyOTP(env: FoirEnv, input: ProviderOTPVerifyInput): Promise<CustomerAuthResult>;
-/** List the project's configured auth providers (for a login UI). */
-declare function getAuthProviders(env: FoirEnv): Promise<AuthProviderPublic[]>;
-/** Persist an auth result to the session; returns the customer identity. */
-declare function saveSession(adapter: SessionAdapter, result: CustomerAuthResult): Promise<FoirCustomer>;
-/** Clear all Foir auth keys from the session. */
-declare function clearSession(adapter: SessionAdapter): Promise<void>;
-/** Read the stored access token (null when signed out). */
-declare function getSessionToken(adapter: SessionAdapter): Promise<string | null>;
-/** Read the stored customer identity (null when signed out). */
-declare function getSessionCustomer(adapter: SessionAdapter): Promise<FoirCustomer | null>;
-/** Login with email + password and persist the session. */
-declare function loginWithPassword(adapter: SessionAdapter, env: FoirEnv, vars: {
-    email: string;
-    password: string;
-}): Promise<FoirCustomer>;
-/** Register with email + password and persist the session. */
-declare function registerWithPassword(adapter: SessionAdapter, env: FoirEnv, vars: {
-    email: string;
-    password: string;
-}): Promise<FoirCustomer>;
-/** Complete an OTP login and persist the session. */
-declare function loginWithOTP(adapter: SessionAdapter, env: FoirEnv, vars: {
-    email: string;
-    otp: string;
-}): Promise<FoirCustomer>;
-/**
- * Refresh the access token from the stored refresh token, persisting the
- * rotated pair. Returns the new tokens, or null when there's no refresh token
- * or the refresh fails (the session is cleared in that case).
- */
-declare function refreshSession(adapter: SessionAdapter, env: FoirEnv): Promise<FoirAuthTokens | null>;
-/**
- * Run a bearer-authed GraphQL operation with refresh-with-retry: uses the
- * stored access token, and on a 401-shaped failure (rejected/expired bearer)
- * attempts a single token refresh and retries once. Any other error — network
- * blips, server errors, validation — propagates without a retry so transient
- * mutation failures can't be duplicated. Throws the original error if there's
- * no refresh path.
- */
-declare function authedRequest<TData, TVariables>(adapter: SessionAdapter, env: FoirEnv, document: TypedDocumentNode<TData, TVariables>, variables?: TVariables): Promise<TData>;
-interface RequireAuthOptions {
-    /**
-     * Resolve the full {@link FoirUser} (including the project-specific
-     * `isAdmin`) from the session identity. Typically runs the project's
-     * `myProfile` query via {@link authedRequest}. Defaults to `isAdmin: false`.
-     */
-    resolveUser?: (ctx: {
-        token: string;
-        customer: FoirCustomer;
-    }) => FoirUser | Promise<FoirUser>;
-    /**
-     * Called when there's no valid session — throw your framework's redirect
-     * (e.g. `throw redirect(loginUrl)`). Must not return.
-     */
-    onUnauthenticated: () => never | Promise<never>;
-}
-/**
- * Require a signed-in customer. Resolves the {@link FoirUser} via
- * `resolveUser` (or a minimal identity), or invokes `onUnauthenticated` when
- * there's no session.
- */
-declare function requireAuth(adapter: SessionAdapter, options: RequireAuthOptions): Promise<FoirUser>;
-interface RequireAdminOptions extends RequireAuthOptions {
-    /** Called when the user is authenticated but not an admin. Must not return. */
-    onForbidden: () => never | Promise<never>;
-}
-/** Require a signed-in customer who is also an admin. */
-declare function requireAdmin(adapter: SessionAdapter, options: RequireAdminOptions): Promise<FoirUser>;
-
-/**
- * Hosted-login bridge — for storefronts that delegate sign-in to a Foir
- * white-label front door (the `customerLoginWithFoir` flow) instead of
- * rendering their own login UI.
- *
- * The front door sets a first-party session cookie on the registrable domain;
- * because that domain is shared, the cookie reaches the storefront, which
- * exchanges it server-side for a short-lived customer bearer + identity. The
- * cookie is the durable credential (re-exchanged on bearer expiry) — there's
- * no separate refresh token in this flow.
- *
- * Every URL/cookie/path is CONFIG, not a constant, so a domain restructure
- * is a config change, not a code change.
- */
-interface HostedLoginConfig {
-    /** White-label front-door origin, e.g. `https://login.example.com`. */
-    loginOrigin: string;
-    /** Session cookie name set on the registrable domain. Default `foir_customer_session`. */
-    cookieName?: string;
-    /** Session-exchange path on the front door. Default `/session/token`. */
-    sessionPath?: string;
-}
-/**
- * Build the redirect URL to the hosted front door, forwarding a best-effort
- * absolute `returnTo` (honoured if the front door supports it).
- */
-declare function hostedLoginUrl(config: HostedLoginConfig, returnTo?: string): string;
-/** The identity + bearer returned by a successful hosted-session exchange. */
-interface HostedSession {
-    token: string;
-    customerId: string;
-    email: string;
-}
-/**
- * Exchange the hosted-login cookie on an incoming request for a customer
- * bearer + identity (server-to-server: forwards the cookie to the front
- * door's session endpoint with the CSRF header). Returns null when there's no
- * cookie or it's expired/revoked.
- */
-declare function fetchHostedSession(request: Request, config: HostedLoginConfig): Promise<HostedSession | null>;
-
-/**
- * Foir-hosted first-party sessions, from the browser — the model for a
- * backend-less SPA (Vite, CRA, a static site) that wants no tokens in JS.
- *
- * The sibling `fetchHostedSession` in ./hosted does the same exchange from a
- * SERVER: it reads the cookie off an incoming request and forwards it by hand.
- * A browser cannot set a `Cookie` header, so that function is unusable from an
- * SPA by construction. This one lets the browser send the cookie the only way it
- * can — `credentials: 'include'` — and keeps the resulting bearer in memory.
- *
- * How the pieces divide:
- *
- *   cookie  — long-lived (30d), HttpOnly, first-party on your registrable
- *             domain, set by Foir when hosted login finalizes. JS cannot read
- *             it, so XSS cannot exfiltrate it.
- *   bearer  — 15 minutes, held in a closure here. Never written to
- *             localStorage/sessionStorage/IndexedDB, never in a cookie of ours.
- *
- * There is no refresh token in this flow. Re-exchanging the cookie IS the
- * refresh, which is why nothing here needs rotation or reuse-detection: the
- * durable credential is an opaque server-side session handle, revocable at any
- * time from the admin panel or `signOut()`.
- *
- * REQUIRES a verified custom login domain that shares a registrable domain with
- * your app (app.acme.com + login.acme.com). That is what makes the cookie
- * first-party and lets `SameSite=Lax` send it. The same endpoints exist on
- * api.foir.dev but a browser cannot reach them there — the cookie would be
- * cross-site, and that CORS surface deliberately refuses credentials.
- */
-interface FoirSessionConfig {
-    /**
-     * Your verified custom login domain, e.g. `https://login.acme.com`. Must share
-     * a registrable domain with the app calling it.
-     */
-    loginOrigin: string;
-    /** Session-exchange path. Default `/session/token`. */
-    sessionPath?: string;
-    /** Logout path. Default `/session/logout`. */
-    logoutPath?: string;
-    /** Seconds before expiry to re-exchange. Default 60. */
-    refreshSkewSeconds?: number;
-    /**
-     * Called when the session goes away — the cookie expired, was revoked, or
-     * `signOut()` ran. Use it to redirect to `signInUrl()`.
-     */
-    onSignOut?: () => void;
-}
-/** The identity behind the current session. */
-interface FoirSessionUser {
-    customerId: string;
-    email: string;
-}
-interface FoirSessionClient {
-    /**
-     * The current access token, exchanging or re-exchanging the cookie as needed.
-     * Null when there is no session. Concurrent callers share one in-flight
-     * exchange. Call this before each API request — do not cache the result.
-     */
-    getToken(): Promise<string | null>;
-    /** The signed-in customer, or null. Exchanges if the session isn't loaded yet. */
-    getUser(): Promise<FoirSessionUser | null>;
-    /** Revoke the session server-side and clear the cookie. Idempotent. */
-    signOut(): Promise<void>;
-    /** Where to send the browser to sign in. */
-    signInUrl(returnTo?: string): string;
-    /** Observe session changes. Returns an unsubscribe function. */
-    subscribe(listener: (user: FoirSessionUser | null) => void): () => void;
-    /** Cancel the refresh timer. Call on unmount. */
-    destroy(): void;
-}
-/**
- * Create a session client. Safe to call during SSR — it does nothing until a
- * method is invoked, and `getToken()` on the server returns null rather than
- * throwing (there is no cookie jar to draw on).
- */
-declare function createFoirSessionClient(config: FoirSessionConfig): FoirSessionClient;
-
-export { type AuthProviderPublic, AuthProvidersDocument, type CustomerAuthResult, CustomerLoginDocument, CustomerLoginOTPDocument, CustomerLoginWithProviderDocument, CustomerProviderCallbackDocument, CustomerProviderVerifyOTPDocument, CustomerRefreshTokenDocument, CustomerRegisterDocument, CustomerRequestOTPDocument, type FoirAuthTokens, type FoirCustomer, type FoirSessionClient, type FoirSessionConfig, type FoirSessionUser, type FoirUser, type HostedLoginConfig, type HostedSession, type ProviderCallbackInput, type ProviderLoginInput, type ProviderLoginResult, type ProviderOTPVerifyInput, type RequireAdminOptions, type RequireAuthOptions, type SessionAdapter, authedRequest, clearSession, createFoirSessionClient, customerLogin, customerLoginOTP, customerLoginWithProvider, customerProviderCallback, customerProviderVerifyOTP, customerRefreshToken, customerRegister, customerRequestOTP, fetchHostedSession, getAuthProviders, getSessionCustomer, getSessionToken, hostedLoginUrl, loginWithOTP, loginWithPassword, refreshSession, registerWithPassword, requireAdmin, requireAuth, saveSession };