@isomorph.ai/app-sdk 1.27.0 → 1.29.0

package/README.md

@@ -482,3 +482,32 @@ On a serverless cell Harbour runs an app's server code as Lambda functions, from
 `ISOMORPH_JOBS_QUEUE_URL`: `isomorph.jobs.enqueue` writes the run, then sends one message to this SQS queue; the runtime never works the queue itself.
 
 (1.24.0; data plane ADR 0065)
+
+### Email-arrival jobs
+
+On managed serverless hosting, an ordinary job can declare an inbox trigger instead of a schedule:
+
+```ts
+export const trigger = {
+  type: 'email.arrived',
+  connection: 'company-gmail',
+  resource: 'inbox',
+  filter: { subjectContains: 'Invoice' },
+};
+export default async (ctx) => {
+  // ctx.input: provider, sourceId, messageId, threadId, receivedAt.
+  // Read the message/attachments through the declared integration operations.
+  // Persist business progress in the app's own workflow records.
+};
+```
+
+`connection` names the configured Gmail or Outlook connection. A literal `filter.from`
+may additionally require an exact sender. Deployment registers the job; activation requires
+the app owner's approved read access and background consent for that environment.
+Multiple apps share one provider watch per mailbox. Notifications enqueue the existing durable
+job runtime; duplicate deliveries retain the same run instead of rerunning a completed job.
+This does not add a per-app polling timer. Cluster hosting and cross-account delivery are not
+supported by this first release. Local manual job execution tests the handler, not the provider
+subscription; verify a real incoming email after deployment before calling the trigger live.
+
+For PO-linked Zoho bills, first read the PO and send each returned `lineItemId` as the bill line’s `purchaseOrderItemId`. `itemId` identifies the catalog item; it does not identify the PO line. Purchase-order list results are summaries; read the document before comparing lines.

package/dist/index.d.ts

@@ -1100,6 +1100,9 @@ export interface BooksLineInput {
     taxId?: string;
     description?: string;
 }
+export interface BooksBillLineInput extends BooksLineInput {
+    purchaseOrderItemId?: string;
+}
 export interface BooksDocument {
     id: string;
     number: string;
@@ -1110,6 +1113,8 @@ export interface BooksDocument {
     customerId?: string;
     lineItems: {
         itemId: string;
+        lineItemId?: string;
+        purchaseOrderItemId?: string;
         quantity: string;
         rate: string;
         total: string;
@@ -1151,7 +1156,7 @@ export type ZohoBooksRequest = {
         documentNumber: string;
         documentDate: string;
         purchaseOrderId?: string;
-        lineItems: BooksLineInput[];
+        lineItems: BooksBillLineInput[];
     };
 } | {
     operation: 'zohobooks.invoice.create';

package/dist/integration-execute-input-rules.d.ts

@@ -2268,6 +2268,13 @@ export declare const IntegrationExecuteInputRules: {
                         readonly minLength: 0;
                         readonly maxLength: 2000;
                     };
+                    readonly purchaseOrderItemId: {
+                        readonly kind: "string";
+                        readonly required: false;
+                        readonly minLength: 0;
+                        readonly maxLength: 32;
+                        readonly pattern: "^[0-9]{1,32}$";
+                    };
                 };
             };
         };

package/dist/integration-execute-input-rules.js

@@ -701,6 +701,7 @@ export const IntegrationExecuteInputRules = {
                     rate: { kind: "string", required: true, minLength: 0, maxLength: 17, pattern: "^[0-9]{1,10}(\\.[0-9]{1,6})?$" },
                     taxId: { kind: "string", required: false, minLength: 0, maxLength: 32, pattern: "^[0-9]{1,32}$" },
                     description: { kind: "string", required: false, minLength: 0, maxLength: 2000 },
+                    purchaseOrderItemId: { kind: "string", required: false, minLength: 0, maxLength: 32, pattern: "^[0-9]{1,32}$" },
                 } },
         },
     },

