@fourier-labs/harbour-contracts 0.47.0 → 0.51.0

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

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://schemas.harbour.dev/integration-execute-request.schema.json",
   "title": "IntegrationExecuteRequest",
-  "description": "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}; warehouse.view.read {columns 1..32, limit? 1..1000, default 100}. Transport limits (not expressible here): request <= 16 KiB, total deadline 10 s.",
+  "description": "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}. Each operation's then-block is the one statement of its input rules: propertyNames.enum names the fields it accepts, required the ones it needs, and per-field overrides (maximum, default) narrow the shared property. Codegen derives IntegrationExecuteInputRules and validateIntegrationExecuteInput (gen-ts/integration-execute-input-rules.ts, gen-go/integration_execute_input_rules.go) from exactly these blocks, so the governance execute route, the app SDK and the kit's local check refuse the same request with the same message. Transport limits (not expressible here): request <= 16 KiB, total deadline 10 s.",
   "type": "object",
   "additionalProperties": false,
   "required": ["connection", "operation", "resource", "input"],
@@ -14,9 +14,14 @@
       "type": "object",
       "additionalProperties": false,
       "properties": {
-        "limit": { "type": "integer", "minimum": 1, "maximum": 1000 },
-        "text": { "type": "string", "minLength": 1, "maxLength": 4000 },
+        "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "Read operations: how many items to return; the per-operation then-block sets the real ceiling (15 for slack.channel.history and gmail.thread.list, 1000 for warehouse.view.read) and the default." },
+        "text": { "type": "string", "minLength": 1, "maxLength": 4000, "description": "slack.message.post / gmail.message.send: the plain-text body, 1..4000 characters." },
         "messageId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$", "description": "gmail.message.read: the Gmail message id a gmail.thread.list result named." },
+        "to": { "$ref": "#/definitions/EmailAddressList", "description": "gmail.message.send: primary recipients." },
+        "cc": { "$ref": "#/definitions/EmailAddressList", "description": "gmail.message.send: carbon-copy recipients." },
+        "bcc": { "$ref": "#/definitions/EmailAddressList", "description": "gmail.message.send: blind-copy recipients." },
+        "subject": { "type": "string", "minLength": 1, "maxLength": 256, "description": "gmail.message.send: one-line subject (no line breaks)." },
+        "replyToMessageId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$", "description": "gmail.message.send: a Gmail message id (from gmail.thread.list / gmail.message.read) the email replies to; the send joins that thread." },
         "columns": {
           "type": "array",
           "minItems": 1,
@@ -28,7 +33,7 @@
     "idempotencyKey": {
       "type": "string",
       "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
-      "description": "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."
+      "description": "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."
     }
   },
   "allOf": [
@@ -37,7 +42,7 @@
       "then": {
         "not": { "required": ["idempotencyKey"] },
         "properties": {
-          "input": { "properties": { "limit": { "maximum": 15 } }, "not": { "anyOf": [{ "required": ["text"] }, { "required": ["columns"] }, { "required": ["messageId"] }] } }
+          "input": { "propertyNames": { "enum": ["limit"] }, "properties": { "limit": { "maximum": 15, "default": 15 } } }
         }
       }
     },
@@ -46,7 +51,7 @@
       "then": {
         "required": ["idempotencyKey"],
         "properties": {
-          "input": { "required": ["text"], "not": { "anyOf": [{ "required": ["limit"] }, { "required": ["columns"] }, { "required": ["messageId"] }] } }
+          "input": { "propertyNames": { "enum": ["text"] }, "required": ["text"] }
         }
       }
     },
@@ -55,7 +60,7 @@
       "then": {
         "not": { "required": ["idempotencyKey"] },
         "properties": {
-          "input": { "required": ["columns"], "not": { "anyOf": [{ "required": ["text"] }, { "required": ["messageId"] }] } }
+          "input": { "propertyNames": { "enum": ["columns", "limit"] }, "required": ["columns"], "properties": { "limit": { "maximum": 1000, "default": 100 } } }
         }
       }
     },
@@ -64,7 +69,7 @@
       "then": {
         "not": { "required": ["idempotencyKey"] },
         "properties": {
-          "input": { "properties": { "limit": { "maximum": 15 } }, "not": { "anyOf": [{ "required": ["text"] }, { "required": ["columns"] }, { "required": ["messageId"] }] } }
+          "input": { "propertyNames": { "enum": ["limit"] }, "properties": { "limit": { "maximum": 15, "default": 15 } } }
         }
       }
     },
@@ -73,11 +78,24 @@
       "then": {
         "not": { "required": ["idempotencyKey"] },
         "properties": {
-          "input": { "required": ["messageId"], "not": { "anyOf": [{ "required": ["text"] }, { "required": ["columns"] }, { "required": ["limit"] }] } }
+          "input": { "propertyNames": { "enum": ["messageId"] }, "required": ["messageId"] }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "operation": { "const": "gmail.message.send" } } },
+      "then": {
+        "required": ["idempotencyKey"],
+        "properties": {
+          "input": { "propertyNames": { "enum": ["to", "cc", "bcc", "subject", "text", "replyToMessageId"] }, "required": ["to", "subject", "text"] }
         }
       }
     }
   ],
