@fourier-labs/harbour-contracts 0.73.0 → 0.76.0

package/schema/app-integrations-declaration.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://schemas.harbour.dev/app-integrations-declaration.schema.json",
   "title": "AppIntegrationsDeclaration",
-  "description": "Committed `.isomorph/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 (thirteen operations since 0.73.0, ADR 0018). Each operation carries a fixed identity mode \u2014 slack.dm.send=app, slack.user.lookup=app, every gmail.* operation=user, warehouse.view.read=app \u2014 except the declared-mode Slack operations (slack.message.post, and since 0.71.0 slack.channel.history, slack.message.update and slack.message.delete), whose mode the app DECLARES: `app` acts as the company's Slack app (the one audited bot identity; a post goes out under the IT-approved per-app display name when the connection declares `presentation`), `user` acts as the signed-in person after their own consent (reads what they can read, edits what they wrote). The declared mode is the one the app requests access for; an app may hold approved grants for both modes after two requests, and each declared-mode call names which approved mode it runs under (`mode` on the execute request, 0.55.0) \u2014 a mode IT did not approve is refused, never swapped for the other. A `saas` connection may declare only the Slack and Gmail operations and a `database` connection only warehouse.view.read; `presentation` is a `saas` connection's optional per-app display name and icon for app-mode Slack posts, shown to IT at approval time and applied only from the approved grant. Gmail is user-mode only (reads, one send); its single resource is the fixed `inbox` alias. slack.dm.send and slack.user.lookup address people by email rather than a channel, so their single resource is the fixed `workspace` alias (the connection's installed workspace), the way Gmail's is `inbox`. This file also owns the shared IntegrationOperation / IntegrationIdentityMode / IntegrationEnvironment / IntegrationConnectionKind / IntegrationPresentation definitions referenced by the other integration schemas.",
+  "description": "Committed `.isomorph/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 (twenty-four operations since 0.76.0, ADR 0018 and ADR 0022). Each operation carries a fixed identity mode \u2014 slack.dm.send=app, slack.user.lookup=app, every gmail.* operation=user, every basecamp.* operation=user, warehouse.view.read=app, service.request=app \u2014 except the declared-mode Slack operations (slack.message.post, and since 0.71.0 slack.channel.history, slack.message.update and slack.message.delete), whose mode the app DECLARES: `app` acts as the company's Slack app (the one audited bot identity; a post goes out under the IT-approved per-app display name when the connection declares `presentation`), `user` acts as the signed-in person after their own consent (reads what they can read, edits what they wrote). The declared mode is the one the app requests access for; an app may hold approved grants for both modes after two requests, and each declared-mode call names which approved mode it runs under (`mode` on the execute request, 0.55.0) \u2014 a mode IT did not approve is refused, never swapped for the other. A `saas` connection may declare only the Slack, Gmail and Basecamp operations and a `database` connection only warehouse.view.read; `presentation` is a `saas` connection's optional per-app display name and icon for app-mode Slack posts, shown to IT at approval time and applied only from the approved grant. Gmail is user-mode only (reads, one send); its single resource is the fixed `inbox` alias. Basecamp (0.76.0, ADR 0022) is user-mode only too: basecamp.project.list runs on the fixed `account` alias (the company's pinned Basecamp account) and every other basecamp.* operation on a project alias IT mapped in the connection's `channels` map, so Basecamp itself refuses an id outside that project. slack.dm.send and slack.user.lookup address people by email rather than a channel, so their single resource is the fixed `workspace` alias (the connection's installed workspace), the way Gmail's is `inbox`. This file also owns the shared IntegrationOperation / IntegrationIdentityMode / IntegrationEnvironment / IntegrationConnectionKind / IntegrationPresentation definitions referenced by the other integration schemas.",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -32,6 +32,11 @@
       "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$",
       "description": "Tenant-wide logical alias of a connection (governance sourceId) or of a resource under it."
     },