package/dist/jobs.d.ts

@@ -1,8 +1,19 @@
 export declare const JOBS_DIR = "jobs";
+export interface EmailArrivalTrigger {
+    type: 'email.arrived';
+    connection: string;
+    resource: 'inbox';
+    filter?: {
+        from?: string;
+        subjectContains?: string;
+    };
+}
 export interface JobDefinition {
     name: string;
     schedule?: string;
+    trigger?: EmailArrivalTrigger;
 }
+export declare function emailArrivalTrigger(value: unknown): EmailArrivalTrigger;
 export interface JobContext {
     scheduledAt: string;
     runId?: string;

package/dist/jobs.js

@@ -6,13 +6,40 @@ 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) {
+function literalObject(node) {
+    const value = node;
+    if (value?.type === 'Literal')
+        return value.value;
+    if (value?.type !== 'ObjectExpression')
+        throw new Error('trigger must be a literal object');
+    const result = {};
+    for (const property of value.properties ?? []) {
+        if (property.type !== 'Property' || property.computed || property.kind !== 'init' || property.method)
+            throw new Error('trigger must be a literal object');
+        const key = property.key.name ?? property.key.value;
+        if (typeof key !== 'string' || Object.hasOwn(result, key))
+            throw new Error('trigger contains an invalid or repeated field');
+        Object.defineProperty(result, key, { value: literalObject(property.value), enumerable: true });
+    }
+    return result;
+}
+export function emailArrivalTrigger(value) {
+    const trigger = value;
+    if (!trigger || typeof trigger !== 'object' || Object.keys(trigger).some(key => !['type', 'connection', 'resource', 'filter'].includes(key))
+        || trigger.type !== 'email.arrived' || trigger.resource !== 'inbox' || typeof trigger.connection !== 'string' || !LOGICAL_NAME.test(trigger.connection))
+        throw new Error('trigger must declare email.arrived, a connection and resource inbox');
+    if (trigger.filter !== undefined && (!trigger.filter || typeof trigger.filter !== 'object' || Array.isArray(trigger.filter)
+        || Object.entries(trigger.filter).some(([key, value]) => !['from', 'subjectContains'].includes(key) || typeof value !== 'string' || !value.trim() || value.length > 320)))
+        throw new Error('trigger filter supports non-empty from and subjectContains strings up to 320 characters');
+    return trigger;
+}
+function bindsJobSetup(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);
+        case 'Identifier': return binding.name === 'schedule' || binding.name === 'trigger';
+        case 'ObjectPattern': return binding.properties.some(property => bindsJobSetup(property.type === 'RestElement' ? property.argument : property.value));
+        case 'ArrayPattern': return binding.elements.some(element => element !== null && bindsJobSetup(element));
+        case 'AssignmentPattern': return bindsJobSetup(binding.left);
+        case 'RestElement': return bindsJobSetup(binding.argument);
         default: return false;
     }
 }
@@ -57,23 +84,35 @@ export async function discoverJobs(root) {
             fail(`cannot parse the job module: ${error instanceof Error ? error.message : String(error)}`);
         }
         let schedule;
+        let trigger;
         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 === 'ExportAllDeclaration' && statement.exported && ['schedule', 'trigger'].includes(statement.exported.type === 'Identifier' ? statement.exported.name : String(statement.exported.value)))
+                fail('export one literal schedule or trigger directly with export const.');
             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.specifiers.some(specifier => ['schedule', 'trigger'].includes(specifier.exported.type === 'Identifier' ? specifier.exported.name : String(specifier.exported.value))))