+  "definitions": {
+    "EmailAddress": { "type": "string", "minLength": 3, "maxLength": 254, "pattern": "^[^\\s@<>,;\"]+@[^\\s@<>,;\"]+\\.[^\\s@<>,;\"]+$", "description": "One bare email address (no display name)." },
+    "EmailAddressList": { "type": "array", "minItems": 1, "maxItems": 50, "uniqueItems": true, "items": { "$ref": "#/definitions/EmailAddress" } }
+  },
   "examples": [
     { "connection": "company-slack", "operation": "slack.channel.history", "resource": "team-updates", "input": { "limit": 15 } },
     {
@@ -89,6 +107,13 @@
     },
     { "connection": "sales-warehouse", "operation": "warehouse.view.read", "resource": "weekly_sales", "input": { "columns": ["week", "total"], "limit": 100 } },
     { "connection": "gmail", "operation": "gmail.thread.list", "resource": "inbox", "input": { "limit": 15 } },
-    { "connection": "gmail", "operation": "gmail.message.read", "resource": "inbox", "input": { "messageId": "18f2c3a4b5d6e7f8" } }
+    { "connection": "gmail", "operation": "gmail.message.read", "resource": "inbox", "input": { "messageId": "18f2c3a4b5d6e7f8" } },
+    {
+      "connection": "gmail",
+      "operation": "gmail.message.send",
+      "resource": "inbox",
+      "input": { "to": ["jane@example.com"], "subject": "Weekly report", "text": "Shipped the weekly report.", "replyToMessageId": "18f2c3a4b5d6e7f8" },
+      "idempotencyKey": "6f1c2c1e-3a1c-4c3e-9f0e-2b6f7d8a9c11"
+    }
   ]
 }

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 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.",
+  "description": "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.",
   "type": "object",
   "additionalProperties": false,
   "properties": {
@@ -35,6 +35,7 @@
   "oneOf": [
     { "required": ["messages", "hasMore"], "maxProperties": 2 },
     { "required": ["messageId"], "maxProperties": 1 },
+    { "required": ["messageId", "threadId"], "maxProperties": 2 },
     { "required": ["threads", "hasMore"], "maxProperties": 2 },
     { "required": ["id", "threadId", "subject", "from", "to", "date", "text", "truncated"], "maxProperties": 8 },
     { "required": ["rows"], "maxProperties": 1 }
@@ -71,6 +72,7 @@
       "hasMore": false
     },
     { "messageId": "1725840100.000200" },
+    { "messageId": "18f2c3a4b5d6e7f9", "threadId": "18f2c3a4b5d6e7f0" },
     {
       "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

package/schema/saas-connection.schema.json

@@ -26,11 +26,11 @@
     "operations": {
       "type": "array",
       "minItems": 1,
-      "maxItems": 4,
+      "maxItems": 5,
       "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."
+      "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, gmail.message.send). Never warehouse.view.read."
     },
     "developmentPreapproval": { "$ref": "#/definitions/DevelopmentPreapproval" },
     "blockedDevelopmentBuilders": {
@@ -161,7 +161,7 @@
       "status": "ACTIVE",
       "version": 1,
       "channels": {},
-      "operations": ["gmail.thread.list", "gmail.message.read"],
+      "operations": ["gmail.thread.list", "gmail.message.read", "gmail.message.send"],
       "developmentPreapproval": { "enabled": false, "hours": 24 },
       "blockedDevelopmentBuilders": ["contractor@example.com"],
       "createdAt": "2026-09-11T08:00:00Z",

package/schema/transform-report.schema.json

@@ -9,6 +9,7 @@
   "required": ["application"],
   "properties": {
     "applied_playbooks": {
+      "description": "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.",
       "type": "array",
       "minItems": 1,
       "items": { "type": "string", "minLength": 1 }
@@ -666,7 +667,7 @@
   ],
   "oneOf": [
     {
-      "required": ["applied_playbooks", "static_rebuild_required", "analysis", "database", "preservation_plan", "validation_fixtures", "application"],
+      "required": ["static_rebuild_required", "analysis", "database", "preservation_plan", "validation_fixtures", "application"],
       "properties": {
         "application": {
           "required": ["runtime", "buildKind", "topology", "entrypoint", "build", "basePath", "evidence", "unsupportedFeatures"],

package/schema/well-defined-app-manifest.schema.json

@@ -26,9 +26,70 @@
       "type": "array",
       "maxItems": 128,
       "items": { "$ref": "#/definitions/WorkloadBinding" }
+    },
+    "runtime": {
+      "type": "string",
+      "pattern": "^(?:nodejs|python)[0-9]+(?:\\.[0-9]+)?$",
+      "description": "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."
+    },
+    "capabilities": {
+      "type": "array",
+      "maxItems": 5,
+      "uniqueItems": true,
+      "items": { "$ref": "#/definitions/Capability" },
+      "description": "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."
+    },
+    "routeAuth": {
+      "$ref": "#/definitions/RouteAuth",
+      "description": "Optional method/path authentication policy. Omitted means every route requires Harbour SSO, the same default the policy states explicitly."
     }
   },
   "definitions": {
+    "Capability": {
+      "type": "string",
+      "enum": ["data", "files", "actions", "realtime", "telemetry"]
+    },
+    "RouteAuth": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["default", "public"],
+      "description": "Harbour SSO is required by default; the public list is the only way a route escapes it, and each entry names the methods and the application-authorized mode so the artifact contract's route_auth can be built from this document alone.",
+      "properties": {
+        "default": {
+          "type": "string",
+          "const": "sso_required",
+          "default": "sso_required"
+        },
+        "public": {
+          "type": "array",
+          "maxItems": 64,
+          "default": [],
+          "items": { "$ref": "#/definitions/PublicRoute" }
+        }
+      }
+    },
+    "PublicRoute": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "methods", "mode"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "pattern": "^/(?:[A-Za-z0-9._~-]+/)*(?:[A-Za-z0-9._~-]+|\\*)$"
+        },
+        "methods": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 7,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "enum": ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]
+          }
+        },
+        "mode": { "type": "string", "const": "application_authorized" }
+      }
+    },
     "ResourceProfile": {
       "type": "string",
       "enum": ["standard", "memory-1g", "memory-2g"]