@foir/sdk 0.2.0 → 0.4.0

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
+};

package/dist/react.d.ts

@@ -0,0 +1,319 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/**
+ * 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`).
+ */
+
+/** 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;
+}
+
+/**
+ * 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>;
+}
+
+/**
+ * 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;
+}
+
+/** Where the session hydration stands. */
+type FoirStatus = 'loading' | 'authenticated' | 'unauthenticated';
+/** The full context value. Read it through the hooks below, not directly. */
+interface FoirContextValue {
+    status: FoirStatus;
+    customer: FoirCustomer | null;
+    /** The API config; exposed so advanced consumers can call `@foir/sdk/auth` directly. */
+    env: FoirEnv;
+    /** The session store backing this provider. */
+    adapter: SessionAdapter;
+    signIn(vars: {
+        email: string;
+        password: string;
+    }): Promise<FoirCustomer>;
+    register(vars: {
+        email: string;
+        password: string;
+    }): Promise<FoirCustomer>;
+    requestOtp(email: string): Promise<boolean>;
+    signInWithOtp(vars: {
+        email: string;
+        otp: string;
+    }): Promise<FoirCustomer>;
+    /** Start a provider (OAuth/OIDC) login. Redirect providers navigate away. */
+    signInWithProvider(providerKey: string, opts?: Omit<ProviderLoginInput, 'providerKey'>): Promise<void>;
+    /** Complete a provider login from your callback route (code + state). */
+    completeProviderLogin(input: Omit<ProviderCallbackInput, 'providerKey'> & {
+        providerKey: string;
+    }): Promise<FoirCustomer>;
+    signOut(): Promise<void>;
+    /** Rotate the access token; returns false (and signs out) if it can't. */
+    refresh(): Promise<boolean>;
+    /** The current access token, or null when signed out. */
+    getToken(): Promise<string | null>;
+    /** The project's configured auth providers (for OAuth buttons). */
+    getProviders(): Promise<AuthProviderPublic[]>;
+    /**
+     * In `hostedSession` mode, where to send the browser to sign in — sign-in is a
+     * redirect to your Foir login domain, not an in-page form. Null in token mode,
+     * where you call {@link FoirContextValue.signIn} instead.
+     */
+    hostedSignInUrl: ((returnTo?: string) => string) | null;
+}
+interface FoirProviderProps {
+    /** API config: `{ PLATFORM_API_URL, PLATFORM_API_KEY }` (a publishable `pk_` key). */
+    env: FoirEnv;
+    /** Session store for token mode. Defaults to a browser localStorage adapter. */
+    adapter?: SessionAdapter;
+    /**
+     * Opt into Foir-hosted first-party sessions: the durable credential is an
+     * HttpOnly cookie on your own domain and the access token lives only in
+     * memory, so nothing authentication-related is reachable from JS. This is the
+     * secure default for a backend-less SPA, and it REPLACES `adapter` — pass one
+     * or the other, not both.
+     *
+     * Requires a verified custom login domain sharing a registrable domain with
+     * your app (`app.acme.com` + `login.acme.com`). Sign-in becomes a redirect to
+     * {@link FoirContextValue.hostedSignInUrl}; the password/OTP/provider actions
+     * do not apply and will throw.
+     */
+    hostedSession?: Omit<FoirSessionConfig, 'onSignOut'>;
+    children: ReactNode;
+}
+/**
+ * Provides Foir customer auth to a React tree. Hydrates the session on mount,
+ * then exposes the current customer and sign-in/out actions through
+ * {@link useFoirSession}, {@link useFoirUser}, and {@link useFoirAuth}.
+ *
+ * Two session models:
+ *
+ *   default          tokens in a `SessionAdapter` (localStorage unless you pass
+ *                    your own). Simple, but a refresh token sits in JS.
+ *   `hostedSession`  Foir-hosted first-party cookie; the bearer never leaves
+ *                    memory. Needs a custom login domain. Prefer this.
+ */
+declare function FoirProvider({ env, adapter, hostedSession, children, }: FoirProviderProps): react_jsx_runtime.JSX.Element;
+/** The current session state. */
+interface FoirSession {
+    status: FoirStatus;
+    customer: FoirCustomer | null;
+    isLoading: boolean;
+    isAuthenticated: boolean;
+}
+/** Read the current session status and customer. */
+declare function useFoirSession(): FoirSession;
+/** The signed-in customer (`{ id, email }`), or null. */
+declare function useFoirUser(): FoirCustomer | null;
+/** The sign-in / sign-out actions. */
+declare function useFoirAuth(): {
+    signIn: (vars: {
+        email: string;
+        password: string;
+    }) => Promise<FoirCustomer>;
+    register: (vars: {
+        email: string;
+        password: string;
+    }) => Promise<FoirCustomer>;
+    requestOtp: (email: string) => Promise<boolean>;
+    signInWithOtp: (vars: {
+        email: string;
+        otp: string;
+    }) => Promise<FoirCustomer>;
+    signInWithProvider: (providerKey: string, opts?: Omit<ProviderLoginInput, "providerKey">) => Promise<void>;
+    completeProviderLogin: (input: Omit<ProviderCallbackInput, "providerKey"> & {
+        providerKey: string;
+    }) => Promise<FoirCustomer>;
+    signOut: () => Promise<void>;
+    refresh: () => Promise<boolean>;
+    getToken: () => Promise<string | null>;
+    getProviders: () => Promise<AuthProviderPublic[]>;
+    hostedSignInUrl: ((returnTo?: string) => string) | null;
+};
+
+interface SignInProps {
+    /** `password` (default) or `otp` (email one-time code). Ignored when `hostedUrl` is set. */
+    method?: 'password' | 'otp';
+    /** Render a single button that redirects to a hosted login page instead of an embedded form. */
+    hostedUrl?: string;
+    /** Show OAuth provider buttons below the form. Default true. */
+    oauth?: boolean;
+    /** Navigate here after a successful sign-in. */
+    afterSignInUrl?: string;
+    /** Called with the customer on a successful sign-in (before any redirect). */
+    onSignIn?(customer: FoirCustomer): void;
+    className?: string;
+}
+/**
+ * A drop-in customer sign-in. Renders an email/password (or OTP) form and,
+ * unless disabled, OAuth provider buttons. Set `hostedUrl` to instead render a
+ * button that redirects to a hosted login page. All state is handled through
+ * {@link FoirProvider}; on success it calls `onSignIn` and optionally navigates
+ * to `afterSignInUrl`.
+ */
+declare function SignIn({ method, hostedUrl, oauth, afterSignInUrl, onSignIn, className, }: SignInProps): react_jsx_runtime.JSX.Element;
+
+interface OAuthButtonsProps {
+    /** Passed to the provider login (where the callback returns the user). */
+    returnTo?: string;
+    /** Override the provider's default redirect URI (must be allow-listed). */
+    redirectUri?: string;
+    /** Filter which providers render (defaults to every redirect-capable one). */
+    filter?(provider: AuthProviderPublic): boolean;
+    /** Render your own button. Receives the provider and a click handler. */
+    children?(provider: AuthProviderPublic, signIn: () => void): ReactNode;
+    className?: string;
+    onError?(error: unknown): void;
+}
+/**
+ * Renders a sign-in button per configured OAuth/OIDC/SAML provider. Clicking a
+ * button starts the provider login and (for redirect flows) navigates away.
+ * Pass a `children` render prop to fully control the button markup.
+ */
+declare function OAuthButtons({ returnTo, redirectUri, filter, children, className, onError, }: OAuthButtonsProps): react_jsx_runtime.JSX.Element | null;
+
+interface UserButtonProps {
+    /** Called after a successful sign-out. */
+    afterSignOut?(): void;
+    /** Navigate here after sign-out. */
+    afterSignOutUrl?: string;
+    className?: string;
+}
+/**
+ * A minimal signed-in affordance: the customer's email plus a sign-out button.
+ * Renders nothing when signed out. Style it via `className` (the default is an
+ * unopinionated inline layout).
+ */
+declare function UserButton({ afterSignOut, afterSignOutUrl, className }: UserButtonProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * A {@link SessionAdapter} backed by the browser's `localStorage`.
+ *
+ * SSR-safe: with no `window` (server render) reads return `null` and writes are
+ * no-ops, so {@link FoirProvider} starts in `loading` and hydrates the real
+ * session on the client after mount. This is the default adapter when you don't
+ * pass one to `FoirProvider`.
+ */
+declare function createLocalStorageAdapter(): SessionAdapter;
+
+export { type AuthProviderPublic, type FoirContextValue, type FoirCustomer, type FoirEnv, FoirProvider, type FoirProviderProps, type FoirSession, type FoirStatus, OAuthButtons, type OAuthButtonsProps, type SessionAdapter, SignIn, type SignInProps, UserButton, type UserButtonProps, createLocalStorageAdapter, useFoirAuth, useFoirSession, useFoirUser };