@rox-one/sdk 0.0.0-stage → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (483) hide show
  1. package/CALLS.md +82 -0
  2. package/README.md +1259 -2
  3. package/dist/chunk-AOHK5YXC.js +5585 -0
  4. package/dist/chunk-CATFKTFD.js +80 -0
  5. package/dist/chunk-FQGPXWPJ.js +1491 -0
  6. package/dist/chunk-G43PLP2U.js +1087 -0
  7. package/dist/chunk-LMJW65ML.js +836 -0
  8. package/dist/chunk-MCSQNZ4E.js +836 -0
  9. package/dist/chunk-NSJ3GKUC.js +1552 -0
  10. package/dist/chunk-OGFKJOK7.js +2068 -0
  11. package/dist/chunk-RDEJZJBZ.js +1351 -0
  12. package/dist/chunk-TMTYN2UK.js +1128 -0
  13. package/dist/chunk-V45LUJDI.js +838 -0
  14. package/dist/chunk-YRUXFEZM.js +1044 -0
  15. package/dist/chunk-ZYBAKW25.js +994 -0
  16. package/dist/generated/agent-fold/index.d.ts +4520 -0
  17. package/dist/generated/agent-fold/index.js +0 -0
  18. package/dist/generated/agent-harness/client/client.gen.d.ts +2 -0
  19. package/dist/generated/agent-harness/client/index.d.ts +10 -0
  20. package/dist/generated/agent-harness/client/types.gen.d.ts +120 -0
  21. package/dist/generated/agent-harness/client/utils.gen.d.ts +37 -0
  22. package/dist/generated/agent-harness/client.gen.d.ts +12 -0
  23. package/dist/generated/agent-harness/core/auth.gen.d.ts +25 -0
  24. package/dist/generated/agent-harness/core/bodySerializer.gen.d.ts +25 -0
  25. package/dist/generated/agent-harness/core/params.gen.d.ts +43 -0
  26. package/dist/generated/agent-harness/core/pathSerializer.gen.d.ts +33 -0
  27. package/dist/generated/agent-harness/core/queryKeySerializer.gen.d.ts +18 -0
  28. package/dist/generated/agent-harness/core/serverSentEvents.gen.d.ts +71 -0
  29. package/dist/generated/agent-harness/core/types.gen.d.ts +83 -0
  30. package/dist/generated/agent-harness/core/utils.gen.d.ts +19 -0
  31. package/dist/generated/agent-harness/index.d.ts +2 -0
  32. package/dist/generated/agent-harness/index.js +6 -0
  33. package/dist/generated/agent-harness/sdk.gen.d.ts +375 -0
  34. package/dist/generated/agent-harness/types.gen.d.ts +4725 -0
  35. package/dist/generated/agent-reviews/index.d.ts +895 -0
  36. package/dist/generated/agent-reviews/index.js +0 -0
  37. package/dist/generated/auth/client/client.gen.d.ts +2 -0
  38. package/dist/generated/auth/client/index.d.ts +10 -0
  39. package/dist/generated/auth/client/types.gen.d.ts +120 -0
  40. package/dist/generated/auth/client/utils.gen.d.ts +37 -0
  41. package/dist/generated/auth/client.gen.d.ts +12 -0
  42. package/dist/generated/auth/core/auth.gen.d.ts +25 -0
  43. package/dist/generated/auth/core/bodySerializer.gen.d.ts +25 -0
  44. package/dist/generated/auth/core/params.gen.d.ts +43 -0
  45. package/dist/generated/auth/core/pathSerializer.gen.d.ts +33 -0
  46. package/dist/generated/auth/core/queryKeySerializer.gen.d.ts +18 -0
  47. package/dist/generated/auth/core/serverSentEvents.gen.d.ts +71 -0
  48. package/dist/generated/auth/core/types.gen.d.ts +83 -0
  49. package/dist/generated/auth/core/utils.gen.d.ts +19 -0
  50. package/dist/generated/auth/index.d.ts +2 -0
  51. package/dist/generated/auth/index.js +6 -0
  52. package/dist/generated/auth/sdk.gen.d.ts +674 -0
  53. package/dist/generated/auth/types.gen.d.ts +5233 -0
  54. package/dist/generated/calendar/client/client.gen.d.ts +2 -0
  55. package/dist/generated/calendar/client/index.d.ts +10 -0
  56. package/dist/generated/calendar/client/types.gen.d.ts +120 -0
  57. package/dist/generated/calendar/client/utils.gen.d.ts +37 -0
  58. package/dist/generated/calendar/client.gen.d.ts +12 -0
  59. package/dist/generated/calendar/core/auth.gen.d.ts +25 -0
  60. package/dist/generated/calendar/core/bodySerializer.gen.d.ts +25 -0
  61. package/dist/generated/calendar/core/params.gen.d.ts +43 -0
  62. package/dist/generated/calendar/core/pathSerializer.gen.d.ts +33 -0
  63. package/dist/generated/calendar/core/queryKeySerializer.gen.d.ts +18 -0
  64. package/dist/generated/calendar/core/serverSentEvents.gen.d.ts +71 -0
  65. package/dist/generated/calendar/core/types.gen.d.ts +83 -0
  66. package/dist/generated/calendar/core/utils.gen.d.ts +19 -0
  67. package/dist/generated/calendar/index.d.ts +2 -0
  68. package/dist/generated/calendar/index.js +6 -0
  69. package/dist/generated/calendar/sdk.gen.d.ts +157 -0
  70. package/dist/generated/calendar/types.gen.d.ts +2333 -0
  71. package/dist/generated/cognition/client/client.gen.d.ts +2 -0
  72. package/dist/generated/cognition/client/index.d.ts +10 -0
  73. package/dist/generated/cognition/client/types.gen.d.ts +120 -0
  74. package/dist/generated/cognition/client/utils.gen.d.ts +37 -0
  75. package/dist/generated/cognition/client.gen.d.ts +12 -0
  76. package/dist/generated/cognition/core/auth.gen.d.ts +25 -0
  77. package/dist/generated/cognition/core/bodySerializer.gen.d.ts +25 -0
  78. package/dist/generated/cognition/core/params.gen.d.ts +43 -0
  79. package/dist/generated/cognition/core/pathSerializer.gen.d.ts +33 -0
  80. package/dist/generated/cognition/core/queryKeySerializer.gen.d.ts +18 -0
  81. package/dist/generated/cognition/core/serverSentEvents.gen.d.ts +71 -0
  82. package/dist/generated/cognition/core/types.gen.d.ts +83 -0
  83. package/dist/generated/cognition/core/utils.gen.d.ts +19 -0
  84. package/dist/generated/cognition/index.d.ts +2 -0
  85. package/dist/generated/cognition/index.js +6 -0
  86. package/dist/generated/cognition/sdk.gen.d.ts +348 -0
  87. package/dist/generated/cognition/types.gen.d.ts +4228 -0
  88. package/dist/generated/connection/client/client.gen.d.ts +2 -0
  89. package/dist/generated/connection/client/index.d.ts +10 -0
  90. package/dist/generated/connection/client/types.gen.d.ts +120 -0
  91. package/dist/generated/connection/client/utils.gen.d.ts +37 -0
  92. package/dist/generated/connection/client.gen.d.ts +12 -0
  93. package/dist/generated/connection/core/auth.gen.d.ts +25 -0
  94. package/dist/generated/connection/core/bodySerializer.gen.d.ts +25 -0
  95. package/dist/generated/connection/core/params.gen.d.ts +43 -0
  96. package/dist/generated/connection/core/pathSerializer.gen.d.ts +33 -0
  97. package/dist/generated/connection/core/queryKeySerializer.gen.d.ts +18 -0
  98. package/dist/generated/connection/core/serverSentEvents.gen.d.ts +71 -0
  99. package/dist/generated/connection/core/types.gen.d.ts +83 -0
  100. package/dist/generated/connection/core/utils.gen.d.ts +19 -0
  101. package/dist/generated/connection/index.d.ts +2 -0
  102. package/dist/generated/connection/index.js +854 -0
  103. package/dist/generated/connection/sdk.gen.d.ts +43 -0
  104. package/dist/generated/connection/types.gen.d.ts +252 -0
  105. package/dist/generated/contacts/client/client.gen.d.ts +2 -0
  106. package/dist/generated/contacts/client/index.d.ts +10 -0
  107. package/dist/generated/contacts/client/types.gen.d.ts +120 -0
  108. package/dist/generated/contacts/client/utils.gen.d.ts +37 -0
  109. package/dist/generated/contacts/client.gen.d.ts +12 -0
  110. package/dist/generated/contacts/core/auth.gen.d.ts +25 -0
  111. package/dist/generated/contacts/core/bodySerializer.gen.d.ts +25 -0
  112. package/dist/generated/contacts/core/params.gen.d.ts +43 -0
  113. package/dist/generated/contacts/core/pathSerializer.gen.d.ts +33 -0
  114. package/dist/generated/contacts/core/queryKeySerializer.gen.d.ts +18 -0
  115. package/dist/generated/contacts/core/serverSentEvents.gen.d.ts +71 -0
  116. package/dist/generated/contacts/core/types.gen.d.ts +83 -0
  117. package/dist/generated/contacts/core/utils.gen.d.ts +19 -0
  118. package/dist/generated/contacts/index.d.ts +2 -0
  119. package/dist/generated/contacts/index.js +6 -0
  120. package/dist/generated/contacts/sdk.gen.d.ts +47 -0
  121. package/dist/generated/contacts/types.gen.d.ts +108 -0
  122. package/dist/generated/email/client/client.gen.d.ts +2 -0
  123. package/dist/generated/email/client/index.d.ts +10 -0
  124. package/dist/generated/email/client/types.gen.d.ts +120 -0
  125. package/dist/generated/email/client/utils.gen.d.ts +37 -0
  126. package/dist/generated/email/client.gen.d.ts +12 -0
  127. package/dist/generated/email/core/auth.gen.d.ts +25 -0
  128. package/dist/generated/email/core/bodySerializer.gen.d.ts +25 -0
  129. package/dist/generated/email/core/params.gen.d.ts +43 -0
  130. package/dist/generated/email/core/pathSerializer.gen.d.ts +33 -0
  131. package/dist/generated/email/core/queryKeySerializer.gen.d.ts +18 -0
  132. package/dist/generated/email/core/serverSentEvents.gen.d.ts +71 -0
  133. package/dist/generated/email/core/types.gen.d.ts +83 -0
  134. package/dist/generated/email/core/utils.gen.d.ts +19 -0
  135. package/dist/generated/email/index.d.ts +2 -0
  136. package/dist/generated/email/index.js +6 -0
  137. package/dist/generated/email/sdk.gen.d.ts +301 -0
  138. package/dist/generated/email/types.gen.d.ts +3262 -0
  139. package/dist/generated/notification/client/client.gen.d.ts +2 -0
  140. package/dist/generated/notification/client/index.d.ts +10 -0
  141. package/dist/generated/notification/client/types.gen.d.ts +120 -0
  142. package/dist/generated/notification/client/utils.gen.d.ts +37 -0
  143. package/dist/generated/notification/client.gen.d.ts +12 -0
  144. package/dist/generated/notification/core/auth.gen.d.ts +25 -0
  145. package/dist/generated/notification/core/bodySerializer.gen.d.ts +25 -0
  146. package/dist/generated/notification/core/params.gen.d.ts +43 -0
  147. package/dist/generated/notification/core/pathSerializer.gen.d.ts +33 -0
  148. package/dist/generated/notification/core/queryKeySerializer.gen.d.ts +18 -0
  149. package/dist/generated/notification/core/serverSentEvents.gen.d.ts +71 -0
  150. package/dist/generated/notification/core/types.gen.d.ts +83 -0
  151. package/dist/generated/notification/core/utils.gen.d.ts +19 -0
  152. package/dist/generated/notification/index.d.ts +2 -0
  153. package/dist/generated/notification/index.js +6 -0
  154. package/dist/generated/notification/sdk.gen.d.ts +127 -0
  155. package/dist/generated/notification/types.gen.d.ts +2084 -0
  156. package/dist/generated/properties/client/client.gen.d.ts +2 -0
  157. package/dist/generated/properties/client/index.d.ts +10 -0
  158. package/dist/generated/properties/client/types.gen.d.ts +120 -0
  159. package/dist/generated/properties/client/utils.gen.d.ts +37 -0
  160. package/dist/generated/properties/client.gen.d.ts +12 -0
  161. package/dist/generated/properties/core/auth.gen.d.ts +25 -0
  162. package/dist/generated/properties/core/bodySerializer.gen.d.ts +25 -0
  163. package/dist/generated/properties/core/params.gen.d.ts +43 -0
  164. package/dist/generated/properties/core/pathSerializer.gen.d.ts +33 -0
  165. package/dist/generated/properties/core/queryKeySerializer.gen.d.ts +18 -0
  166. package/dist/generated/properties/core/serverSentEvents.gen.d.ts +71 -0
  167. package/dist/generated/properties/core/types.gen.d.ts +83 -0
  168. package/dist/generated/properties/core/utils.gen.d.ts +19 -0
  169. package/dist/generated/properties/index.d.ts +2 -0
  170. package/dist/generated/properties/index.js +6 -0
  171. package/dist/generated/properties/sdk.gen.d.ts +158 -0
  172. package/dist/generated/properties/types.gen.d.ts +1311 -0
  173. package/dist/generated/scheduled-action/client/client.gen.d.ts +2 -0
  174. package/dist/generated/scheduled-action/client/index.d.ts +10 -0
  175. package/dist/generated/scheduled-action/client/types.gen.d.ts +120 -0
  176. package/dist/generated/scheduled-action/client/utils.gen.d.ts +37 -0
  177. package/dist/generated/scheduled-action/client.gen.d.ts +12 -0
  178. package/dist/generated/scheduled-action/core/auth.gen.d.ts +25 -0
  179. package/dist/generated/scheduled-action/core/bodySerializer.gen.d.ts +25 -0
  180. package/dist/generated/scheduled-action/core/params.gen.d.ts +43 -0
  181. package/dist/generated/scheduled-action/core/pathSerializer.gen.d.ts +33 -0
  182. package/dist/generated/scheduled-action/core/queryKeySerializer.gen.d.ts +18 -0
  183. package/dist/generated/scheduled-action/core/serverSentEvents.gen.d.ts +71 -0
  184. package/dist/generated/scheduled-action/core/types.gen.d.ts +83 -0
  185. package/dist/generated/scheduled-action/core/utils.gen.d.ts +19 -0
  186. package/dist/generated/scheduled-action/index.d.ts +2 -0
  187. package/dist/generated/scheduled-action/index.js +6 -0
  188. package/dist/generated/scheduled-action/sdk.gen.d.ts +156 -0
  189. package/dist/generated/scheduled-action/types.gen.d.ts +3099 -0
  190. package/dist/generated/search/client/client.gen.d.ts +2 -0
  191. package/dist/generated/search/client/index.d.ts +10 -0
  192. package/dist/generated/search/client/types.gen.d.ts +120 -0
  193. package/dist/generated/search/client/utils.gen.d.ts +37 -0
  194. package/dist/generated/search/client.gen.d.ts +12 -0
  195. package/dist/generated/search/core/auth.gen.d.ts +25 -0
  196. package/dist/generated/search/core/bodySerializer.gen.d.ts +25 -0
  197. package/dist/generated/search/core/params.gen.d.ts +43 -0
  198. package/dist/generated/search/core/pathSerializer.gen.d.ts +33 -0
  199. package/dist/generated/search/core/queryKeySerializer.gen.d.ts +18 -0
  200. package/dist/generated/search/core/serverSentEvents.gen.d.ts +71 -0
  201. package/dist/generated/search/core/types.gen.d.ts +83 -0
  202. package/dist/generated/search/core/utils.gen.d.ts +19 -0
  203. package/dist/generated/search/index.d.ts +2 -0
  204. package/dist/generated/search/index.js +6 -0
  205. package/dist/generated/search/sdk.gen.d.ts +44 -0
  206. package/dist/generated/search/types.gen.d.ts +2532 -0
  207. package/dist/generated/static-files/client/client.gen.d.ts +2 -0
  208. package/dist/generated/static-files/client/index.d.ts +10 -0
  209. package/dist/generated/static-files/client/types.gen.d.ts +120 -0
  210. package/dist/generated/static-files/client/utils.gen.d.ts +37 -0
  211. package/dist/generated/static-files/client.gen.d.ts +12 -0
  212. package/dist/generated/static-files/core/auth.gen.d.ts +25 -0
  213. package/dist/generated/static-files/core/bodySerializer.gen.d.ts +25 -0
  214. package/dist/generated/static-files/core/params.gen.d.ts +43 -0
  215. package/dist/generated/static-files/core/pathSerializer.gen.d.ts +33 -0
  216. package/dist/generated/static-files/core/queryKeySerializer.gen.d.ts +18 -0
  217. package/dist/generated/static-files/core/serverSentEvents.gen.d.ts +71 -0
  218. package/dist/generated/static-files/core/types.gen.d.ts +83 -0
  219. package/dist/generated/static-files/core/utils.gen.d.ts +19 -0
  220. package/dist/generated/static-files/index.d.ts +2 -0
  221. package/dist/generated/static-files/index.js +842 -0
  222. package/dist/generated/static-files/sdk.gen.d.ts +43 -0
  223. package/dist/generated/static-files/types.gen.d.ts +220 -0
  224. package/dist/generated/storage/client/client.gen.d.ts +2 -0
  225. package/dist/generated/storage/client/index.d.ts +10 -0
  226. package/dist/generated/storage/client/types.gen.d.ts +120 -0
  227. package/dist/generated/storage/client/utils.gen.d.ts +37 -0
  228. package/dist/generated/storage/client.gen.d.ts +12 -0
  229. package/dist/generated/storage/core/auth.gen.d.ts +25 -0
  230. package/dist/generated/storage/core/bodySerializer.gen.d.ts +25 -0
  231. package/dist/generated/storage/core/params.gen.d.ts +43 -0
  232. package/dist/generated/storage/core/pathSerializer.gen.d.ts +33 -0
  233. package/dist/generated/storage/core/queryKeySerializer.gen.d.ts +18 -0
  234. package/dist/generated/storage/core/serverSentEvents.gen.d.ts +71 -0
  235. package/dist/generated/storage/core/types.gen.d.ts +83 -0
  236. package/dist/generated/storage/core/utils.gen.d.ts +19 -0
  237. package/dist/generated/storage/index.d.ts +2 -0
  238. package/dist/generated/storage/index.js +6 -0
  239. package/dist/generated/storage/sdk.gen.d.ts +2285 -0
  240. package/dist/generated/storage/types.gen.d.ts +34546 -0
  241. package/dist/generated/unfurl/client/client.gen.d.ts +2 -0
  242. package/dist/generated/unfurl/client/index.d.ts +10 -0
  243. package/dist/generated/unfurl/client/types.gen.d.ts +120 -0
  244. package/dist/generated/unfurl/client/utils.gen.d.ts +37 -0
  245. package/dist/generated/unfurl/client.gen.d.ts +12 -0
  246. package/dist/generated/unfurl/core/auth.gen.d.ts +25 -0
  247. package/dist/generated/unfurl/core/bodySerializer.gen.d.ts +25 -0
  248. package/dist/generated/unfurl/core/params.gen.d.ts +43 -0
  249. package/dist/generated/unfurl/core/pathSerializer.gen.d.ts +33 -0
  250. package/dist/generated/unfurl/core/queryKeySerializer.gen.d.ts +18 -0
  251. package/dist/generated/unfurl/core/serverSentEvents.gen.d.ts +71 -0
  252. package/dist/generated/unfurl/core/types.gen.d.ts +83 -0
  253. package/dist/generated/unfurl/core/utils.gen.d.ts +19 -0
  254. package/dist/generated/unfurl/index.d.ts +2 -0
  255. package/dist/generated/unfurl/index.js +6 -0
  256. package/dist/generated/unfurl/sdk.gen.d.ts +47 -0
  257. package/dist/generated/unfurl/types.gen.d.ts +145 -0
  258. package/dist/src/calls/browser.d.ts +14 -0
  259. package/dist/src/calls/browser.js +102 -0
  260. package/dist/src/calls/common.d.ts +18 -0
  261. package/dist/src/calls/node.d.ts +24 -0
  262. package/dist/src/calls/node.js +145 -0
  263. package/dist/src/calls/telemetry.d.ts +5 -0
  264. package/dist/src/config.d.ts +71 -0
  265. package/dist/src/entities/account-managers/grant.d.ts +62 -0
  266. package/dist/src/entities/account-managers/namespace.d.ts +29 -0
  267. package/dist/src/entities/activity/entity.d.ts +7 -0
  268. package/dist/src/entities/activity/namespace.d.ts +58 -0
  269. package/dist/src/entities/activity/namespace.test.d.ts +1 -0
  270. package/dist/src/entities/agent-sessions/activity.d.ts +48 -0
  271. package/dist/src/entities/agent-sessions/agent-session.d.ts +518 -0
  272. package/dist/src/entities/agent-sessions/code-execution.d.ts +60 -0
  273. package/dist/src/entities/agent-sessions/conversation.d.ts +91 -0
  274. package/dist/src/entities/agent-sessions/namespace.d.ts +142 -0
  275. package/dist/src/entities/agent-sessions/origin.d.ts +94 -0
  276. package/dist/src/entities/agent-sessions/queued-action.d.ts +60 -0
  277. package/dist/src/entities/agent-sessions/review.d.ts +114 -0
  278. package/dist/src/entities/agent-sessions/tool-approval.d.ts +25 -0
  279. package/dist/src/entities/agent-sessions/view.d.ts +11 -0
  280. package/dist/src/entities/agents/agent.d.ts +142 -0
  281. package/dist/src/entities/agents/namespace.d.ts +66 -0
  282. package/dist/src/entities/ai/namespace.d.ts +36 -0
  283. package/dist/src/entities/api-keys/api-key.d.ts +22 -0
  284. package/dist/src/entities/api-keys/namespace.d.ts +37 -0
  285. package/dist/src/entities/bots/bot.d.ts +143 -0
  286. package/dist/src/entities/bots/namespace.d.ts +50 -0
  287. package/dist/src/entities/bots/token.d.ts +39 -0
  288. package/dist/src/entities/calendar/booking-link.d.ts +55 -0
  289. package/dist/src/entities/calendar/booking-namespace.d.ts +143 -0
  290. package/dist/src/entities/calendar/booking-namespace.test.d.ts +1 -0
  291. package/dist/src/entities/calendar/booking.d.ts +97 -0
  292. package/dist/src/entities/calendar/calendar.d.ts +49 -0
  293. package/dist/src/entities/calendar/create-confirmed.test.d.ts +1 -0
  294. package/dist/src/entities/calendar/event.d.ts +283 -0
  295. package/dist/src/entities/calendar/event.test.d.ts +1 -0
  296. package/dist/src/entities/calendar/namespace.d.ts +334 -0
  297. package/dist/src/entities/calendar/namespace.test.d.ts +1 -0
  298. package/dist/src/entities/calendar/replacement.d.ts +31 -0
  299. package/dist/src/entities/calls/call-record.d.ts +231 -0
  300. package/dist/src/entities/calls/connection.d.ts +59 -0
  301. package/dist/src/entities/calls/errors.d.ts +15 -0
  302. package/dist/src/entities/calls/message.d.ts +55 -0
  303. package/dist/src/entities/calls/namespace.d.ts +41 -0
  304. package/dist/src/entities/calls/participant.d.ts +22 -0
  305. package/dist/src/entities/canvases/canvas.d.ts +329 -0
  306. package/dist/src/entities/channels/access-request.d.ts +42 -0
  307. package/dist/src/entities/channels/activity.d.ts +40 -0
  308. package/dist/src/entities/channels/channel.d.ts +302 -0
  309. package/dist/src/entities/channels/labels.d.ts +73 -0
  310. package/dist/src/entities/channels/message.d.ts +153 -0
  311. package/dist/src/entities/channels/message.test.d.ts +1 -0
  312. package/dist/src/entities/channels/namespace.d.ts +82 -0
  313. package/dist/src/entities/channels/namespace.test.d.ts +1 -0
  314. package/dist/src/entities/channels/picture.d.ts +11 -0
  315. package/dist/src/entities/channels/post.d.ts +37 -0
  316. package/dist/src/entities/channels/post.test.d.ts +1 -0
  317. package/dist/src/entities/channels/share.d.ts +9 -0
  318. package/dist/src/entities/channels/share.test.d.ts +1 -0
  319. package/dist/src/entities/channels/thread.d.ts +64 -0
  320. package/dist/src/entities/chats/chat.d.ts +121 -0
  321. package/dist/src/entities/chats/generation.d.ts +55 -0
  322. package/dist/src/entities/chats/namespace.d.ts +35 -0
  323. package/dist/src/entities/connected-apps/connected-app.d.ts +121 -0
  324. package/dist/src/entities/connected-apps/connector.d.ts +59 -0
  325. package/dist/src/entities/connected-apps/namespace.d.ts +92 -0
  326. package/dist/src/entities/crm/company.d.ts +154 -0
  327. package/dist/src/entities/crm/contact.d.ts +168 -0
  328. package/dist/src/entities/crm/namespace.d.ts +163 -0
  329. package/dist/src/entities/crm/pipeline-entry.d.ts +109 -0
  330. package/dist/src/entities/crm/pipeline.d.ts +426 -0
  331. package/dist/src/entities/crm/pipelines.d.ts +79 -0
  332. package/dist/src/entities/crm-email-privacy/email-privacy.d.ts +238 -0
  333. package/dist/src/entities/crm-email-privacy/email-rule-preview.d.ts +55 -0
  334. package/dist/src/entities/crm-email-privacy/email-rule-revision.d.ts +27 -0
  335. package/dist/src/entities/crm-email-privacy/email-rules.d.ts +32 -0
  336. package/dist/src/entities/databases/column.d.ts +122 -0
  337. package/dist/src/entities/databases/database.d.ts +431 -0
  338. package/dist/src/entities/databases/namespace.d.ts +109 -0
  339. package/dist/src/entities/databases/query.d.ts +86 -0
  340. package/dist/src/entities/databases/row.d.ts +29 -0
  341. package/dist/src/entities/databases/saved-query.d.ts +151 -0
  342. package/dist/src/entities/databases/table.d.ts +124 -0
  343. package/dist/src/entities/databases/view.d.ts +72 -0
  344. package/dist/src/entities/databases/webhook.d.ts +39 -0
  345. package/dist/src/entities/documents/ai-edit.d.ts +54 -0
  346. package/dist/src/entities/documents/anchor.d.ts +39 -0
  347. package/dist/src/entities/documents/comment.d.ts +68 -0
  348. package/dist/src/entities/documents/create.test.d.ts +1 -0
  349. package/dist/src/entities/documents/document.d.ts +675 -0
  350. package/dist/src/entities/documents/markdown.d.ts +25 -0
  351. package/dist/src/entities/documents/namespace.d.ts +291 -0
  352. package/dist/src/entities/documents/office-files.d.ts +47 -0
  353. package/dist/src/entities/documents/skills.test.d.ts +1 -0
  354. package/dist/src/entities/documents/system-skill.d.ts +36 -0
  355. package/dist/src/entities/documents/text-comment.d.ts +41 -0
  356. package/dist/src/entities/documents/text-comment.test.d.ts +1 -0
  357. package/dist/src/entities/documents/version.d.ts +26 -0
  358. package/dist/src/entities/email/attachment.d.ts +39 -0
  359. package/dist/src/entities/email/body-rox-compat.d.ts +22 -0
  360. package/dist/src/entities/email/draft.d.ts +164 -0
  361. package/dist/src/entities/email/filter.d.ts +44 -0
  362. package/dist/src/entities/email/label.d.ts +37 -0
  363. package/dist/src/entities/email/link.d.ts +35 -0
  364. package/dist/src/entities/email/message.d.ts +223 -0
  365. package/dist/src/entities/email/namespace.d.ts +235 -0
  366. package/dist/src/entities/email/namespace.test.d.ts +1 -0
  367. package/dist/src/entities/email/thread.d.ts +268 -0
  368. package/dist/src/entities/entity-mentions/mention.d.ts +21 -0
  369. package/dist/src/entities/entity-mentions/namespace.d.ts +20 -0
  370. package/dist/src/entities/entity.d.ts +167 -0
  371. package/dist/src/entities/external-chat/chat.d.ts +173 -0
  372. package/dist/src/entities/external-chat/message.d.ts +54 -0
  373. package/dist/src/entities/external-chat/namespace.d.ts +22 -0
  374. package/dist/src/entities/external-chat/participant.d.ts +28 -0
  375. package/dist/src/entities/external-chat/send.d.ts +40 -0
  376. package/dist/src/entities/external-chat/upload.d.ts +25 -0
  377. package/dist/src/entities/favorites/namespace.d.ts +52 -0
  378. package/dist/src/entities/foreign/foreign-entity.d.ts +36 -0
  379. package/dist/src/entities/foreign/namespace.d.ts +54 -0
  380. package/dist/src/entities/forms/form.d.ts +319 -0
  381. package/dist/src/entities/forms/namespace.d.ts +30 -0
  382. package/dist/src/entities/forms/question.d.ts +65 -0
  383. package/dist/src/entities/forms/response.d.ts +52 -0
  384. package/dist/src/entities/forms/section.d.ts +31 -0
  385. package/dist/src/entities/github-pull-requests/namespace.d.ts +20 -0
  386. package/dist/src/entities/github-pull-requests/pull-request.d.ts +64 -0
  387. package/dist/src/entities/harnesses/harness.d.ts +76 -0
  388. package/dist/src/entities/harnesses/namespace.d.ts +83 -0
  389. package/dist/src/entities/harnesses/pairing.d.ts +50 -0
  390. package/dist/src/entities/images/image.d.ts +88 -0
  391. package/dist/src/entities/images/namespace.d.ts +55 -0
  392. package/dist/src/entities/images/namespace.test.d.ts +1 -0
  393. package/dist/src/entities/imports/entry.d.ts +65 -0
  394. package/dist/src/entities/imports/namespace.d.ts +103 -0
  395. package/dist/src/entities/imports/namespace.test.d.ts +1 -0
  396. package/dist/src/entities/initiatives/initiative.d.ts +185 -0
  397. package/dist/src/entities/initiatives/initiative.test.d.ts +1 -0
  398. package/dist/src/entities/initiatives/namespace.d.ts +90 -0
  399. package/dist/src/entities/me/namespace.d.ts +68 -0
  400. package/dist/src/entities/meetings/meeting.d.ts +81 -0
  401. package/dist/src/entities/meetings/namespace.d.ts +38 -0
  402. package/dist/src/entities/memory/namespace.d.ts +49 -0
  403. package/dist/src/entities/memory/namespace.test.d.ts +1 -0
  404. package/dist/src/entities/messages/discussion.d.ts +84 -0
  405. package/dist/src/entities/messages/thread.d.ts +115 -0
  406. package/dist/src/entities/notifications/namespace.d.ts +66 -0
  407. package/dist/src/entities/notifications/notification.d.ts +78 -0
  408. package/dist/src/entities/notifications/notification.test.d.ts +1 -0
  409. package/dist/src/entities/passwords/item.d.ts +118 -0
  410. package/dist/src/entities/passwords/namespace.d.ts +45 -0
  411. package/dist/src/entities/pins/namespace.d.ts +42 -0
  412. package/dist/src/entities/projects/namespace.d.ts +45 -0
  413. package/dist/src/entities/projects/project.d.ts +108 -0
  414. package/dist/src/entities/properties/namespace.d.ts +105 -0
  415. package/dist/src/entities/properties/namespace.test.d.ts +1 -0
  416. package/dist/src/entities/properties/property-definition.d.ts +70 -0
  417. package/dist/src/entities/properties/property-option.d.ts +44 -0
  418. package/dist/src/entities/reference.d.ts +82 -0
  419. package/dist/src/entities/referrals/namespace.d.ts +40 -0
  420. package/dist/src/entities/routines/namespace.d.ts +239 -0
  421. package/dist/src/entities/routines/routine.d.ts +341 -0
  422. package/dist/src/entities/routines/suggestion.d.ts +38 -0
  423. package/dist/src/entities/saved-views/namespace.d.ts +58 -0
  424. package/dist/src/entities/saved-views/saved-view.d.ts +78 -0
  425. package/dist/src/entities/search/exclusions.d.ts +6 -0
  426. package/dist/src/entities/search/namespace.d.ts +71 -0
  427. package/dist/src/entities/search/options.d.ts +30 -0
  428. package/dist/src/entities/search/types.d.ts +90 -0
  429. package/dist/src/entities/sharing/access.d.ts +120 -0
  430. package/dist/src/entities/sharing/permissions.d.ts +13 -0
  431. package/dist/src/entities/spreadsheets/spreadsheet.d.ts +201 -0
  432. package/dist/src/entities/suggestions/namespace.d.ts +118 -0
  433. package/dist/src/entities/suggestions/suggestion.d.ts +172 -0
  434. package/dist/src/entities/suggestions/suggestion.test.d.ts +1 -0
  435. package/dist/src/entities/tasks/namespace.d.ts +77 -0
  436. package/dist/src/entities/tasks/task.d.ts +99 -0
  437. package/dist/src/entities/teams/invite.d.ts +33 -0
  438. package/dist/src/entities/teams/namespace.d.ts +23 -0
  439. package/dist/src/entities/teams/team.d.ts +129 -0
  440. package/dist/src/entities/ui/app-link.d.ts +24 -0
  441. package/dist/src/entities/ui/namespace.d.ts +75 -0
  442. package/dist/src/entities/unfurls/namespace.d.ts +24 -0
  443. package/dist/src/entities/users/namespace.d.ts +41 -0
  444. package/dist/src/entities/users/profile-picture.d.ts +29 -0
  445. package/dist/src/entities/users/profile-picture.test.d.ts +1 -0
  446. package/dist/src/entities/users/user.d.ts +102 -0
  447. package/dist/src/entities/web/namespace.d.ts +67 -0
  448. package/dist/src/entities/web/namespace.test.d.ts +1 -0
  449. package/dist/src/entities/webhooks/namespace.d.ts +38 -0
  450. package/dist/src/entities/webhooks/webhook.d.ts +130 -0
  451. package/dist/src/entities/whatsapp/account.d.ts +24 -0
  452. package/dist/src/entities/whatsapp/chat.d.ts +62 -0
  453. package/dist/src/entities/whatsapp/namespace.d.ts +29 -0
  454. package/dist/src/entities/workspace/items.d.ts +14 -0
  455. package/dist/src/entities/workspace/namespace.d.ts +96 -0
  456. package/dist/src/entities/workspace/query.d.ts +39 -0
  457. package/dist/src/entities/workspace/query.test.d.ts +1 -0
  458. package/dist/src/entities/workspace/types.d.ts +99 -0
  459. package/dist/src/events/hydrate/agentSession.d.ts +192 -0
  460. package/dist/src/events/hydrate/call.d.ts +101 -0
  461. package/dist/src/events/hydrate/channel.d.ts +55 -0
  462. package/dist/src/events/hydrate/document.d.ts +59 -0
  463. package/dist/src/events/hydrate/message.d.ts +70 -0
  464. package/dist/src/events/hydrate/user.d.ts +14 -0
  465. package/dist/src/events/receiver.d.ts +91 -0
  466. package/dist/src/events/types.d.ts +44 -0
  467. package/dist/src/events/verify.d.ts +13 -0
  468. package/dist/src/local-portmap.d.ts +8 -0
  469. package/dist/src/mentions.d.ts +42 -0
  470. package/dist/src/raw.d.ts +12 -0
  471. package/dist/src/rox.d.ts +268 -0
  472. package/dist/src/rox.js +23231 -0
  473. package/dist/src/utils/activity.d.ts +34 -0
  474. package/dist/src/utils/activity.test.d.ts +1 -0
  475. package/dist/src/utils/client.d.ts +62 -0
  476. package/dist/src/utils/concurrency.d.ts +5 -0
  477. package/dist/src/utils/index.d.ts +5 -0
  478. package/dist/src/utils/lazy.d.ts +37 -0
  479. package/dist/src/utils/options.d.ts +7 -0
  480. package/dist/src/utils/pagination.d.ts +28 -0
  481. package/dist/src/utils/unwrap.d.ts +48 -0
  482. package/dist/src/utils/verbs.d.ts +3 -0
  483. package/package.json +82 -4
package/README.md CHANGED
@@ -1,3 +1,1260 @@
1
- # Temporary Holding Version
1
+ Rox's SDK: a Typescript library for harnessing the power of Rox
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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.