@foir/sdk 0.4.0 → 0.7.0

package/dist/auth/operations.d.ts

@@ -0,0 +1,123 @@
+/**
+ * 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`).
+ */
+import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
+/** The common auth result every login/register/refresh mutation returns. */
+export interface CustomerAuthResult {
+    token: string;
+    refreshToken: string;
+    customerId: string;
+    email: string;
+}
+/** Result of initiating a provider login — a redirect URL or an inline token. */
+export interface ProviderLoginResult {
+    /** OAuth/OIDC authorization URL to redirect the user to (redirect flows). */
+    redirectUrl: string | null;
+    /** Inline access token (non-redirect provider flows). */
+    token: string | null;
+}
+/** A configured auth provider, as exposed to unauthenticated callers. */
+export interface AuthProviderPublic {
+    key: string;
+    name: string;
+    /** OAUTH2 | TOKEN_SSO | SAML | OIDC | EXTERNAL */
+    type: string;
+    isDefault: boolean | null;
+}
+export interface ProviderLoginInput {
+    providerKey: string;
+    email?: string;
+    returnTo?: string;
+    /** Override the provider's default redirect_uri (must be allow-listed). */
+    redirectUri?: string;
+}
+export interface ProviderCallbackInput {
+    providerKey: string;
+    code?: string;
+    state?: string;
+    email?: string;
+    idToken?: string;
+}
+export interface ProviderOTPVerifyInput {
+    providerKey: string;
+    email: string;
+    otp: string;
+}
+/** The project's customer signup mode. */
+export type SignupMode = "PUBLIC" | "RESTRICTED" | "WAITLIST" | "CLOSED";
+/** The signup surface a self-hosted frontend reads to render the right UI. */
+export interface SignupContext {
+    signupMode: SignupMode;
+}
+/** The queued (or existing pending) entry a waitlist join returns. */
+export interface WaitlistJoinResult {
+    id: string;
+    email: string;
+    /** Waitlist lifecycle status; PENDING on a fresh join. */
+    status: string;
+}
+export declare const CustomerLoginDocument: TypedDocumentNode<{
+    customerLogin: CustomerAuthResult;
+}, {
+    email: string;
+    password: string;
+}>;
+export declare const CustomerRegisterDocument: TypedDocumentNode<{
+    customerRegister: CustomerAuthResult;
+}, {
+    email: string;
+    password: string;
+}>;
+export declare const CustomerRefreshTokenDocument: TypedDocumentNode<{
+    customerRefreshToken: CustomerAuthResult;
+}, {
+    refreshToken: string;
+}>;
+export declare const CustomerRequestOTPDocument: TypedDocumentNode<{
+    customerRequestOTP: boolean;
+}, {
+    email: string;
+}>;
+export declare const CustomerLoginOTPDocument: TypedDocumentNode<{
+    customerLoginOTP: CustomerAuthResult;
+}, {
+    email: string;
+    otp: string;
+}>;
+export declare const CustomerLoginWithProviderDocument: TypedDocumentNode<{
+    customerLoginWithProvider: ProviderLoginResult;
+}, {
+    input: ProviderLoginInput;
+}>;
+export declare const CustomerProviderCallbackDocument: TypedDocumentNode<{
+    customerProviderCallback: CustomerAuthResult;
+}, {
+    input: ProviderCallbackInput;
+}>;
+export declare const CustomerProviderVerifyOTPDocument: TypedDocumentNode<{
+    customerProviderVerifyOTP: CustomerAuthResult;
+}, {
+    input: ProviderOTPVerifyInput;
+}>;
+export declare const AuthProvidersDocument: TypedDocumentNode<{
+    authProviders: AuthProviderPublic[];
+}, Record<string, never>>;
+export declare const CustomerJoinWaitlistDocument: TypedDocumentNode<{
+    customerJoinWaitlist: WaitlistJoinResult;
+}, {
+    email: string;
+}>;
+export declare const CustomerSignupContextDocument: TypedDocumentNode<{
+    customerSignupContext: SignupContext;
+}, Record<string, never>>;

