@macro-inc/sdk 0.0.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 (296) hide show
  1. package/README.md +177 -0
  2. package/dist/chunk-5HAKQN23.js +1263 -0
  3. package/dist/chunk-77EI4LSQ.js +2492 -0
  4. package/dist/chunk-CTKR64MY.js +1436 -0
  5. package/dist/chunk-JXIQT5TH.js +1467 -0
  6. package/dist/chunk-P4DTO6VD.js +830 -0
  7. package/dist/chunk-PAAFJYGO.js +967 -0
  8. package/dist/chunk-QNUS5BC5.js +913 -0
  9. package/dist/chunk-SGAHIERJ.js +1235 -0
  10. package/dist/chunk-V45LUJDI.js +838 -0
  11. package/dist/chunk-YRUXFEZM.js +1044 -0
  12. package/dist/generated/agent-harness/client/client.gen.d.ts +2 -0
  13. package/dist/generated/agent-harness/client/index.d.ts +10 -0
  14. package/dist/generated/agent-harness/client/types.gen.d.ts +120 -0
  15. package/dist/generated/agent-harness/client/utils.gen.d.ts +37 -0
  16. package/dist/generated/agent-harness/client.gen.d.ts +12 -0
  17. package/dist/generated/agent-harness/core/auth.gen.d.ts +25 -0
  18. package/dist/generated/agent-harness/core/bodySerializer.gen.d.ts +25 -0
  19. package/dist/generated/agent-harness/core/params.gen.d.ts +43 -0
  20. package/dist/generated/agent-harness/core/pathSerializer.gen.d.ts +33 -0
  21. package/dist/generated/agent-harness/core/queryKeySerializer.gen.d.ts +18 -0
  22. package/dist/generated/agent-harness/core/serverSentEvents.gen.d.ts +71 -0
  23. package/dist/generated/agent-harness/core/types.gen.d.ts +83 -0
  24. package/dist/generated/agent-harness/core/utils.gen.d.ts +19 -0
  25. package/dist/generated/agent-harness/index.d.ts +2 -0
  26. package/dist/generated/agent-harness/index.js +6 -0
  27. package/dist/generated/agent-harness/sdk.gen.d.ts +84 -0
  28. package/dist/generated/agent-harness/types.gen.d.ts +539 -0
  29. package/dist/generated/auth/client/client.gen.d.ts +2 -0
  30. package/dist/generated/auth/client/index.d.ts +10 -0
  31. package/dist/generated/auth/client/types.gen.d.ts +120 -0
  32. package/dist/generated/auth/client/utils.gen.d.ts +37 -0
  33. package/dist/generated/auth/client.gen.d.ts +12 -0
  34. package/dist/generated/auth/core/auth.gen.d.ts +25 -0
  35. package/dist/generated/auth/core/bodySerializer.gen.d.ts +25 -0
  36. package/dist/generated/auth/core/params.gen.d.ts +43 -0
  37. package/dist/generated/auth/core/pathSerializer.gen.d.ts +33 -0
  38. package/dist/generated/auth/core/queryKeySerializer.gen.d.ts +18 -0
  39. package/dist/generated/auth/core/serverSentEvents.gen.d.ts +71 -0
  40. package/dist/generated/auth/core/types.gen.d.ts +83 -0
  41. package/dist/generated/auth/core/utils.gen.d.ts +19 -0
  42. package/dist/generated/auth/index.d.ts +2 -0
  43. package/dist/generated/auth/index.js +6 -0
  44. package/dist/generated/auth/sdk.gen.d.ts +383 -0
  45. package/dist/generated/auth/types.gen.d.ts +2175 -0
  46. package/dist/generated/cognition/client/client.gen.d.ts +2 -0
  47. package/dist/generated/cognition/client/index.d.ts +10 -0
  48. package/dist/generated/cognition/client/types.gen.d.ts +120 -0
  49. package/dist/generated/cognition/client/utils.gen.d.ts +37 -0
  50. package/dist/generated/cognition/client.gen.d.ts +12 -0
  51. package/dist/generated/cognition/core/auth.gen.d.ts +25 -0
  52. package/dist/generated/cognition/core/bodySerializer.gen.d.ts +25 -0
  53. package/dist/generated/cognition/core/params.gen.d.ts +43 -0
  54. package/dist/generated/cognition/core/pathSerializer.gen.d.ts +33 -0
  55. package/dist/generated/cognition/core/queryKeySerializer.gen.d.ts +18 -0
  56. package/dist/generated/cognition/core/serverSentEvents.gen.d.ts +71 -0
  57. package/dist/generated/cognition/core/types.gen.d.ts +83 -0
  58. package/dist/generated/cognition/core/utils.gen.d.ts +19 -0
  59. package/dist/generated/cognition/index.d.ts +2 -0
  60. package/dist/generated/cognition/index.js +6 -0
  61. package/dist/generated/cognition/sdk.gen.d.ts +224 -0
  62. package/dist/generated/cognition/types.gen.d.ts +2484 -0
  63. package/dist/generated/connection/client/client.gen.d.ts +2 -0
  64. package/dist/generated/connection/client/index.d.ts +10 -0
  65. package/dist/generated/connection/client/types.gen.d.ts +120 -0
  66. package/dist/generated/connection/client/utils.gen.d.ts +37 -0
  67. package/dist/generated/connection/client.gen.d.ts +12 -0
  68. package/dist/generated/connection/core/auth.gen.d.ts +25 -0
  69. package/dist/generated/connection/core/bodySerializer.gen.d.ts +25 -0
  70. package/dist/generated/connection/core/params.gen.d.ts +43 -0
  71. package/dist/generated/connection/core/pathSerializer.gen.d.ts +33 -0
  72. package/dist/generated/connection/core/queryKeySerializer.gen.d.ts +18 -0
  73. package/dist/generated/connection/core/serverSentEvents.gen.d.ts +71 -0
  74. package/dist/generated/connection/core/types.gen.d.ts +83 -0
  75. package/dist/generated/connection/core/utils.gen.d.ts +19 -0
  76. package/dist/generated/connection/index.d.ts +2 -0
  77. package/dist/generated/connection/index.js +839 -0
  78. package/dist/generated/connection/sdk.gen.d.ts +38 -0
  79. package/dist/generated/connection/types.gen.d.ts +235 -0
  80. package/dist/generated/contacts/client/client.gen.d.ts +2 -0
  81. package/dist/generated/contacts/client/index.d.ts +10 -0
  82. package/dist/generated/contacts/client/types.gen.d.ts +120 -0
  83. package/dist/generated/contacts/client/utils.gen.d.ts +37 -0
  84. package/dist/generated/contacts/client.gen.d.ts +12 -0
  85. package/dist/generated/contacts/core/auth.gen.d.ts +25 -0
  86. package/dist/generated/contacts/core/bodySerializer.gen.d.ts +25 -0
  87. package/dist/generated/contacts/core/params.gen.d.ts +43 -0
  88. package/dist/generated/contacts/core/pathSerializer.gen.d.ts +33 -0
  89. package/dist/generated/contacts/core/queryKeySerializer.gen.d.ts +18 -0
  90. package/dist/generated/contacts/core/serverSentEvents.gen.d.ts +71 -0
  91. package/dist/generated/contacts/core/types.gen.d.ts +83 -0
  92. package/dist/generated/contacts/core/utils.gen.d.ts +19 -0
  93. package/dist/generated/contacts/index.d.ts +2 -0
  94. package/dist/generated/contacts/index.js +6 -0
  95. package/dist/generated/contacts/sdk.gen.d.ts +43 -0
  96. package/dist/generated/contacts/types.gen.d.ts +52 -0
  97. package/dist/generated/email/client/client.gen.d.ts +2 -0
  98. package/dist/generated/email/client/index.d.ts +10 -0
  99. package/dist/generated/email/client/types.gen.d.ts +120 -0
  100. package/dist/generated/email/client/utils.gen.d.ts +37 -0
  101. package/dist/generated/email/client.gen.d.ts +12 -0
  102. package/dist/generated/email/core/auth.gen.d.ts +25 -0
  103. package/dist/generated/email/core/bodySerializer.gen.d.ts +25 -0
  104. package/dist/generated/email/core/params.gen.d.ts +43 -0
  105. package/dist/generated/email/core/pathSerializer.gen.d.ts +33 -0
  106. package/dist/generated/email/core/queryKeySerializer.gen.d.ts +18 -0
  107. package/dist/generated/email/core/serverSentEvents.gen.d.ts +71 -0
  108. package/dist/generated/email/core/types.gen.d.ts +83 -0
  109. package/dist/generated/email/core/utils.gen.d.ts +19 -0
  110. package/dist/generated/email/index.d.ts +2 -0
  111. package/dist/generated/email/index.js +6 -0
  112. package/dist/generated/email/sdk.gen.d.ts +254 -0
  113. package/dist/generated/email/types.gen.d.ts +2614 -0
  114. package/dist/generated/notification/client/client.gen.d.ts +2 -0
  115. package/dist/generated/notification/client/index.d.ts +10 -0
  116. package/dist/generated/notification/client/types.gen.d.ts +120 -0
  117. package/dist/generated/notification/client/utils.gen.d.ts +37 -0
  118. package/dist/generated/notification/client.gen.d.ts +12 -0
  119. package/dist/generated/notification/core/auth.gen.d.ts +25 -0
  120. package/dist/generated/notification/core/bodySerializer.gen.d.ts +25 -0
  121. package/dist/generated/notification/core/params.gen.d.ts +43 -0
  122. package/dist/generated/notification/core/pathSerializer.gen.d.ts +33 -0
  123. package/dist/generated/notification/core/queryKeySerializer.gen.d.ts +18 -0
  124. package/dist/generated/notification/core/serverSentEvents.gen.d.ts +71 -0
  125. package/dist/generated/notification/core/types.gen.d.ts +83 -0
  126. package/dist/generated/notification/core/utils.gen.d.ts +19 -0
  127. package/dist/generated/notification/index.d.ts +2 -0
  128. package/dist/generated/notification/index.js +6 -0
  129. package/dist/generated/notification/sdk.gen.d.ts +118 -0
  130. package/dist/generated/notification/types.gen.d.ts +1352 -0
  131. package/dist/generated/properties/client/client.gen.d.ts +2 -0
  132. package/dist/generated/properties/client/index.d.ts +10 -0
  133. package/dist/generated/properties/client/types.gen.d.ts +120 -0
  134. package/dist/generated/properties/client/utils.gen.d.ts +37 -0
  135. package/dist/generated/properties/client.gen.d.ts +12 -0
  136. package/dist/generated/properties/core/auth.gen.d.ts +25 -0
  137. package/dist/generated/properties/core/bodySerializer.gen.d.ts +25 -0
  138. package/dist/generated/properties/core/params.gen.d.ts +43 -0
  139. package/dist/generated/properties/core/pathSerializer.gen.d.ts +33 -0
  140. package/dist/generated/properties/core/queryKeySerializer.gen.d.ts +18 -0
  141. package/dist/generated/properties/core/serverSentEvents.gen.d.ts +71 -0
  142. package/dist/generated/properties/core/types.gen.d.ts +83 -0
  143. package/dist/generated/properties/core/utils.gen.d.ts +19 -0
  144. package/dist/generated/properties/index.d.ts +2 -0
  145. package/dist/generated/properties/index.js +6 -0
  146. package/dist/generated/properties/sdk.gen.d.ts +158 -0
  147. package/dist/generated/properties/types.gen.d.ts +1288 -0
  148. package/dist/generated/scheduled-action/client/client.gen.d.ts +2 -0
  149. package/dist/generated/scheduled-action/client/index.d.ts +10 -0
  150. package/dist/generated/scheduled-action/client/types.gen.d.ts +120 -0
  151. package/dist/generated/scheduled-action/client/utils.gen.d.ts +37 -0
  152. package/dist/generated/scheduled-action/client.gen.d.ts +12 -0
  153. package/dist/generated/scheduled-action/core/auth.gen.d.ts +25 -0
  154. package/dist/generated/scheduled-action/core/bodySerializer.gen.d.ts +25 -0
  155. package/dist/generated/scheduled-action/core/params.gen.d.ts +43 -0
  156. package/dist/generated/scheduled-action/core/pathSerializer.gen.d.ts +33 -0
  157. package/dist/generated/scheduled-action/core/queryKeySerializer.gen.d.ts +18 -0
  158. package/dist/generated/scheduled-action/core/serverSentEvents.gen.d.ts +71 -0
  159. package/dist/generated/scheduled-action/core/types.gen.d.ts +83 -0
  160. package/dist/generated/scheduled-action/core/utils.gen.d.ts +19 -0
  161. package/dist/generated/scheduled-action/index.d.ts +2 -0
  162. package/dist/generated/scheduled-action/index.js +845 -0
  163. package/dist/generated/scheduled-action/sdk.gen.d.ts +42 -0
  164. package/dist/generated/scheduled-action/types.gen.d.ts +241 -0
  165. package/dist/generated/search/client/client.gen.d.ts +2 -0
  166. package/dist/generated/search/client/index.d.ts +10 -0
  167. package/dist/generated/search/client/types.gen.d.ts +120 -0
  168. package/dist/generated/search/client/utils.gen.d.ts +37 -0
  169. package/dist/generated/search/client.gen.d.ts +12 -0
  170. package/dist/generated/search/core/auth.gen.d.ts +25 -0
  171. package/dist/generated/search/core/bodySerializer.gen.d.ts +25 -0
  172. package/dist/generated/search/core/params.gen.d.ts +43 -0
  173. package/dist/generated/search/core/pathSerializer.gen.d.ts +33 -0
  174. package/dist/generated/search/core/queryKeySerializer.gen.d.ts +18 -0
  175. package/dist/generated/search/core/serverSentEvents.gen.d.ts +71 -0
  176. package/dist/generated/search/core/types.gen.d.ts +83 -0
  177. package/dist/generated/search/core/utils.gen.d.ts +19 -0
  178. package/dist/generated/search/index.d.ts +2 -0
  179. package/dist/generated/search/index.js +6 -0
  180. package/dist/generated/search/sdk.gen.d.ts +44 -0
  181. package/dist/generated/search/types.gen.d.ts +2194 -0
  182. package/dist/generated/static-files/client/client.gen.d.ts +2 -0
  183. package/dist/generated/static-files/client/index.d.ts +10 -0
  184. package/dist/generated/static-files/client/types.gen.d.ts +120 -0
  185. package/dist/generated/static-files/client/utils.gen.d.ts +37 -0
  186. package/dist/generated/static-files/client.gen.d.ts +12 -0
  187. package/dist/generated/static-files/core/auth.gen.d.ts +25 -0
  188. package/dist/generated/static-files/core/bodySerializer.gen.d.ts +25 -0
  189. package/dist/generated/static-files/core/params.gen.d.ts +43 -0
  190. package/dist/generated/static-files/core/pathSerializer.gen.d.ts +33 -0
  191. package/dist/generated/static-files/core/queryKeySerializer.gen.d.ts +18 -0
  192. package/dist/generated/static-files/core/serverSentEvents.gen.d.ts +71 -0
  193. package/dist/generated/static-files/core/types.gen.d.ts +83 -0
  194. package/dist/generated/static-files/core/utils.gen.d.ts +19 -0
  195. package/dist/generated/static-files/index.d.ts +2 -0
  196. package/dist/generated/static-files/index.js +842 -0
  197. package/dist/generated/static-files/sdk.gen.d.ts +43 -0
  198. package/dist/generated/static-files/types.gen.d.ts +214 -0
  199. package/dist/generated/storage/client/client.gen.d.ts +2 -0
  200. package/dist/generated/storage/client/index.d.ts +10 -0
  201. package/dist/generated/storage/client/types.gen.d.ts +120 -0
  202. package/dist/generated/storage/client/utils.gen.d.ts +37 -0
  203. package/dist/generated/storage/client.gen.d.ts +12 -0
  204. package/dist/generated/storage/core/auth.gen.d.ts +25 -0
  205. package/dist/generated/storage/core/bodySerializer.gen.d.ts +25 -0
  206. package/dist/generated/storage/core/params.gen.d.ts +43 -0
  207. package/dist/generated/storage/core/pathSerializer.gen.d.ts +33 -0
  208. package/dist/generated/storage/core/queryKeySerializer.gen.d.ts +18 -0
  209. package/dist/generated/storage/core/serverSentEvents.gen.d.ts +71 -0
  210. package/dist/generated/storage/core/types.gen.d.ts +83 -0
  211. package/dist/generated/storage/core/utils.gen.d.ts +19 -0
  212. package/dist/generated/storage/index.d.ts +2 -0
  213. package/dist/generated/storage/index.js +6 -0
  214. package/dist/generated/storage/sdk.gen.d.ts +858 -0
  215. package/dist/generated/storage/types.gen.d.ts +12105 -0
  216. package/dist/generated/unfurl/client/client.gen.d.ts +2 -0
  217. package/dist/generated/unfurl/client/index.d.ts +10 -0
  218. package/dist/generated/unfurl/client/types.gen.d.ts +120 -0
  219. package/dist/generated/unfurl/client/utils.gen.d.ts +37 -0
  220. package/dist/generated/unfurl/client.gen.d.ts +12 -0
  221. package/dist/generated/unfurl/core/auth.gen.d.ts +25 -0
  222. package/dist/generated/unfurl/core/bodySerializer.gen.d.ts +25 -0
  223. package/dist/generated/unfurl/core/params.gen.d.ts +43 -0
  224. package/dist/generated/unfurl/core/pathSerializer.gen.d.ts +33 -0
  225. package/dist/generated/unfurl/core/queryKeySerializer.gen.d.ts +18 -0
  226. package/dist/generated/unfurl/core/serverSentEvents.gen.d.ts +71 -0
  227. package/dist/generated/unfurl/core/types.gen.d.ts +83 -0
  228. package/dist/generated/unfurl/core/utils.gen.d.ts +19 -0
  229. package/dist/generated/unfurl/index.d.ts +2 -0
  230. package/dist/generated/unfurl/index.js +835 -0
  231. package/dist/generated/unfurl/sdk.gen.d.ts +47 -0
  232. package/dist/generated/unfurl/types.gen.d.ts +125 -0
  233. package/dist/src/config.d.ts +51 -0
  234. package/dist/src/entities/agent-sessions/agent-session.d.ts +45 -0
  235. package/dist/src/entities/agent-sessions/namespace.d.ts +18 -0
  236. package/dist/src/entities/bots/namespace.d.ts +25 -0
  237. package/dist/src/entities/calls/call-record.d.ts +55 -0
  238. package/dist/src/entities/calls/namespace.d.ts +9 -0
  239. package/dist/src/entities/channels/channel.d.ts +88 -0
  240. package/dist/src/entities/channels/message.d.ts +64 -0
  241. package/dist/src/entities/channels/namespace.d.ts +30 -0
  242. package/dist/src/entities/channels/post.d.ts +20 -0
  243. package/dist/src/entities/channels/thread.d.ts +30 -0
  244. package/dist/src/entities/chats/chat.d.ts +55 -0
  245. package/dist/src/entities/chats/namespace.d.ts +14 -0
  246. package/dist/src/entities/crm/comment.d.ts +43 -0
  247. package/dist/src/entities/crm/company.d.ts +70 -0
  248. package/dist/src/entities/crm/contact.d.ts +48 -0
  249. package/dist/src/entities/crm/namespace.d.ts +22 -0
  250. package/dist/src/entities/documents/comment.d.ts +41 -0
  251. package/dist/src/entities/documents/document.d.ts +130 -0
  252. package/dist/src/entities/documents/namespace.d.ts +43 -0
  253. package/dist/src/entities/documents/system-skill.d.ts +16 -0
  254. package/dist/src/entities/email/attachment.d.ts +36 -0
  255. package/dist/src/entities/email/label.d.ts +31 -0
  256. package/dist/src/entities/email/link.d.ts +29 -0
  257. package/dist/src/entities/email/message.d.ts +58 -0
  258. package/dist/src/entities/email/namespace.d.ts +49 -0
  259. package/dist/src/entities/email/thread.d.ts +88 -0
  260. package/dist/src/entities/entity.d.ts +101 -0
  261. package/dist/src/entities/favorites/namespace.d.ts +19 -0
  262. package/dist/src/entities/foreign/foreign-entity.d.ts +30 -0
  263. package/dist/src/entities/foreign/namespace.d.ts +7 -0
  264. package/dist/src/entities/notifications/namespace.d.ts +29 -0
  265. package/dist/src/entities/notifications/notification.d.ts +50 -0
  266. package/dist/src/entities/pins/namespace.d.ts +19 -0
  267. package/dist/src/entities/projects/namespace.d.ts +13 -0
  268. package/dist/src/entities/projects/project.d.ts +42 -0
  269. package/dist/src/entities/properties/namespace.d.ts +47 -0
  270. package/dist/src/entities/properties/property-definition.d.ts +45 -0
  271. package/dist/src/entities/properties/property-option.d.ts +32 -0
  272. package/dist/src/entities/search.d.ts +23 -0
  273. package/dist/src/entities/tasks/namespace.d.ts +21 -0
  274. package/dist/src/entities/tasks/task.d.ts +34 -0
  275. package/dist/src/entities/teams/namespace.d.ts +12 -0
  276. package/dist/src/entities/teams/team.d.ts +40 -0
  277. package/dist/src/entities/users/namespace.d.ts +10 -0
  278. package/dist/src/entities/users/user.d.ts +43 -0
  279. package/dist/src/entities/webhooks/namespace.d.ts +31 -0
  280. package/dist/src/entities/webhooks/webhook.d.ts +88 -0
  281. package/dist/src/events/hydrate/channel.d.ts +85 -0
  282. package/dist/src/events/hydrate/document.d.ts +54 -0
  283. package/dist/src/events/receiver.d.ts +51 -0
  284. package/dist/src/events/types.d.ts +40 -0
  285. package/dist/src/events/verify.d.ts +13 -0
  286. package/dist/src/local-portmap.d.ts +8 -0
  287. package/dist/src/macro.d.ts +62 -0
  288. package/dist/src/macro.js +4215 -0
  289. package/dist/src/mentions.d.ts +37 -0
  290. package/dist/src/raw.d.ts +12 -0
  291. package/dist/src/utils/client.d.ts +53 -0
  292. package/dist/src/utils/index.d.ts +4 -0
  293. package/dist/src/utils/lazy.d.ts +18 -0
  294. package/dist/src/utils/pagination.d.ts +7 -0
  295. package/dist/src/utils/unwrap.d.ts +23 -0
  296. package/package.json +49 -0
