@fourier-labs/harbour-contracts 0.72.0 → 0.74.0

package/gen-ts/data-grant-v2.ts

@@ -30,7 +30,7 @@ export interface DataGrantV2 {
    * Whose authority an operation runs under. Fixed per operation, except the declared-mode Slack operations (slack.message.post; since 0.71.0 also slack.channel.history, slack.message.update, slack.message.delete): declared per app for the access request, and named per call among the app's approved modes (execute request `mode`, 0.55.0).
    */
   mode: 'app' | 'user';
-  kind: 'saas' | 'database';
+  kind: 'saas' | 'database' | 'service';
   status: DataGrantV2Status;
   /**
    * Approved operations; each must match this grant's mode. Empty until the first approval. At most the eleven SaaS operations (0.71.0); a database grant holds one.
@@ -50,6 +50,7 @@ export interface DataGrantV2 {
     | 'gmail.message.send'
     | 'gmail.attachment.read'
     | 'warehouse.view.read'
+    | 'service.request'
   )[];
   /**
    * Approved logical resources. Never inherited by wildcard. Empty until the first approval.

package/gen-ts/data-source.ts

@@ -2,9 +2,9 @@
 // Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
 
 /**
- * Closed connector set for the Data-Access MVP.
+ * Closed connector set for the Data-Access MVP. trino (0.74.0): Trino/Presto-compatible engines (Trino, Presto, Starburst, Galaxy) over the Trino HTTP statement protocol; the endpoint reuses host, port and database (as the Trino catalog) with no connector-specific fields.
  */
-export type DataSourceConnector = 'postgres' | 'redshift' | 'bigquery' | 'databricks' | 'mysql';
+export type DataSourceConnector = 'postgres' | 'redshift' | 'bigquery' | 'databricks' | 'mysql' | 'trino';
 /**
  * byo = admin brought existing infrastructure; harbour_managed = Isomorph provisioned it.
  */
@@ -54,6 +54,13 @@ export interface DataSource {
    */
   allowValidation?: boolean;
   status: DataSourceStatus;
+  /**
+   * 0.74.0: per-environment copies of the source. A read for an environment that has a copy here uses that copy's endpoint and credentialRef; production always uses the top-level endpoint and credentialRef. A development read with no development copy is answered from the app's sample rows (integration-execute-request.sampleRows), never from the source; a preview read with no preview copy uses the production endpoint. A laptop never reads the production endpoint.
+   */
+  environments?: {
+    development?: DataSourceEnvironmentCopy;
+    preview?: DataSourceEnvironmentCopy;
+  };
 }
 /**
  * Connector endpoint coordinates. host is always present; database vs project/workspace depends on the connector family.
@@ -80,3 +87,13 @@ export interface DataSourceEndpoint {
    */
   workspace?: string;
 }
+/**
+ * One environment's copy of a source: the same endpoint and credentialRef shapes as the top-level fields, for the same connector.
+ */
+export interface DataSourceEnvironmentCopy {
+  endpoint: DataSourceEndpoint;
+  /**
+   * secretref URI naming the platform-held credential for this copy. The referenced value never crosses this boundary.
+   */
+  credentialRef: string;
+}

package/gen-ts/integration-error-details.ts

@@ -7,7 +7,7 @@
 export type IntegrationErrorCategory =
   'AUTH_REQUIRED' | 'FORBIDDEN' | 'NOT_FOUND' | 'CONFLICT' | 'VALIDATION_FAILED' | 'RATE_LIMITED' | 'UNAVAILABLE';
 /**
- * Stable reason codes. SEND_OUTCOME_UNKNOWN: dispatch happened but the outcome is unknown; never re-post automatically. SEND_KEY_REUSED: the idempotency key was seen with a different payload or subject. GRANT_DENIED: IT denied the request. TOKEN_REFRESH_PENDING: another call holds the refresh lease; retry shortly. REQUEST_PENDING: a different request for this grant is still open. INPUT_INVALID: the operation input failed its bounds. IDEMPOTENCY_KEY_REQUIRED: a send without a UUID idempotencyKey. SEND_IN_PROGRESS: a retry arrived while the first send of that key is still running. CONNECTION_NOT_FOUND / APP_NOT_FOUND / GRANT_NOT_FOUND: the named record does not exist. AUTH_REQUIRED: no verified caller. UNAVAILABLE: the governance dependency (store, provider seam) is unreachable. MODE_NOT_GRANTED (403 FORBIDDEN, 0.55.0): a slack.message.post named a mode (app or user) IT has not approved for this app; the post is never served under the other mode. MODE_REQUIRED (400 VALIDATION_FAILED, 0.55.0): the app holds approved grants for both modes and the post named neither.
+ * Stable reason codes. SEND_OUTCOME_UNKNOWN: dispatch happened but the outcome is unknown; never re-post automatically. SEND_KEY_REUSED: the idempotency key was seen with a different payload or subject. GRANT_DENIED: IT denied the request. TOKEN_REFRESH_PENDING: another call holds the refresh lease; retry shortly. REQUEST_PENDING: a different request for this grant is still open. INPUT_INVALID: the operation input failed its bounds. IDEMPOTENCY_KEY_REQUIRED: a send without a UUID idempotencyKey. SEND_IN_PROGRESS: a retry arrived while the first send of that key is still running. CONNECTION_NOT_FOUND / APP_NOT_FOUND / GRANT_NOT_FOUND: the named record does not exist. AUTH_REQUIRED: no verified caller. UNAVAILABLE: the governance dependency (store, provider seam) is unreachable. MODE_NOT_GRANTED (403 FORBIDDEN, 0.55.0): a slack.message.post named a mode (app or user) IT has not approved for this app; the post is never served under the other mode. MODE_REQUIRED (400 VALIDATION_FAILED, 0.55.0): the app holds approved grants for both modes and the post named neither. SAMPLE_ROWS_NOT_ALLOWED (400 VALIDATION_FAILED, 0.74.0): an execute request carried sampleRows on any route but the development one. A sample value that does not parse as the column's recorded type is INPUT_INVALID, naming the column and the row.
  */
 export type IntegrationErrorCode =
   | 'USER_CONNECTION_REQUIRED'