+                fail('export one literal schedule or trigger directly with export const.');
             if (statement.declaration?.type !== 'VariableDeclaration') {
-                if (statement.declaration?.id?.name === 'schedule')
-                    fail('export one literal schedule directly with export const schedule.');
+                if (['schedule', 'trigger'].includes(statement.declaration?.id?.name ?? ''))
+                    fail('export one literal schedule or trigger directly with export const.');
                 continue;
             }
             for (const declaration of statement.declaration.declarations) {
-                if (!bindsSchedule(declaration.id))
+                if (declaration.id.type === 'Identifier' && declaration.id.name === 'trigger') {
+                    if (statement.declaration.kind !== 'const')
+                        fail('export one literal trigger with export const trigger.');
+                    try {
+                        trigger = emailArrivalTrigger(literalObject(declaration.init));
+                    }
+                    catch (error) {
+                        fail(String(error));
+                    }
+                    continue;
+                }
+                if (!bindsJobSetup(declaration.id))
                     continue;
                 if (declaration.id.type !== 'Identifier')
-                    fail('export one literal schedule directly with export const schedule.');
+                    fail('export one literal schedule or trigger directly with export const.');
                 const value = declaration.init;
                 if (statement.declaration.kind !== 'const')
                     fail('export one literal schedule.');
@@ -89,7 +128,9 @@ export async function discoverJobs(root) {
         }
         if (!statements.some(statement => statement.type === 'ExportDefaultDeclaration'))
             fail('export one default job handler.');
-        jobs.push({ name, ...(schedule ? { schedule } : {}) });
+        if (schedule && trigger)
+            fail('a job may declare a schedule or an email trigger, not both.');
+        jobs.push({ name, ...(schedule ? { schedule } : {}), ...(trigger ? { trigger } : {}) });
     }
     return jobs.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
 }

package/dist/lambda-events-entry.js

