@fourier-labs/harbour-contracts 0.90.0 → 0.92.0

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

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://schemas.harbour.dev/integration-execute-result.schema.json",
   "title": "IntegrationExecuteResult",
-  "description": "The `data` member of a successful execute response `{data, requestId}`; the SDK unwraps `data`. Exactly one of the operation results (eighty-one operations since 0.86.0, ADR 0018, ADR 0022, ADR 0024, ADR 0028, ADR 0029 and ADR 0032): slack.channel.history -> {messages, hasMore, nextCursor?} (plain text/IDs/time, plus the display name and emoji icon a per-app-named app post carries \u2014 authorName/authorIcon, 0.55.0 \u2014 never the provider payload; `nextCursor` when hasMore, to pass as the next read's `cursor`); slack.message.post, slack.message.update, slack.message.delete -> {messageId} (the Slack ts); slack.dm.send -> {messageId, channelId} (the ts and the DM channel it went to); slack.user.lookup -> {userId, displayName}; gmail.thread.list -> {threads, hasMore, nextPageToken?} (newest matching threads; each `messageId` is the thread's newest message, what gmail.message.read takes; `nextPageToken` when hasMore); gmail.thread.read -> {id, emails} (every message of the thread, oldest first, each shaped like a gmail.message.read result); gmail.message.read -> {id, threadId, subject, from, to, date, text, truncated, attachments?} (headers plus the plain text with html stripped, cut at 16 KiB with `truncated` set; `attachments` lists the files without their bytes, which gmail.attachment.read fetches by id); gmail.attachment.read -> {filename, mimeType, size, dataBase64}; gmail.message.send -> {messageId, threadId} (the Gmail ids of the sent message and its thread); warehouse.view.read -> {rows, truncated} (rows keyed by the selected columns, or for an aggregate read by the groupBy columns then the aggregate aliases; decimal/64-bit values as strings, dates as ISO strings; since 0.70.0 every server sends `truncated`, true when more rows matched than `limit` \u2014 the server reads limit+1 rows to know \u2014 so the rows are incomplete and must not be totalled or averaged; a server before 0.70.0 omitted it). Basecamp (0.76.0, ADR 0022; every id a string of digits, every page at most 100 items, `nextPageToken` only when hasMore, text cut at 16 KiB like Gmail): basecamp.project.list -> {projects, hasMore, nextPageToken?}; basecamp.todolist.list -> {todolists, hasMore, nextPageToken?}; basecamp.todo.list -> {todos, hasMore, nextPageToken?}; basecamp.message.list -> {boardMessages, hasMore, nextPageToken?} (`boardMessages`, not `messages`, which is the Slack history shape); basecamp.comment.list -> {comments, hasMore, nextPageToken?}; basecamp.people.list -> {people, hasMore, nextPageToken?}; basecamp.todo.create, basecamp.message.post, basecamp.comment.post, basecamp.campfire.post -> {id, appUrl} (the new recording and its Basecamp page); basecamp.todo.complete -> {id, completed} with completed always true. SharePoint (0.78.0, ADR 0024; every id a Microsoft Graph id, `nextPageToken` only when hasMore and up to 2048 characters for a Graph `$skiptoken`): sharepoint.list.list -> {lists, hasMore, nextPageToken?} (at most 100, hidden lists dropped); sharepoint.item.list -> {items, hasMore, nextPageToken?} (at most 50; each item's `fields` are the column values as Graph returns them with the system columns dropped, the whole object cut at 16 KiB); sharepoint.drive.list -> {drives, hasMore, nextPageToken?}; sharepoint.file.list and sharepoint.file.search -> {files, hasMore, nextPageToken?} (at most 100 entries, folders included with isFolder); sharepoint.file.read -> {id, filename, mimeType, size, dataBase64} (the Gmail attachment shape plus the file's id; at most 2 MiB of bytes); sharepoint.item.create -> {id, webUrl} (the new item and its SharePoint page); sharepoint.item.update -> {id}; sharepoint.file.upload -> {id, filename, webUrl} (the stored file, under the name `conflict` rename may have given it). Google Workspace and Microsoft 365 (0.86.0, ADR 0032; every page at most 100 items, `nextPageToken` only when hasMore, up to 2048 characters): calendar.calendar.list -> {calendars, hasMore, nextPageToken?}; calendar.event.list and outlook.event.list -> {events, hasMore, nextPageToken?}; calendar.event.read and outlook.event.read -> the event itself, {id, title, start, end, allDay, timeZone?, location?, description?, attendees, organizer?, webUrl, eventStatus} (the CalendarEvent shape spread at the top level, the way gmail.message.read spreads GmailMessage; `eventStatus`, because `status` is the HTTP status of a service.request result); calendar.event.create and outlook.event.create -> {id, webUrl}; calendar.event.update, calendar.event.cancel, outlook.event.update, outlook.event.cancel -> {id}; drive.file.list, drive.file.search, onedrive.file.list, onedrive.file.search -> {files, hasMore, nextPageToken?} (the SharePoint entry shape); drive.file.read and onedrive.file.read -> {id, filename, mimeType, size, dataBase64} (the sharepoint.file.read shape; `filename` and `mimeType` are the stored or exported name and type); drive.file.upload and onedrive.file.upload -> {id, filename, webUrl}; drive.folder.create and onedrive.folder.create -> {id, webUrl}; docs.document.read -> {id, title, text, revisionId, webUrl, truncated} (the body as plain text cut at 64 KiB); docs.document.create -> {id, webUrl}; docs.document.append -> {id, revisionId}; docs.text.replace -> {id, replaced} (how many occurrences changed); sheets.spreadsheet.read -> {id, title, sheets, webUrl}; sheets.values.read -> {range, values} (the range Google answered with and the cells as rows; a trailing empty row or cell is dropped by Google); sheets.values.append -> {range, updatedRows}; sheets.values.update -> {range, updatedCells}; sheets.values.clear -> {range}; sheets.spreadsheet.create -> {id, webUrl}; outlook.message.list -> {mailMessages, hasMore, nextPageToken?} (`mailMessages`, not `messages`, which is the Slack history shape); outlook.message.read -> the gmail.message.read shape {id, threadId, subject, from, to, date, text, truncated, attachments?} with `threadId` the Graph conversationId; outlook.attachment.read -> {id, filename, mimeType, size, dataBase64}; outlook.message.send and outlook.message.reply -> {id} (the sent message's id, which Graph does not return for a send: governance's own internetMessageId); excel.worksheet.list -> {worksheets}; excel.range.read -> {address, values}; excel.range.update -> {address, updatedCells}; excel.table.list -> {tables}; excel.row.add -> {index, updatedRows} (the index of the first added row); excel.worksheet.add -> {id, name}; teams.message.list -> {teamsMessages, hasMore, nextPageToken?} (`teamsMessages`, apart from Slack's `messages`); teams.message.post and teams.reply.post -> {id, webUrl}. An unknown send outcome is never a result; it is an error with details.code SEND_OUTCOME_UNKNOWN. A whole result over 1 MiB is rejected, never cut down to fit \u2014 except a gmail.attachment.read, a sharepoint.file.read, a drive.file.read, an onedrive.file.read or an outlook.attachment.read, whose single file is bounded by its own 2 MiB.",
+  "description": "The `data` member of a successful execute response `{data, requestId}`; the SDK unwraps `data`. Exactly one of the operation results (eighty-one operations since 0.86.0, ADR 0018, ADR 0022, ADR 0024, ADR 0028, ADR 0029 and ADR 0032): slack.channel.history -> {messages, hasMore, nextCursor?} (plain text/IDs/time, plus the display name and emoji icon a per-app-named app post carries — authorName/authorIcon, 0.55.0 — never the provider payload; `nextCursor` when hasMore, to pass as the next read's `cursor`); slack.message.post, slack.message.update, slack.message.delete -> {messageId} (the Slack ts); slack.dm.send -> {messageId, channelId} (the ts and the DM channel it went to); slack.user.lookup -> {userId, displayName}; gmail.thread.list -> {threads, hasMore, nextPageToken?} (newest matching threads; each `messageId` is the thread's newest message, what gmail.message.read takes; `nextPageToken` when hasMore); gmail.thread.read -> {id, emails} (every message of the thread, oldest first, each shaped like a gmail.message.read result); gmail.message.read -> {id, threadId, subject, from, to, date, text, truncated, attachments?} (headers plus the plain text with html stripped, cut at 16 KiB with `truncated` set; `attachments` lists the files without their bytes, which gmail.attachment.read fetches by id); gmail.attachment.read -> {filename, mimeType, size, dataBase64}; gmail.message.send -> {messageId, threadId} (the Gmail ids of the sent message and its thread); warehouse.view.read -> {rows, truncated} (rows keyed by the selected columns, or for an aggregate read by the groupBy columns then the aggregate aliases; decimal/64-bit values as strings, dates as ISO strings; since 0.70.0 every server sends `truncated`, true when more rows matched than `limit` — the server reads limit+1 rows to know — so the rows are incomplete and must not be totalled or averaged; a server before 0.70.0 omitted it). Basecamp (0.76.0, ADR 0022; every id a string of digits, every page at most 100 items, `nextPageToken` only when hasMore, text cut at 16 KiB like Gmail): basecamp.project.list -> {projects, hasMore, nextPageToken?}; basecamp.todolist.list -> {todolists, hasMore, nextPageToken?}; basecamp.todo.list -> {todos, hasMore, nextPageToken?}; basecamp.message.list -> {boardMessages, hasMore, nextPageToken?} (`boardMessages`, not `messages`, which is the Slack history shape); basecamp.comment.list -> {comments, hasMore, nextPageToken?}; basecamp.people.list -> {people, hasMore, nextPageToken?}; basecamp.todo.create, basecamp.message.post, basecamp.comment.post, basecamp.campfire.post -> {id, appUrl} (the new recording and its Basecamp page); basecamp.todo.complete -> {id, completed} with completed always true. SharePoint (0.78.0, ADR 0024; every id a Microsoft Graph id, `nextPageToken` only when hasMore and up to 2048 characters for a Graph `$skiptoken`): sharepoint.list.list -> {lists, hasMore, nextPageToken?} (at most 100, hidden lists dropped); sharepoint.item.list -> {items, hasMore, nextPageToken?} (at most 50; each item's `fields` are the column values as Graph returns them with the system columns dropped, the whole object cut at 16 KiB); sharepoint.drive.list -> {drives, hasMore, nextPageToken?}; sharepoint.file.list and sharepoint.file.search -> {files, hasMore, nextPageToken?} (at most 100 entries, folders included with isFolder); sharepoint.file.read -> {id, filename, mimeType, size, dataBase64} (the Gmail attachment shape plus the file's id; at most 2 MiB of bytes); sharepoint.item.create -> {id, webUrl} (the new item and its SharePoint page); sharepoint.item.update -> {id}; sharepoint.file.upload -> {id, filename, webUrl} (the stored file, under the name `conflict` rename may have given it). Google Workspace and Microsoft 365 (0.86.0, ADR 0032; every page at most 100 items, `nextPageToken` only when hasMore, up to 2048 characters): calendar.calendar.list -> {calendars, hasMore, nextPageToken?}; calendar.event.list and outlook.event.list -> {events, hasMore, nextPageToken?}; calendar.event.read and outlook.event.read -> the event itself, {id, title, start, end, allDay, timeZone?, location?, description?, attendees, organizer?, webUrl, eventStatus} (the CalendarEvent shape spread at the top level, the way gmail.message.read spreads GmailMessage; `eventStatus`, because `status` is the HTTP status of a service.request result); calendar.event.create and outlook.event.create -> {id, webUrl}; calendar.event.update, calendar.event.cancel, outlook.event.update, outlook.event.cancel -> {id}; drive.file.list, drive.file.search, onedrive.file.list, onedrive.file.search -> {files, hasMore, nextPageToken?} (the SharePoint entry shape); drive.file.read and onedrive.file.read -> {id, filename, mimeType, size, dataBase64} (the sharepoint.file.read shape; `filename` and `mimeType` are the stored or exported name and type); drive.file.upload and onedrive.file.upload -> {id, filename, webUrl}; drive.folder.create and onedrive.folder.create -> {id, webUrl}; docs.document.read -> {id, title, text, revisionId, webUrl, truncated} (the body as plain text cut at 64 KiB); docs.document.create -> {id, webUrl}; docs.document.append -> {id, revisionId}; docs.text.replace -> {id, replaced} (how many occurrences changed); sheets.spreadsheet.read -> {id, title, sheets, webUrl}; sheets.values.read -> {range, values} (the range Google answered with and the cells as rows; a trailing empty row or cell is dropped by Google); sheets.values.append -> {range, updatedRows}; sheets.values.update -> {range, updatedCells}; sheets.values.clear -> {range}; sheets.spreadsheet.create -> {id, webUrl}; outlook.message.list -> {mailMessages, hasMore, nextPageToken?} (`mailMessages`, not `messages`, which is the Slack history shape); outlook.message.read -> the gmail.message.read shape {id, threadId, subject, from, to, date, text, truncated, attachments?} with `threadId` the Graph conversationId; outlook.attachment.read -> {id, filename, mimeType, size, dataBase64}; outlook.message.send and outlook.message.reply -> {id} (the sent message's id, which Graph does not return for a send: governance's own internetMessageId); excel.worksheet.list -> {worksheets}; excel.range.read -> {address, values}; excel.range.update -> {address, updatedCells}; excel.table.list -> {tables}; excel.row.add -> {index, updatedRows} (the index of the first added row); excel.worksheet.add -> {id, name}; teams.message.list -> {teamsMessages, hasMore, nextPageToken?} (`teamsMessages`, apart from Slack's `messages`); teams.message.post and teams.reply.post -> {id, webUrl}. An unknown send outcome is never a result; it is an error with details.code SEND_OUTCOME_UNKNOWN. A whole result over 1 MiB is rejected, never cut down to fit — except a gmail.attachment.read, a sharepoint.file.read, a drive.file.read, an onedrive.file.read or an outlook.attachment.read, whose single file is bounded by its own 2 MiB.",
   "type": "object",
   "additionalProperties": false,
   "properties": {
@@ -429,7 +429,203 @@
         "type": "string"
       }
     },
