@foir/sdk 0.4.0 → 0.7.0

package/dist/next/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `@foir/sdk/next` — server-side Foir customer auth for the Next.js App Router
+ * (the BFF pattern): an HttpOnly-cookie session adapter, server-side session
+ * helpers, a provider-callback exchange, and a route-protection middleware.
+ *
+ * This is the server counterpart to `@foir/sdk/react`. `next` is a peer
+ * dependency (for the middleware helper).
+ */
+export { createFoirCookieAdapter, foirCookieName, } from './cookieAdapter';
+export type { FoirCookieStore, CookieAdapterOptions } from './cookieAdapter';
+export { getFoirSession, getFoirToken, foirSignOut, foirSignInWithPassword, foirRegisterWithPassword, foirSignInWithOtp, completeFoirProviderLogin, } from './session';
+export { createFoirMiddleware } from './middleware';
+export type { FoirMiddlewareConfig, FoirMiddlewareRequest } from './middleware';
+export type { FoirCustomer, SessionAdapter } from '../auth';
+export type { FoirEnv } from '../graphql/foir-request';

package/dist/next/middleware.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The slice of `NextRequest` the middleware reads. Typed structurally so the SDK
+ * doesn't need `next` installed to build — a real `NextRequest` satisfies it, so
+ * the returned function drops straight into `export const middleware`.
+ */
+export interface FoirMiddlewareRequest {
+    cookies: {
+        get(name: string): {
+            value: string;
+        } | undefined;
+    };
+    nextUrl: {
+        pathname: string;
+        search: string;
+    };
+    url: string;
+}
+export interface FoirMiddlewareConfig {
+    /** Where to send unauthenticated requests (path or absolute URL). */
+    signInUrl: string;
+    /**
+     * The session cookie whose presence means "signed in". Defaults to the
+     * access-token cookie the cookie adapter writes (`foir_token`).
+     */
+    cookieName?: string;
+    /**
+     * Return true for requests that require auth. Omit to protect every request
+     * the middleware `matcher` passes through.
+     */
+    isProtected?(request: FoirMiddlewareRequest): boolean;
+    /** Query param carrying the original path on the sign-in URL. Default `returnTo`. */
+    returnParam?: string;
+}
+/**
+ * Build a Next.js middleware that redirects unauthenticated requests to your
+ * sign-in URL. Edge-safe: it checks for the presence of the session cookie only
+ * — the bearer itself is validated server-side when you call the Foir API — so
+ * pair it with a real `getFoirSession` check in protected route handlers /
+ * server components. Returns a standard `Response` (redirect) or `undefined`
+ * (continue), both of which Next.js middleware accepts.
+ *
+ * ```ts
+ * // middleware.ts
+ * import { createFoirMiddleware } from '@foir/sdk/next';
+ * export const middleware = createFoirMiddleware({ signInUrl: '/sign-in' });
+ * export const config = { matcher: ['/dashboard/:path*'] };
+ * ```
+ */
+export declare function createFoirMiddleware(config: FoirMiddlewareConfig): (request: FoirMiddlewareRequest) => Response | undefined;

package/dist/next/session.d.ts

@@ -0,0 +1,53 @@
+import type { FoirCustomer } from '../auth';
+import type { FoirEnv } from '../graphql/foir-request';
+import type { CookieAdapterOptions, FoirCookieStore } from './cookieAdapter';
+/**
+ * Server-side session helpers for the Next.js BFF pattern. Each takes the Next
+ * cookie store (`await cookies()` in a route handler / server action, or the
+ * read-only `cookies()` in a Server Component for reads).
+ *
+ * Note on "verification": the customer access token is opaque to your app and
+ * validated by the Foir API on use, so `getFoirSession` returns the identity
+ * stored in the cookies rather than locally verifying a JWT. A rejected/expired
+ * bearer surfaces when you call the API (and `@foir/sdk/auth`'s `authedRequest`
+ * transparently refreshes it).
+ */
+/** The signed-in customer from the session cookies, or null. */
+export declare function getFoirSession(store: FoirCookieStore): Promise<FoirCustomer | null>;
+/** The current access token from the session cookies, or null. */
+export declare function getFoirToken(store: FoirCookieStore): Promise<string | null>;
+/** Clear the session cookies (sign out). */
+export declare function foirSignOut(store: FoirCookieStore, opts?: CookieAdapterOptions): Promise<void>;
+interface PasswordArgs {
+    env: FoirEnv;
+    store: FoirCookieStore;
+    email: string;
+    password: string;
+    cookieOptions?: CookieAdapterOptions['cookieOptions'];
+}
+/** Password sign-in in a route handler; persists the session to cookies. */
+export declare function foirSignInWithPassword({ env, store, email, password, cookieOptions, }: PasswordArgs): Promise<FoirCustomer>;
+/** Register a customer in a route handler; persists the session to cookies. */
+export declare function foirRegisterWithPassword({ env, store, email, password, cookieOptions, }: PasswordArgs): Promise<FoirCustomer>;
+/** Complete an OTP sign-in in a route handler; persists the session to cookies. */
+export declare function foirSignInWithOtp({ env, store, email, otp, cookieOptions, }: {
+    env: FoirEnv;
+    store: FoirCookieStore;
+    email: string;
+    otp: string;
+    cookieOptions?: CookieAdapterOptions['cookieOptions'];
+}): Promise<FoirCustomer>;
+/**
+ * Complete a provider (OAuth/OIDC) login in your callback route handler:
+ * exchange the `code` + `state` for tokens and persist them to the session
+ * cookies. Returns the customer.
+ */
+export declare function completeFoirProviderLogin(opts: {
+    env: FoirEnv;
+    store: FoirCookieStore;
+    providerKey: string;
+    code?: string;
+    state?: string;
+    cookieOptions?: CookieAdapterOptions['cookieOptions'];
+}): Promise<FoirCustomer>;
+export {};

