@foir/sdk 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -108,6 +108,49 @@ 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.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
+platform that production serves from the next promotion; `latest` moves to it
+then.
+
+### Added
+
+- **`notifications.setConsent` answers `confirmationPending`**, and takes
+  `givenElsewhere` and `locale` (`@foir/sdk/app`). A project can ask that an
+  opt-in an app collects in a category is confirmed by email before it counts.
+  In such a category an opt-in writes nothing: the platform sends the customer
+  one confirmation email, in the page's `locale` when they have stated no
+  language of their own, and the answer says `confirmationPending`. The
+  preference turns on when they follow the link. Everywhere else an opt-in is
+  applied at once, as before.
+- A consent the app carries over from the system it was given in says
+  `givenElsewhere: true`, and is applied as it stands.
+
+### Changed
+
+- `notifications.setConsent` asks the platform for `confirmationPending`, a
+  field a platform older than this release does not have.
+
 ## [0.14.0] — 2026-10-01
 
 Published under npm's `next` tag from `dev`, because it calls parts of the

package/dist/app/client.d.ts

@@ -183,6 +183,22 @@ export interface AppConsentChange {
      * answering `stale`.
      */
     sourceModifiedAt?: string;
+    /**
+     * True when the customer gave this consent in another system and the app is
+     * carrying it over (a mirror). It is applied as it stands.
+     *
+     * Left out, the app collected the consent itself (a sign-up form), and an
+     * opt-in is applied the way its category says: at once, or, in a category
+     * that confirms by email, only when the customer follows the link the
+     * platform sends them. Until then nothing is written and the answer says
+     * `confirmationPending`.
+     */
+    givenElsewhere?: boolean;
+    /**
+     * The language of the page the consent was collected on. The confirmation
+     * email is written in it when the customer has stated none of their own.
+     */
+    locale?: string;
 }
 /** What the calling token is, and what it is served. Read from the platform, never off the token. */
 export interface AppWhoami {
@@ -409,9 +425,16 @@ export interface AppClient {
         /**
          * Set a named customer's consent in an opt-in category. Needs
          * `notifications:consent`, which only an operation's token carries.
+         *
+         * `confirmationPending` is true when an opt-in the app collected was not
+         * applied because its category confirms by email first: the customer has
+         * been sent a link, or was sent one recently, and the preference turns on
+         * when they follow it. The answer is the same whether or not the address
+         * already had a customer.
          */
         setConsent(change: AppConsentChange): Promise<{
             stale: boolean;
+            confirmationPending: boolean;
         }>;
     };
     operations: {

package/dist/app.js

@@ -825,13 +825,15 @@ function createAppClient(config) {
           enabled: change.enabled
         };
         if (change.sourceModifiedAt !== void 0) input.sourceModifiedAt = change.sourceModifiedAt;
+        if (change.givenElsewhere !== void 0) input.givenElsewhere = change.givenElsewhere;
+        if (change.locale !== void 0) input.locale = change.locale;
         const answer = await field(
           "setCustomerConsent",
-          `mutation AppSetCustomerConsent($input: SetCustomerConsentInput!) { setCustomerConsent(input: $input) { stale } }`,
+          `mutation AppSetCustomerConsent($input: SetCustomerConsentInput!) { setCustomerConsent(input: $input) { stale confirmationPending } }`,
           { input }
         );
         if (!answer) return refuse("setCustomerConsent reported no error and answered nothing");
-        return { stale: answer.stale === true };
+        return { stale: answer.stale === true, confirmationPending: answer.confirmationPending === true };
       }
     },
     operations: {

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

@@ -4,8 +4,8 @@
  * Used by config API backends (e.g., Hono servers) to query the platform
  * GraphQL API at runtime. Provisioning (models, operations, schedules) is
  * handled by `foir push`. Record writes from upstream sources go through
- * the scoped-token `upsertRecord` GraphQL mutation served by the
- * integrations gateway, not through this client.
+ * the scoped-token `upsertRecord` GraphQL mutation an app's token reaches
+ * (`@foir/sdk/app`), not through this client.
  *
  * Auth: All requests use an API key (x-api-key header).
  */

package/package.json

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