@foir/sdk 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -108,6 +108,47 @@ nobody asking for `@foir/sdk` gets it early. The push that carries the commit to
 
 Changes on `dev` that have not been published to npm.
 
+## [0.17.0] — 2026-10-02
+
+Published under npm's `next` tag from `dev`, because it reads a field the
+platform serves from the next promotion; `latest` moves to it then.
+
+### Added
+
+- **An app is told when a project cannot email its customers**
+  (`@foir/sdk/app`). A project with no App base URL used to accept a
+  notification's email and drop it. The platform now refuses a notification
+  that carries an email, and an opt-in to a category confirmed by email, with
+  the reason as data. `appCustomerEmailUnavailableOf(error)` reads it:
+  `{ reason: 'NO_APP_BASE_URL' }`, or `null` for any other failure.
+- `install.config()` answers `customerEmailUnavailable`: the same reason ahead
+  of time, or `null` when the project can send. `AppCustomerEmailUnavailableReason`
+  is the type.
+
+### Changed
+
+- `install.config()` asks the platform for `customerEmailUnavailable`, a field
+  a platform older than this release does not have.
+
+## [0.16.0] — 2026-10-02
+
+Published under npm's `next` tag from `dev`, as 0.15.0 was; `latest` moves to
+it at the next promotion.
+
+### Added
+
+- **An embedded page is told how the console looks** (`@foir/sdk/placement`).
+  The console's theme is the operator's own setting, which a framed page cannot
+  see, so a page that followed the system's preference could sit dark inside a
+  light console. `connectPlacement` takes `onAppearance`, called with
+  `{ theme: 'light' | 'dark' }` as soon as the console says (before the token
+  arrives) and again whenever the operator changes it; `session.appearance`
+  holds the current one. `PlacementAppearance` is the type, and
+  `PLACEMENT_MESSAGE.appearance` the message.
+- A console older than this says nothing: `onAppearance` is not called and
+  `session.appearance` is `null`, so keep the system's preference as the
+  fallback.
+
 ## [0.15.0] — 2026-10-02
 
 Published under npm's `next` tag from `dev`, because it calls parts of the

package/dist/app/client.d.ts

@@ -28,6 +28,7 @@
  */
 import type { FoirDispatchCredential } from '../data/transport';
 import { type FoirRetryPolicy } from '../transport/retry';
+import type { AppCustomerEmailUnavailableReason } from './errors';
 type Json = null | boolean | number | string | Json[] | {
     [key: string]: Json;
 };
@@ -95,6 +96,13 @@ export interface AppInstallConfig {
     settings: JsonObject;
     sources: AppBinding[];
     sinks: AppBinding[];
+    /**
+     * Why the project cannot send a customer an email at the level this install
+     * sits at, or null when it can. While it is set, a notification that carries
+     * an email and an opt-in to a category confirmed by email are refused
+     * (`appCustomerEmailUnavailableOf`), so say so before one is.
+     */
+    customerEmailUnavailable: AppCustomerEmailUnavailableReason | null;
 }
 /**
  * The status an install reports. Leaving out `subscriptionHealth`,

package/dist/app/errors.d.ts

@@ -34,6 +34,26 @@ export declare function appCustomerUnlinkedOf(error: unknown): {
     model: string;
     identityProvider: string;
 } | null;
+/**
+ * Why a project cannot send a customer an email. `NO_APP_BASE_URL`: no App base
+ * URL is set for the project, or for the customer's organization. A reason
+ * this build does not know arrives as the platform spelled it.
+ */
+export type AppCustomerEmailUnavailableReason = 'NO_APP_BASE_URL' | (string & {});
+/** The reason as the platform sent it, or null when it sent none. */
+export declare function customerEmailUnavailableReasonOf(value: unknown): AppCustomerEmailUnavailableReason | null;
+/**
+ * A request refused because it would send a customer an email the project
+ * cannot send, or null for any other failure. Nothing was written and nothing
+ * was queued. An opt-in to a category confirmed by email is refused this way,
+ * and so is a notification that carries an email.
+ *
+ * It is about the project, not the customer: the project's operator fixes it,
+ * and the same request goes once they have.
+ */
+export declare function appCustomerEmailUnavailableOf(error: unknown): {
+    reason: AppCustomerEmailUnavailableReason;
+} | null;
 /**
  * Whether a read failed because the token is not served the field it asked
  * for: the field is not on the schema this token's capabilities reach. That is

package/dist/app/index.d.ts

@@ -22,8 +22,8 @@
  */
 export { createAppClient } from './client';
 export type { AppBinding, AppClient, AppClientConfig, AppConsentChange, AppCustomer, AppCustomerEraseResult, AppCustomerList, AppCustomerSaveResult, AppFieldMapping, AppInstallConfig, AppNotification, AppOperationStart, AppRecord, AppRecordList, AppStartedOperation, AppStatusReport, AppSyncDirection, AppUpsertResult, AppWhoami, } from './client';