package/dist/next.js

@@ -18,10 +18,18 @@ function createFoirCookieAdapter(store, opts = {}) {
 }
 
 // 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;
@@ -35,41 +43,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) {
@@ -86,6 +136,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";
@@ -134,6 +328,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/protocol/constants.d.ts

@@ -0,0 +1,6 @@
+/** Protocol version for compatibility checks. */
+export declare const PROTOCOL_VERSION = "1.0";
+/** Maximum allowed iframe resize height in pixels. */
+export declare const MAX_RESIZE_HEIGHT = 100000;
+/** Path segments that must be rejected to prevent prototype pollution. */
+export declare const DANGEROUS_PATH_SEGMENTS: string[];

package/dist/protocol/messages.d.ts

@@ -0,0 +1,155 @@
+/**
+ * PostMessage protocol types between EIDE platform host and extension iframes.
+ *
+ * Inlined from the platform protocol to keep the SDK zero-dep.
+ */
+/**
+ * Messages sent FROM the platform host TO the iframe extension.
+ */
+export type HostToEditorMessage = {
+    type: 'init';
+    payload: {
+        values: Record<string, unknown>;
+        metadata?: Record<string, unknown>;
+        modelKey: string;
+        recordId: string;
+        naturalKey?: string;
+        versionId: string | null;
+        variantKey: string | null;
+        locale: string | null;
+        schema: unknown;
+        mode: 'edit' | 'readonly';
+        theme: 'light' | 'dark';
+        apiKey: string;
+        apiUrl: string;
+        connectionDomain?: string;
+        configMode?: 'editor' | 'sidebar';
+        selectedFieldKeys?: string[];
+        selectableFields?: Array<{
+            key: string;
+            label: string;
+            type: string;
+        }>;
+        localeContext?: {
+            currentLocale: string;
+            sourceLocale: string;
+            isTranslating: boolean;
+            locales: Array<{
+                code: string;
+                displayName: string;
+                isDefault: boolean;
+            }>;
+        };
+    };
+} | {
+    type: 'values-changed';
+    payload: {
+        values: Record<string, unknown>;
+        source: 'remote';
+    };
+} | {
+    type: 'variant-changed';
+    payload: {
+        variantKey: string;
+        values: Record<string, unknown>;
+    };
+} | {
+    type: 'save-result';
+    payload: {
+        success: boolean;
+        error?: string;
+        versionId?: string;
+    };
+} | {
+    type: 'publish-result';
+    payload: {
+        success: boolean;
+        error?: string;
+    };
+} | {
+    type: 'theme-changed';
+    payload: {
+        theme: 'light' | 'dark';
+    };
+} | {
+    type: 'selection-changed';
+    payload: {
+        selectedFieldKeys: string[];
+        fields: Array<{
+            key: string;
+            label: string;
+            type: string;
+        }>;
+    };
+} | {
+    type: 'locale-changed';
+    payload: {
+        currentLocale: string;
+        sourceLocale: string;
+        isTranslating: boolean;
+        locales: Array<{
+            code: string;
+            displayName: string;
+            isDefault: boolean;
+        }>;
+    };
+} | {
+    type: 'operation-result';
+    payload: {
+        requestId: string;
+        success: boolean;
+        result?: unknown;
+        error?: {
+            code: string;
+            message: string;
+        };
+    };
+};
+/**
+ * Messages sent FROM the iframe extension TO the platform host.
+ */
+export type EditorToHostMessage = {
+    type: 'ready';
+    payload: Record<string, never>;
+} | {
+    type: 'update-values';
+    payload: {
+        values: Record<string, unknown>;
+    };
+} | {
+    type: 'update-field';
+    payload: {
+        path: string;
+        value: unknown;
+    };
+} | {
+    type: 'request-save';
+    payload: Record<string, never>;
+} | {
+    type: 'request-publish';
+    payload: Record<string, never>;
+} | {
+    type: 'resize';
+    payload: {
+        height: number;
+    };
+} | {
+    type: 'dirty';
+    payload: {
+        isDirty: boolean;
+    };
+} | {
+    type: 'request-navigate';
+    payload: {
+        path: string;
+    };
+} | {
+    type: 'request-operation';
+    payload: {
+        operationKey: string;
+        input?: Record<string, unknown>;
+        requestId: string;
+        /** Execution mode: 'sync' waits for completion, 'async' queues and returns. */
+        mode?: 'sync' | 'async';
+    };
+};

package/dist/protocol/validation.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Runtime validation for postMessage payloads.
+ */
+import type { HostToEditorMessage, EditorToHostMessage } from './messages';
+/** Validate an incoming message from a custom editor iframe (editor -> host). */
+export declare function isValidEditorMessage(data: unknown): data is EditorToHostMessage;
+/** Validate an incoming message from the platform host (host -> editor). */
+export declare function isValidHostMessage(data: unknown): data is HostToEditorMessage;

package/dist/push/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `@foir/sdk/push` — native Web Push (VAPID) enrolment for browser web apps.
+ *
+ * @example
+ * ```ts
+ * import { enableWebPush } from '@foir/sdk/push';
+ *
+ * await enableWebPush({ adapter, env }); // registers /foir-sw.js + a WEB token
+ * ```
+ */
+export { enableWebPush, disableWebPush, isWebPushSupported, } from './web-push';
+export type { EnableWebPushOptions, EnableWebPushResult, DisableWebPushOptions, } from './web-push';
+export { WebPushConfigDocument, RegisterDeviceTokenDocument, UnregisterDeviceTokenDocument, } from './operations';
+export type { RegisterDeviceTokenInput } from './operations';

package/dist/push/operations.d.ts

@@ -0,0 +1,22 @@
+import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
+/** The project's non-secret VAPID public key a browser subscribes with. */
+export declare const WebPushConfigDocument: TypedDocumentNode<{
+    webPushConfig: {
+        vapidPublicKey: string;
+    } | null;
+}, Record<string, never>>;
+export interface RegisterDeviceTokenInput {
+    token: string;
+    platform: 'IOS' | 'ANDROID' | 'WEB';
+    deviceName?: string;
+}
+export declare const RegisterDeviceTokenDocument: TypedDocumentNode<{
+    registerDeviceToken: boolean;
+}, {
+    input: RegisterDeviceTokenInput;
+}>;
+export declare const UnregisterDeviceTokenDocument: TypedDocumentNode<{
+    unregisterDeviceToken: boolean;
+}, {
+    token: string;
+}>;

package/dist/push/web-push.d.ts

@@ -0,0 +1,39 @@
+import type { SessionAdapter } from '../auth/auth';
+import type { FoirEnv } from '../graphql/foir-request';
+export interface EnableWebPushOptions {
+    adapter: SessionAdapter;
+    env: FoirEnv;
+    /** Path the service worker is served from (must be same-origin). Default `/foir-sw.js`. */
+    swPath?: string;
+    /** Service-worker registration scope. Default `/`. */
+    scope?: string;
+    /** Optional label stored alongside the device token. */
+    deviceName?: string;
+}
+export type EnableWebPushResult = {
+    ok: true;
+    subscription: PushSubscription;
+} | {
+    ok: false;
+    reason: 'unsupported' | 'denied' | 'no-config';
+};
+export interface DisableWebPushOptions {
+    adapter: SessionAdapter;
+    env: FoirEnv;
+    /** Scope the service worker was registered with. Default `/`. */
+    scope?: string;
+}
+/** True when the current browser supports the Web Push APIs this helper needs. */
+export declare function isWebPushSupported(): boolean;
+/**
+ * Subscribe the current browser to Foir Web Push and register the subscription
+ * as a `WEB` device token. Idempotent: reuses an existing subscription when one
+ * is already present. Returns `{ ok: false }` (never throws) when the browser
+ * is unsupported or the user declines permission.
+ */
+export declare function enableWebPush(opts: EnableWebPushOptions): Promise<EnableWebPushResult>;
+/**
+ * Unsubscribe the current browser from Web Push and deregister the device
+ * token. Returns `false` when there was no active subscription to remove.
+ */
+export declare function disableWebPush(opts: DisableWebPushOptions): Promise<boolean>;