@isomorph.ai/app-sdk 1.9.0 → 1.11.0

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { type IsomorphUserRole } from './user-role.js';
+export type { IsomorphUserRole } from './user-role.js';
 export type IsomorphErrorCategory = 'AUTH_REQUIRED' | 'FORBIDDEN' | 'NOT_FOUND' | 'CONFLICT' | 'VALIDATION_FAILED' | 'RATE_LIMITED' | 'UNAVAILABLE' | 'INTERNAL';
 export declare class IsomorphError extends Error {
     readonly category: IsomorphErrorCategory;
@@ -18,6 +20,14 @@ export interface IsomorphUser {
      * enforced before your code runs.
      */
     groups: string[];
+    /**
+     * What the person may do on the company's app platform: a `'builder'`
+     * builds and deploys apps, a `'member'` uses them. Show builders what only
+     * they need (a debug panel, a "deploy" hint); never gate data on it — that
+     * is a row rule's job, where `current_setting('harbour.user_role', true)`
+     * carries the same value.
+     */
+    role: IsomorphUserRole;
     appUser?: unknown;
 }
 export interface IsomorphResult<T> {

package/dist/index.js

@@ -1,5 +1,7 @@
+import { IntegrationOperations } from './integration-operations.js';
 import { validateIntegrationExecuteInput } from './integration-execute-input-rules.js';
 import { userGroups } from './user-groups.js';
+import { userRole } from './user-role.js';
 export class IsomorphError extends Error {
     category;
     requestId;
@@ -28,13 +30,6 @@ function warehouseReadProblem({ columns, aggregates }) {
         return { field: 'columns', message: 'columns may use "*" only as the sole entry' };
     return undefined;
 }
-// The operations whose request carries a `mode`, and the only ones it is sent
-// for (every other operation's mode is fixed, and the platform refuses the
-// field there). The key type is derived from the union, so adding or removing
-// `mode` on a request without changing this table does not compile.
-const declaredModeOperations = {
-    'slack.channel.history': true, 'slack.message.post': true, 'slack.message.update': true, 'slack.message.delete': true,
-};
 /** The AI reason code carried by an error, when it is a governed-AI refusal. */
 export function aiErrorCode(error) {
     const code = error instanceof IsomorphError ? error.details?.code : undefined;
@@ -417,8 +412,9 @@ export function createClient(options = {}) {
     };
     // The gateway's answer becomes an IsomorphUser in place: the same object
     // must reach every caller (the API-host refresh below relies on it).
-    const withGroups = (user) => {
+    const normalizeUser = (user) => {
         user.groups = userGroups(user.groups);
+        user.role = userRole(user.role);
         return user;
     };
     const transport = new Transport(options, () => notifyIdentity(null));
@@ -429,7 +425,7 @@ export function createClient(options = {}) {
         refreshesStarted += 1;
         refreshInFlight = transport.json(IDENTITY_PATH)
             .then((answer) => {
-            const user = answer === null ? null : withGroups(answer);
+            const user = answer === null ? null : normalizeUser(answer);
             // A user answered by the API host's context refresh was announced by
             // that refresh already (it is the same object): once is enough.
             if (user === null || user !== currentUser)
@@ -480,7 +476,7 @@ export function createClient(options = {}) {
                 const user = (await response.json())?.data;
                 if (typeof user?.id !== 'string')
                     return false;
-                notifyIdentity(withGroups(user), true);
+                notifyIdentity(normalizeUser(user), true);
                 return user;
             })
                 .catch(() => false)
@@ -724,11 +720,11 @@ export function createClient(options = {}) {
                 if (problem) {
                     return Promise.reject(new IsomorphError('VALIDATION_FAILED', problem.message, undefined, { code: 'INPUT_INVALID', field: problem.field }));
                 }
-                // Exactly the contract's fields go on the wire: `mode` only for the
-                // declaredModeOperations; an `identity` or any other stray field is not sent.
+                // Exactly the contract's fields go on the wire: metadata declares which
+                // operations accept `mode`; identity and stray fields are not sent.
                 const { operation, resource, input, idempotencyKey, mode } = request;
                 return transport.json('/_harbour/integrations/execute', {
-                    method: 'POST', body: JSON.stringify({ connection, operation, resource, ...(input !== undefined ? { input } : {}), ...(idempotencyKey !== undefined ? { idempotencyKey } : {}), ...(operation in declaredModeOperations && mode !== undefined ? { mode } : {}) }),
+                    method: 'POST', body: JSON.stringify({ connection, operation, resource, ...(input !== undefined ? { input } : {}), ...(idempotencyKey !== undefined ? { idempotencyKey } : {}), ...(IntegrationOperations[operation]?.declaredMode && mode !== undefined ? { mode } : {}) }),
                 });
             },
             // In a browser the consent returns the person to this page (without its

package/dist/integration-operations.d.ts

@@ -0,0 +1,87 @@
+/** Declaration and execute metadata from the contract schemas. */
+export declare const IntegrationOperations: {
+    readonly "slack.channel.history": {
+        readonly kind: "saas";
+        readonly identities: readonly ["user", "app"];
+        readonly readOnly: true;
+        readonly declaredMode: true;
+        readonly idempotencyKey: false;
+    };
+    readonly "slack.message.post": {
+        readonly kind: "saas";
+        readonly identities: readonly ["app", "user"];
+        readonly readOnly: false;
+        readonly declaredMode: true;
+        readonly idempotencyKey: true;
+    };
+    readonly "slack.message.update": {
+        readonly kind: "saas";
+        readonly identities: readonly ["app", "user"];
+        readonly readOnly: false;
+        readonly declaredMode: true;
+        readonly idempotencyKey: false;
+    };
+    readonly "slack.message.delete": {
+        readonly kind: "saas";
+        readonly identities: readonly ["app", "user"];
+        readonly readOnly: false;
+        readonly declaredMode: true;
+        readonly idempotencyKey: false;
+    };
+    readonly "slack.dm.send": {
+        readonly kind: "saas";
+        readonly identities: readonly ["app"];
+        readonly readOnly: false;
+        readonly declaredMode: false;
+        readonly idempotencyKey: true;
+    };
+    readonly "slack.user.lookup": {
+        readonly kind: "saas";
+        readonly identities: readonly ["app"];
+        readonly readOnly: true;
+        readonly declaredMode: false;
+        readonly idempotencyKey: false;
+    };
+    readonly "gmail.thread.list": {
+        readonly kind: "saas";
+        readonly identities: readonly ["user"];
+        readonly readOnly: true;
+        readonly declaredMode: false;
+        readonly idempotencyKey: false;
+    };
+    readonly "gmail.thread.read": {
+        readonly kind: "saas";
+        readonly identities: readonly ["user"];
+        readonly readOnly: true;
+        readonly declaredMode: false;
+        readonly idempotencyKey: false;
+    };
+    readonly "gmail.message.read": {
+        readonly kind: "saas";
+        readonly identities: readonly ["user"];
+        readonly readOnly: true;
+        readonly declaredMode: false;
+        readonly idempotencyKey: false;
+    };
+    readonly "gmail.message.send": {
+        readonly kind: "saas";
+        readonly identities: readonly ["user"];
+        readonly readOnly: false;
+        readonly declaredMode: false;
+        readonly idempotencyKey: true;
+    };
+    readonly "gmail.attachment.read": {
+        readonly kind: "saas";
+        readonly identities: readonly ["user"];
+        readonly readOnly: true;
+        readonly declaredMode: false;
+        readonly idempotencyKey: false;
+    };
+    readonly "warehouse.view.read": {
+        readonly kind: "database";
+        readonly identities: readonly ["app"];
+        readonly readOnly: true;
+        readonly declaredMode: false;
+        readonly idempotencyKey: false;
+    };
+};

package/dist/integration-operations.js

@@ -0,0 +1,117 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+/** Declaration and execute metadata from the contract schemas. */
+export const IntegrationOperations = {
+    "slack.channel.history": {
+        "kind": "saas",
+        "identities": [
+            "user",
+            "app"
+        ],
+        "readOnly": true,
+        "declaredMode": true,
+        "idempotencyKey": false
+    },
+    "slack.message.post": {
+        "kind": "saas",
+        "identities": [
+            "app",
+            "user"
+        ],
+        "readOnly": false,
+        "declaredMode": true,
+        "idempotencyKey": true
+    },
+    "slack.message.update": {
+        "kind": "saas",
+        "identities": [
+            "app",
+            "user"
+        ],
+        "readOnly": false,
+        "declaredMode": true,
+        "idempotencyKey": false
+    },
+    "slack.message.delete": {
+        "kind": "saas",
+        "identities": [
+            "app",
+            "user"
+        ],
+        "readOnly": false,
+        "declaredMode": true,
+        "idempotencyKey": false
+    },
+    "slack.dm.send": {
+        "kind": "saas",
+        "identities": [
+            "app"
+        ],
+        "readOnly": false,
+        "declaredMode": false,
+        "idempotencyKey": true
+    },
+    "slack.user.lookup": {
+        "kind": "saas",
+        "identities": [
+            "app"
+        ],
+        "readOnly": true,
+        "declaredMode": false,
+        "idempotencyKey": false
+    },
+    "gmail.thread.list": {
+        "kind": "saas",
+        "identities": [
+            "user"
+        ],
+        "readOnly": true,
+        "declaredMode": false,
+        "idempotencyKey": false
+    },
+    "gmail.thread.read": {
+        "kind": "saas",
+        "identities": [
+            "user"
+        ],
+        "readOnly": true,
+        "declaredMode": false,
+        "idempotencyKey": false
+    },
+    "gmail.message.read": {
+        "kind": "saas",
+        "identities": [
+            "user"
+        ],
+        "readOnly": true,
+        "declaredMode": false,
+        "idempotencyKey": false
+    },
+    "gmail.message.send": {
+        "kind": "saas",
+        "identities": [
+            "user"
+        ],
+        "readOnly": false,
+        "declaredMode": false,
+        "idempotencyKey": true
+    },
+    "gmail.attachment.read": {
+        "kind": "saas",
+        "identities": [
+            "user"
+        ],
+        "readOnly": true,
+        "declaredMode": false,
+        "idempotencyKey": false
+    },
+    "warehouse.view.read": {
+        "kind": "database",
+        "identities": [
+            "app"
+        ],
+        "readOnly": true,
+        "declaredMode": false,
+        "idempotencyKey": false
+    }
+};

package/dist/jobs-cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/jobs-cli.js

@@ -0,0 +1,11 @@
+// Read-only native gate adapter. No app modules or runtime server are started.
+import { discoverJobs } from './jobs.js';
+try {
+    if (process.argv[2] !== 'discover' || !process.argv[3])
+        throw new Error('usage: jobs-cli.js discover <app-root>');
+    process.stdout.write(JSON.stringify(await discoverJobs(process.argv[3])) + '\n');
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}

package/dist/jobs.d.ts

@@ -0,0 +1,17 @@
+export declare const JOBS_DIR = "jobs";
+export interface JobDefinition {
+    name: string;
+    schedule?: string;
+}
+export interface JobContext {
+    scheduledAt: string;
+    runId?: string;
+    input?: unknown;
+    progress(percent: number, note?: string): Promise<void>;
+    cancelled(): Promise<boolean>;
+}
+export declare function discoverJobs(root: string): Promise<JobDefinition[]>;
+type Handler = (...args: unknown[]) => unknown;
+export declare function loadHandler(root: string, dir: string, name: string): Promise<Handler>;
+export declare function invokeJob(root: string, name: string, context: JobContext): Promise<unknown>;
+export {};

package/dist/jobs.js

@@ -0,0 +1,98 @@
+// Node-only: shared by runtime, local CLI and the native gate. Discovery never imports app code.
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { stripTypeScriptTypes } from 'node:module';
+import { parse } from 'acorn';
+export const JOBS_DIR = 'jobs';
+const LOGICAL_NAME = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+function bindsSchedule(binding) {
+    switch (binding.type) {
+        case 'Identifier': return binding.name === 'schedule';
+        case 'ObjectPattern': return binding.properties.some(property => bindsSchedule(property.type === 'RestElement' ? property.argument : property.value));
+        case 'ArrayPattern': return binding.elements.some(element => element !== null && bindsSchedule(element));
+        case 'AssignmentPattern': return bindsSchedule(binding.left);
+        case 'RestElement': return bindsSchedule(binding.argument);
+        default: return false;
+    }
+}
+export async function discoverJobs(root) {
+    const directory = join(root, JOBS_DIR);
+    const entries = await readdir(directory, { withFileTypes: true }).catch((error) => {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    });
+    const jobs = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.ts'))
+            continue;
+        const name = entry.name.slice(0, -3);
+        const fail = (message) => { throw new Error(`jobs/${entry.name}: ${message}`); };
+        if (!LOGICAL_NAME.test(name))
+            fail('the file name must be a lowercase logical name.');
+        const source = await readFile(join(directory, entry.name), 'utf8');
+        let statements;
+        try {
+            statements = parse(stripTypeScriptTypes(source), { ecmaVersion: 'latest', sourceType: 'module' }).body;
+        }
+        catch (error) {
+            fail(`cannot parse the job module: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        let schedule;
+        for (const statement of statements) {
+            if (statement.type === 'ExportAllDeclaration' && statement.exported && (statement.exported.type === 'Identifier' ? statement.exported.name : statement.exported.value) === 'schedule')
+                fail('export one literal schedule directly with export const schedule.');
+            if (statement.type !== 'ExportNamedDeclaration')
+                continue;
+            if (statement.specifiers.some(specifier => specifier.exported.type === 'Identifier' ? specifier.exported.name === 'schedule' : specifier.exported.value === 'schedule'))
+                fail('export one literal schedule directly with export const schedule.');
+            if (statement.declaration?.type !== 'VariableDeclaration') {
+                if (statement.declaration?.id?.name === 'schedule')
+                    fail('export one literal schedule directly with export const schedule.');
+                continue;
+            }
+            for (const declaration of statement.declaration.declarations) {
+                if (!bindsSchedule(declaration.id))
+                    continue;
+                if (declaration.id.type !== 'Identifier')
+                    fail('export one literal schedule directly with export const schedule.');
+                const value = declaration.init;
+                if (statement.declaration.kind !== 'const')
+                    fail('export one literal schedule.');
+                if (value?.type === 'Literal' && typeof value.value === 'string')
+                    schedule = value.value.trim();
+                else if (value?.type === 'TemplateLiteral' && value.expressions.length === 0)
+                    schedule = value.quasis[0].value.cooked?.trim();
+                else
+                    fail('export one literal schedule, for example export const schedule = "0 9 * * 1-5".');
+                if (!schedule)
+                    fail('export one non-empty literal schedule.');
+            }
+        }
+        if (!statements.some(statement => statement.type === 'ExportDefaultDeclaration'))
+            fail('export one default job handler.');
+        jobs.push({ name, ...(schedule ? { schedule } : {}) });
+    }
+    return jobs.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+}
+const modules = new Map();
+export function loadHandler(root, dir, name) {
+    const key = pathToFileURL(join(root, dir, `${name}.ts`)).href;
+    let loading = modules.get(key);
+    if (!loading) {
+        loading = import(key).then((module) => {
+            if (typeof module.default !== 'function')
+                throw new Error(`${dir}/${name}.ts has no default handler`);
+            return module.default;
+        });
+        loading.catch(() => modules.delete(key));
+        modules.set(key, loading);
+    }
+    return loading;
+}
+export async function invokeJob(root, name, context) {
+    if (!LOGICAL_NAME.test(name))
+        throw new Error('A valid job name is required.');
+    return (await loadHandler(root, JOBS_DIR, name))(context);
+}

package/dist/runtime.d.ts

@@ -1,7 +1,8 @@
 import { type IncomingMessage, type ServerResponse } from 'node:http';
 import { type IsomorphClient, type IsomorphUser, type JobRun } from './index.js';
+import { type JobDefinition } from './jobs.js';
+export { JOBS_DIR, type JobContext } from './jobs.js';
 export declare const ACTIONS_DIR = "actions";
-export declare const JOBS_DIR = "jobs";
 export declare const RUNS_TABLE = "isomorph_job_runs";
 export declare const RESERVED_PREFIX = "isomorph-";
 export declare const PING_ACTION = "isomorph-ping";
@@ -10,7 +11,7 @@ export declare const GET_RUN_ACTION = "isomorph-jobs-get";
 export declare const CANCEL_RUN_ACTION = "isomorph-jobs-cancel";
 export interface ActionContext {
     signal: AbortSignal;
-    user: Pick<IsomorphUser, 'id' | 'email' | 'groups'>;
+    user: Pick<IsomorphUser, 'id' | 'email' | 'groups' | 'role'>;
     tenant: string;
     app: string;
     requestId: string;
@@ -21,19 +22,9 @@ export interface ActionContext {
      */
     progress(step: string | Record<string, unknown>): void;
 }
-export interface JobContext {
-    scheduledAt: string;
-    runId?: string;
-    input?: unknown;
-    progress(percent: number, note?: string): Promise<void>;
-    cancelled(): Promise<boolean>;
-}
 export interface RuntimeInventory {
     actions: string[];
-    jobs: {
-        name: string;
-        schedule?: string;
-    }[];
+    jobs: JobDefinition[];
 }
 /** Every `actions/<name>.ts` and `jobs/<name>.ts` the app carries, by logical name. */
 export declare function discover(root: string): Promise<RuntimeInventory>;

package/dist/runtime.js

@@ -57,11 +57,13 @@ import { join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { createClient, IsomorphError } from './index.js';
 import { userGroupsFromHeader } from './user-groups.js';
+import { userRole } from './user-role.js';
+import { discoverJobs, invokeJob, loadHandler, JOBS_DIR } from './jobs.js';
+export { JOBS_DIR } from './jobs.js';
 const actionIdentity = new AsyncLocalStorage();
 const identityKey = Symbol.for('isomorph.actionIdentity');
 globalThis[identityKey] = () => actionIdentity.getStore();
 export const ACTIONS_DIR = 'actions';
-export const JOBS_DIR = 'jobs';
 export const RUNS_TABLE = 'isomorph_job_runs';
 export const RESERVED_PREFIX = 'isomorph-';
 export const PING_ACTION = 'isomorph-ping';
@@ -69,9 +71,6 @@ export const ENQUEUE_ACTION = 'isomorph-jobs-enqueue';
 export const GET_RUN_ACTION = 'isomorph-jobs-get';
 export const CANCEL_RUN_ACTION = 'isomorph-jobs-cancel';
 const LOGICAL_NAME = /^[a-z0-9][a-z0-9_-]{0,63}$/;
-// \x60 is the backtick: the brand guard counts template literals by
-// backticks, and a bare one inside this regex unbalanced its scan.
-const SCHEDULE_DECLARATION = /^export\s+const\s+schedule\s*=\s*["'\x60]([^"'\x60\n]+)["'\x60]/m;
 const MAX_BODY_BYTES = 1 << 20;
 const LEASE_MS = 5 * 60_000;
 const QUEUE_POLL_MS = 2_000;
@@ -94,12 +93,7 @@ export async function discover(root) {
         return entries.filter((entry) => entry.isFile() && entry.name.endsWith('.ts')).map((entry) => entry.name.slice(0, -3)).filter((name) => LOGICAL_NAME.test(name)).sort();
     };
     const actions = (await list(ACTIONS_DIR)).filter((name) => !name.startsWith(RESERVED_PREFIX));
-    const jobs = [];
-    for (const name of await list(JOBS_DIR)) {
-        const body = await readFile(join(root, JOBS_DIR, `${name}.ts`), 'utf8');
-        const match = SCHEDULE_DECLARATION.exec(body);
-        jobs.push(match ? { name, schedule: match[1].trim() } : { name });
-    }
+    const jobs = await discoverJobs(root);
     return { actions, jobs };
 }
 // ---- Cron ------------------------------------------------------------------
@@ -137,21 +131,6 @@ export function cronMatches(expression, at) {
         && fieldMatches(month, at.getUTCMonth() + 1, 1, 12)
         && (fieldMatches(weekday, at.getUTCDay(), 0, 7) || (sunday && fieldMatches(weekday, 7, 0, 7)));
 }
-const modules = new Map();
-function loadHandler(root, dir, name) {
-    const key = `${dir}/${name}`;
-    let loading = modules.get(key);
-    if (!loading) {
-        loading = import(pathToFileURL(join(root, dir, `${name}.ts`)).href).then((module) => {
-            if (typeof module.default !== 'function')
-                throw new Error(`${key}.ts has no default handler`);
-            return module.default;
-        });
-        loading.catch(() => modules.delete(key));
-        modules.set(key, loading);
-    }
-    return loading;
-}
 // ---- HTTP helpers ------------------------------------------------------------
 // Once an action has streamed progress the status line is gone, so its
 // answer — result or refusal — is the stream's last line, the refusal
@@ -446,8 +425,7 @@ export class Runtime {
         this.running.add(key);
         try {
             await this.prepareAI();
-            const handler = await loadHandler(this.options.root, JOBS_DIR, name);
-            await handler({ scheduledAt: at.toISOString(), progress: async () => undefined, cancelled: async () => false });
+            await invokeJob(this.options.root, name, { scheduledAt: at.toISOString(), progress: async () => undefined, cancelled: async () => false });
             this.log(`jobs/${name}.ts ran for ${at.toISOString()}`);
             return true;
         }
@@ -481,8 +459,7 @@ export class Runtime {
             }
             try {
                 await this.prepareAI();
-                const handler = await loadHandler(this.options.root, JOBS_DIR, run.job);
-                const result = await handler({
+                const result = await invokeJob(this.options.root, run.job, {
                     scheduledAt: now.toISOString(), runId: run.id, input: run.input,
                     progress: (percent, note) => this.runs.progress(run.id, percent, note),
                     cancelled: () => this.runs.cancelRequested(run.id),
@@ -515,6 +492,7 @@ export class Runtime {
             id: header(request, 'X-Harbour-Verified-User-ID'),
             email: header(request, 'X-Harbour-Verified-User-Email'),
             groups: userGroupsFromHeader(header(request, 'X-Harbour-Verified-User-Groups')),
+            role: userRole(header(request, 'X-Harbour-Verified-User-Role')),
         };
         const streams = header(request, 'accept').toLowerCase().includes(PROGRESS_MEDIA_TYPE);
         let steps = 0;

package/dist/user-role.d.ts

@@ -0,0 +1,2 @@
+export type IsomorphUserRole = 'builder' | 'member';
+export declare function userRole(value: unknown): IsomorphUserRole;

package/dist/user-role.js

@@ -0,0 +1,3 @@
+export function userRole(value) {
+    return value === 'builder' ? 'builder' : 'member';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isomorph.ai/app-sdk",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -36,5 +36,8 @@
     "playwright-core": {
       "optional": true
     }
+  },
+  "dependencies": {
+    "acorn": "8.18.0"
   }
 }