+    "BasecampId": {
+      "type": "string",
+      "pattern": "^[0-9]{1,20}$",
+      "description": "A Basecamp id (0.76.0): an account, project, to-do list, to-do, recording or person, as a string of 1..20 digits \u2014 how every basecamp.* result names one and every basecamp.* input takes one back."
+    },
     "IntegrationConnectionKind": {
       "type": "string",
       "enum": [
@@ -54,10 +59,21 @@
         "gmail.message.read",
         "gmail.message.send",
         "gmail.attachment.read",
+        "basecamp.project.list",
+        "basecamp.todolist.list",
+        "basecamp.todo.list",
+        "basecamp.todo.create",
+        "basecamp.todo.complete",
+        "basecamp.message.list",
+        "basecamp.message.post",
+        "basecamp.comment.list",
+        "basecamp.comment.post",
+        "basecamp.campfire.post",
+        "basecamp.people.list",
         "warehouse.view.read",
         "service.request"
       ],
-      "description": "Closed operation set. Extending it is a contracts change. gmail.message.send (0.50.0) sends one email as the signed-in person: a send like slack.message.post (explicit Send, idempotencyKey, write receipt) under user identity; since 0.71.0 it may carry an HTML body and attachments. slack.message.post (0.53.0) runs in the mode the app declares: app (the company's Slack app, under the IT-approved per-app name) or user (the signed-in person, after their consent); since 0.55.0 each call names which of the approved modes it runs under. 0.71.0 (ADR 0018) adds slack.message.update and slack.message.delete (declared mode, like post), slack.dm.send (app mode: a direct message to 1..8 workspace members named by email), slack.user.lookup (app mode: email to Slack user id), gmail.thread.read (every message of one thread) and gmail.attachment.read (one attachment's bytes), and lets slack.channel.history run in app mode as well as user mode."
+      "description": "Closed operation set. Extending it is a contracts change. 0.76.0 (ADR 0022) adds the eleven Basecamp operations, every one user mode only like gmail.*: basecamp.project.list (the projects of the company's pinned Basecamp account; its resource is the fixed `account` alias), and on one mapped project (the resource is a project alias, a key of the connection's `channels` map) basecamp.todolist.list, basecamp.todo.list, basecamp.todo.create (a receipted write: explicit action, idempotencyKey), basecamp.todo.complete (idempotent at Basecamp, no key), basecamp.message.list, basecamp.message.post, basecamp.comment.list, basecamp.comment.post, basecamp.campfire.post (the three posts are receipted writes) and basecamp.people.list. gmail.message.send (0.50.0) sends one email as the signed-in person: a send like slack.message.post (explicit Send, idempotencyKey, write receipt) under user identity; since 0.71.0 it may carry an HTML body and attachments. slack.message.post (0.53.0) runs in the mode the app declares: app (the company's Slack app, under the IT-approved per-app name) or user (the signed-in person, after their consent); since 0.55.0 each call names which of the approved modes it runs under. 0.71.0 (ADR 0018) adds slack.message.update and slack.message.delete (declared mode, like post), slack.dm.send (app mode: a direct message to 1..8 workspace members named by email), slack.user.lookup (app mode: email to Slack user id), gmail.thread.read (every message of one thread) and gmail.attachment.read (one attachment's bytes), and lets slack.channel.history run in app mode as well as user mode."
     },
     "IntegrationIdentityMode": {
       "type": "string",
@@ -147,6 +163,7 @@
         "identity",
         "resources"
       ],
+      "description": "Every gmail.* operation (resource: the fixed `inbox` alias) and, since 0.76.0, every basecamp.* operation (resource: a project alias from the connection's `channels` map, or the fixed `account` alias for basecamp.project.list): user mode only — the app acts as the signed-in person after their own consent.",
       "properties": {
         "identity": {
           "type": "string",
@@ -270,6 +287,39 @@
             "gmail.attachment.read": {
               "$ref": "#/definitions/UserModeChannelOperation"
             },
+            "basecamp.project.list": {
+              "$ref": "#/definitions/UserModeChannelOperation"
+            },
+            "basecamp.todolist.list": {
+              "$ref": "#/definitions/UserModeChannelOperation"
+            },
+            "basecamp.todo.list": {
+              "$ref": "#/definitions/UserModeChannelOperation"
+            },
+            "basecamp.todo.create": {
+              "$ref": "#/definitions/UserModeChannelOperation"
+            },
+            "basecamp.todo.complete": {
+              "$ref": "#/definitions/UserModeChannelOperation"
+            },
+            "basecamp.message.list": {
+              "$ref": "#/definitions/UserModeChannelOperation"
+            },
+            "basecamp.message.post": {
+              "$ref": "#/definitions/UserModeChannelOperation"
+            },
+            "basecamp.comment.list": {
+              "$ref": "#/definitions/UserModeChannelOperation"
+            },
+            "basecamp.comment.post": {
+              "$ref": "#/definitions/UserModeChannelOperation"
+            },
+            "basecamp.campfire.post": {
+              "$ref": "#/definitions/UserModeChannelOperation"
+            },
+            "basecamp.people.list": {
+              "$ref": "#/definitions/UserModeChannelOperation"
+            },
             "warehouse.view.read": {
               "$ref": "#/definitions/AppModeViewOperation"
             },
@@ -377,6 +427,61 @@
                         "gmail.attachment.read"
                       ]
                     },
