@isomorph.ai/app-sdk 1.19.0 → 1.21.0

package/README.md

@@ -215,6 +215,117 @@ await isomorph.integrations.execute('company-sharepoint', {
 
 (1.16.0; contracts 0.78.0)
 
+Google Workspace — Calendar, Drive, Docs and Sheets — runs as the signed-in
+person after their consent, on the person's own data: there is nothing for IT
+to map, so every operation names the provider's one fixed alias (`primary`,
+`my-drive`, `my-docs`, `my-sheets`). Creating an event, folder, document or
+spreadsheet, uploading a file or appending rows is an explicit action with a
+fresh UUID; an update, cancel, append to a document, replace or clear has one
+outcome however often it runs and needs none. A Sheet used as a small table:
+
+```ts
+// The person's week, then one event they created
+const week = await isomorph.integrations.execute('company-calendar', {
+  operation: 'calendar.event.list', resource: 'primary',
+  input: { timeMin: '2026-10-20T00:00:00+05:30', timeMax: '2026-10-27T00:00:00+05:30' },
+});
+const walkthrough = await isomorph.integrations.execute('company-calendar', {
+  operation: 'calendar.event.create', resource: 'primary',
+  input: { title: 'Venue walkthrough', start: '2026-10-20T09:30:00+05:30', end: '2026-10-20T10:30:00+05:30', timeZone: 'Asia/Kolkata', attendees: ['jane@example.com'] },
+  idempotencyKey: crypto.randomUUID(),
+});
+
+// A Sheet as a table: read the header and rows, append two, overwrite one cell
+const orders = await isomorph.integrations.execute('company-sheets', {
+  operation: 'sheets.values.read', resource: 'my-sheets',
+  input: { spreadsheetId: '1FixtureSpreadsheetB1cD2eF3gH4iJ5kL6mN7o', range: 'Orders!A1:D' },
+});
+const [header, ...rows] = orders.values; // each cell a string, a number, a boolean or null
+await isomorph.integrations.execute('company-sheets', {
+  operation: 'sheets.values.append', resource: 'my-sheets',
+  input: { spreadsheetId: '1FixtureSpreadsheetB1cD2eF3gH4iJ5kL6mN7o', range: 'Orders!A:D', values: [['Acme', 3, false, '2026-10-20'], ['Globex', 1, true, null]] },
+  idempotencyKey: crypto.randomUUID(),
+});
+await isomorph.integrations.execute('company-sheets', {
+  operation: 'sheets.values.update', resource: 'my-sheets',
+  input: { spreadsheetId: '1FixtureSpreadsheetB1cD2eF3gH4iJ5kL6mN7o', range: 'Orders!C2', values: [[true]] },
+});
+
+// A Doc from a template: read it, fill the placeholders, append the decisions
+const minutes = await isomorph.integrations.execute('company-docs', {
+  operation: 'docs.document.create', resource: 'my-docs',
+  input: { title: 'Venue minutes', text: 'Customer: {{customer}}\n' }, idempotencyKey: crypto.randomUUID(),
+});
+await isomorph.integrations.execute('company-docs', {
+  operation: 'docs.text.replace', resource: 'my-docs',
+  input: { documentId: minutes.id, replacements: [{ find: '{{customer}}', replace: 'Acme' }] },
+});
+
+// Drive: a search, one file's bytes (a Google Doc exported as pdf), an upload into a new folder
+const found = await isomorph.integrations.execute('company-drive', {
+  operation: 'drive.file.search', resource: 'my-drive', input: { q: 'venue contract' },
+});
+const contract = await isomorph.integrations.execute('company-drive', {
+  operation: 'drive.file.read', resource: 'my-drive', input: { fileId: found.files[0].id, exportAs: 'pdf' },
+});
+const folder = await isomorph.integrations.execute('company-drive', {
+  operation: 'drive.folder.create', resource: 'my-drive', input: { title: 'Signed' }, idempotencyKey: crypto.randomUUID(),
+});
+await isomorph.integrations.execute('company-drive', {
+  operation: 'drive.file.upload', resource: 'my-drive',
+  input: { filename: contract.filename, contentType: contract.mimeType, dataBase64: contract.dataBase64, folderId: folder.id },
+  idempotencyKey: crypto.randomUUID(),
+});
+```
+
+Microsoft 365 — Outlook, OneDrive, Excel and Teams — runs as the signed-in
+person the same way. Outlook, OneDrive and Excel act on the person's own
+mailbox, drive and workbooks on a fixed alias (`inbox`, `my-drive`,
+`my-workbooks`); Teams is the exception: like Slack, every operation names a
+channel alias IT mapped to one channel of one team. Ids are opaque Microsoft
+Graph ids. A send, reply, post, upload, folder or worksheet create and a table
+row add are explicit actions with a fresh UUID; an event update or cancel and
+a range update need none. An Excel workbook is the same small table:
+
+```ts
+// Unread mail about the venue, one message's text, a reply
+const mail = await isomorph.integrations.execute('company-outlook', {
+  operation: 'outlook.message.list', resource: 'inbox', input: { q: 'venue' },
+});
+const message = await isomorph.integrations.execute('company-outlook', {
+  operation: 'outlook.message.read', resource: 'inbox', input: { messageId: mail.mailMessages[0].id },
+});
+await isomorph.integrations.execute('company-outlook', {
+  operation: 'outlook.message.reply', resource: 'inbox',
+  input: { messageId: message.id, text: 'Confirmed for Monday.' }, idempotencyKey: crypto.randomUUID(),
+});
+
+// The workbook's tables, then two rows added to one of them
+const { files } = await isomorph.integrations.execute('company-onedrive', {
+  operation: 'onedrive.file.search', resource: 'my-drive', input: { q: 'orders.xlsx' },
+});
+const { tables } = await isomorph.integrations.execute('company-excel', {
+  operation: 'excel.table.list', resource: 'my-workbooks', input: { fileId: files[0].id },
+});
+await isomorph.integrations.execute('company-excel', {
+  operation: 'excel.row.add', resource: 'my-workbooks',
+  input: { fileId: files[0].id, tableName: tables[0].name, values: [['Acme', 3, false], ['Globex', 1, true]] },
+  idempotencyKey: crypto.randomUUID(),
+});
+const range = await isomorph.integrations.execute('company-excel', {
+  operation: 'excel.range.read', resource: 'my-workbooks', input: { fileId: files[0].id, worksheet: tables[0].worksheet },
+}); // range.address is what Excel answered, range.values the grid
+
+// A summary to the mapped Teams channel
+await isomorph.integrations.execute('company-teams', {
+  operation: 'teams.message.post', resource: 'project-updates',
+  input: { text: `Venue confirmed; ${range.values.length - 1} orders on the sheet.` },
+  idempotencyKey: crypto.randomUUID(),
+});
+```
+
+(1.21.0; contracts 0.86.0)
+
 ## Trusted actions
 
 A normal action runs with the signed-in person's rights, so a rule in it is advice: whatever it may write, the browser may write directly. A business rule that must hold goes in a trusted action: `export const trusted = true;` beside the default export. Its data calls run as the app on behalf of the caller (the database sees `harbour.user_id = 'workload:…'` and `harbour.on_behalf_of` = the person, with the person's email, groups and role), so the tables it writes give people no write rule (`WITH CHECK (current_setting('harbour.user_id', true) LIKE 'workload:%')`). `ctx.transaction(fn)` runs every call inside `fn` as one database transaction, committed when `fn` returns and rolled back when it throws; `.forUpdate()` on a select locks the row until then. A thrown `Error` with `code` (an error category such as `FORBIDDEN` or `CONFLICT`) and `message` reaches the page with that status and text.