package/README.md ADDED
@@ -0,0 +1,177 @@
1
+ Macro's SDK: a Typescript library for harnessing the power of Macro
2
+
3
+ - **`generated/`**: generated Typescript types and a HeyAPI client from Macro's
4
+ OpenAPI specs.
5
+ - **`src/`**: a hand-written ergonomic SDK layer that provides an "orm"-y API.
6
+
7
+ ## Usage
8
+
9
+ ### Getting started
10
+
11
+ To get started, make a Macro client
12
+
13
+ ```ts
14
+ import { Macro } from '@macro-inc/sdk';
15
+
16
+ const macro = new Macro({ }); // uses MACRO_API_KEY env var
17
+ ```
18
+
19
+ ### Authenticating
20
+
21
+ The SDK can authenticate as a **user** (a Macro API token, sent as an
22
+ `Authorization` bearer) or as a **bot** (an `mbot_` API key, created under
23
+ Settings → Bots in the web app). With no explicit `auth`, the SDK falls back
24
+ to the `MACRO_API_KEY` (user) or `MACRO_BOT_TOKEN` (bot) env var.
25
+
26
+ ```ts
27
+ const asUser = new Macro({ auth: { type: 'user', token: myApiToken } });
28
+ const asBot = new Macro({ auth: { type: 'bot', token: myBotKey } });
29
+ ```
30
+
31
+ A bot can act on behalf of a user it's authorized for (its owner, or a member
32
+ of its owning team):
33
+
34
+ ```ts
35
+ const asWolf = asBot.requestedAs('macro|wolf@macro.com');
36
+ ```
37
+
38
+ Bot requests carry an access scope: `user` (the requested-as user's access —
39
+ the default whenever `requestedAs` is used) or `team` (the owning team's
40
+ access, for team-owned bots — the default otherwise). Pass
41
+ `auth: { type: 'bot', token, scope: ... }` to override.
42
+
43
+ ### Accessing our API
44
+
45
+ Our SDK acts lets you easily access any Macro "resource":
46
+
47
+ ```ts
48
+ const doc = macro.documents.byId('doc_123');
49
+ const name = await doc.name();
50
+ ```
51
+
52
+ ```ts
53
+ const owner = await doc.owner();
54
+ const email = await owner.email();
55
+ ```
56
+
57
+ ### Creating, mutating, and deleting
58
+
59
+ ```ts
60
+ const doc = await macro.documents.create({
61
+ name: 'Weekly update',
62
+ markdown: '# Week 32\n\n- shipped the thing',
63
+ });
64
+
65
+ await doc.rename('Weekly update (final)');
66
+ await doc.setTeamShare(true);
67
+ await doc.delete(); // soft delete; doc.restore() brings it back
68
+ ```
69
+
70
+ ### Listing and searching
71
+
72
+ List/search methods that can page return a genreator that auto-paginates:
73
+ iterate with `for await`, and `break` early to stop fetching:
74
+
75
+ ```ts
76
+ for await (const doc of macro.documents.recent()) {
77
+ console.log(await doc.name());
78
+ }
79
+
80
+ for await (const hit of macro.documents.search('quarterly revenue')) {
81
+ console.log(hit.webUrl());
82
+ }
83
+ ```
84
+
85
+ You can request all with `Array.fromAsync(...)`:
86
+
87
+ ```ts
88
+ const allDocs = await Array.fromAsync(macro.documents.recent());
89
+ ```
90
+
91
+ ### Properties and favorites
92
+
93
+ Most entities carry user-defined properties and can be favorited:
94
+
95
+ ```ts
96
+ await doc.favorite();
97
+ await doc.setProperty(macro.properties.byId('prop_status'), {
98
+ text: 'In review',
99
+ });
100
+ const props = await doc.properties();
101
+ ```
102
+
103
+ ### Rich message helper
104
+
105
+ Use the `msg` tagged template to build rich message bodies for channel messages
106
+ or documents.
107
+
108
+ ```ts
109
+ import { msg, here } from '@macro-inc/sdk';
110
+
111
+ const channel = macro.channels.byId('chan_1');
112
+ const user = macro.users.byId('user_1');
113
+ await channel.send(msg`Hey ${user}, take a look at ${doc}. cc ${here}`);
114
+ ```
115
+
116
+ These will render as @mentions in the Macro UI.
117
+
118
+ ### Posting to a channel webhook
119
+
120
+ The web UI can hand you a webhook URL and token for a channel. That token is a
121
+ bot token, so it goes in the normal place:
122
+
123
+ ```ts
124
+ const macro = new Macro({
125
+ auth: { type: 'bot', token: process.env.MACRO_WEBHOOK_TOKEN },
126
+ });
127
+
128
+ await macro.channels
129
+ .byId(channelId)
130
+ .send(msg`Deploy ${sha} finished. ${here}`);
131
+ ```
132
+
133
+ # Webhook Events
134
+
135
+ Pass a `webhookSecret` (or set `MACRO_WEBHOOK_SECRET`) to receive events. You
136
+ should use a framework like Hono or Express to handle the webhook request and
137
+ pass it to the SDK which will handle verification and dispatching.
138
+
139
+ ```ts
140
+ const macro = new Macro({
141
+ token: process.env.MACRO_API_KEY,
142
+ webhookSecret: process.env.MACRO_WEBHOOK_SECRET,
143
+ });
144
+
145
+ const me = await macro.users.me();
146
+
147
+ macro.events.on('channel.message_posted', async ({ metadata, message }) => {
148
+ if (metadata.sender === me.id) return; // don't reply to ourselves
149
+ await message.reply('hi!');
150
+ });
151
+
152
+ // Hono
153
+ app.post('/webhook', (c) => macro.events.webhook()(c.req.raw));
154
+ ```
155
+
156
+ # Developing
157
+
158
+ This section is just if you are contributing to the SDK.
159
+
160
+ ## Coverage checking
161
+
162
+ We have a coverage checker. It reads every generated function and ensures that
163
+ every client function that is generated is called by some hand-written function
164
+ in `src/`. If a generated function is not called, the coverage checker will fail
165
+ the build.
166
+
167
+ You can add exceptions for stuff OpenAPI covers that we don't want the sdk to
168
+ support by adding them to the `src/coverage/skipped.ts`. You can implement
169
+ support by adding a wrapper to the appropriate model. There is CI to ensure that
170
+ we don't forget to add coverage or explicitly skip coverage for new generated
171
+ functions (endpoints).
172
+
173
+ ## Webhook events
174
+
175
+ Event names and payloads are **generated from the backend**: the Rust webhook
176
+ crate exposes a `WebhookEvent` union in the storage OpenAPI spec, and
177
+ `src/events/types.ts` derives `EventName` / `EventPayload` from it.