@isomorph.ai/app-sdk 2.6.2 → 2.7.1

package/README.md

@@ -533,6 +533,21 @@ await runtimeSecrets.delete(`supplier-key/${ctx.user.id}`);
 
 (1.36.0, 1.36.1, 1.45.0; data plane ADR 0090)
 
+## Another app's address and this app's environment
+
+`appApiUrl(name)` is another app's API address in the environment the calling code runs in: its preview from preview, its production from production. `name` is that app's address name (the first part of its API host).
+
+```ts
+import { appApiUrl } from '@isomorph.ai/app-sdk';
+const reply = await fetch(`${appApiUrl('ats')}/_harbour/api/list-openings`, { method: 'POST', headers, body });
+```
+
+- It is `https://<name>.<ISOMORPH_APPS_API_SUFFIX>`. Provision sets the suffix on a deployed app's actions and jobs from the app's own API host; `isomorph check` and `isomorph dev` set it from the app's preview address.
+- A name that is not lower-case letters, digits and hyphens (one DNS label) throws `VALIDATION_FAILED`. Without the suffix (a browser, or a local run with no app address) it throws an `UNAVAILABLE` error whose `details.code` is `APP_API_ADDRESS_UNAVAILABLE`.
+- `process.env.ISOMORPH_ENVIRONMENT` is `preview` or `production` on a deployed app, and `local` under `isomorph dev`.
+
+(2.7.0; data plane ADR 2026-11-06, kit apps learn their environment and the apps' API suffix)
+
 ## Running and rollout
 
 `isomorph dev` uses canned server-model fixtures. `dev --real` supplies an approved development connection to the action process. Hosted actions resolve their exact ACTIVE version key. The current V2 PLAN is published after LIVE; before key activation, an AI action fails and later actions retry. LIVE alone is not AI acceptance.
@@ -573,6 +588,14 @@ and no second GET is sent. When the refresh fails, `identity.current()`
 answers `null` and listeners hear `null`, as before. On the page's own origin
 the identity GET is never renewed (it is the renewal). (1.5.3)
 
+When the renewal cannot restore the sign-in — the refresh failed, or the
+resend was refused again — the session has ended (a platform operator's
+session never renews; any session ends at its lifetime). That refusal's
+message is `Your sign-in has ended. Reload the page to sign in again.`, which
+you can show as is; its `category` (`AUTH_REQUIRED`), `status` (401),
+`requestId` and `details` are unchanged, so branch on `category`. A 401 your
+own action or a connected service gave keeps its own message. (2.7.1)
+
 ## External OTP users
 
 Use `user.id` for ownership and database row rules. External users can sign in with a phone number and have no email. `user.name`, `user.phone`, `user.email` and the `emailVerified`/`phoneVerified` flags describe their profile; an optional contact is not verified automatically. `user.directory` identifies `company` or `external`. Database transactions also expose `current_setting('harbour.directory', true)` when a row rule needs that distinction.

package/dist/index.d.ts

@@ -2026,6 +2026,12 @@ declare class RealtimeChannelBuilder {
 }
 /** One request on the gateway with the client's headers and refusals; for the kit runtime's own calls. */
 export declare function gatewayRequest<T>(options: ClientOptions, path: string, init?: RequestInit): Promise<T>;
+/**
+ * Another app's API address in the environment this code runs in: its preview from preview, its production
+ * from production. `name` is that app's address name. Server code only; the platform sets
+ * ISOMORPH_APPS_API_SUFFIX on a deployed app and `isomorph dev` sets it locally.
+ */
+export declare function appApiUrl(name: string): string;
 export declare function createClient(options?: ClientOptions): {
     identity: {
         current: () => Promise<IsomorphUser | null>;

package/dist/index.js

@@ -183,6 +183,18 @@ function renewableOnUnauthorized(path) {
         return false;
     return path.startsWith('/_harbour/') && path !== IDENTITY_PATH;
 }
+// A browser call still refused after the renewal could not restore the
+// identity (the API-host refresh failed, or the resend was refused again)
+// means the person's sign-in has ended: a platform operator's session never
+// renews (governance ADR 0178), and any session ends at its lifetime. The
+// gateway's wire message is for engineers, and apps showed it verbatim to
+// people mid-task (escplan, 2026-11-07), so that refusal reads as a plain
+// instruction instead; category, status, requestId and details are kept.
+// Only the identity refusal is reworded — the gateway's own sentence, or a
+// 401 with no Isomorph error at all (an edge refusal). A 401 an action or a
+// connected service gave keeps its own words.
+const IDENTITY_REFUSAL = 'signed Isomorph identity is required';
+const SIGN_IN_ENDED = 'Your sign-in has ended. Reload the page to sign in again.';
 class Transport {
     onUnauthorized;
     baseUrl;
@@ -207,7 +219,7 @@ class Transport {
     json(path, init = {}, onProgress) {
         return this.request(path, init, renewableOnUnauthorized(path) || (this.separateApiHost && path === IDENTITY_PATH), onProgress);
     }
-    async request(path, init, renewOnUnauthorized, onProgress) {
+    async request(path, init, renewOnUnauthorized, onProgress, renewalTried = false) {
         const sentAt = this.renewal?.renewals() ?? 0;
         const action = currentAction();
         // (headers with an undefined value are removed so a multipart body can
@@ -245,13 +257,17 @@ class Transport {
                     if (renewed && path === IDENTITY_PATH)
                         return renewed;
                     if (renewed !== false)
-                        return this.request(path, init, false, onProgress);
+                        return this.request(path, init, false, onProgress, true);
+                    renewalTried = true;
                 }
                 // Not before the resend: a page listening to identity.onChange would
                 // otherwise see the user flicker to null while the edge was healing.
                 this.onUnauthorized?.();
             }
-            throw new IsomorphError(body?.error?.category ?? (response.status === 401 ? 'AUTH_REQUIRED' : response.status === 403 ? 'FORBIDDEN' : 'INTERNAL'), body?.error?.message ?? `Isomorph request failed with ${response.status}`, body?.requestId ?? response.headers.get('x-request-id') ?? undefined, body?.error?.details, response.status);
+            const category = body?.error?.category ?? (response.status === 401 ? 'AUTH_REQUIRED' : response.status === 403 ? 'FORBIDDEN' : 'INTERNAL');
+            const signInEnded = renewalTried && response.status === 401 && category === 'AUTH_REQUIRED'
+                && (body?.error?.message === undefined || body.error.message === IDENTITY_REFUSAL);
+            throw new IsomorphError(category, signInEnded ? SIGN_IN_ENDED : body?.error?.message ?? `Isomorph request failed with ${response.status}`, body?.requestId ?? response.headers.get('x-request-id') ?? undefined, body?.error?.details, response.status);
         }
         return (body && Object.prototype.hasOwnProperty.call(body, 'data') ? body.data : body);
     }
@@ -435,6 +451,22 @@ class RealtimeChannelBuilder {
 export function gatewayRequest(options, path, init) {
     return new Transport(options).json(path, init);
 }
+const DNS_LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+/**
+ * Another app's API address in the environment this code runs in: its preview from preview, its production
+ * from production. `name` is that app's address name. Server code only; the platform sets
+ * ISOMORPH_APPS_API_SUFFIX on a deployed app and `isomorph dev` sets it locally.
+ */
+export function appApiUrl(name) {
+    if (typeof name !== 'string' || !DNS_LABEL.test(name)) {
+        throw new IsomorphError('VALIDATION_FAILED', `${JSON.stringify(name)} is not an app address name: lower-case letters, digits and hyphens, at most 63, starting and ending with a letter or digit.`, undefined, { code: 'VALIDATION_FAILED' });
+    }
+    const suffix = typeof process === 'undefined' ? undefined : process.env.ISOMORPH_APPS_API_SUFFIX;
+    if (!suffix) {
+        throw new IsomorphError('UNAVAILABLE', `Another app's address is not known here. appApiUrl works in a deployed app's actions and jobs, and under isomorph dev for an app that has an address.`, undefined, { code: 'APP_API_ADDRESS_UNAVAILABLE' });
+    }
+    return `https://${name}.${suffix}`;
+}
 export function createClient(options = {}) {
     const authListeners = new Set();
     let currentUser;

package/dist/runtime.js

@@ -57,6 +57,11 @@
 //   ISOMORPH_JOBS_QUEUE_URL       an enqueue sends the run to this SQS queue and
 //                                 the queue loop never runs here: the cell's
 //                                 Event Function works it (lambda-events-entry.ts)
+//   ISOMORPH_ENVIRONMENT          preview or production, set by Provision (by the
+//                                 CLI under isomorph check and isomorph dev); the
+//                                 SDK itself never reads it
+//   ISOMORPH_APPS_API_SUFFIX      the part of this app's API host after its own
+//                                 name, which appApiUrl puts after another app's
 import { createHash, randomBytes } from 'node:crypto';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { createServer } from 'node:http';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isomorph.ai/app-sdk",
-  "version": "2.6.2",
+  "version": "2.7.1",
   "type": "module",
   "repository": {
     "type": "git",