@fourier-labs/harbour-contracts 0.95.0 → 0.97.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fourier-labs/harbour-contracts",
-  "version": "0.95.0",
+  "version": "0.97.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

@@ -141,7 +141,12 @@
         "zohobooks.bill.read",
         "zohobooks.invoice.create",
         "zohobooks.invoice.read",
-        "zohobooks.invoice.pdf"
+        "zohobooks.invoice.pdf",
+        "zohobooks.salesorder.list",
+        "zohobooks.salesorder.read",
+        "zohobooks.invoice.reviseDraft",
+        "zohobooks.creditnote.create",
+        "zohobooks.creditnote.read"
       ],
       "description": "Closed operation set. Extending it is a contracts change. 0.86.0 (ADR 0032) adds the forty-five Google Workspace and Microsoft 365 operations, every one user mode only: on the provider's fixed alias for the signed-in person's own data, calendar.calendar.list, calendar.event.list, calendar.event.read, calendar.event.create (a receipted write: explicit action, idempotencyKey), calendar.event.update and calendar.event.cancel (idempotent at Google, no key); drive.file.list, drive.file.search, drive.file.read, drive.file.upload and drive.folder.create (receipted writes); docs.document.read, docs.document.create (receipted), docs.document.append and docs.text.replace (no key); sheets.spreadsheet.read, sheets.values.read, sheets.values.append (receipted), sheets.values.update and sheets.values.clear (no key), sheets.spreadsheet.create (receipted); outlook.message.list, outlook.message.read, outlook.attachment.read, outlook.message.send and outlook.message.reply (receipted sends, as gmail.message.send), outlook.event.list, outlook.event.read, outlook.event.create (receipted), outlook.event.update and outlook.event.cancel (no key); onedrive.file.list, onedrive.file.search, onedrive.file.read, onedrive.file.upload and onedrive.folder.create (receipted); excel.worksheet.list, excel.range.read, excel.range.update (no key), excel.table.list, excel.row.add and excel.worksheet.add (receipted); and on a Teams channel alias (a key of the connection's `channels` map) teams.message.list, teams.message.post and teams.reply.post (receipted). 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. 0.82.0 (ADR 0028) adds phone.sms.list (app mode only, a number alias from a phone connection's `channels` map: the SMS received on that number since a time) and warehouse.table.append (app mode only on a database connection, a receipted write with idempotencyKey: rows appended to a view alias whose mapping says `access: append`). 0.83.0 (ADR 0029) adds phone.number.get (app mode only, read-only, no input, on a number alias from a phone connection's `channels` map: the E.164 number that alias maps to, so the app — or a computer-use agent it drives — can type it into a portal that signs in by mobile number). 0.85.0 (ADR 0031) raises warehouse.table.append's `rows` from 1..500 to 1..5000 records (the byte cap stays governance's, now 8 MiB), so a downloaded report of a few thousand rows lands in one call."
     },
@@ -599,6 +604,21 @@
             },
             "zohobooks.invoice.pdf": {
               "$ref": "#/definitions/UserModeChannelOperation"
+            },
+            "zohobooks.salesorder.list": {
+              "$ref": "#/definitions/UserModeChannelOperation"
+            },
+            "zohobooks.salesorder.read": {
+              "$ref": "#/definitions/UserModeChannelOperation"
+            },
+            "zohobooks.invoice.reviseDraft": {
+              "$ref": "#/definitions/UserModeChannelOperation"
+            },
+            "zohobooks.creditnote.create": {
+              "$ref": "#/definitions/UserModeChannelOperation"
+            },
+            "zohobooks.creditnote.read": {
+              "$ref": "#/definitions/UserModeChannelOperation"
             }
           }
         }
@@ -1085,6 +1105,31 @@
                       "required": [
                         "zohobooks.invoice.pdf"
                       ]
+                    },
+                    {
+                      "required": [
+                        "zohobooks.salesorder.list"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "zohobooks.salesorder.read"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "zohobooks.invoice.reviseDraft"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "zohobooks.creditnote.create"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "zohobooks.creditnote.read"
+                      ]
                     }
                   ]
                 }
@@ -1549,6 +1594,31 @@
                       "required": [
                         "zohobooks.invoice.pdf"
                       ]
+                    },
+                    {
+                      "required": [
+                        "zohobooks.salesorder.list"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "zohobooks.salesorder.read"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "zohobooks.invoice.reviseDraft"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "zohobooks.creditnote.create"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "zohobooks.creditnote.read"
+                      ]
                     }
                   ]
                 }

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

@@ -17,7 +17,7 @@
     "status": { "$ref": "#/definitions/DataGrantV2Status" },
     "operations": {
       "type": "array",
-      "maxItems": 86,
+      "maxItems": 91,
       "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 seventy-eight SaaS operations (0.86.0: eleven Slack and Gmail, eleven Basecamp, nine SharePoint, two phone, forty-five Google Workspace and Microsoft 365); a database grant holds up to two (warehouse.view.read, warehouse.table.append)."
@@ -65,7 +65,7 @@
       "description": "Only for SaaS grants mixing reviewed and automatic access: the previously human-reviewed scope. The remaining scope must satisfy current automatic rules. Homogeneous grants continue using approvedBy alone. Governance validates this is a subset of the grant; database behaviour is unchanged.",
       "properties": {
         "operations": {
-          "type": "array", "maxItems": 86, "uniqueItems": true,
+          "type": "array", "maxItems": 91, "uniqueItems": true,
           "items": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationOperation" }
         },
         "resources": {

package/schema/deployment-app-registration.schema.json

@@ -145,6 +145,56 @@
             }
           }
         }
