@rox-one/sdk 0.7.0 → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/dist/generated/email/types.gen.d.ts +4 -4
  2. package/dist/src/config.d.ts +3 -3
  3. package/dist/src/entities/activity/namespace.d.ts +3 -3
  4. package/dist/src/entities/agent-sessions/namespace.d.ts +4 -4
  5. package/dist/src/entities/ai/namespace.d.ts +1 -1
  6. package/dist/src/entities/calendar/booking-namespace.d.ts +1 -1
  7. package/dist/src/entities/calendar/namespace.d.ts +2 -2
  8. package/dist/src/entities/canvases/canvas.d.ts +1 -1
  9. package/dist/src/entities/channels/channel.d.ts +3 -3
  10. package/dist/src/entities/channels/message.d.ts +1 -1
  11. package/dist/src/entities/channels/namespace.d.ts +1 -1
  12. package/dist/src/entities/channels/thread.d.ts +2 -2
  13. package/dist/src/entities/chats/namespace.d.ts +2 -2
  14. package/dist/src/entities/connected-apps/namespace.d.ts +3 -3
  15. package/dist/src/entities/crm/pipelines.d.ts +1 -1
  16. package/dist/src/entities/databases/namespace.d.ts +4 -4
  17. package/dist/src/entities/databases/saved-query.d.ts +1 -1
  18. package/dist/src/entities/documents/document.d.ts +1 -1
  19. package/dist/src/entities/documents/namespace.d.ts +5 -5
  20. package/dist/src/entities/email/body-rox-compat.d.ts +22 -0
  21. package/dist/src/entities/email/draft.d.ts +5 -1
  22. package/dist/src/entities/email/namespace.d.ts +2 -2
  23. package/dist/src/entities/external-chat/namespace.d.ts +2 -2
  24. package/dist/src/entities/favorites/namespace.d.ts +1 -1
  25. package/dist/src/entities/harnesses/namespace.d.ts +1 -1
  26. package/dist/src/entities/images/image.d.ts +2 -2
  27. package/dist/src/entities/images/namespace.d.ts +2 -2
  28. package/dist/src/entities/initiatives/initiative.d.ts +1 -1
  29. package/dist/src/entities/me/namespace.d.ts +5 -5
  30. package/dist/src/entities/memory/namespace.d.ts +4 -4
  31. package/dist/src/entities/pins/namespace.d.ts +1 -1
  32. package/dist/src/entities/projects/namespace.d.ts +1 -1
  33. package/dist/src/entities/routines/namespace.d.ts +8 -8
  34. package/dist/src/entities/routines/suggestion.d.ts +1 -1
  35. package/dist/src/entities/search/namespace.d.ts +6 -6
  36. package/dist/src/entities/search/options.d.ts +1 -1
  37. package/dist/src/entities/spreadsheets/spreadsheet.d.ts +6 -6
  38. package/dist/src/entities/suggestions/namespace.d.ts +5 -5
  39. package/dist/src/entities/suggestions/suggestion.d.ts +3 -3
  40. package/dist/src/entities/ui/app-link.d.ts +2 -2
  41. package/dist/src/entities/ui/namespace.d.ts +3 -3
  42. package/dist/src/entities/users/namespace.d.ts +2 -2
  43. package/dist/src/entities/users/profile-picture.d.ts +1 -1
  44. package/dist/src/entities/users/user.d.ts +3 -3
  45. package/dist/src/entities/web/namespace.d.ts +3 -3
  46. package/dist/src/entities/webhooks/webhook.d.ts +2 -2
  47. package/dist/src/entities/whatsapp/namespace.d.ts +2 -2
  48. package/dist/src/entities/workspace/namespace.d.ts +6 -6
  49. package/dist/src/events/receiver.d.ts +3 -3
  50. package/dist/src/rox.d.ts +1 -0
  51. package/dist/src/rox.js +60 -46
  52. package/dist/src/utils/unwrap.d.ts +1 -1
  53. package/package.json +1 -1