@@ -39,7 +39,8 @@ export type IntegrationErrorCode =
   | 'AUTH_REQUIRED'
   | 'UNAVAILABLE'
   | 'MODE_NOT_GRANTED'
-  | 'MODE_REQUIRED';
+  | 'MODE_REQUIRED'
+  | 'SAMPLE_ROWS_NOT_ALLOWED';
 
 /**
  * The `error` member of an integration failure response `{error, requestId}` on the execute/connect routes; the SDK maps it onto IsomorphError(category, message, details). `category` is the app-SDK IsomorphErrorCategory (not the deployment pipeline's dot-path error-category registry), with the HTTP status fixed per category: 401 AUTH_REQUIRED, 403 FORBIDDEN (denied/revoked/expired), 404 NOT_FOUND (unknown app/connection/resource), 409 CONFLICT (pending provisioning/consent/concurrent request), 400 or 413 VALIDATION_FAILED (invalid input / size overflow), 429 RATE_LIMITED (+ Retry-After header), 503 UNAVAILABLE. `details.code` is the closed stable reason set; `message` is human-facing and never carries provider error bodies, tokens or SQL.

package/gen-ts/integration-execute-input-rules.ts

@@ -9,6 +9,7 @@
  * same message wherever it is made.
  */
 export type IntegrationExecuteInputFieldRule =
+  | { kind: 'object'; required: boolean }
   | { kind: 'integer'; required: boolean; minimum: number; maximum: number; default?: number }
   | { kind: 'string'; required: boolean; minLength: number; maxLength?: number; pattern?: string }
   | { kind: 'string[]'; required: boolean; minItems: number; maxItems: number; uniqueItems: boolean; item: { minLength: number; maxLength?: number; pattern?: string }; default?: readonly string[] }
@@ -134,6 +135,17 @@ export const IntegrationExecuteInputRules = {
       limit: { kind: "integer", required: false, minimum: 1, maximum: 1000, default: 100 },
     },
   },
+  "service.request": {
+    idempotencyKey: false,
+    fields: {
+      method: { kind: "enum", required: true, values: ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"] },
+      path: { kind: "string", required: true, minLength: 0, maxLength: 16384 },
+      pathParams: { kind: "object", required: false },
+      query: { kind: "object", required: false },
+      headers: { kind: "object", required: false },
+      body: { kind: "object", required: false },
+    },
+  },
 } as const satisfies Record<string, IntegrationExecuteOperationRule>;
 
 export type IntegrationExecuteOperation = keyof typeof IntegrationExecuteInputRules;
