@foir/sdk 0.2.0 → 0.3.0

package/README.md

@@ -25,6 +25,8 @@ pnpm add yjs y-websocket    # for @foir/sdk/realtime
 | `@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/react` | Drop-in React auth — `<FoirProvider>`, `useFoirSession`/`useFoirUser`/`useFoirAuth`, `<SignIn>`, `<OAuthButtons>`, `<UserButton>` | `react`, `graphql` |
+| `@foir/sdk/next` | Next.js App Router BFF auth — `createFoirCookieAdapter`, `getFoirSession`, `foirSignIn*`, `completeFoirProviderLogin`, `createFoirMiddleware` | `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` |
@@ -72,6 +74,76 @@ const customer = await loginWithPassword(adapter, env, { email, password });
 const { myProfile } = await authedRequest(adapter, env, MyProfileDocument);
 ```
 
+### React
+
+`@foir/sdk/react` builds the reactive layer on top of `@foir/sdk/auth`. Wrap
+your app once, then read the session with hooks or drop in the components. The
+default session store is `localStorage`; pass your own `adapter` for cookies.
+
+```tsx
+'use client';
+import { FoirProvider, SignIn, UserButton, useFoirSession } from '@foir/sdk/react';
+
+const env = {
+  PLATFORM_API_URL: process.env.NEXT_PUBLIC_PLATFORM_API_URL,
+  PLATFORM_API_KEY: process.env.NEXT_PUBLIC_PLATFORM_API_KEY, // a publishable pk_ key
+};
+
+export function App() {
+  return (
+    <FoirProvider env={env}>
+      <Header />
+      <SignIn afterSignInUrl="/dashboard" />
+    </FoirProvider>
+  );
+}
+
+function Header() {
+  const { isAuthenticated, isLoading } = useFoirSession();
+  if (isLoading) return null;
+  return isAuthenticated ? <UserButton afterSignOutUrl="/" /> : null;
+}
+```
+
+For a custom form, use `useFoirAuth()` (`signIn`, `register`, `signInWithOtp`,
+`requestOtp`, `signInWithProvider`, `signOut`, `getToken`) and `useFoirUser()`.
+
+### Next.js (App Router, BFF)
+
+`@foir/sdk/next` keeps the tokens in HttpOnly cookies server-side. Protect
+routes with the middleware, read the session in a server component, and sign in
+from a route handler.
+
+```ts
+// middleware.ts
+import { createFoirMiddleware } from '@foir/sdk/next';
+export const middleware = createFoirMiddleware({ signInUrl: '/sign-in' });
+export const config = { matcher: ['/dashboard/:path*'] };
+```
+
+```ts
+// app/dashboard/page.tsx (Server Component)
+import { cookies } from 'next/headers';
+import { getFoirSession } from '@foir/sdk/next';
+
+export default async function Dashboard() {
+  const customer = await getFoirSession(await cookies());
+  return <p>Signed in as {customer?.email}</p>;
+}
+```
+
+```ts
+// app/sign-in/route.ts (Route Handler)
+import { cookies } from 'next/headers';
+import { foirSignInWithPassword } from '@foir/sdk/next';
+
+export async function POST(req: Request) {
+  const { email, password } = await req.json();
+  await foirSignInWithPassword({ env, store: await cookies(), email, password });
+  return Response.json({ ok: true });
+}
+```
+
 ### Codegen
 
 ```ts

package/dist/next.d.ts

