@fourier-labs/harbour-contracts 0.45.0 → 0.47.0

package/schema/integration-execute-result.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://schemas.harbour.dev/integration-execute-result.schema.json",
   "title": "IntegrationExecuteResult",
-  "description": "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.",
+  "description": "The `data` member of a successful execute response `{data, requestId}`; the SDK unwraps `data`. Exactly one of the five 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); 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.",
   "type": "object",
   "additionalProperties": false,
   "properties": {
@@ -13,6 +13,19 @@
     },
     "hasMore": { "type": "boolean" },
     "messageId": { "type": "string", "minLength": 1, "maxLength": 128 },
+    "threads": {
+      "type": "array",
+      "maxItems": 15,
+      "items": { "$ref": "#/definitions/GmailThread" }
+    },
+    "id": { "type": "string", "minLength": 1, "maxLength": 128 },
+    "threadId": { "type": "string", "minLength": 1, "maxLength": 128 },
+    "subject": { "type": "string", "maxLength": 2048 },
+    "from": { "type": "string", "maxLength": 2048 },
+    "to": { "type": "string", "maxLength": 8192 },
+    "date": { "type": "string", "maxLength": 128 },
+    "text": { "type": "string", "maxLength": 16384 },
+    "truncated": { "type": "boolean" },
     "rows": {
       "type": "array",
       "maxItems": 1000,
@@ -22,9 +35,24 @@
   "oneOf": [
     { "required": ["messages", "hasMore"], "maxProperties": 2 },
     { "required": ["messageId"], "maxProperties": 1 },
+    { "required": ["threads", "hasMore"], "maxProperties": 2 },
+    { "required": ["id", "threadId", "subject", "from", "to", "date", "text", "truncated"], "maxProperties": 8 },
     { "required": ["rows"], "maxProperties": 1 }
   ],
   "definitions": {
+    "GmailThread": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "messageId", "subject", "from", "date", "snippet"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "messageId": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "subject": { "type": "string", "maxLength": 2048 },
+        "from": { "type": "string", "maxLength": 2048 },
+        "date": { "type": "string", "maxLength": 128 },
+        "snippet": { "type": "string", "maxLength": 4096 }
+      }
+    },
     "ChannelMessage": {
       "type": "object",
       "additionalProperties": false,
@@ -43,6 +71,11 @@
       "hasMore": false
     },
     { "messageId": "1725840100.000200" },
+    {
+      "threads": [{ "id": "18f2c3a4b5d6e7f0", "messageId": "18f2c3a4b5d6e7f8", "subject": "Weekly report", "from": "Jane <jane@example.com>", "date": "2026-09-11T08:00:00Z", "snippet": "Shipped the weekly report." }],
+      "hasMore": false
+    },
+    { "id": "18f2c3a4b5d6e7f8", "threadId": "18f2c3a4b5d6e7f0", "subject": "Weekly report", "from": "Jane <jane@example.com>", "to": "team@example.com", "date": "2026-09-11T08:00:00Z", "text": "Shipped the weekly report.", "truncated": false },
     { "rows": [{ "week": "2026-W36", "total": "1234.50" }] }
   ]
 }

package/schema/kit-bundle-manifest.schema.json