@@ -18,7 +18,9 @@ function eventRuntime() {
     return runtime;
 }
 export async function handler(event) {
-    const { job, Records: records } = (event && typeof event === 'object' ? event : {});
+    const { job, Records: records, mailArrival } = (event && typeof event === 'object' ? event : {});
+    if (mailArrival !== undefined)
+        return eventRuntime().acceptMailArrival(mailArrival);
     if (typeof job === 'string' && job) {
         if (!(await eventRuntime().runJobOnce(job)))
             throw new Error(`jobs/${job}.ts did not run to completion; the log above names why`);

package/dist/runtime.d.ts

@@ -50,6 +50,14 @@ export declare class Runs {
     enqueue(job: string, input: unknown, owner: string): Promise<{
         id: string;
     }>;
+    enqueueMail(delivery: {
+        deliveryId: string;
+        job: string;
+        input: unknown;
+        owner: string;
+    }): Promise<{
+        id: string;
+    }>;
     get(id: string, owner: string): Promise<JobRun | null>;
     cancel(id: string, owner: string): Promise<JobRun | null>;
     /** Rows whose lease ran out go back to the queue while attempts remain, else fail; how many there were. */
@@ -133,6 +141,7 @@ export declare class Runtime {
      * would have been. False when the app has no such job, the gateway's data
      * path never answered, or the handler threw; the log names which.
      */
+    acceptMailArrival(value: unknown): Promise<void>;
     runJobOnce(name: string, now?: Date): Promise<boolean>;
     private awaitDataPath;
     stop(): Promise<void>;
@@ -152,6 +161,7 @@ export declare class Runtime {
     private serve;
     private transaction;
     private loadFailures;
+    private signalQueuedRun;
     private reserved;
 }
 /** The runtime's settings from the environment; exported for the entry point and its test. */

package/dist/runtime.js

@@ -56,6 +56,7 @@
 //   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)
+import { createHash } from 'node:crypto';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { createServer } from 'node:http';
 import { readFile, readdir, stat } from 'node:fs/promises';
@@ -203,6 +204,19 @@ export class Runs {
         const { data } = await this.table().insert({ job, input: input ?? null, status: 'queued', attempt: 0, max_attempts: DEFAULT_MAX_ATTEMPTS, progress: 0, owner_subject: owner, cancel_requested: false }).select('id').single();
         return { id: data.id };
     }
+    async enqueueMail(delivery) {
+        const hex = createHash('sha256').update(`mail:${delivery.deliveryId}`).digest('hex');
+        const id = `${hex.slice(0, 8)}-${hex.slice(8, 12)}-5${hex.slice(13, 16)}-a${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+        try {
+            await this.table().insert({ id, job: delivery.job, input: delivery.input, status: 'queued', attempt: 0, max_attempts: DEFAULT_MAX_ATTEMPTS, progress: 0, owner_subject: delivery.owner, cancel_requested: false });
+        }
+        catch (error) {
+            const existing = await this.get(id, delivery.owner);
+            if (!existing || existing.job !== delivery.job)
+                throw error;
+        }
+        return { id };
+    }
     async get(id, owner) {
         const { data } = await this.table().select('*').eq('id', id).eq('owner_subject', owner).maybeSingle();
         return data;
@@ -370,6 +384,25 @@ export class Runtime {
      * would have been. False when the app has no such job, the gateway's data
      * path never answered, or the handler threw; the log names which.
      */
+    async acceptMailArrival(value) {
+        const delivery = value;
+        if (!delivery || typeof delivery.deliveryId !== 'string' || !/^[a-f0-9]{64}$/.test(delivery.deliveryId)
+            || typeof delivery.owner !== 'string' || !delivery.owner || delivery.owner.length > 320
+            || !delivery.input || !['gmail', 'outlook'].includes(delivery.input.provider)
+            || typeof delivery.input.messageId !== 'string' || !delivery.input.messageId || delivery.input.messageId.length > 2048
+            || typeof delivery.input.threadId !== 'string' || delivery.input.threadId.length > 2048
+            || typeof delivery.input.receivedAt !== 'string' || !Number.isFinite(Date.parse(delivery.input.receivedAt)))
+            throw new Error('invalid mail arrival');
+        this.inventory = await discover(this.options.root);
+        const job = this.inventory.jobs.find(job => job.name === delivery.job);
+        if (!job?.trigger || job.trigger.connection !== delivery.input.sourceId)
+            throw new Error('mail trigger is not declared by this deployed app');
+        await this.refreshToken(JOB_SESSION_MIN_VALIDITY_MS);
+        if (!this.options.gatewayUrl || !this.options.queueUrl || this.options.jobRuns === false || !(await this.awaitDataPath()))
+            throw new Error('mail arrival requires durable job runs');
+        const queued = await this.runs.enqueueMail(delivery);
+        await this.signalQueuedRun(queued.id);
+    }
     async runJobOnce(name, now = new Date()) {
         this.inventory = await discover(this.options.root);
         await this.refreshToken(JOB_SESSION_MIN_VALIDITY_MS);
@@ -674,6 +707,14 @@ export class Runtime {
         }
         return failures;
     }
+    async signalQueuedRun(id) {
+        if (this.options.queueUrl) {
+            const { awsEnvironment, sendQueueMessage } = await import('./aws.js');
+            await sendQueueMessage(awsEnvironment(), this.options.queueUrl, JSON.stringify({ runId: id }));
+        }
+        else
+            this.wakeQueue();
+    }
     async reserved(name, input, context) {
         const body = (input && typeof input === 'object' ? input : {});
         const owner = context.user.id;
@@ -690,12 +731,7 @@ export class Runtime {
                     throw new IsomorphError('AUTH_REQUIRED', 'a run is started by a signed-in person', undefined, undefined, 401);
                 const queued = await this.runs.enqueue(job, body.input, owner);
                 // Awaited before the enqueue answers: a Web Function may be frozen as soon as it has replied.
-                if (this.options.queueUrl) {
-                    const { awsEnvironment, sendQueueMessage } = await import('./aws.js');
-                    await sendQueueMessage(awsEnvironment(), this.options.queueUrl, JSON.stringify({ runId: queued.id }));
-                }
-                else
-                    this.wakeQueue();
+                await this.signalQueuedRun(queued.id);
                 return queued;
             }
             case GET_RUN_ACTION: {

package/package.json

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