@fourier-labs/harbour-contracts 0.73.0 → 0.76.0

package/gen-ts/integration-execute-result.ts

@@ -2,7 +2,7 @@
 // Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
 
 /**
- * The `data` member of a successful execute response `{data, requestId}`; the SDK unwraps `data`. Exactly one of the operation results (twelve operations since 0.71.0, ADR 0018): 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). 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, whose single attachment is bounded by its own 2 MiB.
+ * The `data` member of a successful execute response `{data, requestId}`; the SDK unwraps `data`. Exactly one of the operation results (twenty-four operations since 0.76.0, ADR 0018 and ADR 0022): 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. 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, whose single attachment is bounded by its own 2 MiB.
  */
 export type IntegrationExecuteResult = {
   /**
@@ -46,6 +46,10 @@ export type IntegrationExecuteResult = {
    * gmail.message.read: the text was cut at 16 KiB. warehouse.view.read (0.70.0): more rows matched than the read's limit, so `rows` is incomplete.
    */
   truncated?: boolean;
+  /**
+   * warehouse.view.read (0.74.0): true when `rows` came from the app's sample rows (integration-execute-request.sampleRows) because the development read had no development copy of the source; the rows were never read from the source. Absent or false: the rows came from the source.
+   */
+  sample?: boolean;
   /**
    * gmail.message.read (0.71.0): the message's attachments, without their bytes.
    *
@@ -74,6 +78,50 @@ export type IntegrationExecuteResult = {
   rows?: {
     [k: string]: unknown;
   }[];
+  /**
+   * basecamp.project.list (0.76.0): one page of the pinned account's projects the signed-in person can see.
+   *
+   * @maxItems 100
+   */
+  projects?: BasecampProject[];
+  /**
+   * basecamp.todolist.list (0.76.0): one page of the project's to-do lists.
+   *
+   * @maxItems 100
+   */
+  todolists?: BasecampTodolist[];
+  /**
+   * basecamp.todo.list (0.76.0): one page of the list's open to-dos, or its completed ones when the read said `completed`.
+   *
+   * @maxItems 100
+   */
+  todos?: BasecampTodo[];
+  /**
+   * basecamp.message.list (0.76.0): one page of the project's message board, newest first. Named apart from `messages`, the Slack history shape.
+   *
+   * @maxItems 100
+   */
+  boardMessages?: BasecampMessage[];
+  /**
+   * basecamp.comment.list (0.76.0): one page of the recording's comments, oldest first.
+   *
+   * @maxItems 100
+   */
+  comments?: BasecampComment[];
+  /**
+   * basecamp.people.list (0.76.0): one page of the people on the project.
+   *
+   * @maxItems 100
+   */
+  people?: BasecampPerson[];
+  /**
+   * basecamp.todo.create / basecamp.message.post / basecamp.comment.post / basecamp.campfire.post (0.76.0): the Basecamp page of the new recording, for a person to open.
+   */
+  appUrl?: string;
+  /**
+   * basecamp.todo.complete (0.76.0): always true; the to-do is complete whether this call or an earlier one completed it.
+   */
+  completed?: boolean;
   status?: number;
   headers?: {
     [k: string]: string;
@@ -132,3 +180,119 @@ export interface GmailMessage {
    */
   attachments?: GmailAttachment[];
 }
+/**
+ * One Basecamp project of a basecamp.project.list result (0.76.0). `id` is what IT maps a project alias to on the connection.
+ */
+export interface BasecampProject {
+  /**
+   * A Basecamp id (0.76.0): an account, project, to-do list, to-do, recording or person, as a string of 1..20 digits — how every basecamp.* result names one and every basecamp.* input takes one back.
+   */
+  id: string;
+  name: string;
+  description?: string;
+  appUrl: string;
+  /**
+   * @maxItems 32
+   */
+  tools: BasecampTool[];
+}
+/**
+ * One enabled tool of a Basecamp project (0.76.0), from its dock: `name` is Basecamp's kind (todoset, message_board, chat, schedule, vault, questionnaire, inbox, kanban_board), `title` what the project calls it.
+ */
+export interface BasecampTool {
+  /**
+   * A Basecamp id (0.76.0): an account, project, to-do list, to-do, recording or person, as a string of 1..20 digits — how every basecamp.* result names one and every basecamp.* input takes one back.
+   */
+  id: string;
+  name: string;
+  title: string;
+}
+/**
+ * One to-do list of a basecamp.todolist.list result (0.76.0); `id` is what basecamp.todo.list and basecamp.todo.create take as `todolistId`.
+ */
+export interface BasecampTodolist {
+  /**
+   * A Basecamp id (0.76.0): an account, project, to-do list, to-do, recording or person, as a string of 1..20 digits — how every basecamp.* result names one and every basecamp.* input takes one back.
+   */
+  id: string;
+  name: string;
+  description?: string;
+  /**
+   * Basecamp's `completed_ratio`, e.g. `3/10`.
+   */
+  completedRatio: string;
+  appUrl: string;
+}
+/**
+ * One to-do of a basecamp.todo.list result (0.76.0): `content` is its title, `description` its notes as plain text (empty when none), each cut at 16 KiB.
+ */
+export interface BasecampTodo {
+  /**
+   * A Basecamp id (0.76.0): an account, project, to-do list, to-do, recording or person, as a string of 1..20 digits — how every basecamp.* result names one and every basecamp.* input takes one back.
+   */
+  id: string;
+  content: string;
+  description: string;
+  completed: boolean;
+  dueOn?: string;
+  /**
+   * @maxItems 100
+   */
+  assignees: BasecampPersonRef[];
+  appUrl: string;
+  createdAt: string;
+}
+/**
+ * A person named on a Basecamp recording (0.76.0): an author or an assignee.
+ */
+export interface BasecampPersonRef {
+  /**
+   * A Basecamp id (0.76.0): an account, project, to-do list, to-do, recording or person, as a string of 1..20 digits — how every basecamp.* result names one and every basecamp.* input takes one back.
+   */
+  id: string;
+  name: string;
+}
+/**
+ * One message-board post of a basecamp.message.list result (0.76.0); `content` is plain text cut at 16 KiB; `id` is a recordingId for basecamp.comment.list and basecamp.comment.post.
+ */
+export interface BasecampMessage {
+  /**
+   * A Basecamp id (0.76.0): an account, project, to-do list, to-do, recording or person, as a string of 1..20 digits — how every basecamp.* result names one and every basecamp.* input takes one back.
+   */
+  id: string;
+  subject: string;
+  content: string;
+  author: BasecampPersonRef;
+  createdAt: string;
+  appUrl: string;
+  commentsCount: number;
+}
+/**
+ * One comment of a basecamp.comment.list result (0.76.0); `content` is plain text cut at 16 KiB.
+ */
+export interface BasecampComment {
+  /**
+   * A Basecamp id (0.76.0): an account, project, to-do list, to-do, recording or person, as a string of 1..20 digits — how every basecamp.* result names one and every basecamp.* input takes one back.
+   */
+  id: string;
+  content: string;
+  author: BasecampPersonRef;
+  createdAt: string;
+  appUrl: string;
+}
+/**
+ * One person of a basecamp.people.list result (0.76.0); `id` is what basecamp.todo.create takes in `assigneeIds`. `email` and `title` when Basecamp shows them.
+ */
+export interface BasecampPerson {
+  /**
+   * A Basecamp id (0.76.0): an account, project, to-do list, to-do, recording or person, as a string of 1..20 digits — how every basecamp.* result names one and every basecamp.* input takes one back.
+   */
+  id: string;
+  name: string;
+  email?: string;
+  title?: string;
+  /**
+   * Whether the person is an administrator of the Basecamp account.
+   */
+  admin: boolean;
+}

package/gen-ts/integration-operations.ts

@@ -106,6 +106,105 @@ export const IntegrationOperations = {
     "declaredMode": false,
     "idempotencyKey": false
   },
+  "basecamp.project.list": {
+    "kind": "saas",
+    "identities": [
+      "user"
+    ],
+    "readOnly": true,
+    "declaredMode": false,
+    "idempotencyKey": false
+  },
+  "basecamp.todolist.list": {
+    "kind": "saas",
+    "identities": [
+      "user"
+    ],
+    "readOnly": true,
+    "declaredMode": false,
+    "idempotencyKey": false
+  },
+  "basecamp.todo.list": {
+    "kind": "saas",
+    "identities": [
+      "user"
+    ],
+    "readOnly": true,
+    "declaredMode": false,
+    "idempotencyKey": false
+  },
+  "basecamp.todo.create": {
+    "kind": "saas",
+    "identities": [
+      "user"
+    ],
+    "readOnly": false,
+    "declaredMode": false,
+    "idempotencyKey": true
+  },
+  "basecamp.todo.complete": {
+    "kind": "saas",
+    "identities": [
+      "user"
+    ],
+    "readOnly": false,
+    "declaredMode": false,
+    "idempotencyKey": false
+  },
+  "basecamp.message.list": {
+    "kind": "saas",
+    "identities": [
+      "user"
+    ],
+    "readOnly": true,
+    "declaredMode": false,
+    "idempotencyKey": false
+  },
+  "basecamp.message.post": {
+    "kind": "saas",
+    "identities": [
+      "user"
+    ],
+    "readOnly": false,
+    "declaredMode": false,
+    "idempotencyKey": true
+  },
+  "basecamp.comment.list": {
+    "kind": "saas",
+    "identities": [
+      "user"
+    ],
+    "readOnly": true,
+    "declaredMode": false,
+    "idempotencyKey": false
+  },
+  "basecamp.comment.post": {
+    "kind": "saas",
+    "identities": [
+      "user"
+    ],
+    "readOnly": false,
+    "declaredMode": false,
+    "idempotencyKey": true
+  },
+  "basecamp.campfire.post": {
+    "kind": "saas",
+    "identities": [
+      "user"
+    ],
+    "readOnly": false,
+    "declaredMode": false,
+    "idempotencyKey": true
+  },
+  "basecamp.people.list": {
+    "kind": "saas",
+    "identities": [
+      "user"
+    ],
+    "readOnly": true,
+    "declaredMode": false,
+    "idempotencyKey": false
+  },
   "warehouse.view.read": {
     "kind": "database",
     "identities": [

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.73.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,