@isomorph.ai/app-sdk 1.6.2 → 1.7.0

package/dist/index.d.ts

@@ -49,12 +49,46 @@ export interface SlackMessagePostRequest {
      */
     mode?: 'app' | 'user';
 }
+/**
+ * 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;
     };
@@ -112,6 +146,8 @@ export interface SlackMessagePostResult {
 }
 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;

package/dist/index.js

@@ -16,6 +16,18 @@ 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 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,11 +671,10 @@ 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

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

@@ -28,7 +28,30 @@ export type IntegrationExecuteInputFieldRule = {
         maxLength?: number;
         pattern?: 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>;
@@ -144,7 +167,7 @@ export declare const IntegrationExecuteInputRules: {
         readonly fields: {
             readonly columns: {
                 readonly kind: "string[]";
-                readonly required: true;
+                readonly required: false;
                 readonly minItems: 1;
                 readonly maxItems: 32;
                 readonly uniqueItems: false;
@@ -153,6 +176,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

@@ -39,7 +39,22 @@ export const IntegrationExecuteInputRules = {
     "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 +75,111 @@ 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;
             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.7.0",
   "type": "module",
   "repository": {
     "type": "git",