package/dist/auth/session-client.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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.
+ */
+export 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;
+}
+/** The identity behind the current session. */
+export interface FoirSessionUser {
+    customerId: string;
+    email: string;
+}
+export interface FoirSessionClient {
+    /**
+     * The current access token, exchanging or re-exchanging the cookie as needed.
+     * Null when there is no session. Concurrent callers share one in-flight
+     * exchange. Call this before each API request — do not cache the result.
+     */
+    getToken(): Promise<string | null>;
+    /** The signed-in customer, or null. Exchanges if the session isn't loaded yet. */
+    getUser(): Promise<FoirSessionUser | null>;
+    /** Revoke the session server-side and clear the cookie. Idempotent. */
+    signOut(): Promise<void>;
+    /** Where to send the browser to sign in. */
+    signInUrl(returnTo?: string): string;
+    /** Observe session changes. Returns an unsubscribe function. */
+    subscribe(listener: (user: FoirSessionUser | null) => void): () => void;
+    /** Cancel the refresh timer. Call on unmount. */
+    destroy(): void;
+}
+/**
+ * Create a session client. Safe to call during SSR — it does nothing until a
+ * method is invoked, and `getToken()` on the server returns null rather than
+ * throwing (there is no cookie jar to draw on).
+ */
+export declare function createFoirSessionClient(config: FoirSessionConfig): FoirSessionClient;

package/dist/auth-session.js

