@foir/sdk 0.1.0

package/README.md

@@ -0,0 +1,110 @@
+# @foir/sdk
+
+Official Foir SDK — client-agnostic typed GraphQL transport, customer auth,
+progressive media, content rendering, realtime collaboration, and editor/server
+helpers for building apps on the [Foir](https://foir.dev) platform.
+
+The SDK is split into independent subpath exports so consumers only pull what
+they use. Everything heavy (`react`, `graphql`, `yjs`, `hls.js`, …) is an
+optional peer dependency gated to the subpath that needs it.
+
+## Install
+
+```sh
+pnpm add @foir/sdk
+# plus the peers for the subpaths you use, e.g.:
+pnpm add graphql            # for @foir/sdk/client + @foir/sdk/auth
+pnpm add react              # for @foir/sdk (editor), /media, /content
+pnpm add yjs y-websocket    # for @foir/sdk/realtime
+```
+
+## Subpath exports
+
+| Import | What it is | Peers |
+| --- | --- | --- |
+| `@foir/sdk` | Editor iframe client — `EditorProvider`, `useEditor`, `useAutoResize`, `createPlatformClient`, host↔editor message protocol | `react` |
+| `@foir/sdk/client` | Client-agnostic GraphQL transport for SSR/edge loaders — `foirRequest`, `isFoirPreview`, `absolutiseFoirMediaUrl` | `graphql` |
+| `@foir/sdk/auth` | Framework-agnostic customer auth — login/register/OTP/provider flows, token lifecycle (`SessionAdapter`), `authedRequest`, guards | `graphql` |
+| `@foir/sdk/server` | Server-side helpers for extension/config API backends — `createServerClient`, `verifyWebhookSignature`, `verifyScopedToken`, callback client | — |
+| `@foir/sdk/media` | Progressive media — `ProgressiveMedia`, `BlurhashCanvas`, `useProgressiveLoad`, variant-tier adapters | `react` (`hls.js`, `blurhash` optional) |
+| `@foir/sdk/content` | Content-rendering primitives — `createContentRenderer` block dispatch + Lexical `RichTextRenderer` | `react` |
+| `@foir/sdk/realtime` | Thin collaboration helper over `y-websocket` — canonical room addressing, presence, token refresh | `yjs`, `y-websocket` |
+| `@foir/sdk/codegen` | Build-time graphql-codegen preset (`foirCodegen`) + exhaustive block-registry plugin | `@graphql-codegen/cli`, `@graphql-codegen/client-preset` (devDeps) |
+
+## Usage
+
+### Typed GraphQL from a server loader
+
+`foirRequest` is a typed `fetch` wrapper, not a GraphQL client: it carries the
+Foir-specific transport concerns (`x-api-key`, preview schema channel, error
+shape) and runs generated `TypedDocumentNode`s. Bring-your-own-client consumers
+(Apollo/urql/react-query) use the generated documents directly and replicate
+those headers.
+
+```ts
+import { foirRequest, type FoirEnv } from '@foir/sdk/client';
+import { HomePageDocument } from './generated/graphql';
+
+export async function loader({ context }: LoaderArgs) {
+  const env: FoirEnv = {
+    PLATFORM_API_URL: context.env.PLATFORM_API_URL,
+    PLATFORM_API_KEY: context.env.PLATFORM_API_KEY,
+  };
+  const data = await foirRequest(env, HomePageDocument, { slug: 'home' });
+  return data.homePage;
+}
+```
+
+### Customer auth
+
+```ts
+import {
+  loginWithPassword,
+  authedRequest,
+  type SessionAdapter,
+} from '@foir/sdk/auth';
+import { MyProfileDocument } from './generated/graphql';
+
+// SessionAdapter = { get, set, delete } over your session store (cookie, KV…).
+const customer = await loginWithPassword(adapter, env, { email, password });
+
+// Bearer-authed request with automatic refresh-and-retry on expired sessions.
+const { myProfile } = await authedRequest(adapter, env, MyProfileDocument);
+```
+
+### Codegen
+
+```ts
+// codegen.ts
+import { foirCodegen } from '@foir/sdk/codegen';
+
+export default foirCodegen({
+  apiUrl: process.env.PLATFORM_API_URL!,
+  apiKey: process.env.PLATFORM_API_KEY!,
+  // documents: 'app/graphql/foir/**/*.graphql' (default)
+  // outputDir: './app/gql/foir/' (default)
+});
+```
+
+### Editor extensions
+
+```tsx
+import { EditorProvider, useEditor } from '@foir/sdk';
+
+function App() {
+  return (
+    <EditorProvider>
+      <MyEditor />
+    </EditorProvider>
+  );
+}
+
+function MyEditor() {
+  const { init, client } = useEditor(); // record context + platform GraphQL client
+  // ...
+}
+```
+
+## License
+
+MIT

package/dist/auth.d.ts

@@ -0,0 +1,305 @@
+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>;
+
+export { type AuthProviderPublic, AuthProvidersDocument, type CustomerAuthResult, CustomerLoginDocument, CustomerLoginOTPDocument, CustomerLoginWithProviderDocument, CustomerProviderCallbackDocument, CustomerProviderVerifyOTPDocument, CustomerRefreshTokenDocument, CustomerRegisterDocument, CustomerRequestOTPDocument, type FoirAuthTokens, type FoirCustomer, type FoirUser, type HostedLoginConfig, type HostedSession, type ProviderCallbackInput, type ProviderLoginInput, type ProviderLoginResult, type ProviderOTPVerifyInput, type RequireAdminOptions, type RequireAuthOptions, type SessionAdapter, authedRequest, clearSession, customerLogin, customerLoginOTP, customerLoginWithProvider, customerProviderCallback, customerProviderVerifyOTP, customerRefreshToken, customerRegister, customerRequestOTP, fetchHostedSession, getAuthProviders, getSessionCustomer, getSessionToken, hostedLoginUrl, loginWithOTP, loginWithPassword, refreshSession, registerWithPassword, requireAdmin, requireAuth, saveSession };