@isomorph.ai/app-sdk 1.17.0 → 1.19.0

package/dist/index.d.ts

@@ -172,6 +172,49 @@ export interface WarehouseViewReadRequest {
         limit?: number;
     };
 }
+/** One row to append: every key an approved column of the alias; values typed by the catalog, `null` for any column. */
+export type WarehouseAppendRow = Record<string, string | number | boolean | null>;
+/**
+ * Land rows in the warehouse. The resource is an alias IT approved with access `append` (an alias reads or
+ * appends, never both). Up to 500 rows per call; a larger report is several calls, each with its own fresh key.
+ * On a lane without a warehouse binding the rows are validated and answered as a dry run; nothing is written.
+ */
+export interface WarehouseTableAppendRequest {
+    operation: 'warehouse.table.append';
+    resource: string;
+    input: {
+        /** 1 to 500 rows. */
+        rows: WarehouseAppendRow[];
+    };
+    /** A fresh UUID per append, reused only to retry that same append. */
+    idempotencyKey: string;
+}
+/**
+ * The SMS a company-owned number received. The resource is a number alias of a `phone` connection. An app waiting
+ * for a one-time code polls this every few seconds with `since` set to when it asked, and reads the code out of
+ * the message body itself; there is no OTP concept on the platform.
+ */
+export interface PhoneSmsListRequest {
+    operation: 'phone.sms.list';
+    resource: string;
+    input: {
+        /** ISO 8601 instant; only messages received at or after it are returned. */
+        since: string;
+        /** Only messages from this sender id or number, up to 32 characters. */
+        from?: string;
+    };
+}
+/**
+ * The number a phone alias maps to (contracts 0.83.0, ADR 0029). The resource is a number alias of a `phone`
+ * connection, declared like `phone.sms.list`'s; the answer is the E.164 number IT mapped it to, so the app (or an
+ * agent it drives) can type it into a portal that signs in by mobile number. It takes no input: leave `input`
+ * out and the client sends `input: {}`, which the platform requires on the wire.
+ */
+export interface PhoneNumberGetRequest {
+    operation: 'phone.number.get';
+    resource: string;
+    input?: Record<string, never>;
+}
 /** Gmail runs as the signed-in person after their consent. Resources are approved mailbox aliases (`inbox`). */
 export interface GmailThreadListRequest {
     operation: 'gmail.thread.list';
@@ -497,7 +540,7 @@ export interface ServiceRequestResult {
     headers: Record<string, string>;
     body: unknown;
 }
-export type IntegrationRequest = ServiceRequest | SlackChannelHistoryRequest | SlackMessagePostRequest | SlackMessageUpdateRequest | SlackMessageDeleteRequest | SlackDmSendRequest | SlackUserLookupRequest | WarehouseViewReadRequest | GmailThreadListRequest | GmailThreadReadRequest | GmailMessageReadRequest | GmailAttachmentReadRequest | GmailMessageSendRequest | BasecampProjectListRequest | BasecampTodolistListRequest | BasecampTodoListRequest | BasecampTodoCreateRequest | BasecampTodoCompleteRequest | BasecampMessageListRequest | BasecampMessagePostRequest | BasecampCommentListRequest | BasecampCommentPostRequest | BasecampCampfirePostRequest | BasecampPeopleListRequest | SharePointListListRequest | SharePointItemListRequest | SharePointItemCreateRequest | SharePointItemUpdateRequest | SharePointDriveListRequest | SharePointFileListRequest | SharePointFileSearchRequest | SharePointFileReadRequest | SharePointFileUploadRequest;
+export type IntegrationRequest = ServiceRequest | SlackChannelHistoryRequest | SlackMessagePostRequest | SlackMessageUpdateRequest | SlackMessageDeleteRequest | SlackDmSendRequest | SlackUserLookupRequest | WarehouseViewReadRequest | WarehouseTableAppendRequest | PhoneSmsListRequest | PhoneNumberGetRequest | GmailThreadListRequest | GmailThreadReadRequest | GmailMessageReadRequest | GmailAttachmentReadRequest | GmailMessageSendRequest | BasecampProjectListRequest | BasecampTodolistListRequest | BasecampTodoListRequest | BasecampTodoCreateRequest | BasecampTodoCompleteRequest | BasecampMessageListRequest | BasecampMessagePostRequest | BasecampCommentListRequest | BasecampCommentPostRequest | BasecampCampfirePostRequest | BasecampPeopleListRequest | SharePointListListRequest | SharePointItemListRequest | SharePointItemCreateRequest | SharePointItemUpdateRequest | SharePointDriveListRequest | SharePointFileListRequest | SharePointFileSearchRequest | SharePointFileReadRequest | SharePointFileUploadRequest;
 export type IntegrationOperation = IntegrationRequest['operation'];
 export interface SlackMessage {
     id: string;
@@ -534,6 +577,27 @@ export interface WarehouseViewReadResult {
     /** True when more rows matched than `limit`: the rows are incomplete, so never total or average them in code. */
     truncated: boolean;
 }
+export interface WarehouseTableAppendResult {
+    /** How many rows landed (or, on a lane without a warehouse binding, would have). */
+    appended: number;
+    /** The write receipt's id; a retry with the same idempotencyKey answers the same receipt. */
+    jobId: string;
+    /** Present and true when the lane has no warehouse binding: the rows were validated, nothing was written. */
+    dryRun?: boolean;
+}
+export interface PhoneSmsMessage {
+    from: string;
+    body: string;
+    receivedAt: string;
+}
+/** Up to 50 messages received since `since`, newest first. */
+export interface PhoneSmsListResult {
+    messages: PhoneSmsMessage[];
+}
+export interface PhoneNumberGetResult {
+    /** The E.164 number the alias maps to, e.g. `+919876543210`. */
+    number: string;
+}
 export interface GmailThreadSummary {
     id: string;
     messageId: string;
@@ -753,7 +817,7 @@ export interface SharePointFileUploadResult {
     filename: string;
     webUrl: string;
 }
-export type IntegrationResult<R extends IntegrationRequest> = R extends ServiceRequest ? ServiceRequestResult : 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 : R extends BasecampProjectListRequest ? BasecampProjectListResult : R extends BasecampTodolistListRequest ? BasecampTodolistListResult : R extends BasecampTodoListRequest ? BasecampTodoListResult : R extends BasecampMessageListRequest ? BasecampMessageListResult : R extends BasecampCommentListRequest ? BasecampCommentListResult : R extends BasecampPeopleListRequest ? BasecampPeopleListResult : R extends BasecampTodoCreateRequest | BasecampMessagePostRequest | BasecampCommentPostRequest | BasecampCampfirePostRequest ? BasecampRecordingResult : R extends BasecampTodoCompleteRequest ? BasecampTodoCompleteResult : R extends SharePointListListRequest ? SharePointListListResult : R extends SharePointItemListRequest ? SharePointItemListResult : R extends SharePointItemCreateRequest ? SharePointItemCreateResult : R extends SharePointItemUpdateRequest ? SharePointItemUpdateResult : R extends SharePointDriveListRequest ? SharePointDriveListResult : R extends SharePointFileListRequest | SharePointFileSearchRequest ? SharePointFileListResult : R extends SharePointFileReadRequest ? SharePointFileReadResult : R extends SharePointFileUploadRequest ? SharePointFileUploadResult : never;
+export type IntegrationResult<R extends IntegrationRequest> = R extends ServiceRequest ? ServiceRequestResult : R extends SlackChannelHistoryRequest ? SlackChannelHistoryResult : R extends SlackMessagePostRequest | SlackMessageUpdateRequest | SlackMessageDeleteRequest ? SlackMessagePostResult : R extends SlackDmSendRequest ? SlackDmSendResult : R extends SlackUserLookupRequest ? SlackUserLookupResult : R extends WarehouseViewReadRequest ? WarehouseViewReadResult : R extends WarehouseTableAppendRequest ? WarehouseTableAppendResult : R extends PhoneSmsListRequest ? PhoneSmsListResult : R extends PhoneNumberGetRequest ? PhoneNumberGetResult : R extends GmailThreadListRequest ? GmailThreadListResult : R extends GmailThreadReadRequest ? GmailThreadReadResult : R extends GmailMessageReadRequest ? GmailMessageReadResult : R extends GmailAttachmentReadRequest ? GmailAttachmentReadResult : R extends GmailMessageSendRequest ? GmailMessageSendResult : R extends BasecampProjectListRequest ? BasecampProjectListResult : R extends BasecampTodolistListRequest ? BasecampTodolistListResult : R extends BasecampTodoListRequest ? BasecampTodoListResult : R extends BasecampMessageListRequest ? BasecampMessageListResult : R extends BasecampCommentListRequest ? BasecampCommentListResult : R extends BasecampPeopleListRequest ? BasecampPeopleListResult : R extends BasecampTodoCreateRequest | BasecampMessagePostRequest | BasecampCommentPostRequest | BasecampCampfirePostRequest ? BasecampRecordingResult : R extends BasecampTodoCompleteRequest ? BasecampTodoCompleteResult : R extends SharePointListListRequest ? SharePointListListResult : R extends SharePointItemListRequest ? SharePointItemListResult : R extends SharePointItemCreateRequest ? SharePointItemCreateResult : R extends SharePointItemUpdateRequest ? SharePointItemUpdateResult : R extends SharePointDriveListRequest ? SharePointDriveListResult : R extends SharePointFileListRequest | SharePointFileSearchRequest ? SharePointFileListResult : R extends SharePointFileReadRequest ? SharePointFileReadResult : R extends SharePointFileUploadRequest ? SharePointFileUploadResult : never;
 export type IntegrationConnectResult = {
     status: 'connected';
     accountLabel: string;

package/dist/index.js

@@ -30,6 +30,20 @@ function warehouseReadProblem({ columns, aggregates }) {
         return { field: 'columns', message: 'columns may use "*" only as the sole entry' };
     return undefined;
 }
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+// The append rules governance states in prose: 1 to 500 rows per call (a
+// larger report is several calls) and a UUID idempotency key per call.
+// Governance checks the columns and the value types against the catalog.
+function warehouseAppendProblem({ input, idempotencyKey }) {
+    const rows = input?.rows;
+    if (!Array.isArray(rows) || rows.length === 0)
+        return { field: 'rows', message: 'a warehouse append needs 1 to 500 rows' };
+    if (rows.length > 500)
+        return { field: 'rows', message: 'a warehouse append takes at most 500 rows per call; send a larger report as several calls, each with its own idempotencyKey' };
+    if (typeof idempotencyKey !== 'string' || !UUID_PATTERN.test(idempotencyKey))
+        return { field: 'idempotencyKey', message: 'a warehouse append needs a fresh UUID idempotencyKey per call' };
+    return undefined;
+}
 /** 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;
@@ -751,14 +765,18 @@ 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);
-                const problem = !checked.ok ? checked.problem
-                    : request.operation === 'warehouse.view.read' ? warehouseReadProblem(request.input ?? {}) : undefined;
+                const problem = (request.operation === 'warehouse.table.append' ? warehouseAppendProblem(request) : undefined)
+                    ?? (!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: metadata declares which
                 // operations accept `mode`; identity and stray fields are not sent.
-                const { operation, resource, input, idempotencyKey, mode } = request;
+                // phone.number.get takes no input, but the contract keeps `input`
+                // required on the wire (ADR 0029), so an omitted one goes out as {}.
+                const { operation, resource, input: given, idempotencyKey, mode } = request;
+                const input = given === undefined && operation === 'phone.number.get' ? {} : given;
                 return transport.json('/_harbour/integrations/execute', {
                     method: 'POST', body: JSON.stringify({ connection, operation, ...(operation !== 'service.request' ? { resource } : {}), ...(input !== undefined ? { input } : {}), ...(idempotencyKey !== undefined ? { idempotencyKey } : {}), ...(IntegrationOperations[operation]?.declaredMode && mode !== undefined ? { mode } : {}) }),
                 });

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

@@ -63,6 +63,15 @@ export type IntegrationExecuteInputFieldRule = {
     maxProperties: number;
     types: readonly IntegrationExecuteInputRecordValueType[];
     maxLength?: number;
+} | {
+    kind: 'record[]';
+    required: boolean;
+    minItems: number;
+    maxItems: number;
+    minProperties: number;
+    maxProperties: number;
+    types: readonly IntegrationExecuteInputRecordValueType[];
+    maxLength?: number;
 };
 /** The scalar types a `value` input accepts, alone or in its list form. */
 export type IntegrationExecuteInputValueType = 'string' | 'number' | 'boolean';
@@ -771,6 +780,27 @@ export declare const IntegrationExecuteInputRules: {
             };
         };
     };
+    readonly "phone.sms.list": {
+        readonly idempotencyKey: false;
+        readonly fields: {
+            readonly since: {
+                readonly kind: "string";
+                readonly required: true;
+                readonly minLength: 1;
+                readonly pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]{1,9})?(Z|[+-][0-9]{2}:[0-9]{2})$";
+            };
+            readonly from: {
+                readonly kind: "string";
+                readonly required: false;
+                readonly minLength: 0;
+                readonly maxLength: 32;
+            };
+        };
+    };
+    readonly "phone.number.get": {
+        readonly idempotencyKey: false;
+        readonly fields: {};
+    };
     readonly "warehouse.view.read": {
         readonly idempotencyKey: false;
         readonly fields: {
@@ -880,6 +910,21 @@ export declare const IntegrationExecuteInputRules: {
             };
         };
     };