@@ -0,0 +1,178 @@
+/**
+ * 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 — 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.
+ */
+
+/** The customer identity carried by an auth result. */
+interface FoirCustomer {
+    id: string;
+    email: string;
+}
+/**
+ * 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>;
+}
+
+/**
+ * The minimal cookie-store shape this adapter needs. It's satisfied by Next's
+ * `cookies()` (route handlers / server actions — `await cookies()` on Next 15),
+ * and by `NextResponse.cookies` in middleware. Kept structural on purpose so the
+ * SDK doesn't import (or pin a version of) `next/headers`.
+ */
+interface FoirCookieStore {
+    get(name: string): {
+        value: string;
+    } | undefined;
+    set(name: string, value: string, options?: Record<string, unknown>): void;
+    delete(name: string): void;
+}
+interface CookieAdapterOptions {
+    /** Cookie attributes for writes, merged over the secure defaults. */
+    cookieOptions?: Record<string, unknown>;
+}
+declare function foirCookieName(key: string): string;
+/**
+ * A {@link SessionAdapter} backed by an HttpOnly cookie store — the seam for
+ * server-side (BFF) Foir sessions in Next.js. Pass the cookie store from a route
+ * handler / server action (`await cookies()`) for reads and writes; a Server
+ * Component's `cookies()` is read-only, so use it only for reads there.
+ */
+declare function createFoirCookieAdapter(store: FoirCookieStore, opts?: CookieAdapterOptions): SessionAdapter;
+
+/**
+ * Server-side session helpers for the Next.js BFF pattern. Each takes the Next
+ * cookie store (`await cookies()` in a route handler / server action, or the
+ * read-only `cookies()` in a Server Component for reads).
+ *
+ * Note on "verification": the customer access token is opaque to your app and
+ * validated by the Foir API on use, so `getFoirSession` returns the identity
+ * stored in the cookies rather than locally verifying a JWT. A rejected/expired
+ * bearer surfaces when you call the API (and `@foir/sdk/auth`'s `authedRequest`
+ * transparently refreshes it).
+ */
+/** The signed-in customer from the session cookies, or null. */
+declare function getFoirSession(store: FoirCookieStore): Promise<FoirCustomer | null>;
+/** The current access token from the session cookies, or null. */
+declare function getFoirToken(store: FoirCookieStore): Promise<string | null>;
+/** Clear the session cookies (sign out). */
+declare function foirSignOut(store: FoirCookieStore, opts?: CookieAdapterOptions): Promise<void>;
+interface PasswordArgs {
+    env: FoirEnv;
+    store: FoirCookieStore;
+    email: string;
+    password: string;
+    cookieOptions?: CookieAdapterOptions['cookieOptions'];
+}
+/** Password sign-in in a route handler; persists the session to cookies. */
+declare function foirSignInWithPassword({ env, store, email, password, cookieOptions, }: PasswordArgs): Promise<FoirCustomer>;
+/** Register a customer in a route handler; persists the session to cookies. */
+declare function foirRegisterWithPassword({ env, store, email, password, cookieOptions, }: PasswordArgs): Promise<FoirCustomer>;
+/** Complete an OTP sign-in in a route handler; persists the session to cookies. */
+declare function foirSignInWithOtp({ env, store, email, otp, cookieOptions, }: {
+    env: FoirEnv;
+    store: FoirCookieStore;
+    email: string;
+    otp: string;
+    cookieOptions?: CookieAdapterOptions['cookieOptions'];
+}): Promise<FoirCustomer>;
+/**
+ * Complete a provider (OAuth/OIDC) login in your callback route handler:
+ * exchange the `code` + `state` for tokens and persist them to the session
+ * cookies. Returns the customer.
+ */
+declare function completeFoirProviderLogin(opts: {
+    env: FoirEnv;
+    store: FoirCookieStore;
+    providerKey: string;
+    code?: string;
+    state?: string;
+    cookieOptions?: CookieAdapterOptions['cookieOptions'];
+}): Promise<FoirCustomer>;
+
+/**
+ * The slice of `NextRequest` the middleware reads. Typed structurally so the SDK
+ * doesn't need `next` installed to build — a real `NextRequest` satisfies it, so
+ * the returned function drops straight into `export const middleware`.
+ */
+interface FoirMiddlewareRequest {
+    cookies: {
+        get(name: string): {
+            value: string;
+        } | undefined;
+    };
+    nextUrl: {
+        pathname: string;
+        search: string;
+    };
+    url: string;
+}
+interface FoirMiddlewareConfig {
+    /** Where to send unauthenticated requests (path or absolute URL). */
+    signInUrl: string;
+    /**
+     * The session cookie whose presence means "signed in". Defaults to the
+     * access-token cookie the cookie adapter writes (`foir_token`).
+     */
+    cookieName?: string;
+    /**
+     * Return true for requests that require auth. Omit to protect every request
+     * the middleware `matcher` passes through.
+     */
+    isProtected?(request: FoirMiddlewareRequest): boolean;
+    /** Query param carrying the original path on the sign-in URL. Default `returnTo`. */
+    returnParam?: string;
+}
+/**
+ * Build a Next.js middleware that redirects unauthenticated requests to your
+ * sign-in URL. Edge-safe: it checks for the presence of the session cookie only
+ * — the bearer itself is validated server-side when you call the Foir API — so
+ * pair it with a real `getFoirSession` check in protected route handlers /
+ * server components. Returns a standard `Response` (redirect) or `undefined`
+ * (continue), both of which Next.js middleware accepts.
+ *
+ * ```ts
+ * // middleware.ts
+ * import { createFoirMiddleware } from '@foir/sdk/next';
+ * export const middleware = createFoirMiddleware({ signInUrl: '/sign-in' });
+ * export const config = { matcher: ['/dashboard/:path*'] };
+ * ```
+ */
+declare function createFoirMiddleware(config: FoirMiddlewareConfig): (request: FoirMiddlewareRequest) => Response | undefined;
+
+export { type CookieAdapterOptions, type FoirCookieStore, type FoirCustomer, type FoirEnv, type FoirMiddlewareConfig, type FoirMiddlewareRequest, type SessionAdapter, completeFoirProviderLogin, createFoirCookieAdapter, createFoirMiddleware, foirCookieName, foirRegisterWithPassword, foirSignInWithOtp, foirSignInWithPassword, foirSignOut, getFoirSession, getFoirToken };