@@ -0,0 +1,137 @@
+// src/auth/session-client.ts
+var DEFAULT_SESSION_PATH = "/session/token";
+var DEFAULT_LOGOUT_PATH = "/session/logout";
+var DEFAULT_REFRESH_SKEW_SECONDS = 60;
+var MIN_REFRESH_DELAY_MS = 5e3;
+var CSRF_HEADER = { "X-Foir-Session": "1" };
+function createFoirSessionClient(config) {
+  const sessionUrl = `${trimSlash(config.loginOrigin)}${config.sessionPath ?? DEFAULT_SESSION_PATH}`;
+  const logoutUrl = `${trimSlash(config.loginOrigin)}${config.logoutPath ?? DEFAULT_LOGOUT_PATH}`;
+  const skewMs = (config.refreshSkewSeconds ?? DEFAULT_REFRESH_SKEW_SECONDS) * 1e3;
+  let cached = null;
+  let inflight = null;
+  let timer = null;
+  let destroyed = false;
+  const listeners = /* @__PURE__ */ new Set();
+  function emit(user) {
+    for (const l of listeners) l(user);
+  }
+  function clearTimer() {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+  }
+  function scheduleRefresh(expiresAt) {
+    clearTimer();
+    if (destroyed || typeof setTimeout === "undefined") return;
+    const delay = Math.max(expiresAt - Date.now() - skewMs, MIN_REFRESH_DELAY_MS);
+    timer = setTimeout(() => {
+      void exchange();
+    }, delay);
+    timer.unref?.();
+  }
+  function forget() {
+    const had = cached !== null;
+    cached = null;
+    clearTimer();
+    if (had) emit(null);
+  }
+  function exchange() {
+    if (inflight) return inflight;
+    const pending = (async () => {
+      let res;
+      try {
+        res = await fetch(sessionUrl, {
+          method: "GET",
+          // The whole point: send the first-party cookie cross-origin (but
+          // same-site) to the login domain. Without this the cookie is not sent.
+          credentials: "include",
+          headers: { ...CSRF_HEADER }
+        });
+      } catch {
+        return cached;
+      }
+      if (res.status === 401) {
+        forget();
+        config.onSignOut?.();
+        return null;
+      }
+      if (!res.ok) return cached;
+      let json;
+      try {
+        json = await res.json();
+      } catch {
+        return cached;
+      }
+      if (!json.access_token || !json.customer_id) return cached;
+      const expiresIn = typeof json.expires_in === "number" ? json.expires_in : 0;
+      const next = {
+        token: json.access_token,
+        expiresAt: Date.now() + expiresIn * 1e3,
+        user: { customerId: json.customer_id, email: json.email ?? "" }
+      };
+      const changed = cached?.user.customerId !== next.user.customerId;
+      cached = next;
+      scheduleRefresh(next.expiresAt);
+      if (changed) emit(next.user);
+      return next;
+    })();
+    inflight = pending;
+    void pending.finally(() => {
+      if (inflight === pending) inflight = null;
+    });
+    return pending;
+  }
+  function fresh() {
+    if (!cached) return null;
+    return Date.now() < cached.expiresAt - skewMs ? cached : null;
+  }
+  return {
+    async getToken() {
+      const hit = fresh();
+      if (hit) return hit.token;
+      const got = await exchange();
+      return got?.token ?? null;
+    },
+    async getUser() {
+      const hit = fresh();
+      if (hit) return hit.user;
+      const got = await exchange();
+      return got?.user ?? null;
+    },
+    async signOut() {
+      try {
+        await fetch(logoutUrl, {
+          method: "POST",
+          credentials: "include",
+          headers: { ...CSRF_HEADER }
+        });
+      } catch {
+      }
+      forget();
+      config.onSignOut?.();
+    },
+    signInUrl(returnTo) {
+      const dest = new URL(trimSlash(config.loginOrigin));
+      const target = returnTo ?? (typeof window !== "undefined" ? window.location.href : void 0);
+      if (target && target !== "/") dest.searchParams.set("returnTo", target);
+      return dest.toString();
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    destroy() {
+      destroyed = true;
+      clearTimer();
+      listeners.clear();
+    }
+  };
+}
+function trimSlash(s) {
+  return s.replace(/\/+$/, "");
+}
+export {
+  createFoirSessionClient
+};

package/dist/auth.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}`;
-  }
-  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 (input.bearerToken) {
+    headers["Authorization"] = `Bearer ${input.bearerToken}`;
   }
-  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";
@@ -148,6 +352,12 @@ async function customerProviderVerifyOTP(env, input) {
 async function getAuthProviders(env) {
   return (await foirRequest(env, AuthProvidersDocument, {})).authProviders;
 }
+async function customerSignupContext(env) {
+  return (await foirRequest(env, CustomerSignupContextDocument, {})).customerSignupContext;
+}
+async function customerJoinWaitlist(env, email) {
+  return (await foirRequest(env, CustomerJoinWaitlistDocument, { email })).customerJoinWaitlist;
+}
 async function saveSession(adapter, result) {
   await adapter.set(TOKEN_KEY, result.token);
   await adapter.set(REFRESH_KEY, result.refreshToken);
@@ -422,6 +632,7 @@ export {
   authedRequest,
   clearSession,
   createFoirSessionClient,
+  customerJoinWaitlist,
   customerLogin,
   customerLoginOTP,
   customerLoginWithProvider,
@@ -430,6 +641,7 @@ export {
   customerRefreshToken,
   customerRegister,
   customerRequestOTP,
+  customerSignupContext,
   fetchHostedSession,
   getAuthProviders,
   getSessionCustomer,

package/dist/client/platform-client.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Fetch-based GraphQL client for the EIDE platform API.
+ *
+ * Zero dependencies — uses the native Fetch API.
+ */
+import type { PlatformClient, PlatformClientOptions } from '../types';
+/** Error thrown when a platform API request fails. */
+export declare class PlatformClientError extends Error {
+    status?: number | undefined;
+    response?: unknown | undefined;
+    constructor(message: string, status?: number | undefined, response?: unknown | undefined);
+}
+/**
+ * Create a PlatformClient instance.
+ *
+ * @example
+ * ```ts
+ * const client = createPlatformClient({
+ *   apiUrl: 'https://api.example.com/graphql',
+ *   apiKey: 'sk_test_...',
+ * });
+ *
+ * const { data } = await client.query(
+ *   `query GetProduct($id: ID!) { product(id: $id) { title } }`,
+ *   { id: '123' }
+ * );
+ * ```
+ */
+export declare function createPlatformClient(options: PlatformClientOptions): PlatformClient;