@fourier-labs/harbour-contracts 0.74.0 → 0.76.0

package/gen-ts/saas-connection.ts

@@ -2,9 +2,9 @@
 // Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
 
 /**
- * Slack carries an installation and a channel map; Gmail is user-consent only.
+ * Slack carries an installation and a channel map; Gmail is user-consent only; Basecamp is user-consent only with an IT-pinned account and a project map in `channels`.
  */
-export type SaasProvider = 'slack' | 'gmail';
+export type SaasProvider = 'slack' | 'gmail' | 'basecamp';
 /**
  * DISABLED stops every app call immediately (details.code CONNECTION_DISABLED).
  */
@@ -27,7 +27,7 @@ export type ExternalRecipientMode = 'block' | 'allowlist' | 'allow';
 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). 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.
+ * 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. A Basecamp connection (0.76.0, ADR 0022) has no installation either: IT pins the company's Basecamp `account` (chosen from the accounts IT's own Basecamp sign-in belongs to) and maps project aliases to project ids in `channels`; basecamp.project.list runs on the fixed `account` 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';
@@ -45,20 +45,21 @@ export interface SaasConnection {
    */
   version: number;
   installation?: SaasInstallation;
+  account?: BasecampAccount;
   /**
-   * Logical channel alias -> provider channel ID, shared by every environment. Always empty for Gmail.
+   * Logical alias → provider resource id: a Slack channel id or a Basecamp project id. Always empty for Gmail.
    */
   channels: {
     /**
-     * Provider channel ID; only public, non-archived channels are valid.
+     * A Slack channel id (public, non-archived) or a Basecamp project id (digits).
      */
     [k: string]: string;
   };
   /**
-   * Operations IT allows apps to request on this connection: the provider's own SaaS operations (Slack: slack.channel.history, slack.message.post, slack.message.update, slack.message.delete, slack.dm.send, slack.user.lookup; Gmail: gmail.thread.list, gmail.thread.read, gmail.message.read, gmail.message.send, gmail.attachment.read). Never warehouse.view.read.
+   * Operations IT allows apps to request on this connection: the provider's own SaaS operations (Slack: slack.channel.history, slack.message.post, slack.message.update, slack.message.delete, slack.dm.send, slack.user.lookup; Gmail: gmail.thread.list, gmail.thread.read, gmail.message.read, gmail.message.send, gmail.attachment.read; Basecamp (0.76.0): 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). Never warehouse.view.read.
    *
    * @minItems 1
-   * @maxItems 11
+   * @maxItems 22
    */
   operations: (
     | 'slack.channel.history'
@@ -72,6 +73,17 @@ export interface SaasConnection {
     | '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'
   )[];
@@ -138,6 +150,19 @@ export interface SaasInstallation {
    */
   botName?: string;
 }
+/**
+ * The pinned Basecamp account (0.76.0, Basecamp only): the one account, among those IT's own Basecamp sign-in belongs to, that every user token on this connection must also belong to and that every project id in `channels` lives in. Absent until IT chooses it; governance refuses every basecamp.* call until then.
+ */
+export interface BasecampAccount {
+  /**
+   * The Basecamp account id, the first path segment of the API base URL.
+   */
+  id: string;
+  /**
+   * The account's name as Basecamp shows it, for IT to recognise.
+   */
+  name: string;
+}
 export interface DevelopmentPreapproval {
   /**
    * Auto-approve development requests within the allowlist.

package/package.json

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

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": {