@foir/sdk 0.5.0 → 0.7.0

package/dist/push.js

@@ -1,8 +1,16 @@
 // src/graphql/foir-request.ts
+import { print as print2 } from "graphql";
+
+// src/graphql/cdn-route.ts
 import { print } from "graphql";
+
+// src/transport/foir-http.ts
 function isFoirPreview(env) {
   return env.FOIR_PREVIEW === "true";
 }
+function resolveFoirApiKey(env) {
+  return isFoirPreview(env) ? env.PLATFORM_PREVIEW_API_KEY ?? env.PLATFORM_API_KEY : env.PLATFORM_API_KEY;
+}
 var FoirRequestError = class extends Error {
   /** HTTP status code, when the request failed at the HTTP layer. */
   status;
@@ -16,41 +24,83 @@ var FoirRequestError = class extends Error {
     this.status = options?.status;
     this.graphQLErrors = options?.graphQLErrors;
   }
+  /**
+   * 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() {
+    return this.graphQLErrors?.[0]?.extensions?.code;
+  }
+  /** The correlation id, if the response carried one. */
+  get requestId() {
+    return this.graphQLErrors?.[0]?.extensions?.requestId;
+  }
+  /**
+   * 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() {
+    if (this.status === void 0) return true;
+    if (this.status === 429 || this.code === "RATE_LIMITED") return true;
+    if (this.status >= 500) return true;
+    return this.code === "UNAVAILABLE" || this.code === "TIMEOUT";
+  }
+  /**
+   * 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() {
+    const seconds = this.graphQLErrors?.[0]?.extensions?.retryAfter;
+    return typeof seconds === "number" && seconds > 0 ? seconds * 1e3 : void 0;
+  }
 };
-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"
-    );
+function readFoirRateLimit(headers) {
+  const raw = {
+    limit: headers.get("X-RateLimit-Limit"),
+    remaining: headers.get("X-RateLimit-Remaining"),
+    resetAt: headers.get("X-RateLimit-Reset")
+  };
+  if (raw.limit === null || raw.remaining === null || raw.resetAt === null) {
+    return void 0;
+  }
+  const limit = Number(raw.limit);
+  const remaining = Number(raw.remaining);
+  const resetAt = Number(raw.resetAt);
+  if (!Number.isFinite(limit) || !Number.isFinite(remaining) || !Number.isFinite(resetAt)) {
+    return void 0;
   }
+  return { limit, remaining, resetAt };
+}
+function readFoirRetryAfterMs(headers) {
+  const seconds = Number(headers.get("Retry-After"));
+  return Number.isFinite(seconds) && seconds > 0 ? seconds * 1e3 : void 0;
+}
+function buildFoirHeaders(input) {
   const headers = {
     "Content-Type": "application/json",
-    "x-api-key": apiKey
+    "x-api-key": input.apiKey
   };
-  if (isFoirPreview(env)) {
+  if (input.draftChannel) {
     headers["X-Foir-Schema-Channel"] = "draft";
   }
-  if (options?.bearerToken) {
-    headers["Authorization"] = `Bearer ${options.bearerToken}`;
+  if (input.bearerToken) {
+    headers["Authorization"] = `Bearer ${input.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
-    });
+  if (input.extra) {
+    for (const [key, value] of Object.entries(input.extra)) {
+      headers[key] = value;
+    }
   }
-  const json = await res.json();
+  return headers;
+}
+function readFoirEnvelope(json) {
   if (json.errors?.length) {
     const msg = json.errors.map((e) => e.message).join("; ");
     if (json.data) {
@@ -67,6 +117,150 @@ async function foirRequest(env, document, variables, options) {
   return json.data;
 }
 
+// src/graphql/cdn-route.ts
+var CDN_PATH = "/cdn/graphql";
+function isCdnEligible(env, documentText, bearerToken) {
+  if (bearerToken) return false;
+  if (isFoirPreview(env)) return false;
+  const apiKey = resolveFoirApiKey(env);
+  if (!apiKey?.startsWith("pk_")) return false;
+  return !/\bmutation\b/.test(documentText);
+}
+function buildCdnUrl(endpoint, apiKey, hash, variables) {
+  const url = new URL(endpoint);
+  url.pathname = url.pathname.replace(/\/graphql\/?$/, "") + CDN_PATH;
+  url.searchParams.set("key", apiKey);
+  url.searchParams.set("extensions", JSON.stringify(persistedQueryExtension(hash)));
+  if (variables && Object.keys(variables).length > 0) {
+    url.searchParams.set("variables", JSON.stringify(variables));
+  }
+  return url.toString();
+}
+function persistedQueryExtension(hash) {
+  return { persistedQuery: { version: 1, sha256Hash: hash } };
+}
+async function documentHash(documentText) {
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(documentText)
+  );
+  return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+var PERSISTED_QUERY_NOT_FOUND = "PERSISTED_QUERY_NOT_FOUND";
+var NOT_SHAREABLE = "NOT_SHAREABLE";
+
+// src/graphql/foir-request.ts
+async function foirRequest(env, document, variables, options) {
+  const endpoint = env.PLATFORM_API_URL;
+  const apiKey = resolveFoirApiKey(env);
+  if (!endpoint || !apiKey) {
+    throw new FoirRequestError(
+      "[foir] PLATFORM_API_URL or PLATFORM_API_KEY is not set \u2014 add them to .env"
+    );
+  }
+  const headers = buildFoirHeaders({
+    apiKey,
+    draftChannel: isFoirPreview(env),
+    bearerToken: options?.bearerToken
+  });
+  const documentText = print2(document);
+  let res;
+  try {
+    if (isCdnEligible(env, documentText, options?.bearerToken)) {
+      const hash = await documentHash(documentText);
+      let shared = await fetch(buildCdnUrl(endpoint, apiKey, hash, variables), {
+        method: "GET",
+        headers
+      });
+      if (await isPersistedQueryMiss(shared)) {
+        shared = await fetch(buildCdnUrl(endpoint, apiKey, hash, variables), {
+          method: "POST",
+          headers,
+          body: JSON.stringify({
+            query: documentText,
+            variables,
+            extensions: persistedQueryExtension(hash)
+          })
+        });
+      }
+      if (await isSharedRefusal(shared)) {
+        res = await fetch(endpoint, {
+          method: "POST",
+          headers,
+          body: JSON.stringify({ query: documentText, variables })
+        });
+      } else {
+        res = shared;
+      }
+    } else {
+      res = await fetch(endpoint, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ query: documentText, variables })
+      });
+    }
+  } catch (err) {
+    throw new FoirRequestError("[foir] network error", { cause: err });
+  }
+  options?.onRateLimit?.(readFoirRateLimit(res.headers));
+  if (!res.ok) {
+    const errors = await readErrorEnvelope(res);
+    const first = errors?.[0]?.message;
+    throw new FoirRequestError(
+      first ? `[foir] HTTP ${res.status} ${res.statusText}: ${first}` : `[foir] HTTP ${res.status} ${res.statusText}`,
+      { status: res.status, graphQLErrors: errors }
+    );
+  }
+  const json = await res.json();
+  return readFoirEnvelope(json);
+}
+async function readErrorEnvelope(res) {
+  let errors;
+  try {
+    const body = await res.json();
+    errors = body.errors;
+  } catch {
+    errors = void 0;
+  }
+  const headerRetryMs = readFoirRetryAfterMs(res.headers);
+  if (headerRetryMs === void 0) return errors;
+  const seconds = Math.round(headerRetryMs / 1e3);
+  if (!errors?.length) {
+    return [
+      {
+        message: res.statusText || `HTTP ${res.status}`,
+        extensions: { code: "RATE_LIMITED", retryAfter: seconds }
+      }
+    ];
+  }
+  if (errors[0].extensions?.retryAfter === void 0) {
+    errors[0] = {
+      ...errors[0],
+      extensions: { ...errors[0].extensions, retryAfter: seconds }
+    };
+  }
+  return errors;
+}
+async function isSharedRefusal(res) {
+  if (res.ok) return false;
+  try {
+    const body = await res.clone().json();
+    return body.errors?.some((e) => e.extensions?.code === NOT_SHAREABLE) ?? false;
+  } catch {
+    return false;
+  }
+}
+async function isPersistedQueryMiss(res) {
+  try {
+    const body = await res.clone().json();
+    return body.errors?.some(
+      (e) => e.extensions?.code === PERSISTED_QUERY_NOT_FOUND
+    ) ?? false;
+  } catch {
+    return false;
+  }
+}
+
 // src/auth/operations.ts
 import { parse } from "graphql";
 var AUTH_RESULT_FIELDS = "token refreshToken customerId email";
@@ -115,6 +309,16 @@ var AuthProvidersDocument = parse(
     authProviders { key name type isDefault }
   }`
 );
+var CustomerJoinWaitlistDocument = parse(
+  `mutation CustomerJoinWaitlist($email: String!) {
+    customerJoinWaitlist(email: $email) { id email status }
+  }`
+);
+var CustomerSignupContextDocument = parse(
+  `query CustomerSignupContext {
+    customerSignupContext { signupMode }
+  }`
+);
 
 // src/auth/auth.ts
 var TOKEN_KEY = "foir:token";

package/dist/react/FoirProvider.d.ts

@@ -0,0 +1,116 @@
+import type { ReactNode } from 'react';
+import type { AuthProviderPublic, FoirCustomer, FoirSessionConfig, SessionAdapter } from '../auth';
+import type { ProviderCallbackInput, ProviderLoginInput } from '../auth';
+import type { FoirEnv } from '../graphql/foir-request';
+/** Where the session hydration stands. */
+export type FoirStatus = 'loading' | 'authenticated' | 'unauthenticated';
+/** The full context value. Read it through the hooks below, not directly. */
+export 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;
+}
+export 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.
+ */
+export declare function FoirProvider({ env, adapter, hostedSession, children, }: FoirProviderProps): import("react/jsx-runtime").JSX.Element;
+/** The current session state. */
+export interface FoirSession {
+    status: FoirStatus;
+    customer: FoirCustomer | null;
+    isLoading: boolean;
+    isAuthenticated: boolean;
+}
+/** Read the current session status and customer. */
+export declare function useFoirSession(): FoirSession;
+/** The signed-in customer (`{ id, email }`), or null. */
+export declare function useFoirUser(): FoirCustomer | null;
+/** The sign-in / sign-out actions. */
+export 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;
+};