+                    {
+                      "required": [
+                        "basecamp.project.list"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "basecamp.todolist.list"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "basecamp.todo.list"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "basecamp.todo.create"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "basecamp.todo.complete"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "basecamp.message.list"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "basecamp.message.post"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "basecamp.comment.list"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "basecamp.comment.post"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "basecamp.campfire.post"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "basecamp.people.list"
+                      ]
+                    },
                     {
                       "required": [
                         "service.request"
@@ -461,6 +566,61 @@
                         "gmail.attachment.read"
                       ]
                     },
+                    {
+                      "required": [
+                        "basecamp.project.list"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "basecamp.todolist.list"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "basecamp.todo.list"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "basecamp.todo.create"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "basecamp.todo.complete"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "basecamp.message.list"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "basecamp.message.post"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "basecamp.comment.list"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "basecamp.comment.post"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "basecamp.campfire.post"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "basecamp.people.list"
+                      ]
+                    },
                     {
                       "required": [
                         "warehouse.view.read"
@@ -587,6 +747,77 @@
             }
           }
         },
+        "company-basecamp": {
+          "kind": "saas",
+          "operations": {
+            "basecamp.project.list": {
+              "identity": "user",
+              "resources": [
+                "account"
+              ]
+            },
+            "basecamp.todolist.list": {
+              "identity": "user",
+              "resources": [
+                "launch"
+              ]
+            },
+            "basecamp.todo.list": {
+              "identity": "user",
+              "resources": [
+                "launch"
+              ]
+            },
+            "basecamp.todo.create": {
+              "identity": "user",
+              "resources": [
+                "launch"
+              ]
+            },
+            "basecamp.todo.complete": {
+              "identity": "user",
+              "resources": [
+                "launch"
+              ]
+            },
+            "basecamp.message.list": {
+              "identity": "user",
+              "resources": [
+                "launch"
+              ]
+            },
+            "basecamp.message.post": {
+              "identity": "user",
+              "resources": [
+                "launch"
+              ]
+            },
+            "basecamp.comment.list": {
+              "identity": "user",
+              "resources": [
+                "launch"
+              ]
+            },
+            "basecamp.comment.post": {
+              "identity": "user",
+              "resources": [
+                "launch"
+              ]
+            },
+            "basecamp.campfire.post": {
+              "identity": "user",
+              "resources": [
+                "launch"
+              ]
+            },
+            "basecamp.people.list": {
+              "identity": "user",
+              "resources": [
+                "launch"
+              ]
+            }
+          }
+        },
         "sales-warehouse": {
           "kind": "database",
           "operations": {

package/schema/data-grant-v2.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://schemas.harbour.dev/data-grant-v2.schema.json",
   "title": "DataGrantV2",
-  "description": "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. An app-mode Slack grant may carry `presentation` (0.53.0): the IT-approved display name and icon the app's posts go out under, copied from the approved request and read by every post — never from the call. `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.",
+  "description": "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, a Basecamp project alias or the fixed Basecamp `account` 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. An app-mode Slack grant may carry `presentation` (0.53.0): the IT-approved display name and icon the app's posts go out under, copied from the approved request and read by every post — never from the call. `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.",
   "type": "object",
   "additionalProperties": false,
   "required": ["schema", "tenantId", "appId", "environment", "sourceId", "mode", "kind", "status", "operations", "resources", "version", "provisioning", "createdAt", "updatedAt"],
@@ -17,10 +17,10 @@
     "status": { "$ref": "#/definitions/DataGrantV2Status" },
     "operations": {
       "type": "array",
-      "maxItems": 11,
+      "maxItems": 22,
       "uniqueItems": true,
       "items": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationOperation" },
-      "description": "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."
+      "description": "Approved operations; each must match this grant's mode. Empty until the first approval. At most the twenty-two SaaS operations (0.76.0: eleven Slack and Gmail, eleven Basecamp); a database grant holds one."
     },
     "resources": {
       "type": "array",
@@ -62,7 +62,7 @@
       "type": "object",
       "additionalProperties": false,
       "required": ["name"],
-      "description": "One approved logical resource: a channel alias, the fixed Gmail `inbox` alias, or a warehouse view alias with the approved columns.",
+      "description": "One approved logical resource: a Slack channel alias, the fixed Gmail `inbox` alias, a Basecamp project alias or the fixed Basecamp `account` alias (0.76.0), or a warehouse view alias with the approved columns.",
       "properties": {
         "name": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationAlias" },
         "columns": {

package/schema/data-source.schema.json

@@ -77,13 +77,42 @@
     },
     "status": {
       "$ref": "#/definitions/DataSourceStatus"
+    },
+    "environments": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "development": {
+          "$ref": "#/definitions/DataSourceEnvironmentCopy"
+        },
+        "preview": {
+          "$ref": "#/definitions/DataSourceEnvironmentCopy"
+        }
+      },
+      "description": "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."
     }
   },
   "definitions": {
     "DataSourceConnector": {
       "type": "string",
-      "enum": ["postgres", "redshift", "bigquery", "databricks", "mysql"],
-      "description": "Closed connector set for the Data-Access MVP."
+      "enum": ["postgres", "redshift", "bigquery", "databricks", "mysql", "trino"],
+      "description": "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."
+    },
+    "DataSourceEnvironmentCopy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["endpoint", "credentialRef"],
+      "properties": {
+        "endpoint": {
+          "$ref": "#/definitions/DataSourceEndpoint"
+        },
+        "credentialRef": {
+          "type": "string",
+          "pattern": "^secretref://[A-Za-z0-9][A-Za-z0-9/_.:-]*$",
+          "description": "secretref URI naming the platform-held credential for this copy. The referenced value never crosses this boundary."
+        }
+      },
+      "description": "One environment's copy of a source: the same endpoint and credentialRef shapes as the top-level fields, for the same connector."
     },
     "DataSourceEndpoint": {
       "type": "object",
@@ -152,6 +181,32 @@
       "requestableByBuilders": true,
       "allowValidation": false,
       "status": "ACTIVE"
+    },
+    {
+      "tenantId": "pocketfm",
+      "sourceId": "lakehouse",
+      "connector": "trino",
+      "displayName": "Lakehouse (Trino)",
+      "endpoint": {
+        "host": "trino.internal.example.com",
+        "port": 8443,
+        "database": "hive"
+      },
+      "credentialRef": "secretref://tenants/pocketfm/sources/lakehouse/reader",
+      "environments": {
+        "development": {
+          "endpoint": {
+            "host": "trino-dev.internal.example.com",
+            "port": 8443,
+            "database": "hive_dev"
+          },
+          "credentialRef": "secretref://tenants/pocketfm/sources/lakehouse/reader-dev"
+        }
+      },
+      "provisioningMode": "byo",
+      "allowedScope": ["analytics.episode_plays"],
+      "requestableByBuilders": true,
+      "status": "ACTIVE"
     }
   ]
 }

package/schema/integration-error-details.schema.json

@@ -62,9 +62,10 @@
         "AUTH_REQUIRED",
         "UNAVAILABLE",
         "MODE_NOT_GRANTED",
-        "MODE_REQUIRED"
+        "MODE_REQUIRED",
+        "SAMPLE_ROWS_NOT_ALLOWED"
       ],
-      "description": "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."
+      "description": "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."
     }
   },
   "examples": [