@isomorph.ai/app-sdk 1.6.2 → 1.8.0

package/README.md

@@ -36,6 +36,93 @@ Replace the connection/resource with the app's existing approved integration. To
 
 For images call `generateImage({model: gateway.image(process.env.ISOMORPH_AI_IMAGE_MODEL_ALIAS!), prompt: 'A blue notebook'})`. Editing uses `prompt: {text: 'Make it red', images: [inputBytes]}` only when `isomorph ai models` advertises edit. Reuse app files upload/signed reads for authorized input and output storage; respect existing transfer/action limits and never return credentials.
 
+## Company integrations
+
+`isomorph.integrations.execute(connection, request)` is one method over a closed
+set of operations; the operation fixes whose identity it runs under, and the
+contract's bounds are checked in the client before any request is sent (the
+same sentence the platform answers with). The connection, operation, resource
+and `mode` are literals in the call: the kit gate derives
+`.isomorph/integrations.json` from them. `isomorph dev` without `--real`
+answers every operation from a local fixture.
+
+Slack. A history, post, edit or delete runs as the app or as the signed-in
+person (`mode`, the one IT approved for the app); a DM and a user lookup run
+as the app only, against the fixed `workspace` resource. A post or DM needs a
+fresh UUID per explicit Send press.
+
+```ts
+// A thread reply in Slack mrkdwn
+const page = await isomorph.integrations.execute('company-slack', {
+  operation: 'slack.channel.history', resource: 'team-updates', input: { limit: 100 },
+});
+await isomorph.integrations.execute('company-slack', {
+  operation: 'slack.message.post', resource: 'team-updates',
+  input: { text: '*Done* — see <https://example.com/report|the report>', format: 'mrkdwn', threadId: page.messages[0].id },
+  idempotencyKey: crypto.randomUUID(), mode: 'app',
+});
+
+// Paged history: hasMore and nextCursor say when and how to read the next (older) page
+const older = await isomorph.integrations.execute('company-slack', {
+  operation: 'slack.channel.history', resource: 'team-updates', input: { limit: 100, cursor: page.nextCursor },
+});
+
+// Edit or delete a message the app posted (its ts is the messageId)
+const posted = await isomorph.integrations.execute('company-slack', {
+  operation: 'slack.message.post', resource: 'team-updates', input: { text: 'Deploy starting' }, idempotencyKey: crypto.randomUUID(), mode: 'app',
+});
+await isomorph.integrations.execute('company-slack', {
+  operation: 'slack.message.update', resource: 'team-updates', input: { messageId: posted.messageId, text: 'Deploy finished' }, mode: 'app',
+});
+await isomorph.integrations.execute('company-slack', {
+  operation: 'slack.message.delete', resource: 'team-updates', input: { messageId: posted.messageId }, mode: 'app',
+});
+
+// A direct message by email (1 to 8 people; several open one group DM) and a user lookup
+await isomorph.integrations.execute('company-slack', {
+  operation: 'slack.dm.send', resource: 'workspace', input: { to: ['jane@example.com'], text: 'Your review is due today.' },
+  idempotencyKey: crypto.randomUUID(),
+});
+const { userId } = await isomorph.integrations.execute('company-slack', {
+  operation: 'slack.user.lookup', resource: 'workspace', input: { email: 'jane@example.com' },
+});
+```
+
+Gmail runs as the signed-in person after their consent, on the fixed `inbox`
+resource.
+
+```ts
+// Search, then read a whole thread
+const found = await isomorph.integrations.execute('company-gmail', {
+  operation: 'gmail.thread.list', resource: 'inbox', input: { q: 'from:jane newer_than:7d', limit: 50 },
+});
+const thread = await isomorph.integrations.execute('company-gmail', {
+  operation: 'gmail.thread.read', resource: 'inbox', input: { threadId: found.threads[0].id },
+});
+// found.nextPageToken, when hasMore, is the next read's pageToken
+
+// An attachment: a message or thread read names them (id, filename, mimeType, size); this fetches the bytes
+const file = thread.emails[0].attachments?.[0];
+if (file) {
+  const { dataBase64 } = await isomorph.integrations.execute('company-gmail', {
+    operation: 'gmail.attachment.read', resource: 'inbox', input: { messageId: thread.emails[0].id, attachmentId: file.id },
+  });
+}
+
+// An HTML send: text stays the plain-text alternative; up to 5 attachments of 2 MiB each
+await isomorph.integrations.execute('company-gmail', {
+  operation: 'gmail.message.send', resource: 'inbox',
+  input: {
+    to: ['jane@example.com'], subject: 'Weekly report', text: 'The report is attached.',
+    html: '<p>The report is <b>attached</b>.</p>',
+    attachments: [{ filename: 'report.csv', contentType: 'text/csv', dataBase64: csvBase64 }],
+  },
+  idempotencyKey: crypto.randomUUID(),
+});
+```
+
+(1.8.0; contracts 0.71.0)
+
 ## Browser read tools
 
 Install optional peers `ai` and `playwright-core@1.58.2`. Locally run `npx playwright-core install chromium --only-shell`; V2 packages Chromium in the existing app image. An existing system executable can be supplied as executablePath.

package/dist/index.d.ts

@@ -24,47 +24,161 @@ export interface IsomorphResult<T> {
     data: T;
     count?: number;
 }
+/** How Slack renders a message's `text`: plain text, or Slack mrkdwn (`*bold*`, `<url|label>`, `<@U123>`); plain when absent. */
+export type SlackTextFormat = 'plain' | 'mrkdwn';
+/**
+ * Which of the modes IT approved for this app a declared-mode Slack operation runs under: `app` (the company's
+ * Slack app, under the IT-approved per-app name and footer) or `user` (the signed-in person, after their consent).
+ * Leave it out when the app is approved for one mode; an app approved for both must say (MODE_REQUIRED), and a
+ * mode IT has not approved is refused with MODE_NOT_GRANTED — never served under the other mode.
+ */
+export type SlackIdentityMode = 'app' | 'user';
+/** Reads a channel's newest messages as the signed-in person (or as the app, when declared so); pages backwards with `cursor`. */
 export interface SlackChannelHistoryRequest {
     operation: 'slack.channel.history';
     resource: string;
     input?: {
-        /** How many newest messages to read: an integer from 1 to 15 (the platform's ceiling); default 15. */
+        /** How many messages to read: an integer from 1 to 100 (the platform's ceiling); default 15. */
         limit?: number;
+        /** The `nextCursor` of the previous page; leave it out to read the newest page. */
+        cursor?: string;
+        /** Only messages after this Slack ts (a message id). */
+        oldest?: string;
+        /** Only messages before this Slack ts (a message id). */
+        latest?: string;
     };
+    mode?: SlackIdentityMode;
 }
