@fourier-labs/harbour-contracts 0.73.0 → 0.76.0

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

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://schemas.harbour.dev/integration-execute-request.schema.json",
   "title": "IntegrationExecuteRequest",
-  "description": "Body of POST /_harbour/integrations/execute (app SDK), forwarded unchanged to the governance development and runtime execute routes. Exactly one declared operation against one declared resource. The identity mode is fixed by the operation for every operation but the declared-mode Slack operations (slack.channel.history, slack.message.post, slack.message.update, slack.message.delete; 0.71.0 widened history), and always enforced from an approved grant; any identity/userId/scope field is rejected by additionalProperties. A declared-mode operation runs as the app (for a post: the IT-approved per-app name from the grant, plus a \"Posted by <app> on Isomorph\" footer) or as the signed-in person (no name, no footer) \u2014 the same input either way \u2014 and since 0.55.0 the call names which of the app's approved modes it runs under (`mode`): required when IT approved both modes for the app (MODE_REQUIRED otherwise), optional when it approved one (that one is used), and a named mode without an approved grant is refused (MODE_NOT_GRANTED) rather than served under the other, so approval order never decides what a call does. Per-operation input bounds (0.71.0, ADR 0018): slack.channel.history {limit? 1..100, default 15, cursor?, oldest?, latest?}; slack.message.post {text 1..4000 chars, threadId?, format? plain|mrkdwn} and a required idempotencyKey retained across retries of one explicit Send; slack.message.update {messageId, text, format?}; slack.message.delete {messageId}; slack.dm.send {to 1..8 addresses, text, format?} (app mode only) with a required idempotencyKey; slack.user.lookup {email}; gmail.thread.list {limit? 1..50, default 15, q?, labelIds? default [INBOX], pageToken?}; gmail.thread.read {threadId}; gmail.message.read {messageId}; gmail.attachment.read {messageId, attachmentId}; gmail.message.send {to 1..50 addresses (to+cc+bcc <= 50 in total), cc?, bcc?, subject 1..256 chars, text 1..4000 chars, html? <= 64 KiB, attachments? 1..5 of <= 2 MiB each as base64, replyToMessageId?} and a required idempotencyKey like slack.message.post; warehouse.view.read {columns? 1..32, where? 1..16 filters, groupBy? 1..8 columns, aggregates? 1..16, orderBy? 1..8, limit? 1..1000, default 100} (0.70.0: a plain read names columns, an aggregate read names aggregates and optionally groupBy; the cross-field rules \u2014 exactly one of columns or aggregates, groupBy needs aggregates, a filter value that fits its op, orderBy naming a returned column, every named column approved \u2014 are enforced by governance, not expressible here; ADR 0017). Each operation's then-block is the one statement of its input rules: propertyNames.enum names the fields it accepts, required the ones it needs, and per-field overrides (maximum, default) narrow the shared property. Codegen derives IntegrationExecuteInputRules and validateIntegrationExecuteInput (gen-ts/integration-execute-input-rules.ts, gen-go/integration_execute_input_rules.go) from exactly these blocks, so the governance execute route, the app SDK and the kit's local check refuse the same request with the same message. Transport limits (not expressible here): request <= 16 KiB except a gmail.message.send carrying attachments (governance sizes that route for the attachment bound), total deadline 10 s.",
+  "description": "Body of POST /_harbour/integrations/execute (app SDK), forwarded unchanged to the governance development and runtime execute routes. Exactly one declared operation against one declared resource. The identity mode is fixed by the operation for every operation but the declared-mode Slack operations (slack.channel.history, slack.message.post, slack.message.update, slack.message.delete; 0.71.0 widened history), and always enforced from an approved grant; any identity/userId/scope field is rejected by additionalProperties. A declared-mode operation runs as the app (for a post: the IT-approved per-app name from the grant, plus a \"Posted by <app> on Isomorph\" footer) or as the signed-in person (no name, no footer) \u2014 the same input either way \u2014 and since 0.55.0 the call names which of the app's approved modes it runs under (`mode`): required when IT approved both modes for the app (MODE_REQUIRED otherwise), optional when it approved one (that one is used), and a named mode without an approved grant is refused (MODE_NOT_GRANTED) rather than served under the other, so approval order never decides what a call does. Per-operation input bounds (0.71.0, ADR 0018): slack.channel.history {limit? 1..100, default 15, cursor?, oldest?, latest?}; slack.message.post {text 1..4000 chars, threadId?, format? plain|mrkdwn} and a required idempotencyKey retained across retries of one explicit Send; slack.message.update {messageId, text, format?}; slack.message.delete {messageId}; slack.dm.send {to 1..8 addresses, text, format?} (app mode only) with a required idempotencyKey; slack.user.lookup {email}; gmail.thread.list {limit? 1..50, default 15, q?, labelIds? default [INBOX], pageToken?}; gmail.thread.read {threadId}; gmail.message.read {messageId}; gmail.attachment.read {messageId, attachmentId}; gmail.message.send {to 1..50 addresses (to+cc+bcc <= 50 in total), cc?, bcc?, subject 1..256 chars, text 1..4000 chars, html? <= 64 KiB, attachments? 1..5 of <= 2 MiB each as base64, replyToMessageId?} and a required idempotencyKey like slack.message.post; warehouse.view.read {columns? 1..32, where? 1..16 filters, groupBy? 1..8 columns, aggregates? 1..16, orderBy? 1..8, limit? 1..1000, default 100} (0.70.0: a plain read names columns, an aggregate read names aggregates and optionally groupBy; the cross-field rules \u2014 exactly one of columns or aggregates, groupBy needs aggregates, a filter value that fits its op, orderBy naming a returned column, every named column approved \u2014 are enforced by governance, not expressible here; ADR 0017). Basecamp (0.76.0, ADR 0022; every id a string of 1..20 digits, every operation user mode): basecamp.project.list {pageToken?, projectStatus? active|archived} on the fixed `account` alias; on a project alias basecamp.todolist.list {pageToken?}; basecamp.todo.list {todolistId, completed?, pageToken?}; basecamp.todo.create {todolistId, content 1..1000 (the to-do title), description? <= 16384, contentFormat? plain|html, dueOn? YYYY-MM-DD, assigneeIds? 1..20, notify?} with a required idempotencyKey; basecamp.todo.complete {todoId} (idempotent at Basecamp, so no key); basecamp.message.list {pageToken?}; basecamp.message.post {subject 1..256, content 1..65536, contentFormat?} with a required idempotencyKey; basecamp.comment.list {recordingId, pageToken?}; basecamp.comment.post {recordingId, content 1..16384, contentFormat?} with a required idempotencyKey; basecamp.campfire.post {content 1..4000, contentFormat?} with a required idempotencyKey; basecamp.people.list {pageToken?}. `pageToken` is the previous page's `nextPageToken` (a Basecamp page number as digits). Each operation's then-block is the one statement of its input rules: propertyNames.enum names the fields it accepts, required the ones it needs, and per-field overrides (maximum, default) narrow the shared property. Codegen derives IntegrationExecuteInputRules and validateIntegrationExecuteInput (gen-ts/integration-execute-input-rules.ts, gen-go/integration_execute_input_rules.go) from exactly these blocks, so the governance execute route, the app SDK and the kit's local check refuse the same request with the same message. Transport limits (not expressible here): request <= 16 KiB except a gmail.message.send carrying attachments (governance sizes that route for the attachment bound) and a basecamp.message.post (its 64 KiB body; governance allows 80 KiB there), total deadline 10 s.",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -99,7 +99,7 @@
           "type": "string",
           "minLength": 1,
           "maxLength": 256,
