@foir/sdk 0.10.0 → 0.12.0

package/dist/next.js

@@ -87,7 +87,12 @@ var FoirRequestError = class extends Error {
    * failed on the first attempt for an hour.
    */
   get retryable() {
-    if (this.status === void 0) return true;
+    if (this.status === void 0) {
+      if (this.graphQLErrors?.length || this.prunedSelections?.length) {
+        return this.code === "RATE_LIMITED" || this.code === "UNAVAILABLE" || this.code === "TIMEOUT";
+      }
+      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";
@@ -101,19 +106,50 @@ var FoirRequestError = class extends Error {
     return typeof seconds === "number" && seconds > 0 ? seconds * 1e3 : void 0;
   }
 };
+var DISPATCH_RESERVED_HEADERS = /* @__PURE__ */ new Set([
+  "x-api-key",
+  "authorization",
+  "x-foir-token",
+  "x-foir-context"
+]);
+function refuseCredentialHeaders(extra) {
+  if (!extra) return;
+  for (const name of Object.keys(extra)) {
+    if (DISPATCH_RESERVED_HEADERS.has(name.toLowerCase())) {
+      throw new FoirRequestError(
+        `[foir] a client built from a dispatch token cannot send "${name}" in \`headers\`. The dispatch token is the credential, and an api key or a bearer beside it would make the request two actors at once. Build a separate client for the other credential.`
+      );
+    }
+  }
+}
+var FOIR_VISITOR_IP_HEADER = "X-Foir-Visitor-IP";
 function buildFoirHeaders(input) {
   const headers = {
-    "Content-Type": "application/json",
-    "x-api-key": input.apiKey
+    "Content-Type": "application/json"
   };
-  if (input.draftChannel) {
-    headers["X-Foir-Schema-Channel"] = "draft";
-  }
-  if (input.bearerToken) {
-    headers["Authorization"] = `Bearer ${input.bearerToken}`;
-  }
-  if (input.orgId) {
-    headers["X-Org-Id"] = input.orgId;
+  if (input.dispatchToken !== void 0) {
+    refuseCredentialHeaders(input.extra);
+    headers["X-Foir-Token"] = input.dispatchToken;
+    if (input.dispatchContext) {
+      headers["X-Foir-Context"] = input.dispatchContext;
+    }
+  } else {
+    headers["x-api-key"] = input.apiKey;
+    if (input.draftChannel) {
+      headers["X-Foir-Schema-Channel"] = "draft";
+    }
+    if (input.bearerToken) {
+      headers["Authorization"] = `Bearer ${input.bearerToken}`;
+    }
+    if (input.orgId) {
+      headers["X-Org-Id"] = input.orgId;
+    }
+    if (input.orgUrl) {
+      headers["X-Org-Url"] = input.orgUrl;
+    }
+    if (input.visitorAddress) {
+      headers[FOIR_VISITOR_IP_HEADER] = input.visitorAddress;
+    }
   }
   if (input.extra) {
     for (const [key, value] of Object.entries(input.extra)) {
@@ -129,6 +165,26 @@ function foirApiEndpoint(apiUrl, path) {
   }
   return base + path;
 }
+var FoirAuthDowngradedError = class extends FoirRequestError {
+  downgrade;
+  constructor(downgrade) {
+    super(
+      `[foir] your customer token was ${downgrade.customerToken} (${downgrade.reason}), so the request was served as ${downgrade.servedAs}`,
+      { graphQLErrors: [{ message: "customer token rejected", extensions: { code: "AUTH_DOWNGRADED" } }] }
+    );
+    this.name = "FoirAuthDowngradedError";
+    this.downgrade = downgrade;
+  }
+};
+var FoirSessionExpiredError = class extends FoirRequestError {
+  constructor(options) {
+    super("[foir] the customer session has expired and could not be refreshed: sign in again", {
+      cause: options?.cause,
+      graphQLErrors: [{ message: "session expired", extensions: { code: "SESSION_EXPIRED" } }]
+    });
+    this.name = "FoirSessionExpiredError";
+  }
+};
 var warnedDowngrade = null;
 function reportAuthDowngrade(envelope) {
   const downgrade = envelope.extensions?.auth;
@@ -157,12 +213,18 @@ function refusePrunedDocument(json, options) {
     `[foir] selections stripped from this query: ${selections.map(describe).join(", ")}`
   );
 }
+function answeredAnything(data) {
+  return typeof data === "object" && data !== null && Object.values(data).some((value) => value !== null && value !== void 0);
+}
 function readFoirEnvelope(json, options) {
+  if (options?.rejectDowngrade && json.extensions?.auth) {
+    throw new FoirAuthDowngradedError(json.extensions.auth);
+  }
   reportAuthDowngrade(json);
   refusePrunedDocument(json, options);
   if (json.errors?.length) {
     const msg = json.errors.map((e) => e.message).join("; ");
-    if (json.data && !options?.strict) {
+    if (answeredAnything(json.data) && !options?.strict) {
       console.warn(`[foir] GraphQL partial errors (data returned): ${msg}`);
     } else {
       throw new FoirRequestError(`[foir] GraphQL errors: ${msg}`, {
@@ -676,15 +738,54 @@ function operationName(scope, op) {
 function foirDataEndpoint(apiUrl, path) {
   return foirApiEndpoint(apiUrl, path);
 }
+async function resolveVisitorAddress(config) {
+  const source = config.visitor;
+  const value = typeof source === "function" ? await source() : source;
+  const address = value?.trim();
+  return address ? address : void 0;
+}
 async function resolveBearerToken(config) {
   const source = config.bearerToken;
   if (typeof source === "function") return await source() ?? void 0;
   return source ?? void 0;
 }
+async function resolveDispatchToken(dispatch) {
+  const token = (await dispatch.token())?.trim();
+  if (!token) {
+    throw new FoirRequestError(
+      "[foir] the dispatch token provider returned no token. A client built from a dispatch calls Foir as that operation and holds no other credential. Build it from the token the endpoint was handed: `(await requireScopedToken(request)).dispatch`."
+    );
+  }
+  return token;
+}
+async function resolveFoirAuth(config) {
+  if (config.dispatch !== void 0) {
+    return {
+      headers: buildFoirHeaders({
+        dispatchToken: await resolveDispatchToken(config.dispatch),
+        dispatchContext: config.dispatch.context ?? void 0,
+        extra: config.headers
+      })
+    };
+  }
+  const bearerToken = await resolveBearerToken(config);
+  return {
+    headers: buildFoirHeaders({
+      apiKey: config.apiKey,
+      draftChannel: config.channel === "draft",
+      bearerToken,
+      orgId: config.orgId,
+      orgUrl: config.orgUrl,
+      visitorAddress: await resolveVisitorAddress(config),
+      extra: config.headers
+    }),
+    key: { apiKey: config.apiKey, bearerToken }
+  };
+}
 function foirRoute(input) {
   if (!input.apiKey.startsWith("pk_")) return { lane: "origin", reason: "key" };
   if (input.bearerToken) return { lane: "origin", reason: "bearer" };
-  if (input.orgId) return { lane: "origin", reason: "org" };
+  if (input.orgId || input.orgUrl) return { lane: "origin", reason: "org" };
   if (input.mutation) return { lane: "origin", reason: "operation" };
   if (input.writeToken) return { lane: "origin", reason: "floor" };
   if (input.channel === "draft") return { lane: "origin", reason: "channel" };
@@ -699,25 +800,45 @@ async function executeFoirDocument(config, plan) {
   }
   return data[plan.rootField];
 }
+var renewing = /* @__PURE__ */ new WeakMap();
+function renewBearerOnce(refresh) {
+  const running = renewing.get(refresh);
+  if (running) return running;
+  const next = refresh().finally(() => renewing.delete(refresh));
+  renewing.set(refresh, next);
+  return next;
+}
 async function runFoirDocument(config, document, mutation, variables, options) {
+  try {
+    return await sendFoirDocument(config, document, mutation, variables, options);
+  } catch (err) {
+    const refresh = config.refreshBearer;
+    if (!(err instanceof FoirAuthDowngradedError) || !refresh || err.downgrade.reason === "wrong_project") {
+      throw err;
+    }
+    const token = err.downgrade.reason === "expired" ? await renewBearerOnce(refresh) : null;
+    if (!token) throw new FoirSessionExpiredError({ cause: err });
+    try {
+      return await sendFoirDocument({ ...config, bearerToken: token }, document, mutation, variables, options);
+    } catch (again) {
+      if (again instanceof FoirAuthDowngradedError) throw new FoirSessionExpiredError({ cause: again });
+      throw again;
+    }
+  }
+}
+async function sendFoirDocument(config, document, mutation, variables, options) {
   const doFetch = config.fetch ?? globalThis.fetch;
   const endpoint = foirDataEndpoint(config.apiUrl, "/graphql");
-  const bearerToken = await resolveBearerToken(config);
-  const headers = buildFoirHeaders({
-    apiKey: config.apiKey,
-    draftChannel: config.channel === "draft",
-    bearerToken,
-    orgId: config.orgId,
-    extra: config.headers
-  });
+  const { headers, key } = await resolveFoirAuth(config);
   const hash = await documentHash(document);
-  const route = foirRoute({
-    apiKey: config.apiKey,
-    bearerToken,
+  const sharedKey = key !== void 0 && foirRoute({
+    apiKey: key.apiKey,
+    bearerToken: key.bearerToken,
     orgId: config.orgId,
+    orgUrl: config.orgUrl,
     mutation,
     channel: config.channel
-  });
+  }).lane === "shared" ? key.apiKey : void 0;
   const post = (body) => doFetch(endpoint, {
     method: "POST",
     headers,
@@ -727,8 +848,8 @@ async function runFoirDocument(config, document, mutation, variables, options) {
   const extensions = persistedQueryExtension(hash);
   let res;
   try {
-    if (route.lane === "shared") {
-      res = await doFetch(buildCdnUrl(endpoint, config.apiKey, hash, variables), {
+    if (sharedKey !== void 0) {
+      res = await doFetch(buildCdnUrl(endpoint, sharedKey, hash, variables), {
         method: "GET",
         headers,
         ...config.requestInit
@@ -754,7 +875,7 @@ async function runFoirDocument(config, document, mutation, variables, options) {
     });
   }
   const json = await res.json();
-  return readFoirEnvelope(json, options);
+  return readFoirEnvelope(json, { ...options, rejectDowngrade: Boolean(key?.bearerToken) });
 }
 async function readErrorBody(res) {
   try {
@@ -766,20 +887,16 @@ async function readErrorBody(res) {
 }
 
 // src/data/manifest.ts
-async function fetchFoirManifest(config) {
-  const url = foirDataEndpoint(config.apiUrl, "/v1/manifest");
+async function fetchFoirManifest(config, options = {}) {
+  const base = foirDataEndpoint(config.apiUrl, "/v1/manifest");
+  const url = options.operation === void 0 ? base : `${base}?operation=${encodeURIComponent(options.operation)}`;
   const doFetch = config.fetch ?? globalThis.fetch;
+  const { headers } = await resolveFoirAuth(config);
   let res;
   try {
     res = await doFetch(url, {
       method: "GET",
-      headers: buildFoirHeaders({
-        apiKey: config.apiKey,
-        draftChannel: config.channel === "draft",
-        bearerToken: await resolveBearerToken(config),
-        orgId: config.orgId,
-        extra: config.headers
-      }),
+      headers,
       ...config.requestInit
     });
   } catch (err) {
@@ -851,6 +968,7 @@ function authClientConfig(env, options) {
     channel: isFoirPreview(env) ? "draft" : "published",
     bearerToken: options?.bearerToken,
     orgId: options?.orgId,
+    orgUrl: options?.orgUrl,
     headers: options?.headers,
     fetch: options?.fetch
   };
@@ -911,6 +1029,9 @@ async function customerProviderCallback(env, input) {
 async function saveSession(adapter, result) {
   await adapter.set(TOKEN_KEY, result.token);
   await adapter.set(REFRESH_KEY, result.refreshToken);
+  if (!result.customerId) {
+    return await getSessionCustomer(adapter) ?? { id: "", email: "" };
+  }
   await adapter.set(CUSTOMER_ID_KEY, result.customerId);
   await adapter.set(EMAIL_KEY, result.email);
   return { id: result.customerId, email: result.email };

package/dist/placement/index.d.ts

@@ -0,0 +1,129 @@
+/**
+ * `@foir/sdk/placement`: your app's own admin console, shown inside Foir's.
+ *
+ * A full-page placement is loaded in a frame on the Foir console. No cookie
+ * reaches a cross-site frame, so the console hands the page a short-lived token
+ * instead, by message, to your placement's origin only. The token is the
+ * operator looking at the page, acting through your app at the level your app
+ * is installed at, carrying the scopes your placement declares that this
+ * operator holds. Your page runs no login of its own.
+ *
+ * ```ts
+ * import { connectPlacement, FOIR_CONSOLE_ORIGINS } from '@foir/sdk/placement';
+ *
+ * const session = await connectPlacement({
+ *   apiUrl: 'https://api.foir.dev',
+ *   consoleOrigins: FOIR_CONSOLE_ORIGINS.production,
+ * });
+ * if (session.can('records:write:preorder')) showEditButtons();
+ * const data = await session.request('{ preorders { items { id } } }');
+ * ```
+ *
+ * The browser shows the page blank, however well it is authenticated, unless
+ * the page allows the console as a frame ancestor. Hydrogen and many other
+ * frameworks send `frame-ancestors 'none'` by default. `placementFrameAncestors`
+ * builds the header value; the console and the install preview list the origins
+ * your project needs.
+ */
+/** The messages the console and an embedded page exchange. */
+export declare const PLACEMENT_MESSAGE: {
+    /** Page to console: the page is listening and wants a token. */
+    readonly ready: "foir:placement:ready";
+    /** Console to page: a token. */
+    readonly token: "foir:placement:token";
+    /** Page to console: the token is about to lapse; a fresh one, please. */
+    readonly refresh: "foir:placement:refresh";
+    /** Console to page: no token, and why. */
+    readonly refused: "foir:placement:refused";
+    /** Console to page: the operator signed out. */
+    readonly signedOut: "foir:placement:signed-out";
+};
+/** What the console hands an embedded page. */
+export interface PlacementGrant {
+    /** The bearer for Foir's API. */
+    accessToken: string;
+    /** When it lapses, RFC 3339. The session asks for a fresh one before then. */
+    expiresAt: string;
+    /** The organisation the page acts at: your app's install. Empty for the project. */
+    orgId: string;
+    /** What the token carries. */
+    grantedScopes: string[];
+    /** What your placement declares that this operator does not hold, and why. */
+    withheld: {
+        scope: string;
+        reason: string;
+    }[];
+}
+/** A message the console sends an embedded page. */
+export type PlacementHostMessage = {
+    type: typeof PLACEMENT_MESSAGE.token;
+    grant: PlacementGrant;
+} | {
+    type: typeof PLACEMENT_MESSAGE.refused;
+    reason: string;
+} | {
+    type: typeof PLACEMENT_MESSAGE.signedOut;
+};
+/** A message an embedded page sends the console. */
+export type PlacementPageMessage = {
+    type: typeof PLACEMENT_MESSAGE.ready;
+} | {
+    type: typeof PLACEMENT_MESSAGE.refresh;
+};
+/**
+ * The Foir consoles, per environment. A project that serves the console on its
+ * own verified admin domain adds that origin too: the install preview lists it.
+ */
+export declare const FOIR_CONSOLE_ORIGINS: {
+    readonly production: readonly ["https://app.foir.io"];
+    readonly dev: readonly ["https://app-dev.foir.io"];
+};
+/**
+ * The `Content-Security-Policy` value that lets these consoles show your page:
+ * `frame-ancestors https://app.foir.io`. Set it on every response the
+ * placement's page serves.
+ */
+export declare function placementFrameAncestors(origins: readonly string[]): string;
+/** Why the console would not give the page a token. */
+export declare class PlacementRefused extends Error {
+    constructor(reason: string);
+}
+export interface ConnectPlacementOptions {
+    /** Foir's API, e.g. `https://api.foir.dev`. */
+    apiUrl: string;
+    /**
+     * The consoles your page accepts a token from. A message from any other
+     * origin is ignored, so a page framed elsewhere never receives one.
+     */
+    consoleOrigins: readonly string[];
+    /** How long to wait for the first token. Default 10 seconds. */
+    timeoutMs?: number;
+    /** How long before expiry to ask for a fresh token. Default 60 seconds. */
+    refreshBeforeMs?: number;
+    /** The page's window. Default the global one; tests pass their own. */
+    window?: Window;
+    /** The fetch the session's requests use. Default the global one. */
+    fetch?: typeof fetch;
+}
+/** An embedded page's connection to the console that showed it. */
+export interface PlacementSession {
+    /** The grant in force now. Replaced as the session refreshes. */
+    readonly grant: PlacementGrant;
+    /** Whether the token carries this scope, to hide or grey out what the operator cannot do. */
+    can(scope: string): boolean;
+    /** A GraphQL request to Foir's API as the operator, through your app. */
+    request<TResult = unknown>(document: string | {
+        toString(): string;
+    }, variables?: Record<string, unknown>): Promise<TResult>;
+    /** Called when the operator signs out; the session holds no token from then on. */
+    onSignedOut(listener: () => void): () => void;
+    /** Stop listening and refreshing. */
+    close(): void;
+}
+/**
+ * Connect an embedded page to the console showing it: tell the console the page
+ * is listening, wait for its token, and keep the token fresh while the page is
+ * open. Resolves with the session, or rejects with `PlacementRefused` when the
+ * console gives no token, or when none arrives in time.
+ */
+export declare function connectPlacement(options: ConnectPlacementOptions): Promise<PlacementSession>;

package/dist/placement.js

@@ -0,0 +1,144 @@
+// src/placement/index.ts
+var PLACEMENT_MESSAGE = {
+  /** Page to console: the page is listening and wants a token. */
+  ready: "foir:placement:ready",
+  /** Console to page: a token. */
+  token: "foir:placement:token",
+  /** Page to console: the token is about to lapse; a fresh one, please. */
+  refresh: "foir:placement:refresh",
+  /** Console to page: no token, and why. */
+  refused: "foir:placement:refused",
+  /** Console to page: the operator signed out. */
+  signedOut: "foir:placement:signed-out"
+};
+var FOIR_CONSOLE_ORIGINS = {
+  production: ["https://app.foir.io"],
+  dev: ["https://app-dev.foir.io"]
+};
+function placementFrameAncestors(origins) {
+  if (origins.length === 0) {
+    throw new Error("[foir] placementFrameAncestors needs at least one console origin");
+  }
+  for (const o of origins) {
+    let u;
+    try {
+      u = new URL(o);
+    } catch {
+      throw new Error(`[foir] placementFrameAncestors: ${JSON.stringify(o)} is not an origin`);
+    }
+    if (u.protocol !== "https:" || u.origin !== o) {
+      throw new Error(`[foir] placementFrameAncestors: ${JSON.stringify(o)} must be an https origin, such as https://app.foir.io`);
+    }
+  }
+  return `frame-ancestors ${origins.join(" ")}`;
+}
+var PlacementRefused = class extends Error {
+  constructor(reason) {
+    super(reason);
+    this.name = "PlacementRefused";
+  }
+};
+function isHostMessage(data) {
+  if (typeof data !== "object" || data === null) return false;
+  const t = data.type;
+  return t === PLACEMENT_MESSAGE.token || t === PLACEMENT_MESSAGE.refused || t === PLACEMENT_MESSAGE.signedOut;
+}
+function connectPlacement(options) {
+  const win = options.window ?? window;
+  const doFetch = options.fetch ?? fetch;
+  const timeoutMs = options.timeoutMs ?? 1e4;
+  const refreshBeforeMs = options.refreshBeforeMs ?? 6e4;
+  const allowed = new Set(options.consoleOrigins);
+  const apiUrl = options.apiUrl.replace(/\/+$/, "");
+  if (win.parent === win) {
+    return Promise.reject(new PlacementRefused("this page is not inside the Foir console, so there is no console to give it a token"));
+  }
+  return new Promise((resolve, reject) => {
+    let grant = null;
+    let settled = false;
+    let refreshTimer;
+    const signedOut = /* @__PURE__ */ new Set();
+    const post = (message) => {
+      win.parent.postMessage(message, "*");
+    };
+    const scheduleRefresh = () => {
+      clearTimeout(refreshTimer);
+      if (!grant) return;
+      const due = Date.parse(grant.expiresAt) - Date.now() - refreshBeforeMs;
+      refreshTimer = setTimeout(() => post({ type: PLACEMENT_MESSAGE.refresh }), Math.max(0, due));
+    };
+    const close = () => {
+      clearTimeout(refreshTimer);
+      clearTimeout(timeout);
+      win.removeEventListener("message", onMessage);
+    };
+    const session = {
+      get grant() {
+        if (!grant) throw new PlacementRefused("the operator has signed out");
+        return grant;
+      },
+      can: (scope) => grant?.grantedScopes.includes(scope) ?? false,
+      async request(document, variables) {
+        if (!grant) throw new PlacementRefused("the operator has signed out");
+        const res = await doFetch(`${apiUrl}/graphql`, {
+          method: "POST",
+          headers: { "content-type": "application/json", authorization: `Bearer ${grant.accessToken}` },
+          body: JSON.stringify({ query: String(document), variables: variables ?? {} })
+        });
+        const body = await res.json().catch(() => ({}));
+        if (!res.ok || body.errors && body.errors.length > 0) {
+          const messages = body.errors?.map((e) => e.message).join("; ") || `HTTP ${res.status}`;
+          throw new Error(`[foir] placement request failed: ${messages}`);
+        }
+        return body.data;
+      },
+      onSignedOut(listener) {
+        signedOut.add(listener);
+        return () => signedOut.delete(listener);
+      },
+      close
+    };
+    function onMessage(event) {
+      if (event.source !== win.parent || !allowed.has(event.origin) || !isHostMessage(event.data)) return;
+      const msg = event.data;
+      switch (msg.type) {
+        case PLACEMENT_MESSAGE.token:
+          grant = msg.grant;
+          scheduleRefresh();
+          if (!settled) {
+            settled = true;
+            clearTimeout(timeout);
+            resolve(session);
+          }
+          return;
+        case PLACEMENT_MESSAGE.refused:
+          if (!settled) {
+            settled = true;
+            close();
+            reject(new PlacementRefused(msg.reason));
+          }
+          return;
+        case PLACEMENT_MESSAGE.signedOut:
+          grant = null;
+          close();
+          for (const l of signedOut) l();
+          return;
+      }
+    }
+    const timeout = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      close();
+      reject(new PlacementRefused(`no token arrived from the Foir console within ${timeoutMs} ms`));
+    }, timeoutMs);
+    win.addEventListener("message", onMessage);
+    post({ type: PLACEMENT_MESSAGE.ready });
+  });
+}
+export {
+  FOIR_CONSOLE_ORIGINS,
+  PLACEMENT_MESSAGE,
+  PlacementRefused,
+  connectPlacement,
+  placementFrameAncestors
+};