@macro-inc/sdk 0.2.2 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (175) hide show
  1. package/README.md +177 -3
  2. package/dist/{chunk-OGE7WXJE.js → chunk-AZJUIUIV.js} +177 -23
  3. package/dist/{chunk-PRUFPW3B.js → chunk-G43PLP2U.js} +144 -0
  4. package/dist/{chunk-7LVVPVNT.js → chunk-K4G5VO4P.js} +76 -1
  5. package/dist/{chunk-PAAFJYGO.js → chunk-PPR7IWZ7.js} +77 -51
  6. package/dist/{chunk-QVBNNMQS.js → chunk-PTX2RV2N.js} +169 -20
  7. package/dist/{chunk-SUINKDXF.js → chunk-PZPTJI6F.js} +42 -0
  8. package/dist/{chunk-7YJ6Y7HJ.js → chunk-XFA7NCJ5.js} +207 -0
  9. package/dist/{chunk-ZQXOHNDB.js → chunk-ZLBDES7U.js} +789 -12
  10. package/dist/generated/agent-fold/index.d.ts +4332 -0
  11. package/dist/generated/agent-fold/index.js +0 -0
  12. package/dist/generated/agent-harness/index.d.ts +1 -1
  13. package/dist/generated/agent-harness/index.js +1 -1
  14. package/dist/generated/agent-harness/sdk.gen.d.ts +83 -9
  15. package/dist/generated/agent-harness/types.gen.d.ts +1504 -160
  16. package/dist/generated/agent-reviews/index.d.ts +893 -0
  17. package/dist/generated/agent-reviews/index.js +0 -0
  18. package/dist/generated/auth/index.d.ts +1 -1
  19. package/dist/generated/auth/index.js +1 -1
  20. package/dist/generated/auth/sdk.gen.d.ts +108 -2
  21. package/dist/generated/auth/types.gen.d.ts +799 -6
  22. package/dist/generated/calendar/index.d.ts +1 -1
  23. package/dist/generated/calendar/index.js +1 -1
  24. package/dist/generated/calendar/sdk.gen.d.ts +63 -1
  25. package/dist/generated/calendar/types.gen.d.ts +1234 -5
  26. package/dist/generated/cognition/index.d.ts +1 -1
  27. package/dist/generated/cognition/index.js +1 -1
  28. package/dist/generated/cognition/sdk.gen.d.ts +85 -20
  29. package/dist/generated/cognition/types.gen.d.ts +1040 -121
  30. package/dist/generated/connection/index.d.ts +1 -1
  31. package/dist/generated/connection/index.js +15 -0
  32. package/dist/generated/connection/sdk.gen.d.ts +6 -1
  33. package/dist/generated/connection/types.gen.d.ts +18 -1
  34. package/dist/generated/email/index.d.ts +1 -1
  35. package/dist/generated/email/index.js +1 -1
  36. package/dist/generated/email/sdk.gen.d.ts +44 -2
  37. package/dist/generated/email/types.gen.d.ts +475 -10
  38. package/dist/generated/notification/index.d.ts +1 -1
  39. package/dist/generated/notification/index.js +1 -1
  40. package/dist/generated/notification/sdk.gen.d.ts +29 -21
  41. package/dist/generated/notification/types.gen.d.ts +267 -73
  42. package/dist/generated/properties/index.d.ts +1 -1
  43. package/dist/generated/properties/types.gen.d.ts +21 -1
  44. package/dist/generated/scheduled-action/index.d.ts +1 -1
  45. package/dist/generated/scheduled-action/index.js +1 -1
  46. package/dist/generated/scheduled-action/sdk.gen.d.ts +8 -1
  47. package/dist/generated/scheduled-action/types.gen.d.ts +669 -19
  48. package/dist/generated/search/index.d.ts +1 -1
  49. package/dist/generated/search/types.gen.d.ts +87 -7
  50. package/dist/generated/static-files/types.gen.d.ts +6 -0
  51. package/dist/generated/storage/index.d.ts +1 -1
  52. package/dist/generated/storage/index.js +1 -1
  53. package/dist/generated/storage/sdk.gen.d.ts +376 -13
  54. package/dist/generated/storage/types.gen.d.ts +12038 -5562
  55. package/dist/src/entities/account-managers/grant.d.ts +39 -0
  56. package/dist/src/entities/account-managers/namespace.d.ts +17 -0
  57. package/dist/src/entities/agent-sessions/activity.d.ts +39 -0
  58. package/dist/src/entities/agent-sessions/agent-session.d.ts +148 -6
  59. package/dist/src/entities/agent-sessions/code-execution.d.ts +5 -0
  60. package/dist/src/entities/agent-sessions/namespace.d.ts +54 -4
  61. package/dist/src/entities/agent-sessions/origin.d.ts +94 -0
  62. package/dist/src/entities/agent-sessions/review.d.ts +18 -62
  63. package/dist/src/entities/agent-sessions/view.d.ts +11 -0
  64. package/dist/src/entities/agents/namespace.d.ts +11 -2
  65. package/dist/src/entities/ai/namespace.d.ts +5 -1
  66. package/dist/src/entities/api-keys/namespace.d.ts +5 -1
  67. package/dist/src/entities/bots/bot.d.ts +108 -0
  68. package/dist/src/entities/bots/namespace.d.ts +17 -4
  69. package/dist/src/entities/bots/token.d.ts +34 -0
  70. package/dist/src/entities/calendar/booking-link.d.ts +49 -0
  71. package/dist/src/entities/calendar/booking-namespace.d.ts +130 -0
  72. package/dist/src/entities/calendar/booking-namespace.test.d.ts +1 -0
  73. package/dist/src/entities/calendar/booking.d.ts +77 -0
  74. package/dist/src/entities/calendar/calendar.d.ts +11 -4
  75. package/dist/src/entities/calendar/create-confirmed.test.d.ts +1 -0
  76. package/dist/src/entities/calendar/event.d.ts +104 -3
  77. package/dist/src/entities/calendar/namespace.d.ts +151 -7
  78. package/dist/src/entities/calendar/namespace.test.d.ts +1 -0
  79. package/dist/src/entities/calls/call-record.d.ts +34 -4
  80. package/dist/src/entities/calls/connection.d.ts +53 -0
  81. package/dist/src/entities/calls/errors.d.ts +15 -0
  82. package/dist/src/entities/calls/namespace.d.ts +21 -1
  83. package/dist/src/entities/calls/participant.d.ts +22 -0
  84. package/dist/src/entities/channels/access-request.d.ts +34 -0
  85. package/dist/src/entities/channels/channel.d.ts +47 -1
  86. package/dist/src/entities/channels/namespace.d.ts +21 -5
  87. package/dist/src/entities/channels/namespace.test.d.ts +1 -0
  88. package/dist/src/entities/channels/post.d.ts +14 -3
  89. package/dist/src/entities/channels/thread.d.ts +10 -1
  90. package/dist/src/entities/chats/chat.d.ts +7 -1
  91. package/dist/src/entities/chats/namespace.d.ts +14 -1
  92. package/dist/src/entities/connected-apps/connected-app.d.ts +107 -0
  93. package/dist/src/entities/connected-apps/connector.d.ts +56 -0
  94. package/dist/src/entities/connected-apps/namespace.d.ts +74 -0
  95. package/dist/src/entities/crm/company.d.ts +7 -3
  96. package/dist/src/entities/crm/contact.d.ts +4 -4
  97. package/dist/src/entities/crm/namespace.d.ts +34 -1
  98. package/dist/src/entities/crm/pipeline.d.ts +43 -2
  99. package/dist/src/entities/databases/database.d.ts +17 -0
  100. package/dist/src/entities/databases/namespace.d.ts +56 -0
  101. package/dist/src/entities/documents/ai-edit.d.ts +52 -0
  102. package/dist/src/entities/documents/document.d.ts +244 -5
  103. package/dist/src/entities/documents/namespace.d.ts +89 -4
  104. package/dist/src/entities/documents/office-files.d.ts +47 -0
  105. package/dist/src/entities/email/draft.d.ts +36 -7
  106. package/dist/src/entities/email/message.d.ts +99 -3
  107. package/dist/src/entities/email/namespace.d.ts +47 -4
  108. package/dist/src/entities/email/namespace.test.d.ts +1 -0
  109. package/dist/src/entities/email/thread.d.ts +55 -3
  110. package/dist/src/entities/entity-mentions/namespace.d.ts +5 -1
  111. package/dist/src/entities/external-chat/chat.d.ts +105 -0
  112. package/dist/src/entities/external-chat/message.d.ts +54 -0
  113. package/dist/src/entities/external-chat/namespace.d.ts +18 -0
  114. package/dist/src/entities/external-chat/participant.d.ts +28 -0
  115. package/dist/src/entities/external-chat/send.d.ts +32 -0
  116. package/dist/src/entities/external-chat/upload.d.ts +25 -0
  117. package/dist/src/entities/favorites/namespace.d.ts +5 -1
  118. package/dist/src/entities/foreign/namespace.d.ts +3 -0
  119. package/dist/src/entities/forms/form.d.ts +17 -2
  120. package/dist/src/entities/forms/namespace.d.ts +5 -1
  121. package/dist/src/entities/github-pull-requests/namespace.d.ts +5 -1
  122. package/dist/src/entities/harnesses/harness.d.ts +9 -0
  123. package/dist/src/entities/harnesses/namespace.d.ts +5 -1
  124. package/dist/src/entities/images/image.d.ts +77 -0
  125. package/dist/src/entities/images/namespace.d.ts +48 -0
  126. package/dist/src/entities/images/namespace.test.d.ts +1 -0
  127. package/dist/src/entities/initiatives/initiative.d.ts +12 -1
  128. package/dist/src/entities/initiatives/namespace.d.ts +15 -2
  129. package/dist/src/entities/me/namespace.d.ts +43 -0
  130. package/dist/src/entities/meetings/meeting.d.ts +5 -0
  131. package/dist/src/entities/meetings/namespace.d.ts +5 -1
  132. package/dist/src/entities/messages/thread.d.ts +1 -1
  133. package/dist/src/entities/notifications/namespace.d.ts +3 -0
  134. package/dist/src/entities/pins/namespace.d.ts +5 -1
  135. package/dist/src/entities/projects/namespace.d.ts +4 -1
  136. package/dist/src/entities/projects/project.d.ts +9 -1
  137. package/dist/src/entities/properties/namespace.d.ts +2 -0
  138. package/dist/src/entities/referrals/namespace.d.ts +33 -0
  139. package/dist/src/entities/routines/namespace.d.ts +42 -2
  140. package/dist/src/entities/routines/routine.d.ts +84 -5
  141. package/dist/src/entities/search/namespace.d.ts +65 -0
  142. package/dist/src/entities/{search.d.ts → search/options.d.ts} +8 -2
  143. package/dist/src/entities/search/types.d.ts +90 -0
  144. package/dist/src/entities/sharing/access.d.ts +14 -0
  145. package/dist/src/entities/tasks/namespace.d.ts +42 -3
  146. package/dist/src/entities/tasks/task.d.ts +47 -6
  147. package/dist/src/entities/teams/invite.d.ts +30 -0
  148. package/dist/src/entities/teams/namespace.d.ts +3 -0
  149. package/dist/src/entities/teams/team.d.ts +37 -0
  150. package/dist/src/entities/unfurls/namespace.d.ts +5 -1
  151. package/dist/src/entities/users/namespace.d.ts +9 -0
  152. package/dist/src/entities/users/user.d.ts +8 -0
  153. package/dist/src/entities/web/namespace.d.ts +61 -0
  154. package/dist/src/entities/web/namespace.test.d.ts +1 -0
  155. package/dist/src/entities/webhooks/namespace.d.ts +2 -0
  156. package/dist/src/entities/whatsapp/account.d.ts +20 -0
  157. package/dist/src/entities/whatsapp/chat.d.ts +54 -0
  158. package/dist/src/entities/whatsapp/namespace.d.ts +23 -0
  159. package/dist/src/entities/workspace/items.d.ts +7 -0
  160. package/dist/src/entities/workspace/namespace.d.ts +14 -9
  161. package/dist/src/entities/workspace/query.d.ts +23 -0
  162. package/dist/src/entities/workspace/types.d.ts +6 -3
  163. package/dist/src/events/hydrate/agentSession.d.ts +1 -1
  164. package/dist/src/events/hydrate/call.d.ts +101 -0
  165. package/dist/src/events/hydrate/channel.d.ts +8 -1
  166. package/dist/src/events/hydrate/document.d.ts +1 -1
  167. package/dist/src/events/hydrate/message.d.ts +1 -1
  168. package/dist/src/events/types.d.ts +2 -1
  169. package/dist/src/macro.d.ts +73 -4
  170. package/dist/src/macro.js +8235 -3701
  171. package/dist/src/mentions.d.ts +6 -1
  172. package/dist/src/utils/activity.d.ts +23 -2
  173. package/dist/src/utils/index.d.ts +1 -1
  174. package/dist/src/utils/unwrap.d.ts +27 -2
  175. package/package.json +2 -2
