@foir/sdk 0.1.0 → 0.2.0

package/dist/push.d.ts

@@ -0,0 +1,109 @@
+import { TypedDocumentNode } from '@graphql-typed-document-node/core';
+
+/**
+ * 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 — 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.
+ */
+
+/**
+ * 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>;
+}
+
+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;
+}
+type EnableWebPushResult = {
+    ok: true;
+    subscription: PushSubscription;
+} | {
+    ok: false;
+    reason: 'unsupported' | 'denied' | 'no-config';
+};
+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. */
+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.
+ */
+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.
+ */
+declare function disableWebPush(opts: DisableWebPushOptions): Promise<boolean>;
+
+/** The project's non-secret VAPID public key a browser subscribes with. */
+declare const WebPushConfigDocument: TypedDocumentNode<{
+    webPushConfig: {
+        vapidPublicKey: string;
+    } | null;
+}, Record<string, never>>;
+interface RegisterDeviceTokenInput {
+    token: string;
+    platform: 'IOS' | 'ANDROID' | 'WEB';
+    deviceName?: string;
+}
+declare const RegisterDeviceTokenDocument: TypedDocumentNode<{
+    registerDeviceToken: boolean;
+}, {
+    input: RegisterDeviceTokenInput;
+}>;
+declare const UnregisterDeviceTokenDocument: TypedDocumentNode<{
+    unregisterDeviceToken: boolean;
+}, {
+    token: string;
+}>;
+
+export { type DisableWebPushOptions, type EnableWebPushOptions, type EnableWebPushResult, RegisterDeviceTokenDocument, type RegisterDeviceTokenInput, UnregisterDeviceTokenDocument, WebPushConfigDocument, disableWebPush, enableWebPush, isWebPushSupported };

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/server.d.ts