@@ -148,7 +148,7 @@ export type ApiDraftInput = {
148
148
  /**
149
149
  * Rox body format.
150
150
  */
151
- body_macro?: string | null;
151
+ body_rox?: string | null;
152
152
  /**
153
153
  * Plain text body.
154
154
  */
@@ -218,7 +218,7 @@ export type ApiDraftOutput = {
218
218
  /**
219
219
  * Rox body.
220
220
  */
221
- body_macro?: string | null;
221
+ body_rox?: string | null;
222
222
  /**
223
223
  * Plain text body.
224
224
  */
@@ -300,7 +300,7 @@ export type ApiMessage = {
300
300
  attachments_forwarded: Array<ApiAttachmentForwarded>;
301
301
  bcc: Array<ApiContactInfo>;
302
302
  body_html_sanitized?: string | null;
303
- body_macro?: string | null;
303
+ body_rox?: string | null;
304
304
  body_replyless?: string | null;
305
305
  body_text?: string | null;
306
306
  calendar_invitations?: Array<CalendarInvitation>;
@@ -1515,7 +1515,7 @@ export type Message = {
1515
1515
  attachments_forwarded: Array<AttachmentForwarded>;
1516
1516
  bcc: Array<ContactInfo>;
1517
1517
  body_html_sanitized?: string | null;
1518
- body_macro?: string | null;
1518
+ body_rox?: string | null;
1519
1519
  body_text?: string | null;
1520
1520
  cc: Array<ContactInfo>;
1521
1521
  created_at: string;
@@ -58,14 +58,14 @@ export interface RoxOpts {
58
58
  webAppUrl?: string;
59
59
  /**
60
60
  * Signing secret for verifying incoming persisted-webhook deliveries.
61
- * Required only for `macro.events.webhook()` / `macro.events.handle()`.
62
- * SSE via `macro.events.listen()` uses the API token and does not need
61
+ * Required only for `rox.events.webhook()` / `rox.events.handle()`.
62
+ * SSE via `rox.events.listen()` uses the API token and does not need
63
63
  * this. Falls back to ROX_WEBHOOK_SECRET.
64
64
  */
65
65
  webhookSecret?: string;
66
66
  wsVerify?: string;
67
67
  /** User id the bot acts for, sent as `x-macro-bot-for-macro-user-id` on
68
- * every request. Bot auth only. Set via `macro.requestedAs(user)` rather
68
+ * every request. Bot auth only. Set via `rox.requestedAs(user)` rather
69
69
  * than directly. */
70
70
  requestedAs?: string;
71
71
  }
@@ -27,9 +27,9 @@ export interface ActivityRange {
27
27
  /**
28
28
  * The acting user's own action history across Rox.
29
29
  *
30
- * @routing Use when reading what the user did, opened, edited or sent in a time range, or a teammate's or project's history; not everything that changed in the workspace (`macro.workspace`).
30
+ * @routing Use when reading what the user did, opened, edited or sent in a time range, or a teammate's or project's history; not everything that changed in the workspace (`rox.workspace`).
31
31
  *
32
- * @agent `macro.activity.mine` lists the user's own raw actions (opened,
32
+ * @agent `rox.activity.mine` lists the user's own raw actions (opened,
33
33
  * edited, sent), including actions agents took for them; `User.activity`
34
34
  * reads privacy-reviewed daily, weekly and monthly summaries of the user's
35
35
  * or a teammate's work; `Initiative.activity` reads one project's history.
@@ -47,7 +47,7 @@ export declare class ActivityNamespace {
47
47
  * @example
48
48
  * const to = new Date();
49
49
  * const from = new Date(to.getTime() - 7 * 24 * 60 * 60 * 1000);
50
- * const { activities, truncated } = await macro.activity.mine({ from, to });
50
+ * const { activities, truncated } = await rox.activity.mine({ from, to });
51
51
  *
52
52
  * @readonly
53
53
  */
@@ -11,14 +11,14 @@ import { AgentSession, type AgentSessionUpdates, type CreateManagedSessionOption
11
11
  *
12
12
  * Do repository and coding work yourself when you can. Start another agent session only when the user asks for one, or the work needs a repository runtime you do not have.
13
13
  *
14
- * Start sessions from ExecuteCode. For coding work, macro.agents.coding() lists the coding personas the user can start right now, built-in ones such as Cursor included; for a chat agent, macro.agents.list() lists the user's configurable agents. Choose by name, description and instructions, preferring an agent the user named, and pass its `agent` handle to macro.agentSessions.createManaged. Never invent an agent or construct one by id. To use Macro's default persona instead, omit `agent`. Read AgentSessionNamespace.createManaged with ReadCodeDocs before the first call.
14
+ * Start sessions from ExecuteCode. For coding work, rox.agents.coding() lists the coding personas the user can start right now, built-in ones such as Cursor included; for a chat agent, rox.agents.list() lists the user's configurable agents. Choose by name, description and instructions, preferring an agent the user named, and pass its `agent` handle to rox.agentSessions.createManaged. Never invent an agent or construct one by id. To use Macro's default persona instead, omit `agent`. Read AgentSessionNamespace.createManaged with ReadCodeDocs before the first call.
15
15
  *
16
16
  * ```javascript
17
17
  * export async function main({macro}) {
18
- * const coding = await macro.agents.coding();
18
+ * const coding = await rox.agents.coding();
19
19
  * const chosen = coding.find((option) => option.name === 'Cursor');
20
20
  * if (!chosen) return {data: {error: 'Cursor is not connected', available: coding.map((option) => option.name)}};
21
- * const session = await macro.agentSessions.createManaged({
21
+ * const session = await rox.agentSessions.createManaged({
22
22
  * agent: chosen.agent,
23
23
  * repoUrl: 'https://github.com/acme/web',
24
24
  * prompt: 'Fix the login redirect loop in acme/web. ...',
@@ -31,7 +31,7 @@ import { AgentSession, type AgentSessionUpdates, type CreateManagedSessionOption
31
31
  *
32
32
  * ## Sessions waiting for the user
33
33
  *
34
- * macro.agentSessions.updates() lists the user's sessions waiting on them (permission requests, questions, held tool approvals) or stalled. The user answers them only on cards: in ExecuteCode, whenever it returns items, present them with execution.views.present({widgets: [{type: "agentUpdates", items: updates.items}]}). A session's held tool calls come from session.pendingApprovals(); approve or deny one only when the user said so for that call. session.linkTask(task) links a session the user owns to its Macro task, and the session's pull request with it.
34
+ * rox.agentSessions.updates() lists the user's sessions waiting on them (permission requests, questions, held tool approvals) or stalled. The user answers them only on cards: in ExecuteCode, whenever it returns items, present them with execution.views.present({widgets: [{type: "agentUpdates", items: updates.items}]}). A session's held tool calls come from session.pendingApprovals(); approve or deny one only when the user said so for that call. session.linkTask(task) links a session the user owns to its Macro task, and the session's pull request with it.
35
35
  */
36
36
  export declare class AgentSessionNamespace {
37
37
  private readonly client;
@@ -5,7 +5,7 @@ export type { DecisionRequest, DecisionResponse, StructuredCompletionRequest, St
5
5
  /**
6
6
  * Shared cognition endpoints, charged to the authenticated acting user.
7
7
  *
8
- * @routing Use when asking a model to answer named yes/no questions or fill a JSON Schema from content you supply, or when reading AI usage; not generating images (`macro.images`) or answering the user yourself.
8
+ * @routing Use when asking a model to answer named yes/no questions or fill a JSON Schema from content you supply, or when reading AI usage; not generating images (`rox.images`) or answering the user yourself.
9
9
  */
10
10
  export declare class AiNamespace {
11
11
  private readonly client;
@@ -43,7 +43,7 @@ export interface BookingInsightsQuery extends BookingScope {
43
43
  host?: User;
44
44
  }
45
45
  /**
46
- * Booking links (`macro.calendar.booking`): reusable booking pages, the
46
+ * Booking links (`rox.calendar.booking`): reusable booking pages, the
47
47
  * settings behind them, the meetings guests book through them, and their
48
48
  * statistics. Personal unless a `team` is given; any team member can read and
49
49
  * edit a team's.
@@ -93,10 +93,10 @@ export type CalendarEventRole = 'organizer' | 'guest';
93
93
  * @agent
94
94
  * ## Booking links
95
95
  *
96
- * - Booking links live under `macro.calendar.booking`. They are reusable booking pages, not
96
+ * - Booking links live under `rox.calendar.booking`. They are reusable booking pages, not
97
97
  * calendar meetings; the meetings guests book through them are `Booking`s.
98
98
  * - Booking links use conversational confirmation in every surface. First list
99
- * `macro.calendar.booking.links()` to find existing links and reusable availability. Resolve
99
+ * `rox.calendar.booking.links()` to find existing links and reusable availability. Resolve
100
100
  * teams and hosts from what it returns; never ask for IDs, revisions or JSON. Default to
101
101
  * personal ownership unless a team is requested. Explain the complete proposal in readable
102
102
  * prose: ownership and named hosts, who attends, meeting name and description, duration,
@@ -193,7 +193,7 @@ export declare class Canvas {
193
193
  *
194
194
  * @example Find the items labelled "Risk".
195
195
  * ```js
196
- * const canvas = macro.documents.byId(id).canvas();
196
+ * const canvas = rox.documents.byId(id).canvas();
197
197
  * const scene = await canvas.scene();
198
198
  * const risks = scene.items.filter((item) => item.text?.includes('Risk'));
199
199
  * return { data: { revision: scene.revision, risks: risks.map((item) => ({ id: item.id, bounds: item.bounds })) } };
@@ -123,8 +123,8 @@ export declare class Channel extends PropertiedEntity<ChannelDetail> {
123
123
  * Post a message; pass `silent: true` for a routine update that should
124
124
  * notify nobody. Plain text, or a rich body composed with `msg`.
125
125
  * `images` attaches static images, such as one from
126
- * `macro.images.generate()`, below the text; `documents` attaches Macro
127
- * documents as file chips, such as a file from `macro.documents.upload()`.
126
+ * `rox.images.generate()`, below the text; `documents` attaches Macro
127
+ * documents as file chips, such as a file from `rox.documents.upload()`.
128
128
  * `silent` sends no push, email or inbox entry to anyone, mentioned people
129
129
  * included; the message still appears in the channel.
130
130
  *
@@ -134,7 +134,7 @@ export declare class Channel extends PropertiedEntity<ChannelDetail> {
134
134
  *
135
135
  * @example Share a generated CSV.
136
136
  * ```js
137
- * const file = await macro.documents.upload({ name: 'q3.csv', content: csv });
137
+ * const file = await rox.documents.upload({ name: 'q3.csv', content: csv });
138
138
  * await channel.send('Q3 numbers attached.', { documents: [file] });
139
139
  * ```
140
140
  *
@@ -76,7 +76,7 @@ export declare class Message extends FavoritableEntity<MessageRecord> {
76
76
  author(): Promise<User>;
77
77
  /**
78
78
  * The message's URL in the Rox web app: its channel, scrolled to it. Pass
79
- * the message to `macro.ui.open` to show it to the user.
79
+ * the message to `rox.ui.open` to show it to the user.
80
80
  *
81
81
  * @readonly
82
82
  */
@@ -8,7 +8,7 @@ import { ChannelActivity } from './activity';
8
8
  import { Channel } from './channel';
9
9
  import { ChannelLabelsNamespace } from './labels';
10
10
  /**
11
- * @routing Use when reading or sending channel and direct messages, posting a poll, reacting or managing members; not email, or WhatsApp and other external chats (`macro.externalChats`).
11
+ * @routing Use when reading or sending channel and direct messages, posting a poll, reacting or managing members; not email, or WhatsApp and other external chats (`rox.externalChats`).
12
12
  *
13
13
  * @agent
14
14
  * ## Polls
@@ -47,9 +47,9 @@ export declare class Thread {
47
47
  *
48
48
  * @param body - Plain text, or a rich body composed with {@link msg}.
49
49
  * @param opts.images - Static images to attach, such as one from
50
- * `macro.images.generate()`.
50
+ * `rox.images.generate()`.
51
51
  * @param opts.documents - Rox documents to attach as file chips, such as
52
- * a file from `macro.documents.upload()`.
52
+ * a file from `rox.documents.upload()`.
53
53
  * @param opts.silent - Send no push, email or inbox entry to anyone,
54
54
  * mentioned people included; the reply still appears in the thread.
55
55
  * @returns The created reply.
@@ -5,8 +5,8 @@ import { Chat } from './chat';
5
5
  /**
6
6
  * The user's AI chats: earlier conversations with Rox's assistant, each
7
7
  * with its message history. Find one with {@link ChatNamespace.search},
8
- * `macro.search.all(query, {types: ['chat']})` or
9
- * `macro.workspace.list({includeTypes: ['ai_chat']})`, then read it with
8
+ * `rox.search.all(query, {types: ['chat']})` or
9
+ * `rox.workspace.list({includeTypes: ['ai_chat']})`, then read it with
10
10
  * `chat.history()`. Agent work and coding sessions are agent sessions, not
11
11
  * chats.
12
12
  *
@@ -14,17 +14,17 @@ export type { ConnectMcpServerResponse };
14
14
  * @agent
15
15
  * ## Connected apps
16
16
  *
17
- * Connected apps are reached only from an agent session's ExecuteCode program: pass the `execution` that `main` receives. `macro.connectedApps.list(execution)` returns the apps this agent was given (every app the user connected, or the agent's own selection); an app missing from it is not connected for this agent. Find a tool across every app with `macro.connectedApps.searchTools(execution, 'linear issue')`, or read one app's tools with `app.tools()`; pick one by name and description, read its `inputSchema`, then `tool.call(args)`.
17
+ * Connected apps are reached only from an agent session's ExecuteCode program: pass the `execution` that `main` receives. `rox.connectedApps.list(execution)` returns the apps this agent was given (every app the user connected, or the agent's own selection); an app missing from it is not connected for this agent. Find a tool across every app with `rox.connectedApps.searchTools(execution, 'linear issue')`, or read one app's tools with `app.tools()`; pick one by name and description, read its `inputSchema`, then `tool.call(args)`.
18
18
  *
19
19
  * Calls run in the user's real account through Rox's server, as the account this execution acts as, and take effect at once; the program never sees a credential. In a turn someone other than the session's owner prompted, each call that uses the owner's account waits for the owner to approve it, so make few such calls and expect a long wait or a refusal. Read before writing, and never repeat a write whose outcome is unknown: check the app's state first. A result with `isError` explains itself: when it says an app is not connected, tell the user and include the connect markup it gives you in your reply verbatim, then stop.
20
20
  *
21
21
  * Each account's calls to one app share a budget across its running programs on the same Macro server: a few run at once, paced, and the rest queue. Narrow first with the app's search or list tools and their own limits and filters (e.g. open PRs updated this week), then call per item only for the few items you need, in small batches; never `Promise.all` a call per item over a whole list. A call the app keeps refusing with HTTP 429 is retried after its `Retry-After`; one still refused throws a rate-limit error and did not run, so stop and report partial results rather than retrying in a loop.
22
22
  *
23
- * When an app the work needs is missing, find it with `macro.connectedApps.discover(execution, appName)` and `connector.inspect()` its advertised actions and connection status. Recommend connecting only when an advertised action supports the task; an app's name is not evidence. For a suitable unconnected app, put the inspection's `connectMarkup` in your reply verbatim and say what connecting enables. To add a remote MCP server the user gives you the URL of, use `macro.connectedApps.addServer(execution, {url, serverName})`; never guess a URL, and tell the user to sign in under Settings → Connections when its summary says so.
23
+ * When an app the work needs is missing, find it with `rox.connectedApps.discover(execution, appName)` and `connector.inspect()` its advertised actions and connection status. Recommend connecting only when an advertised action supports the task; an app's name is not evidence. For a suitable unconnected app, put the inspection's `connectMarkup` in your reply verbatim and say what connecting enables. To add a remote MCP server the user gives you the URL of, use `rox.connectedApps.addServer(execution, {url, serverName})`; never guess a URL, and tell the user to sign in under Settings → Connections when its summary says so.
24
24
  *
25
25
  * ```javascript
26
26
  * export async function main({macro, execution}) {
27
- * const apps = await macro.connectedApps.list(execution);
27
+ * const apps = await rox.connectedApps.list(execution);
28
28
  * const linear = apps.find((app) => app.key === 'linear');
29
29
  * if (!linear) return {data: {error: 'Linear is not connected', available: apps.map((app) => app.name)}};
30
30
  * const tools = await linear.tools();
@@ -38,7 +38,7 @@ export declare class PipelineNamespace {
38
38
  * standard ones. Private unless `sharing` is `team`.
39
39
  *
40
40
  * @example
41
- * await macro.crm.pipelines.create({
41
+ * await rox.crm.pipelines.create({
42
42
  * name: 'Hiring',
43
43
  * recordType: 'contact',
44
44
  * stages: ['Sourced', 'Interview', 'Offer', 'Hired'],
@@ -8,18 +8,18 @@ import { SavedQuery, type SaveQueryOptions } from './saved-query';
8
8
  *
9
9
  * A table the user names can be a tab inside a database with another name,
10
10
  * so look through every database's tables before saying it does not exist.
11
- * Person columns hold user ids, never names: find people in `macro.people`,
11
+ * Person columns hold user ids, never names: find people in `rox.people`,
12
12
  * then write their ids. Select the rows a write means first, then change
13
13
  * exactly those by `row_id`, and read them back before saying it worked.
14
14
  *
15
15
  * ```js
16
- * const databases = await macro.databases.list();
16
+ * const databases = await rox.databases.list();
17
17
  * const matches = await Promise.all(
18
18
  * databases.map(async (database) => ({ database, table: await database.table('Tickets') })),
19
19
  * );
20
20
  * const { database } = matches.find((match) => match.table);
21
21
  * const people = await database.query(
22
- * `SELECT id FROM macro.people WHERE email = 'sam@example.com'`,
22
+ * `SELECT id FROM rox.people WHERE email = 'sam@example.com'`,
23
23
  * );
24
24
  * const sam = people.result?.rows[0]?.[0]?.value;
25
25
  * const open = await database.query(`SELECT row_id FROM "Tickets" WHERE "Status" = 'Open'`);
@@ -65,7 +65,7 @@ import { SavedQuery, type SaveQueryOptions } from './saved-query';
65
65
  *
66
66
  * **Verify.** After a change, read back the affected schema or rows before claiming success. After an ambiguous failure, inspect the current state before retrying a create or insert. Never describe a proposed change as saved.
67
67
  *
68
- * **Answers.** Answer a question about the data, or a request for a chart, with a saved live query block beside a sentence stating the answer, never with a block you wrote or edited yourself: run the `SELECT` with `database.query`, save exactly that SQL with `database.saveQuery` (or `macro.databases.saveQuery` when it spans databases), and put its `toBlock()` in the document. Restyle an answer with `withView`; to ask something else, save a new question. A query result, a saved question, and a document containing its block are different outcomes: say which happened.
68
+ * **Answers.** Answer a question about the data, or a request for a chart, with a saved live query block beside a sentence stating the answer, never with a block you wrote or edited yourself: run the `SELECT` with `database.query`, save exactly that SQL with `database.saveQuery` (or `rox.databases.saveQuery` when it spans databases), and put its `toBlock()` in the document. Restyle an answer with `withView`; to ask something else, save a new question. A query result, a saved question, and a document containing its block are different outcomes: say which happened.
69
69
  */
70
70
  export declare class DatabaseNamespace {
71
71
  private readonly client;
@@ -38,7 +38,7 @@ export type SavedQueryDisplay = {
38
38
  chart: SavedQueryChart;
39
39
  };
40
40
  /**
41
- * Options for `macro.databases.saveQuery`, {@link Database.saveQuery} and
41
+ * Options for `rox.databases.saveQuery`, {@link Database.saveQuery} and
42
42
  * {@link DatabaseTable.saveQuery}.
43
43
  */
44
44
  export type SaveQueryOptions = {
@@ -273,7 +273,7 @@ export declare class Document extends PropertiedEntity<DocumentDetail> implement
273
273
  * ```js
274
274
  * const file = await attachment.toDocument();
275
275
  * const bytes = await file.bytes();
276
- * const copy = await macro.documents.upload({
276
+ * const copy = await rox.documents.upload({
277
277
  * name: await attachment.filename(),
278
278
  * content: bytes,
279
279
  * project,
@@ -41,7 +41,7 @@ export type FileContent = Uint8Array<ArrayBuffer> | ArrayBuffer | Blob | string;
41
41
  *
42
42
  * ## New spreadsheets
43
43
  *
44
- * `createSpreadsheet` saves the spreadsheet before it returns, so it exists even when a later step of the program throws. Keep its id across that failure: fill it inside `try`/`catch` and return `{ data: { spreadsheet: sheet, error } }` (the handle serializes as its `id` and `url`). To retry, reopen it with `macro.documents.spreadsheet(macro.documents.byId(id))`; never search recent documents for it or create another.
44
+ * `createSpreadsheet` saves the spreadsheet before it returns, so it exists even when a later step of the program throws. Keep its id across that failure: fill it inside `try`/`catch` and return `{ data: { spreadsheet: sheet, error } }` (the handle serializes as its `id` and `url`). To retry, reopen it with `rox.documents.spreadsheet(rox.documents.byId(id))`; never search recent documents for it or create another.
45
45
  *
46
46
  * ## Linking Rox items inside document content
47
47
  *
@@ -95,7 +95,7 @@ export declare class DocumentNamespace {
95
95
  * @example Upload a generated CSV and share it in a channel.
96
96
  * ```js
97
97
  * const rows = [['name', 'amount'], ['Acme', 1200]];
98
- * const file = await macro.documents.upload({
98
+ * const file = await rox.documents.upload({
99
99
  * name: 'invoices.csv',
100
100
  * content: rows.map((row) => row.join(',')).join('\n'),
101
101
  * });
@@ -161,7 +161,7 @@ export declare class DocumentNamespace {
161
161
  *
162
162
  * @example Create and fill a budget, keeping the spreadsheet if a step fails.
163
163
  * ```js
164
- * const sheet = await macro.documents.createSpreadsheet({ name: 'Q4 budget' });
164
+ * const sheet = await rox.documents.createSpreadsheet({ name: 'Q4 budget' });
165
165
  * try {
166
166
  * const { revision, sheets } = await sheet.read();
167
167
  * await sheet.applyEdits(
@@ -208,7 +208,7 @@ export declare class DocumentNamespace {
208
208
  * a skill mention or of a search result:
209
209
  *
210
210
  * ```js
211
- * const skill = macro.documents.byId(skillId);
211
+ * const skill = rox.documents.byId(skillId);
212
212
  * const instructions = await skill.content();
213
213
  * ```
214
214
  *
@@ -238,7 +238,7 @@ export declare class DocumentNamespace {
238
238
  * updated first, then built-in skills.
239
239
  *
240
240
  * ```js
241
- * const [match] = await macro.documents.skills({ query: 'deploy' });
241
+ * const [match] = await rox.documents.skills({ query: 'deploy' });
242
242
  * const instructions = match && (await match.skill.content());
243
243
  * ```
244
244
  *
@@ -0,0 +1,22 @@
1
+ /**
2
+ * The editor document used to be the Macro body. Payloads written before the
3
+ * rename — stored drafts, queued sends, cached threads — can still carry the
4
+ * former names, so readers accept both and prefer the Rox ones. Writers emit
5
+ * only the Rox names.
6
+ */
7
+ export type BodyNames = {
8
+ body_rox?: string | null;
9
+ bodyRox?: string | null;
10
+ body_macro?: string | null;
11
+ bodyMacro?: string | null;
12
+ };
13
+ export type RestoreBodyNames = {
14
+ restore_body_rox?: string | null;
15
+ restoreBodyRox?: string | null;
16
+ restore_body_macro?: string | null;
17
+ restoreBodyMacro?: string | null;
18
+ };
19
+ /** Read the editor body from a payload, preferring the Rox name over the former Macro one. */
20
+ export declare function readBodyRox(source: BodyNames | null | undefined): string | null;
21
+ /** Read the body a failed send restores to the editor, preferring the Rox name. */
22
+ export declare function readRestoreBodyRox(source: RestoreBodyNames | null | undefined): string | null;
@@ -4,7 +4,7 @@ import type { EmailAttachment } from './attachment';
4
4
  import { EmailMessage } from './message';
5
5
  import type { EmailThread } from './thread';
6
6
  /** Draft content; relationships use message and thread handles. */
7
- export type DraftOptions = Omit<ApiDraftInput, 'db_id' | 'provider_id' | 'provider_thread_id' | 'replying_to_id' | 'thread_db_id' | 'body_text' | 'body_html' | 'body_macro' | 'headers_json' | 'include_signature' | 'draft_generation'> & {
7
+ export type DraftOptions = Omit<ApiDraftInput, 'db_id' | 'provider_id' | 'provider_thread_id' | 'replying_to_id' | 'thread_db_id' | 'body_text' | 'body_html' | 'body_rox' | 'headers_json' | 'include_signature' | 'draft_generation'> & {
8
8
  /** Generation captured when editing began; defaults to the loaded draft. */
9
9
  draftGeneration?: number;
10
10
  /** Plain text body. */
@@ -12,7 +12,11 @@ export type DraftOptions = Omit<ApiDraftInput, 'db_id' | 'provider_id' | 'provid
12
12
  /** HTML body. */
13
13
  bodyHtml?: string;
14
14
  /** Rox body. */
15
+ bodyRox?: string;
16
+ /** Former name for `bodyRox`; payloads written before the rename still carry it. */
15
17
  bodyMacro?: string;
18
+ /** Former wire name for `bodyRox`; accepted from older payloads. */
19
+ body_macro?: string;
16
20
  /** Extra headers. */
17
21
  headers?: ApiDraftInput['headers_json'];
18
22
  /** Include the inbox signature. */
@@ -24,7 +24,7 @@ export interface InboxOptions extends IterationOptions {
24
24
  * @agent
25
25
  * ## Email inboxes
26
26
  *
27
- * - A user can have more than one inbox: their primary one, others they connected, and inboxes teammates delegated to them. `macro.email.links()` lists them; most users have one.
27
+ * - A user can have more than one inbox: their primary one, others they connected, and inboxes teammates delegated to them. `rox.email.links()` lists them; most users have one.
28
28
  * - Searching and listing span every inbox the user can access unless you pass one. When the user means a specific mailbox ("my work inbox", "the shared inbox"), find it in `links()` and pass that link; never guess an address.
29
29
  * - Labels are per inbox: a label from one inbox does not apply to a thread in another. Change a thread's labels with labels from the inbox that owns the thread.
30
30
  *
@@ -163,7 +163,7 @@ export declare class EmailNamespace {
163
163
  * Search email threads by subject and content. To find a person's emails,
164
164
  * search for their quoted email address, not their name: a name only
165
165
  * matches where that display name appears. Resolve the address first, for
166
- * example with `macro.users.search(name)`.
166
+ * example with `rox.users.search(name)`.
167
167
  *
168
168
  * @readonly
169
169
  */
@@ -3,9 +3,9 @@ import { ExternalChat } from './chat';
3
3
  /**
4
4
  * Chats from external messaging providers (WhatsApp today) that someone added
5
5
  * to Rox: read, share and send in them. Find and add a provider's chats
6
- * through its own namespace, such as `macro.whatsapp.chats()`.
6
+ * through its own namespace, such as `rox.whatsapp.chats()`.
7
7
  *
8
- * @routing Use when reading, sharing or sending in an external chat, such as a WhatsApp chat, already added to Macro; not Macro channels, or finding chats to add (`macro.whatsapp`).
8
+ * @routing Use when reading, sharing or sending in an external chat, such as a WhatsApp chat, already added to Macro; not Macro channels, or finding chats to add (`rox.whatsapp`).
9
9
  */
10
10
  export declare class ExternalChatsNamespace {
11
11
  private readonly client;
@@ -17,7 +17,7 @@ export type FavoritesFilter = {
17
17
  /**
18
18
  * The user's favorites: a manually ordered collection of entity references.
19
19
  *
20
- * @routing Use when adding or removing the user's favorites; not pins (`macro.pins`).
20
+ * @routing Use when adding or removing the user's favorites; not pins (`rox.pins`).
21
21
  */
22
22
  export declare class FavoritesNamespace {
23
23
  private readonly client;
@@ -7,7 +7,7 @@ import { DevicePairing, HarnessPairing } from './pairing';
7
7
  /**
8
8
  * Hosts and device pairing. Self operations require host credentials.
9
9
  *
10
- * @routing Use when listing, pairing, renaming or sharing the machines (agent hosts) that run the user's agents, or the agents living on them; not changing an agent persona's setup (`macro.agents`).
10
+ * @routing Use when listing, pairing, renaming or sharing the machines (agent hosts) that run the user's agents, or the agents living on them; not changing an agent persona's setup (`rox.agents`).
11
11
  */
12
12
  export declare class HarnessNamespace {
13
13
  private readonly client;
@@ -1,7 +1,7 @@
1
1
  import type { RoxClient } from '../../utils/client';
2
2
  /**
3
3
  * An image in static file storage: an upload, a render from
4
- * `canvas.render()`, or one made with `macro.images.generate()`. Attach it to
4
+ * `canvas.render()`, or one made with `rox.images.generate()`. Attach it to
5
5
  * a channel message with `channel.send(text, { images: [image] })`, show it in
6
6
  * a reply or Markdown with {@link StaticImage.toMarkdown}, or pass it back to
7
7
  * `generate` as a reference. It is not a document: never mention its `id` as
@@ -50,7 +50,7 @@ export declare class StaticImage {
50
50
  markdown: string;
51
51
  };
52
52
  }
53
- /** An image made by `macro.images.generate()`, stored as a static file. */
53
+ /** An image made by `rox.images.generate()`, stored as a static file. */
54
54
  export declare class GeneratedImage extends StaticImage {
55
55
  /** Intrinsic pixel width. */
56
56
  readonly width: number;
@@ -26,7 +26,7 @@ export interface GenerateImageOptions {
26
26
  /**
27
27
  * Image generation, charged to the acting user's AI allowance.
28
28
  *
29
- * @routing Use when generating an image; not structured output or classification (`macro.ai`).
29
+ * @routing Use when generating an image; not structured output or classification (`rox.ai`).
30
30
  */
31
31
  export declare class ImagesNamespace {
32
32
  private readonly client;
@@ -43,7 +43,7 @@ export declare class ImagesNamespace {
43
43
  * let the message reserve space before the image loads.
44
44
  *
45
45
  * @example
46
- * const image = await macro.images.generate({
46
+ * const image = await rox.images.generate({
47
47
  * prompt: 'A watercolor lighthouse at dusk',
48
48
  * aspectRatio: 'widescreen',
49
49
  * });
@@ -76,7 +76,7 @@ export declare class Initiative extends RoxEntity<InitiativeDetail> {
76
76
  readonly members: () => Promise<User[]>;
77
77
  /**
78
78
  * Tasks in this initiative. For their names, pass them to
79
- * `macro.tasks.summaries` (one request) instead of calling `name()` on each.
79
+ * `rox.tasks.summaries` (one request) instead of calling `name()` on each.
80
80
  */
81
81
  readonly tasks: () => Promise<Task[]>;
82
82
  /** Current user's access. */
@@ -15,7 +15,7 @@ export interface UpdateMeOptions {
15
15
  /**
16
16
  * An image from {@link MeNamespace.uploadProfilePicture}. To switch back to
17
17
  * an earlier upload without uploading again, pass its handle again, or
18
- * `macro.images.byId(savedId)`. Setting is throttled to once a second per
18
+ * `rox.images.byId(savedId)`. Setting is throttled to once a second per
19
19
  * user; a faster call fails with 429.
20
20
  */
21
21
  profilePicture?: StaticImage;
@@ -23,7 +23,7 @@ export interface UpdateMeOptions {
23
23
  /**
24
24
  * The authenticated user's own profile.
25
25
  *
26
- * @routing Use when reading who the user is or changing their own name or profile picture; not looking up other people (`macro.users`).
26
+ * @routing Use when reading who the user is or changing their own name or profile picture; not looking up other people (`rox.users`).
27
27
  */
28
28
  export declare class MeNamespace {
29
29
  private readonly client;
@@ -53,13 +53,13 @@ export declare class MeNamespace {
53
53
  * signing in, so teammates can tell who they are working with.
54
54
  *
55
55
  * @example
56
- * const image = await macro.me.uploadProfilePicture(bytes, {
56
+ * const image = await rox.me.uploadProfilePicture(bytes, {
57
57
  * fileName: 'avatar.png',
58
58
  * contentType: 'image/png',
59
59
  * });
60
- * await macro.me.update({ name: 'Research Agent', profilePicture: image });
60
+ * await rox.me.update({ name: 'Research Agent', profilePicture: image });
61
61
  * // Later, switch back to it from its saved id:
62
- * await macro.me.update({ profilePicture: macro.images.byId(savedId) });
62
+ * await rox.me.update({ profilePicture: rox.images.byId(savedId) });
63
63
  *
64
64
  * @write
65
65
  * @idempotent
@@ -5,7 +5,7 @@ export type { ExplicitMemory, MemoryEdit };
5
5
  * The acting user's private explicit memory: the preferences and facts they
6
6
  * asked AI to remember, one per line.
7
7
  *
8
- * @routing Use when the user asks to remember, correct or forget something, or to see what AI remembers about them; not what someone worked on (`macro.activity`, `User.activity`).
8
+ * @routing Use when the user asks to remember, correct or forget something, or to see what AI remembers about them; not what someone worked on (`rox.activity`, `User.activity`).
9
9
  *
10
10
  * @agent Change memory only when the user explicitly asks to remember,
11
11
  * correct or forget something; never save inferred preferences. Read first:
@@ -21,7 +21,7 @@ export declare class MemoryNamespace {
21
21
  * newline-separated, and edits address its one-based lines.
22
22
  *
23
23
  * @example
24
- * const memory = await macro.memory.read();
24
+ * const memory = await rox.memory.read();
25
25
  * const lines = memory.content.split('\n');
26
26
  *
27
27
  * @readonly
@@ -36,9 +36,9 @@ export declare class MemoryNamespace {
36
36
  * retrying. Insert at `lines.length + 1` to append.
37
37
  *
38
38
  * @example
39
- * const memory = await macro.memory.read();
39
+ * const memory = await rox.memory.read();
40
40
  * const lines = memory.content ? memory.content.split('\n') : [];
41
- * await macro.memory.edit(
41
+ * await rox.memory.edit(
42
42
  * { action: 'insert', line: lines.length + 1, content: 'Prefers metric units' },
43
43
  * memory.revision,
44
44
  * );
@@ -5,7 +5,7 @@ export type { PinnedItem, ReorderPinRequest };
5
5
  /**
6
6
  * The user's pins: items pinned to fixed slots in the home view.
7
7
  *
8
- * @routing Use when pinning or unpinning items; not favorites (`macro.favorites`).
8
+ * @routing Use when pinning or unpinning items; not favorites (`rox.favorites`).
9
9
  */
10
10
  export declare class PinsNamespace {
11
11
  private readonly client;
@@ -13,7 +13,7 @@ import { Project } from './project';
13
13
  * @example Link an agent session from a project.
14
14
  * ```js
15
15
  * const chip = JSON.stringify({ id: session.id, label: '', expanded: true });
16
- * const document = await macro.documents.create({
16
+ * const document = await rox.documents.create({
17
17
  * name: 'Agent work',
18
18
  * project,
19
19
  * markdown: `<m-agent-session-mention>${chip}</m-agent-session-mention>`,