-          "description": "gmail.thread.list (0.71.0): the `nextPageToken` of the previous page; absent reads the first page."
+          "description": "gmail.thread.list (0.71.0) and every basecamp.*.list operation (0.76.0): the `nextPageToken` of the previous page; absent reads the first page."
         },
         "email": {
           "$ref": "#/definitions/EmailAddress",
@@ -121,7 +121,7 @@
           "type": "string",
           "minLength": 1,
           "maxLength": 256,
-          "description": "gmail.message.send: one-line subject (no line breaks)."
+          "description": "gmail.message.send: one-line subject (no line breaks). basecamp.message.post (0.76.0): the message's title."
         },
         "replyToMessageId": {
           "type": "string",
@@ -143,6 +143,61 @@
           },
           "description": "gmail.message.send (0.71.0): files to attach, 1..5, each at most 2 MiB (2,796,203 base64 characters)."
         },
+        "todolistId": {
+          "$ref": "app-integrations-declaration.schema.json#/definitions/BasecampId",
+          "description": "basecamp.todo.list / basecamp.todo.create (0.76.0): the to-do list, as a basecamp.todolist.list result named it."
+        },
+        "todoId": {
+          "$ref": "app-integrations-declaration.schema.json#/definitions/BasecampId",
+          "description": "basecamp.todo.complete (0.76.0): the to-do, as a basecamp.todo.list or basecamp.todo.create result named it."
+        },
+        "recordingId": {
+          "$ref": "app-integrations-declaration.schema.json#/definitions/BasecampId",
+          "description": "basecamp.comment.list / basecamp.comment.post (0.76.0): the Basecamp recording commented on — a message, a to-do or any other id a basecamp.* result named."
+        },
+        "content": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 65536,
+          "description": "basecamp.todo.create (0.76.0): the to-do's title, 1..1000 characters. basecamp.message.post: the body, at most 64 KiB; basecamp.comment.post: at most 16 KiB; basecamp.campfire.post: at most 4000 characters. Plain text unless `contentFormat` is html."
+        },
+        "contentFormat": {
+          "$ref": "#/definitions/BasecampContentFormat",
+          "description": "basecamp.todo.create / basecamp.message.post / basecamp.comment.post / basecamp.campfire.post (0.76.0): how `content` (and a to-do's `description`) is read; plain when absent."
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 16384,
+          "description": "basecamp.todo.create (0.76.0): the to-do's notes, at most 16 KiB, read the way `contentFormat` says."
+        },
+        "dueOn": {
+          "type": "string",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+          "description": "basecamp.todo.create (0.76.0): the due date as YYYY-MM-DD; absent leaves the to-do undated."
+        },
+        "assigneeIds": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 20,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "app-integrations-declaration.schema.json#/definitions/BasecampId"
+          },
+          "description": "basecamp.todo.create (0.76.0): the people assigned, 1..20, by the ids a basecamp.people.list result named."
+        },
+        "notify": {
+          "type": "boolean",
+          "description": "basecamp.todo.create (0.76.0): whether Basecamp notifies the assignees; false when absent."
+        },
+        "completed": {
+          "type": "boolean",
+          "description": "basecamp.todo.list (0.76.0): true lists the completed to-dos instead of the open ones; absent lists the open ones."
+        },
+        "projectStatus": {
+          "$ref": "#/definitions/BasecampProjectStatus",
+          "description": "basecamp.project.list (0.76.0): which projects to list; active when absent."
+        },
         "columns": {
           "type": "array",
           "minItems": 1,
@@ -239,11 +294,23 @@
     "idempotencyKey": {
       "type": "string",
       "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
-      "description": "UUID of one explicit Send action; required for slack.message.post and gmail.message.send only. The same key with the same payload and subject returns the recorded outcome for seven days."
+      "description": "UUID of one explicit Send action; required for the sends (slack.message.post, slack.dm.send, gmail.message.send) and the receipted Basecamp writes (basecamp.todo.create, basecamp.message.post, basecamp.comment.post, basecamp.campfire.post; 0.76.0), refused everywhere else. The same key with the same payload and subject returns the recorded outcome for seven days."
     },
     "mode": {
       "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationIdentityMode",
       "description": "The declared-mode Slack operations only (slack.message.post since 0.55.0; slack.channel.history, slack.message.update and slack.message.delete since 0.71.0): which of the app's IT-approved modes this call runs under \u2014 app (the company's Slack app; a post goes out under the grant's per-app name and the footer) or user (the signed-in person, after their consent; no name, no footer). Required when the app holds approved grants for both modes (else MODE_REQUIRED); may be omitted when it holds one, which is then used. A named mode without an approved grant is refused with MODE_NOT_GRANTED; governance never falls back to the other mode. Every other operation's mode is fixed, so the field is refused there."
+    },
+    "sampleRows": {
+      "type": "array",
+      "maxItems": 50,
+      "items": {
+        "type": "object",
+        "additionalProperties": {
+          "type": ["string", "number", "boolean", "null"]
+        },
+        "description": "One sample row keyed by column name; each value is a scalar that governance parses by the column's recorded type."
+      },
+      "description": "Development only (0.74.0). Rows the kit dev runtime attaches for the resource being read, from the sample-row file the agent wrote into the app's .isomorph/ folder. Governance serves them for a development warehouse.view.read when the source has no development copy (data-source.environments.development): it parses each value by the resource's recorded column type and refuses a value that does not parse, naming the column and the row. The field is refused with SAMPLE_ROWS_NOT_ALLOWED on any route but the development one, so a preview or production read never carries made-up data. Not part of the per-operation input rules; the dev runtime adds it beside the app's request."
     }
   },
   "allOf": [
@@ -642,6 +709,360 @@
         }
       }
     },
