@fourier-labs/harbour-contracts 0.77.0 → 0.78.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 (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.",
+  "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 (thirty-three operations since 0.78.0, ADR 0018, ADR 0022 and ADR 0024). Each operation carries a fixed identity mode \u2014 slack.dm.send=app, slack.user.lookup=app, every gmail.* operation=user, every basecamp.* operation=user, every sharepoint.* 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, Basecamp and SharePoint 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. SharePoint (0.78.0, ADR 0024) is user-mode only as well: every sharepoint.* operation runs on a site alias IT mapped in the connection's `channels` map (a Microsoft Graph site id), so Graph itself refuses a list, item or file outside that site. 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": [
@@ -37,6 +37,11 @@
       "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."
     },
+    "GraphId": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9!._,=-]{1,256}$",
+      "description": "A Microsoft Graph id (0.78.0): a SharePoint list (a GUID), list item (digits), drive (`b!...`) or drive item, as Graph names it \u2014 opaque, 1..256 characters of letters, digits and `!._,=-`. How every sharepoint.* result names one and every sharepoint.* input takes one back."
+    },
     "IntegrationConnectionKind": {
       "type": "string",
       "enum": [
@@ -70,10 +75,19 @@
         "basecamp.comment.post",
         "basecamp.campfire.post",
         "basecamp.people.list",
+        "sharepoint.list.list",
+        "sharepoint.item.list",
+        "sharepoint.item.create",
+        "sharepoint.item.update",
+        "sharepoint.drive.list",
+        "sharepoint.file.list",
+        "sharepoint.file.search",
+        "sharepoint.file.read",
+        "sharepoint.file.upload",
         "warehouse.view.read",
         "service.request"
       ],
-      "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."
+      "description": "Closed operation set. Extending it is a contracts change. 0.78.0 (ADR 0024) adds the nine SharePoint operations, every one user mode only on a site alias (a key of the connection's `channels` map, holding a Microsoft Graph site id): sharepoint.list.list, sharepoint.item.list, sharepoint.item.create (a receipted write: explicit action, idempotencyKey), sharepoint.item.update (a PATCH, idempotent at Graph, no key), sharepoint.drive.list, sharepoint.file.list, sharepoint.file.search, sharepoint.file.read and sharepoint.file.upload (a receipted write). 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",
@@ -163,7 +177,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.",
+      "description": "Every gmail.* operation (resource: the fixed `inbox` alias), 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) and since 0.78.0 every sharepoint.* operation (resource: a site alias from the connection's `channels` map): user mode only — the app acts as the signed-in person after their own consent.",
       "properties": {
         "identity": {
           "type": "string",
@@ -320,6 +334,33 @@
             "basecamp.people.list": {
               "$ref": "#/definitions/UserModeChannelOperation"
             },
+            "sharepoint.list.list": {
+              "$ref": "#/definitions/UserModeChannelOperation"
+            },
+            "sharepoint.item.list": {
+              "$ref": "#/definitions/UserModeChannelOperation"
+            },
+            "sharepoint.item.create": {
+              "$ref": "#/definitions/UserModeChannelOperation"
+            },
+            "sharepoint.item.update": {
+              "$ref": "#/definitions/UserModeChannelOperation"
+            },
+            "sharepoint.drive.list": {
+              "$ref": "#/definitions/UserModeChannelOperation"
+            },
+            "sharepoint.file.list": {
+              "$ref": "#/definitions/UserModeChannelOperation"
+            },
+            "sharepoint.file.search": {
+              "$ref": "#/definitions/UserModeChannelOperation"
+            },
+            "sharepoint.file.read": {
+              "$ref": "#/definitions/UserModeChannelOperation"
+            },
+            "sharepoint.file.upload": {
+              "$ref": "#/definitions/UserModeChannelOperation"
+            },
             "warehouse.view.read": {
               "$ref": "#/definitions/AppModeViewOperation"
             },
@@ -482,6 +523,51 @@
                         "basecamp.people.list"
                       ]
                     },
+                    {
+                      "required": [
+                        "sharepoint.list.list"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "sharepoint.item.list"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "sharepoint.item.create"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "sharepoint.item.update"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "sharepoint.drive.list"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "sharepoint.file.list"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "sharepoint.file.search"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "sharepoint.file.read"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "sharepoint.file.upload"
+                      ]
+                    },
                     {
                       "required": [
                         "service.request"
@@ -621,6 +707,51 @@
                         "basecamp.people.list"
                       ]
                     },
+                    {
+                      "required": [
+                        "sharepoint.list.list"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "sharepoint.item.list"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "sharepoint.item.create"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "sharepoint.item.update"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "sharepoint.drive.list"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "sharepoint.file.list"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "sharepoint.file.search"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "sharepoint.file.read"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "sharepoint.file.upload"
+                      ]
+                    },
                     {
                       "required": [
                         "warehouse.view.read"
@@ -818,6 +949,65 @@
             }
           }
         },
+        "company-sharepoint": {
+          "kind": "saas",
+          "operations": {
+            "sharepoint.list.list": {
+              "identity": "user",
+              "resources": [
+                "intranet"
+              ]
+            },
+            "sharepoint.item.list": {
+              "identity": "user",
+              "resources": [
+                "intranet"
+              ]
+            },
+            "sharepoint.item.create": {
+              "identity": "user",
+              "resources": [
+                "intranet"
+              ]
+            },
+            "sharepoint.item.update": {
+              "identity": "user",
+              "resources": [
+                "intranet"
+              ]
+            },
+            "sharepoint.drive.list": {
+              "identity": "user",
+              "resources": [
+                "intranet"
+              ]
+            },
+            "sharepoint.file.list": {
+              "identity": "user",
+              "resources": [
+                "intranet"
+              ]
+            },
+            "sharepoint.file.search": {
+              "identity": "user",
+              "resources": [
+                "intranet"
+              ]
+            },
+            "sharepoint.file.read": {
+              "identity": "user",
+              "resources": [
+                "intranet"
+              ]
+            },
+            "sharepoint.file.upload": {
+              "identity": "user",
+              "resources": [
+                "intranet"
+              ]
+            }
+          }
+        },
         "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, 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.",
+  "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, a SharePoint site 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": 22,
+      "maxItems": 31,
       "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 twenty-two SaaS operations (0.76.0: eleven Slack and Gmail, eleven Basecamp); a database grant holds one."
+      "description": "Approved operations; each must match this grant's mode. Empty until the first approval. At most the thirty-one SaaS operations (0.78.0: eleven Slack and Gmail, eleven Basecamp, nine SharePoint); a database grant holds one."
     },
     "resources": {
       "type": "array",
@@ -62,7 +62,7 @@
       "type": "object",
       "additionalProperties": false,
       "required": ["name"],
-      "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.",
+      "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), a SharePoint site alias (0.78.0), or a warehouse view alias with the approved columns.",
       "properties": {
         "name": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationAlias" },
         "columns": {