package/dist/react/OAuthButtons.d.ts

@@ -0,0 +1,20 @@
+import type { ReactNode } from 'react';
+import type { AuthProviderPublic } from '../auth';
+export 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.
+ */
+export declare function OAuthButtons({ returnTo, redirectUri, filter, children, className, onError, }: OAuthButtonsProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/react/SignIn.d.ts

@@ -0,0 +1,22 @@
+import type { FoirCustomer } from '../auth';
+export 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`.
+ */
+export declare function SignIn({ method, hostedUrl, oauth, afterSignInUrl, onSignIn, className, }: SignInProps): import("react/jsx-runtime").JSX.Element;

package/dist/react/UserButton.d.ts

@@ -0,0 +1,13 @@
+export 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).
+ */
+export declare function UserButton({ afterSignOut, afterSignOutUrl, className }: UserButtonProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/react/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `@foir/sdk/react` — a drop-in React auth layer for Foir customers.
+ *
+ * Wrap your app in `<FoirProvider>`, then read the session with
+ * `useFoirSession` / `useFoirUser` and drive it with `useFoirAuth` — or drop in
+ * the `<SignIn>`, `<OAuthButtons>`, and `<UserButton>` components. Built entirely
+ * on `@foir/sdk/auth`; `react` is the only peer dependency.
+ */
+export { FoirProvider, useFoirSession, useFoirUser, useFoirAuth, } from './FoirProvider';
+export type { FoirProviderProps, FoirContextValue, FoirSession, FoirStatus, } from './FoirProvider';
+export { SignIn } from './SignIn';
+export type { SignInProps } from './SignIn';
+export { OAuthButtons } from './OAuthButtons';
+export type { OAuthButtonsProps } from './OAuthButtons';
+export { UserButton } from './UserButton';
+export type { UserButtonProps } from './UserButton';
+export { createLocalStorageAdapter } from './localStorageAdapter';
+export type { FoirCustomer, SessionAdapter, AuthProviderPublic } from '../auth';
+export type { FoirEnv } from '../graphql/foir-request';

package/dist/react/localStorageAdapter.d.ts

@@ -0,0 +1,10 @@
+import type { SessionAdapter } from '../auth';
+/**
+ * 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`.
+ */
+export declare function createLocalStorageAdapter(): SessionAdapter;