@foir/sdk 0.5.0 → 0.8.0

package/dist/react.d.ts

@@ -1,319 +0,0 @@
-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 };