@@ -15,7 +15,9 @@
       "required": ["package", "tarballSha256"],
       "properties": {
         "package": { "type": "string", "const": "@harbour/app-sdk" },
-        "tarballSha256": { "$ref": "#/definitions/HexSha256", "description": "SHA-256 of the SDK tarball baked into this bundle; the CodeBuild gate compares it with the pipeline's own tarball." }
+        "version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(-[0-9A-Za-z.-]+)?$", "description": "The SDK package version the tarball was packed from (informational; compatibility is decided by tarballSha256)." },
+        "tarballSha256": { "$ref": "#/definitions/HexSha256", "description": "SHA-256 of the SDK tarball baked into this bundle; the CodeBuild gate compares it with the pipeline's own tarball." },
+        "url": { "type": "string", "pattern": "^https://[^\\s{}]+$", "maxLength": 2048, "description": "Where the CLI downloads the SDK tarball from when it is not shipped inline; the bytes are verified against tarballSha256 before install. The publisher may name the location by content address (for example an OCI blob whose path ends in sha256:<tarballSha256>)." }
       }
     },
     "images": {
@@ -54,7 +56,12 @@
     {
       "schema": "harbour.kit-bundle/1.0",
       "kitVersion": "0.2.0",
-      "sdk": { "package": "@harbour/app-sdk", "tarballSha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" },
+      "sdk": {
+        "package": "@harbour/app-sdk",
+        "version": "1.0.0",
+        "tarballSha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
+        "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
+      },
       "images": {
         "appGateway": "123456789012.dkr.ecr.us-east-1.amazonaws.com/harbour/app-gateway@sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
         "sessionFixture": "123456789012.dkr.ecr.us-east-1.amazonaws.com/harbour/session-fixture@sha256:fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9"

package/schema/saas-connection.schema.json

@@ -2,70 +2,99 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://schemas.harbour.dev/saas-connection.schema.json",
   "title": "SaasConnection",
-  "description": "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.",
+  "description": "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.",
   "type": "object",
   "additionalProperties": false,
-  "required": ["sourceId", "kind", "provider", "displayName", "status", "version", "clientId", "environments", "operations", "developmentPreapproval"],
+  "required": ["schema", "tenantId", "sourceId", "kind", "provider", "displayName", "status", "version", "channels", "operations", "developmentPreapproval", "createdAt", "updatedAt"],
   "properties": {
+    "schema": { "type": "string", "const": "harbour.saas-connection/1.0" },
+    "tenantId": { "type": "string", "minLength": 1, "maxLength": 255 },
     "sourceId": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationAlias" },
     "kind": { "type": "string", "const": "saas" },
-    "provider": { "type": "string", "enum": ["slack"] },
-    "displayName": { "type": "string", "minLength": 1, "maxLength": 255 },
+    "provider": { "$ref": "#/definitions/SaasProvider" },
+    "displayName": { "type": "string", "minLength": 1, "maxLength": 120 },
     "status": { "$ref": "#/definitions/SaasConnectionStatus" },
     "version": { "type": "integer", "minimum": 1, "description": "Optimistic-concurrency version; every write is conditional on it." },
-    "clientId": { "type": "string", "minLength": 1, "maxLength": 255 },
+    "installation": { "$ref": "#/definitions/SaasInstallation" },
+    "channels": {
+      "type": "object",
+      "maxProperties": 64,
+      "propertyNames": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationAlias" },
+      "additionalProperties": { "type": "string", "pattern": "^[A-Z0-9]{5,20}$", "description": "Provider channel ID; only public, non-archived channels are valid." },
+      "description": "Logical channel alias -> provider channel ID, shared by every environment. Always empty for Gmail."
+    },
+    "operations": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 4,
+      "uniqueItems": true,
+      "items": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationOperation" },
+      "not": { "contains": { "const": "warehouse.view.read" } },
+      "description": "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). Never warehouse.view.read."
+    },
+    "developmentPreapproval": { "$ref": "#/definitions/DevelopmentPreapproval" },
+    "blockedDevelopmentBuilders": {
+      "type": "array",
+      "maxItems": 256,
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1, "maxLength": 255 },
+      "description": "Lower-cased builder emails excluded from development preapproval."
+    },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "updatedAt": { "type": "string", "format": "date-time" },
+    "clientId": { "type": "string", "minLength": 1, "maxLength": 255, "deprecated": true, "description": "Deprecated (pre-T25 tenant-owned provider client). Dropped on read; never written." },
     "clientSecretRef": {
       "type": "string",
       "pattern": "^secretref://[A-Za-z0-9][A-Za-z0-9/_.:-]*$",
-      "description": "secretref://tenant/{tenantId}/saas/{sourceId}/client"
+      "deprecated": true,
+      "description": "Deprecated (pre-T25 tenant-owned provider client secret reference). Dropped on read; never written."
     },
     "environments": {
       "type": "object",
       "additionalProperties": false,
       "minProperties": 1,
+      "deprecated": true,
+      "description": "Deprecated pre-T25 per-environment mapping. On read the development entry's channels become `channels`; never written.",
       "properties": {
         "development": { "$ref": "#/definitions/SaasEnvironmentMapping" },
         "preview": { "$ref": "#/definitions/SaasEnvironmentMapping" },
         "production": { "$ref": "#/definitions/SaasEnvironmentMapping" }
       }
     },
-    "operations": {
-      "type": "array",
-      "minItems": 1,
-      "maxItems": 2,
-      "uniqueItems": true,
-      "items": { "type": "string", "enum": ["slack.channel.history", "slack.message.post"] },
-      "description": "Operations IT allows apps to request on this connection."
-    },
-    "developmentPreapproval": { "$ref": "#/definitions/DevelopmentPreapproval" },
     "installations": {
       "type": "object",
       "propertyNames": { "$ref": "#/definitions/InstallationName" },
-      "additionalProperties": { "$ref": "#/definitions/SaasInstallation" },
-      "description": "Provider installations keyed by the installation name environments point at."
-    },
-    "createdAt": { "type": "string", "format": "date-time" },
-    "updatedAt": { "type": "string", "format": "date-time" }
+      "additionalProperties": { "$ref": "#/definitions/LegacySaasInstallation" },
+      "deprecated": true,
+      "description": "Deprecated pre-T25 named installations. On read the `nonprod` entry (or the development mapping's) becomes `installation`; never written."
+    }
   },
   "definitions": {
+    "SaasProvider": {
+      "type": "string",
+      "enum": ["slack", "gmail"],
+      "description": "Slack carries an installation and a channel map; Gmail is user-consent only and read-only."
+    },
     "SaasConnectionStatus": {
       "type": "string",
       "enum": ["ACTIVE", "DISABLED"],
       "description": "DISABLED stops every app call immediately (details.code CONNECTION_DISABLED)."
     },
-    "InstallationName": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,62}$" },
-    "SaasEnvironmentMapping": {
+    "SaasInstallationStatus": {
+      "type": "string",
+      "enum": ["installed", "reconnect_required", "revoked"]
+    },
+    "SaasInstallation": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["installation", "channels"],
+      "required": ["tokenRecordId", "workspaceId", "botUserId", "status", "installedAt"],
+      "description": "The one bot installation of the platform-owned provider app in this tenant's workspace.",
       "properties": {
-        "installation": { "$ref": "#/definitions/InstallationName" },
-        "channels": {
-          "type": "object",
-          "maxProperties": 64,
-          "propertyNames": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationAlias" },
-          "additionalProperties": { "type": "string", "pattern": "^[A-Z0-9]{1,32}$", "description": "Provider channel ID; only public, non-archived channels are valid." }
-        }
+        "tokenRecordId": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "workspaceId": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "botUserId": { "type": "string", "maxLength": 128, "description": "Empty only for a legacy record normalised without one." },
+        "status": { "$ref": "#/definitions/SaasInstallationStatus" },
+        "installedAt": { "type": "string", "format": "date-time" }
       }
     },
     "DevelopmentPreapproval": {
@@ -77,10 +106,26 @@
         "hours": { "type": "integer", "minimum": 1, "maximum": 168, "description": "Development grant duration; default 24." }
       }
     },