+    readonly "warehouse.table.append": {
+        readonly idempotencyKey: true;
+        readonly fields: {
+            readonly rows: {
+                readonly kind: "record[]";
+                readonly required: true;
+                readonly minItems: 1;
+                readonly maxItems: 500;
+                readonly minProperties: 1;
+                readonly maxProperties: 64;
+                readonly types: readonly ["string", "number", "boolean", "null"];
+                readonly maxLength: 4000;
+            };
+        };
+    };
     readonly "service.request": {
         readonly idempotencyKey: false;
         readonly fields: {

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

@@ -241,6 +241,17 @@ export const IntegrationExecuteInputRules = {
             conflict: { kind: "enum", required: false, values: ["rename", "replace", "fail"], default: "rename" },
         },
     },
+    "phone.sms.list": {
+        idempotencyKey: false,
+        fields: {
+            since: { kind: "string", required: true, minLength: 1, pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]{1,9})?(Z|[+-][0-9]{2}:[0-9]{2})$" },
+            from: { kind: "string", required: false, minLength: 0, maxLength: 32 },
+        },
+    },
+    "phone.number.get": {
+        idempotencyKey: false,
+        fields: {},
+    },
     "warehouse.view.read": {
         idempotencyKey: false,
         fields: {
@@ -263,6 +274,12 @@ export const IntegrationExecuteInputRules = {
             limit: { kind: "integer", required: false, minimum: 1, maximum: 1000, default: 100 },
         },
     },
+    "warehouse.table.append": {
+        idempotencyKey: true,
+        fields: {
+            rows: { kind: "record[]", required: true, minItems: 1, maxItems: 500, minProperties: 1, maxProperties: 64, types: ["string", "number", "boolean", "null"], maxLength: 4000 },
+        },
+    },
     "service.request": {
         idempotencyKey: false,
         fields: {
@@ -337,6 +354,19 @@ function checkFields(operation, prefix, fields, given, nullIsAbsent) {
     }
     return { ok: true, value: out };
 }
+/** One record: a bounded count of free keys, every value one of the record's scalar types. */
+function checkRecord(path, field, value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return refuse(path, `${path} must be a JSON object`);
+    const keys = Object.keys(value);
+    if (keys.length < field.minProperties || keys.length > field.maxProperties)
+        return refuse(path, `${path} must have ${field.minProperties} to ${field.maxProperties} properties`);
+    for (const key of keys) {
+        if (!isScalar(field.types, field.maxLength, value[key]))
+            return refuse(`${path}.${key}`, `${path}.${key} must be ${either(scalarShapes(field.types, field.maxLength))}`);
+    }
+    return { ok: true, value };
+}
 function checkField(operation, path, name, field, value) {
     switch (field.kind) {
         case 'object':
@@ -347,15 +377,17 @@ function checkField(operation, path, name, field, value) {
             if (typeof value !== 'boolean')
                 return refuse(path, `${path} must be a boolean`);
             return { ok: true, value };
-        case 'record': {
-            if (value === null || typeof value !== 'object' || Array.isArray(value))
-                return refuse(path, `${path} must be a JSON object`);
-            const keys = Object.keys(value);
-            if (keys.length < field.minProperties || keys.length > field.maxProperties)
-                return refuse(path, `${path} must have ${field.minProperties} to ${field.maxProperties} properties`);
-            for (const key of keys) {
-                if (!isScalar(field.types, field.maxLength, value[key]))
-                    return refuse(`${path}.${key}`, `${path}.${key} must be ${either(scalarShapes(field.types, field.maxLength))}`);
+        case 'record':
+            return checkRecord(path, field, value);
+        case 'record[]': {
+            if (!Array.isArray(value) || value.length < field.minItems || value.length > field.maxItems)
+                return refuse(path, `${path} must list ${field.minItems} to ${field.maxItems} items`);
+            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 = checkRecord(`${path}[${index}]`, field, item);
+                if (!entry.ok)
+                    return entry;
             }
             return { ok: true, value };
         }

package/dist/integration-operations.d.ts

@@ -217,6 +217,20 @@ export declare const IntegrationOperations: {
         readonly declaredMode: false;
         readonly idempotencyKey: true;
     };
+    readonly "phone.sms.list": {
+        readonly kind: "saas";
+        readonly identities: readonly ["app"];
+        readonly readOnly: true;
+        readonly declaredMode: false;
+        readonly idempotencyKey: false;
+    };
+    readonly "phone.number.get": {
+        readonly kind: "saas";
+        readonly identities: readonly ["app"];
+        readonly readOnly: true;
+        readonly declaredMode: false;
+        readonly idempotencyKey: false;
+    };
     readonly "warehouse.view.read": {
         readonly kind: "database";
         readonly identities: readonly ["app"];
@@ -224,6 +238,13 @@ export declare const IntegrationOperations: {
         readonly declaredMode: false;
         readonly idempotencyKey: false;
     };
+    readonly "warehouse.table.append": {
+        readonly kind: "database";
+        readonly identities: readonly ["app"];
+        readonly readOnly: false;
+        readonly declaredMode: false;
+        readonly idempotencyKey: true;
+    };
     readonly "service.request": {
         readonly kind: "service";
         readonly identities: readonly ["app"];

package/dist/integration-operations.js

@@ -285,6 +285,24 @@ export const IntegrationOperations = {
         "declaredMode": false,
         "idempotencyKey": true
     },
+    "phone.sms.list": {
+        "kind": "saas",
+        "identities": [
+            "app"
+        ],
+        "readOnly": true,
+        "declaredMode": false,
+        "idempotencyKey": false
+    },
+    "phone.number.get": {
+        "kind": "saas",
+        "identities": [
+            "app"
+        ],
+        "readOnly": true,
+        "declaredMode": false,
+        "idempotencyKey": false
+    },
     "warehouse.view.read": {
         "kind": "database",
         "identities": [
@@ -294,6 +312,15 @@ export const IntegrationOperations = {
         "declaredMode": false,
         "idempotencyKey": false
     },
+    "warehouse.table.append": {
+        "kind": "database",
+        "identities": [
+            "app"
+        ],
+        "readOnly": false,
+        "declaredMode": false,
+        "idempotencyKey": true
+    },
     "service.request": {
         "kind": "service",
         "identities": [

package/package.json

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