+/** Posts one message to a channel, as the app or as the signed-in person; `threadId` makes it a thread reply. */
 export interface SlackMessagePostRequest {
     operation: 'slack.message.post';
     resource: string;
     input: {
-        /** Plain text, 1 to 4000 characters. Posted as the app (under the IT-approved per-app name) or as the signed-in person (their consent), the same text either way. */
+        /** The body, 1 to 4000 characters; plain text unless `format` is `mrkdwn`. Posted as the app (under the IT-approved per-app name) or as the signed-in person (their consent), the same text either way. */
         text: string;
+        /** The Slack ts of the message this one replies to (a history message id), so the post lands in that thread. */
+        threadId?: string;
+        format?: SlackTextFormat;
     };
     /** A fresh UUID per explicit Send press, reused only to retry that press. */
     idempotencyKey: string;
-    /**
-     * Which of the modes IT approved for this app the post runs under: `app` (the company's Slack app, under the
-     * IT-approved per-app name and footer) or `user` (the signed-in person, after their consent). Leave it out when
-     * the app is approved for one mode; an app approved for both must say (MODE_REQUIRED), and a mode IT has not
-     * approved is refused with MODE_NOT_GRANTED — never served under the other mode.
-     */
-    mode?: 'app' | 'user';
+    mode?: SlackIdentityMode;
 }
+/** Edits a message the app (or the signed-in person, in user mode) posted; the whole `text` is replaced. */
+export interface SlackMessageUpdateRequest {
+    operation: 'slack.message.update';
+    resource: string;
+    input: {
+        /** The Slack ts a post or history result named as `messageId`. */
+        messageId: string;
+        /** The new body, 1 to 4000 characters. */
+        text: string;
+        format?: SlackTextFormat;
+    };
+    mode?: SlackIdentityMode;
+}
+/** Deletes a message the app (or the signed-in person, in user mode) posted. */
+export interface SlackMessageDeleteRequest {
+    operation: 'slack.message.delete';
+    resource: string;
+    input: {
+        /** The Slack ts a post or history result named as `messageId`. */
+        messageId: string;
+    };
+    mode?: SlackIdentityMode;
+}
+/**
+ * Sends a direct message as the company's Slack app to workspace members named by email (always app mode; the
+ * resource is the fixed `workspace` alias). Several recipients open one group DM.
+ */
+export interface SlackDmSendRequest {
+    operation: 'slack.dm.send';
+    resource: string;
+    input: {
+        /** 1 to 8 email addresses of workspace members, no repeats. */
+        to: string[];
+        /** The body, 1 to 4000 characters. */
+        text: string;
+        format?: SlackTextFormat;
+    };
+    /** A fresh UUID per explicit Send press, reused only to retry that press. */
+    idempotencyKey: string;
+}
+/** Resolves a workspace member's email to their Slack user id, as the app (the resource is the fixed `workspace` alias). */
+export interface SlackUserLookupRequest {
+    operation: 'slack.user.lookup';
+    resource: string;
+    input: {
+        /** The member's email address. */
+        email: string;
+    };
+}
+/**
+ * One condition on a warehouse read; a read's conditions are AND-ed. `isNull`/`isNotNull` take no value, `in`/`notIn`
+ * a non-empty list of one type, every other op one value (a boolean only with `eq`/`ne`). The column and op are
+ * literals in the call; the value may be any expression.
+ */
+export interface WarehouseFilter {
+    column: string;
+    op: 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'notIn' | 'isNull' | 'isNotNull';
+    value?: string | number | boolean | Array<string | number>;
+}
+/** One aggregate a warehouse read returns under `as`: `count` may count `'*'`; sum, avg, min and max need a column. */
+export interface WarehouseAggregate {
+    fn: 'count' | 'sum' | 'avg' | 'min' | 'max';
+    column: string;
+    as: string;
+}
+/** One sort key: a returned column or an aggregate's alias; `direction` defaults to `'asc'`. */
+export interface WarehouseOrder {
+    column: string;
+    direction?: 'asc' | 'desc';
+}
+/**
+ * Filter, group and sort in the warehouse, never by pulling raw rows to total in code. A read names `columns`
+ * (a plain read) or `aggregates` (grouped by `groupBy`, or one row for the whole view), never both. Every column
+ * the read names must be approved for the view.
+ */
 export interface WarehouseViewReadRequest {
     operation: 'warehouse.view.read';
     resource: string;
     input: {
-        /** 1 to 32 approved column names, or `['*']` when IT exposes all current and future columns. */
-        columns: string[];
+        /** A plain read: 1 to 32 approved column names, or `['*']` when IT exposes all current and future columns. */
+        columns?: string[];
+        /** 1 to 16 conditions, all of which a row must meet. */
+        where?: WarehouseFilter[];
+        /** 1 to 8 columns to group the aggregates by; needs `aggregates`. */
+        groupBy?: string[];
+        /** 1 to 16 aggregates; each row carries the `groupBy` columns, then each alias. */
+        aggregates?: WarehouseAggregate[];
+        /** 1 to 8 sort keys. A grouped read with none is sorted by its `groupBy` columns; a plain read with none is unsorted. */
+        orderBy?: WarehouseOrder[];
         /** How many rows to read: an integer from 1 to 1000; default 100. */
         limit?: number;
     };
 }