-    "SaasInstallation": {
+    "InstallationName": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,62}$", "deprecated": true },
+    "SaasEnvironmentMapping": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["tokenRecordId", "workspaceId", "botUserId", "status"],
+      "required": ["installation", "channels"],
+      "deprecated": true,
+      "properties": {
+        "installation": { "$ref": "#/definitions/InstallationName" },
+        "channels": {
+          "type": "object",
+          "maxProperties": 64,
+          "propertyNames": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationAlias" },
+          "additionalProperties": { "type": "string", "pattern": "^[A-Z0-9]{1,32}$" }
+        }
+      }
+    },
+    "LegacySaasInstallation": {
+      "type": "object",
+      "additionalProperties": false,
+      "deprecated": true,
       "properties": {
         "tokenRecordId": { "type": "string", "minLength": 1, "maxLength": 128 },
         "workspaceId": { "type": "string", "minLength": 1, "maxLength": 128 },
@@ -91,25 +136,36 @@
   },
   "examples": [
     {
+      "schema": "harbour.saas-connection/1.0",
+      "tenantId": "fourier",
       "sourceId": "company-slack",
       "kind": "saas",
       "provider": "slack",
       "displayName": "Company Slack",
       "status": "ACTIVE",
       "version": 3,
-      "clientId": "1234567890.1234567890",
-      "clientSecretRef": "secretref://tenant/fourier/saas/company-slack/client",
-      "environments": {
-        "development": { "installation": "nonprod", "channels": { "team-updates": "C0123NONPROD" } },
-        "production": { "installation": "prod", "channels": { "team-updates": "C0123PROD" } }
-      },
+      "installation": { "tokenRecordId": "tok_workspace", "workspaceId": "T0WORKSPACE", "botUserId": "U0BOT", "status": "installed", "installedAt": "2026-09-09T08:00:00Z" },
+      "channels": { "team-updates": "C0123TEAM" },
       "operations": ["slack.channel.history", "slack.message.post"],
       "developmentPreapproval": { "enabled": true, "hours": 24 },
-      "installations": {
-        "nonprod": { "tokenRecordId": "tok_nonprod", "workspaceId": "T0NONPROD", "botUserId": "U0BOT", "status": "ACTIVE" }
-      },
       "createdAt": "2026-09-09T08:00:00Z",
       "updatedAt": "2026-09-09T08:00:00Z"
+    },
+    {
+      "schema": "harbour.saas-connection/1.0",
+      "tenantId": "fourier",
+      "sourceId": "gmail",
+      "kind": "saas",
+      "provider": "gmail",
+      "displayName": "Gmail",
+      "status": "ACTIVE",
+      "version": 1,
+      "channels": {},
+      "operations": ["gmail.thread.list", "gmail.message.read"],
+      "developmentPreapproval": { "enabled": false, "hours": 24 },
+      "blockedDevelopmentBuilders": ["contractor@example.com"],
+      "createdAt": "2026-09-11T08:00:00Z",
+      "updatedAt": "2026-09-11T08:00:00Z"
     }
   ]
 }