@@ -1,12 +1,21 @@
1
1
  import type { MacroClient } from '../../utils/client';
2
2
  import { Agent, type AgentOptions } from './agent';
3
- /** Configurable agents. */
3
+ /**
4
+ * Configurable agents.
5
+ *
6
+ * @routing Use when the user wants to change how one of their Macro agent personas is set up: its instructions, model, runtime, channels or hosts; not any request the user asks you, the agent, to carry out.
7
+ */
4
8
  export declare class AgentNamespace {
5
9
  private readonly client;
6
10
  constructor(client: MacroClient);
7
11
  /** Construct a lazy agent handle. */
8
12
  byId(id: string): Agent;
9
- /** All accessible agents. */
13
+ /**
14
+ * Accessible custom agents. Pass one to
15
+ * {@link AgentSessionNamespace.createManaged} to start a session as that
16
+ * persona. System personas such as Cursor are constructed with
17
+ * {@link Agent.byId}.
18
+ */
10
19
  list(): Promise<Agent[]>;
11
20
  /** Create an agent. */
12
21
  create(options: AgentOptions): Promise<Agent>;
@@ -2,7 +2,11 @@ import type { DecisionRequest, DecisionResponse, StructuredCompletionRequest, St
2
2
  import type { MacroClient } from '../../utils/client';
3
3
  import type { User } from '../users/user';
4
4
  export type { DecisionRequest, DecisionResponse, StructuredCompletionRequest, StructuredCompletionResponse, };
5
- /** Shared cognition endpoints, charged to the authenticated acting user. */
5
+ /**
6
+ * Shared cognition endpoints, charged to the authenticated acting user.
7
+ *
8
+ * @routing Use when generating structured objects or classifying supplied content with Jev; not generating images (`macro.images`) or answering the user yourself.
9
+ */
6
10
  export declare class AiNamespace {
7
11
  private readonly client;
8
12
  /** Read AI usage over a time range, optionally restricting it to users. */
@@ -1,6 +1,10 @@
1
1
  import type { MacroClient } from '../../utils/client';
2
2
  import { UserApiKey } from './api-key';
3
- /** User API key management. */
3
+ /**
4
+ * User API key management.
5
+ *
6
+ * @routing Use when creating, listing or revoking the user's API keys; not bot credentials.
7
+ */
4
8
  export declare class ApiKeyNamespace {
5
9
  private readonly client;
6
10
  constructor(client: MacroClient);
@@ -0,0 +1,108 @@
1
+ import type { Bot as BotRecord } from '../../../generated/storage/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import { Channel } from '../channels/channel';
4
+ import { MacroEntity } from '../entity';
5
+ import { Team } from '../teams/team';
6
+ import { User } from '../users/user';
7
+ import { BotToken } from './token';
8
+ /** Settings for a new bot. */
9
+ export type CreateBotOptions = {
10
+ /** Display name. */
11
+ name: string;
12
+ /** Stable mention handle: lowercase ASCII letters, digits, `-` and `_`, at most 64 characters. */
13
+ handle: string;
14
+ /** Short description of what the bot does. */
15
+ description?: string;
16
+ /** Profile picture URL, such as a Macro static-file URL. */
17
+ avatarUrl?: string;
18
+ /** Owning team; omit for a bot owned by the caller. Requires team admin or owner. */
19
+ team?: Team;
20
+ /** Whether mentioning the bot opens a coding-agent session. Defaults to false. */
21
+ hasAgent?: boolean;
22
+ };
23
+ /** Profile changes for a bot; omitted fields keep their value. */
24
+ export type UpdateBotOptions = {
25
+ /** New display name. */
26
+ name?: string;
27
+ /** New stable handle. Integrations and mentions may rely on the old one. */
28
+ handle?: string;
29
+ /** New description; an empty string clears it. */
30
+ description?: string;
31
+ /** New profile picture URL; an empty string clears it. */
32
+ avatarUrl?: string;
33
+ /** Whether mentioning the bot opens a coding-agent session. */
34
+ hasAgent?: boolean;
35
+ };
36
+ /** A bot channel webhook: POST `{ content }` to `url` to post as the bot. */
37
+ export type BotWebhook = {
38
+ /** Channel the webhook posts into. */
39
+ channel: Channel;
40
+ /** Public URL to POST to. */
41
+ url: string;
42
+ };
43
+ /** Who owns a bot. */
44
+ export type BotOwner = {
45
+ type: 'user';
46
+ user: User;
47
+ } | {
48
+ type: 'team';
49
+ team: Team;
50
+ };
51
+ /** A user- or team-owned bot: an identity that posts to channels through webhooks or the SDK. */
52
+ export declare class Bot extends MacroEntity<BotRecord> {
53
+ /** A handle to a bot by id. */
54
+ static byId(client: MacroClient, id: string): Bot;
55
+ /** Seed from a listed or created bot. */
56
+ static from(client: MacroClient, record: BotRecord): Bot;
57
+ /** Create a bot owned by the caller or by a team. */
58
+ static create(client: MacroClient, options: CreateBotOptions): Promise<Bot>;
59
+ /** The bots the caller can manage: their own and their teams'. */
60
+ static list(client: MacroClient): Promise<Bot[]>;
61
+ protected fetch(): Promise<BotRecord>;
62
+ /** Display name. */
63
+ readonly name: () => Promise<string>;
64
+ /** Stable mention handle, without the `@`. */
65
+ readonly handle: () => Promise<string>;
66
+ /** Short description. */
67
+ readonly description: () => Promise<string | undefined>;
68
+ /** Profile picture URL. */
69
+ readonly avatarUrl: () => Promise<string | undefined>;
70
+ /** Whether mentioning the bot opens a coding-agent session. */
71
+ readonly hasAgent: () => Promise<boolean>;
72
+ /** Creation time. */
73
+ readonly createdAt: () => Promise<string>;
74
+ /** Last profile change. */
75
+ readonly updatedAt: () => Promise<string>;
76
+ /** The owning user or team. */
77
+ readonly owner: () => Promise<BotOwner | undefined>;
78
+ /** Change the bot's profile; pass only the fields that should change. */
79
+ update(changes: UpdateBotOptions): Promise<void>;
80
+ /** Delete the bot. Its tokens stop working and it leaves every channel. */
81
+ delete(): Promise<void>;
82
+ /** Channels the bot can post to. */
83
+ channels(): Promise<Channel[]>;
84
+ /**
85
+ * One webhook per channel the bot can post to. POST JSON `{ content }` with
86
+ * a token from {@link createToken} in the `x-macro-bot-token` header and
87
+ * `x-macro-bot-scope: user`. Empty until {@link grantChannel}.
88
+ */
89
+ webhooks(): Promise<BotWebhook[]>;
90
+ /** Let the bot post to a channel. The caller must be a member of it and manage the bot. */
91
+ grantChannel(channel: Channel): Promise<void>;
92
+ /** Remove the bot from a channel. Works after the caller has left the channel. */
93
+ revokeChannel(channel: Channel): Promise<void>;
94
+ /** The bot's tokens, including revoked and expired ones. Secrets are never returned. */
95
+ tokens(): Promise<BotToken[]>;
96
+ /**
97
+ * Mint a bearer token for the bot's webhooks and API. The secret is returned
98
+ * once and cannot be read again; never write it into chat, documents or
99
+ * results. To hand a user a token, have them mint it in bot settings.
100
+ */
101
+ createToken(options?: {
102
+ label?: string;
103
+ expiresAt?: Date;
104
+ }): Promise<{
105
+ token: BotToken;
106
+ secret: string;
107
+ }>;
108
+ }
@@ -1,17 +1,30 @@
1
- import type { Bot, BotChannel } from '../../../generated/storage/types.gen';
1
+ import type { BotChannel, Bot as BotRecord } from '../../../generated/storage/types.gen';
2
2
  import type { MacroClient } from '../../utils/client';
3
+ import { Bot, type CreateBotOptions } from './bot';
3
4
  /**
4
- * The authenticated bot's identity. Only meaningful with bot auth
5
- * (`auth: { type: 'bot', token }`).
5
+ * Bots the user manages — create, list, configure, delete, channel access,
6
+ * webhooks and tokens — and, with bot auth (`auth: { type: 'bot', token }`),
7
+ * the authenticated bot's own identity.
8
+ *
9
+ * @routing Use when inspecting or managing bots and their channel access; not an agent's instructions, which are agents.
6
10
  */
7
11
  export declare class BotsNamespace {
8
12
  private readonly client;
9
13
  constructor(client: MacroClient);
14
+ /** A handle to a bot by id. */
15
+ byId(id: string): Bot;
16
+ /** The bots the user can manage: their own and their teams'. */
17
+ list(): Promise<Bot[]>;
18
+ /**
19
+ * Create a bot. It can post nowhere until `bot.grantChannel(channel)`; then
20
+ * `bot.webhooks()` and `bot.createToken()` give an integration what it needs.
21
+ */
22
+ create(options: CreateBotOptions): Promise<Bot>;
10
23
  /**
11
24
  * The authenticated bot's own record. Requires bot auth; with a user API
12
25
  * key this throws (a user token has no bot identity).
13
26
  */
14
- me(): Promise<Bot>;
27
+ me(): Promise<BotRecord>;
15
28
  /**
16
29
  * Channels containing the authenticated bot. Requires bot auth.
17
30
  */
@@ -0,0 +1,34 @@
1
+ import type { BotToken as BotTokenRecord } from '../../../generated/storage/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import { MacroEntity } from '../entity';
4
+ import type { Bot } from './bot';
5
+ /** A bot bearer token's metadata. The secret is returned only by `Bot.createToken`. */
6
+ export declare class BotToken extends MacroEntity<BotTokenRecord> {
7
+ /** The bot this token authenticates. */
8
+ readonly bot: Bot;
9
+ private constructor();
10
+ /** A handle to one of a bot's tokens by id. */
11
+ static byId(client: MacroClient, bot: Bot, id: string): BotToken;
12
+ /** Seed from a listed or created token. */
13
+ static from(client: MacroClient, bot: Bot, record: BotTokenRecord): BotToken;
14
+ protected fetch(): Promise<BotTokenRecord>;
15
+ /** The first characters of the secret, for telling tokens apart. */
16
+ readonly prefix: () => Promise<string>;
17
+ /** Where the token is used, such as `github-webhook`. */
18
+ readonly label: () => Promise<string | undefined>;
19
+ /** Last time the token authenticated a request. */
20
+ readonly lastUsedAt: () => Promise<string | undefined>;
21
+ /** Scheduled expiry. */
22
+ readonly expiresAt: () => Promise<string | undefined>;
23
+ /** When the token was revoked. */
24
+ readonly revokedAt: () => Promise<string | undefined>;
25
+ /** Creation time. */
26
+ readonly createdAt: () => Promise<string>;
27
+ /** Revoke the token; requests using it fail from now on. */
28
+ revoke(): Promise<void>;
29
+ toJSON(): {
30
+ id: string;
31
+ botId: string;
32
+ detail?: BotTokenRecord;
33
+ };
34
+ }
@@ -0,0 +1,49 @@
1
+ import type { BookingLinkDraft, BookingLink as BookingLinkRecord } from '../../../generated/calendar/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import { MacroEntity } from '../entity';
4
+ import type { Team } from '../teams/team';
5
+ /**
6
+ * A reusable booking page (not a calendar meeting) on the user's or a team's
7
+ * profile: its full draft, the profile revision to edit it at, and the URL
8
+ * guests book through. Paused links (`enabled: false`) stay listed but accept
9
+ * no bookings.
10
+ */
11
+ export declare class BookingLink extends MacroEntity<BookingLinkRecord> {
12
+ /** The team owning the link; undefined for a personal link. */
13
+ readonly team: Team | undefined;
14
+ private constructor();
15
+ protected fetch(): Promise<BookingLinkRecord>;
16
+ /** A handle to a personal link, or a team's when `team` is given. Detail loads on first access. */
17
+ static byId(client: MacroClient, id: string, team?: Team): BookingLink;
18
+ /** A handle seeded with a link record the service returned. */
19
+ static fromRecord(client: MacroClient, record: BookingLinkRecord, team?: Team): BookingLink;
20
+ /** The full editable configuration: event details, hosts, rules, questions and schedule. */
21
+ readonly draft: () => Promise<BookingLinkDraft>;
22
+ /** The profile revision this link was read at; {@link edit} saves against it. */
23
+ readonly revision: () => Promise<number>;
24
+ /** The shareable URL guests book through. */
25
+ webUrl(): Promise<string>;
26
+ /**
27
+ * Replace this link's whole configuration, only after the user replied
28
+ * approving the edited proposal, quoting that reply in `userConfirmation`.
29
+ *
30
+ * Start from {@link draft} and change only what the user asked for. Other
31
+ * links and the personal default hours keep their settings. The edit saves
32
+ * against {@link revision}; when someone saved in between it is refused
33
+ * (409): read the link again and confirm the updated proposal instead of
34
+ * overwriting their change. Returns the saved link.
35
+ */
36
+ edit(draft: BookingLinkDraft, options: {
37
+ userConfirmation: string;
38
+ }): Promise<BookingLink>;
39
+ toJSON(): {
40
+ id: string;
41
+ detail?: BookingLinkRecord | undefined;
42
+ } | {
43
+ url: string;
44
+ id: string;
45
+ detail?: BookingLinkRecord | undefined;
46
+ };
47
+ }
48
+ /** The public booking page of a profile, or of one link on it. */
49
+ export declare function bookingPageUrl(client: MacroClient, profileId: string, slug?: string): string;
@@ -0,0 +1,130 @@
1
+ import type { BookingInsights, BookingLinkDraft, BookingProfile, BookingSchedule } from '../../../generated/calendar/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import { Team } from '../teams/team';
4
+ import { User } from '../users/user';
5
+ import { Booking } from './booking';
6
+ import { BookingLink } from './booking-link';
7
+ /** Whose booking links: the user's own when `team` is omitted, otherwise that team's. */
8
+ export interface BookingScope {
9
+ /** A team the user belongs to; omit for the user's personal booking links. */
10
+ team?: Team;
11
+ }
12
+ /** A profile's booking settings and its public booking page. */
13
+ export interface BookingSettings {
14
+ /** Every setting, with the revision {@link BookingNamespace.saveSettings} saves against. */
15
+ profile: BookingProfile;
16
+ /** The public page listing the profile's links; a revision-0 profile must be saved before sharing it. */
17
+ pageUrl: string;
18
+ }
19
+ /** The user's or a team's booking links, and what a new link can reuse. */
20
+ export interface BookingLinkListing {
21
+ /** Matching links, paused ones included. */
22
+ links: BookingLink[];
23
+ /** Reusable availability schedules to copy into a new draft. */
24
+ schedules: BookingSchedule[];
25
+ /** The user, as the host to name in a personal draft's `hosts`. */
26
+ host: User;
27
+ /** The user's teams, whose links {@link BookingNamespace.links} lists with `team`. */
28
+ teams: Team[];
29
+ /** The profile's public booking page. */
30
+ pageUrl: string;
31
+ }
32
+ /** A local date range for {@link BookingNamespace.insights}. */
33
+ export interface BookingInsightsQuery extends BookingScope {
34
+ /** First local date (`YYYY-MM-DD`), inclusive. */
35
+ from: string;
36
+ /** Last local date (`YYYY-MM-DD`), inclusive; at most 366 days after `from`. */
37
+ to: string;
38
+ /** IANA zone for dates and hour-of-day grouping. */
39
+ timeZone: string;
40
+ /** Only bookings of this link. */
41
+ link?: BookingLink;
42
+ /** Only bookings this user hosts. */
43
+ host?: User;
44
+ }
45
+ /**
46
+ * Booking links (`macro.calendar.booking`): reusable booking pages, the
47
+ * settings behind them, the meetings guests book through them, and their
48
+ * statistics. Personal unless a `team` is given; any team member can read and
49
+ * edit a team's.
50
+ */
51
+ export declare class BookingNamespace {
52
+ private readonly client;
53
+ constructor(client: MacroClient);
54
+ /**
55
+ * List and search the user's booking links (or a team's), with their full
56
+ * drafts, the reusable schedules and the user as host; call this before
57
+ * creating a link. Reading never creates settings.
58
+ *
59
+ * `query` matches link title, slug and description; omit it for every link
60
+ * (at most 100).
61
+ */
62
+ links(options?: BookingScope & {
63
+ query?: string;
64
+ }): Promise<BookingLinkListing>;
65
+ /**
66
+ * Create a booking link only after the user replied approving the full
67
+ * proposal, quoting that reply in `userConfirmation`; never on the request
68
+ * that asked for the link.
69
+ *
70
+ * List {@link links} first and reuse what fits. Before creating, write the
71
+ * whole proposal out for the user: personal or team ownership, the named
72
+ * hosts and who attends, meeting name and description, duration, location,
73
+ * Macro call or Google Meet, time zone, weekly hours and date exceptions,
74
+ * link name, buffers, minimum notice, booking window, slot interval, daily
75
+ * limit, guest questions and whether bookings are enabled. Ask whether to
76
+ * proceed and stop. Never ask the user for ids, revisions or JSON.
77
+ *
78
+ * The draft needs all seven weekdays (Sunday is 0), an IANA time zone and
79
+ * real hosts: a personal link names {@link BookingLinkListing.host} with
80
+ * mode `individual`; a team link uses `collective` or `roundRobin`.
81
+ * `requiresConfirmation` must be false. For video set `macroCall`
82
+ * (preferred) or `googleMeet`, never both. Creating sends no invitations.
83
+ * Replaying an identical draft at the same slug returns the saved link; a
84
+ * different draft at that slug conflicts (409). Share the link's
85
+ * {@link BookingLink.webUrl} as an `<m-booking-link-mention>` chip.
86
+ */
87
+ createLink(draft: BookingLinkDraft, options: BookingScope & {
88
+ userConfirmation: string;
89
+ }): Promise<BookingLink>;
90
+ /**
91
+ * Read every booking setting of the user (or a team): booking-page name and
92
+ * introduction, reusable schedules, default hours and every link. Reading
93
+ * never creates settings.
94
+ */
95
+ settings(options?: BookingScope): Promise<BookingSettings>;
96
+ /**
97
+ * Save the full settings read with {@link settings}, only after the user
98
+ * replied approving the changes; use {@link createLink} and
99
+ * {@link BookingLink.edit} for a single link.
100
+ *
101
+ * Change only what the user asked for and keep every id; generate new
102
+ * UUIDs for new schedules, links and questions. A shared schedule's hours
103
+ * apply to every link using it, and personal default hours apply to team
104
+ * hosting, so name the affected links before changing them. Deleting a link
105
+ * cancels none of its bookings. Saving at a stale revision is refused (409):
106
+ * read again and reconcile instead of overwriting.
107
+ */
108
+ saveSettings(profile: BookingProfile, options?: BookingScope): Promise<BookingSettings>;
109
+ /**
110
+ * Every booking starting in a half-open range (`from` inclusive, `to`
111
+ * exclusive, ISO timestamps with an offset, at most 733 days apart), with
112
+ * guests, answers, attendance and reschedule history. An oversized result
113
+ * fails rather than truncating: narrow the range. Use {@link insights} for
114
+ * statistics.
115
+ */
116
+ bookings(options: BookingScope & {
117
+ from: string;
118
+ to: string;
119
+ }): Promise<Booking[]>;
120
+ /**
121
+ * Booking statistics for local dates, and the equally long period before:
122
+ * totals, completed, rescheduled, cancelled, no-shows, scheduled minutes,
123
+ * daily trends, popular hours and counts by link and host.
124
+ *
125
+ * Failed and processing requests are excluded. Completed means confirmed
126
+ * and ended without a recorded no-show, not verified attendance; minutes
127
+ * are scheduled duration, not call length. No guest contact details.
128
+ */
129
+ insights(query: BookingInsightsQuery): Promise<BookingInsights>;
130
+ }
@@ -0,0 +1,77 @@
1
+ import type { BookingAttendance, Booking as BookingRecord, BookingSlot } from '../../../generated/calendar/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import { MacroEntity } from '../entity';
4
+ import { User } from '../users/user';
5
+ /**
6
+ * A meeting someone booked through one of the user's or their team's booking
7
+ * links. Detail loads through the host's management view, so it needs the
8
+ * personal owner, a host of the meeting or a team administrator.
9
+ */
10
+ export declare class Booking extends MacroEntity<BookingRecord> {
11
+ protected fetch(): Promise<BookingRecord>;
12
+ /** A handle to a booking by id. Detail loads on first access. */
13
+ static byId(client: MacroClient, id: string): Booking;
14
+ /** A handle seeded with a booking record the service returned. */
15
+ static fromRecord(client: MacroClient, record: BookingRecord): Booking;
16
+ /** Meeting title, as it was when the meeting was booked. */
17
+ readonly title: () => Promise<string>;
18
+ /** The guest's name. */
19
+ readonly name: () => Promise<string>;
20
+ /** The guest's email. */
21
+ readonly email: () => Promise<string>;
22
+ /** Absolute start. */
23
+ readonly startsAt: () => Promise<string>;
24
+ /** Absolute end. */
25
+ readonly endsAt: () => Promise<string>;
26
+ /** The guest's IANA display time zone. */
27
+ readonly timeZone: () => Promise<string>;
28
+ /** Lifecycle state. `failed` and `processing` need reconciliation, never a blind retry. */
29
+ readonly status: () => Promise<import("../../../generated/calendar").BookingStatus>;
30
+ /** Recorded attendance; `unknown` until a host records it. */
31
+ readonly attendance: () => Promise<NonNullable<BookingAttendance | undefined> | undefined>;
32
+ /** How many times the meeting moved to another start. */
33
+ readonly rescheduleCount: () => Promise<number | undefined>;
34
+ /** When the meeting last moved, if it ever did. */
35
+ readonly rescheduledAt: () => Promise<string | undefined>;
36
+ /** Final location or conference URL. */
37
+ readonly location: () => Promise<string>;
38
+ /** The guest's answers, keyed by question id; {@link questionLabels} names each question. */
39
+ readonly answers: () => Promise<{
40
+ [key: string]: string;
41
+ }>;
42
+ /** Question labels as they were when the meeting was booked, keyed by question id. */
43
+ readonly questionLabels: () => Promise<{
44
+ [key: string]: string;
45
+ } | undefined>;
46
+ /** The hosts assigned to the meeting. */
47
+ readonly hosts: () => Promise<User[]>;
48
+ /**
49
+ * Available replacement starts on one date (`YYYY-MM-DD`, in the booking
50
+ * schedule's time zone), for {@link reschedule}. Availability is checked
51
+ * again when the meeting moves.
52
+ */
53
+ rescheduleSlots(date: string): Promise<BookingSlot[]>;
54
+ /**
55
+ * Move the meeting to a start returned by {@link rescheduleSlots}; only on
56
+ * the user's go-ahead, since the guest and hosts are notified. Returns the
57
+ * saved booking.
58
+ */
59
+ reschedule(startsAt: string): Promise<Booking>;
60
+ /**
61
+ * Cancel the meeting; only on the user's go-ahead, since the guest and
62
+ * hosts are notified. The booking link stays as it is. Returns the saved
63
+ * booking.
64
+ */
65
+ cancel(): Promise<Booking>;
66
+ /**
67
+ * Approve a legacy pending booking and send its invitations; only on the
68
+ * user's go-ahead. Returns the saved booking.
69
+ */
70
+ approve(): Promise<Booking>;
71
+ /**
72
+ * Record or clear attendance once a confirmed meeting has ended. Returns
73
+ * the saved booking.
74
+ */
75
+ setAttendance(attendance: BookingAttendance): Promise<Booking>;
76
+ private change;
77
+ }
@@ -16,14 +16,21 @@ export declare class Calendar extends MacroEntity<VisibleCalendar> {
16
16
  static byId(client: MacroClient, id: string): Calendar;
17
17
  /** The caller's visible calendars, primaries and writable first. */
18
18
  static list(client: MacroClient): Promise<Calendar[]>;
19
- /** Provider display name. */
19
+ /** Provider display name. Often says whose calendar it is: Google names a
20
+ * person's primary calendar after them or their address. */
20
21
  readonly name: () => Promise<string>;
21
- /** Connected inbox address that syncs this calendar. */
22
+ /** Connected inbox address that syncs this calendar. It stays the user's
23
+ * own address on a calendar someone else shared with them. */
22
24
  readonly emailAddress: () => Promise<string>;
23
- /** Whether this is its account's primary calendar. */
25
+ /** Whether this is its account's primary calendar. The user's other
26
+ * calendars are not primary either, so false does not mean it isn't theirs. */
24
27
  readonly isPrimary: () => Promise<boolean>;
25
- /** Whether the grant can create and modify events on this calendar. */
28
+ /** Whether the grant can create and modify events on this calendar. People
29
+ * can hold that on someone else's calendar, so it does not mean it is theirs. */
26
30
  readonly isWritable: () => Promise<boolean>;
31
+ /** Whether this calendar counts toward the caller's busy time: their
32
+ * setting, by default only the primary calendars of inboxes they own. */
33
+ readonly contributesToAvailability: () => Promise<NonNullable<boolean | undefined> | undefined>;
27
34
  /** Whether this is a subscribed system calendar (holidays, birthdays). */
28
35
  readonly isSubscription: () => Promise<boolean>;
29
36
  /** Provider color, when set. */