+      ],
+      "description": "Temporary rolling-release input for email targets; writers use eventTarget. Remove after old deployments are migrated."
+    },
+    "eventTarget": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "versionId",
+            "jobs",
+            "functionArn"
+          ],
+          "properties": {
+            "functionArn": {
+              "type": "string",
+              "pattern": "^arn:aws:lambda:[a-z0-9-]+:[0-9]{12}:function:[A-Za-z0-9-_]+$"
+            },
+            "versionId": {
+              "type": "string",
+              "minLength": 1
+            },
+            "jobs": {
+              "$ref": "#/definitions/eventJobs"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "versionId",
+            "jobs",
+            "gatewayUrl"
+          ],
+          "properties": {
+            "versionId": {
+              "type": "string",
+              "minLength": 1
+            },
+            "jobs": {
+              "$ref": "#/definitions/eventJobs"
+            },
+            "gatewayUrl": {
+              "type": "string",
+              "format": "uri",
+              "pattern": "^https://[^/]+/_harbour/internal/mail-arrival$"
+            }
+          }
+        }
       ]
     }
   },
@@ -178,6 +228,27 @@
           "workloadPrincipalArn"
         ]
       }
+    },
+    {
+      "if": {
+        "required": [
+          "eventTarget"
+        ]
+      },
+      "then": {
+        "required": [
+          "environment",
+          "workloadPrincipalArn"
+        ]
+      }
+    },
+    {
+      "not": {
+        "required": [
+          "eventTarget",
+          "mailArrivalTarget"
+        ]
+      }
     }
   ],
   "definitions": {
@@ -198,40 +269,130 @@
             "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$"
           },
           "trigger": {
-            "type": "object",
-            "additionalProperties": false,
-            "required": [
-              "type",
-              "connection",
-              "resource"
-            ],
-            "properties": {
-              "type": {
-                "const": "email.arrived"
-              },
-              "connection": {
-                "type": "string",
-                "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$"
-              },
-              "resource": {
-                "const": "inbox"
+            "$ref": "#/definitions/emailArrivalTrigger"
+          }
+        }
+      }
+    },
+    "eventJobs": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 100,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "name",
+          "trigger"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$"
+          },
+          "trigger": {
+            "oneOf": [
+              {
+                "$ref": "#/definitions/emailArrivalTrigger"
               },
-              "filter": {
+              {
                 "type": "object",
                 "additionalProperties": false,
+                "required": [
+                  "type",
+                  "connection",
+                  "resource"
+                ],
                 "properties": {
-                  "from": {
+                  "type": {
+                    "const": "file.created"
+                  },
+                  "connection": {
                     "type": "string",
-                    "minLength": 1,
-                    "maxLength": 320
+                    "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$"
                   },
-                  "subjectContains": {
+                  "resource": {
                     "type": "string",
                     "minLength": 1,
                     "maxLength": 320
+                  },
+                  "folderId": {
+                    "type": "string",
+                    "pattern": "^[A-Za-z0-9!._,=-]{1,256}$"
+                  },
+                  "driveId": {
+                    "type": "string",
+                    "pattern": "^[A-Za-z0-9!._,=-]{1,256}$"
+                  },
+                  "mimeTypes": {
+                    "type": "array",
+                    "minItems": 1,
+                    "maxItems": 4,
+                    "uniqueItems": true,
+                    "items": {
+                      "enum": [
+                        "application/pdf",
+                        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+                        "image/png",
+                        "image/jpeg"
+                      ]
+                    }
+                  },
+                  "configurableFolder": {
+                    "const": true,
+                    "description": "The app owner may select a folder at runtime within the declared connection and resource."
+                  }
+                },
+                "if": {
+                  "not": {
+                    "required": [
+                      "configurableFolder"
+                    ]
                   }
+                },
+                "then": {
+                  "required": [
+                    "folderId"
+                  ]
                 }
               }
+            ]
+          }
+        }
+      }
+    },
+    "emailArrivalTrigger": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "type",
+        "connection",
+        "resource"
+      ],
+      "properties": {
+        "type": {
+          "const": "email.arrived"
+        },
+        "connection": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$"
+        },
+        "resource": {
+          "const": "inbox"
+        },
+        "filter": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "from": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 320
+            },
+            "subjectContains": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 320
             }
           }
         }

package/schema/file-arrival.schema.json

@@ -0,0 +1,88 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://harbour.dev/schema/file-arrival.schema.json",
+  "title": "FileArrival",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "type",
+    "provider",
+    "sourceId",
+    "fileId",
+    "folderId",
+    "name",
+    "mimeType",
+    "size",
+    "createdAt",
+    "observedAt"
+  ],
+  "properties": {
+    "type": {
+      "const": "file.created"
+    },
+    "provider": {
+      "enum": [
+        "drive",
+        "sharepoint"
+      ]
+    },
+    "sourceId": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$"
+    },
+    "fileId": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9!._,=-]{1,256}$"
+    },
+    "folderId": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9!._,=-]{1,256}$"
+    },
+    "driveId": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9!._,=-]{1,256}$"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1024
+    },
+    "mimeType": {
+      "enum": [
+        "application/pdf",
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        "image/png",
+        "image/jpeg"
+      ]
+    },
+    "size": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "observedAt": {
+      "type": "string",
+      "format": "date-time"
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "provider": {
+            "const": "sharepoint"
+          }
+        }
+      },
+      "then": {
+        "required": [
+          "driveId"
+        ]
+      }
+    }
+  ]
+}