@fourier-labs/harbour-contracts 0.46.0 → 0.50.0

package/dist/gen-ts/saas-connection.d.ts

@@ -1,59 +1,98 @@
+/**
+ * Slack carries an installation and a channel map; Gmail is user-consent only and read-only.
+ */
+export type SaasProvider = 'slack' | 'gmail';
 /**
  * DISABLED stops every app call immediately (details.code CONNECTION_DISABLED).
  */
 export type SaasConnectionStatus = 'ACTIVE' | 'DISABLED';
+export type SaasInstallationStatus = 'installed' | 'reconnect_required' | 'revoked';
+/**
+ */
 export type InstallationName = string;
 /**
- * Tenant-wide SaaS connection record (control table sk SAASCONN#<sourceId>, same tenant partition as database sources; alias uniqueness is enforced across both). IT maps each environment to a provider installation and logical channel aliases to channel IDs; apps only ever see the aliases. Contains references, never secrets: the client secret lives in Secrets Manager under clientSecretRef and installation tokens under their own token records.
+ * Tenant-wide SaaS connection record (control table sk SAASCONN#<sourceId>, same tenant partition as database sources; alias uniqueness is enforced across both). One connection per tenant and provider: a single bot installation of the platform-owned provider app and a single logical channel map shared by every app environment (grants, requests and user consent links stay per environment). A Gmail connection has neither installation nor channels: user consent is the only step and its one resource is the fixed `inbox` alias. Contains references, never secrets: installation tokens live under their own token records. The pre-T25 per-environment shape (`clientId`, `clientSecretRef`, `environments`, `installations`) is deprecated: the control plane normalises such a stored record on read and never writes it.
  */
 export interface SaasConnection {
+    schema: 'harbour.saas-connection/1.0';
+    tenantId: string;
     /**
      * Tenant-wide logical alias of a connection (governance sourceId) or of a resource under it.
      */
     sourceId: string;
     kind: 'saas';
-    provider: 'slack';
+    provider: SaasProvider;
     displayName: string;
     status: SaasConnectionStatus;
     /**
      * Optimistic-concurrency version; every write is conditional on it.
      */
     version: number;
-    clientId: string;
+    installation?: SaasInstallation;
     /**
-     * secretref://tenant/{tenantId}/saas/{sourceId}/client
+     * Logical channel alias -> provider channel ID, shared by every environment. Always empty for Gmail.
      */
-    clientSecretRef?: string;
-    environments: {
-        development?: SaasEnvironmentMapping;
-        preview?: SaasEnvironmentMapping;
-        production?: SaasEnvironmentMapping;
+    channels: {
+        /**
+         * Provider channel ID; only public, non-archived channels are valid.
+         */
+        [k: string]: string;
     };
     /**
-     * Operations IT allows apps to request on this connection.
+     * Operations IT allows apps to request on this connection: the provider's own SaaS operations (Slack: slack.channel.history, slack.message.post; Gmail: gmail.thread.list, gmail.message.read, gmail.message.send). Never warehouse.view.read.
      *
      * @minItems 1
-     * @maxItems 2
+     * @maxItems 5
      */
-    operations: ('slack.channel.history' | 'slack.message.post')[];
+    operations: ('slack.channel.history' | 'slack.message.post' | 'gmail.thread.list' | 'gmail.message.read' | 'gmail.message.send' | 'warehouse.view.read')[];
     developmentPreapproval: DevelopmentPreapproval;
     /**
-     * Provider installations keyed by the installation name environments point at.
+     * Lower-cased builder emails excluded from development preapproval.
+     *
+     * @maxItems 256
+     */
+    blockedDevelopmentBuilders?: string[];
+    createdAt: string;
+    updatedAt: string;
+    /**
+     * @deprecated
+     * Deprecated (pre-T25 tenant-owned provider client). Dropped on read; never written.
+     */
+    clientId?: string;
+    /**
+     * @deprecated
+     * Deprecated (pre-T25 tenant-owned provider client secret reference). Dropped on read; never written.
+     */
+    clientSecretRef?: string;
+    /**
+     * @deprecated
+     * Deprecated pre-T25 per-environment mapping. On read the development entry's channels become `channels`; never written.
+     */
+    environments?: {
+        development?: SaasEnvironmentMapping;
+        preview?: SaasEnvironmentMapping;
+        production?: SaasEnvironmentMapping;
+    };
+    /**
+     * @deprecated
+     * Deprecated pre-T25 named installations. On read the `nonprod` entry (or the development mapping's) becomes `installation`; never written.
      */
     installations?: {
-        [k: string]: SaasInstallation;
+        [k: string]: LegacySaasInstallation;
     };
-    createdAt?: string;
-    updatedAt?: string;
 }
-export interface SaasEnvironmentMapping {
-    installation: InstallationName;
-    channels: {
-        /**
-         * Provider channel ID; only public, non-archived channels are valid.
-         */
-        [k: string]: string;
-    };
+/**
+ * The one bot installation of the platform-owned provider app in this tenant's workspace.
+ */
+export interface SaasInstallation {
+    tokenRecordId: string;
+    workspaceId: string;
+    /**
+     * Empty only for a legacy record normalised without one.
+     */
+    botUserId: string;
+    status: SaasInstallationStatus;
+    installedAt: string;
 }
 export interface DevelopmentPreapproval {
     /**
@@ -65,9 +104,21 @@ export interface DevelopmentPreapproval {
      */
     hours: number;
 }
-export interface SaasInstallation {
-    tokenRecordId: string;
-    workspaceId: string;
-    botUserId: string;
-    status: 'ACTIVE' | 'RECONNECT_REQUIRED' | 'REVOKED';
+/**
+ * @deprecated
+ */
+export interface SaasEnvironmentMapping {
+    installation: InstallationName;
+    channels: {
+        [k: string]: string;
+    };
+}
+/**
+ * @deprecated
+ */
+export interface LegacySaasInstallation {
+    tokenRecordId?: string;
+    workspaceId?: string;
+    botUserId?: string;
+    status?: 'ACTIVE' | 'RECONNECT_REQUIRED' | 'REVOKED';
 }

package/dist/gen-ts/transform-report.d.ts

@@ -3,6 +3,8 @@
  */
 export type TransformReport = {
     /**
+     * Optional self-report of the playbooks the agent says it applied. A claim about its own behaviour is not evidence, so nothing validates it; a deployable report may omit it, and one that still carries it stays valid.
+     *
      * @minItems 1
      */
     applied_playbooks?: string[];

package/dist/gen-ts/well-defined-app-manifest.d.ts

@@ -15,6 +15,7 @@ export type Workload = {
  */
 export type Command = string[];
 export type ResourceProfile = 'standard' | 'memory-1g' | 'memory-2g';
+export type Capability = 'data' | 'files' | 'actions' | 'realtime' | 'telemetry';
 /**
  * Versioned provisioning input emitted by Harbour Transform. It describes runtime wiring and workload lifecycle only; PostgreSQL grants and RLS remain the database authorization authority.
  */
@@ -33,6 +34,17 @@ export interface WellDefinedAppManifest {
      * @maxItems 128
      */
     bindings: WorkloadBinding[];
+    /**
+     * Optional language runtime the application container is built on, spelled exactly as transform-report.application.runtime does (nodejs22, python3.11). Optional so a manifest written before the producer emits it still validates.
+     */
+    runtime?: string;
+    /**
+     * Optional declaration of the Harbour browser capabilities the application uses. Same closed set as the app-capabilities document; this is the declaration, not a source scan.
+     *
+     * @maxItems 5
+     */
+    capabilities?: Capability[];
+    routeAuth?: RouteAuth;
 }
 export interface QueueConsumer {
     logicalName: string;
@@ -64,3 +76,22 @@ export interface WorkloadBinding {
      */
     reference?: string;
 }
+/**
+ * Optional method/path authentication policy. Omitted means every route requires Harbour SSO, the same default the policy states explicitly.
+ */
+export interface RouteAuth {
+    default: 'sso_required';
+    /**
+     * @maxItems 64
+     */
+    public: PublicRoute[];
+}
+export interface PublicRoute {
+    path: string;
+    /**
+     * @minItems 1
+     * @maxItems 7
+     */
+    methods: ('GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS')[];
+    mode: 'application_authorized';
+}

package/dist/resolver/index.d.ts

@@ -136,7 +136,13 @@ export declare function canonicalJson(value: unknown): string;
  * to compile until someone states its merge rules. A `Pick<>` here previously
  * let a seventh family parse, store, and enter the snapshot digest while being
  * silently dropped from the effective policy. */
-type AiPolicySnapshotIdentity = "schema" | "scope" | "revision" | "publishedAt" | "contentDigest" | "baselineDigest" | "classificationMinimum";
+/** `assignments` sits here with `classificationMinimum` for the same reason:
+ * both are scope-LEVEL statements resolution consumes directly from the
+ * application snapshot (the classification raises the floor; the assignments
+ * select among the merged families by name), not per-entry families the
+ * tenant merge narrows. Excluding them keeps `SCOPE_FAMILY_MERGES` a registry
+ * of genuine family merges. */
+type AiPolicySnapshotIdentity = "schema" | "scope" | "revision" | "publishedAt" | "contentDigest" | "baselineDigest" | "classificationMinimum" | "assignments";
 /** The resource families a scope snapshot contributes to resolution. */
 export type AiScopePolicySet = Omit<AiPolicySnapshot, AiPolicySnapshotIdentity>;
 /** The merged control set every later layer narrowed but could not weaken. */

package/gen-ts/ai-policy-snapshot.ts

@@ -86,6 +86,7 @@ export interface AiPolicySnapshot {
    */
   limits: AiPolicyLimit[];
   retention: AiPolicyRetention;
+  assignments?: AiPolicyAssignments;
 }
 export interface AiPolicyClassificationMinimum {
   classification: 'Green' | 'Yellow' | 'Orange' | 'Red';
@@ -204,3 +205,21 @@ export interface AiPolicyRetention {
    */
   revealRoles: AiPolicyIdentifier[];
 }
+/**
+ * Application-scope only: the tenant resources this application/environment snapshot pins BY NAME (D-8/D-9). A scope without assignments keeps the default rule (the whole merge-narrowed set is the assignment). Every name must exist in the same snapshot's own family; empty route and budget selections are legal (tenant-scoped limits bind regardless).
+ */
+export interface AiPolicyAssignments {
+  /**
+   * @maxItems 256
+   */
+  routes: AiPolicyIdentifier[];
+  /**
+   * @minItems 1
+   * @maxItems 256
+   */
+  policies: AiPolicyIdentifier[];
+  /**
+   * @maxItems 128
+   */
+  budgets: AiPolicyIdentifier[];
+}

package/gen-ts/ai-runtime-contract.ts

@@ -53,7 +53,7 @@ export interface AiRuntimeContract {
 export interface AiConfigurationMappingDescriptor {
   mappingId: string;
   version: string;
-  protocol: 'openai-chat';
+  protocol: 'openai-chat' | 'openai-images';
   providerId: string;
   apiKeyEnvironmentName: string;
   baseUrlEnvironmentName: string;

package/gen-ts/ai-trace-event.ts

@@ -20,7 +20,10 @@ export type AiTraceEvent = {
   provider?: 'openai' | 'anthropic' | 'gemini' | 'openrouter' | 'deepseek' | 'elevenlabs' | 'deepgram' | 'higgsfield';
   providerModel?: string;
   outcome: 'succeeded' | 'blocked' | 'failed' | 'cancelled';
-  usage?: AiTraceUsage;
+  /**
+   * Trace-level provider-reported usage, or null when no attempt reported any (the reservation stays committed rather than reconciled against invented zero usage).
+   */
+  usage?: AiTraceUsage | null;
   priceRevision?: AiTraceIdentifier;
   costMicroUsd: number;
   latencyMs: number;

package/gen-ts/app-integrations-declaration.ts

@@ -11,9 +11,13 @@ export type IntegrationAlias = string;
  * @maxItems 64
  */
 export type ResourceNames = IntegrationAlias[];
+/**
+ * A plain column identifier of a warehouse view.
+ */
+export type ColumnName = string;
 
 /**
- * Committed `.harbour/integrations.json`: the app's declared use of tenant-wide integration connections. Keys are logical connection aliases (the governance sourceId); resources are logical names (Slack channel alias, warehouse view name), never IDs, tokens or URLs. The operation set is closed (three operations) and each operation carries a fixed identity mode: slack.channel.history=user, slack.message.post=app, warehouse.view.read=app. A `saas` connection may declare only the Slack operations and a `database` connection only warehouse.view.read. This file also owns the shared IntegrationOperation / IntegrationIdentityMode / IntegrationEnvironment / IntegrationConnectionKind enums referenced by the other integration schemas.
+ * Committed `.harbour/integrations.json`: the app's declared use of tenant-wide integration connections. Keys are logical connection aliases (the governance sourceId); resources are logical names (Slack channel alias, warehouse view name), never IDs, tokens or URLs. The operation set is closed (five operations) and each operation carries a fixed identity mode: slack.channel.history=user, slack.message.post=app, gmail.thread.list=user, gmail.message.read=user, warehouse.view.read=app. A `saas` connection may declare only the Slack and Gmail operations and a `database` connection only warehouse.view.read. Gmail is read-only and user-mode only; its single resource is the fixed `inbox` alias. This file also owns the shared IntegrationOperation / IntegrationIdentityMode / IntegrationEnvironment / IntegrationConnectionKind enums referenced by the other integration schemas.
  */
 export interface AppIntegrationsDeclaration {
   schema: 'harbour.app-integrations/2.0';
@@ -26,6 +30,9 @@ export interface DeclaredConnection {
   operations: {
     'slack.channel.history'?: UserModeChannelOperation;
     'slack.message.post'?: AppModeChannelOperation;
+    'gmail.thread.list'?: UserModeChannelOperation;
+    'gmail.message.read'?: UserModeChannelOperation;
+    'gmail.message.send'?: UserModeChannelOperation;
     'warehouse.view.read'?: AppModeViewOperation;
   };
 }
@@ -48,5 +55,5 @@ export interface ViewResource {
    * @minItems 1
    * @maxItems 32
    */
-  columns: string[];
+  columns: ColumnName[];
 }

package/gen-ts/contract-release.ts

@@ -1,10 +1,10 @@
 /* eslint-disable */
 // Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
 
-export const ContractRepositoryVersion = "0.46.0.0" as const;
-export const ContractPublishVersion = "0.46.0" as const;
-export const ContractPublishTag = "v0.46.0" as const;
-export const ContractSchemasDigest = "sha256:2d5d65ab7cf2f575de0f93cc3b096b2ac6505e5f505653c65b6a472f219fbbe2" as const;
+export const ContractRepositoryVersion = "0.50.0.0" as const;
+export const ContractPublishVersion = "0.50.0" as const;
+export const ContractPublishTag = "v0.50.0" as const;
+export const ContractSchemasDigest = "sha256:c77dcbf9daad9c66141e9cb8215760a098afd1bf3e665e247f6a4df8db2bcd4f" as const;
 export const ContractAiFixturesDigest = "sha256:edac31c92e146ca1c40130f2fb5649db82e24b8cd1ac758153b90612052fddb6" as const;
-export const ContractGeneratedGoDigest = "sha256:529c21544ed916b2d50854f31acd933d0b5b2f9251465375bfe0338fb11351e5" as const;
-export const ContractGeneratedTypeScriptDigest = "sha256:7ebe33c88dcb7e20024201518b0da941b49e25f8ae4324cb15308cb450bf2422" as const;
+export const ContractGeneratedGoDigest = "sha256:545d8b23ab712e75285ea962851bcf8f08f5baeb018bea6f7ba4e1ca2fe80ed0" as const;
+export const ContractGeneratedTypeScriptDigest = "sha256:1e47c3956a3468531690693ff50ff7947a798af01e01d25659401f727cb934c4" as const;

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

@@ -9,46 +9,58 @@ export type DataGrantV2Status = 'REQUESTED' | 'GRANTED' | 'DENIED' | 'REVOKED';
  * Provider-side work for the current approved scope (credential mint, cleanup, installation check).
  */
 export type DataGrantV2ProvisioningStatus = 'NONE' | 'PENDING' | 'FAILED' | 'DONE';
+export type DataGrantV2CleanupStatus = 'PENDING' | 'FAILED' | 'DONE';
 
 /**
- * An app's integration grant for one connection, environment and identity mode (control table sk APP#<appId>#IGRANT#<environment>#<sourceId>#<mode>; grantId = base64url(JSON ["v2",appId,environment,sourceId,mode])). Additive to the legacy DataGrant (data-grant.schema.json), which is never consulted by v2 paths. Expiry is enforced from UTC time on every call and SDK calls never extend it. Status edges live in x-transitions; DENIED and REVOKED are terminal (a regrant after revocation is a new REQUESTED record once cleanup is DONE). Database grants add credentialRef/mintedPrincipal, SaaS grants add installation; both hold references only.
+ * An app's integration grant for one connection, environment and identity mode (control table sk APP#<appId>#IGRANT#<environment>#<sourceId>#<mode>; grantId = base64url(JSON ["v2",appId,environment,sourceId,mode])). Additive to the legacy DataGrant (data-grant.schema.json), which is never consulted by v2 paths. A fresh REQUESTED record carries empty `operations`/`resources` until the attached request is approved; approved resources are structured `{name, columns?}` entries (a Slack channel alias, the fixed Gmail `inbox` alias, or a warehouse view alias with its approved columns). Expiry is enforced from UTC time on every call and SDK calls never extend it; `expiredAt` is stamped by the recovery sweep afterwards. Status edges live in x-transitions; DENIED and REVOKED are terminal (a regrant after revocation is a new REQUESTED record once cleanup is DONE). Database grants add credentialRef/mintedPrincipal; both hold references only. `identityMode` and `installation` are the deprecated 0.45.0 spellings: the record carries `mode`, and a SaaS grant runs on the connection's single installation.
  */
 export interface DataGrantV2 {
   schema: 'harbour.data-grant/2.0';
+  tenantId: string;
   appId: string;
-  /**
-   * Tenant-wide logical alias of a connection (governance sourceId) or of a resource under it.
-   */
-  sourceId: string;
-  kind: 'saas' | 'database';
   /**
    * development is the CLI/local kit; preview and production are hosted.
    */
   environment: 'development' | 'preview' | 'production';
+  /**
+   * Tenant-wide logical alias of a connection (governance sourceId) or of a resource under it.
+   */
+  sourceId: string;
   /**
    * Whose authority an operation runs under. Fixed per operation; callers never choose it.
    */
-  identityMode: 'app' | 'user';
+  mode: 'app' | 'user';
+  kind: 'saas' | 'database';
   status: DataGrantV2Status;
   /**
-   * Approved operations; each must match this grant's identityMode.
+   * Approved operations; each must match this grant's mode. Empty until the first approval.
    *
-   * @minItems 1
-   * @maxItems 3
+   * @maxItems 5
    */
-  operations: ('slack.channel.history' | 'slack.message.post' | 'warehouse.view.read')[];
+  operations: (
+    | 'slack.channel.history'
+    | 'slack.message.post'
+    | 'gmail.thread.list'
+    | 'gmail.message.read'
+    | 'gmail.message.send'
+    | 'warehouse.view.read'
+  )[];
   /**
-   * Approved logical resource names (channel aliases or view names). Never inherited by wildcard.
+   * Approved logical resources. Never inherited by wildcard. Empty until the first approval.
    *
-   * @minItems 1
    * @maxItems 64
    */
-  resources: string[];
+  resources: IntegrationResource[];
   /**
    * Absent only for explicitly approved ongoing production access.
    */
   expiresAt?: string;
+  /**
+   * Set by the recovery sweep once expiry has passed; enforcement itself is the UTC check on every call.
+   */
+  expiredAt?: string;
   approvedBy?: string;
+  approvedAt?: string;
   /**
    * Optimistic-concurrency version; approvals compare it with the reviewed value.
    */
@@ -59,18 +71,42 @@ export interface DataGrantV2 {
   pendingRequestId?: string;
   provisioning: DataGrantV2Provisioning;
   /**
-   * Database grants: secretref://tenant/{t}/app/{a}/env/{env}/source/{s}.
+   * Database grants: secretref://tenant/{t}/app/{a}/env/{env}/source/{s}. Set only by a successful publish and removed by cleanup.
    */
   credentialRef?: string;
   /**
    * Database grants: the deterministic per tenant/app/environment/source principal.
    */
   mintedPrincipal?: string;
+  createdAt: string;
+  updatedAt: string;
   /**
-   * SaaS grants: the connection installation this environment maps to.
+   * @deprecated
+   * Whose authority an operation runs under. Fixed per operation; callers never choose it.
+   */
+  identityMode?: 'app' | 'user';
+  /**
+   * @deprecated
+   * Deprecated: a SaaS grant runs on the connection's single installation; the control plane never writes it.
    */
   installation?: string;
 }
+/**
+ * One approved logical resource: a channel alias, the fixed Gmail `inbox` alias, or a warehouse view alias with the approved columns.
+ */
+export interface IntegrationResource {
+  /**
+   * Tenant-wide logical alias of a connection (governance sourceId) or of a resource under it.
+   */
+  name: string;
+  /**
+   * warehouse.view.read only: the approved columns of the view.
+   *
+   * @minItems 1
+   * @maxItems 32
+   */
+  columns?: string[];
+}
 export interface DataGrantV2Provisioning {
   status: DataGrantV2ProvisioningStatus;
   /**
@@ -81,6 +117,21 @@ export interface DataGrantV2Provisioning {
    * Sanitized reason; never a provider error body.
    */
   lastError?: string;
+  /**
+   * Conditional worker lease serialising database mutations (120 s).
+   */
+  lease?: {
+    until: string;
+    owner: string;
+  };
+  /**
+   * Provider-side cleanup after revocation or expiry; a FAILED cleanup waits for an admin retry-cleanup.
+   */
+  cleanup?: {
+    status: DataGrantV2CleanupStatus;
+    attempts: number;
+    lastError?: string;
+  };
 }
 
 const legalDataGrantV2StatusTransitions: Record<string, Record<string, true>> = {

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.
+ * 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.
  */
 export type IntegrationErrorCode =
   | 'USER_CONNECTION_REQUIRED'
@@ -29,7 +29,15 @@ export type IntegrationErrorCode =
   | 'APP_ACCESS_REQUIRED'
   | 'GRANT_DENIED'
   | 'TOKEN_REFRESH_PENDING'
-  | 'REQUEST_PENDING';
+  | 'REQUEST_PENDING'
+  | 'INPUT_INVALID'
+  | 'IDEMPOTENCY_KEY_REQUIRED'
+  | 'SEND_IN_PROGRESS'
+  | 'CONNECTION_NOT_FOUND'
+  | 'APP_NOT_FOUND'
+  | 'GRANT_NOT_FOUND'
+  | 'AUTH_REQUIRED'
+  | 'UNAVAILABLE';
 
 /**
  * The `error` member of an integration failure response `{error, requestId}` on the execute/connect routes; the SDK maps it onto HarbourError(category, message, details). `category` is the app-SDK HarbourErrorCategory (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-request.ts

@@ -2,7 +2,7 @@
 // Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
 
 /**
- * Body of POST /_harbour/integrations/execute (app SDK), forwarded unchanged to the governance development and runtime execute routes. Exactly one declared operation against one declared resource. The identity mode is NOT a caller field: it is fixed by the operation and enforced from the approved grant; any identity/userId/scope field is rejected by additionalProperties. Per-operation input bounds: slack.channel.history {limit? 1..15, default 15}; slack.message.post {text 1..4000 chars} and a required idempotencyKey retained across retries of one explicit Send; warehouse.view.read {columns 1..32, limit? 1..1000, default 100}. Transport limits (not expressible here): request <= 16 KiB, total deadline 10 s.
+ * Body of POST /_harbour/integrations/execute (app SDK), forwarded unchanged to the governance development and runtime execute routes. Exactly one declared operation against one declared resource. The identity mode is NOT a caller field: it is fixed by the operation and enforced from the approved grant; any identity/userId/scope field is rejected by additionalProperties. Per-operation input bounds: slack.channel.history {limit? 1..15, default 15}; slack.message.post {text 1..4000 chars} and a required idempotencyKey retained across retries of one explicit Send; gmail.thread.list {limit? 1..15, default 15}; gmail.message.read {messageId}; gmail.message.send {to 1..50 addresses (to+cc+bcc <= 50 in total), cc?, bcc?, subject 1..256 chars, text 1..4000 chars, replyToMessageId?} and a required idempotencyKey like slack.message.post (plain text only, no attachments); warehouse.view.read {columns 1..32, limit? 1..1000, default 100}. Transport limits (not expressible here): request <= 16 KiB, total deadline 10 s.
  */
 export type IntegrationExecuteRequest = {
   /**
@@ -10,9 +10,15 @@ export type IntegrationExecuteRequest = {
    */
   connection: string;
   /**
-   * Closed operation set. Extending it is a contracts change.
+   * Closed operation set. Extending it is a contracts change. gmail.message.send (0.50.0) sends one plain-text email as the signed-in person: a send like slack.message.post (explicit Send, idempotencyKey, write receipt) under user identity.
    */
-  operation: 'slack.channel.history' | 'slack.message.post' | 'warehouse.view.read';
+  operation:
+    | 'slack.channel.history'
+    | 'slack.message.post'
+    | 'gmail.thread.list'
+    | 'gmail.message.read'
+    | 'gmail.message.send'
+    | 'warehouse.view.read';
   /**
    * Tenant-wide logical alias of a connection (governance sourceId) or of a resource under it.
    */
@@ -20,6 +26,21 @@ export type IntegrationExecuteRequest = {
   input: {
     limit?: number;
     text?: string;
+    /**
+     * gmail.message.read: the Gmail message id a gmail.thread.list result named.
+     */
+    messageId?: string;
+    to?: EmailAddressList;
+    cc?: EmailAddressList1;
+    bcc?: EmailAddressList2;
+    /**
+     * gmail.message.send: one-line subject (no line breaks).
+     */
+    subject?: string;
+    /**
+     * gmail.message.send: a Gmail message id (from gmail.thread.list / gmail.message.read) the email replies to; the send joins that thread.
+     */
+    replyToMessageId?: string;
     /**
      * @minItems 1
      * @maxItems 32
@@ -27,7 +48,32 @@ export type IntegrationExecuteRequest = {
     columns?: string[];
   };
   /**
-   * UUID of one explicit Send action; required for slack.message.post only. The same key with the same payload and subject returns the recorded outcome for seven days.
+   * 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.
    */
   idempotencyKey?: string;
 };
+/**
+ * One bare email address (no display name).
+ */
+export type EmailAddress = string;
+/**
+ * gmail.message.send: primary recipients.
+ *
+ * @minItems 1
+ * @maxItems 50
+ */
+export type EmailAddressList = EmailAddress[];
+/**
+ * gmail.message.send: carbon-copy recipients.
+ *
+ * @minItems 1
+ * @maxItems 50
+ */
+export type EmailAddressList1 = EmailAddress[];
+/**
+ * gmail.message.send: blind-copy recipients.
+ *
+ * @minItems 1
+ * @maxItems 50
+ */
+export type EmailAddressList2 = EmailAddress[];

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

@@ -2,7 +2,7 @@
 // Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
 
 /**
- * The `data` member of a successful execute response `{data, requestId}`; the SDK unwraps `data`. Exactly one of the three operation results: slack.channel.history -> {messages, hasMore} (plain text/IDs/time only, never the provider payload); slack.message.post -> {messageId}; warehouse.view.read -> {rows} (decimal/64-bit values as strings, dates as ISO strings). An unknown send outcome is never a result; it is an error with details.code SEND_OUTCOME_UNKNOWN. Results over 1 MiB are rejected, not truncated.
+ * The `data` member of a successful execute response `{data, requestId}`; the SDK unwraps `data`. Exactly one of the six operation results: slack.channel.history -> {messages, hasMore} (plain text/IDs/time only, never the provider payload); slack.message.post -> {messageId}; gmail.thread.list -> {threads, hasMore} (newest inbox threads; each `messageId` is the thread's newest message, what gmail.message.read takes); gmail.message.read -> {id, threadId, subject, from, to, date, text, truncated} (headers plus the plain text with html stripped, cut at 16 KiB with `truncated` set); gmail.message.send -> {messageId, threadId} (the Gmail ids of the sent message and its thread); warehouse.view.read -> {rows} (decimal/64-bit values as strings, dates as ISO strings). An unknown send outcome is never a result; it is an error with details.code SEND_OUTCOME_UNKNOWN. Results over 1 MiB are rejected, not truncated.
  */
 export type IntegrationExecuteResult = {
   /**
@@ -11,6 +11,18 @@ export type IntegrationExecuteResult = {
   messages?: ChannelMessage[];
   hasMore?: boolean;
   messageId?: string;
+  /**
+   * @maxItems 15
+   */
+  threads?: GmailThread[];
+  id?: string;
+  threadId?: string;
+  subject?: string;
+  from?: string;
+  to?: string;
+  date?: string;
+  text?: string;
+  truncated?: boolean;
   /**
    * @maxItems 1000
    */
@@ -25,3 +37,11 @@ export interface ChannelMessage {
   authorId: string;
   createdAt: string;
 }
+export interface GmailThread {
+  id: string;
+  messageId: string;
+  subject: string;
+  from: string;
+  date: string;
+  snippet: string;
+}