@foir/sdk 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -108,6 +108,28 @@ 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

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/package.json

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