-export { appCustomerUnlinkedOf, appLookupConflictOf, isAppFieldWithheld } from './errors';
-export type { AppLookupConflict } from './errors';
+export { appCustomerEmailUnavailableOf, appCustomerUnlinkedOf, appLookupConflictOf, isAppFieldWithheld } from './errors';
+export type { AppCustomerEmailUnavailableReason, AppLookupConflict } from './errors';
 export { appModelFieldName, appModelTypeName, appSelectorEnumValue } from './naming';
 export { RECORD_KEY_RULE, recordKeyRefusal } from './record-key';
 export { readAppDispatch, readCredentialProbe } from './dispatch';

package/dist/app.js

@@ -251,6 +251,13 @@ function appCustomerUnlinkedOf(error) {
   if (typeof model !== "string" || typeof identityProvider !== "string") return null;
   return { model, identityProvider };
 }
+function customerEmailUnavailableReasonOf(value) {
+  return typeof value === "string" && value !== "" ? value : null;
+}
+function appCustomerEmailUnavailableOf(error) {
+  const reason = customerEmailUnavailableReasonOf(extensionOf(error, "customerEmailUnavailable")?.reason);
+  return reason ? { reason } : null;
+}
 function isAppFieldWithheld(error, field) {
   if (!(error instanceof FoirRequestError)) return false;
   return (error.prunedSelections ?? []).some((selection) => {
@@ -490,7 +497,7 @@ function createAppClient(config) {
           "integrationConfig",
           `query AppInstallConfig {
             integrationConfig {
-              name enabled middlewareUrl targetModels webhookUrl config
+              name enabled middlewareUrl targetModels webhookUrl config customerEmailUnavailable
               sources { key model naturalKey mode fields { appField modelField direction } }
               sinks { key model naturalKey fields { appField modelField direction } }
             }
@@ -506,7 +513,8 @@ function createAppClient(config) {
           webhookUrl: got.webhookUrl ?? "",
           settings: got.config ?? {},
           sources: bindingsOf(got.sources),
-          sinks: bindingsOf(got.sinks)
+          sinks: bindingsOf(got.sinks),
+          customerEmailUnavailable: customerEmailUnavailableReasonOf(got.customerEmailUnavailable)
         };
       },
       async credentials() {
@@ -1145,6 +1153,7 @@ export {
   FoirRequestError,
   MAX_APP_MANIFEST_BYTES,
   RECORD_KEY_RULE,
+  appCustomerEmailUnavailableOf,
   appCustomerUnlinkedOf,
   appLookupConflictOf,
   appModelFieldName,

package/dist/placement/index.d.ts

@@ -19,6 +19,10 @@
  * const data = await session.request('{ preorders { items { id } } }');
  * ```
  *
+ * The console also tells the page how it looks, so the page can match it: pass
+ * `onAppearance` and apply the theme it names. The operator's console theme is
+ * their own setting and need not be their system's.
+ *
  * 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`
@@ -37,6 +41,8 @@ export declare const PLACEMENT_MESSAGE: {
     readonly refused: "foir:placement:refused";
     /** Console to page: the operator signed out. */
     readonly signedOut: "foir:placement:signed-out";
+    /** Console to page: how the console looks, now and whenever it changes. */
+    readonly appearance: "foir:placement:appearance";
 };
 /** What the console hands an embedded page. */
 export interface PlacementGrant {
@@ -54,6 +60,14 @@ export interface PlacementGrant {
         reason: string;
     }[];
 }
+/** How the console looks, for an embedded page to match. */
+export interface PlacementAppearance {
+    /**
+     * The console's theme as the operator sees it: their own choice, or their
+     * system's when they left it to the system.
+     */
+    theme: 'light' | 'dark';
+}
 /** A message the console sends an embedded page. */
 export type PlacementHostMessage = {
     type: typeof PLACEMENT_MESSAGE.token;
@@ -63,6 +77,9 @@ export type PlacementHostMessage = {
     reason: string;
 } | {
     type: typeof PLACEMENT_MESSAGE.signedOut;
+} | {
+    type: typeof PLACEMENT_MESSAGE.appearance;
+    appearance: PlacementAppearance;
 };
 /** A message an embedded page sends the console. */
 export type PlacementPageMessage = {
@@ -100,6 +117,13 @@ export interface ConnectPlacementOptions {
     timeoutMs?: number;
     /** How long before expiry to ask for a fresh token. Default 60 seconds. */
     refreshBeforeMs?: number;
+    /**
+     * Called with how the console looks: once as soon as the console says, which
+     * is before the token arrives, and again whenever the operator changes it.
+     * Apply it instead of the system's preference, so the page matches the
+     * console it is shown in.
+     */
+    onAppearance?: (appearance: PlacementAppearance) => void;
     /** 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. */
@@ -109,6 +133,11 @@ export interface ConnectPlacementOptions {
 export interface PlacementSession {
     /** The grant in force now. Replaced as the session refreshes. */
     readonly grant: PlacementGrant;
+    /**
+     * How the console looks now, or null when the console has not said (a console
+     * older than this). Kept current as the operator changes it.
+     */
+    readonly appearance: PlacementAppearance | null;
     /** 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. */

package/dist/placement.js

@@ -9,7 +9,9 @@ var PLACEMENT_MESSAGE = {
   /** Console to page: no token, and why. */
   refused: "foir:placement:refused",
   /** Console to page: the operator signed out. */
-  signedOut: "foir:placement:signed-out"
+  signedOut: "foir:placement:signed-out",
+  /** Console to page: how the console looks, now and whenever it changes. */
+  appearance: "foir:placement:appearance"
 };
 var FOIR_CONSOLE_ORIGINS = {
   production: ["https://app.foir.io"],
@@ -41,6 +43,10 @@ var PlacementRefused = class extends Error {
 function isHostMessage(data) {
   if (typeof data !== "object" || data === null) return false;
   const t = data.type;
+  if (t === PLACEMENT_MESSAGE.appearance) {
+    const theme = data.appearance?.theme;
+    return theme === "light" || theme === "dark";
+  }
   return t === PLACEMENT_MESSAGE.token || t === PLACEMENT_MESSAGE.refused || t === PLACEMENT_MESSAGE.signedOut;
 }
 function connectPlacement(options) {
@@ -55,6 +61,7 @@ function connectPlacement(options) {
   }
   return new Promise((resolve, reject) => {
     let grant = null;
+    let appearance = null;
     let settled = false;
     let refreshTimer;
     const signedOut = /* @__PURE__ */ new Set();
@@ -77,6 +84,9 @@ function connectPlacement(options) {
         if (!grant) throw new PlacementRefused("the operator has signed out");
         return grant;
       },
+      get appearance() {
+        return appearance;
+      },
       can: (scope) => grant?.grantedScopes.includes(scope) ?? false,
       async request(document, variables) {
         if (!grant) throw new PlacementRefused("the operator has signed out");
@@ -123,6 +133,10 @@ function connectPlacement(options) {
           close();
           for (const l of signedOut) l();
           return;
+        case PLACEMENT_MESSAGE.appearance:
+          appearance = { theme: msg.appearance.theme };
+          options.onAppearance?.(appearance);
+          return;
       }
     }
     const timeout = setTimeout(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foir/sdk",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Official Foir SDK — editor iframe client + server-side platform helpers",
   "type": "module",
   "publishConfig": {