-/** Gmail runs as the signed-in person after their consent. Resources are approved mailbox aliases. */
+/** Gmail runs as the signed-in person after their consent. Resources are approved mailbox aliases (`inbox`). */
 export interface GmailThreadListRequest {
     operation: 'gmail.thread.list';
     resource: string;
     input?: {
+        /** Newest matching threads, 1 to 50; default 15. */
         limit?: number;
+        /** A Gmail search query in the search-box syntax, e.g. `from:jane newer_than:7d`, 1 to 256 characters. */
+        q?: string;
+        /** 1 to 5 labels a thread must carry (all of them); `['INBOX']` when absent. */
+        labelIds?: string[];
+        /** The `nextPageToken` of the previous page; leave it out to read the first page. */
+        pageToken?: string;
+    };
+}
+/** Reads every message of one thread, oldest first, as the signed-in person. */
+export interface GmailThreadReadRequest {
+    operation: 'gmail.thread.read';
+    resource: string;
+    input: {
+        /** The thread id a `gmail.thread.list` result named. */
+        threadId: string;
     };
 }
 export interface GmailMessageReadRequest {
@@ -74,24 +188,47 @@ export interface GmailMessageReadRequest {
         messageId: string;
     };
 }
+/** Reads one attachment's bytes (at most 2 MiB) as the signed-in person; the ids come from a message or thread read. */
+export interface GmailAttachmentReadRequest {
+    operation: 'gmail.attachment.read';
+    resource: string;
+    input: {
+        messageId: string;
+        /** The `id` of an entry in the message's `attachments`. */
+        attachmentId: string;
+    };
+}
+/** One file to attach to a send, carried inline as base64: at most 2 MiB of bytes (2,796,203 base64 characters). */
+export interface GmailAttachmentInput {
+    /** The name the recipient sees, 1 to 255 characters. */
+    filename: string;
+    /** The MIME type, e.g. `application/pdf`. */
+    contentType: string;
+    /** The file bytes, standard base64. */
+    dataBase64: string;
+}
 export interface GmailMessageSendRequest {
     operation: 'gmail.message.send';
     resource: string;
     input: {
-        /** 1 to 50 email addresses per recipient list. */
+        /** 1 to 50 email addresses per recipient list (at most 50 across to, cc and bcc). */
         to: string[];
         cc?: string[];
         bcc?: string[];
         /** 1 to 256 characters. */
         subject: string;
-        /** Plain text, 1 to 4000 characters. Attachments and HTML are not supported. */
+        /** Plain text, 1 to 4000 characters; the plain-text alternative when `html` is sent too. */
         text: string;
+        /** An HTML body sent beside `text`, at most 64 KiB. */
+        html?: string;
+        /** 1 to 5 files, each at most 2 MiB. */
+        attachments?: GmailAttachmentInput[];
         replyToMessageId?: string;
     };
     /** A fresh UUID per authorized Send action, reused only to retry that action. */
     idempotencyKey: string;
 }
