@rox-one/sdk 0.0.0-stage → 0.7.0
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.
- package/CALLS.md +82 -0
- package/README.md +1259 -2
- package/dist/chunk-AOHK5YXC.js +5585 -0
- package/dist/chunk-CATFKTFD.js +80 -0
- package/dist/chunk-FQGPXWPJ.js +1491 -0
- package/dist/chunk-G43PLP2U.js +1087 -0
- package/dist/chunk-LMJW65ML.js +836 -0
- package/dist/chunk-MCSQNZ4E.js +836 -0
- package/dist/chunk-NSJ3GKUC.js +1552 -0
- package/dist/chunk-OGFKJOK7.js +2068 -0
- package/dist/chunk-RDEJZJBZ.js +1351 -0
- package/dist/chunk-TMTYN2UK.js +1128 -0
- package/dist/chunk-V45LUJDI.js +838 -0
- package/dist/chunk-YRUXFEZM.js +1044 -0
- package/dist/chunk-ZYBAKW25.js +994 -0
- package/dist/generated/agent-fold/index.d.ts +4520 -0
- package/dist/generated/agent-fold/index.js +0 -0
- package/dist/generated/agent-harness/client/client.gen.d.ts +2 -0
- package/dist/generated/agent-harness/client/index.d.ts +10 -0
- package/dist/generated/agent-harness/client/types.gen.d.ts +120 -0
- package/dist/generated/agent-harness/client/utils.gen.d.ts +37 -0
- package/dist/generated/agent-harness/client.gen.d.ts +12 -0
- package/dist/generated/agent-harness/core/auth.gen.d.ts +25 -0
- package/dist/generated/agent-harness/core/bodySerializer.gen.d.ts +25 -0
- package/dist/generated/agent-harness/core/params.gen.d.ts +43 -0
- package/dist/generated/agent-harness/core/pathSerializer.gen.d.ts +33 -0
- package/dist/generated/agent-harness/core/queryKeySerializer.gen.d.ts +18 -0
- package/dist/generated/agent-harness/core/serverSentEvents.gen.d.ts +71 -0
- package/dist/generated/agent-harness/core/types.gen.d.ts +83 -0
- package/dist/generated/agent-harness/core/utils.gen.d.ts +19 -0
- package/dist/generated/agent-harness/index.d.ts +2 -0
- package/dist/generated/agent-harness/index.js +6 -0
- package/dist/generated/agent-harness/sdk.gen.d.ts +375 -0
- package/dist/generated/agent-harness/types.gen.d.ts +4725 -0
- package/dist/generated/agent-reviews/index.d.ts +895 -0
- package/dist/generated/agent-reviews/index.js +0 -0
- package/dist/generated/auth/client/client.gen.d.ts +2 -0
- package/dist/generated/auth/client/index.d.ts +10 -0
- package/dist/generated/auth/client/types.gen.d.ts +120 -0
- package/dist/generated/auth/client/utils.gen.d.ts +37 -0
- package/dist/generated/auth/client.gen.d.ts +12 -0
- package/dist/generated/auth/core/auth.gen.d.ts +25 -0
- package/dist/generated/auth/core/bodySerializer.gen.d.ts +25 -0
- package/dist/generated/auth/core/params.gen.d.ts +43 -0
- package/dist/generated/auth/core/pathSerializer.gen.d.ts +33 -0
- package/dist/generated/auth/core/queryKeySerializer.gen.d.ts +18 -0
- package/dist/generated/auth/core/serverSentEvents.gen.d.ts +71 -0
- package/dist/generated/auth/core/types.gen.d.ts +83 -0
- package/dist/generated/auth/core/utils.gen.d.ts +19 -0
- package/dist/generated/auth/index.d.ts +2 -0
- package/dist/generated/auth/index.js +6 -0
- package/dist/generated/auth/sdk.gen.d.ts +674 -0
- package/dist/generated/auth/types.gen.d.ts +5233 -0
- package/dist/generated/calendar/client/client.gen.d.ts +2 -0
- package/dist/generated/calendar/client/index.d.ts +10 -0
- package/dist/generated/calendar/client/types.gen.d.ts +120 -0
- package/dist/generated/calendar/client/utils.gen.d.ts +37 -0
- package/dist/generated/calendar/client.gen.d.ts +12 -0
- package/dist/generated/calendar/core/auth.gen.d.ts +25 -0
- package/dist/generated/calendar/core/bodySerializer.gen.d.ts +25 -0
- package/dist/generated/calendar/core/params.gen.d.ts +43 -0
- package/dist/generated/calendar/core/pathSerializer.gen.d.ts +33 -0
- package/dist/generated/calendar/core/queryKeySerializer.gen.d.ts +18 -0
- package/dist/generated/calendar/core/serverSentEvents.gen.d.ts +71 -0
- package/dist/generated/calendar/core/types.gen.d.ts +83 -0
- package/dist/generated/calendar/core/utils.gen.d.ts +19 -0
- package/dist/generated/calendar/index.d.ts +2 -0
- package/dist/generated/calendar/index.js +6 -0
- package/dist/generated/calendar/sdk.gen.d.ts +157 -0
- package/dist/generated/calendar/types.gen.d.ts +2333 -0
- package/dist/generated/cognition/client/client.gen.d.ts +2 -0
- package/dist/generated/cognition/client/index.d.ts +10 -0
- package/dist/generated/cognition/client/types.gen.d.ts +120 -0
- package/dist/generated/cognition/client/utils.gen.d.ts +37 -0
- package/dist/generated/cognition/client.gen.d.ts +12 -0
- package/dist/generated/cognition/core/auth.gen.d.ts +25 -0
- package/dist/generated/cognition/core/bodySerializer.gen.d.ts +25 -0
- package/dist/generated/cognition/core/params.gen.d.ts +43 -0
- package/dist/generated/cognition/core/pathSerializer.gen.d.ts +33 -0
- package/dist/generated/cognition/core/queryKeySerializer.gen.d.ts +18 -0
- package/dist/generated/cognition/core/serverSentEvents.gen.d.ts +71 -0
- package/dist/generated/cognition/core/types.gen.d.ts +83 -0
- package/dist/generated/cognition/core/utils.gen.d.ts +19 -0
- package/dist/generated/cognition/index.d.ts +2 -0
- package/dist/generated/cognition/index.js +6 -0
- package/dist/generated/cognition/sdk.gen.d.ts +348 -0
- package/dist/generated/cognition/types.gen.d.ts +4228 -0
- package/dist/generated/connection/client/client.gen.d.ts +2 -0
- package/dist/generated/connection/client/index.d.ts +10 -0
- package/dist/generated/connection/client/types.gen.d.ts +120 -0
- package/dist/generated/connection/client/utils.gen.d.ts +37 -0
- package/dist/generated/connection/client.gen.d.ts +12 -0
- package/dist/generated/connection/core/auth.gen.d.ts +25 -0
- package/dist/generated/connection/core/bodySerializer.gen.d.ts +25 -0
- package/dist/generated/connection/core/params.gen.d.ts +43 -0
- package/dist/generated/connection/core/pathSerializer.gen.d.ts +33 -0
- package/dist/generated/connection/core/queryKeySerializer.gen.d.ts +18 -0
- package/dist/generated/connection/core/serverSentEvents.gen.d.ts +71 -0
- package/dist/generated/connection/core/types.gen.d.ts +83 -0
- package/dist/generated/connection/core/utils.gen.d.ts +19 -0
- package/dist/generated/connection/index.d.ts +2 -0
- package/dist/generated/connection/index.js +854 -0
- package/dist/generated/connection/sdk.gen.d.ts +43 -0
- package/dist/generated/connection/types.gen.d.ts +252 -0
- package/dist/generated/contacts/client/client.gen.d.ts +2 -0
- package/dist/generated/contacts/client/index.d.ts +10 -0
- package/dist/generated/contacts/client/types.gen.d.ts +120 -0
- package/dist/generated/contacts/client/utils.gen.d.ts +37 -0
- package/dist/generated/contacts/client.gen.d.ts +12 -0
- package/dist/generated/contacts/core/auth.gen.d.ts +25 -0
- package/dist/generated/contacts/core/bodySerializer.gen.d.ts +25 -0
- package/dist/generated/contacts/core/params.gen.d.ts +43 -0
- package/dist/generated/contacts/core/pathSerializer.gen.d.ts +33 -0
- package/dist/generated/contacts/core/queryKeySerializer.gen.d.ts +18 -0
- package/dist/generated/contacts/core/serverSentEvents.gen.d.ts +71 -0
- package/dist/generated/contacts/core/types.gen.d.ts +83 -0
- package/dist/generated/contacts/core/utils.gen.d.ts +19 -0
- package/dist/generated/contacts/index.d.ts +2 -0
- package/dist/generated/contacts/index.js +6 -0
- package/dist/generated/contacts/sdk.gen.d.ts +47 -0
- package/dist/generated/contacts/types.gen.d.ts +108 -0
- package/dist/generated/email/client/client.gen.d.ts +2 -0
- package/dist/generated/email/client/index.d.ts +10 -0
- package/dist/generated/email/client/types.gen.d.ts +120 -0
- package/dist/generated/email/client/utils.gen.d.ts +37 -0
- package/dist/generated/email/client.gen.d.ts +12 -0
- package/dist/generated/email/core/auth.gen.d.ts +25 -0
- package/dist/generated/email/core/bodySerializer.gen.d.ts +25 -0
- package/dist/generated/email/core/params.gen.d.ts +43 -0
- package/dist/generated/email/core/pathSerializer.gen.d.ts +33 -0
- package/dist/generated/email/core/queryKeySerializer.gen.d.ts +18 -0
- package/dist/generated/email/core/serverSentEvents.gen.d.ts +71 -0
- package/dist/generated/email/core/types.gen.d.ts +83 -0
- package/dist/generated/email/core/utils.gen.d.ts +19 -0
- package/dist/generated/email/index.d.ts +2 -0
- package/dist/generated/email/index.js +6 -0
- package/dist/generated/email/sdk.gen.d.ts +301 -0
- package/dist/generated/email/types.gen.d.ts +3262 -0
- package/dist/generated/notification/client/client.gen.d.ts +2 -0
- package/dist/generated/notification/client/index.d.ts +10 -0
- package/dist/generated/notification/client/types.gen.d.ts +120 -0
- package/dist/generated/notification/client/utils.gen.d.ts +37 -0
- package/dist/generated/notification/client.gen.d.ts +12 -0
- package/dist/generated/notification/core/auth.gen.d.ts +25 -0
- package/dist/generated/notification/core/bodySerializer.gen.d.ts +25 -0
- package/dist/generated/notification/core/params.gen.d.ts +43 -0
- package/dist/generated/notification/core/pathSerializer.gen.d.ts +33 -0
- package/dist/generated/notification/core/queryKeySerializer.gen.d.ts +18 -0
- package/dist/generated/notification/core/serverSentEvents.gen.d.ts +71 -0
- package/dist/generated/notification/core/types.gen.d.ts +83 -0
- package/dist/generated/notification/core/utils.gen.d.ts +19 -0
- package/dist/generated/notification/index.d.ts +2 -0
- package/dist/generated/notification/index.js +6 -0
- package/dist/generated/notification/sdk.gen.d.ts +127 -0
- package/dist/generated/notification/types.gen.d.ts +2084 -0
- package/dist/generated/properties/client/client.gen.d.ts +2 -0
- package/dist/generated/properties/client/index.d.ts +10 -0
- package/dist/generated/properties/client/types.gen.d.ts +120 -0
- package/dist/generated/properties/client/utils.gen.d.ts +37 -0
- package/dist/generated/properties/client.gen.d.ts +12 -0
- package/dist/generated/properties/core/auth.gen.d.ts +25 -0
- package/dist/generated/properties/core/bodySerializer.gen.d.ts +25 -0
- package/dist/generated/properties/core/params.gen.d.ts +43 -0
- package/dist/generated/properties/core/pathSerializer.gen.d.ts +33 -0
- package/dist/generated/properties/core/queryKeySerializer.gen.d.ts +18 -0
- package/dist/generated/properties/core/serverSentEvents.gen.d.ts +71 -0
- package/dist/generated/properties/core/types.gen.d.ts +83 -0
- package/dist/generated/properties/core/utils.gen.d.ts +19 -0
- package/dist/generated/properties/index.d.ts +2 -0
- package/dist/generated/properties/index.js +6 -0
- package/dist/generated/properties/sdk.gen.d.ts +158 -0
- package/dist/generated/properties/types.gen.d.ts +1311 -0
- package/dist/generated/scheduled-action/client/client.gen.d.ts +2 -0
- package/dist/generated/scheduled-action/client/index.d.ts +10 -0
- package/dist/generated/scheduled-action/client/types.gen.d.ts +120 -0
- package/dist/generated/scheduled-action/client/utils.gen.d.ts +37 -0
- package/dist/generated/scheduled-action/client.gen.d.ts +12 -0
- package/dist/generated/scheduled-action/core/auth.gen.d.ts +25 -0
- package/dist/generated/scheduled-action/core/bodySerializer.gen.d.ts +25 -0
- package/dist/generated/scheduled-action/core/params.gen.d.ts +43 -0
- package/dist/generated/scheduled-action/core/pathSerializer.gen.d.ts +33 -0
- package/dist/generated/scheduled-action/core/queryKeySerializer.gen.d.ts +18 -0
- package/dist/generated/scheduled-action/core/serverSentEvents.gen.d.ts +71 -0
- package/dist/generated/scheduled-action/core/types.gen.d.ts +83 -0
- package/dist/generated/scheduled-action/core/utils.gen.d.ts +19 -0
- package/dist/generated/scheduled-action/index.d.ts +2 -0
- package/dist/generated/scheduled-action/index.js +6 -0
- package/dist/generated/scheduled-action/sdk.gen.d.ts +156 -0
- package/dist/generated/scheduled-action/types.gen.d.ts +3099 -0
- package/dist/generated/search/client/client.gen.d.ts +2 -0
- package/dist/generated/search/client/index.d.ts +10 -0
- package/dist/generated/search/client/types.gen.d.ts +120 -0
- package/dist/generated/search/client/utils.gen.d.ts +37 -0
- package/dist/generated/search/client.gen.d.ts +12 -0
- package/dist/generated/search/core/auth.gen.d.ts +25 -0
- package/dist/generated/search/core/bodySerializer.gen.d.ts +25 -0
- package/dist/generated/search/core/params.gen.d.ts +43 -0
- package/dist/generated/search/core/pathSerializer.gen.d.ts +33 -0
- package/dist/generated/search/core/queryKeySerializer.gen.d.ts +18 -0
- package/dist/generated/search/core/serverSentEvents.gen.d.ts +71 -0
- package/dist/generated/search/core/types.gen.d.ts +83 -0
- package/dist/generated/search/core/utils.gen.d.ts +19 -0
- package/dist/generated/search/index.d.ts +2 -0
- package/dist/generated/search/index.js +6 -0
- package/dist/generated/search/sdk.gen.d.ts +44 -0
- package/dist/generated/search/types.gen.d.ts +2532 -0
- package/dist/generated/static-files/client/client.gen.d.ts +2 -0
- package/dist/generated/static-files/client/index.d.ts +10 -0
- package/dist/generated/static-files/client/types.gen.d.ts +120 -0
- package/dist/generated/static-files/client/utils.gen.d.ts +37 -0
- package/dist/generated/static-files/client.gen.d.ts +12 -0
- package/dist/generated/static-files/core/auth.gen.d.ts +25 -0
- package/dist/generated/static-files/core/bodySerializer.gen.d.ts +25 -0
- package/dist/generated/static-files/core/params.gen.d.ts +43 -0
- package/dist/generated/static-files/core/pathSerializer.gen.d.ts +33 -0
- package/dist/generated/static-files/core/queryKeySerializer.gen.d.ts +18 -0
- package/dist/generated/static-files/core/serverSentEvents.gen.d.ts +71 -0
- package/dist/generated/static-files/core/types.gen.d.ts +83 -0
- package/dist/generated/static-files/core/utils.gen.d.ts +19 -0
- package/dist/generated/static-files/index.d.ts +2 -0
- package/dist/generated/static-files/index.js +842 -0
- package/dist/generated/static-files/sdk.gen.d.ts +43 -0
- package/dist/generated/static-files/types.gen.d.ts +220 -0
- package/dist/generated/storage/client/client.gen.d.ts +2 -0
- package/dist/generated/storage/client/index.d.ts +10 -0
- package/dist/generated/storage/client/types.gen.d.ts +120 -0
- package/dist/generated/storage/client/utils.gen.d.ts +37 -0
- package/dist/generated/storage/client.gen.d.ts +12 -0
- package/dist/generated/storage/core/auth.gen.d.ts +25 -0
- package/dist/generated/storage/core/bodySerializer.gen.d.ts +25 -0
- package/dist/generated/storage/core/params.gen.d.ts +43 -0
- package/dist/generated/storage/core/pathSerializer.gen.d.ts +33 -0
- package/dist/generated/storage/core/queryKeySerializer.gen.d.ts +18 -0
- package/dist/generated/storage/core/serverSentEvents.gen.d.ts +71 -0
- package/dist/generated/storage/core/types.gen.d.ts +83 -0
- package/dist/generated/storage/core/utils.gen.d.ts +19 -0
- package/dist/generated/storage/index.d.ts +2 -0
- package/dist/generated/storage/index.js +6 -0
- package/dist/generated/storage/sdk.gen.d.ts +2285 -0
- package/dist/generated/storage/types.gen.d.ts +34546 -0
- package/dist/generated/unfurl/client/client.gen.d.ts +2 -0
- package/dist/generated/unfurl/client/index.d.ts +10 -0
- package/dist/generated/unfurl/client/types.gen.d.ts +120 -0
- package/dist/generated/unfurl/client/utils.gen.d.ts +37 -0
- package/dist/generated/unfurl/client.gen.d.ts +12 -0
- package/dist/generated/unfurl/core/auth.gen.d.ts +25 -0
- package/dist/generated/unfurl/core/bodySerializer.gen.d.ts +25 -0
- package/dist/generated/unfurl/core/params.gen.d.ts +43 -0
- package/dist/generated/unfurl/core/pathSerializer.gen.d.ts +33 -0
- package/dist/generated/unfurl/core/queryKeySerializer.gen.d.ts +18 -0
- package/dist/generated/unfurl/core/serverSentEvents.gen.d.ts +71 -0
- package/dist/generated/unfurl/core/types.gen.d.ts +83 -0
- package/dist/generated/unfurl/core/utils.gen.d.ts +19 -0
- package/dist/generated/unfurl/index.d.ts +2 -0
- package/dist/generated/unfurl/index.js +6 -0
- package/dist/generated/unfurl/sdk.gen.d.ts +47 -0
- package/dist/generated/unfurl/types.gen.d.ts +145 -0
- package/dist/src/calls/browser.d.ts +14 -0
- package/dist/src/calls/browser.js +102 -0
- package/dist/src/calls/common.d.ts +18 -0
- package/dist/src/calls/node.d.ts +24 -0
- package/dist/src/calls/node.js +145 -0
- package/dist/src/calls/telemetry.d.ts +5 -0
- package/dist/src/config.d.ts +71 -0
- package/dist/src/entities/account-managers/grant.d.ts +62 -0
- package/dist/src/entities/account-managers/namespace.d.ts +29 -0
- package/dist/src/entities/activity/entity.d.ts +7 -0
- package/dist/src/entities/activity/namespace.d.ts +58 -0
- package/dist/src/entities/activity/namespace.test.d.ts +1 -0
- package/dist/src/entities/agent-sessions/activity.d.ts +48 -0
- package/dist/src/entities/agent-sessions/agent-session.d.ts +518 -0
- package/dist/src/entities/agent-sessions/code-execution.d.ts +60 -0
- package/dist/src/entities/agent-sessions/conversation.d.ts +91 -0
- package/dist/src/entities/agent-sessions/namespace.d.ts +142 -0
- package/dist/src/entities/agent-sessions/origin.d.ts +94 -0
- package/dist/src/entities/agent-sessions/queued-action.d.ts +60 -0
- package/dist/src/entities/agent-sessions/review.d.ts +114 -0
- package/dist/src/entities/agent-sessions/tool-approval.d.ts +25 -0
- package/dist/src/entities/agent-sessions/view.d.ts +11 -0
- package/dist/src/entities/agents/agent.d.ts +142 -0
- package/dist/src/entities/agents/namespace.d.ts +66 -0
- package/dist/src/entities/ai/namespace.d.ts +36 -0
- package/dist/src/entities/api-keys/api-key.d.ts +22 -0
- package/dist/src/entities/api-keys/namespace.d.ts +37 -0
- package/dist/src/entities/bots/bot.d.ts +143 -0
- package/dist/src/entities/bots/namespace.d.ts +50 -0
- package/dist/src/entities/bots/token.d.ts +39 -0
- package/dist/src/entities/calendar/booking-link.d.ts +55 -0
- package/dist/src/entities/calendar/booking-namespace.d.ts +143 -0
- package/dist/src/entities/calendar/booking-namespace.test.d.ts +1 -0
- package/dist/src/entities/calendar/booking.d.ts +97 -0
- package/dist/src/entities/calendar/calendar.d.ts +49 -0
- package/dist/src/entities/calendar/create-confirmed.test.d.ts +1 -0
- package/dist/src/entities/calendar/event.d.ts +283 -0
- package/dist/src/entities/calendar/event.test.d.ts +1 -0
- package/dist/src/entities/calendar/namespace.d.ts +334 -0
- package/dist/src/entities/calendar/namespace.test.d.ts +1 -0
- package/dist/src/entities/calendar/replacement.d.ts +31 -0
- package/dist/src/entities/calls/call-record.d.ts +231 -0
- package/dist/src/entities/calls/connection.d.ts +59 -0
- package/dist/src/entities/calls/errors.d.ts +15 -0
- package/dist/src/entities/calls/message.d.ts +55 -0
- package/dist/src/entities/calls/namespace.d.ts +41 -0
- package/dist/src/entities/calls/participant.d.ts +22 -0
- package/dist/src/entities/canvases/canvas.d.ts +329 -0
- package/dist/src/entities/channels/access-request.d.ts +42 -0
- package/dist/src/entities/channels/activity.d.ts +40 -0
- package/dist/src/entities/channels/channel.d.ts +302 -0
- package/dist/src/entities/channels/labels.d.ts +73 -0
- package/dist/src/entities/channels/message.d.ts +153 -0
- package/dist/src/entities/channels/message.test.d.ts +1 -0
- package/dist/src/entities/channels/namespace.d.ts +82 -0
- package/dist/src/entities/channels/namespace.test.d.ts +1 -0
- package/dist/src/entities/channels/picture.d.ts +11 -0
- package/dist/src/entities/channels/post.d.ts +37 -0
- package/dist/src/entities/channels/post.test.d.ts +1 -0
- package/dist/src/entities/channels/share.d.ts +9 -0
- package/dist/src/entities/channels/share.test.d.ts +1 -0
- package/dist/src/entities/channels/thread.d.ts +64 -0
- package/dist/src/entities/chats/chat.d.ts +121 -0
- package/dist/src/entities/chats/generation.d.ts +55 -0
- package/dist/src/entities/chats/namespace.d.ts +35 -0
- package/dist/src/entities/connected-apps/connected-app.d.ts +121 -0
- package/dist/src/entities/connected-apps/connector.d.ts +59 -0
- package/dist/src/entities/connected-apps/namespace.d.ts +92 -0
- package/dist/src/entities/crm/company.d.ts +154 -0
- package/dist/src/entities/crm/contact.d.ts +168 -0
- package/dist/src/entities/crm/namespace.d.ts +163 -0
- package/dist/src/entities/crm/pipeline-entry.d.ts +109 -0
- package/dist/src/entities/crm/pipeline.d.ts +426 -0
- package/dist/src/entities/crm/pipelines.d.ts +79 -0
- package/dist/src/entities/crm-email-privacy/email-privacy.d.ts +238 -0
- package/dist/src/entities/crm-email-privacy/email-rule-preview.d.ts +55 -0
- package/dist/src/entities/crm-email-privacy/email-rule-revision.d.ts +27 -0
- package/dist/src/entities/crm-email-privacy/email-rules.d.ts +32 -0
- package/dist/src/entities/databases/column.d.ts +122 -0
- package/dist/src/entities/databases/database.d.ts +431 -0
- package/dist/src/entities/databases/namespace.d.ts +109 -0
- package/dist/src/entities/databases/query.d.ts +86 -0
- package/dist/src/entities/databases/row.d.ts +29 -0
- package/dist/src/entities/databases/saved-query.d.ts +151 -0
- package/dist/src/entities/databases/table.d.ts +124 -0
- package/dist/src/entities/databases/view.d.ts +72 -0
- package/dist/src/entities/databases/webhook.d.ts +39 -0
- package/dist/src/entities/documents/ai-edit.d.ts +54 -0
- package/dist/src/entities/documents/anchor.d.ts +39 -0
- package/dist/src/entities/documents/comment.d.ts +68 -0
- package/dist/src/entities/documents/create.test.d.ts +1 -0
- package/dist/src/entities/documents/document.d.ts +675 -0
- package/dist/src/entities/documents/markdown.d.ts +25 -0
- package/dist/src/entities/documents/namespace.d.ts +291 -0
- package/dist/src/entities/documents/office-files.d.ts +47 -0
- package/dist/src/entities/documents/skills.test.d.ts +1 -0
- package/dist/src/entities/documents/system-skill.d.ts +36 -0
- package/dist/src/entities/documents/text-comment.d.ts +41 -0
- package/dist/src/entities/documents/text-comment.test.d.ts +1 -0
- package/dist/src/entities/documents/version.d.ts +26 -0
- package/dist/src/entities/email/attachment.d.ts +39 -0
- package/dist/src/entities/email/draft.d.ts +160 -0
- package/dist/src/entities/email/filter.d.ts +44 -0
- package/dist/src/entities/email/label.d.ts +37 -0
- package/dist/src/entities/email/link.d.ts +35 -0
- package/dist/src/entities/email/message.d.ts +223 -0
- package/dist/src/entities/email/namespace.d.ts +235 -0
- package/dist/src/entities/email/namespace.test.d.ts +1 -0
- package/dist/src/entities/email/thread.d.ts +268 -0
- package/dist/src/entities/entity-mentions/mention.d.ts +21 -0
- package/dist/src/entities/entity-mentions/namespace.d.ts +20 -0
- package/dist/src/entities/entity.d.ts +167 -0
- package/dist/src/entities/external-chat/chat.d.ts +173 -0
- package/dist/src/entities/external-chat/message.d.ts +54 -0
- package/dist/src/entities/external-chat/namespace.d.ts +22 -0
- package/dist/src/entities/external-chat/participant.d.ts +28 -0
- package/dist/src/entities/external-chat/send.d.ts +40 -0
- package/dist/src/entities/external-chat/upload.d.ts +25 -0
- package/dist/src/entities/favorites/namespace.d.ts +52 -0
- package/dist/src/entities/foreign/foreign-entity.d.ts +36 -0
- package/dist/src/entities/foreign/namespace.d.ts +54 -0
- package/dist/src/entities/forms/form.d.ts +319 -0
- package/dist/src/entities/forms/namespace.d.ts +30 -0
- package/dist/src/entities/forms/question.d.ts +65 -0
- package/dist/src/entities/forms/response.d.ts +52 -0
- package/dist/src/entities/forms/section.d.ts +31 -0
- package/dist/src/entities/github-pull-requests/namespace.d.ts +20 -0
- package/dist/src/entities/github-pull-requests/pull-request.d.ts +64 -0
- package/dist/src/entities/harnesses/harness.d.ts +76 -0
- package/dist/src/entities/harnesses/namespace.d.ts +83 -0
- package/dist/src/entities/harnesses/pairing.d.ts +50 -0
- package/dist/src/entities/images/image.d.ts +88 -0
- package/dist/src/entities/images/namespace.d.ts +55 -0
- package/dist/src/entities/images/namespace.test.d.ts +1 -0
- package/dist/src/entities/imports/entry.d.ts +65 -0
- package/dist/src/entities/imports/namespace.d.ts +103 -0
- package/dist/src/entities/imports/namespace.test.d.ts +1 -0
- package/dist/src/entities/initiatives/initiative.d.ts +185 -0
- package/dist/src/entities/initiatives/initiative.test.d.ts +1 -0
- package/dist/src/entities/initiatives/namespace.d.ts +90 -0
- package/dist/src/entities/me/namespace.d.ts +68 -0
- package/dist/src/entities/meetings/meeting.d.ts +81 -0
- package/dist/src/entities/meetings/namespace.d.ts +38 -0
- package/dist/src/entities/memory/namespace.d.ts +49 -0
- package/dist/src/entities/memory/namespace.test.d.ts +1 -0
- package/dist/src/entities/messages/discussion.d.ts +84 -0
- package/dist/src/entities/messages/thread.d.ts +115 -0
- package/dist/src/entities/notifications/namespace.d.ts +66 -0
- package/dist/src/entities/notifications/notification.d.ts +78 -0
- package/dist/src/entities/notifications/notification.test.d.ts +1 -0
- package/dist/src/entities/passwords/item.d.ts +118 -0
- package/dist/src/entities/passwords/namespace.d.ts +45 -0
- package/dist/src/entities/pins/namespace.d.ts +42 -0
- package/dist/src/entities/projects/namespace.d.ts +45 -0
- package/dist/src/entities/projects/project.d.ts +108 -0
- package/dist/src/entities/properties/namespace.d.ts +105 -0
- package/dist/src/entities/properties/namespace.test.d.ts +1 -0
- package/dist/src/entities/properties/property-definition.d.ts +70 -0
- package/dist/src/entities/properties/property-option.d.ts +44 -0
- package/dist/src/entities/reference.d.ts +82 -0
- package/dist/src/entities/referrals/namespace.d.ts +40 -0
- package/dist/src/entities/routines/namespace.d.ts +239 -0
- package/dist/src/entities/routines/routine.d.ts +341 -0
- package/dist/src/entities/routines/suggestion.d.ts +38 -0
- package/dist/src/entities/saved-views/namespace.d.ts +58 -0
- package/dist/src/entities/saved-views/saved-view.d.ts +78 -0
- package/dist/src/entities/search/exclusions.d.ts +6 -0
- package/dist/src/entities/search/namespace.d.ts +71 -0
- package/dist/src/entities/search/options.d.ts +30 -0
- package/dist/src/entities/search/types.d.ts +90 -0
- package/dist/src/entities/sharing/access.d.ts +120 -0
- package/dist/src/entities/sharing/permissions.d.ts +13 -0
- package/dist/src/entities/spreadsheets/spreadsheet.d.ts +201 -0
- package/dist/src/entities/suggestions/namespace.d.ts +118 -0
- package/dist/src/entities/suggestions/suggestion.d.ts +172 -0
- package/dist/src/entities/suggestions/suggestion.test.d.ts +1 -0
- package/dist/src/entities/tasks/namespace.d.ts +77 -0
- package/dist/src/entities/tasks/task.d.ts +99 -0
- package/dist/src/entities/teams/invite.d.ts +33 -0
- package/dist/src/entities/teams/namespace.d.ts +23 -0
- package/dist/src/entities/teams/team.d.ts +129 -0
- package/dist/src/entities/ui/app-link.d.ts +24 -0
- package/dist/src/entities/ui/namespace.d.ts +75 -0
- package/dist/src/entities/unfurls/namespace.d.ts +24 -0
- package/dist/src/entities/users/namespace.d.ts +41 -0
- package/dist/src/entities/users/profile-picture.d.ts +29 -0
- package/dist/src/entities/users/profile-picture.test.d.ts +1 -0
- package/dist/src/entities/users/user.d.ts +102 -0
- package/dist/src/entities/web/namespace.d.ts +67 -0
- package/dist/src/entities/web/namespace.test.d.ts +1 -0
- package/dist/src/entities/webhooks/namespace.d.ts +38 -0
- package/dist/src/entities/webhooks/webhook.d.ts +130 -0
- package/dist/src/entities/whatsapp/account.d.ts +24 -0
- package/dist/src/entities/whatsapp/chat.d.ts +62 -0
- package/dist/src/entities/whatsapp/namespace.d.ts +29 -0
- package/dist/src/entities/workspace/items.d.ts +14 -0
- package/dist/src/entities/workspace/namespace.d.ts +96 -0
- package/dist/src/entities/workspace/query.d.ts +39 -0
- package/dist/src/entities/workspace/query.test.d.ts +1 -0
- package/dist/src/entities/workspace/types.d.ts +99 -0
- package/dist/src/events/hydrate/agentSession.d.ts +192 -0
- package/dist/src/events/hydrate/call.d.ts +101 -0
- package/dist/src/events/hydrate/channel.d.ts +55 -0
- package/dist/src/events/hydrate/document.d.ts +59 -0
- package/dist/src/events/hydrate/message.d.ts +70 -0
- package/dist/src/events/hydrate/user.d.ts +14 -0
- package/dist/src/events/receiver.d.ts +91 -0
- package/dist/src/events/types.d.ts +44 -0
- package/dist/src/events/verify.d.ts +13 -0
- package/dist/src/local-portmap.d.ts +8 -0
- package/dist/src/mentions.d.ts +42 -0
- package/dist/src/raw.d.ts +12 -0
- package/dist/src/rox.d.ts +267 -0
- package/dist/src/rox.js +23217 -0
- package/dist/src/utils/activity.d.ts +34 -0
- package/dist/src/utils/activity.test.d.ts +1 -0
- package/dist/src/utils/client.d.ts +62 -0
- package/dist/src/utils/concurrency.d.ts +5 -0
- package/dist/src/utils/index.d.ts +5 -0
- package/dist/src/utils/lazy.d.ts +37 -0
- package/dist/src/utils/options.d.ts +7 -0
- package/dist/src/utils/pagination.d.ts +28 -0
- package/dist/src/utils/unwrap.d.ts +48 -0
- package/dist/src/utils/verbs.d.ts +3 -0
- package/package.json +82 -4
package/README.md
CHANGED
|
@@ -1,3 +1,1260 @@
|
|
|
1
|
-
|
|
1
|
+
Rox's SDK: a Typescript library for harnessing the power of Rox
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**[Read the SDK documentation](https://sdk.rox.one)** — a quick start,
|
|
4
|
+
plain-English entity guide, and complete API reference, served by the SDK docs Worker.
|
|
5
|
+
|
|
6
|
+
- **`generated/`**: generated Typescript types and a HeyAPI client from Rox's
|
|
7
|
+
OpenAPI specs.
|
|
8
|
+
- **`src/`**: a hand-written ergonomic SDK layer that provides an "orm"-y API.
|
|
9
|
+
|
|
10
|
+
The [SDK reference build](../sdk-docs/README.md) uses TypeDoc to generate linked
|
|
11
|
+
Markdown and HTML from these sources at build time; the HTML is served with the
|
|
12
|
+
included static docs Worker.
|
|
13
|
+
|
|
14
|
+
## Usage
|
|
15
|
+
|
|
16
|
+
### Getting started
|
|
17
|
+
|
|
18
|
+
To get started, make a Rox client
|
|
19
|
+
|
|
20
|
+
```ts
|
|
21
|
+
import { Rox } from '@rox-one/sdk';
|
|
22
|
+
|
|
23
|
+
const macro = new Rox({ }); // uses ROX_API_KEY env var
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
### Authenticating
|
|
27
|
+
|
|
28
|
+
Every request the SDK sends carries exactly one Rox credential. There are three kinds.
|
|
29
|
+
|
|
30
|
+
| Credential | Minted in | Prefix | Acts as |
|
|
31
|
+
| --- | --- | --- | --- |
|
|
32
|
+
| API key | Settings → API Keys | `mak_` | the user who minted it |
|
|
33
|
+
| Bot token | Settings → Bots | `mbot_` | the bot, optionally on behalf of a user |
|
|
34
|
+
| Bearer token | a signed-in session | none (JWT) | the signed-in user |
|
|
35
|
+
|
|
36
|
+
#### API key
|
|
37
|
+
|
|
38
|
+
The default for scripts and integrations. Put the key in `ROX_API_KEY` and construct with no options.
|
|
39
|
+
|
|
40
|
+
```ts
|
|
41
|
+
import { Rox } from '@rox-one/sdk';
|
|
42
|
+
|
|
43
|
+
const macro = new Rox({});
|
|
44
|
+
const me = await macro.users.me();
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Or pass it in code. `token` accepts an API key or a bearer token. The SDK picks the header from the prefix.
|
|
48
|
+
|
|
49
|
+
```ts
|
|
50
|
+
const macro = new Rox({ token: process.env.ROX_API_KEY });
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
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.
|
|
54
|
+
|
|
55
|
+
```ts
|
|
56
|
+
const macro = new Rox({
|
|
57
|
+
auth: { type: 'user', apiKey: process.env.ROX_API_KEY },
|
|
58
|
+
});
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
An API key always acts as the user who minted it. `requestedAs` is bot-only.
|
|
62
|
+
|
|
63
|
+
#### Agent accounts
|
|
64
|
+
|
|
65
|
+
An agent has its own account and seat. Invite one with
|
|
66
|
+
`(await macro.teams.current()).invite('agent@example.com', { agent: true })` from your own
|
|
67
|
+
key (an agent's program is refused), or sign up at https://rox.one/app/signup/agent. After signing in, the agent sees its API key once in the
|
|
68
|
+
web app and uses it like any other key. It can set up its profile with
|
|
69
|
+
`macro.me.update({ name, profilePicture: await macro.me.uploadProfilePicture(bytes, options) })`
|
|
70
|
+
and mint more keys with `macro.apiKeys.create(name)`.
|
|
71
|
+
|
|
72
|
+
Switch between earlier uploads with `macro.me.update({ profilePicture: macro.images.byId(savedId) })`,
|
|
73
|
+
and read pictures with `macro.me.profilePicture()`, `user.profilePicture()` or
|
|
74
|
+
`macro.users.profilePictures(users)`. Pictures set through Macro are a
|
|
75
|
+
`StaticImage`; legacy URL pictures are an `ExternalProfilePicture` (`{ url }`).
|
|
76
|
+
Setting a picture is throttled to once a second per user and uploads to 20 an
|
|
77
|
+
hour; both fail with 429 beyond that.
|
|
78
|
+
|
|
79
|
+
#### Account managers
|
|
80
|
+
|
|
81
|
+
An agent account can manage a person's account: either side asks in their DM, and
|
|
82
|
+
the other side approves. An agent account can't be managed.
|
|
83
|
+
|
|
84
|
+
```ts
|
|
85
|
+
// As the agent, ask to manage a person's account:
|
|
86
|
+
const grant = await macro.accountManagers.askToManage(person);
|
|
87
|
+
// Once the person approves, the agent gets the token, once:
|
|
88
|
+
const token = await grant.claimToken();
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
An agent's program (ExecuteCode, a routine) can't ask, approve or claim: those return 403,
|
|
92
|
+
so an agent account uses its own API key. A person can ask instead, with
|
|
93
|
+
`macro.accountManagers.askToBeManagedBy(agent)`. Only the
|
|
94
|
+
manager can claim, so the agent approves and claims with its own client, using the grant id
|
|
95
|
+
from the card in the DM: `macro.accountManagers.byId(id)`.
|
|
96
|
+
|
|
97
|
+
The token is an API key for the managed account, with full access except its
|
|
98
|
+
managers, API keys and other credentials, sign-in, and deleting the account. It
|
|
99
|
+
lasts until either side calls `grant.revoke()`, or the managed account revokes it
|
|
100
|
+
in Settings → Account Managers.
|
|
101
|
+
|
|
102
|
+
#### Bot token
|
|
103
|
+
|
|
104
|
+
```ts
|
|
105
|
+
const asBot = new Rox({ auth: { type: 'bot', token: process.env.ROX_BOT_TOKEN } });
|
|
106
|
+
const asWolf = asBot.requestedAs('macro|wolf@rox.one');
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
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.
|
|
110
|
+
|
|
111
|
+
#### Bearer token
|
|
112
|
+
|
|
113
|
+
A session token, for code running with a signed-in user. Sent as `Authorization: Bearer`. The function form refreshes it.
|
|
114
|
+
|
|
115
|
+
```ts
|
|
116
|
+
const macro = new Rox({ auth: { type: 'user', token: () => session.accessToken() } });
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
#### Which header goes out
|
|
120
|
+
|
|
121
|
+
The backend rejects a request carrying two credentials with `400 ambiguous credentials`. The SDK sets exactly one.
|
|
122
|
+
|
|
123
|
+
| You passed | Header sent |
|
|
124
|
+
| --- | --- |
|
|
125
|
+
| `apiKey: '…'` | `x-macro-user-api-key: …` |
|
|
126
|
+
| `token: 'mak_…'` or `ROX_API_KEY=mak_…` | `x-macro-user-api-key: mak_…` |
|
|
127
|
+
| `token: '<jwt>'` or `ROX_API_KEY=<jwt>` | `Authorization: Bearer <jwt>` |
|
|
128
|
+
| `token: 'mbot_…'` | throws. Use `auth: { type: 'bot', token }` or `ROX_BOT_TOKEN`. |
|
|
129
|
+
| `type: 'bot'` | `x-macro-bot-token` plus `x-macro-bot-scope` |
|
|
130
|
+
|
|
131
|
+
### Accessing our API
|
|
132
|
+
|
|
133
|
+
Our SDK acts lets you easily access any Macro "resource":
|
|
134
|
+
|
|
135
|
+
```ts
|
|
136
|
+
const doc = macro.documents.byId('doc_123');
|
|
137
|
+
const name = await doc.name();
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
```ts
|
|
141
|
+
const owner = await doc.owner();
|
|
142
|
+
const email = await owner.email();
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
### Forms
|
|
146
|
+
|
|
147
|
+
Forms collect answers into a table. Respondents can read questions and submit
|
|
148
|
+
without permission to read the response database.
|
|
149
|
+
|
|
150
|
+
```ts
|
|
151
|
+
const form = await macro.forms.create({ name: 'Workshop registration' });
|
|
152
|
+
const table = await form.table();
|
|
153
|
+
const name = await table.addColumn({ name: 'Name', type: { type: 'text' } });
|
|
154
|
+
await form.replaceLayout([
|
|
155
|
+
{
|
|
156
|
+
kind: 'questions',
|
|
157
|
+
title: 'About you',
|
|
158
|
+
questions: [{ column: name, required: true }],
|
|
159
|
+
},
|
|
160
|
+
]);
|
|
161
|
+
const [question] = await form.questions();
|
|
162
|
+
if (!question) throw new Error('The form has no questions');
|
|
163
|
+
const receipt = await form.submit([
|
|
164
|
+
{ question, value: { type: 'text', value: 'Ada' } },
|
|
165
|
+
]);
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
Pass `table` to `macro.forms.create` to ask about an existing table's columns.
|
|
169
|
+
`editResponse` replaces the caller's answers while the form is open;
|
|
170
|
+
`myResponse` reads only that caller's receipt. Editors use `responseSummary`,
|
|
171
|
+
and `tally` is available to viewers when the owner enables `tallyVisible`.
|
|
172
|
+
Use `sharePermissions` and `updateSharePermissions` for sharing grants, and
|
|
173
|
+
`update({ audience: 'public' })` to allow anonymous responses.
|
|
174
|
+
|
|
175
|
+
### Creating, mutating, and deleting
|
|
176
|
+
|
|
177
|
+
```ts
|
|
178
|
+
const doc = await macro.documents.create({
|
|
179
|
+
name: 'Weekly update',
|
|
180
|
+
markdown: '# Week 32\n\n- shipped the thing',
|
|
181
|
+
});
|
|
182
|
+
|
|
183
|
+
await doc.rename('Weekly update (final)');
|
|
184
|
+
await doc.setTeamShare(true);
|
|
185
|
+
await doc.delete(); // soft delete; doc.restore() brings it back
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
### Entity appearance
|
|
189
|
+
|
|
190
|
+
Markdown documents, snippets, initiatives (task projects), forms, databases,
|
|
191
|
+
and routines expose `appearance()` and `setAppearance()`. Appearance is shared
|
|
192
|
+
with other viewers and requires edit access to change.
|
|
193
|
+
|
|
194
|
+
```ts
|
|
195
|
+
await doc.setAppearance({
|
|
196
|
+
icon: { kind: 'emoji', value: '🌱' },
|
|
197
|
+
color: 'green',
|
|
198
|
+
});
|
|
199
|
+
const appearance = await doc.appearance();
|
|
200
|
+
await doc.setAppearance({}); // restore the default icon and color
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
Writes replace both overrides without changing content timestamps. Omit an
|
|
204
|
+
override to restore its default. Colors use the same twelve-color palette as
|
|
205
|
+
tags and only tint Rox icons; native emoji keep their own colors.
|
|
206
|
+
|
|
207
|
+
### Sharing permissions
|
|
208
|
+
Documents, projects, calls and chats change their link and channel sharing with
|
|
209
|
+
`updateSharePermissions`; omitted fields are left as they are. Any item a
|
|
210
|
+
channel message can carry (a document or task, project, database, form, call,
|
|
211
|
+
email thread, agent session, external chat or calendar event) is shared with a
|
|
212
|
+
channel's current members, as posting it there does, through `shareWithChannel`:
|
|
213
|
+
|
|
214
|
+
```ts
|
|
215
|
+
await project.updateSharePermissions({
|
|
216
|
+
linkShareAccessLevel: 'view',
|
|
217
|
+
channelSharePermissions: [{ channel, accessLevel: 'comment', operation: 'add' }],
|
|
218
|
+
});
|
|
219
|
+
await doc.shareWithChannel(channel);
|
|
220
|
+
await event.shareWithChannel(channel);
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
### Listing and searching
|
|
224
|
+
|
|
225
|
+
List/search methods that can page return a genreator that auto-paginates:
|
|
226
|
+
iterate with `for await`, and `break` early to stop fetching:
|
|
227
|
+
|
|
228
|
+
```ts
|
|
229
|
+
for await (const doc of macro.documents.recent()) {
|
|
230
|
+
console.log(await doc.name());
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
for await (const hit of macro.documents.search('quarterly revenue')) {
|
|
234
|
+
console.log(hit.webUrl());
|
|
235
|
+
}
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
You can request all with `Array.fromAsync(...)`:
|
|
239
|
+
|
|
240
|
+
```ts
|
|
241
|
+
const allDocs = await Array.fromAsync(macro.documents.recent());
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
### Properties and favorites
|
|
245
|
+
|
|
246
|
+
Most entities carry user-defined properties and can be favorited:
|
|
247
|
+
|
|
248
|
+
```ts
|
|
249
|
+
await doc.favorite();
|
|
250
|
+
await doc.setProperty(macro.properties.byId('prop_status'), {
|
|
251
|
+
text: 'In review',
|
|
252
|
+
});
|
|
253
|
+
const props = await doc.properties();
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
### Databases
|
|
257
|
+
|
|
258
|
+
Databases are collections of tables. Tables, columns, and views are parts of
|
|
259
|
+
a database, not entities of their own, so they come back as handles that
|
|
260
|
+
resolve through the database's schema.
|
|
261
|
+
|
|
262
|
+
SQL is available through `database.query(sql)` or
|
|
263
|
+
`macro.databases.query(sql, { database })`. The scoped database resolves
|
|
264
|
+
unqualified names; joins can reach any other database the caller can view.
|
|
265
|
+
Results contain discriminated cell values, typed source rows and table-version
|
|
266
|
+
handles. SQL can also write; a statement executes once without automatic retries.
|
|
267
|
+
|
|
268
|
+
```ts
|
|
269
|
+
const database = macro.databases.byId('database-id');
|
|
270
|
+
const result = await database.query('SELECT "Name" FROM "Guests"');
|
|
271
|
+
console.log(result.result?.rows);
|
|
272
|
+
await database.query(`UPDATE "Guests" SET "Status" = 'Going' WHERE "Name" = 'Sam'`, {
|
|
273
|
+
baseVersions: result.readVersions,
|
|
274
|
+
});
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
`baseVersions` guards written tables atomically. Check `truncatedTables`:
|
|
278
|
+
nonempty means a read hit the row cap and aggregates may be partial. SQL schemas
|
|
279
|
+
are dynamic, so result cells use a generated tagged union rather than an inferred
|
|
280
|
+
TypeScript interface for each table. The HTTP route is `POST /databases/query`.
|
|
281
|
+
|
|
282
|
+
To show a live answer in a document, save the `SELECT` as a question. The
|
|
283
|
+
server refuses anything but one `SELECT` that compiles, and chart columns the
|
|
284
|
+
`SELECT` does not return (`POST /databases/queries`). `toBlock()` is the
|
|
285
|
+
`<m-db-query>` block to put in a document's Markdown; it re-runs for whoever
|
|
286
|
+
views it. `withView()` restyles the answer without saving a new question.
|
|
287
|
+
`macro.databases.saveQuery()` saves a question whose tables span databases.
|
|
288
|
+
|
|
289
|
+
```ts
|
|
290
|
+
const question = await database.saveQuery({
|
|
291
|
+
sql: 'SELECT "Party", COUNT(*) AS invites FROM "Guests" GROUP BY "Party"',
|
|
292
|
+
title: 'Invites per party',
|
|
293
|
+
display: { mode: 'bar', chart: { x: 'Party', y: ['invites'] } },
|
|
294
|
+
});
|
|
295
|
+
await macro.documents.create({ name: 'Invites', markdown: question.toBlock() });
|
|
296
|
+
const pie = question.withView({ displayMode: 'pie' }).toBlock();
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
The SDK's schema methods write typed ops through one endpoint,
|
|
300
|
+
`POST /databases/{id}/ops`. The methods below each send a one-op batch: the
|
|
301
|
+
SDK mints the new table, column, and option ids (UUIDv7) itself and builds the
|
|
302
|
+
handle it returns from the op's result.
|
|
303
|
+
|
|
304
|
+
```ts
|
|
305
|
+
const database = await macro.databases.create({ name: 'Events' });
|
|
306
|
+
const guests = await database.createTable({ name: 'Guests' });
|
|
307
|
+
const email = await guests.addColumn({ name: 'Email', type: { type: 'text' } });
|
|
308
|
+
|
|
309
|
+
// A select column only accepts labels you give it, at creation or later.
|
|
310
|
+
const rsvp = await guests.addColumn({
|
|
311
|
+
name: 'RSVP',
|
|
312
|
+
type: { type: 'select', multi: false },
|
|
313
|
+
options: ['Yes', 'No'],
|
|
314
|
+
after: email,
|
|
315
|
+
});
|
|
316
|
+
await rsvp.addOptions(['Maybe']); // labels it already has are skipped
|
|
317
|
+
|
|
318
|
+
await guests.rename('Attendees');
|
|
319
|
+
await rsvp.rename('Response');
|
|
320
|
+
|
|
321
|
+
// A relation column holds rows of another table, named by handle.
|
|
322
|
+
const hosts = await database.createTable({ name: 'Hosts' });
|
|
323
|
+
await guests.addColumn({
|
|
324
|
+
name: 'Host',
|
|
325
|
+
type: { type: 'relation', table: hosts },
|
|
326
|
+
});
|
|
327
|
+
|
|
328
|
+
// See what each type change would do to the existing values first.
|
|
329
|
+
const casts = await rsvp.casts();
|
|
330
|
+
await rsvp.changeType({ to: { type: 'select', multi: true } });
|
|
331
|
+
|
|
332
|
+
// A type change converts every value or refuses, naming the misfits. To keep
|
|
333
|
+
// the original, add a column of the new type after it, filled with the values
|
|
334
|
+
// that convert ("Response (Text)" unless you pass a name).
|
|
335
|
+
await rsvp.convertIntoNewColumn({ to: { type: 'text' } });
|
|
336
|
+
|
|
337
|
+
// Tabs: a new database starts with a "Table 1". Reorder by naming every
|
|
338
|
+
// table once, or delete one; a database keeps at least one.
|
|
339
|
+
const tables = await database.tables();
|
|
340
|
+
await database.reorderTables(tables.toReversed());
|
|
341
|
+
await (await database.table('Table 1'))?.delete();
|
|
342
|
+
```
|
|
343
|
+
|
|
344
|
+
Changing a column's type, reordering columns, and deleting a column send the
|
|
345
|
+
table version last read as the batch's base version: if the table changed
|
|
346
|
+
since, the server refuses with a 409 and nothing is written.
|
|
347
|
+
`convertIntoNewColumn` is the exception to one op per call: it reads the
|
|
348
|
+
conversion (`POST …/columns/{c}/conversion`, which changes nothing), then sends
|
|
349
|
+
one batch that creates the column and fills it, at the version that read saw.
|
|
350
|
+
|
|
351
|
+
To do several things at once, send the ops yourself. They apply in order in
|
|
352
|
+
one transaction, later ops see what earlier ones did, and a refused op leaves
|
|
353
|
+
the whole batch unwritten. Each op names the resource it changes (a `table`,
|
|
354
|
+
`column`, `rows`, or `view`) and what `change` it makes; each result answers
|
|
355
|
+
with the same `kind` and what happened as its own `change`. Ids for new
|
|
356
|
+
tables, columns, options, and views are yours to mint, so a later op of the
|
|
357
|
+
batch can name them:
|
|
358
|
+
|
|
359
|
+
```ts
|
|
360
|
+
import { v7 as uuidv7 } from 'uuid';
|
|
361
|
+
|
|
362
|
+
const notes = uuidv7();
|
|
363
|
+
const results = await database.applyOps(
|
|
364
|
+
[
|
|
365
|
+
{
|
|
366
|
+
kind: 'column',
|
|
367
|
+
table: guests.id,
|
|
368
|
+
column: notes,
|
|
369
|
+
change: {
|
|
370
|
+
kind: 'create',
|
|
371
|
+
definition: { source: 'new', name: 'Notes', type: { type: 'text' } },
|
|
372
|
+
},
|
|
373
|
+
},
|
|
374
|
+
{
|
|
375
|
+
kind: 'rows',
|
|
376
|
+
table: guests.id,
|
|
377
|
+
change: {
|
|
378
|
+
kind: 'insert',
|
|
379
|
+
rows: [
|
|
380
|
+
[
|
|
381
|
+
{ column: email.id, value: { type: 'text', value: 'ada@example.com' } },
|
|
382
|
+
{ column: notes, value: { type: 'text', value: 'Vegetarian' } },
|
|
383
|
+
],
|
|
384
|
+
],
|
|
385
|
+
},
|
|
386
|
+
},
|
|
387
|
+
],
|
|
388
|
+
{ baseVersions: [{ table: guests, version: await guests.version() }] },
|
|
389
|
+
);
|
|
390
|
+
// results[1] is { kind: 'rows', table, tableVersion, change: { kind: 'inserted', rows: [rowId] } }
|
|
391
|
+
```
|
|
392
|
+
|
|
393
|
+
A refusal throws `RoxOpRefusedError`, naming the op at fault (`op`, and
|
|
394
|
+
`row` / `column` when one is) and, when the batch minted an id that already
|
|
395
|
+
names something, that id as `taken` (`{ kind: 'table' | 'column' | 'option' |
|
|
396
|
+
'view', id }`). A retried batch whose first attempt committed refuses this way.
|
|
397
|
+
|
|
398
|
+
```ts
|
|
399
|
+
import { RoxOpRefusedError } from '@rox-one/sdk';
|
|
400
|
+
|
|
401
|
+
try {
|
|
402
|
+
await database.createTable({ name: 'Guests' });
|
|
403
|
+
} catch (error) {
|
|
404
|
+
if (error instanceof RoxOpRefusedError) console.log(error.op, error.taken);
|
|
405
|
+
}
|
|
406
|
+
```
|
|
407
|
+
|
|
408
|
+
A table's views are handles too. A board view reads where its cards sit:
|
|
409
|
+
|
|
410
|
+
```ts
|
|
411
|
+
for (const view of await guests.views()) {
|
|
412
|
+
const layout = await view.layout();
|
|
413
|
+
if (layout.kind === 'board') console.log(await view.positions());
|
|
414
|
+
}
|
|
415
|
+
```
|
|
416
|
+
|
|
417
|
+
### Rich message helper
|
|
418
|
+
|
|
419
|
+
Use the `msg` tagged template to build rich message bodies for channel messages
|
|
420
|
+
or documents.
|
|
421
|
+
|
|
422
|
+
```ts
|
|
423
|
+
import { msg, here } from '@rox-one/sdk';
|
|
424
|
+
|
|
425
|
+
const channel = macro.channels.byId('chan_1');
|
|
426
|
+
const user = macro.users.byId('user_1');
|
|
427
|
+
await channel.send(msg`Hey ${user}, take a look at ${doc}. cc ${here}`);
|
|
428
|
+
```
|
|
429
|
+
|
|
430
|
+
These will render as @mentions in the Rox UI.
|
|
431
|
+
|
|
432
|
+
### Generating images
|
|
433
|
+
|
|
434
|
+
`macro.images.generate()` makes an image with Google's Nano Banana model, charged
|
|
435
|
+
to the acting user's AI allowance, and stores it as a static file. Attach it to a
|
|
436
|
+
message with `images`; its width and height let the message reserve space before
|
|
437
|
+
the image loads. `image.toMarkdown()` is the `<m-image>` tag that shows it inline
|
|
438
|
+
in Markdown, such as an agent's reply; a static image is not a document, so never
|
|
439
|
+
mention its id as one. Pass up to three image documents or earlier images as
|
|
440
|
+
`referenceImages` to edit or combine them. `examples/generate-image.ts` runs this
|
|
441
|
+
end to end.
|
|
442
|
+
|
|
443
|
+
```ts
|
|
444
|
+
const image = await macro.images.generate({
|
|
445
|
+
prompt: 'A watercolor lighthouse at dusk',
|
|
446
|
+
aspectRatio: 'widescreen',
|
|
447
|
+
});
|
|
448
|
+
await channel.send('Fresh off the press', { images: [image] });
|
|
449
|
+
|
|
450
|
+
const night = await macro.images.generate({
|
|
451
|
+
prompt: 'The lighthouse in image 1, at night under stars',
|
|
452
|
+
referenceImages: [image],
|
|
453
|
+
});
|
|
454
|
+
```
|
|
455
|
+
|
|
456
|
+
### Posting to a channel webhook
|
|
457
|
+
|
|
458
|
+
The web UI can hand you a webhook URL and token for a channel. That token is a
|
|
459
|
+
bot token, so it goes in the normal place:
|
|
460
|
+
|
|
461
|
+
```ts
|
|
462
|
+
const macro = new Rox({
|
|
463
|
+
auth: { type: 'bot', token: process.env.MACRO_WEBHOOK_TOKEN },
|
|
464
|
+
});
|
|
465
|
+
|
|
466
|
+
await macro.channels
|
|
467
|
+
.byId(channelId)
|
|
468
|
+
.send(msg`Deploy ${sha} finished. ${here}`);
|
|
469
|
+
```
|
|
470
|
+
|
|
471
|
+
Pass `{ silent: true }` to `send` or `reply` for a routine update that should
|
|
472
|
+
notify nobody, mentioned people included; the message still appears in the
|
|
473
|
+
channel. It works with every credential.
|
|
474
|
+
|
|
475
|
+
### Routines
|
|
476
|
+
|
|
477
|
+
Create scheduled or event-triggered routines through `macro.routines`. A
|
|
478
|
+
routine runs `steps` in order: an `agent` ("Ask AI") step hands the run to a
|
|
479
|
+
model or agent, and `code` steps run TypeScript against this SDK as the owner,
|
|
480
|
+
type-checked when saved. Routine configuration takes typed agent and event
|
|
481
|
+
resource handles:
|
|
482
|
+
|
|
483
|
+
```ts
|
|
484
|
+
const routine = await macro.routines.create({
|
|
485
|
+
name: 'Daily summary',
|
|
486
|
+
trigger: { type: 'cron', schedule: '0 0 9 * * *', timezone: 'America/New_York' },
|
|
487
|
+
steps: [
|
|
488
|
+
{
|
|
489
|
+
type: 'agent',
|
|
490
|
+
instructions: 'Summarize my open tasks.',
|
|
491
|
+
model: 'anthropic/claude-sonnet-5-5',
|
|
492
|
+
},
|
|
493
|
+
],
|
|
494
|
+
});
|
|
495
|
+
await routine.setEnabled(false);
|
|
496
|
+
const transcript = await routine.execute(); // Chat or AgentSession, if available
|
|
497
|
+
const executions = await routine.history(); // Each retains its parent routine
|
|
498
|
+
```
|
|
499
|
+
|
|
500
|
+
A cron `schedule` has 6 fields (second minute hour day-of-month month
|
|
501
|
+
day-of-week) or 7 with a year. The older single agent task (`prompt` and
|
|
502
|
+
`userPrompt`, with `model`, `agent` or both, instead of `steps`) still saves
|
|
503
|
+
and runs as one Ask AI step. Code steps' writes are attributed to Rox's
|
|
504
|
+
agent acting for the owner; set `dangerouslyOperateAsUser: true` only when the
|
|
505
|
+
user explicitly asks for the routine to act, send or post as them:
|
|
506
|
+
|
|
507
|
+
```ts
|
|
508
|
+
await macro.routines.create({
|
|
509
|
+
name: 'Say hello',
|
|
510
|
+
trigger: { type: 'once', at: '2027-11-03T14:30:00Z' },
|
|
511
|
+
steps: [
|
|
512
|
+
{
|
|
513
|
+
type: 'code',
|
|
514
|
+
title: 'Post hello',
|
|
515
|
+
source: `export async function main({ macro }: StepContext) {
|
|
516
|
+
await macro.channels.byId(channelId).send('Hello');
|
|
517
|
+
}`,
|
|
518
|
+
},
|
|
519
|
+
],
|
|
520
|
+
dangerouslyOperateAsUser: true,
|
|
521
|
+
});
|
|
522
|
+
```
|
|
523
|
+
|
|
524
|
+
Event triggers use `{ type: 'events', filters: [{ events, entities, condition }] }`;
|
|
525
|
+
`entities` takes typed references such as `{ type: 'document', entity: doc }`.
|
|
526
|
+
Use `{ type: 'multiple', triggers: [...] }` to combine schedules and events.
|
|
527
|
+
`routine.update(options)` replaces task and trigger settings; `delete()` removes it.
|
|
528
|
+
Routines run as their owner, so share one as a template instead:
|
|
529
|
+
`routine.shareAsTemplate({ description, variables })` publishes a snapshot,
|
|
530
|
+
`routine.template()` reads it (undefined when not shared), and
|
|
531
|
+
`routine.activateTemplate(options)` creates the caller's own routine from it.
|
|
532
|
+
`routine.sourceTemplate()` returns the routine a template came from.
|
|
533
|
+
Publishing, reading, and activating templates require the caller's
|
|
534
|
+
`enable-routine-sharing` PostHog flag. Disabled or unavailable evaluations return
|
|
535
|
+
404 (`template()` returns `undefined`). `stopSharingTemplate()` stays available
|
|
536
|
+
to owners, and previously activated routines continue working.
|
|
537
|
+
|
|
538
|
+
A GitHub trigger takes a filter of its own, with optional exact payload tests in
|
|
539
|
+
`match`. It needs the owner to have connected GitHub:
|
|
540
|
+
|
|
541
|
+
```ts
|
|
542
|
+
await routine.update({
|
|
543
|
+
...options,
|
|
544
|
+
trigger: {
|
|
545
|
+
type: 'events',
|
|
546
|
+
filters: [
|
|
547
|
+
{
|
|
548
|
+
events: ['github'],
|
|
549
|
+
github: { events: ['workflow_run'], actions: ['completed'], repositories: ['macro-inc/macro'] },
|
|
550
|
+
match: [
|
|
551
|
+
{ path: ['workflow_run', 'name'], equals: 'CI' },
|
|
552
|
+
{ path: ['workflow_run', 'conclusion'], in: ['failure', 'timed_out'] },
|
|
553
|
+
],
|
|
554
|
+
},
|
|
555
|
+
],
|
|
556
|
+
},
|
|
557
|
+
});
|
|
558
|
+
```
|
|
559
|
+
|
|
560
|
+
### Agents, conversations and hosts
|
|
561
|
+
|
|
562
|
+
`macro.agents.list/create/byId` manage agent configuration; listed agents read
|
|
563
|
+
their runtime, coding/chat choice, apps, channel scope and permission settings.
|
|
564
|
+
`agent.update(patch)` changes only the settings it names (`PATCH /agents/{id}`);
|
|
565
|
+
`agent.replace(options)` replaces everything, including the owning team, and
|
|
566
|
+
`AgentOptions` takes channel, team and host handles. `macro.agents.coding()` lists the coding personas the caller can
|
|
567
|
+
start right now, built-in ones such as Cursor included; pass an entry's `agent`
|
|
568
|
+
to `macro.agentSessions.createManaged`.
|
|
569
|
+
`channel.agentConversations()` returns conversations with session and turn handles;
|
|
570
|
+
`conversation.startFresh(session)` and `turn.retry(actionId)` expose explicit
|
|
571
|
+
conversation controls. `session.toolApprovalById(id).answer(answer)` answers a
|
|
572
|
+
permission request scoped to that session.
|
|
573
|
+
|
|
574
|
+
`macro.harnesses.list/me/byId` manages agent hosts. `createPairing(options)` returns
|
|
575
|
+
separate pairing and device handles plus a device secret. Approve through
|
|
576
|
+
`pairing.approve(...)`, then `device.claim(deviceSecret)`; a pending claim returns
|
|
577
|
+
`undefined`. Host tokens and device secrets are never stored in entity handles.
|
|
578
|
+
Self-host operations (`me`, `agents`, `sessions`, `deleteSelf`) require the backend's
|
|
579
|
+
host authentication; ordinary user or bot credentials do not grant those rights.
|
|
580
|
+
|
|
581
|
+
### Drafts, filters and follow-ups
|
|
582
|
+
|
|
583
|
+
```ts
|
|
584
|
+
const inbox = (await macro.email.links())[0];
|
|
585
|
+
const draft = await macro.email.createDraft({
|
|
586
|
+
subject: 'Follow-up',
|
|
587
|
+
to: [{ email: 'ada@example.com' }],
|
|
588
|
+
bodyHtml: '<p>Thanks for meeting.</p>',
|
|
589
|
+
}, inbox);
|
|
590
|
+
await draft.update({ subject: 'Follow-up notes', bodyText: 'Thanks for meeting.' });
|
|
591
|
+
const upload = await draft.addAttachment({ fileName: 'notes.txt', sha, size });
|
|
592
|
+
// Upload bytes to upload.uploadUrl, then verify before sending:
|
|
593
|
+
await upload.attachment.complete();
|
|
594
|
+
await draft.schedule('2026-11-01T09:00:00Z');
|
|
595
|
+
await draft.unschedule();
|
|
596
|
+
```
|
|
597
|
+
|
|
598
|
+
HTML input is UTF-8 encoded for the wire contract. Draft writes retain the draft's
|
|
599
|
+
inbox selection, including delegated inboxes. `update` replaces content; omitted
|
|
600
|
+
recipients and body fields follow the server's replacement semantics.
|
|
601
|
+
`draft.forwardAttachment(attachment)` returns a draft-scoped attachment handle.
|
|
602
|
+
Use its `remove()` method to detach it. `email.scheduled({ inbox, pageSize })`
|
|
603
|
+
automatically pages; breaking iteration stops further requests.
|
|
604
|
+
|
|
605
|
+
`email.filters(inbox)` and `email.upsertFilter(options, inbox)` return filter handles
|
|
606
|
+
with `setImportant` and `delete`. Omit the inbox to select the caller's primary.
|
|
607
|
+
`email.contacts()` returns the service's address/interaction buckets.
|
|
608
|
+
`thread.calendarInvitations()` reads resolved invitations. `thread.followup()` and
|
|
609
|
+
`thread.setFollowup(command)` expose revision-aware reminder state; commands require
|
|
610
|
+
caller-persisted operation IDs. `email.reminders({ inboxes })` auto-paginates and
|
|
611
|
+
returns thread handles alongside reminder snapshots.
|
|
612
|
+
|
|
613
|
+
### Saved views
|
|
614
|
+
|
|
615
|
+
```ts
|
|
616
|
+
const view = await macro.savedViews.create({
|
|
617
|
+
name: 'Invoices',
|
|
618
|
+
config: {
|
|
619
|
+
kind: 'email',
|
|
620
|
+
version: 1,
|
|
621
|
+
filters: {
|
|
622
|
+
inboxIds: [], participants: [{ type: 'domain', domain: 'example.com' }],
|
|
623
|
+
participantFields: ['from'], subject: ['invoice'], starred: false,
|
|
624
|
+
attachments: [], calendarInvite: false, tags: [],
|
|
625
|
+
},
|
|
626
|
+
},
|
|
627
|
+
});
|
|
628
|
+
await view.edit({ name: 'Bills', team: macro.teams.byId(teamId) });
|
|
629
|
+
for await (const each of macro.savedViews.list({ kind: 'email' })) {
|
|
630
|
+
console.log(await each.name());
|
|
631
|
+
}
|
|
632
|
+
await macro.savedViews.reorder('email', [view]);
|
|
633
|
+
await view.remove();
|
|
634
|
+
```
|
|
635
|
+
|
|
636
|
+
A saved view is a named filter definition the app shows in a surface's sidebar
|
|
637
|
+
(`kind` picks the surface, such as Email). `edit` and `remove` are checked
|
|
638
|
+
against the revision the handle last saw: a write made elsewhere since then
|
|
639
|
+
fails with a 409 conflict instead of being overwritten, and `view.refresh()`
|
|
640
|
+
picks up the current revision. Order is personal; `reorder` sets yours for one
|
|
641
|
+
kind.
|
|
642
|
+
|
|
643
|
+
### CRM email contribution
|
|
644
|
+
|
|
645
|
+
`macro.crm.emailPrivacy` manages only the authenticated member's contribution,
|
|
646
|
+
including when their CRM viewing permission is off. `get()` is read-only and
|
|
647
|
+
returns the current mode, selectors, mailbox handle and observed-state token.
|
|
648
|
+
`settings()` reads domain exclusions; `excludedThreads()` lazily lists private
|
|
649
|
+
thread exceptions. Existing team-wide domain methods remain on `macro.crm`;
|
|
650
|
+
`emailPrivacy.blockDomain` and `unblockDomain` edit personal exclusions.
|
|
651
|
+
|
|
652
|
+
Rules use `{ schemaVersion: 1, include: [...] }`. Selectors are `thread` with an
|
|
653
|
+
`EmailThread`, `contact` with a `Contact`, `company` with a `Company`, or
|
|
654
|
+
`address` / `domain` with the corresponding string. A participant match includes
|
|
655
|
+
the whole thread, across eligible past and future mail. Contact/company rules
|
|
656
|
+
follow live records. Private-thread, domain and personal-email exclusions always
|
|
657
|
+
win. Narrowing or withdrawal leaves CRM records in place; a teammate's eligible
|
|
658
|
+
copy remains independent.
|
|
659
|
+
|
|
660
|
+
```ts
|
|
661
|
+
const privacy = macro.crm.emailPrivacy;
|
|
662
|
+
const state = await privacy.get();
|
|
663
|
+
if (!state.authoringAvailable || !state.token) {
|
|
664
|
+
throw new Error('Selective contribution is unavailable.');
|
|
665
|
+
}
|
|
666
|
+
const checked = await privacy.validateRules({
|
|
667
|
+
schemaVersion: 1,
|
|
668
|
+
include: [{ kind: 'domain', domain: 'example.com' }],
|
|
669
|
+
});
|
|
670
|
+
const idempotencyKey = crypto.randomUUID();
|
|
671
|
+
const result = await privacy.replaceRules(checked.rules, {
|
|
672
|
+
ifPolicy: state.token,
|
|
673
|
+
idempotencyKey,
|
|
674
|
+
});
|
|
675
|
+
```
|
|
676
|
+
|
|
677
|
+
`replaceRules` directly activates the replacement; member-authorized agents need
|
|
678
|
+
no separate human confirmation. `enableAll` and `withdraw` take the same options.
|
|
679
|
+
Keep the exact token, key and command for retries. A 409 requires fresh inspection
|
|
680
|
+
and a new decision; the SDK never refreshes or retries automatically. A result
|
|
681
|
+
with `replayed: true` describes the original commit, not current sharing. Server
|
|
682
|
+
rollout and credential restrictions remain authoritative.
|
|
683
|
+
|
|
684
|
+
Optional counts use `preview()` to inspect the current slot, then
|
|
685
|
+
`previewRules(rules, { ifPolicy: state.token, ifPreview: previousPreview })`.
|
|
686
|
+
A preview handle's `get()` refreshes only that preview and `cancel()` names that
|
|
687
|
+
exact identity. Superseded handles cannot read or cancel newer work. Only
|
|
688
|
+
`status: 'complete'` means exact counts; running/partial counts are lower bounds,
|
|
689
|
+
and stale/cancelled results are not current estimates. Counts are mailbox-local,
|
|
690
|
+
limited to 10,000 scanned raw threads and five minutes. Previewing does not grant
|
|
691
|
+
contribution or schedule mail backfill.
|
|
692
|
+
|
|
693
|
+
`history()` iterates owner-only audit events in pages of fifty. Revision handles
|
|
694
|
+
on current state, mutation outcomes and history read immutable definitions with
|
|
695
|
+
`get()`; they never fetch target content or reapply rules. Verified agent/session
|
|
696
|
+
provenance is read from history, never supplied by the caller.
|
|
697
|
+
|
|
698
|
+
Legacy members without a policy token retain `setConsent(false)` for withdrawal.
|
|
699
|
+
`setConsent(true, inbox)` uses the existing all-mail opt-in, bound to the chosen
|
|
700
|
+
primary inbox; members with a policy token use `enableAll` / `withdraw` instead.
|
|
701
|
+
`setThreadExcluded(thread, excluded)` reuses the existing thread-exclusion API and
|
|
702
|
+
its rollout gate. The SDK changes no flags and adds no settings UI.
|
|
703
|
+
|
|
704
|
+
### CRM member access
|
|
705
|
+
|
|
706
|
+
`macro.crm.access()` reads the caller's current team and effective CRM access,
|
|
707
|
+
even when access is denied. `team.members()` includes `crmAccess` for each member.
|
|
708
|
+
Admins and owners use `team.setMemberCrmAccess(user, enabled)` to deny or restore
|
|
709
|
+
an ordinary member; admins and owners cannot be denied. This never changes the
|
|
710
|
+
member's mailbox contribution consent. The mutation returns 503 until the
|
|
711
|
+
server rollout enables access changes; existing denials remain enforced while
|
|
712
|
+
changes are disabled. Record, search, email and tool requests
|
|
713
|
+
recheck access on the server. A separately shared pipeline still exposes its own
|
|
714
|
+
rows and cell values, while its CRM record references need separate access.
|
|
715
|
+
|
|
716
|
+
### CRM contact fields
|
|
717
|
+
|
|
718
|
+
A contact holds several addresses, one of them primary: `contact.emails()` lists
|
|
719
|
+
them, primary first. `addEmail(address)` adds one, `setEmail(address)` makes one
|
|
720
|
+
the primary (adding it when the contact does not hold it), and
|
|
721
|
+
`removeEmail(address)` removes one; removing the primary promotes the oldest
|
|
722
|
+
address left. Removing an address deletes nothing else: the contact stops
|
|
723
|
+
showing that address's mail. An identical retry of any of them is safe.
|
|
724
|
+
|
|
725
|
+
`setCompany(company)` links or switches a contact with a personal-provider
|
|
726
|
+
primary to a Company handle in the same team, and `unlinkCompany()` removes the
|
|
727
|
+
link. A contact with an address on one of its company's domains
|
|
728
|
+
(`contact.companyDomain()`) can do neither, and the last of those addresses
|
|
729
|
+
(`contact.companyDomainEmails()`) cannot be removed. All of them preserve
|
|
730
|
+
identity and reject same-team email conflicts without merging records.
|
|
731
|
+
|
|
732
|
+
### CRM pipelines and initiatives
|
|
733
|
+
|
|
734
|
+
`macro.crm.pipelines.create/list/byId` returns pipeline handles. Rename, sharing,
|
|
735
|
+
permissions and trash operations live on the pipeline. `pipeline.table()` returns
|
|
736
|
+
its table handle, with column and row handles. `rows()` and `queryRows({ rows, query })`
|
|
737
|
+
fetch through the pipeline's authorization boundary and auto-paginate.
|
|
738
|
+
`(await pipeline.table()).views()` returns scoped `PipelineView` handles;
|
|
739
|
+
`view.detail()` reads its definition and `view.positions()` reads its saved board
|
|
740
|
+
order through pipeline permissions.
|
|
741
|
+
`pipeline.applyOps(ops, { baseVersions: [{ table, version }] })` accepts the generated
|
|
742
|
+
atomic database operation contract, including batch-local UUIDs, like
|
|
743
|
+
`Database.applyOps`. Table and column reads share a schema cache invalidated by
|
|
744
|
+
successful batches. Call `row.refresh()` to reload a row after a batch changes it.
|
|
745
|
+
|
|
746
|
+
A pipeline that tracks companies or contacts has an **Outcome** field (`Open`,
|
|
747
|
+
`Won` or `Lost`, independent of Stage) and a currency field beside each
|
|
748
|
+
monetary field, such as `Revenue currency`; new entries default to `Open` and
|
|
749
|
+
`USD`, and neither field can be emptied. `listWithFields()` and `find()` name
|
|
750
|
+
each monetary field's `currencyField`, `find()` returns one total per
|
|
751
|
+
`currency` for it, never converted or combined, and an update's changes carry
|
|
752
|
+
`beforeCurrency` and `afterCurrency` for a monetary field.
|
|
753
|
+
|
|
754
|
+
`macro.initiatives.create/byId` groups tasks and members. Relations return user
|
|
755
|
+
and task handles; `initiative.update({ name, members, sharePermission })` and
|
|
756
|
+
`delete()` manage it. `initiatives.list({ query, status, priority, assignee,
|
|
757
|
+
dueAfter, dueBefore, sort })` iterates the matching initiatives with their Status,
|
|
758
|
+
Priority, assignees, due date and progress over the tasks the caller can view;
|
|
759
|
+
`initiatives.summaries()` reads every name in one request.
|
|
760
|
+
`initiative.description()` returns its description as Markdown, and
|
|
761
|
+
`comments()`, `comment(body)` and `commentById(id)` read and write its
|
|
762
|
+
discussion; `comment.reply(body)` answers a thread. Its comments are the same
|
|
763
|
+
`DiscussionComment` handles CRM companies and contacts use (formerly
|
|
764
|
+
`CrmComment`).
|
|
765
|
+
|
|
766
|
+
### Access requests and message threads
|
|
767
|
+
|
|
768
|
+
Documents, chats, projects, initiatives, databases, calls, email threads and agent
|
|
769
|
+
sessions expose `.access`. `access.state()` returns review rights, typed requests,
|
|
770
|
+
and an optional continuation offset. `submit(level)`, `cancel(revision)`,
|
|
771
|
+
`request.resolve(level)`, `direct()`, `grant(user, level)`, and `remove(user)` use
|
|
772
|
+
server authorization and optimistic request revisions. Omit the level on
|
|
773
|
+
`request.resolve()` to decline. Resolved request handles retain their result even
|
|
774
|
+
after they leave the pending listing.
|
|
775
|
+
|
|
776
|
+
New sharing updates use `SharePermissionOptions`: channel grants name a channel
|
|
777
|
+
handle, operation (`add`, `replace`, `remove`) and optional access level.
|
|
778
|
+
|
|
779
|
+
Channels, documents, CRM companies/contacts and calls expose
|
|
780
|
+
`messageThreadById(id)` for thread resolution, anchor detachment and deletion.
|
|
781
|
+
`timelinePage({ messages, around, cursor, limit })` returns a mixed timeline with
|
|
782
|
+
seeded message handles and typed activity actors. Selectors must belong to the same
|
|
783
|
+
parent. Cursors are opaque; pass the returned cursor on the next request.
|
|
784
|
+
`channel.recordActivity(type)` records a view or interaction; `channels.activity()`
|
|
785
|
+
reads activity handles. `ChannelPicture.byId(uploadId)` references an uploaded
|
|
786
|
+
picture for `channel.setPicture(picture)`; omit it to clear the picture.
|
|
787
|
+
|
|
788
|
+
### Meetings and calendar browsing
|
|
789
|
+
|
|
790
|
+
`macro.meetings.create/list/active/lookup` returns meeting handles. `list()` contains
|
|
791
|
+
the caller's newest 100 standalone meetings; use `lookup(invitationToken)` for
|
|
792
|
+
channel meetings and other invitations. A seeded meeting retains its lookup token
|
|
793
|
+
when mutations invalidate metadata. `update`, `cancel`, `invite(email)`,
|
|
794
|
+
`inviteUsers(users)`, `invitePermissions` and `webUrl` live on the meeting.
|
|
795
|
+
`call.meeting()` creates or reads its shareable meeting; calls also expose
|
|
796
|
+
`editTranscript(assignments)` and `toggleTeamShare()`.
|
|
797
|
+
|
|
798
|
+
### Programmatic calls
|
|
799
|
+
|
|
800
|
+
Use `macro.calls.active()` to find joinable live calls and reconcile missed
|
|
801
|
+
`call.*` events. `macro.calls.summaries(calls)` previews live or archived call
|
|
802
|
+
handles in one request. `channel.activeCall()` checks without starting a call; use
|
|
803
|
+
`channel.startCall()` only when intending to ring channel members. A live
|
|
804
|
+
`call.join()` never creates a replacement call. `meeting.join()` enters with
|
|
805
|
+
an account and `meeting.joinAsGuest(name)` uses the invitation link.
|
|
806
|
+
|
|
807
|
+
Each entry returns a `CallConnection` with the LiveKit URL, token, identity,
|
|
808
|
+
room name, call handle, and `started` flag. Pass the token directly to a
|
|
809
|
+
LiveKit client; it is omitted from JSON and console inspection. Call
|
|
810
|
+
`connection.leave()` when finished. Joins default to `onOtherCall: 'fail'`;
|
|
811
|
+
pass `{ onOtherCall: 'switch' }` to move intentionally, or `{ replace: true }`
|
|
812
|
+
to take over an existing connection for the same identity. Branch on
|
|
813
|
+
`InOtherCallError`, `AlreadyConnectedError`, and `CallEndedError`.
|
|
814
|
+
|
|
815
|
+
`call.ringState()` reads this account's ring state, `call.participants()` reads
|
|
816
|
+
the live roster with user handles, `call.decline()` declines its ring,
|
|
817
|
+
`call.discussion()` returns the call chat or its channel thread, and
|
|
818
|
+
`call.recording.bytes()` downloads through the Rox host. Historical
|
|
819
|
+
participants remain available as `call.historicParticipants()`.
|
|
820
|
+
|
|
821
|
+
|
|
822
|
+
`calendar.occurrences(viewport)` auto-paginates and seeds event handles.
|
|
823
|
+
`calendar.teamPage(viewport)` includes the roster and an optional next cursor;
|
|
824
|
+
`teamOutOfOffice(viewport)` reports `hasMore` when its bounded results are truncated.
|
|
825
|
+
`availabilityCalendars`, `calendar.setContributesToAvailability`, `teamSharing` and
|
|
826
|
+
`setTeamSharing` manage availability and sharing preferences.
|
|
827
|
+
|
|
828
|
+
### Editing documents and tasks
|
|
829
|
+
|
|
830
|
+
`document.edit(instructions, options)` edits a markdown document or a task's body
|
|
831
|
+
by natural-language instructions. The AI editor merges its changes with anyone
|
|
832
|
+
editing at the same time. Say where (name the section or quote the text) and
|
|
833
|
+
describe the outcome:
|
|
834
|
+
|
|
835
|
+
```ts
|
|
836
|
+
const { revision, webUrl } = await document.edit(
|
|
837
|
+
'Rewrite the "Summary" section as three bullet points. Keep the heading.',
|
|
838
|
+
{ fast: true },
|
|
839
|
+
);
|
|
840
|
+
```
|
|
841
|
+
|
|
842
|
+
It returns the new revision, not a diff; read `content()` to see what changed.
|
|
843
|
+
`options.signal` cancels the edit, keeping what was applied before the abort. A
|
|
844
|
+
refused edit throws `DocumentEditRefusedError` with the editor's reason;
|
|
845
|
+
`EditOutcomeUnknownError` means read the document before retrying.
|
|
846
|
+
|
|
847
|
+
### Canvases
|
|
848
|
+
|
|
849
|
+
`document.canvas()` reads and edits a native canvas's live, shared scene:
|
|
850
|
+
|
|
851
|
+
```ts
|
|
852
|
+
const canvas = document.canvas();
|
|
853
|
+
const scene = await canvas.scene(); // stable item ids, geometry, text, revision
|
|
854
|
+
await canvas.apply(
|
|
855
|
+
"editor.move(['box'], 0, 40); editor.text('box', snippets.label)",
|
|
856
|
+
{ expectedRevision: scene.revision, snippets: { label: 'Shipped' } },
|
|
857
|
+
);
|
|
858
|
+
await canvas.edit('Arrange the boxes left to right as a flowchart.');
|
|
859
|
+
const image = await canvas.render({ items: ['box'] }); // a StaticImage
|
|
860
|
+
```
|
|
861
|
+
|
|
862
|
+
`apply` runs CanvasEditor code without a model and commits the batch whole or
|
|
863
|
+
not at all: `CanvasRevisionConflictError` (the scene changed since
|
|
864
|
+
`expectedRevision`) and `CanvasEditRejectedError` (the code failed) mean nothing
|
|
865
|
+
changed; `EditOutcomeUnknownError` means read the scene before retrying. `edit`
|
|
866
|
+
takes natural-language instructions, like `document.edit`, and is billed as an
|
|
867
|
+
AI edit. `render` keeps the PNG as a static file you own, ready to attach to a
|
|
868
|
+
message. A canvas links to `canvas.webUrl()` (`/app/canvas/<id>`).
|
|
869
|
+
|
|
870
|
+
### Spreadsheets
|
|
871
|
+
|
|
872
|
+
`documents.createSpreadsheet({ name })` creates a blank native spreadsheet, and
|
|
873
|
+
`documents.spreadsheet(document)` addresses an existing one. `read()` returns
|
|
874
|
+
every sheet's summary and the cells of the requested ranges with the revision,
|
|
875
|
+
`calculate(formulas, { overrides })` evaluates scratch formulas without saving,
|
|
876
|
+
and `applyEdits(operations, { expectedRevision })` saves one atomic batch:
|
|
877
|
+
|
|
878
|
+
```ts
|
|
879
|
+
const sheet = macro.documents.spreadsheet(document);
|
|
880
|
+
const { revision, sheets } = await sheet.read({ ranges: ['A1:D20'] });
|
|
881
|
+
await sheet.applyEdits(
|
|
882
|
+
[{ type: 'set_cells', sheetId: sheets[0].id, cells: [{ address: 'D21', value: '=SUM(D2:D20)' }] }],
|
|
883
|
+
{ expectedRevision: revision },
|
|
884
|
+
);
|
|
885
|
+
```
|
|
886
|
+
|
|
887
|
+
A workbook that changed since the read throws `RevisionConflictError` and
|
|
888
|
+
saves nothing: read again and rebuild the batch.
|
|
889
|
+
|
|
890
|
+
`sheet.edit(instructions)` hands the change to an AI writer instead, which reads
|
|
891
|
+
what it needs and saves one batch the same way. It is billed as an AI edit and
|
|
892
|
+
throws `DocumentEditRefusedError` with the writer's reason when it can't do it.
|
|
893
|
+
|
|
894
|
+
### Document lifecycle and other resources
|
|
895
|
+
|
|
896
|
+
`documents.createUpload(options)` reserves a binary document and returns upload
|
|
897
|
+
instructions. `document.prepareSave(parts)`, `save(options)` and `simpleSave()` expose
|
|
898
|
+
the existing content lifecycle; upload bytes before committing. Version handles
|
|
899
|
+
come from `document.version(number)`. PDF highlights and comment anchors are scoped
|
|
900
|
+
handles from `anchors()` / `createHighlight(options)`, with kind-checked edits and
|
|
901
|
+
deletion. `documents.byTeamSlug('ENG-42')` resolves a task reference.
|
|
902
|
+
`sharePermissions`, `permissionsToken` and `documents.validatePermissionsToken`
|
|
903
|
+
expose document access contracts.
|
|
904
|
+
|
|
905
|
+
`macro.githubPullRequests.byId(foreignEntityId)` reads stored GitHub snapshots;
|
|
906
|
+
`changes()` returns a changeset handle with `patch()`. `macro.entityMentions.create`
|
|
907
|
+
takes typed source/target references and returns a deletable mention handle.
|
|
908
|
+
`macro.unfurls.get(url)` and `bulk(urls)` read URL preview metadata.
|
|
909
|
+
|
|
910
|
+
`macro.apiKeys.create(name)` returns `{ key, secret }`. Save the secret immediately;
|
|
911
|
+
the handle only retains metadata. It and `bot.createToken()` are refused to an
|
|
912
|
+
agent's program (ExecuteCode, a routine), whose results reach the model. `list()` and `key.delete()` manage keys.
|
|
913
|
+
`tokenForEmail(email)` exchanges credentials subject to ordinary server authorization;
|
|
914
|
+
an agent's program is refused.
|
|
915
|
+
|
|
916
|
+
`chat.send({ content, model, attachments, toolset })` starts a generation and returns
|
|
917
|
+
its chat, response message and cancellable stream handle. Use
|
|
918
|
+
`generation.message.refresh()` after it changes; reading an unfinished response
|
|
919
|
+
may report that it is not yet available. Tools can perform writes unless disabled.
|
|
920
|
+
`macro.ai.usage({ from, until, users, features })` reads AI usage.
|
|
921
|
+
|
|
922
|
+
# Events
|
|
923
|
+
|
|
924
|
+
`macro.events` is always available. The default transport is a live SSE
|
|
925
|
+
stream — no public URL, persisted webhook, or signing secret required.
|
|
926
|
+
|
|
927
|
+
```ts
|
|
928
|
+
const macro = new Rox({
|
|
929
|
+
token: process.env.ROX_API_KEY,
|
|
930
|
+
});
|
|
931
|
+
|
|
932
|
+
const me = await macro.users.me();
|
|
933
|
+
|
|
934
|
+
macro.events.on('message.posted', async ({ metadata, target }) => {
|
|
935
|
+
if (metadata.sender === me.id) return; // don't reply to ourselves
|
|
936
|
+
if (target.type === 'channel') await target.message.reply('hi!');
|
|
937
|
+
else await target.comment.reply('hi!');
|
|
938
|
+
});
|
|
939
|
+
|
|
940
|
+
const stop = await macro.events.listen();
|
|
941
|
+
// later: stop();
|
|
942
|
+
```
|
|
943
|
+
|
|
944
|
+
`listen()` opens `GET /webhook/events/stream` with the same `WebhookFilters`
|
|
945
|
+
model as persisted webhooks. If you omit `filters`, it derives one filter from
|
|
946
|
+
the event names already registered with `.on()`. Pass `scope: 'team'` for a
|
|
947
|
+
team workspace (defaults to `'user'`). Delivery is best-effort: there is no
|
|
948
|
+
replay if you disconnect. Reconnecting sends `Last-Event-ID`, but the service
|
|
949
|
+
replays only for clients that also ask `resume=true`, which `listen()` does
|
|
950
|
+
not, so a reconnected listener gets the live stream as before.
|
|
951
|
+
|
|
952
|
+
Handlers receive the same hydrated payloads as webhook deliveries — ORM
|
|
953
|
+
handles for every entity the event names.
|
|
954
|
+
|
|
955
|
+
Five families are delivered: `document.*`, `channel.*`, `message.*`, `user.*`,
|
|
956
|
+
and `agent_session.*`. Message events (`posted`, `patched`, `deleted`, `mentioned`,
|
|
957
|
+
`attachment_created`, `attachment_removed`) cover channel messages and document
|
|
958
|
+
comments alike: `metadata.parent` names the channel or document, and the
|
|
959
|
+
hydrated `target` carries a `Channel` plus `Message` (and the `Thread` for a
|
|
960
|
+
reply) or a `Document` plus `Comment`. `macro.events.onSelfMention` subscribes to
|
|
961
|
+
`message.mentioned` deliveries that name the caller.
|
|
962
|
+
`user.picture_changed` tells you a user's own profile picture changed (set or
|
|
963
|
+
removed) and is delivered only to the changed user's own workspaces; it hydrates
|
|
964
|
+
to the `User` and, when the picture is a static file, its `StaticImage` (`image`
|
|
965
|
+
is undefined when the picture was removed or set by URL).
|
|
966
|
+
Agent-session events describe a coding agent's life: `opened`, `turn_started`,
|
|
967
|
+
`turn_ended`, `settled` (a turn ended with nothing queued behind it),
|
|
968
|
+
`waiting_for_input` (the agent asked its owner a question), `input_received`,
|
|
969
|
+
`mentioned` (a prompt named other users who can see the session), `stopped`,
|
|
970
|
+
`renamed`, and `deleted`. Each carries the session's identity and
|
|
971
|
+
hydrates to an `AgentSession` handle, the owner `User`, and, for a session
|
|
972
|
+
opened from a channel thread, the `Channel`, `Thread`, and magic-chip
|
|
973
|
+
`Message` the turn renders into.
|
|
974
|
+
|
|
975
|
+
```ts
|
|
976
|
+
macro.events.on('agent_session.settled', async ({ metadata, session, thread }) => {
|
|
977
|
+
console.log(`${metadata.identity.bot_name} finished: ${metadata.last_turn?.excerpt}`);
|
|
978
|
+
await thread?.reply(msg`Done — see ${session}`);
|
|
979
|
+
});
|
|
980
|
+
```
|
|
981
|
+
|
|
982
|
+
### Persisted webhooks
|
|
983
|
+
|
|
984
|
+
To receive the same events as HTTPS POSTs instead of (or in addition to) SSE,
|
|
985
|
+
register a webhook and pass a `webhookSecret` (or set `ROX_WEBHOOK_SECRET`).
|
|
986
|
+
Use a framework like Hono or Express to handle the request; the SDK verifies
|
|
987
|
+
the signature and dispatches.
|
|
988
|
+
|
|
989
|
+
```ts
|
|
990
|
+
const macro = new Rox({
|
|
991
|
+
token: process.env.ROX_API_KEY,
|
|
992
|
+
webhookSecret: process.env.ROX_WEBHOOK_SECRET,
|
|
993
|
+
});
|
|
994
|
+
|
|
995
|
+
macro.events.on('message.posted', async ({ metadata, target }) => {
|
|
996
|
+
if (metadata.sender === me.id || target.type !== 'channel') return;
|
|
997
|
+
await target.message.reply('hi!');
|
|
998
|
+
});
|
|
999
|
+
|
|
1000
|
+
// Hono
|
|
1001
|
+
app.post('/webhook', (c) => macro.events.webhook()(c.req.raw));
|
|
1002
|
+
```
|
|
1003
|
+
|
|
1004
|
+
Call chat events have `event.target.type === 'call'`, with a `CallRecord` in
|
|
1005
|
+
`event.target.call` and a `CallMessage` in `event.target.message`. Read with
|
|
1006
|
+
`content()`, or call `reply(body)`, `edit(body)`, and `delete()`. Replies always
|
|
1007
|
+
join the call's single chat thread, even when responding to another reply.
|
|
1008
|
+
`macro.calls.byId(callId).message(messageId)` creates the same lazy message handle.
|
|
1009
|
+
|
|
1010
|
+
# Upgrading to 0.2
|
|
1011
|
+
|
|
1012
|
+
Channel messages, document comments, and CRM company and contact comments share
|
|
1013
|
+
one API, `/messages/{parent_type}/{parent_id}`, and the SDK entities follow it.
|
|
1014
|
+
The old channel message, document comment, and CRM comment routes are removed
|
|
1015
|
+
from the server in the same release, so 0.1 clients stop working against it.
|
|
1016
|
+
The public `Channel`, `Message`, `Thread`, `Document`, `Company`, and `Contact`
|
|
1017
|
+
methods keep their names; these details changed:
|
|
1018
|
+
|
|
1019
|
+
- `Channel.messages()` and `Channel.messagesAfter()` page with the structured
|
|
1020
|
+
`MessageCursor` and yield `Message` handles seeded from the shared message
|
|
1021
|
+
record (`mentions` are now populated from list reads too).
|
|
1022
|
+
- `Channel.typing(action)` takes `'start' | 'stop'` and posts to
|
|
1023
|
+
`/messages/channel/{id}/typing`.
|
|
1024
|
+
- `Message.from(client, channelId, record)` replaces `Message.from(client, record)`,
|
|
1025
|
+
`Message.fromReply`, and `Message.received`.
|
|
1026
|
+
- `Comment` ids are message UUIDs: `Comment.commentId` is gone, `Comment.threadId()`
|
|
1027
|
+
is async and returns the root comment id, `Comment.edit` accepts a rich body, and
|
|
1028
|
+
`Comment.reply` exists. `Document.comment(body, { threadId })` takes a string
|
|
1029
|
+
thread id and a rich body; `Document.comments()` returns `{ thread: ThreadState,
|
|
1030
|
+
comments }` per live thread.
|
|
1031
|
+
- `CrmComment` is a message-backed comment on its company or contact
|
|
1032
|
+
(`parent: { type: 'crm_company' | 'crm_contact', id }`). Its ids are message
|
|
1033
|
+
UUIDs (imported comments kept their old ids); `text`, `createdAt`,
|
|
1034
|
+
`updatedAt`, and `deletedAt` are lazy accessors; `threadId()` and `author()`
|
|
1035
|
+
are async; `edit` accepts a rich body; and `reply` exists. `owner`, `sender`,
|
|
1036
|
+
`order`, and `metadata` are gone. `Company.comments()` and
|
|
1037
|
+
`Contact.comments()` return `{ thread: ThreadState, comments }` per live
|
|
1038
|
+
thread; `comment(body, { threadId })` replaces `comment({ text, threadId })`;
|
|
1039
|
+
`commentById(id)` returns a handle; `editComment` and `deleteComment` are
|
|
1040
|
+
replaced by `CrmComment.edit` and `CrmComment.delete`. Deleting a thread's
|
|
1041
|
+
root keeps its replies, as it does for channel and document threads.
|
|
1042
|
+
- Webhook and SSE events `channel.message_posted`, `channel.mentioned`,
|
|
1043
|
+
`channel.message_patched`, `channel.message_deleted`,
|
|
1044
|
+
`channel.message_attachment_created`, and `channel.message_attachment_removed`
|
|
1045
|
+
are replaced by `message.posted`, `message.mentioned`, `message.patched`,
|
|
1046
|
+
`message.deleted`, `message.attachment_created`, and
|
|
1047
|
+
`message.attachment_removed`. Their metadata carries `parent` instead of
|
|
1048
|
+
`channel_id`, and handlers receive `target` (see Events above) instead of
|
|
1049
|
+
`channel`/`message`/`thread`. `onSelfMention` handlers now receive
|
|
1050
|
+
`message.mentioned` events. Update persisted webhook filters accordingly.
|
|
1051
|
+
|
|
1052
|
+
Removed storage operations and their replacements: `getChannelMessages` →
|
|
1053
|
+
`messageTimeline`; `getChannelMessagesCatchUp` → `messageTimeline` with
|
|
1054
|
+
`activity_after`; `getThreadReplies` → `entityMessageGetThread`;
|
|
1055
|
+
`getMessageWithContext` → `entityMessageGetMessage` / `messageTimeline` with
|
|
1056
|
+
`around`; `postMessage` → `entityMessageCreate`; `patchMessage` →
|
|
1057
|
+
`entityMessageEdit`; `deleteMessage` → `entityMessageDeleteMessage`;
|
|
1058
|
+
`postReaction` → `entityMessageReact`; `postTyping` → `entityMessageTyping`;
|
|
1059
|
+
`getDocumentComments` → `messageTimeline` + `entityMessageGetThread` on a
|
|
1060
|
+
document parent; `createComment` → `entityMessageCreate`; `editComment` →
|
|
1061
|
+
`entityMessageEdit`; `deleteComment` → `entityMessageDeleteMessage`;
|
|
1062
|
+
`listCrmComments` → `messageTimeline` + `entityMessageGetThread` on a
|
|
1063
|
+
`crm_company` or `crm_contact` parent; `createCrmComment` →
|
|
1064
|
+
`entityMessageCreate`; `editCrmComment` → `entityMessageEdit`;
|
|
1065
|
+
`deleteCrmComment` → `entityMessageDeleteMessage`.
|
|
1066
|
+
|
|
1067
|
+
# Developing
|
|
1068
|
+
|
|
1069
|
+
This section is just if you are contributing to the SDK.
|
|
1070
|
+
|
|
1071
|
+
## Releases
|
|
1072
|
+
|
|
1073
|
+
See [Releasing the SDK](RELEASING.md) for patch version bumps, npm setup,
|
|
1074
|
+
and tag-triggered publishing. Agents can use the
|
|
1075
|
+
[`release-sdk`](../../.agents/skills/release-sdk/SKILL.md) skill.
|
|
1076
|
+
|
|
1077
|
+
## Coverage checking
|
|
1078
|
+
|
|
1079
|
+
We have a coverage checker. It reads every generated function and ensures that
|
|
1080
|
+
every client function that is generated is called by some hand-written function
|
|
1081
|
+
in `src/`. If a generated function is not called, the coverage checker will fail
|
|
1082
|
+
the build.
|
|
1083
|
+
|
|
1084
|
+
You can add exceptions for stuff OpenAPI covers that we don't want the sdk to
|
|
1085
|
+
support by adding them to the `src/coverage/skipped.ts`. You can implement
|
|
1086
|
+
support by adding a wrapper to the appropriate model. Every wrapped generated
|
|
1087
|
+
method also needs a hand-assigned display verb in `src/utils/verbs.ts`; choose a
|
|
1088
|
+
read verb for a POST that only reads. Coverage fails for missing or stale verb
|
|
1089
|
+
entries as well as uncovered endpoints.
|
|
1090
|
+
|
|
1091
|
+
## Events
|
|
1092
|
+
|
|
1093
|
+
Event names and payloads are **generated from the backend**: the Rust webhook
|
|
1094
|
+
crate exposes a `WebhookEvent` union in the storage OpenAPI spec, and
|
|
1095
|
+
`src/events/types.ts` derives `EventName` / `EventPayload` from it. SSE
|
|
1096
|
+
(`listen()`) and persisted webhooks (`webhook()`) dispatch the same union.
|
|
1097
|
+
|
|
1098
|
+
### AI generation and decisions
|
|
1099
|
+
|
|
1100
|
+
Shared cognition endpoints are available through `macro.ai`. They use the
|
|
1101
|
+
authenticated user's model access and AI allowance. For generation using only
|
|
1102
|
+
supplied context, explicitly set `toolset: { type: 'none' }`:
|
|
1103
|
+
|
|
1104
|
+
```ts
|
|
1105
|
+
const answer = await macro.ai.structuredCompletion({
|
|
1106
|
+
prompt: 'Summarize these supplied notes: ...',
|
|
1107
|
+
model: 'google/gemini-3.8-flash',
|
|
1108
|
+
toolset: { type: 'none' },
|
|
1109
|
+
output_schema: {
|
|
1110
|
+
name: 'Summary',
|
|
1111
|
+
schema: {
|
|
1112
|
+
type: 'object',
|
|
1113
|
+
properties: { summary: { type: 'string' } },
|
|
1114
|
+
required: ['summary'],
|
|
1115
|
+
},
|
|
1116
|
+
},
|
|
1117
|
+
});
|
|
1118
|
+
const decision = await macro.ai.decide({
|
|
1119
|
+
input: { subject: 'Invoice due tomorrow', body: 'Please pay by Friday.' },
|
|
1120
|
+
questions: { needsAction: 'Does this ask the recipient to take action?' },
|
|
1121
|
+
});
|
|
1122
|
+
console.log(answer.outcome, decision.probabilities.needsAction);
|
|
1123
|
+
```
|
|
1124
|
+
|
|
1125
|
+
Decision probabilities estimate yes independently for each named question; they
|
|
1126
|
+
do not authorize any action. Structured completions with tools enabled can modify
|
|
1127
|
+
data, so inspect `outcome` and `toolActivity` even when generation is interrupted.
|
|
1128
|
+
|
|
1129
|
+
### Workspace browsing
|
|
1130
|
+
|
|
1131
|
+
Use `macro.workspace.page(options)` for a bounded page or
|
|
1132
|
+
`macro.workspace.list(options)` for lazy automatic pagination. Results include
|
|
1133
|
+
existing entity handles plus generated API snapshots, so metadata does not
|
|
1134
|
+
require a second request:
|
|
1135
|
+
|
|
1136
|
+
```ts
|
|
1137
|
+
const page = await macro.workspace.page({
|
|
1138
|
+
includeTypes: ['document'],
|
|
1139
|
+
sortBy: 'recently_updated',
|
|
1140
|
+
limit: 5,
|
|
1141
|
+
});
|
|
1142
|
+
for (const item of page.items) {
|
|
1143
|
+
if (item.type === 'document') console.log(item.id, item.name);
|
|
1144
|
+
}
|
|
1145
|
+
console.log({ hasMore: page.hasMore, nextCursor: page.nextCursor });
|
|
1146
|
+
```
|
|
1147
|
+
|
|
1148
|
+
The namespace supports documents (including tasks), AI chats, projects, email,
|
|
1149
|
+
channels, channel threads, call records, calendar events and foreign entities.
|
|
1150
|
+
Options preserve source scope through server-side type, time, property, task,
|
|
1151
|
+
favorites, tag and inbox filters. Tags accept personal/team scopes and any/all
|
|
1152
|
+
matching; ambiguous all-matches and unknown labels fail explicitly. Inbox names
|
|
1153
|
+
resolve against all accessible inboxes, including delegated inboxes. `limit`
|
|
1154
|
+
controls page size (default 50, maximum 500); break a `for await` loop to stop
|
|
1155
|
+
without fetching another page. The TypeDoc namespace reference includes task,
|
|
1156
|
+
date-window, signal-email and scoped-tag examples.
|
|
1157
|
+
|
|
1158
|
+
### Saved code executions
|
|
1159
|
+
|
|
1160
|
+
An execution is a lazy entity handle scoped to its agent session. Construct it
|
|
1161
|
+
with the execution ID from an `ExecuteCode` receipt, then read fields on the handle:
|
|
1162
|
+
|
|
1163
|
+
```ts
|
|
1164
|
+
const session = macro.agentSessions.byId(sessionId);
|
|
1165
|
+
const execution = session.codeExecutions.byId(executionId);
|
|
1166
|
+
const status = await execution.status();
|
|
1167
|
+
const source = await execution.source();
|
|
1168
|
+
const result = await execution.result();
|
|
1169
|
+
const calls = await execution.calls();
|
|
1170
|
+
await execution.refresh(); // Reload after a running execution changes.
|
|
1171
|
+
```
|
|
1172
|
+
|
|
1173
|
+
Constructing the handle makes no request. Field reads share a cached record;
|
|
1174
|
+
`refresh()` reloads it. `execution.session()` returns the parent session handle.
|
|
1175
|
+
Every read remains authorized and scoped by both session and execution identity.
|
|
1176
|
+
|
|
1177
|
+
### Persistent code-execution reviews
|
|
1178
|
+
|
|
1179
|
+
A code execution can prepare a saved UI review and finish immediately. The review
|
|
1180
|
+
is presented immediately through the ordinary ACP tool-call stream and remains
|
|
1181
|
+
editable after the execution exits. `session.reviews.create(...)` uses the same
|
|
1182
|
+
presentation without requiring a code execution. The session owner can
|
|
1183
|
+
send one email, send all remaining emails, create a reviewed calendar event, or
|
|
1184
|
+
answer a question. External actions only happen on submission.
|
|
1185
|
+
|
|
1186
|
+
```js
|
|
1187
|
+
const execution = macro.agentSessions.byId(sessionId)
|
|
1188
|
+
.codeExecutions.byId(executionId);
|
|
1189
|
+
const review = await execution.reviews.create({
|
|
1190
|
+
kind: 'email',
|
|
1191
|
+
title: 'Follow-up emails',
|
|
1192
|
+
drafts: people.map((person) => ({
|
|
1193
|
+
subject: 'Following up',
|
|
1194
|
+
body: `Hello ${person.name},\n\nThanks for joining us.`,
|
|
1195
|
+
to: [{ email: person.email, name: person.name }],
|
|
1196
|
+
})),
|
|
1197
|
+
});
|
|
1198
|
+
return { data: { prepared: people.length }, reviews: [await review.reference()] };
|
|
1199
|
+
```
|
|
1200
|
+
|
|
1201
|
+
`execution.reviews.list()` returns fresh `SessionReview` handles.
|
|
1202
|
+
`session.reviews.byId(id)` constructs a lazy handle; `review.items()` returns item
|
|
1203
|
+
handles with `edit(draft)`, `submit()`, and `dismiss()` methods. `submitAll()` and
|
|
1204
|
+
`dismissAll()` act on the pending items. Writes use the saved revision. After a
|
|
1205
|
+
conflict, refresh and inspect the review; never automatically retry a send whose
|
|
1206
|
+
outcome is unknown. These SDK methods have the same user authorization as the
|
|
1207
|
+
ordinary API: review cards offer a user workflow, not a separate security grant.
|
|
1208
|
+
|
|
1209
|
+
### External chats and WhatsApp
|
|
1210
|
+
|
|
1211
|
+
Pair your personal account in Rox's External view first. Your WhatsApp chat
|
|
1212
|
+
list (`whatsapp.chats()`) holds groups and direct chats; adding one makes an
|
|
1213
|
+
independent `ExternalChat` entity (a group or a direct chat, with `provider`
|
|
1214
|
+
`whatsapp`) with its own history and ordinary sharing, and its earlier messages
|
|
1215
|
+
are imported from your phone. `externalChats.list()` returns every added chat
|
|
1216
|
+
you can view; shared viewers can read without WhatsApp. Sending and media
|
|
1217
|
+
uploads require your own connected account in the chat, using your personal
|
|
1218
|
+
session or own API credential; only the owner sends in a direct chat, and bots
|
|
1219
|
+
never send. Adding and removing require a personal bearer session. Each user is
|
|
1220
|
+
limited to one send request per second across all chats.
|
|
1221
|
+
|
|
1222
|
+
```ts
|
|
1223
|
+
const personal = new Rox({
|
|
1224
|
+
auth: { type: 'user', token: () => session.accessToken() },
|
|
1225
|
+
});
|
|
1226
|
+
let chat;
|
|
1227
|
+
for (const entry of await personal.whatsapp.chats()) {
|
|
1228
|
+
if (await entry.canAdd()) {
|
|
1229
|
+
chat = await entry.add();
|
|
1230
|
+
break;
|
|
1231
|
+
}
|
|
1232
|
+
}
|
|
1233
|
+
if (chat && (await chat.canSend())) {
|
|
1234
|
+
const [someone] = await chat.participants();
|
|
1235
|
+
const send = await chat.send(
|
|
1236
|
+
{
|
|
1237
|
+
type: 'text',
|
|
1238
|
+
text: someone ? `Hello @${someone.mentionToken}` : 'Hello',
|
|
1239
|
+
mentions: someone ? [someone] : [],
|
|
1240
|
+
},
|
|
1241
|
+
{ idempotencyKey: crypto.randomUUID() },
|
|
1242
|
+
);
|
|
1243
|
+
await send.refresh();
|
|
1244
|
+
console.log(await send.state());
|
|
1245
|
+
}
|
|
1246
|
+
for (const shared of await personal.externalChats.list()) {
|
|
1247
|
+
for await (const message of shared.messages()) console.log(await message.body());
|
|
1248
|
+
}
|
|
1249
|
+
```
|
|
1250
|
+
|
|
1251
|
+
Keep the same idempotency key when retrying the same request. A delivery state of
|
|
1252
|
+
`unknown` must be reconciled; never automatically resend it. Uploads, quoted
|
|
1253
|
+
messages, mentions, mutations, and delivery references must belong to the same chat.
|
|
1254
|
+
|
|
1255
|
+
## Live call media
|
|
1256
|
+
|
|
1257
|
+
Use `@rox-one/sdk/calls/node` or `@rox-one/sdk/calls/browser` for room
|
|
1258
|
+
connections and screen sharing. Install the optional LiveKit runtime only when
|
|
1259
|
+
using those helpers. The core import does not load or bundle call media code.
|
|
1260
|
+
See [Call rooms](CALLS.md) for installation and examples.
|