Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
Macro's SDK: a Typescript library for harnessing the power of Macro
Read the SDK documentation — a quick start, plain-English entity guide, and complete API reference, served by the SDK docs Worker.
generated/: generated Typescript types and a HeyAPI client from Macro's OpenAPI specs.src/: a hand-written ergonomic SDK layer that provides an "orm"-y API.
The SDK reference build uses TypeDoc to generate linked Markdown and HTML from these sources at build time; the HTML is served with the included static docs Worker.
Usage
Getting started
To get started, make a Macro client
import { Macro } from '@macro-inc/sdk';
const macro = new Macro({ }); // uses MACRO_API_KEY env var
Authenticating
Every request the SDK sends carries exactly one Macro credential. There are three kinds.
| Credential | Minted in | Prefix | Acts as |
|---|---|---|---|
| API key | Settings → API Keys | mak_ |
the user who minted it |
| Bot token | Settings → Bots | mbot_ |
the bot, optionally on behalf of a user |
| Bearer token | a signed-in session | none (JWT) | the signed-in user |
API key
The default for scripts and integrations. Put the key in MACRO_API_KEY and construct with no options.
import { Macro } from '@macro-inc/sdk';
const macro = new Macro({});
const me = await macro.users.me();
Or pass it in code. token accepts an API key or a bearer token. The SDK picks the header from the prefix.
const macro = new Macro({ token: process.env.MACRO_API_KEY });
The explicit form names the credential kind. Use it when the key is not from an env var, or when it predates the mak_ prefix.
const macro = new Macro({
auth: { type: 'user', apiKey: process.env.MACRO_API_KEY },
});
An API key always acts as the user who minted it. requestedAs is bot-only.
Agent accounts
An agent has its own account and seat. Invite one with
(await macro.teams.current()).invite('[email protected]', { agent: true }), or sign
up at https://macro.com/app/signup/agent. After signing in, the agent sees its API key once in the
web app and uses it like any other key. It can set up its profile with
macro.me.update({ name, profilePicture: await macro.me.uploadProfilePicture(bytes, options) })
and mint more keys with macro.apiKeys.create(name).
Account managers
An agent account can manage a person's account: either side asks in their DM, and the other side approves. An agent account can't be managed.
// As the agent, ask to manage a person's account:
const grant = await macro.accountManagers.askToManage(person);
// Once the person approves, the agent gets the token, once:
const token = await grant.claimToken();
A person can ask instead, with macro.accountManagers.askToBeManagedBy(agent). Only the
manager can claim, so the agent approves and claims with its own client, using the grant id
from the card in the DM: macro.accountManagers.byId(id).
The token is an API key for the managed account, with full access except its
managers, API keys and other credentials, sign-in, and deleting the account. It
lasts until either side calls grant.revoke(), or the managed account revokes it
in Settings → Account Managers.
Bot token
const asBot = new Macro({ auth: { type: 'bot', token: process.env.MACRO_BOT_TOKEN } });
const asWolf = asBot.requestedAs('macro|[email protected]');
Bot requests carry an access scope. user uses the requested-as user's access, and is the default when requestedAs is set. team uses the owning team's access, for team-owned bots, and is the default otherwise. Pass auth: { type: 'bot', token, scope: ... } to override.
Bearer token
A session token, for code running with a signed-in user. Sent as Authorization: Bearer. The function form refreshes it.
const macro = new Macro({ auth: { type: 'user', token: () => session.accessToken() } });
Which header goes out
The backend rejects a request carrying two credentials with 400 ambiguous credentials. The SDK sets exactly one.
| You passed | Header sent |
|---|---|
apiKey: '…' |
x-macro-user-api-key: … |
token: 'mak_…' or MACRO_API_KEY=mak_… |
x-macro-user-api-key: mak_… |
token: '<jwt>' or MACRO_API_KEY=<jwt> |
Authorization: Bearer <jwt> |
token: 'mbot_…' |
throws. Use auth: { type: 'bot', token } or MACRO_BOT_TOKEN. |
type: 'bot' |
x-macro-bot-token plus x-macro-bot-scope |
Accessing our API
Our SDK acts lets you easily access any Macro "resource":
const doc = macro.documents.byId('doc_123');
const name = await doc.name();
const owner = await doc.owner();
const email = await owner.email();
Forms
Forms collect answers into a table. Respondents can read questions and submit without permission to read the response database.
const form = await macro.forms.create({ name: 'Workshop registration' });
const table = await form.table();
const name = await table.addColumn({ name: 'Name', type: { type: 'text' } });
await form.replaceLayout([
{
kind: 'questions',
title: 'About you',
questions: [{ column: name, required: true }],
},
]);
const [question] = await form.questions();
if (!question) throw new Error('The form has no questions');
const receipt = await form.submit([
{ question, value: { type: 'text', value: 'Ada' } },
]);
Pass table to macro.forms.create to ask about an existing table's columns.
editResponse replaces the caller's answers while the form is open;
myResponse reads only that caller's receipt. Editors use responseSummary,
and tally is available to viewers when the owner enables tallyVisible.
Use sharePermissions and updateSharePermissions for sharing grants, and
update({ audience: 'public' }) to allow anonymous responses.
Creating, mutating, and deleting
const doc = await macro.documents.create({
name: 'Weekly update',
markdown: '# Week 32\n\n- shipped the thing',
});
await doc.rename('Weekly update (final)');
await doc.setTeamShare(true);
await doc.delete(); // soft delete; doc.restore() brings it back
Listing and searching
List/search methods that can page return a genreator that auto-paginates:
iterate with for await, and break early to stop fetching:
for await (const doc of macro.documents.recent()) {
console.log(await doc.name());
}
for await (const hit of macro.documents.search('quarterly revenue')) {
console.log(hit.webUrl());
}
You can request all with Array.fromAsync(...):
const allDocs = await Array.fromAsync(macro.documents.recent());
Properties and favorites
Most entities carry user-defined properties and can be favorited:
await doc.favorite();
await doc.setProperty(macro.properties.byId('prop_status'), {
text: 'In review',
});
const props = await doc.properties();
Databases
Databases are collections of tables. Tables, columns, and views are parts of a database, not entities of their own, so they come back as handles that resolve through the database's schema.
SQL is available through database.query(sql) or
macro.databases.query(sql, { database }). The scoped database resolves
unqualified names; joins can reach any other database the caller can view.
Results contain discriminated cell values, typed source rows and table-version
handles. SQL can also write; a statement executes once without automatic retries.
const database = macro.databases.byId('database-id');
const result = await database.query('SELECT "Name" FROM "Guests"');
console.log(result.result?.rows);
await database.query(`UPDATE "Guests" SET "Status" = 'Going' WHERE "Name" = 'Sam'`, {
baseVersions: result.readVersions,
});
baseVersions guards written tables atomically. Check truncatedTables:
nonempty means a read hit the row cap and aggregates may be partial. SQL schemas
are dynamic, so result cells use a generated tagged union rather than an inferred
TypeScript interface for each table. The HTTP route is POST /databases/query.
The SDK's schema methods write typed ops through one endpoint,
POST /databases/{id}/ops. The methods below each send a one-op batch: the
SDK mints the new table, column, and option ids (UUIDv7) itself and builds the
handle it returns from the op's result.
const database = await macro.databases.create({ name: 'Events' });
const guests = await database.createTable({ name: 'Guests' });
const email = await guests.addColumn({ name: 'Email', type: { type: 'text' } });
// A select column only accepts labels you give it, at creation or later.
const rsvp = await guests.addColumn({
name: 'RSVP',
type: { type: 'select', multi: false },
options: ['Yes', 'No'],
after: email,
});
await rsvp.addOptions(['Maybe']); // labels it already has are skipped
await guests.rename('Attendees');
await rsvp.rename('Response');
// A relation column holds rows of another table, named by handle.
const hosts = await database.createTable({ name: 'Hosts' });
await guests.addColumn({
name: 'Host',
type: { type: 'relation', table: hosts },
});
// See what each type change would do to the existing values first.
const casts = await rsvp.casts();
await rsvp.changeType({ to: { type: 'select', multi: true } });
// A type change converts every value or refuses, naming the misfits. To keep
// the original, add a column of the new type after it, filled with the values
// that convert ("Response (Text)" unless you pass a name).
await rsvp.convertIntoNewColumn({ to: { type: 'text' } });
// Tabs: a new database starts with a "Table 1". Reorder by naming every
// table once, or delete one; a database keeps at least one.
const tables = await database.tables();
await database.reorderTables(tables.toReversed());
await (await database.table('Table 1'))?.delete();
Changing a column's type, reordering columns, and deleting a column send the
table version last read as the batch's base version: if the table changed
since, the server refuses with a 409 and nothing is written.
convertIntoNewColumn is the exception to one op per call: it reads the
conversion (POST …/columns/{c}/conversion, which changes nothing), then sends
one batch that creates the column and fills it, at the version that read saw.
To do several things at once, send the ops yourself. They apply in order in
one transaction, later ops see what earlier ones did, and a refused op leaves
the whole batch unwritten. Each op names the resource it changes (a table,
column, rows, or view) and what change it makes; each result answers
with the same kind and what happened as its own change. Ids for new
tables, columns, options, and views are yours to mint, so a later op of the
batch can name them:
import { v7 as uuidv7 } from 'uuid';
const notes = uuidv7();
const results = await database.applyOps(
[
{
kind: 'column',
table: guests.id,
column: notes,
change: {
kind: 'create',
definition: { source: 'new', name: 'Notes', type: { type: 'text' } },
},
},
{
kind: 'rows',
table: guests.id,
change: {
kind: 'insert',
rows: [
[
{ column: email.id, value: { type: 'text', value: '[email protected]' } },
{ column: notes, value: { type: 'text', value: 'Vegetarian' } },
],
],
},
},
],
{ baseVersions: [{ table: guests, version: await guests.version() }] },
);
// results[1] is { kind: 'rows', table, tableVersion, change: { kind: 'inserted', rows: [rowId] } }
A refusal throws MacroOpRefusedError, naming the op at fault (op, and
row / column when one is) and, when the batch minted an id that already
names something, that id as taken ({ kind: 'table' | 'column' | 'option' | 'view', id }). A retried batch whose first attempt committed refuses this way.
import { MacroOpRefusedError } from '@macro-inc/sdk';
try {
await database.createTable({ name: 'Guests' });
} catch (error) {
if (error instanceof MacroOpRefusedError) console.log(error.op, error.taken);
}
A table's views are handles too. A board view reads where its cards sit:
for (const view of await guests.views()) {
const layout = await view.layout();
if (layout.kind === 'board') console.log(await view.positions());
}
Rich message helper
Use the msg tagged template to build rich message bodies for channel messages
or documents.
import { msg, here } from '@macro-inc/sdk';
const channel = macro.channels.byId('chan_1');
const user = macro.users.byId('user_1');
await channel.send(msg`Hey ${user}, take a look at ${doc}. cc ${here}`);
These will render as @mentions in the Macro UI.
Generating images
macro.images.generate() makes an image with Google's Nano Banana model, charged
to the acting user's AI allowance, and stores it as a static file. Attach it to a
message with images; its width and height let the message reserve space before
the image loads. Pass up to three image documents or earlier images as
referenceImages to edit or combine them. examples/generate-image.ts runs this
end to end.
const image = await macro.images.generate({
prompt: 'A watercolor lighthouse at dusk',
aspectRatio: 'widescreen',
});
await channel.send('Fresh off the press', { images: [image] });
const night = await macro.images.generate({
prompt: 'The lighthouse in image 1, at night under stars',
referenceImages: [image],
});
Posting to a channel webhook
The web UI can hand you a webhook URL and token for a channel. That token is a bot token, so it goes in the normal place:
const macro = new Macro({
auth: { type: 'bot', token: process.env.MACRO_WEBHOOK_TOKEN },
});
await macro.channels
.byId(channelId)
.send(msg`Deploy ${sha} finished. ${here}`);
Routines
Create scheduled or event-triggered agent tasks through macro.routines.
Routine configuration takes typed agent and event resource handles:
const routine = await macro.routines.create({
name: 'Daily summary',
prompt: 'Summarize my open tasks.',
userPrompt: 'A daily task summary',
trigger: { type: 'cron', schedule: '0 9 * * *', timezone: 'America/New_York' },
});
await routine.setEnabled(false);
const transcript = await routine.execute(); // Chat or AgentSession, if available
const executions = await routine.history(); // Each retains its parent routine
Event triggers use { type: 'events', filters: [{ events, entities, condition }] };
entities takes typed references such as { type: 'document', entity: doc }.
Use { type: 'multiple', triggers: [...] } to combine schedules and events.
routine.update(options) replaces task and trigger settings; delete() removes it.
Routines run as their owner, so share one as a template instead:
routine.shareAsTemplate({ description, variables }) publishes a snapshot,
routine.template() reads it (undefined when not shared), and
routine.activateTemplate(options) creates the caller's own routine from it.
routine.sourceTemplate() returns the routine a template came from.
Publishing, reading, and activating templates require the caller's
enable-routine-sharing PostHog flag. Disabled or unavailable evaluations return
404 (template() returns undefined). stopSharingTemplate() stays available
to owners, and previously activated routines continue working.
A GitHub trigger takes a filter of its own, with optional exact payload tests in
match. It needs the owner to have connected GitHub:
await routine.update({
...options,
trigger: {
type: 'events',
filters: [
{
events: ['github'],
github: { events: ['workflow_run'], actions: ['completed'], repositories: ['macro-inc/macro'] },
match: [
{ path: ['workflow_run', 'name'], equals: 'CI' },
{ path: ['workflow_run', 'conclusion'], in: ['failure', 'timed_out'] },
],
},
],
},
});
Agents, conversations and hosts
macro.agents.list/create/byId manage agent configuration. AgentOptions takes
channel, team and host handles. Updates replace the configuration.
channel.agentConversations() returns conversations with session and turn handles;
conversation.startFresh(session) and turn.retry(actionId) expose explicit
conversation controls. session.toolApprovalById(id).answer(answer) answers a
permission request scoped to that session.
macro.harnesses.list/me/byId manages agent hosts. createPairing(options) returns
separate pairing and device handles plus a device secret. Approve through
pairing.approve(...), then device.claim(deviceSecret); a pending claim returns
undefined. Host tokens and device secrets are never stored in entity handles.
Self-host operations (me, agents, sessions, deleteSelf) require the backend's
host authentication; ordinary user or bot credentials do not grant those rights.
Drafts, filters and follow-ups
const inbox = (await macro.email.links())[0];
const draft = await macro.email.createDraft({
subject: 'Follow-up',
to: [{ email: '[email protected]' }],
bodyHtml: '<p>Thanks for meeting.</p>',
}, inbox);
await draft.update({ subject: 'Follow-up notes', bodyText: 'Thanks for meeting.' });
const upload = await draft.addAttachment({ fileName: 'notes.txt', sha, size });
// Upload bytes to upload.uploadUrl, then verify before sending:
await upload.attachment.complete();
await draft.schedule('2026-11-01T09:00:00Z');
await draft.unschedule();
HTML input is UTF-8 encoded for the wire contract. Draft writes retain the draft's
inbox selection, including delegated inboxes. update replaces content; omitted
recipients and body fields follow the server's replacement semantics.
draft.forwardAttachment(attachment) returns a draft-scoped attachment handle.
Use its remove() method to detach it. email.scheduled({ inbox, pageSize })
automatically pages; breaking iteration stops further requests.
email.filters(inbox) and email.upsertFilter(options, inbox) return filter handles
with setImportant and delete. Omit the inbox to select the caller's primary.
email.contacts() returns the service's address/interaction buckets.
thread.calendarInvitations() reads resolved invitations. thread.followup() and
thread.setFollowup(command) expose revision-aware reminder state; commands require
caller-persisted operation IDs. email.reminders({ inboxes }) auto-paginates and
returns thread handles alongside reminder snapshots.
CRM pipelines and initiatives
macro.crm.pipelines.create/list/byId returns pipeline handles. Rename, sharing,
permissions and trash operations live on the pipeline. pipeline.table() returns
its table handle, with column and row handles. rows() and queryRows({ rows, query })
fetch through the pipeline's authorization boundary and auto-paginate.
(await pipeline.table()).views() returns scoped PipelineView handles;
view.detail() reads its definition and view.positions() reads its saved board
order through pipeline permissions.
pipeline.applyOps(ops, { baseVersions: [{ table, version }] }) accepts the generated
atomic database operation contract, including batch-local UUIDs, like
Database.applyOps. Table and column reads share a schema cache invalidated by
successful batches. Call row.refresh() to reload a row after a batch changes it.
macro.initiatives.create/list/byId groups tasks and members. Relations return user
and task handles; initiative.update({ name, members, sharePermission }) and
delete() manage it.
Access requests and message threads
Documents, chats, projects, initiatives, databases, calls, email threads and agent
sessions expose .access. access.state() returns review rights, typed requests,
and an optional continuation offset. submit(level), cancel(revision),
request.resolve(level), direct(), grant(user, level), and remove(user) use
server authorization and optimistic request revisions. Omit the level on
request.resolve() to decline. Resolved request handles retain their result even
after they leave the pending listing.
New sharing updates use SharePermissionOptions: channel grants name a channel
handle, operation (add, replace, remove) and optional access level.
Channels, documents, CRM companies/contacts and calls expose
messageThreadById(id) for thread resolution, anchor detachment and deletion.
timelinePage({ messages, around, cursor, limit }) returns a mixed timeline with
seeded message handles and typed activity actors. Selectors must belong to the same
parent. Cursors are opaque; pass the returned cursor on the next request.
channel.recordActivity(type) records a view or interaction; channels.activity()
reads activity handles. ChannelPicture.byId(uploadId) references an uploaded
picture for channel.setPicture(picture); omit it to clear the picture.
Meetings and calendar browsing
macro.meetings.create/list/active/lookup returns meeting handles. list() contains
the caller's newest 100 standalone meetings; use lookup(invitationToken) for
channel meetings and other invitations. A seeded meeting retains its lookup token
when mutations invalidate metadata. update, cancel, invite(email),
inviteUsers(users), invitePermissions and webUrl live on the meeting.
call.meeting() creates or reads its shareable meeting; calls also expose
editTranscript(assignments) and toggleTeamShare().
Programmatic calls
Use macro.calls.active() to find joinable live calls and reconcile missed
call.* events. macro.calls.summaries(calls) previews live or archived call
handles in one request. channel.activeCall() checks without starting a call; use
channel.startCall() only when intending to ring channel members. A live
call.join() never creates a replacement call. meeting.join() enters with
an account and meeting.joinAsGuest(name) uses the invitation link.
Each entry returns a CallConnection with the LiveKit URL, token, identity,
room name, call handle, and started flag. Pass the token directly to a
LiveKit client; it is omitted from JSON and console inspection. Call
connection.leave() when finished. Joins default to onOtherCall: 'fail';
pass { onOtherCall: 'switch' } to move intentionally, or { replace: true }
to take over an existing connection for the same identity. Branch on
InOtherCallError, AlreadyConnectedError, and CallEndedError.
call.ringState() reads this account's ring state, call.participants() reads
the live roster with user handles, call.decline() declines its ring,
call.discussion() returns the call chat or its channel thread, and
call.recording.bytes() downloads through the Macro host. Historical
participants remain available as call.historicParticipants().
calendar.occurrences(viewport) auto-paginates and seeds event handles.
calendar.teamPage(viewport) includes the roster and an optional next cursor;
teamOutOfOffice(viewport) reports hasMore when its bounded results are truncated.
availabilityCalendars, calendar.setContributesToAvailability, teamSharing and
setTeamSharing manage availability and sharing preferences.
Editing documents and tasks
document.edit(instructions, options) edits a markdown document or a task's body
by natural-language instructions. The AI editor merges its changes with anyone
editing at the same time. Say where (name the section or quote the text) and
describe the outcome:
const { revision, webUrl } = await document.edit(
'Rewrite the "Summary" section as three bullet points. Keep the heading.',
{ fast: true },
);
It returns the new revision, not a diff; read content() to see what changed.
options.signal cancels the edit, keeping what was applied before the abort. A
refused edit throws DocumentEditRefusedError with the editor's reason;
EditOutcomeUnknownError means read the document before retrying.
Document lifecycle and other resources
documents.createUpload(options) reserves a binary document and returns upload
instructions. document.prepareSave(parts), save(options) and simpleSave() expose
the existing content lifecycle; upload bytes before committing. Version handles
come from document.version(number). PDF highlights and comment anchors are scoped
handles from anchors() / createHighlight(options), with kind-checked edits and
deletion. documents.byTeamSlug('ENG-42') resolves a task reference.
sharePermissions, permissionsToken and documents.validatePermissionsToken
expose document access contracts.
macro.githubPullRequests.byId(foreignEntityId) reads stored GitHub snapshots;
changes() returns a changeset handle with patch(). macro.entityMentions.create
takes typed source/target references and returns a deletable mention handle.
macro.unfurls.get(url) and bulk(urls) read URL preview metadata.
macro.apiKeys.create(name) returns { key, secret }. Save the secret immediately;
the handle only retains metadata. list() and key.delete() manage keys.
tokenForEmail(email) exchanges credentials subject to ordinary server authorization.
chat.send({ content, model, attachments, toolset }) starts a generation and returns
its chat, response message and cancellable stream handle. Use
generation.message.refresh() after it changes; reading an unfinished response
may report that it is not yet available. Tools can perform writes unless disabled.
macro.ai.usage({ from, until, users, features }) reads AI usage.
Events
macro.events is always available. The default transport is a live SSE
stream — no public URL, persisted webhook, or signing secret required.
const macro = new Macro({
token: process.env.MACRO_API_KEY,
});
const me = await macro.users.me();
macro.events.on('message.posted', async ({ metadata, target }) => {
if (metadata.sender === me.id) return; // don't reply to ourselves
if (target.type === 'channel') await target.message.reply('hi!');
else await target.comment.reply('hi!');
});
const stop = await macro.events.listen();
// later: stop();
listen() opens GET /webhook/events/stream with the same WebhookFilters
model as persisted webhooks. If you omit filters, it derives one filter from
the event names already registered with .on(). Pass scope: 'team' for a
team workspace (defaults to 'user'). Delivery is best-effort: there is no
replay if you disconnect.
Handlers receive the same hydrated payloads as webhook deliveries — ORM handles for every entity the event names.
Four families are delivered: document.*, channel.*, message.*, and
agent_session.*. Message events (posted, patched, deleted, mentioned,
attachment_created, attachment_removed) cover channel messages and document
comments alike: metadata.parent names the channel or document, and the
hydrated target carries a Channel plus Message (and the Thread for a
reply) or a Document plus Comment. macro.events.onSelfMention subscribes to
message.mentioned deliveries that name the caller.
Agent-session events describe a coding agent's life: opened, turn_started,
turn_ended, settled (a turn ended with nothing queued behind it),
waiting_for_input (the agent asked its owner a question), input_received,
mentioned (a prompt named other users who can see the session), stopped,
renamed, and deleted. Each carries the session's identity and
hydrates to an AgentSession handle, the owner User, and, for a session
opened from a channel thread, the Channel, Thread, and magic-chip
Message the turn renders into.
macro.events.on('agent_session.settled', async ({ metadata, session, thread }) => {
console.log(`${metadata.identity.bot_name} finished: ${metadata.last_turn?.excerpt}`);
await thread?.reply(msg`Done — see ${session}`);
});
Persisted webhooks
To receive the same events as HTTPS POSTs instead of (or in addition to) SSE,
register a webhook and pass a webhookSecret (or set MACRO_WEBHOOK_SECRET).
Use a framework like Hono or Express to handle the request; the SDK verifies
the signature and dispatches.
const macro = new Macro({
token: process.env.MACRO_API_KEY,
webhookSecret: process.env.MACRO_WEBHOOK_SECRET,
});
macro.events.on('message.posted', async ({ metadata, target }) => {
if (metadata.sender === me.id || target.type !== 'channel') return;
await target.message.reply('hi!');
});
// Hono
app.post('/webhook', (c) => macro.events.webhook()(c.req.raw));
Call chat events have event.target.type === 'call', with a CallRecord in
event.target.call and a CallMessage in event.target.message. Read with
content(), or call reply(body), edit(body), and delete(). Replies always
join the call's single chat thread, even when responding to another reply.
macro.calls.byId(callId).message(messageId) creates the same lazy message handle.
Upgrading to 0.2
Channel messages, document comments, and CRM company and contact comments share
one API, /messages/{parent_type}/{parent_id}, and the SDK entities follow it.
The old channel message, document comment, and CRM comment routes are removed
from the server in the same release, so 0.1 clients stop working against it.
The public Channel, Message, Thread, Document, Company, and Contact
methods keep their names; these details changed:
Channel.messages()andChannel.messagesAfter()page with the structuredMessageCursorand yieldMessagehandles seeded from the shared message record (mentionsare now populated from list reads too).Channel.typing(action)takes'start' | 'stop'and posts to/messages/channel/{id}/typing.Message.from(client, channelId, record)replacesMessage.from(client, record),Message.fromReply, andMessage.received.Commentids are message UUIDs:Comment.commentIdis gone,Comment.threadId()is async and returns the root comment id,Comment.editaccepts a rich body, andComment.replyexists.Document.comment(body, { threadId })takes a string thread id and a rich body;Document.comments()returns{ thread: ThreadState, comments }per live thread.CrmCommentis a message-backed comment on its company or contact (parent: { type: 'crm_company' | 'crm_contact', id }). Its ids are message UUIDs (imported comments kept their old ids);text,createdAt,updatedAt, anddeletedAtare lazy accessors;threadId()andauthor()are async;editaccepts a rich body; andreplyexists.owner,sender,order, andmetadataare gone.Company.comments()andContact.comments()return{ thread: ThreadState, comments }per live thread;comment(body, { threadId })replacescomment({ text, threadId });commentById(id)returns a handle;editCommentanddeleteCommentare replaced byCrmComment.editandCrmComment.delete. Deleting a thread's root keeps its replies, as it does for channel and document threads.- Webhook and SSE events
channel.message_posted,channel.mentioned,channel.message_patched,channel.message_deleted,channel.message_attachment_created, andchannel.message_attachment_removedare replaced bymessage.posted,message.mentioned,message.patched,message.deleted,message.attachment_created, andmessage.attachment_removed. Their metadata carriesparentinstead ofchannel_id, and handlers receivetarget(see Events above) instead ofchannel/message/thread.onSelfMentionhandlers now receivemessage.mentionedevents. Update persisted webhook filters accordingly.
Removed storage operations and their replacements: getChannelMessages →
messageTimeline; getChannelMessagesCatchUp → messageTimeline with
activity_after; getThreadReplies → entityMessageGetThread;
getMessageWithContext → entityMessageGetMessage / messageTimeline with
around; postMessage → entityMessageCreate; patchMessage →
entityMessageEdit; deleteMessage → entityMessageDeleteMessage;
postReaction → entityMessageReact; postTyping → entityMessageTyping;
getDocumentComments → messageTimeline + entityMessageGetThread on a
document parent; createComment → entityMessageCreate; editComment →
entityMessageEdit; deleteComment → entityMessageDeleteMessage;
listCrmComments → messageTimeline + entityMessageGetThread on a
crm_company or crm_contact parent; createCrmComment →
entityMessageCreate; editCrmComment → entityMessageEdit;
deleteCrmComment → entityMessageDeleteMessage.
Developing
This section is just if you are contributing to the SDK.
Releases
See Releasing the SDK for patch version bumps, npm setup,
and tag-triggered publishing. Agents can use the
release-sdk skill.
Coverage checking
We have a coverage checker. It reads every generated function and ensures that
every client function that is generated is called by some hand-written function
in src/. If a generated function is not called, the coverage checker will fail
the build.
You can add exceptions for stuff OpenAPI covers that we don't want the sdk to
support by adding them to the src/coverage/skipped.ts. You can implement
support by adding a wrapper to the appropriate model. There is CI to ensure that
we don't forget to add coverage or explicitly skip coverage for new generated
functions (endpoints).
Events
Event names and payloads are generated from the backend: the Rust webhook
crate exposes a WebhookEvent union in the storage OpenAPI spec, and
src/events/types.ts derives EventName / EventPayload from it. SSE
(listen()) and persisted webhooks (webhook()) dispatch the same union.
AI generation and decisions
Shared cognition endpoints are available through macro.ai. They use the
authenticated user's model access and AI allowance. For generation using only
supplied context, explicitly set toolset: { type: 'none' }:
const answer = await macro.ai.structuredCompletion({
prompt: 'Summarize these supplied notes: ...',
model: 'google/gemini-3.8-flash',
toolset: { type: 'none' },
output_schema: {
name: 'Summary',
schema: {
type: 'object',
properties: { summary: { type: 'string' } },
required: ['summary'],
},
},
});
const decision = await macro.ai.decide({
input: { subject: 'Invoice due tomorrow', body: 'Please pay by Friday.' },
questions: { needsAction: 'Does this ask the recipient to take action?' },
});
console.log(answer.outcome, decision.probabilities.needsAction);
Decision probabilities estimate yes independently for each named question; they
do not authorize any action. Structured completions with tools enabled can modify
data, so inspect outcome and toolActivity even when generation is interrupted.
Workspace browsing
Use macro.workspace.page(options) for a bounded page or
macro.workspace.list(options) for lazy automatic pagination. Results include
existing entity handles plus generated API snapshots, so metadata does not
require a second request:
const page = await macro.workspace.page({
includeTypes: ['document'],
sortBy: 'recently_updated',
limit: 5,
});
for (const item of page.items) {
if (item.type === 'document') console.log(item.id, item.name);
}
console.log({ hasMore: page.hasMore, nextCursor: page.nextCursor });
The namespace supports documents (including tasks), AI chats, projects, email,
channels, channel threads, call records, calendar events and foreign entities.
Options preserve source scope through server-side type, time, property, task,
favorites, tag and inbox filters. Tags accept personal/team scopes and any/all
matching; ambiguous all-matches and unknown labels fail explicitly. Inbox names
resolve against all accessible inboxes, including delegated inboxes. limit
controls page size (default 50, maximum 500); break a for await loop to stop
without fetching another page. The TypeDoc namespace reference includes task,
date-window, signal-email and scoped-tag examples.
Saved code executions
An execution is a lazy entity handle scoped to its agent session. Construct it
with the execution ID from an ExecuteCode receipt, then read fields on the handle:
const session = macro.agentSessions.byId(sessionId);
const execution = session.codeExecutions.byId(executionId);
const status = await execution.status();
const source = await execution.source();
const result = await execution.result();
const calls = await execution.calls();
await execution.refresh(); // Reload after a running execution changes.
Constructing the handle makes no request. Field reads share a cached record;
refresh() reloads it. execution.session() returns the parent session handle.
Every read remains authorized and scoped by both session and execution identity.
Persistent code-execution reviews
A code execution can prepare a saved UI review and finish immediately. The review
is presented immediately through the ordinary ACP tool-call stream and remains
editable after the execution exits. session.reviews.create(...) uses the same
presentation without requiring a code execution. The session owner can
send one email, send all remaining emails, create a reviewed calendar event, or
answer a question. External actions only happen on submission.
const execution = macro.agentSessions.byId(sessionId)
.codeExecutions.byId(executionId);
const review = await execution.reviews.create({
kind: 'email',
title: 'Follow-up emails',
drafts: people.map((person) => ({
subject: 'Following up',
body: `Hello ${person.name},\n\nThanks for joining us.`,
to: [{ email: person.email, name: person.name }],
})),
});
return { data: { prepared: people.length }, reviews: [await review.reference()] };
execution.reviews.list() returns fresh SessionReview handles.
session.reviews.byId(id) constructs a lazy handle; review.items() returns item
handles with edit(draft), submit(), and dismiss() methods. submitAll() and
dismissAll() act on the pending items. Writes use the saved revision. After a
conflict, refresh and inspect the review; never automatically retry a send whose
outcome is unknown. These SDK methods have the same user authorization as the
ordinary API: review cards offer a user workflow, not a separate security grant.
External chats and WhatsApp
Pair your personal account in Macro's External view first. Your WhatsApp chat
list (whatsapp.chats()) holds groups and direct chats; adding one makes an
independent ExternalChat entity (a group or a direct chat, with provider
whatsapp) with its own history and ordinary sharing, and its earlier messages
are imported from your phone. externalChats.list() returns every added chat
you can view; shared viewers can read without WhatsApp. Sending and media
uploads require your own connected account in the chat, using your personal
session or own API credential; only the owner sends in a direct chat, and bots
never send. Adding and removing require a personal bearer session. Each user is
limited to one send request per second across all chats.
const personal = new Macro({
auth: { type: 'user', token: () => session.accessToken() },
});
let chat;
for (const entry of await personal.whatsapp.chats()) {
if (await entry.canAdd()) {
chat = await entry.add();
break;
}
}
if (chat && (await chat.canSend())) {
const [someone] = await chat.participants();
const send = await chat.send(
{
type: 'text',
text: someone ? `Hello @${someone.mentionToken}` : 'Hello',
mentions: someone ? [someone] : [],
},
{ idempotencyKey: crypto.randomUUID() },
);
await send.refresh();
console.log(await send.state());
}
for (const shared of await personal.externalChats.list()) {
for await (const message of shared.messages()) console.log(await message.body());
}
Keep the same idempotency key when retrying the same request. A delivery state of
unknown must be reconciled; never automatically resend it. Uploads, quoted
messages, mentions, mutations, and delivery references must belong to the same chat.
Live call media
Use @macro-inc/sdk/calls/node or @macro-inc/sdk/calls/browser for room
connections and screen sharing. Install the optional LiveKit runtime only when
using those helpers. The core import does not load or bundle call media code.
See Call rooms for installation and examples.