-export type IntegrationRequest = SlackChannelHistoryRequest | SlackMessagePostRequest | WarehouseViewReadRequest | GmailThreadListRequest | GmailMessageReadRequest | GmailMessageSendRequest;
+export type IntegrationRequest = SlackChannelHistoryRequest | SlackMessagePostRequest | SlackMessageUpdateRequest | SlackMessageDeleteRequest | SlackDmSendRequest | SlackUserLookupRequest | WarehouseViewReadRequest | GmailThreadListRequest | GmailThreadReadRequest | GmailMessageReadRequest | GmailAttachmentReadRequest | GmailMessageSendRequest;
 export type IntegrationOperation = IntegrationRequest['operation'];
 export interface SlackMessage {
     id: string;
@@ -106,12 +243,27 @@ export interface SlackMessage {
 export interface SlackChannelHistoryResult {
     messages: SlackMessage[];
     hasMore: boolean;
+    /** The cursor of the next (older) page, present only when `hasMore`; pass it as the next read's `cursor`. */
+    nextCursor?: string;
 }
+/** The Slack ts of the message posted, edited or deleted. */
 export interface SlackMessagePostResult {
     messageId: string;
 }
+export interface SlackDmSendResult {
+    messageId: string;
+    /** The DM channel the message went to. */
+    channelId: string;
+}
+export interface SlackUserLookupResult {
+    userId: string;
+    /** The member's display name, or real name when they set none; may be empty. */
+    displayName: string;
+}
 export interface WarehouseViewReadResult {
     rows: Array<Record<string, unknown>>;
+    /** True when more rows matched than `limit`: the rows are incomplete, so never total or average them in code. */
+    truncated: boolean;
 }
 export interface GmailThreadSummary {
     id: string;
@@ -124,6 +276,16 @@ export interface GmailThreadSummary {
 export interface GmailThreadListResult {
     threads: GmailThreadSummary[];
     hasMore: boolean;
+    /** The token of the next page, present only when `hasMore`; pass it as the next read's `pageToken`. */
+    nextPageToken?: string;
+}
+/** One attachment of a message, named without its bytes; `gmail.attachment.read` fetches them by `id`. */
+export interface GmailAttachment {
+    id: string;
+    filename: string;
+    mimeType: string;
+    /** Bytes. */
+    size: number;
 }
 export interface GmailMessageReadResult {
     id: string;
@@ -132,14 +294,27 @@ export interface GmailMessageReadResult {
     from: string;
     to: string;
     date: string;
+    /** The plain text with HTML stripped, cut at 16 KiB with `truncated` set. */
     text: string;
     truncated: boolean;
+    attachments?: GmailAttachment[];
+}
+/** Every message of the thread, oldest first, each in the `gmail.message.read` shape. */
+export interface GmailThreadReadResult {
+    id: string;
+    emails: GmailMessageReadResult[];
+}
+export interface GmailAttachmentReadResult {
+    filename: string;
+    mimeType: string;
+    size: number;
+    dataBase64: string;
 }
 export interface GmailMessageSendResult {
     messageId: string;
     threadId: string;
 }
-export type IntegrationResult<R extends IntegrationRequest> = R extends SlackChannelHistoryRequest ? SlackChannelHistoryResult : R extends SlackMessagePostRequest ? SlackMessagePostResult : R extends WarehouseViewReadRequest ? WarehouseViewReadResult : R extends GmailThreadListRequest ? GmailThreadListResult : R extends GmailMessageReadRequest ? GmailMessageReadResult : R extends GmailMessageSendRequest ? GmailMessageSendResult : never;
+export type IntegrationResult<R extends IntegrationRequest> = R extends SlackChannelHistoryRequest ? SlackChannelHistoryResult : R extends SlackMessagePostRequest | SlackMessageUpdateRequest | SlackMessageDeleteRequest ? SlackMessagePostResult : R extends SlackDmSendRequest ? SlackDmSendResult : R extends SlackUserLookupRequest ? SlackUserLookupResult : R extends WarehouseViewReadRequest ? WarehouseViewReadResult : R extends GmailThreadListRequest ? GmailThreadListResult : R extends GmailThreadReadRequest ? GmailThreadReadResult : R extends GmailMessageReadRequest ? GmailMessageReadResult : R extends GmailAttachmentReadRequest ? GmailAttachmentReadResult : R extends GmailMessageSendRequest ? GmailMessageSendResult : never;
 export type IntegrationConnectResult = {
     status: 'connected';
     accountLabel: string;

package/dist/index.js

@@ -16,6 +16,25 @@ export class IsomorphError extends Error {
         this.name = 'IsomorphError';
     }
 }
+// The warehouse rules the generated table cannot state, with governance's
+// sentences: a read names columns or aggregates (one of them; it once needed
+// columns), and "*" stands alone. Governance owns the query's other rules.
+function warehouseReadProblem({ columns, aggregates }) {
+    if (columns != null && aggregates != null)
+        return { field: 'columns', message: 'a warehouse read names columns or aggregates, not both' };
+    if (columns == null && aggregates == null)
+        return { field: 'columns', message: 'a warehouse read needs columns or aggregates' };
+    if (columns?.includes('*') && columns.length !== 1)
+        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;
@@ -659,18 +678,16 @@ export function createClient(options = {}) {
                 // `isomorph check` (which runs retained journeys through this client)
                 // and the deployed app fail the same way at build time, not at runtime.
                 const checked = validateIntegrationExecuteInput(request.operation, request.input);
-                if (!checked.ok) {
-                    return Promise.reject(new IsomorphError('VALIDATION_FAILED', checked.problem.message, undefined, { code: 'INPUT_INVALID', field: checked.problem.field }));
-                }
-                if (request.operation === 'warehouse.view.read' && Array.isArray(request.input?.columns) && request.input.columns.includes('*') && request.input.columns.length !== 1) {
-                    return Promise.reject(new IsomorphError('VALIDATION_FAILED', 'columns may use "*" only as the sole entry', undefined, { code: 'INPUT_INVALID', field: 'columns' }));
+                const problem = !checked.ok ? checked.problem
+                    : request.operation === 'warehouse.view.read' ? warehouseReadProblem(request.input ?? {}) : undefined;
+                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` is one of them
-                // for a Slack post only (which approved mode it runs under); an
-                // `identity` or any other stray field is not sent.
+                // Exactly the contract's fields go on the wire: `mode` only for the
+                // declaredModeOperations; an `identity` or any other stray field is 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 === 'slack.message.post' && mode !== undefined ? { mode } : {}) }),
+                    method: 'POST', body: JSON.stringify({ connection, operation, resource, ...(input !== undefined ? { input } : {}), ...(idempotencyKey !== undefined ? { idempotencyKey } : {}), ...(operation in declaredModeOperations && mode !== undefined ? { mode } : {}) }),
                 });
             },
             // In a browser the consent returns the person to this page (without its

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

@@ -28,7 +28,31 @@ export type IntegrationExecuteInputFieldRule = {
         maxLength?: number;
         pattern?: string;
     };
+    default?: readonly string[];
+} | {
+    kind: 'enum';
+    required: boolean;
+    values: readonly string[];
+    default?: string;
+} | {
+    kind: 'object[]';
+    required: boolean;
+    minItems: number;
+    maxItems: number;
+    fields: Readonly<Record<string, IntegrationExecuteInputFieldRule>>;
+} | {
+    kind: 'value';
+    required: boolean;
+    types: readonly IntegrationExecuteInputValueType[];
+    maxLength?: number;
+    list?: {
+        minItems: number;
+        maxItems: number;
+        types: readonly IntegrationExecuteInputValueType[];
+    };
 };
+/** The scalar types a `value` input accepts, alone or in its list form. */
+export type IntegrationExecuteInputValueType = 'string' | 'number' | 'boolean';
 export type IntegrationExecuteOperationRule = {
     idempotencyKey: boolean;
     fields: Record<string, IntegrationExecuteInputFieldRule>;
@@ -41,9 +65,27 @@ export declare const IntegrationExecuteInputRules: {
                 readonly kind: "integer";
                 readonly required: false;
                 readonly minimum: 1;
-                readonly maximum: 15;
+                readonly maximum: 100;
                 readonly default: 15;
             };
+            readonly cursor: {
+                readonly kind: "string";
+                readonly required: false;
+                readonly minLength: 1;
+                readonly maxLength: 256;
+            };
+            readonly oldest: {
+                readonly kind: "string";
+                readonly required: false;
+                readonly minLength: 1;
+                readonly maxLength: 64;
+            };
+            readonly latest: {
+                readonly kind: "string";
+                readonly required: false;
+                readonly minLength: 1;
+                readonly maxLength: 64;
+            };
         };
     };
     readonly "slack.message.post": {
@@ -55,6 +97,93 @@ export declare const IntegrationExecuteInputRules: {
                 readonly minLength: 1;
                 readonly maxLength: 4000;
             };
+            readonly threadId: {
+                readonly kind: "string";
+                readonly required: false;
+                readonly minLength: 0;
+                readonly pattern: "^[A-Za-z0-9._-]{1,64}$";
+            };
+            readonly format: {
+                readonly kind: "enum";
+                readonly required: false;
+                readonly values: readonly ["plain", "mrkdwn"];
+                readonly default: "plain";
+            };
+        };
+    };
+    readonly "slack.message.update": {
+        readonly idempotencyKey: false;
+        readonly fields: {
+            readonly messageId: {
+                readonly kind: "string";
+                readonly required: true;
+                readonly minLength: 0;
+                readonly pattern: "^[A-Za-z0-9._-]{1,64}$";
+            };
+            readonly text: {
+                readonly kind: "string";
+                readonly required: true;
+                readonly minLength: 1;
+                readonly maxLength: 4000;
+            };
+            readonly format: {
+                readonly kind: "enum";
+                readonly required: false;
+                readonly values: readonly ["plain", "mrkdwn"];
+                readonly default: "plain";
+            };
+        };
+    };
+    readonly "slack.message.delete": {
+        readonly idempotencyKey: false;
+        readonly fields: {
+            readonly messageId: {
+                readonly kind: "string";
+                readonly required: true;
+                readonly minLength: 0;
+                readonly pattern: "^[A-Za-z0-9._-]{1,64}$";
+            };
+        };
+    };
+    readonly "slack.dm.send": {
+        readonly idempotencyKey: true;
+        readonly fields: {
+            readonly to: {
+                readonly kind: "string[]";
+                readonly required: true;
+                readonly minItems: 1;
+                readonly maxItems: 8;
+                readonly uniqueItems: true;
+                readonly item: {
+                    readonly minLength: 3;
+                    readonly maxLength: 254;
+                    readonly pattern: "^[^\\s@<>,;\"]+@[^\\s@<>,;\"]+\\.[^\\s@<>,;\"]+$";
+                };
+            };
+            readonly text: {
+                readonly kind: "string";
+                readonly required: true;
+                readonly minLength: 1;
+                readonly maxLength: 4000;
+            };
+            readonly format: {
+                readonly kind: "enum";
+                readonly required: false;
+                readonly values: readonly ["plain", "mrkdwn"];
+                readonly default: "plain";
+            };
+        };
+    };
+    readonly "slack.user.lookup": {
+        readonly idempotencyKey: false;
+        readonly fields: {
+            readonly email: {
+                readonly kind: "string";
+                readonly required: true;
+                readonly minLength: 3;
+                readonly maxLength: 254;
+                readonly pattern: "^[^\\s@<>,;\"]+@[^\\s@<>,;\"]+\\.[^\\s@<>,;\"]+$";
+            };
         };
     };
     readonly "gmail.thread.list": {
@@ -64,9 +193,44 @@ export declare const IntegrationExecuteInputRules: {
                 readonly kind: "integer";
                 readonly required: false;
                 readonly minimum: 1;
-                readonly maximum: 15;
+                readonly maximum: 50;
                 readonly default: 15;
             };
+            readonly q: {
+                readonly kind: "string";
+                readonly required: false;
+                readonly minLength: 1;
+                readonly maxLength: 256;
+            };
+            readonly labelIds: {
+                readonly kind: "string[]";
+                readonly required: false;
+                readonly minItems: 1;
+                readonly maxItems: 5;
+                readonly uniqueItems: true;
+                readonly item: {
+                    readonly minLength: 1;
+                    readonly maxLength: 64;
+                };
+                readonly default: readonly ["INBOX"];
+            };
+            readonly pageToken: {
+                readonly kind: "string";
+                readonly required: false;
+                readonly minLength: 1;
+                readonly maxLength: 256;
+            };
+        };
+    };
+    readonly "gmail.thread.read": {
+        readonly idempotencyKey: false;
+        readonly fields: {
+            readonly threadId: {
+                readonly kind: "string";
+                readonly required: true;
+                readonly minLength: 0;
+                readonly pattern: "^[A-Za-z0-9._-]{1,64}$";
+            };
         };
     };
     readonly "gmail.message.read": {
@@ -76,7 +240,7 @@ export declare const IntegrationExecuteInputRules: {
                 readonly kind: "string";
                 readonly required: true;
                 readonly minLength: 0;
-                readonly pattern: "^[A-Za-z0-9_-]{1,64}$";
+                readonly pattern: "^[A-Za-z0-9._-]{1,64}$";
             };
         };
     };
@@ -131,6 +295,38 @@ export declare const IntegrationExecuteInputRules: {
                 readonly minLength: 1;
                 readonly maxLength: 4000;
             };
+            readonly html: {
+                readonly kind: "string";
+                readonly required: false;
+                readonly minLength: 1;
+                readonly maxLength: 65536;
+            };
+            readonly attachments: {
+                readonly kind: "object[]";
+                readonly required: false;
+                readonly minItems: 1;
+                readonly maxItems: 5;
+                readonly fields: {
+                    readonly filename: {
+                        readonly kind: "string";
+                        readonly required: true;
+                        readonly minLength: 1;
+                        readonly maxLength: 255;
+                    };
+                    readonly contentType: {
+                        readonly kind: "string";
+                        readonly required: true;
+                        readonly minLength: 1;
+                        readonly maxLength: 128;
+                    };
+                    readonly dataBase64: {
+                        readonly kind: "string";
+                        readonly required: true;
+                        readonly minLength: 1;
+                        readonly maxLength: 2796203;
+                    };
+                };
+            };
             readonly replyToMessageId: {
                 readonly kind: "string";
                 readonly required: false;
@@ -139,12 +335,29 @@ export declare const IntegrationExecuteInputRules: {
             };
         };
     };
+    readonly "gmail.attachment.read": {
+        readonly idempotencyKey: false;
+        readonly fields: {
+            readonly messageId: {
+                readonly kind: "string";
+                readonly required: true;
+                readonly minLength: 0;
+                readonly pattern: "^[A-Za-z0-9._-]{1,64}$";
+            };
+            readonly attachmentId: {
+                readonly kind: "string";
+                readonly required: true;
+                readonly minLength: 1;
+                readonly maxLength: 512;
+            };
+        };
+    };
     readonly "warehouse.view.read": {
         readonly idempotencyKey: false;
         readonly fields: {
             readonly columns: {
                 readonly kind: "string[]";
-                readonly required: true;
+                readonly required: false;
                 readonly minItems: 1;
                 readonly maxItems: 32;
                 readonly uniqueItems: false;
@@ -153,6 +366,92 @@ export declare const IntegrationExecuteInputRules: {
                     readonly pattern: "^(?:\\*|[A-Za-z_][A-Za-z0-9_]{0,62})$";
                 };
             };
+            readonly where: {
+                readonly kind: "object[]";
+                readonly required: false;
+                readonly minItems: 1;
+                readonly maxItems: 16;
+                readonly fields: {
+                    readonly column: {
+                        readonly kind: "string";
+                        readonly required: true;
+                        readonly minLength: 0;
+                        readonly pattern: "^[A-Za-z_][A-Za-z0-9_]{0,62}$";
+                    };
+                    readonly op: {
+                        readonly kind: "enum";
+                        readonly required: true;
+                        readonly values: readonly ["eq", "ne", "gt", "gte", "lt", "lte", "in", "notIn", "isNull", "isNotNull"];
+                    };
+                    readonly value: {
+                        readonly kind: "value";
+                        readonly required: false;
+                        readonly types: readonly ["string", "number", "boolean"];
+                        readonly maxLength: 256;
+                        readonly list: {
+                            readonly minItems: 1;
+                            readonly maxItems: 100;
+                            readonly types: readonly ["string", "number"];
+                        };
+                    };
+                };
+            };
+            readonly groupBy: {
+                readonly kind: "string[]";
+                readonly required: false;
+                readonly minItems: 1;
+                readonly maxItems: 8;
+                readonly uniqueItems: false;
+                readonly item: {
+                    readonly minLength: 0;
+                    readonly pattern: "^[A-Za-z_][A-Za-z0-9_]{0,62}$";
+                };
+            };
+            readonly aggregates: {
+                readonly kind: "object[]";
+                readonly required: false;
+                readonly minItems: 1;
+                readonly maxItems: 16;
+                readonly fields: {
+                    readonly fn: {
+                        readonly kind: "enum";
+                        readonly required: true;
+                        readonly values: readonly ["count", "sum", "avg", "min", "max"];
+                    };
+                    readonly column: {
+                        readonly kind: "string";
+                        readonly required: true;
+                        readonly minLength: 0;
+                        readonly pattern: "^(?:\\*|[A-Za-z_][A-Za-z0-9_]{0,62})$";
+                    };
+                    readonly as: {
+                        readonly kind: "string";
+                        readonly required: true;
+                        readonly minLength: 0;
+                        readonly pattern: "^[a-z_][a-z0-9_]{0,62}$";
+                    };
+                };
+            };
+            readonly orderBy: {
+                readonly kind: "object[]";
+                readonly required: false;
+                readonly minItems: 1;
+                readonly maxItems: 8;
+                readonly fields: {
+                    readonly column: {
+                        readonly kind: "string";
+                        readonly required: true;
+                        readonly minLength: 0;
+                        readonly pattern: "^[A-Za-z_][A-Za-z0-9_]{0,62}$";
+                    };
+                    readonly direction: {
+                        readonly kind: "enum";
+                        readonly required: false;
+                        readonly values: readonly ["asc", "desc"];
+                        readonly default: "asc";
+                    };
+                };
+            };
             readonly limit: {
                 readonly kind: "integer";
                 readonly required: false;

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

@@ -4,25 +4,67 @@ export const IntegrationExecuteInputRules = {
     "slack.channel.history": {
         idempotencyKey: false,
         fields: {
-            limit: { kind: "integer", required: false, minimum: 1, maximum: 15, default: 15 },
+            limit: { kind: "integer", required: false, minimum: 1, maximum: 100, default: 15 },
+            cursor: { kind: "string", required: false, minLength: 1, maxLength: 256 },
+            oldest: { kind: "string", required: false, minLength: 1, maxLength: 64 },
+            latest: { kind: "string", required: false, minLength: 1, maxLength: 64 },
         },
     },
     "slack.message.post": {
         idempotencyKey: true,
         fields: {
             text: { kind: "string", required: true, minLength: 1, maxLength: 4000 },
+            threadId: { kind: "string", required: false, minLength: 0, pattern: "^[A-Za-z0-9._-]{1,64}$" },
+            format: { kind: "enum", required: false, values: ["plain", "mrkdwn"], default: "plain" },
+        },
+    },
+    "slack.message.update": {
+        idempotencyKey: false,
+        fields: {
+            messageId: { kind: "string", required: true, minLength: 0, pattern: "^[A-Za-z0-9._-]{1,64}$" },
+            text: { kind: "string", required: true, minLength: 1, maxLength: 4000 },
+            format: { kind: "enum", required: false, values: ["plain", "mrkdwn"], default: "plain" },
+        },
+    },
+    "slack.message.delete": {
+        idempotencyKey: false,
+        fields: {
+            messageId: { kind: "string", required: true, minLength: 0, pattern: "^[A-Za-z0-9._-]{1,64}$" },
+        },
+    },
+    "slack.dm.send": {
+        idempotencyKey: true,
+        fields: {
+            to: { kind: "string[]", required: true, minItems: 1, maxItems: 8, uniqueItems: true, item: { minLength: 3, maxLength: 254, pattern: "^[^\\s@<>,;\"]+@[^\\s@<>,;\"]+\\.[^\\s@<>,;\"]+$" } },
+            text: { kind: "string", required: true, minLength: 1, maxLength: 4000 },
+            format: { kind: "enum", required: false, values: ["plain", "mrkdwn"], default: "plain" },
+        },
+    },
+    "slack.user.lookup": {
+        idempotencyKey: false,
+        fields: {
+            email: { kind: "string", required: true, minLength: 3, maxLength: 254, pattern: "^[^\\s@<>,;\"]+@[^\\s@<>,;\"]+\\.[^\\s@<>,;\"]+$" },
         },
     },
     "gmail.thread.list": {
         idempotencyKey: false,
         fields: {
-            limit: { kind: "integer", required: false, minimum: 1, maximum: 15, default: 15 },
+            limit: { kind: "integer", required: false, minimum: 1, maximum: 50, default: 15 },
+            q: { kind: "string", required: false, minLength: 1, maxLength: 256 },
+            labelIds: { kind: "string[]", required: false, minItems: 1, maxItems: 5, uniqueItems: true, item: { minLength: 1, maxLength: 64 }, default: ["INBOX"] },
+            pageToken: { kind: "string", required: false, minLength: 1, maxLength: 256 },
+        },
+    },
+    "gmail.thread.read": {
+        idempotencyKey: false,
+        fields: {
+            threadId: { kind: "string", required: true, minLength: 0, pattern: "^[A-Za-z0-9._-]{1,64}$" },
         },
     },
     "gmail.message.read": {
         idempotencyKey: false,
         fields: {
-            messageId: { kind: "string", required: true, minLength: 0, pattern: "^[A-Za-z0-9_-]{1,64}$" },
+            messageId: { kind: "string", required: true, minLength: 0, pattern: "^[A-Za-z0-9._-]{1,64}$" },
         },
     },
     "gmail.message.send": {
@@ -33,13 +75,41 @@ export const IntegrationExecuteInputRules = {
             bcc: { kind: "string[]", required: false, minItems: 1, maxItems: 50, uniqueItems: true, item: { minLength: 3, maxLength: 254, pattern: "^[^\\s@<>,;\"]+@[^\\s@<>,;\"]+\\.[^\\s@<>,;\"]+$" } },
             subject: { kind: "string", required: true, minLength: 1, maxLength: 256 },
             text: { kind: "string", required: true, minLength: 1, maxLength: 4000 },
+            html: { kind: "string", required: false, minLength: 1, maxLength: 65536 },
+            attachments: { kind: "object[]", required: false, minItems: 1, maxItems: 5, fields: {
+                    filename: { kind: "string", required: true, minLength: 1, maxLength: 255 },
+                    contentType: { kind: "string", required: true, minLength: 1, maxLength: 128 },
+                    dataBase64: { kind: "string", required: true, minLength: 1, maxLength: 2796203 },
+                } },
             replyToMessageId: { kind: "string", required: false, minLength: 0, pattern: "^[A-Za-z0-9_-]{1,64}$" },
         },
     },
+    "gmail.attachment.read": {
+        idempotencyKey: false,
+        fields: {
+            messageId: { kind: "string", required: true, minLength: 0, pattern: "^[A-Za-z0-9._-]{1,64}$" },
+            attachmentId: { kind: "string", required: true, minLength: 1, maxLength: 512 },
+        },
+    },
     "warehouse.view.read": {
         idempotencyKey: false,
         fields: {
-            columns: { kind: "string[]", required: true, minItems: 1, maxItems: 32, uniqueItems: false, item: { minLength: 0, pattern: "^(?:\\*|[A-Za-z_][A-Za-z0-9_]{0,62})$" } },
+            columns: { kind: "string[]", required: false, minItems: 1, maxItems: 32, uniqueItems: false, item: { minLength: 0, pattern: "^(?:\\*|[A-Za-z_][A-Za-z0-9_]{0,62})$" } },
+            where: { kind: "object[]", required: false, minItems: 1, maxItems: 16, fields: {
+                    column: { kind: "string", required: true, minLength: 0, pattern: "^[A-Za-z_][A-Za-z0-9_]{0,62}$" },
+                    op: { kind: "enum", required: true, values: ["eq", "ne", "gt", "gte", "lt", "lte", "in", "notIn", "isNull", "isNotNull"] },
+                    value: { kind: "value", required: false, types: ["string", "number", "boolean"], maxLength: 256, list: { minItems: 1, maxItems: 100, types: ["string", "number"] } },
+                } },
+            groupBy: { kind: "string[]", required: false, minItems: 1, maxItems: 8, uniqueItems: false, item: { minLength: 0, pattern: "^[A-Za-z_][A-Za-z0-9_]{0,62}$" } },
+            aggregates: { kind: "object[]", required: false, minItems: 1, maxItems: 16, fields: {
+                    fn: { kind: "enum", required: true, values: ["count", "sum", "avg", "min", "max"] },
+                    column: { kind: "string", required: true, minLength: 0, pattern: "^(?:\\*|[A-Za-z_][A-Za-z0-9_]{0,62})$" },
+                    as: { kind: "string", required: true, minLength: 0, pattern: "^[a-z_][a-z0-9_]{0,62}$" },
+                } },
+            orderBy: { kind: "object[]", required: false, minItems: 1, maxItems: 8, fields: {
+                    column: { kind: "string", required: true, minLength: 0, pattern: "^[A-Za-z_][A-Za-z0-9_]{0,62}$" },
+                    direction: { kind: "enum", required: false, values: ["asc", "desc"], default: "asc" },
+                } },
             limit: { kind: "integer", required: false, minimum: 1, maximum: 1000, default: 100 },
         },
     },
@@ -60,55 +130,113 @@ function matches(pattern, value) {
     }
     return compiled.test(value);
 }
+function refuse(field, message) { return { ok: false, problem: { field, message } }; }
+const valueNouns = { string: ['a string', 'strings'], number: ['a number', 'numbers'], boolean: ['a boolean', 'booleans'] };
+function either(parts) {
+    return parts.length > 1 ? `${parts.slice(0, -1).join(', ')} or ${parts[parts.length - 1]}` : parts.join('');
+}
+function isScalar(types, maxLength, value) {
+    if (typeof value === 'string')
+        return types.includes('string') && (maxLength === undefined || value.length <= maxLength);
+    if (typeof value === 'number')
+        return types.includes('number') && Number.isFinite(value);
+    return typeof value === 'boolean' && types.includes('boolean');
+}
 /**
- * Validates one operation's input against the contract and returns it with the
- * contract's defaults applied. The message names the field and its allowed
- * range; it is the sentence the platform answers with, so a caller may show it.
+ * Checks one object's fields in rule order and applies defaults: the input
+ * itself (where null counts as absent), or one entry of an object[] input
+ * (where only a missing key is absent, so null is refused like any wrong value).
  */
-export function validateIntegrationExecuteInput(operation, input) {
-    const rule = IntegrationExecuteInputRules[operation];
-    if (!rule)
-        return { ok: false, problem: { field: 'operation', message: `${operation} is not a declared integration operation` } };
-    const raw = input === undefined ? {} : input;
-    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
-        return { ok: false, problem: { field: 'input', message: 'input must be an object' } };
-    const given = raw;
+function checkFields(operation, prefix, fields, given, nullIsAbsent) {
     for (const name of Object.keys(given))
-        if (!Object.prototype.hasOwnProperty.call(rule.fields, name))
-            return { ok: false, problem: { field: name, message: `${name} is not an input of ${operation}` } };
+        if (!Object.prototype.hasOwnProperty.call(fields, name))
+            return refuse(prefix + name, `${prefix}${name} is not an input of ${operation}`);
     const out = {};
-    for (const [name, field] of Object.entries(rule.fields)) {
+    for (const [name, field] of Object.entries(fields)) {
+        const path = prefix + name;
         const value = given[name];
-        if (value === undefined || value === null) {
+        if (value === undefined || (nullIsAbsent && value === null)) {
             if (field.required)
-                return { ok: false, problem: { field: name, message: `${name} is required for ${operation}` } };
-            if (field.kind === 'integer' && field.default !== undefined)
+                return refuse(path, `${path} is required for ${operation}`);
+            if ((field.kind === 'integer' || field.kind === 'enum') && field.default !== undefined)
                 out[name] = field.default;
+            if (field.kind === 'string[]' && field.default !== undefined)
+                out[name] = [...field.default];
             continue;
         }
-        if (field.kind === 'integer') {
+        const checked = checkField(operation, path, name, field, value);
+        if (!checked.ok)
+            return checked;
+        out[name] = checked.value;
+    }
+    return { ok: true, value: out };
+}
+function checkField(operation, path, name, field, value) {
+    switch (field.kind) {
+        case 'integer':
             if (typeof value !== 'number' || !Number.isInteger(value) || value < field.minimum || value > field.maximum)
-                return { ok: false, problem: { field: name, message: `${name} must be an integer between ${field.minimum} and ${field.maximum}` } };
-        }
-        else if (field.kind === 'string') {
+                return refuse(path, `${path} must be an integer between ${field.minimum} and ${field.maximum}`);
+            return { ok: true, value };
+        case 'string':
             if (typeof value !== 'string' || value.length < field.minLength || (field.maxLength !== undefined && value.length > field.maxLength))
-                return { ok: false, problem: { field: name, message: field.maxLength !== undefined ? `${name} must be ${field.minLength} to ${field.maxLength} characters` : `${name} must be a string of at least ${field.minLength} characters` } };
+                return refuse(path, field.maxLength !== undefined ? `${path} must be ${field.minLength} to ${field.maxLength} characters` : `${path} must be a string of at least ${field.minLength} characters`);
             if (field.pattern && !matches(field.pattern, value))
-                return { ok: false, problem: { field: name, message: `${name} must match ${field.pattern}` } };
-        }
-        else {
+                return refuse(path, `${path} must match ${field.pattern}`);
+            return { ok: true, value };
+        case 'enum':
+            if (typeof value !== 'string' || !field.values.includes(value))
+                return refuse(path, `${path} must be one of ${field.values.join(', ')}`);
+            return { ok: true, value };
+        case 'string[]': {
             if (!Array.isArray(value) || value.length < field.minItems || value.length > field.maxItems)
-                return { ok: false, problem: { field: name, message: `${name} must list ${field.minItems} to ${field.maxItems} items` } };
+                return refuse(path, `${path} must list ${field.minItems} to ${field.maxItems} items`);
             const seen = new Set();
             for (const [index, item] of value.entries()) {
                 if (typeof item !== 'string' || item.length < field.item.minLength || (field.item.maxLength !== undefined && item.length > field.item.maxLength) || (field.item.pattern !== undefined && !matches(field.item.pattern, item)))
-                    return { ok: false, problem: { field: name, message: `${name}[${index}] is not a valid ${name} entry` } };
+                    return refuse(path, `${path}[${index}] is not a valid ${name} entry`);
                 if (field.uniqueItems && seen.has(item))
-                    return { ok: false, problem: { field: name, message: `${name} must not repeat an entry` } };
+                    return refuse(path, `${path} must not repeat an entry`);
                 seen.add(item);
             }
+            return { ok: true, value };
+        }
+        case 'object[]': {
+            if (!Array.isArray(value) || value.length < field.minItems || value.length > field.maxItems)
+                return refuse(path, `${path} must list ${field.minItems} to ${field.maxItems} items`);
+            const entries = [];
+            for (const [index, item] of value.entries()) {
+                if (item === null || typeof item !== 'object' || Array.isArray(item))
+                    return refuse(path, `${path}[${index}] is not a valid ${name} entry`);
+                const entry = checkFields(operation, `${path}[${index}].`, field.fields, item, false);
+                if (!entry.ok)
+                    return entry;
+                entries.push(entry.value);
+            }
+            return { ok: true, value: entries };
+        }
+        case 'value': {
+            const { types, maxLength, list } = field;
+            if (isScalar(types, maxLength, value) || (list !== undefined && Array.isArray(value) && value.length >= list.minItems && value.length <= list.maxItems && value.every(item => isScalar(list.types, maxLength, item))))
+                return { ok: true, value };
+            const shapes = types.map(type => (type === 'string' && maxLength !== undefined ? `a string of at most ${maxLength} characters` : valueNouns[type][0]));
+            if (list !== undefined)
+                shapes.push(`a list of ${list.minItems} to ${list.maxItems} ${either(list.types.map(type => valueNouns[type][1]))}`);
+            return refuse(path, `${path} must be ${either(shapes)}`);
         }
-        out[name] = value;
     }
-    return { ok: true, input: out };
+}
+/**
+ * Validates one operation's input against the contract and returns it with the
+ * contract's defaults applied. The message names the field and its allowed
+ * range; it is the sentence the platform answers with, so a caller may show it.
+ */
+export function validateIntegrationExecuteInput(operation, input) {
+    const rule = IntegrationExecuteInputRules[operation];
+    if (!rule)
+        return refuse('operation', `${operation} is not a declared integration operation`);
+    const raw = input === undefined ? {} : input;
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return refuse('input', 'input must be an object');
+    const checked = checkFields(operation, '', rule.fields, raw, true);
+    return checked.ok ? { ok: true, input: checked.value } : checked;
 }

package/package.json

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