@@ -194,6 +206,9 @@ function checkFields(operation: string, prefix: string, fields: Readonly<Record<
 
 function checkField(operation: string, path: string, name: string, field: IntegrationExecuteInputFieldRule, value: unknown): { ok: true; value: unknown } | Refusal {
   switch (field.kind) {
+    case 'object':
+      if (value === null || typeof value !== 'object' || Array.isArray(value)) return refuse(path, `${path} must be a JSON object`);
+      return { ok: true, value };
     case 'integer':
       if (typeof value !== 'number' || !Number.isInteger(value) || value < field.minimum || value > field.maximum) return refuse(path, `${path} must be an integer between ${field.minimum} and ${field.maximum}`);
       return { ok: true, value };

package/gen-ts/integration-execute-request.ts

@@ -24,11 +24,12 @@ export type IntegrationExecuteRequest = {
     | 'gmail.message.read'
     | 'gmail.message.send'
     | 'gmail.attachment.read'
-    | 'warehouse.view.read';
+    | 'warehouse.view.read'
+    | 'service.request';
   /**
    * Tenant-wide logical alias of a connection (governance sourceId) or of a resource under it.
    */
-  resource: string;
+  resource?: string;
   input: {
     /**
      * Read operations: how many items to return; the per-operation then-block sets the real ceiling (100 for slack.channel.history, 50 for gmail.thread.list, 1000 for warehouse.view.read) and the default.
@@ -142,6 +143,20 @@ export type IntegrationExecuteRequest = {
      * @maxItems 8
      */
     orderBy?: WarehouseOrder[];
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+    path?: string;
+    pathParams?: {
+      [k: string]: unknown;
+    };
+    query?: {
+      [k: string]: unknown;
+    };
+    headers?: {
+      [k: string]: unknown;
+    };
+    body?: {
+      [k: string]: unknown;
+    };
   };
   /**
    * UUID of one explicit Send action; required for slack.message.post and gmail.message.send only. The same key with the same payload and subject returns the recorded outcome for seven days.
@@ -151,6 +166,14 @@ export type IntegrationExecuteRequest = {
    * The declared-mode Slack operations only (slack.message.post since 0.55.0; slack.channel.history, slack.message.update and slack.message.delete since 0.71.0): which of the app's IT-approved modes this call runs under — app (the company's Slack app; a post goes out under the grant's per-app name and the footer) or user (the signed-in person, after their consent; no name, no footer). Required when the app holds approved grants for both modes (else MODE_REQUIRED); may be omitted when it holds one, which is then used. A named mode without an approved grant is refused with MODE_NOT_GRANTED; governance never falls back to the other mode. Every other operation's mode is fixed, so the field is refused there.
    */
   mode?: 'app' | 'user';
+  /**
+   * Development only (0.74.0). Rows the kit dev runtime attaches for the resource being read, from the sample-row file the agent wrote into the app's .isomorph/ folder. Governance serves them for a development warehouse.view.read when the source has no development copy (data-source.environments.development): it parses each value by the resource's recorded column type and refuses a value that does not parse, naming the column and the row. The field is refused with SAMPLE_ROWS_NOT_ALLOWED on any route but the development one, so a preview or production read never carries made-up data. Not part of the per-operation input rules; the dev runtime adds it beside the app's request.
+   *
+   * @maxItems 50
+   */
+  sampleRows?: {
+    [k: string]: string | number | boolean | null;
+  }[];
 };
 /**
  * One bare email address (no display name).

package/gen-ts/integration-execute-result.ts

@@ -46,6 +46,10 @@ export type IntegrationExecuteResult = {
    * gmail.message.read: the text was cut at 16 KiB. warehouse.view.read (0.70.0): more rows matched than the read's limit, so `rows` is incomplete.
    */
   truncated?: boolean;
+  /**
+   * warehouse.view.read (0.74.0): true when `rows` came from the app's sample rows (integration-execute-request.sampleRows) because the development read had no development copy of the source; the rows were never read from the source. Absent or false: the rows came from the source.
+   */
+  sample?: boolean;
   /**
    * gmail.message.read (0.71.0): the message's attachments, without their bytes.
    *
@@ -74,6 +78,11 @@ export type IntegrationExecuteResult = {
   rows?: {
     [k: string]: unknown;
   }[];
+  status?: number;
+  headers?: {
+    [k: string]: string;
+  };
+  body?: unknown;
 };
 
 export interface ChannelMessage {

package/gen-ts/integration-operations.ts

@@ -114,5 +114,14 @@ export const IntegrationOperations = {
     "readOnly": true,
     "declaredMode": false,
     "idempotencyKey": false
+  },
+  "service.request": {
+    "kind": "service",
+    "identities": [
+      "app"
+    ],
+    "readOnly": false,
+    "declaredMode": false,
+    "idempotencyKey": false
   }
 } as const;

package/gen-ts/saas-connection.ts

@@ -73,6 +73,7 @@ export interface SaasConnection {
     | 'gmail.message.send'
     | 'gmail.attachment.read'
     | 'warehouse.view.read'
+    | 'service.request'
   )[];
   developmentPreapproval: DevelopmentPreapproval;
   oauthClient?: SaasOauthClient;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fourier-labs/harbour-contracts",
-  "version": "0.72.0",
+  "version": "0.74.0",
   "description": "Single source of truth for every data shape that crosses a boundary between Isomorph components.",
   "license": "UNLICENSED",
   "private": false,