package/dist/next.js

@@ -0,0 +1,275 @@
+// src/next/cookieAdapter.ts
+var DEFAULT_COOKIE_OPTIONS = {
+  httpOnly: true,
+  secure: true,
+  sameSite: "lax",
+  path: "/"
+};
+function foirCookieName(key) {
+  return key.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+function createFoirCookieAdapter(store, opts = {}) {
+  const options = { ...DEFAULT_COOKIE_OPTIONS, ...opts.cookieOptions };
+  return {
+    get: (key) => store.get(foirCookieName(key))?.value ?? null,
+    set: (key, value) => store.set(foirCookieName(key), value, options),
+    unset: (key) => store.delete(foirCookieName(key))
+  };
+}
+
+// src/graphql/foir-request.ts
+import { print } from "graphql";
+function isFoirPreview(env) {
+  return env.FOIR_PREVIEW === "true";
+}
+var FoirRequestError = class extends Error {
+  /** HTTP status code, when the request failed at the HTTP layer. */
+  status;
+  /** GraphQL errors, when the request failed with a no-data error envelope. */
+  graphQLErrors;
+  cause;
+  constructor(message, options) {
+    super(message);
+    this.name = "FoirRequestError";
+    this.cause = options?.cause;
+    this.status = options?.status;
+    this.graphQLErrors = options?.graphQLErrors;
+  }
+};
+async function foirRequest(env, document, variables, options) {
+  const endpoint = env.PLATFORM_API_URL;
+  const apiKey = isFoirPreview(env) ? env.PLATFORM_PREVIEW_API_KEY ?? env.PLATFORM_API_KEY : env.PLATFORM_API_KEY;
+  if (!endpoint || !apiKey) {
+    throw new FoirRequestError(
+      "[foir] PLATFORM_API_URL or PLATFORM_API_KEY is not set \u2014 add them to .env"
+    );
+  }
+  const headers = {
+    "Content-Type": "application/json",
+    "x-api-key": apiKey
+  };
+  if (isFoirPreview(env)) {
+    headers["X-Foir-Schema-Channel"] = "draft";
+  }
+  if (options?.bearerToken) {
+    headers["Authorization"] = `Bearer ${options.bearerToken}`;
+  }
+  let res;
+  try {
+    res = await fetch(endpoint, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ query: print(document), variables })
+    });
+  } catch (err) {
+    throw new FoirRequestError("[foir] network error", { cause: err });
+  }
+  if (!res.ok) {
+    throw new FoirRequestError(`[foir] HTTP ${res.status} ${res.statusText}`, {
+      status: res.status
+    });
+  }
+  const json = await res.json();
+  if (json.errors?.length) {
+    const msg = json.errors.map((e) => e.message).join("; ");
+    if (json.data) {
+      console.warn(`[foir] GraphQL partial errors (data returned): ${msg}`);
+    } else {
+      throw new FoirRequestError(`[foir] GraphQL errors: ${msg}`, {
+        graphQLErrors: json.errors
+      });
+    }
+  }
+  if (!json.data) {
+    throw new FoirRequestError("[foir] empty GraphQL response");
+  }
+  return json.data;
+}
+
+// src/auth/operations.ts
+import { parse } from "graphql";
+var AUTH_RESULT_FIELDS = "token refreshToken customerId email";
+var CustomerLoginDocument = parse(
+  `mutation CustomerLogin($email: String!, $password: String!) {
+    customerLogin(email: $email, password: $password) { ${AUTH_RESULT_FIELDS} }
+  }`
+);
+var CustomerRegisterDocument = parse(
+  `mutation CustomerRegister($email: String!, $password: String!) {
+    customerRegister(email: $email, password: $password) { ${AUTH_RESULT_FIELDS} }
+  }`
+);
+var CustomerRefreshTokenDocument = parse(
+  `mutation CustomerRefreshToken($refreshToken: String!) {
+    customerRefreshToken(refreshToken: $refreshToken) { ${AUTH_RESULT_FIELDS} }
+  }`
+);
+var CustomerRequestOTPDocument = parse(
+  `mutation CustomerRequestOTP($email: String!) {
+    customerRequestOTP(email: $email)
+  }`
+);
+var CustomerLoginOTPDocument = parse(
+  `mutation CustomerLoginOTP($email: String!, $otp: String!) {
+    customerLoginOTP(email: $email, otp: $otp) { ${AUTH_RESULT_FIELDS} }
+  }`
+);
+var CustomerLoginWithProviderDocument = parse(
+  `mutation CustomerLoginWithProvider($input: ProviderLoginInput!) {
+    customerLoginWithProvider(input: $input) { redirectUrl token }
+  }`
+);
+var CustomerProviderCallbackDocument = parse(
+  `mutation CustomerProviderCallback($input: ProviderCallbackInput!) {
+    customerProviderCallback(input: $input) { ${AUTH_RESULT_FIELDS} }
+  }`
+);
+var CustomerProviderVerifyOTPDocument = parse(
+  `mutation CustomerProviderVerifyOTP($input: ProviderOTPVerifyInput!) {
+    customerProviderVerifyOTP(input: $input) { ${AUTH_RESULT_FIELDS} }
+  }`
+);
+var AuthProvidersDocument = parse(
+  `query AuthProviders {
+    authProviders { key name type isDefault }
+  }`
+);
+
+// src/auth/auth.ts
+var TOKEN_KEY = "foir:token";
+var REFRESH_KEY = "foir:refreshToken";
+var CUSTOMER_ID_KEY = "foir:customerId";
+var EMAIL_KEY = "foir:email";
+async function customerLogin(env, vars) {
+  return (await foirRequest(env, CustomerLoginDocument, vars)).customerLogin;
+}
+async function customerRegister(env, vars) {
+  return (await foirRequest(env, CustomerRegisterDocument, vars)).customerRegister;
+}
+async function customerLoginOTP(env, vars) {
+  return (await foirRequest(env, CustomerLoginOTPDocument, vars)).customerLoginOTP;
+}
+async function customerProviderCallback(env, input) {
+  return (await foirRequest(env, CustomerProviderCallbackDocument, { input })).customerProviderCallback;
+}
+async function saveSession(adapter, result) {
+  await adapter.set(TOKEN_KEY, result.token);
+  await adapter.set(REFRESH_KEY, result.refreshToken);
+  await adapter.set(CUSTOMER_ID_KEY, result.customerId);
+  await adapter.set(EMAIL_KEY, result.email);
+  return { id: result.customerId, email: result.email };
+}
+async function clearSession(adapter) {
+  await adapter.unset(TOKEN_KEY);
+  await adapter.unset(REFRESH_KEY);
+  await adapter.unset(CUSTOMER_ID_KEY);
+  await adapter.unset(EMAIL_KEY);
+}
+async function getSessionToken(adapter) {
+  return await adapter.get(TOKEN_KEY) ?? null;
+}
+async function getSessionCustomer(adapter) {
+  const id = await adapter.get(CUSTOMER_ID_KEY) ?? null;
+  const email = await adapter.get(EMAIL_KEY) ?? null;
+  if (!id) return null;
+  return { id, email: email ?? "" };
+}
+async function loginWithPassword(adapter, env, vars) {
+  return saveSession(adapter, await customerLogin(env, vars));
+}
+async function registerWithPassword(adapter, env, vars) {
+  return saveSession(adapter, await customerRegister(env, vars));
+}
+async function loginWithOTP(adapter, env, vars) {
+  return saveSession(adapter, await customerLoginOTP(env, vars));
+}
+
+// src/next/session.ts
+async function getFoirSession(store) {
+  return getSessionCustomer(createFoirCookieAdapter(store));
+}
+async function getFoirToken(store) {
+  return getSessionToken(createFoirCookieAdapter(store));
+}
+async function foirSignOut(store, opts) {
+  return clearSession(createFoirCookieAdapter(store, opts));
+}
+function foirSignInWithPassword({
+  env,
+  store,
+  email,
+  password,
+  cookieOptions
+}) {
+  return loginWithPassword(createFoirCookieAdapter(store, { cookieOptions }), env, {
+    email,
+    password
+  });
+}
+function foirRegisterWithPassword({
+  env,
+  store,
+  email,
+  password,
+  cookieOptions
+}) {
+  return registerWithPassword(createFoirCookieAdapter(store, { cookieOptions }), env, {
+    email,
+    password
+  });
+}
+function foirSignInWithOtp({
+  env,
+  store,
+  email,
+  otp,
+  cookieOptions
+}) {
+  return loginWithOTP(createFoirCookieAdapter(store, { cookieOptions }), env, {
+    email,
+    otp
+  });
+}
+async function completeFoirProviderLogin(opts) {
+  const result = await customerProviderCallback(opts.env, {
+    providerKey: opts.providerKey,
+    code: opts.code,
+    state: opts.state
+  });
+  return saveSession(
+    createFoirCookieAdapter(opts.store, { cookieOptions: opts.cookieOptions }),
+    result
+  );
+}
+
+// src/next/middleware.ts
+function createFoirMiddleware(config) {
+  const cookieName = config.cookieName ?? foirCookieName("foir:token");
+  const returnParam = config.returnParam ?? "returnTo";
+  return function foirMiddleware(request) {
+    if (config.isProtected && !config.isProtected(request)) {
+      return void 0;
+    }
+    if (request.cookies.get(cookieName)?.value) {
+      return void 0;
+    }
+    const url = new URL(config.signInUrl, request.url);
+    url.searchParams.set(
+      returnParam,
+      request.nextUrl.pathname + request.nextUrl.search
+    );
+    return Response.redirect(url.toString(), 307);
+  };
+}
+export {
+  completeFoirProviderLogin,
+  createFoirCookieAdapter,
+  createFoirMiddleware,
+  foirCookieName,
+  foirRegisterWithPassword,
+  foirSignInWithOtp,
+  foirSignInWithPassword,
+  foirSignOut,
+  getFoirSession,
+  getFoirToken
+};