@@ -226,6 +226,83 @@ declare function verifyScopedToken(token: string, jwksUrl: string, options?: Ver
  */
 declare function parseContextHeader(raw: string | null): Record<string, string>;
 
+/**
+ * requireScopedToken — the one-line ingress guard for BFF routes the
+ * platform dispatches operations to (EID-498).
+ *
+ * Operation endpoints must be publicly reachable (the platform's dispatcher
+ * refuses private networks), so "the BFF is never public-facing" is achieved
+ * by AUTHENTICATED ingress, not network privacy: every route the platform
+ * calls verifies the platform-minted `X-Foir-Token` before doing anything. A
+ * route that skips verification is an open endpoint anyone can call
+ * directly, bypassing the operation's scopes, quotas, and preconditions.
+ *
+ * ```ts
+ * // Hono / Workers / Hydrogen — any fetch-API request:
+ * const { claims, subject, context } = await requireScopedToken(request, {
+ *   expectedProjectId: env.FOIR_PROJECT_ID,
+ * });
+ * ```
+ *
+ * Throws {@link ScopedTokenError} with `status` 401 (missing/invalid token)
+ * or 403 (valid token for the wrong tenant/project) — map it to a response
+ * in one place:
+ *
+ * ```ts
+ * catch (err) {
+ *   if (err instanceof ScopedTokenError) {
+ *     return new Response(err.message, { status: err.status });
+ *   }
+ *   throw err;
+ * }
+ * ```
+ */
+
+/**
+ * Verification failure with the HTTP status the route should answer with:
+ * 401 for a missing or invalid token, 403 for a valid token bound to the
+ * wrong tenant or project.
+ */
+declare class ScopedTokenError extends Error {
+    readonly status: 401 | 403;
+    constructor(message: string, status: 401 | 403);
+}
+/** The minimal request shape needed — satisfied by any fetch-API Request. */
+interface HeaderCarrier {
+    headers: {
+        get(name: string): string | null;
+    };
+}
+interface RequireScopedTokenOptions extends VerifyScopedTokenOptions {
+    /**
+     * JWKS endpoint to verify against. Defaults to the production platform
+     * (`https://api.foir.dev/.well-known/jwks.json`); point it at your dev
+     * host's `/.well-known/jwks.json` for non-production deployments.
+     */
+    jwksUrl?: string;
+    /**
+     * When set, a verified token whose subject names a different project is
+     * rejected with 403. Set this from your deploy's own config — it pins the
+     * route to its project even if a token minted for another project leaks.
+     */
+    expectedProjectId?: string;
+    /** Tenant analogue of {@link expectedProjectId}. */
+    expectedTenantId?: string;
+}
+interface ScopedTokenIngress {
+    claims: ScopedTokenClaims;
+    subject: ScopedTokenSubject;
+    /** Parsed `X-Foir-Context` correlation metadata (empty when absent). */
+    context: Record<string, string>;
+}
+/**
+ * Verify the platform-minted scoped token on an inbound dispatch request.
+ * Returns the decoded claims, parsed subject, and dispatch context; throws
+ * {@link ScopedTokenError} otherwise. See the module doc for the catch
+ * pattern.
+ */
+declare function requireScopedToken(request: HeaderCarrier, options?: RequireScopedTokenOptions): Promise<ScopedTokenIngress>;
+
 /**
  * Type definitions for platform operations.
  *
@@ -454,4 +531,4 @@ declare function createCallbackClient<TResult = unknown>(callback: OperationCall
     fetch?: typeof fetch;
 }): CallbackClient<TResult>;
 
-export { type CallbackClient, type CallbackResult, type EditorPlacement, type GraphQLResponse, type OperationCallback, type OperationContext, type OperationPayload, type OperationRecordContext, type OperationResult, type OperationTrigger, type ScopedTokenClaims, type ScopedTokenSubject, type ServerClient, ServerClientError, type ServerClientOptions, type VerifyScopedTokenOptions, createCallbackClient, createServerClient, parseContextHeader, parseSubject, recordsReadModels, recordsWriteModels, verifyScopedToken, verifyWebhookSignature };
+export { type CallbackClient, type CallbackResult, type EditorPlacement, type GraphQLResponse, type OperationCallback, type OperationContext, type OperationPayload, type OperationRecordContext, type OperationResult, type OperationTrigger, type RequireScopedTokenOptions, type ScopedTokenClaims, ScopedTokenError, type ScopedTokenIngress, type ScopedTokenSubject, type ServerClient, ServerClientError, type ServerClientOptions, type VerifyScopedTokenOptions, createCallbackClient, createServerClient, parseContextHeader, parseSubject, recordsReadModels, recordsWriteModels, requireScopedToken, verifyScopedToken, verifyWebhookSignature };

package/dist/server.js

@@ -184,6 +184,67 @@ function parseContextHeader(raw) {
   return out;
 }
 
+// src/server/require-scoped-token.ts
+var TOKEN_HEADER = "X-Foir-Token";
+var CONTEXT_HEADER = "X-Foir-Context";
+var DEFAULT_JWKS_URL = "https://api.foir.dev/.well-known/jwks.json";
+var ScopedTokenError = class extends Error {
+  status;
+  constructor(message, status) {
+    super(message);
+    this.name = "ScopedTokenError";
+    this.status = status;
+  }
+};
+async function requireScopedToken(request, options) {
+  const token = request.headers.get(TOKEN_HEADER);
+  if (!token) {
+    throw new ScopedTokenError(
+      `missing ${TOKEN_HEADER} header \u2014 this route only accepts platform-dispatched requests`,
+      401
+    );
+  }
+  let claims;
+  try {
+    claims = await verifyScopedToken(
+      token,
+      options?.jwksUrl ?? DEFAULT_JWKS_URL,
+      options
+    );
+  } catch (err) {
+    throw new ScopedTokenError(
+      `invalid scoped token: ${err instanceof Error ? err.message : String(err)}`,
+      401
+    );
+  }
+  let subject;
+  try {
+    subject = parseSubject(claims.sub);
+  } catch (err) {
+    throw new ScopedTokenError(
+      `invalid scoped token subject: ${err instanceof Error ? err.message : String(err)}`,
+      401
+    );
+  }
+  if (options?.expectedProjectId && subject.projectId !== options.expectedProjectId) {
+    throw new ScopedTokenError(
+      "scoped token is bound to a different project",
+      403
+    );
+  }
+  if (options?.expectedTenantId && subject.tenantId !== options.expectedTenantId) {
+    throw new ScopedTokenError(
+      "scoped token is bound to a different tenant",
+      403
+    );
+  }
+  return {
+    claims,
+    subject,
+    context: parseContextHeader(request.headers.get(CONTEXT_HEADER))
+  };
+}
+
 // src/server/callback-client.ts
 function createCallbackClient(callback, opts) {
   const { executionId, signingSecret } = opts;
@@ -284,6 +345,7 @@ async function hmacSha256Hex(secret, body) {
   return Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 export {
+  ScopedTokenError,
   ServerClientError,
   createCallbackClient,
   createServerClient,
@@ -291,6 +353,7 @@ export {
   parseSubject,
   recordsReadModels,
   recordsWriteModels,
+  requireScopedToken,
   verifyScopedToken,
   verifyWebhookSignature
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foir/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Official Foir SDK — editor iframe client + server-side platform helpers",
   "type": "module",
   "publishConfig": {
@@ -33,6 +33,10 @@
       "types": "./dist/auth.d.ts",
       "import": "./dist/auth.js"
     },
+    "./push": {
+      "types": "./dist/push.d.ts",
+      "import": "./dist/push.js"
+    },
     "./realtime": {
       "types": "./dist/realtime.d.ts",
       "import": "./dist/realtime.js"