-    "body": {}
+    "body": {},
+    "booksDocument": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "number",
+        "status",
+        "currency",
+        "total",
+        "lineItems"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[0-9]{1,32}$",
+          "maxLength": 32
+        },
+        "number": {
+          "type": "string",
+          "maxLength": 2000
+        },
+        "status": {
+          "type": "string",
+          "maxLength": 2000
+        },
+        "currency": {
+          "type": "string",
+          "maxLength": 2000
+        },
+        "total": {
+          "type": "string",
+          "maxLength": 64
+        },
+        "vendorId": {
+          "type": "string",
+          "pattern": "^[0-9]{1,32}$",
+          "maxLength": 32
+        },
+        "customerId": {
+          "type": "string",
+          "pattern": "^[0-9]{1,32}$",
+          "maxLength": 32
+        },
+        "lineItems": {
+          "type": "array",
+          "maxItems": 100,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "itemId",
+              "quantity",
+              "rate",
+              "total"
+            ],
+            "properties": {
+              "itemId": {
+                "type": "string",
+                "pattern": "^[0-9]{1,32}$",
+                "maxLength": 32
+              },
+              "quantity": {
+                "type": "string",
+                "maxLength": 64
+              },
+              "rate": {
+                "type": "string",
+                "maxLength": 64
+              },
+              "total": {
+                "type": "string",
+                "maxLength": 64
+              },
+              "description": {
+                "type": "string",
+                "maxLength": 2000
+              }
+            }
+          }
+        }
+      }
+    },
+    "booksContacts": {
+      "type": "array",
+      "maxItems": 100,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "name",
+          "type"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[0-9]{1,32}$",
+            "maxLength": 32
+          },
+          "name": {
+            "type": "string",
+            "maxLength": 2000
+          },
+          "type": {
+            "type": "string",
+            "maxLength": 2000
+          }
+        }
+      }
+    },
+    "booksPurchaseOrders": {
+      "type": "array",
+      "maxItems": 100,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "number",
+          "status",
+          "currency",
+          "total",
+          "lineItems"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[0-9]{1,32}$",
+            "maxLength": 32
+          },
+          "number": {
+            "type": "string",
+            "maxLength": 2000
+          },
+          "status": {
+            "type": "string",
+            "maxLength": 2000
+          },
+          "currency": {
+            "type": "string",
+            "maxLength": 2000
+          },
+          "total": {
+            "type": "string",
+            "maxLength": 64
+          },
+          "vendorId": {
+            "type": "string",
+            "pattern": "^[0-9]{1,32}$",
+            "maxLength": 32
+          },
+          "customerId": {
+            "type": "string",
+            "pattern": "^[0-9]{1,32}$",
+            "maxLength": 32
+          },
+          "lineItems": {
+            "type": "array",
+            "maxItems": 100,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "itemId",
+                "quantity",
+                "rate",
+                "total"
+              ],
+              "properties": {
+                "itemId": {
+                  "type": "string",
+                  "pattern": "^[0-9]{1,32}$",
+                  "maxLength": 32
+                },
+                "quantity": {
+                  "type": "string",
+                  "maxLength": 64
+                },
+                "rate": {
+                  "type": "string",
+                  "maxLength": 64
+                },
+                "total": {
+                  "type": "string",
+                  "maxLength": 64
+                },
+                "description": {
+                  "type": "string",
+                  "maxLength": 2000
+                }
+              }
+            }
+          }
+        }
+      }
+    }
   },
   "oneOf": [
     {
@@ -891,6 +1087,42 @@
           "nextPageToken"
         ]
       }
