@isomorph.ai/app-sdk 1.8.0 → 1.10.0

package/README.md

@@ -200,3 +200,25 @@ export default async function approve(input: { id: string }, ctx: { user: { grou
 ```
 
 (1.6.0)
+
+## Live progress from an action
+
+An action reports steps with `ctx.progress(step)` (a string or a small JSON
+object); a page that passes `onProgress` gets each one as it happens, then the
+result or the error exactly as a plain `invoke` gives it. No table, no polling.
+
+```ts
+// actions/research.ts
+export default async function research(input: { url: string }, ctx: { progress(step: string): void }) {
+  ctx.progress(`Opened ${input.url}`);
+  // ...
+  return result;
+}
+
+// page
+await isomorph.actions.invoke('research', input, { onProgress: (step) => setSteps((steps) => [...steps, step]) });
+```
+
+Without `onProgress` the call is unchanged and `ctx.progress` does nothing. At
+most 256 steps of up to 1 KiB each reach the page; further steps are dropped.
+The action still has the 300 s action budget. (Unreleased)

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> {
@@ -441,7 +451,7 @@ declare class Transport {
     private readonly identity;
     renewal: IdentityRenewal | undefined;
     constructor(options: ClientOptions, onUnauthorized?: (() => void) | undefined);
-    json<T>(path: string, init?: RequestInit): Promise<T>;
+    json<T>(path: string, init?: RequestInit, onProgress?: (step: never) => void): Promise<T>;
     private request;
 }
 export declare class QueryBuilder<T = Record<string, unknown>, Result = T[]> implements PromiseLike<IsomorphResult<Result>> {
@@ -532,7 +542,10 @@ export declare function createClient(options?: ClientOptions): {
         channel: (name: string) => RealtimeChannelBuilder;
     };
     actions: {
-        invoke: <T = unknown>(name: string, input: unknown) => Promise<T>;
+        /** `onProgress` receives each `ctx.progress(step)` the action reports while it runs. */
+        invoke: <T = unknown, P = string>(name: string, input: unknown, options?: {
+            onProgress?: (step: P) => void;
+        }) => Promise<T>;
     };
     jobs: {
         enqueue: (name: string, input?: unknown) => Promise<{

package/dist/index.js

@@ -1,5 +1,6 @@
 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;
@@ -184,18 +185,21 @@ class Transport {
         this.fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
         this.identity = options.identity;
     }
-    json(path, init = {}) {
-        return this.request(path, init, renewableOnUnauthorized(path) || (this.separateApiHost && path === IDENTITY_PATH));
+    json(path, init = {}, onProgress) {
+        return this.request(path, init, renewableOnUnauthorized(path) || (this.separateApiHost && path === IDENTITY_PATH), onProgress);
     }
-    async request(path, init, renewOnUnauthorized) {
+    async request(path, init, renewOnUnauthorized, onProgress) {
         const sentAt = this.renewal?.renewals() ?? 0;
         // (headers with an undefined value are removed so a multipart body can
         // clear the JSON default and let the browser set its own boundary)
         const response = await this.fetch(`${this.baseUrl}${path}`, {
             credentials: 'same-origin',
             ...init,
-            headers: mergeHeaders({ 'content-type': 'application/json' }, runnerIdentityHeaders(this.identity), init.headers),
+            headers: mergeHeaders({ 'content-type': 'application/json' }, runnerIdentityHeaders(this.identity), init.headers, onProgress ? { accept: PROGRESS_MEDIA_TYPE } : undefined),
         });
+        if (onProgress && response.ok && response.body && response.headers.get('content-type')?.startsWith(PROGRESS_MEDIA_TYPE)) {
+            return readProgress(response, onProgress);
+        }
         const body = await response.json().catch(() => undefined);
         if (!response.ok) {
             if (response.status === 401) {
@@ -211,7 +215,7 @@ class Transport {
                     if (renewed && path === IDENTITY_PATH)
                         return renewed;
                     if (renewed !== false)
-                        return this.request(path, init, false);
+                        return this.request(path, init, false, onProgress);
                 }
                 // Not before the resend: a page listening to identity.onChange would
                 // otherwise see the user flicker to null while the edge was healing.
@@ -222,6 +226,44 @@ class Transport {
         return (body && Object.prototype.hasOwnProperty.call(body, 'data') ? body.data : body);
     }
 }
+// An action invoked with onProgress asks for its progress stream: one JSON
+// line per ctx.progress step, then the answer — `{data}` or `{error, status}`,
+// the refusal a plain call would have thrown. A runtime that does not stream
+// answers plain JSON and the call reads it as before.
+const PROGRESS_MEDIA_TYPE = 'application/x-ndjson';
+async function readProgress(response, onProgress) {
+    const requestId = response.headers.get('x-request-id') ?? undefined;
+    const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
+    let pending = '';
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            const lines = (pending + (value ?? '')).split('\n');
+            pending = done ? '' : lines.pop();
+            for (const line of lines.filter((text) => text.trim())) {
+                let event;
+                try {
+                    event = JSON.parse(line);
+                }
+                catch {
+                    throw new IsomorphError('INTERNAL', 'The action answered with an unreadable progress line.', requestId);
+                }
+                if ('progress' in event) {
+                    onProgress(event.progress);
+                    continue;
+                }
+                if (event.error)
+                    throw new IsomorphError(event.error.category ?? 'INTERNAL', event.error.message ?? 'The action failed.', requestId, event.error.details, event.status);
+                return event.data;
+            }
+            if (done)
+                throw new IsomorphError('UNAVAILABLE', 'The action stopped before it answered.', requestId);
+        }
+    }
+    finally {
+        void reader.cancel().catch(() => undefined);
+    }
+}
 function applicationBaseUrl() {
     if (typeof location === 'undefined') {
         // No browser: this module is running under the retained-check runner in
@@ -376,8 +418,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));
@@ -388,7 +431,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)
@@ -439,7 +482,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)
@@ -638,24 +681,24 @@ export function createClient(options = {}) {
             channel: (name) => new RealtimeChannelBuilder(name, connectRealtime),
         },
         actions: {
-            invoke: (name, input) => {
+            /** `onProgress` receives each `ctx.progress(step)` the action reports while it runs. */
+            invoke: (name, input, options = {}) => {
+                const path = `/_harbour/actions/${encodeURIComponent(name)}`;
                 // supabase-js accepts FormData/Blob bodies and sends them as
                 // multipart; JSON.stringify(FormData) silently becomes "{}", which
                 // turned a verbatim-ported multipart action into a guaranteed 500.
                 // Pass binary bodies through and let the browser set the boundary.
                 if (typeof FormData !== 'undefined' && input instanceof FormData) {
-                    return transport.json(`/_harbour/actions/${encodeURIComponent(name)}`, {
+                    return transport.json(path, {
                         method: 'POST', body: input, headers: { 'content-type': undefined },
-                    });
+                    }, options.onProgress);
                 }
                 if (typeof Blob !== 'undefined' && input instanceof Blob) {
-                    return transport.json(`/_harbour/actions/${encodeURIComponent(name)}`, {
+                    return transport.json(path, {
                         method: 'POST', body: input, headers: { 'content-type': input.type || 'application/octet-stream' },
-                    });
+                    }, options.onProgress);
                 }
-                return transport.json(`/_harbour/actions/${encodeURIComponent(name)}`, {
-                    method: 'POST', body: JSON.stringify(input),
-                });
+                return transport.json(path, { method: 'POST', body: JSON.stringify(input) }, options.onProgress);
             },
         },
         jobs: {

package/dist/runtime.d.ts

@@ -10,10 +10,16 @@ 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;
+    /**
+     * Reports a step to a page that invoked the action with `onProgress`; a
+     * no-op otherwise. A string or a small JSON object; after 256 steps, or a
+     * step over 1 KiB, further calls are dropped.
+     */
+    progress(step: string | Record<string, unknown>): void;
 }
 export interface JobContext {
     scheduledAt: string;

package/dist/runtime.js

@@ -57,6 +57,7 @@ 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';
 const actionIdentity = new AsyncLocalStorage();
 const identityKey = Symbol.for('isomorph.actionIdentity');
 globalThis[identityKey] = () => actionIdentity.getStore();
@@ -81,6 +82,12 @@ const DEFAULT_MAX_ATTEMPTS = 3;
 // waits this long for the gateway's data path, probing every retry interval.
 const DATA_PATH_WAIT_MS = 90_000;
 const DATA_PATH_RETRY_MS = 3_000;
+// An action's progress stream: asked for with this Accept, one JSON line per
+// ctx.progress call, then the answer as the last line. Bounded so a loop
+// cannot flood the page or crowd the result out of the gateway's 4 MiB cap.
+const PROGRESS_MEDIA_TYPE = 'application/x-ndjson';
+const MAX_PROGRESS_EVENTS = 256;
+const MAX_PROGRESS_LINE_BYTES = 1 << 10;
 /** Every `actions/<name>.ts` and `jobs/<name>.ts` the app carries, by logical name. */
 export async function discover(root) {
     const list = async (dir) => {
@@ -147,7 +154,14 @@ function loadHandler(root, dir, name) {
     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
+// carrying the status it would have had.
 function answer(response, status, body, requestId) {
+    if (response.headersSent) {
+        response.end(`${JSON.stringify(status >= 400 ? { ...body, status } : body)}\n`);
+        return;
+    }
     const encoded = JSON.stringify(body);
     response.writeHead(status, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(encoded), ...(requestId ? { 'x-request-id': requestId } : {}) });
     response.end(encoded);
@@ -432,6 +446,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 });
             this.log(`jobs/${name}.ts ran for ${at.toISOString()}`);
@@ -466,6 +481,7 @@ export class Runtime {
                 return true;
             }
             try {
+                await this.prepareAI();
                 const handler = await loadHandler(this.options.root, JOBS_DIR, run.job);
                 const result = await handler({
                     scheduledAt: now.toISOString(), runId: run.id, input: run.input,
@@ -500,8 +516,31 @@ 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;
+        const progress = (step) => {
+            if (!streams || steps >= MAX_PROGRESS_EVENTS || response.writableEnded)
+                return;
+            let encoded;
+            try {
+                encoded = JSON.stringify(step);
+            }
+            catch {
+                return;
+            }
+            if (encoded === undefined)
+                return;
+            const line = `{"progress":${encoded}}\n`;
+            if (Buffer.byteLength(line) > MAX_PROGRESS_LINE_BYTES)
+                return;
+            steps += 1;
+            if (!response.headersSent)
+                response.writeHead(200, { 'content-type': PROGRESS_MEDIA_TYPE, ...(requestId ? { 'x-request-id': requestId } : {}) });
+            response.write(line);
         };
-        const context = { signal: controller.signal, user, tenant, app, requestId: requestId ?? '' };
+        const context = { signal: controller.signal, user, tenant, app, requestId: requestId ?? '', progress };
         const raw = await readBody(request);
         if (raw === undefined)
             return refuse(response, 413, 'VALIDATION_FAILED', 'the request body is larger than 1 MiB', requestId);

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