@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.
- package/README.md +177 -0
- package/dist/chunk-5HAKQN23.js +1263 -0
- package/dist/chunk-77EI4LSQ.js +2492 -0
- package/dist/chunk-CTKR64MY.js +1436 -0
- package/dist/chunk-JXIQT5TH.js +1467 -0
- package/dist/chunk-P4DTO6VD.js +830 -0
- package/dist/chunk-PAAFJYGO.js +967 -0
- package/dist/chunk-QNUS5BC5.js +913 -0
- package/dist/chunk-SGAHIERJ.js +1235 -0
- package/dist/chunk-V45LUJDI.js +838 -0
- package/dist/chunk-YRUXFEZM.js +1044 -0
- package/dist/generated/agent-harness/client/client.gen.d.ts +2 -0
- package/dist/generated/agent-harness/client/index.d.ts +10 -0
- package/dist/generated/agent-harness/client/types.gen.d.ts +120 -0
- package/dist/generated/agent-harness/client/utils.gen.d.ts +37 -0
- package/dist/generated/agent-harness/client.gen.d.ts +12 -0
- package/dist/generated/agent-harness/core/auth.gen.d.ts +25 -0
- package/dist/generated/agent-harness/core/bodySerializer.gen.d.ts +25 -0
- package/dist/generated/agent-harness/core/params.gen.d.ts +43 -0
- package/dist/generated/agent-harness/core/pathSerializer.gen.d.ts +33 -0
- package/dist/generated/agent-harness/core/queryKeySerializer.gen.d.ts +18 -0
- package/dist/generated/agent-harness/core/serverSentEvents.gen.d.ts +71 -0
- package/dist/generated/agent-harness/core/types.gen.d.ts +83 -0
- package/dist/generated/agent-harness/core/utils.gen.d.ts +19 -0
- package/dist/generated/agent-harness/index.d.ts +2 -0
- package/dist/generated/agent-harness/index.js +6 -0
- package/dist/generated/agent-harness/sdk.gen.d.ts +84 -0
- package/dist/generated/agent-harness/types.gen.d.ts +539 -0
- package/dist/generated/auth/client/client.gen.d.ts +2 -0
- package/dist/generated/auth/client/index.d.ts +10 -0
- package/dist/generated/auth/client/types.gen.d.ts +120 -0
- package/dist/generated/auth/client/utils.gen.d.ts +37 -0
- package/dist/generated/auth/client.gen.d.ts +12 -0
- package/dist/generated/auth/core/auth.gen.d.ts +25 -0
- package/dist/generated/auth/core/bodySerializer.gen.d.ts +25 -0
- package/dist/generated/auth/core/params.gen.d.ts +43 -0
- package/dist/generated/auth/core/pathSerializer.gen.d.ts +33 -0
- package/dist/generated/auth/core/queryKeySerializer.gen.d.ts +18 -0
- package/dist/generated/auth/core/serverSentEvents.gen.d.ts +71 -0
- package/dist/generated/auth/core/types.gen.d.ts +83 -0
- package/dist/generated/auth/core/utils.gen.d.ts +19 -0
- package/dist/generated/auth/index.d.ts +2 -0
- package/dist/generated/auth/index.js +6 -0
- package/dist/generated/auth/sdk.gen.d.ts +383 -0
- package/dist/generated/auth/types.gen.d.ts +2175 -0
- package/dist/generated/cognition/client/client.gen.d.ts +2 -0
- package/dist/generated/cognition/client/index.d.ts +10 -0
- package/dist/generated/cognition/client/types.gen.d.ts +120 -0
- package/dist/generated/cognition/client/utils.gen.d.ts +37 -0
- package/dist/generated/cognition/client.gen.d.ts +12 -0
- package/dist/generated/cognition/core/auth.gen.d.ts +25 -0
- package/dist/generated/cognition/core/bodySerializer.gen.d.ts +25 -0
- package/dist/generated/cognition/core/params.gen.d.ts +43 -0
- package/dist/generated/cognition/core/pathSerializer.gen.d.ts +33 -0
- package/dist/generated/cognition/core/queryKeySerializer.gen.d.ts +18 -0
- package/dist/generated/cognition/core/serverSentEvents.gen.d.ts +71 -0
- package/dist/generated/cognition/core/types.gen.d.ts +83 -0
- package/dist/generated/cognition/core/utils.gen.d.ts +19 -0
- package/dist/generated/cognition/index.d.ts +2 -0
- package/dist/generated/cognition/index.js +6 -0
- package/dist/generated/cognition/sdk.gen.d.ts +224 -0
- package/dist/generated/cognition/types.gen.d.ts +2484 -0
- package/dist/generated/connection/client/client.gen.d.ts +2 -0
- package/dist/generated/connection/client/index.d.ts +10 -0
- package/dist/generated/connection/client/types.gen.d.ts +120 -0
- package/dist/generated/connection/client/utils.gen.d.ts +37 -0
- package/dist/generated/connection/client.gen.d.ts +12 -0
- package/dist/generated/connection/core/auth.gen.d.ts +25 -0
- package/dist/generated/connection/core/bodySerializer.gen.d.ts +25 -0
- package/dist/generated/connection/core/params.gen.d.ts +43 -0
- package/dist/generated/connection/core/pathSerializer.gen.d.ts +33 -0
- package/dist/generated/connection/core/queryKeySerializer.gen.d.ts +18 -0
- package/dist/generated/connection/core/serverSentEvents.gen.d.ts +71 -0
- package/dist/generated/connection/core/types.gen.d.ts +83 -0
- package/dist/generated/connection/core/utils.gen.d.ts +19 -0
- package/dist/generated/connection/index.d.ts +2 -0
- package/dist/generated/connection/index.js +839 -0
- package/dist/generated/connection/sdk.gen.d.ts +38 -0
- package/dist/generated/connection/types.gen.d.ts +235 -0
- package/dist/generated/contacts/client/client.gen.d.ts +2 -0
- package/dist/generated/contacts/client/index.d.ts +10 -0
- package/dist/generated/contacts/client/types.gen.d.ts +120 -0
- package/dist/generated/contacts/client/utils.gen.d.ts +37 -0
- package/dist/generated/contacts/client.gen.d.ts +12 -0
- package/dist/generated/contacts/core/auth.gen.d.ts +25 -0
- package/dist/generated/contacts/core/bodySerializer.gen.d.ts +25 -0
- package/dist/generated/contacts/core/params.gen.d.ts +43 -0
- package/dist/generated/contacts/core/pathSerializer.gen.d.ts +33 -0
- package/dist/generated/contacts/core/queryKeySerializer.gen.d.ts +18 -0
- package/dist/generated/contacts/core/serverSentEvents.gen.d.ts +71 -0
- package/dist/generated/contacts/core/types.gen.d.ts +83 -0
- package/dist/generated/contacts/core/utils.gen.d.ts +19 -0
- package/dist/generated/contacts/index.d.ts +2 -0
- package/dist/generated/contacts/index.js +6 -0
- package/dist/generated/contacts/sdk.gen.d.ts +43 -0
- package/dist/generated/contacts/types.gen.d.ts +52 -0
- package/dist/generated/email/client/client.gen.d.ts +2 -0
- package/dist/generated/email/client/index.d.ts +10 -0
- package/dist/generated/email/client/types.gen.d.ts +120 -0
- package/dist/generated/email/client/utils.gen.d.ts +37 -0
- package/dist/generated/email/client.gen.d.ts +12 -0
- package/dist/generated/email/core/auth.gen.d.ts +25 -0
- package/dist/generated/email/core/bodySerializer.gen.d.ts +25 -0
- package/dist/generated/email/core/params.gen.d.ts +43 -0
- package/dist/generated/email/core/pathSerializer.gen.d.ts +33 -0
- package/dist/generated/email/core/queryKeySerializer.gen.d.ts +18 -0
- package/dist/generated/email/core/serverSentEvents.gen.d.ts +71 -0
- package/dist/generated/email/core/types.gen.d.ts +83 -0
- package/dist/generated/email/core/utils.gen.d.ts +19 -0
- package/dist/generated/email/index.d.ts +2 -0
- package/dist/generated/email/index.js +6 -0
- package/dist/generated/email/sdk.gen.d.ts +254 -0
- package/dist/generated/email/types.gen.d.ts +2614 -0
- package/dist/generated/notification/client/client.gen.d.ts +2 -0
- package/dist/generated/notification/client/index.d.ts +10 -0
- package/dist/generated/notification/client/types.gen.d.ts +120 -0
- package/dist/generated/notification/client/utils.gen.d.ts +37 -0
- package/dist/generated/notification/client.gen.d.ts +12 -0
- package/dist/generated/notification/core/auth.gen.d.ts +25 -0
- package/dist/generated/notification/core/bodySerializer.gen.d.ts +25 -0
- package/dist/generated/notification/core/params.gen.d.ts +43 -0
- package/dist/generated/notification/core/pathSerializer.gen.d.ts +33 -0
- package/dist/generated/notification/core/queryKeySerializer.gen.d.ts +18 -0
- package/dist/generated/notification/core/serverSentEvents.gen.d.ts +71 -0
- package/dist/generated/notification/core/types.gen.d.ts +83 -0
- package/dist/generated/notification/core/utils.gen.d.ts +19 -0
- package/dist/generated/notification/index.d.ts +2 -0
- package/dist/generated/notification/index.js +6 -0
- package/dist/generated/notification/sdk.gen.d.ts +118 -0
- package/dist/generated/notification/types.gen.d.ts +1352 -0
- package/dist/generated/properties/client/client.gen.d.ts +2 -0
- package/dist/generated/properties/client/index.d.ts +10 -0
- package/dist/generated/properties/client/types.gen.d.ts +120 -0
- package/dist/generated/properties/client/utils.gen.d.ts +37 -0
- package/dist/generated/properties/client.gen.d.ts +12 -0
- package/dist/generated/properties/core/auth.gen.d.ts +25 -0
- package/dist/generated/properties/core/bodySerializer.gen.d.ts +25 -0
- package/dist/generated/properties/core/params.gen.d.ts +43 -0
- package/dist/generated/properties/core/pathSerializer.gen.d.ts +33 -0
- package/dist/generated/properties/core/queryKeySerializer.gen.d.ts +18 -0
- package/dist/generated/properties/core/serverSentEvents.gen.d.ts +71 -0
- package/dist/generated/properties/core/types.gen.d.ts +83 -0
- package/dist/generated/properties/core/utils.gen.d.ts +19 -0
- package/dist/generated/properties/index.d.ts +2 -0
- package/dist/generated/properties/index.js +6 -0
- package/dist/generated/properties/sdk.gen.d.ts +158 -0
- package/dist/generated/properties/types.gen.d.ts +1288 -0
- package/dist/generated/scheduled-action/client/client.gen.d.ts +2 -0
- package/dist/generated/scheduled-action/client/index.d.ts +10 -0
- package/dist/generated/scheduled-action/client/types.gen.d.ts +120 -0
- package/dist/generated/scheduled-action/client/utils.gen.d.ts +37 -0
- package/dist/generated/scheduled-action/client.gen.d.ts +12 -0
- package/dist/generated/scheduled-action/core/auth.gen.d.ts +25 -0
- package/dist/generated/scheduled-action/core/bodySerializer.gen.d.ts +25 -0
- package/dist/generated/scheduled-action/core/params.gen.d.ts +43 -0
- package/dist/generated/scheduled-action/core/pathSerializer.gen.d.ts +33 -0
- package/dist/generated/scheduled-action/core/queryKeySerializer.gen.d.ts +18 -0
- package/dist/generated/scheduled-action/core/serverSentEvents.gen.d.ts +71 -0
- package/dist/generated/scheduled-action/core/types.gen.d.ts +83 -0
- package/dist/generated/scheduled-action/core/utils.gen.d.ts +19 -0
- package/dist/generated/scheduled-action/index.d.ts +2 -0
- package/dist/generated/scheduled-action/index.js +845 -0
- package/dist/generated/scheduled-action/sdk.gen.d.ts +42 -0
- package/dist/generated/scheduled-action/types.gen.d.ts +241 -0
- package/dist/generated/search/client/client.gen.d.ts +2 -0
- package/dist/generated/search/client/index.d.ts +10 -0
- package/dist/generated/search/client/types.gen.d.ts +120 -0
- package/dist/generated/search/client/utils.gen.d.ts +37 -0
- package/dist/generated/search/client.gen.d.ts +12 -0
- package/dist/generated/search/core/auth.gen.d.ts +25 -0
- package/dist/generated/search/core/bodySerializer.gen.d.ts +25 -0
- package/dist/generated/search/core/params.gen.d.ts +43 -0
- package/dist/generated/search/core/pathSerializer.gen.d.ts +33 -0
- package/dist/generated/search/core/queryKeySerializer.gen.d.ts +18 -0
- package/dist/generated/search/core/serverSentEvents.gen.d.ts +71 -0
- package/dist/generated/search/core/types.gen.d.ts +83 -0
- package/dist/generated/search/core/utils.gen.d.ts +19 -0
- package/dist/generated/search/index.d.ts +2 -0
- package/dist/generated/search/index.js +6 -0
- package/dist/generated/search/sdk.gen.d.ts +44 -0
- package/dist/generated/search/types.gen.d.ts +2194 -0
- package/dist/generated/static-files/client/client.gen.d.ts +2 -0
- package/dist/generated/static-files/client/index.d.ts +10 -0
- package/dist/generated/static-files/client/types.gen.d.ts +120 -0
- package/dist/generated/static-files/client/utils.gen.d.ts +37 -0
- package/dist/generated/static-files/client.gen.d.ts +12 -0
- package/dist/generated/static-files/core/auth.gen.d.ts +25 -0
- package/dist/generated/static-files/core/bodySerializer.gen.d.ts +25 -0
- package/dist/generated/static-files/core/params.gen.d.ts +43 -0
- package/dist/generated/static-files/core/pathSerializer.gen.d.ts +33 -0
- package/dist/generated/static-files/core/queryKeySerializer.gen.d.ts +18 -0
- package/dist/generated/static-files/core/serverSentEvents.gen.d.ts +71 -0
- package/dist/generated/static-files/core/types.gen.d.ts +83 -0
- package/dist/generated/static-files/core/utils.gen.d.ts +19 -0
- package/dist/generated/static-files/index.d.ts +2 -0
- package/dist/generated/static-files/index.js +842 -0
- package/dist/generated/static-files/sdk.gen.d.ts +43 -0
- package/dist/generated/static-files/types.gen.d.ts +214 -0
- package/dist/generated/storage/client/client.gen.d.ts +2 -0
- package/dist/generated/storage/client/index.d.ts +10 -0
- package/dist/generated/storage/client/types.gen.d.ts +120 -0
- package/dist/generated/storage/client/utils.gen.d.ts +37 -0
- package/dist/generated/storage/client.gen.d.ts +12 -0
- package/dist/generated/storage/core/auth.gen.d.ts +25 -0
- package/dist/generated/storage/core/bodySerializer.gen.d.ts +25 -0
- package/dist/generated/storage/core/params.gen.d.ts +43 -0
- package/dist/generated/storage/core/pathSerializer.gen.d.ts +33 -0
- package/dist/generated/storage/core/queryKeySerializer.gen.d.ts +18 -0
- package/dist/generated/storage/core/serverSentEvents.gen.d.ts +71 -0
- package/dist/generated/storage/core/types.gen.d.ts +83 -0
- package/dist/generated/storage/core/utils.gen.d.ts +19 -0
- package/dist/generated/storage/index.d.ts +2 -0
- package/dist/generated/storage/index.js +6 -0
- package/dist/generated/storage/sdk.gen.d.ts +858 -0
- package/dist/generated/storage/types.gen.d.ts +12105 -0
- package/dist/generated/unfurl/client/client.gen.d.ts +2 -0
- package/dist/generated/unfurl/client/index.d.ts +10 -0
- package/dist/generated/unfurl/client/types.gen.d.ts +120 -0
- package/dist/generated/unfurl/client/utils.gen.d.ts +37 -0
- package/dist/generated/unfurl/client.gen.d.ts +12 -0
- package/dist/generated/unfurl/core/auth.gen.d.ts +25 -0
- package/dist/generated/unfurl/core/bodySerializer.gen.d.ts +25 -0
- package/dist/generated/unfurl/core/params.gen.d.ts +43 -0
- package/dist/generated/unfurl/core/pathSerializer.gen.d.ts +33 -0
- package/dist/generated/unfurl/core/queryKeySerializer.gen.d.ts +18 -0
- package/dist/generated/unfurl/core/serverSentEvents.gen.d.ts +71 -0
- package/dist/generated/unfurl/core/types.gen.d.ts +83 -0
- package/dist/generated/unfurl/core/utils.gen.d.ts +19 -0
- package/dist/generated/unfurl/index.d.ts +2 -0
- package/dist/generated/unfurl/index.js +835 -0
- package/dist/generated/unfurl/sdk.gen.d.ts +47 -0
- package/dist/generated/unfurl/types.gen.d.ts +125 -0
- package/dist/src/config.d.ts +51 -0
- package/dist/src/entities/agent-sessions/agent-session.d.ts +45 -0
- package/dist/src/entities/agent-sessions/namespace.d.ts +18 -0
- package/dist/src/entities/bots/namespace.d.ts +25 -0
- package/dist/src/entities/calls/call-record.d.ts +55 -0
- package/dist/src/entities/calls/namespace.d.ts +9 -0
- package/dist/src/entities/channels/channel.d.ts +88 -0
- package/dist/src/entities/channels/message.d.ts +64 -0
- package/dist/src/entities/channels/namespace.d.ts +30 -0
- package/dist/src/entities/channels/post.d.ts +20 -0
- package/dist/src/entities/channels/thread.d.ts +30 -0
- package/dist/src/entities/chats/chat.d.ts +55 -0
- package/dist/src/entities/chats/namespace.d.ts +14 -0
- package/dist/src/entities/crm/comment.d.ts +43 -0
- package/dist/src/entities/crm/company.d.ts +70 -0
- package/dist/src/entities/crm/contact.d.ts +48 -0
- package/dist/src/entities/crm/namespace.d.ts +22 -0
- package/dist/src/entities/documents/comment.d.ts +41 -0
- package/dist/src/entities/documents/document.d.ts +130 -0
- package/dist/src/entities/documents/namespace.d.ts +43 -0
- package/dist/src/entities/documents/system-skill.d.ts +16 -0
- package/dist/src/entities/email/attachment.d.ts +36 -0
- package/dist/src/entities/email/label.d.ts +31 -0
- package/dist/src/entities/email/link.d.ts +29 -0
- package/dist/src/entities/email/message.d.ts +58 -0
- package/dist/src/entities/email/namespace.d.ts +49 -0
- package/dist/src/entities/email/thread.d.ts +88 -0
- package/dist/src/entities/entity.d.ts +101 -0
- package/dist/src/entities/favorites/namespace.d.ts +19 -0
- package/dist/src/entities/foreign/foreign-entity.d.ts +30 -0
- package/dist/src/entities/foreign/namespace.d.ts +7 -0
- package/dist/src/entities/notifications/namespace.d.ts +29 -0
- package/dist/src/entities/notifications/notification.d.ts +50 -0
- package/dist/src/entities/pins/namespace.d.ts +19 -0
- package/dist/src/entities/projects/namespace.d.ts +13 -0
- package/dist/src/entities/projects/project.d.ts +42 -0
- package/dist/src/entities/properties/namespace.d.ts +47 -0
- package/dist/src/entities/properties/property-definition.d.ts +45 -0
- package/dist/src/entities/properties/property-option.d.ts +32 -0
- package/dist/src/entities/search.d.ts +23 -0
- package/dist/src/entities/tasks/namespace.d.ts +21 -0
- package/dist/src/entities/tasks/task.d.ts +34 -0
- package/dist/src/entities/teams/namespace.d.ts +12 -0
- package/dist/src/entities/teams/team.d.ts +40 -0
- package/dist/src/entities/users/namespace.d.ts +10 -0
- package/dist/src/entities/users/user.d.ts +43 -0
- package/dist/src/entities/webhooks/namespace.d.ts +31 -0
- package/dist/src/entities/webhooks/webhook.d.ts +88 -0
- package/dist/src/events/hydrate/channel.d.ts +85 -0
- package/dist/src/events/hydrate/document.d.ts +54 -0
- package/dist/src/events/receiver.d.ts +51 -0
- package/dist/src/events/types.d.ts +40 -0
- package/dist/src/events/verify.d.ts +13 -0
- package/dist/src/local-portmap.d.ts +8 -0
- package/dist/src/macro.d.ts +62 -0
- package/dist/src/macro.js +4215 -0
- package/dist/src/mentions.d.ts +37 -0
- package/dist/src/raw.d.ts +12 -0
- package/dist/src/utils/client.d.ts +53 -0
- package/dist/src/utils/index.d.ts +4 -0
- package/dist/src/utils/lazy.d.ts +18 -0
- package/dist/src/utils/pagination.d.ts +7 -0
- package/dist/src/utils/unwrap.d.ts +23 -0
- 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.
|