+    },
+    {
+      "required": [
+        "booksContacts",
+        "hasMore"
+      ],
+      "propertyNames": {
+        "enum": [
+          "booksContacts",
+          "hasMore",
+          "nextPageToken"
+        ]
+      }
+    },
+    {
+      "required": [
+        "booksPurchaseOrders",
+        "hasMore"
+      ],
+      "propertyNames": {
+        "enum": [
+          "booksPurchaseOrders",
+          "hasMore",
+          "nextPageToken"
+        ]
+      }
+    },
+    {
+      "required": [
+        "booksDocument"
+      ],
+      "propertyNames": {
+        "enum": [
+          "booksDocument"
+        ]
+      }
     }
   ],
   "definitions": {

package/schema/mail-arrival-event.schema.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://contracts.harbour.dev/mail-arrival-event.schema.json",
+  "title": "MailArrivalEvent",
+  "description": "IAM-authorized invocation of a deployed app Event Function. The delivery ID is stable across notification retries; runtime deduplicates before running the declared job. No tokens or message bodies.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "mailArrival"
+  ],
+  "properties": {
+    "mailArrival": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "deliveryId",
+        "job",
+        "owner",
+        "input"
+      ],
+      "properties": {
+        "deliveryId": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "job": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$"
+        },
+        "owner": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 320
+        },
+        "input": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "provider",
+            "sourceId",
+            "messageId",
+            "threadId",
+            "receivedAt"
+          ],
+          "properties": {
+            "provider": {
+              "enum": [
+                "gmail",
+                "outlook"
+              ]
+            },
+            "sourceId": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 64
+            },
+            "messageId": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 2048
+            },
+            "threadId": {
+              "type": "string",
+              "maxLength": 2048
+            },
+            "receivedAt": {
+              "type": "string",
+              "format": "date-time"
+            }
+          }
+        }
+      }
+    }
+  }
+}