@foir/sdk 0.1.0 → 0.3.0

package/dist/push.js

@@ -0,0 +1,259 @@
+// 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 customerRefreshToken(env, refreshToken) {
+  return (await foirRequest(env, CustomerRefreshTokenDocument, { refreshToken })).customerRefreshToken;
+}
+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 refreshSession(adapter, env) {
+  const refreshToken = await adapter.get(REFRESH_KEY) ?? null;
+  if (!refreshToken) return null;
+  try {
+    const result = await customerRefreshToken(env, refreshToken);
+    await saveSession(adapter, result);
+    return { token: result.token, refreshToken: result.refreshToken };
+  } catch {
+    await clearSession(adapter);
+    return null;
+  }
+}
+function isAuthExpiredError(err) {
+  if (!(err instanceof FoirRequestError)) return false;
+  if (err.status === 401) return true;
+  return (err.graphQLErrors ?? []).some(
+    (e) => /authentication required/i.test(e.message)
+  );
+}
+async function authedRequest(adapter, env, document, variables) {
+  const token = await getSessionToken(adapter);
+  try {
+    return await foirRequest(env, document, variables, {
+      bearerToken: token ?? void 0
+    });
+  } catch (err) {
+    if (!isAuthExpiredError(err)) throw err;
+    const refreshed = await refreshSession(adapter, env);
+    if (!refreshed) throw err;
+    return foirRequest(env, document, variables, {
+      bearerToken: refreshed.token
+    });
+  }
+}
+
+// src/push/operations.ts
+import { parse as parse2 } from "graphql";
+var WebPushConfigDocument = parse2(
+  `query WebPushConfig {
+    webPushConfig { vapidPublicKey }
+  }`
+);
+var RegisterDeviceTokenDocument = parse2(
+  `mutation RegisterDeviceToken($input: RegisterDeviceTokenInput!) {
+    registerDeviceToken(input: $input)
+  }`
+);
+var UnregisterDeviceTokenDocument = parse2(
+  `mutation UnregisterDeviceToken($token: String!) {
+    unregisterDeviceToken(token: $token)
+  }`
+);
+
+// src/push/web-push.ts
+function urlBase64ToUint8Array(base64) {
+  const padding = "=".repeat((4 - base64.length % 4) % 4);
+  const normalized = (base64 + padding).replace(/-/g, "+").replace(/_/g, "/");
+  const raw = atob(normalized);
+  const out = new Uint8Array(new ArrayBuffer(raw.length));
+  for (let i = 0; i < raw.length; i += 1) out[i] = raw.charCodeAt(i);
+  return out;
+}
+function isWebPushSupported() {
+  return typeof window !== "undefined" && typeof navigator !== "undefined" && "serviceWorker" in navigator && "PushManager" in window && "Notification" in window;
+}
+async function enableWebPush(opts) {
+  if (!isWebPushSupported()) return { ok: false, reason: "unsupported" };
+  const permission = await Notification.requestPermission();
+  if (permission !== "granted") return { ok: false, reason: "denied" };
+  const registration = await navigator.serviceWorker.register(
+    opts.swPath ?? "/foir-sw.js",
+    { scope: opts.scope ?? "/" }
+  );
+  await navigator.serviceWorker.ready;
+  const config = await authedRequest(
+    opts.adapter,
+    opts.env,
+    WebPushConfigDocument
+  );
+  const vapidPublicKey = config.webPushConfig?.vapidPublicKey;
+  if (!vapidPublicKey) return { ok: false, reason: "no-config" };
+  const existing = await registration.pushManager.getSubscription();
+  const subscription = existing ?? await registration.pushManager.subscribe({
+    userVisibleOnly: true,
+    applicationServerKey: urlBase64ToUint8Array(vapidPublicKey)
+  });
+  await authedRequest(opts.adapter, opts.env, RegisterDeviceTokenDocument, {
+    input: {
+      token: JSON.stringify(subscription),
+      platform: "WEB",
+      deviceName: opts.deviceName
+    }
+  });
+  return { ok: true, subscription };
+}
+async function disableWebPush(opts) {
+  if (!isWebPushSupported()) return false;
+  const registration = await navigator.serviceWorker.getRegistration(
+    opts.scope ?? "/"
+  );
+  const subscription = await registration?.pushManager.getSubscription();
+  if (!subscription) return false;
+  const token = JSON.stringify(subscription);
+  await subscription.unsubscribe();
+  await authedRequest(opts.adapter, opts.env, UnregisterDeviceTokenDocument, {
+    token
+  });
+  return true;
+}
+export {
+  RegisterDeviceTokenDocument,
+  UnregisterDeviceTokenDocument,
+  WebPushConfigDocument,
+  disableWebPush,
+  enableWebPush,
+  isWebPushSupported
+};

package/dist/react.d.ts

@@ -0,0 +1,244 @@
+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>;
+}
+
+/** 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[]>;
+}
+interface FoirProviderProps {
+    /** API config: `{ PLATFORM_API_URL, PLATFORM_API_KEY }` (a publishable `pk_` key). */
+    env: FoirEnv;
+    /** Session store. Defaults to a browser localStorage adapter. */
+    adapter?: SessionAdapter;
+    children: ReactNode;
+}
+/**
+ * Provides Foir customer auth to a React tree. Hydrates the stored session on
+ * mount, then exposes the current customer and sign-in/out actions through
+ * {@link useFoirSession}, {@link useFoirUser}, and {@link useFoirAuth}.
+ */
+declare function FoirProvider({ env, adapter, 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[]>;
+};
+
+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 };