+    {
+      "if": {
+        "properties": {
+          "operation": {
+            "const": "basecamp.project.list"
+          }
+        }
+      },
+      "then": {
+        "x-read-only": true,
+        "x-primary-identity": "user",
+        "not": {
+          "required": [
+            "idempotencyKey"
+          ]
+        },
+        "properties": {
+          "mode": false,
+          "input": {
+            "propertyNames": {
+              "enum": [
+                "pageToken",
+                "projectStatus"
+              ]
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "operation": {
+            "const": "basecamp.todolist.list"
+          }
+        }
+      },
+      "then": {
+        "x-read-only": true,
+        "x-primary-identity": "user",
+        "not": {
+          "required": [
+            "idempotencyKey"
+          ]
+        },
+        "properties": {
+          "mode": false,
+          "input": {
+            "propertyNames": {
+              "enum": [
+                "pageToken"
+              ]
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "operation": {
+            "const": "basecamp.todo.list"
+          }
+        }
+      },
+      "then": {
+        "x-read-only": true,
+        "x-primary-identity": "user",
+        "not": {
+          "required": [
+            "idempotencyKey"
+          ]
+        },
+        "properties": {
+          "mode": false,
+          "input": {
+            "propertyNames": {
+              "enum": [
+                "todolistId",
+                "completed",
+                "pageToken"
+              ]
+            },
+            "required": [
+              "todolistId"
+            ]
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "operation": {
+            "const": "basecamp.todo.create"
+          }
+        }
+      },
+      "then": {
+        "x-read-only": false,
+        "x-primary-identity": "user",
+        "required": [
+          "idempotencyKey"
+        ],
+        "properties": {
+          "mode": false,
+          "input": {
+            "propertyNames": {
+              "enum": [
+                "todolistId",
+                "content",
+                "description",
+                "contentFormat",
+                "dueOn",
+                "assigneeIds",
+                "notify"
+              ]
+            },
+            "required": [
+              "todolistId",
+              "content"
+            ],
+            "properties": {
+              "content": {
+                "maxLength": 1000
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "operation": {
+            "const": "basecamp.todo.complete"
+          }
+        }
+      },
+      "then": {
+        "x-read-only": false,
+        "x-primary-identity": "user",
+        "not": {
+          "required": [
+            "idempotencyKey"
+          ]
+        },
+        "properties": {
+          "mode": false,
+          "input": {
+            "propertyNames": {
+              "enum": [
+                "todoId"
+              ]
+            },
+            "required": [
+              "todoId"
+            ]
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "operation": {
+            "const": "basecamp.message.list"
+          }
+        }
+      },
+      "then": {
+        "x-read-only": true,
+        "x-primary-identity": "user",
+        "not": {
+          "required": [
+            "idempotencyKey"
+          ]
+        },
+        "properties": {
+          "mode": false,
+          "input": {
+            "propertyNames": {
+              "enum": [
+                "pageToken"
+              ]
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "operation": {
+            "const": "basecamp.message.post"
+          }
+        }
+      },
+      "then": {
+        "x-read-only": false,
+        "x-primary-identity": "user",
+        "required": [
+          "idempotencyKey"
+        ],
+        "properties": {
+          "mode": false,
+          "input": {
+            "propertyNames": {
+              "enum": [
+                "subject",
+                "content",
+                "contentFormat"
+              ]
+            },
+            "required": [
+              "subject",
+              "content"
+            ]
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "operation": {
+            "const": "basecamp.comment.list"
+          }
+        }
+      },
+      "then": {
+        "x-read-only": true,
+        "x-primary-identity": "user",
+        "not": {
+          "required": [
+            "idempotencyKey"
+          ]
+        },
+        "properties": {
+          "mode": false,
+          "input": {
+            "propertyNames": {
+              "enum": [
+                "recordingId",
+                "pageToken"
+              ]
+            },
+            "required": [
+              "recordingId"
+            ]
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "operation": {
+            "const": "basecamp.comment.post"
+          }
+        }
+      },
+      "then": {
+        "x-read-only": false,
+        "x-primary-identity": "user",
+        "required": [
+          "idempotencyKey"
+        ],
+        "properties": {
+          "mode": false,
+          "input": {
+            "propertyNames": {
+              "enum": [
+                "recordingId",
+                "content",
+                "contentFormat"
+              ]
+            },
+            "required": [
+              "recordingId",
+              "content"
+            ],
+            "properties": {
+              "content": {
+                "maxLength": 16384
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "operation": {
+            "const": "basecamp.campfire.post"
+          }
+        }
+      },
+      "then": {
+        "x-read-only": false,
+        "x-primary-identity": "user",
+        "required": [
+          "idempotencyKey"
+        ],
+        "properties": {
+          "mode": false,
+          "input": {
+            "propertyNames": {
+              "enum": [
+                "content",
+                "contentFormat"
+              ]
+            },
+            "required": [
+              "content"
+            ],
+            "properties": {
+              "content": {
+                "maxLength": 4000
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "operation": {
+            "const": "basecamp.people.list"
+          }
+        }
+      },
+      "then": {
+        "x-read-only": true,
+        "x-primary-identity": "user",
+        "not": {
+          "required": [
+            "idempotencyKey"
+          ]
+        },
+        "properties": {
+          "mode": false,
+          "input": {
+            "propertyNames": {
+              "enum": [
+                "pageToken"
+              ]
+            }
+          }
+        }
+      }
+    },
     {
       "if": {
         "properties": {
@@ -711,6 +1132,23 @@
       "default": "plain",
       "description": "How Slack renders a message body (0.71.0): plain posts the text verbatim; mrkdwn lets Slack interpret its markup (*bold*, links, lists)."
     },
+    "BasecampContentFormat": {
+      "type": "string",
+      "enum": [
+        "plain",
+        "html"
+      ],
+      "default": "plain",
+      "description": "How Basecamp reads a body (0.76.0): plain is HTML-escaped by governance with newlines as <br>; html is passed to Basecamp's rich text as written."
+    },
+    "BasecampProjectStatus": {
+      "type": "string",
+      "enum": [
+        "active",
+        "archived"
+      ],
+      "description": "Which projects basecamp.project.list returns (0.76.0): the active ones (the default) or the archived ones."
+    },
     "EmailAttachment": {
       "type": "object",
       "additionalProperties": false,
@@ -1144,6 +1582,127 @@
           "text": "approved"
         }
       }
+    },
+    {
+      "connection": "sales-warehouse",
+      "operation": "warehouse.view.read",
+      "resource": "weekly_sales",
+      "input": {
+        "columns": [
+          "week",
+          "total"
+        ],
+        "limit": 100
+      },
+      "sampleRows": [
+        {
+          "week": "2026-W36",
+          "total": "1234.50"
+        },
+        {
+          "week": "2026-W37",
+          "total": null
+        }
+      ]
+    },
+    {
+      "connection": "company-basecamp",
+      "operation": "basecamp.project.list",
+      "resource": "account",
+      "input": {
+        "projectStatus": "active"
+      }
+    },
+    {
+      "connection": "company-basecamp",
+      "operation": "basecamp.todolist.list",
+      "resource": "launch",
+      "input": {}
+    },
+    {
+      "connection": "company-basecamp",
+      "operation": "basecamp.todo.list",
+      "resource": "launch",
+      "input": {
+        "todolistId": "1069479520",
+        "completed": false
+      }
+    },
+    {
+      "connection": "company-basecamp",
+      "operation": "basecamp.todo.create",
+      "resource": "launch",
+      "input": {
+        "todolistId": "1069479520",
+        "content": "Ship the weekly report",
+        "description": "Attach the PDF to the message board post.",
+        "dueOn": "2026-10-17",
+        "assigneeIds": [
+          "1049715914"
+        ],
+        "notify": true
+      },
+      "idempotencyKey": "6f1c2c1e-3a1c-4c3e-9f0e-2b6f7d8a9c16"
+    },
+    {
+      "connection": "company-basecamp",
+      "operation": "basecamp.todo.complete",
+      "resource": "launch",
+      "input": {
+        "todoId": "1069479526"
+      }
+    },
+    {
+      "connection": "company-basecamp",
+      "operation": "basecamp.message.list",
+      "resource": "launch",
+      "input": {
+        "pageToken": "2"
+      }
+    },
+    {
+      "connection": "company-basecamp",
+      "operation": "basecamp.message.post",
+      "resource": "launch",
+      "input": {
+        "subject": "Weekly report",
+        "content": "<p>The weekly report is <b>attached</b>.</p>",
+        "contentFormat": "html"
+      },
+      "idempotencyKey": "6f1c2c1e-3a1c-4c3e-9f0e-2b6f7d8a9c17"
+    },
+    {
+      "connection": "company-basecamp",
+      "operation": "basecamp.comment.list",
+      "resource": "launch",
+      "input": {
+        "recordingId": "1069479530"
+      }
+    },
+    {
+      "connection": "company-basecamp",
+      "operation": "basecamp.comment.post",
+      "resource": "launch",
+      "input": {
+        "recordingId": "1069479530",
+        "content": "Shipped, thanks."
+      },
+      "idempotencyKey": "6f1c2c1e-3a1c-4c3e-9f0e-2b6f7d8a9c18"
+    },
+    {
+      "connection": "company-basecamp",
+      "operation": "basecamp.campfire.post",
+      "resource": "launch",
+      "input": {
+        "content": "Weekly report is up on the message board."
+      },
+      "idempotencyKey": "6f1c2c1e-3a1c-4c3e-9f0e-2b6f7d8a9c19"
+    },
+    {
+      "connection": "company-basecamp",
+      "operation": "basecamp.people.list",
+      "resource": "launch",
+      "input": {}
     }
   ]
 }