@isomorph.ai/app-sdk 2.6.1 → 2.7.0

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.

package/dist/index.d.ts

@@ -298,6 +298,8 @@ export interface GmailAttachmentInput {
 export interface GmailMessageSendRequest {
     operation: 'gmail.message.send';
     resource: string;
+    /** `app` sends from the company mailbox IT connected (contracts 0.102.0); `user` (the default) sends as the signed-in person. */
+    mode?: SlackIdentityMode;
     input: {
         /** 1 to 50 email addresses per recipient list (at most 50 across to, cc and bcc). */
         to: string[];
@@ -2024,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

@@ -435,6 +435,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;
@@ -835,7 +851,7 @@ export function createClient(options = {}) {
                 }
                 catch { /* not JSON: the status says what happened */ }
                 if (!response.ok || body.error) {
-                    throw new IsomorphError(body.error?.category ?? 'INTERNAL', body.error?.message ?? `the public action answered ${response.status}`, body.requestId, undefined, response.status);
+                    throw new IsomorphError(body.error?.category ?? 'INTERNAL', body.error?.message ?? `the public action answered ${response.status}`, body.requestId, body.error?.details, response.status);
                 }
                 return body.data;
             },

package/dist/integration-operations.d.ts

@@ -65,9 +65,9 @@ export declare const IntegrationOperations: {
     };
     readonly "gmail.message.send": {
         readonly kind: "saas";
-        readonly identities: readonly ["user"];
+        readonly identities: readonly ["user", "app"];
         readonly readOnly: false;
-        readonly declaredMode: false;
+        readonly declaredMode: true;
         readonly idempotencyKey: true;
     };
     readonly "gmail.attachment.read": {

package/dist/integration-operations.js

@@ -90,10 +90,11 @@ export const IntegrationOperations = {
     "gmail.message.send": {
         "kind": "saas",
         "identities": [
-            "user"
+            "user",
+            "app"
         ],
         "readOnly": false,
-        "declaredMode": false,
+        "declaredMode": true,
         "idempotencyKey": true
     },
     "gmail.attachment.read": {

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.1",
+  "version": "2.7.0",
   "type": "module",
   "repository": {
     "type": "git",