@macro-inc/sdk 0.3.0 → 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.
- package/README.md +45 -0
- package/dist/{chunk-Y4HQV7EL.js → chunk-AZJUIUIV.js} +26 -0
- package/dist/{chunk-KPR5JIGY.js → chunk-G43PLP2U.js} +95 -0
- package/dist/{chunk-IIICUUWY.js → chunk-PPR7IWZ7.js} +51 -51
- package/dist/{chunk-PTMBRVEK.js → chunk-PTX2RV2N.js} +84 -0
- package/dist/{chunk-OEHZOKGE.js → chunk-PZPTJI6F.js} +16 -0
- package/dist/{chunk-HR32RQGP.js → chunk-ZLBDES7U.js} +307 -1
- package/dist/generated/agent-fold/index.d.ts +6 -1
- package/dist/generated/agent-harness/index.d.ts +1 -1
- package/dist/generated/agent-harness/index.js +1 -1
- package/dist/generated/agent-harness/sdk.gen.d.ts +44 -1
- package/dist/generated/agent-harness/types.gen.d.ts +699 -0
- package/dist/generated/calendar/index.d.ts +1 -1
- package/dist/generated/calendar/index.js +1 -1
- package/dist/generated/calendar/sdk.gen.d.ts +41 -1
- package/dist/generated/calendar/types.gen.d.ts +904 -2
- package/dist/generated/cognition/index.d.ts +1 -1
- package/dist/generated/cognition/index.js +1 -1
- package/dist/generated/cognition/sdk.gen.d.ts +9 -1
- package/dist/generated/cognition/types.gen.d.ts +79 -0
- package/dist/generated/email/types.gen.d.ts +11 -1
- package/dist/generated/notification/index.js +1 -1
- package/dist/generated/notification/sdk.gen.d.ts +20 -20
- package/dist/generated/notification/types.gen.d.ts +77 -72
- package/dist/generated/scheduled-action/index.d.ts +1 -1
- package/dist/generated/scheduled-action/index.js +1 -1
- package/dist/generated/scheduled-action/sdk.gen.d.ts +4 -1
- package/dist/generated/scheduled-action/types.gen.d.ts +388 -7
- package/dist/generated/storage/index.d.ts +1 -1
- package/dist/generated/storage/index.js +1 -1
- package/dist/generated/storage/sdk.gen.d.ts +151 -1
- package/dist/generated/storage/types.gen.d.ts +3888 -139
- package/dist/src/entities/account-managers/grant.d.ts +39 -0
- package/dist/src/entities/account-managers/namespace.d.ts +17 -0
- package/dist/src/entities/agent-sessions/activity.d.ts +39 -0
- package/dist/src/entities/agent-sessions/agent-session.d.ts +42 -0
- package/dist/src/entities/agent-sessions/namespace.d.ts +7 -1
- package/dist/src/entities/agent-sessions/origin.d.ts +94 -0
- package/dist/src/entities/ai/namespace.d.ts +1 -1
- package/dist/src/entities/bots/bot.d.ts +108 -0
- package/dist/src/entities/bots/namespace.d.ts +15 -4
- package/dist/src/entities/bots/token.d.ts +34 -0
- package/dist/src/entities/calendar/booking-link.d.ts +49 -0
- package/dist/src/entities/calendar/booking-namespace.d.ts +130 -0
- package/dist/src/entities/calendar/booking-namespace.test.d.ts +1 -0
- package/dist/src/entities/calendar/booking.d.ts +77 -0
- package/dist/src/entities/calendar/create-confirmed.test.d.ts +1 -0
- package/dist/src/entities/calendar/namespace.d.ts +63 -15
- package/dist/src/entities/calls/call-record.d.ts +25 -3
- package/dist/src/entities/calls/connection.d.ts +53 -0
- package/dist/src/entities/calls/errors.d.ts +15 -0
- package/dist/src/entities/calls/namespace.d.ts +19 -2
- package/dist/src/entities/calls/participant.d.ts +22 -0
- package/dist/src/entities/channels/channel.d.ts +21 -3
- package/dist/src/entities/channels/namespace.d.ts +3 -3
- package/dist/src/entities/channels/post.d.ts +10 -2
- package/dist/src/entities/channels/thread.d.ts +4 -0
- package/dist/src/entities/chats/chat.d.ts +1 -1
- package/dist/src/entities/chats/namespace.d.ts +14 -1
- package/dist/src/entities/connected-apps/connected-app.d.ts +107 -0
- package/dist/src/entities/connected-apps/connector.d.ts +56 -0
- package/dist/src/entities/connected-apps/namespace.d.ts +74 -0
- package/dist/src/entities/crm/company.d.ts +1 -1
- package/dist/src/entities/crm/pipeline.d.ts +1 -1
- package/dist/src/entities/documents/document.d.ts +156 -7
- package/dist/src/entities/documents/namespace.d.ts +41 -2
- package/dist/src/entities/documents/office-files.d.ts +47 -0
- package/dist/src/entities/email/draft.d.ts +26 -4
- package/dist/src/entities/email/message.d.ts +91 -1
- package/dist/src/entities/email/namespace.d.ts +26 -3
- package/dist/src/entities/email/namespace.test.d.ts +1 -0
- package/dist/src/entities/email/thread.d.ts +7 -2
- package/dist/src/entities/external-chat/namespace.d.ts +2 -0
- package/dist/src/entities/favorites/namespace.d.ts +1 -1
- package/dist/src/entities/harnesses/namespace.d.ts +5 -1
- package/dist/src/entities/images/namespace.d.ts +5 -1
- package/dist/src/entities/me/namespace.d.ts +5 -1
- package/dist/src/entities/meetings/meeting.d.ts +5 -0
- package/dist/src/entities/messages/thread.d.ts +1 -1
- package/dist/src/entities/pins/namespace.d.ts +1 -1
- package/dist/src/entities/projects/namespace.d.ts +1 -1
- package/dist/src/entities/projects/project.d.ts +1 -1
- package/dist/src/entities/search/namespace.d.ts +65 -0
- package/dist/src/entities/search/options.d.ts +29 -0
- package/dist/src/entities/search/types.d.ts +90 -0
- package/dist/src/entities/tasks/namespace.d.ts +1 -1
- package/dist/src/entities/tasks/task.d.ts +4 -3
- package/dist/src/entities/users/namespace.d.ts +1 -1
- package/dist/src/entities/whatsapp/namespace.d.ts +2 -0
- package/dist/src/entities/workspace/items.d.ts +7 -0
- package/dist/src/entities/workspace/namespace.d.ts +14 -9
- package/dist/src/entities/workspace/query.d.ts +23 -0
- package/dist/src/entities/workspace/types.d.ts +6 -3
- package/dist/src/events/hydrate/call.d.ts +101 -0
- package/dist/src/events/types.d.ts +2 -1
- package/dist/src/macro.d.ts +33 -1
- package/dist/src/macro.js +6423 -4265
- package/dist/src/utils/activity.d.ts +23 -2
- package/package.json +1 -1
- package/dist/src/entities/search.d.ts +0 -53
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
import type { AccountManagerGrant as AccountManagerGrantRecord } from '../../../generated/storage/types.gen';
|
|
2
|
+
import type { MacroClient } from '../../utils/client';
|
|
3
|
+
import { MacroEntity } from '../entity';
|
|
4
|
+
import { User } from '../users/user';
|
|
5
|
+
/** A request for an agent account to manage a person's account, and what became of it. */
|
|
6
|
+
export declare class AccountManagerGrant extends MacroEntity<AccountManagerGrantRecord> {
|
|
7
|
+
/** Construct a lazy grant handle. */
|
|
8
|
+
static byId(client: MacroClient, id: string): AccountManagerGrant;
|
|
9
|
+
/** Seed from a fetched grant. */
|
|
10
|
+
static from(client: MacroClient, record: AccountManagerGrantRecord): AccountManagerGrant;
|
|
11
|
+
protected fetch(): Promise<AccountManagerGrantRecord>;
|
|
12
|
+
/** Where the grant is: `pending`, `approved`, `active`, `declined`, `revoked`, or `expired`. */
|
|
13
|
+
readonly status: () => Promise<import("../../../generated/storage").AccountManagerGrantStatus>;
|
|
14
|
+
/** The side that asked: `managed` or `manager`. */
|
|
15
|
+
readonly requestedBy: () => Promise<import("../../../generated/storage").AccountManagerRole>;
|
|
16
|
+
/** When the request was made. */
|
|
17
|
+
readonly createdAt: () => Promise<string>;
|
|
18
|
+
/** When the pending request or unclaimed approval stops being usable. */
|
|
19
|
+
readonly expiresAt: () => Promise<string | undefined>;
|
|
20
|
+
/** When the manager claimed the token. */
|
|
21
|
+
readonly claimedAt: () => Promise<string | undefined>;
|
|
22
|
+
/** When the token was last used, to the minute. */
|
|
23
|
+
readonly lastUsedAt: () => Promise<string | undefined>;
|
|
24
|
+
/** The account being managed. */
|
|
25
|
+
managed(): Promise<User>;
|
|
26
|
+
/** The agent account doing the managing. */
|
|
27
|
+
manager(): Promise<User>;
|
|
28
|
+
/** Approve a request you didn't make. Only the side that didn't ask can. */
|
|
29
|
+
approve(): Promise<void>;
|
|
30
|
+
/** Decline a request you didn't make. Only the side that didn't ask can. */
|
|
31
|
+
decline(): Promise<void>;
|
|
32
|
+
/**
|
|
33
|
+
* Get the token for the managed account. Only the manager can, and only once:
|
|
34
|
+
* save it now. Use it as the SDK's `token` to act as the managed account.
|
|
35
|
+
*/
|
|
36
|
+
claimToken(): Promise<string>;
|
|
37
|
+
/** End the grant, stopping its token immediately. Either side can. */
|
|
38
|
+
revoke(): Promise<void>;
|
|
39
|
+
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import type { MacroClient } from '../../utils/client';
|
|
2
|
+
import type { User } from '../users/user';
|
|
3
|
+
import { AccountManagerGrant } from './grant';
|
|
4
|
+
/** Account managers: an agent account's full access to a person's account. */
|
|
5
|
+
export declare class AccountManagerNamespace {
|
|
6
|
+
private readonly client;
|
|
7
|
+
constructor(client: MacroClient);
|
|
8
|
+
/** Construct a lazy grant handle. */
|
|
9
|
+
byId(id: string): AccountManagerGrant;
|
|
10
|
+
/** List the approved and active managers of the caller's account. */
|
|
11
|
+
list(): Promise<AccountManagerGrant[]>;
|
|
12
|
+
/** Ask to manage `user`'s account, in your DM. The caller must be an agent account and `user` a person. */
|
|
13
|
+
askToManage(user: User): Promise<AccountManagerGrant>;
|
|
14
|
+
/** Ask `user`, an agent account, to manage the caller's account, in your DM. The caller must be a person. */
|
|
15
|
+
askToBeManagedBy(user: User): Promise<AccountManagerGrant>;
|
|
16
|
+
private request;
|
|
17
|
+
}
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
import type { ActivityWireRow } from '../../../generated/agent-harness/types.gen';
|
|
2
|
+
import type { MacroClient } from '../../utils/client';
|
|
3
|
+
import type { AgentSession } from './agent-session';
|
|
4
|
+
/** Page options for recorded session activity, newest first. */
|
|
5
|
+
export type AgentActivityOptions = {
|
|
6
|
+
/** Page size, from 1 to 100; defaults to 50. */
|
|
7
|
+
limit?: number;
|
|
8
|
+
/** Restrict to one code-mode invocation belonging to this session. */
|
|
9
|
+
invocation?: AgentInvocation;
|
|
10
|
+
};
|
|
11
|
+
/** A code-mode invocation, identified independently of its runtime or retries. */
|
|
12
|
+
export declare class AgentInvocation {
|
|
13
|
+
private readonly client;
|
|
14
|
+
private readonly parent;
|
|
15
|
+
readonly id: string;
|
|
16
|
+
private constructor();
|
|
17
|
+
/** Construct a handle without making a request. */
|
|
18
|
+
static byId(client: MacroClient, session: AgentSession, id: string): AgentInvocation;
|
|
19
|
+
/** The session that owns this invocation. */
|
|
20
|
+
session(): AgentSession;
|
|
21
|
+
/** Recorded activity caused by this invocation, lazily paginated. */
|
|
22
|
+
activity(options?: Omit<AgentActivityOptions, 'invocation'>): AsyncGenerator<AgentActivity, any, any>;
|
|
23
|
+
/** Safe identity without an authenticated client. */
|
|
24
|
+
toJSON(): {
|
|
25
|
+
id: string;
|
|
26
|
+
session: {
|
|
27
|
+
id: string;
|
|
28
|
+
};
|
|
29
|
+
};
|
|
30
|
+
}
|
|
31
|
+
/** An original activity-history row attributed to a session. */
|
|
32
|
+
export type AgentActivity = {
|
|
33
|
+
/** The originating invocation; absent on legacy rows. */
|
|
34
|
+
invocation?: AgentInvocation;
|
|
35
|
+
/** Original recorded metadata. Action tags and payloads are forward-compatible. */
|
|
36
|
+
snapshot: ActivityWireRow;
|
|
37
|
+
};
|
|
38
|
+
/** Iterate recorded mutations; reads and failed requests do not create history. */
|
|
39
|
+
export declare function sessionActivity(client: MacroClient, session: AgentSession, options?: AgentActivityOptions): AsyncGenerator<AgentActivity>;
|
|
@@ -6,7 +6,9 @@ import { MacroEntity } from '../entity';
|
|
|
6
6
|
import { EntityAccess } from '../sharing/access';
|
|
7
7
|
import { type SharePermissionOptions } from '../sharing/permissions';
|
|
8
8
|
import { User } from '../users/user';
|
|
9
|
+
import { type AgentActivityOptions, AgentInvocation } from './activity';
|
|
9
10
|
import { CodeExecution } from './code-execution';
|
|
11
|
+
import { type SessionOrigin } from './origin';
|
|
10
12
|
import { QueuedAction } from './queued-action';
|
|
11
13
|
import { type CreateReviewOptions, SessionReview } from './review';
|
|
12
14
|
import { ToolApproval } from './tool-approval';
|
|
@@ -45,6 +47,15 @@ export type FoldedAgentSessionLog = {
|
|
|
45
47
|
messages: FoldedMessage[];
|
|
46
48
|
};
|
|
47
49
|
/** A GitHub pull request linked to a session. */
|
|
50
|
+
/** An agent session an account registered as its work. */
|
|
51
|
+
export type RegisteredWork = {
|
|
52
|
+
/** The session registered. */
|
|
53
|
+
session: AgentSession;
|
|
54
|
+
/** The account whose work this is. */
|
|
55
|
+
account: User;
|
|
56
|
+
/** When the account registered it. */
|
|
57
|
+
registeredAt: string;
|
|
58
|
+
};
|
|
48
59
|
export type SessionPullRequest = {
|
|
49
60
|
/** The pull request's `owner/repo/pull/number` key. */
|
|
50
61
|
githubKey: string;
|
|
@@ -155,6 +166,11 @@ export declare class AgentSession extends MacroEntity<AgentSessionResponse> {
|
|
|
155
166
|
protected fetch(): Promise<AgentSessionResponse>;
|
|
156
167
|
/** The session's user-facing display name. */
|
|
157
168
|
readonly name: () => Promise<string>;
|
|
169
|
+
/**
|
|
170
|
+
* What opened the session: who or what started it, and what it is about.
|
|
171
|
+
* Readable by anyone who can view the session, including other agents.
|
|
172
|
+
*/
|
|
173
|
+
origin(): Promise<SessionOrigin>;
|
|
158
174
|
/**
|
|
159
175
|
* Who archived the session, making it read-only: `'user'`,
|
|
160
176
|
* `'pull_request_merged'` or `'runtime_closed'`. `undefined` while it is not
|
|
@@ -213,6 +229,26 @@ export declare class AgentSession extends MacroEntity<AgentSessionResponse> {
|
|
|
213
229
|
setAutoArchive(overrides: AutoArchiveOverrides): Promise<void>;
|
|
214
230
|
/** Rename this session. */
|
|
215
231
|
rename(name: string): Promise<void>;
|
|
232
|
+
/**
|
|
233
|
+
* Register this session as the caller's work, so it shows as what the caller
|
|
234
|
+
* is working on. Requires edit access. Registering again changes nothing.
|
|
235
|
+
*
|
|
236
|
+
* Registering does not share the session: a viewer who cannot open it does
|
|
237
|
+
* not see it, so share it too with {@link AgentSession.updateSharePermissions}.
|
|
238
|
+
*
|
|
239
|
+
* The registration ends on its own when the session's pull requests finish,
|
|
240
|
+
* when it is archived, after a day without work, or after a week blocked on
|
|
241
|
+
* input. A later turn does not register it again.
|
|
242
|
+
*/
|
|
243
|
+
registerAsWork(): Promise<RegisteredWork>;
|
|
244
|
+
/**
|
|
245
|
+
* End the caller's registration of this session as its work. Doing it again
|
|
246
|
+
* changes nothing. The session itself is untouched.
|
|
247
|
+
*/
|
|
248
|
+
unregisterAsWork(): Promise<void>;
|
|
249
|
+
/** The caller's active registrations, newest first. */
|
|
250
|
+
static listRegisteredWork(client: MacroClient): Promise<RegisteredWork[]>;
|
|
251
|
+
private static registeredWork;
|
|
216
252
|
/** Archive this session, making it read-only until unarchived. */
|
|
217
253
|
archive(): Promise<void>;
|
|
218
254
|
/** Restore an archived session so it can be edited and prompted again. */
|
|
@@ -284,6 +320,12 @@ export declare class AgentSession extends MacroEntity<AgentSessionResponse> {
|
|
|
284
320
|
readonly codeExecutions: {
|
|
285
321
|
byId: (id: string) => CodeExecution;
|
|
286
322
|
};
|
|
323
|
+
/** Recorded activity caused by this session, lazily paginated newest first. */
|
|
324
|
+
activity(options?: AgentActivityOptions): AsyncGenerator<import("./activity").AgentActivity, any, any>;
|
|
325
|
+
/** Code-mode invocation handles, distinct from saved code executions. */
|
|
326
|
+
readonly invocations: {
|
|
327
|
+
byId: (id: string) => AgentInvocation;
|
|
328
|
+
};
|
|
287
329
|
/** Delete this session and any live resources it owns. */
|
|
288
330
|
delete(): Promise<void>;
|
|
289
331
|
}
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import type { AgentMode, AutoArchivePreferencesBody, CodingPreferencesBody, SandboxSize } from '../../../generated/agent-harness/types.gen';
|
|
2
2
|
import type { MacroClient } from '../../utils/client';
|
|
3
|
-
import { AgentSession, type CreateManagedSessionOptions, type SelectableRepository } from './agent-session';
|
|
3
|
+
import { AgentSession, type CreateManagedSessionOptions, type RegisteredWork, type SelectableRepository } from './agent-session';
|
|
4
4
|
/**
|
|
5
5
|
* Entry point for coding-agent sessions.
|
|
6
6
|
*
|
|
@@ -44,6 +44,12 @@ export declare class AgentSessionNamespace {
|
|
|
44
44
|
* and it starts as Cursor.
|
|
45
45
|
*/
|
|
46
46
|
createManaged(opts?: CreateManagedSessionOptions): Promise<AgentSession>;
|
|
47
|
+
/**
|
|
48
|
+
* The sessions the caller registered as its work with
|
|
49
|
+
* {@link AgentSession.registerAsWork} and can still view, newest first.
|
|
50
|
+
* Ended registrations and archived sessions are left out.
|
|
51
|
+
*/
|
|
52
|
+
registeredWork(): Promise<RegisteredWork[]>;
|
|
47
53
|
/**
|
|
48
54
|
* Whether `prompt` needs a chat agent (`'chat'`) or a coding agent
|
|
49
55
|
* (`'code'`), as the app's Auto mode decides before starting a session.
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
import type { TriggerOrigin } from '../../../generated/agent-harness/types.gen';
|
|
2
|
+
import type { MacroClient } from '../../utils/client';
|
|
3
|
+
import { Agent } from '../agents/agent';
|
|
4
|
+
import { Message } from '../channels/message';
|
|
5
|
+
import { Initiative } from '../initiatives/initiative';
|
|
6
|
+
import { Routine } from '../routines/routine';
|
|
7
|
+
import { Task } from '../tasks/task';
|
|
8
|
+
import { User } from '../users/user';
|
|
9
|
+
import { AgentSession } from './agent-session';
|
|
10
|
+
/** The first non-agent cause of an agent's work. */
|
|
11
|
+
export type SessionOriginRoot = {
|
|
12
|
+
type: 'person';
|
|
13
|
+
user: User;
|
|
14
|
+
} | {
|
|
15
|
+
type: 'routine';
|
|
16
|
+
routine: Routine;
|
|
17
|
+
};
|
|
18
|
+
/** Where an acting agent's own work came from. */
|
|
19
|
+
export type SessionOriginLineage = {
|
|
20
|
+
type: 'session';
|
|
21
|
+
/** The session the agent acted from. */
|
|
22
|
+
session: AgentSession;
|
|
23
|
+
/** Where the chain of agents started. */
|
|
24
|
+
root: SessionOriginRoot;
|
|
25
|
+
}
|
|
26
|
+
/** An agent acted, but its session was not captured. */
|
|
27
|
+
| {
|
|
28
|
+
type: 'unattributed';
|
|
29
|
+
};
|
|
30
|
+
/** Who did something that opened a session. */
|
|
31
|
+
export type SessionOriginCaller = {
|
|
32
|
+
type: 'person';
|
|
33
|
+
user: User;
|
|
34
|
+
} | {
|
|
35
|
+
type: 'agent';
|
|
36
|
+
/** The agent that acted. */
|
|
37
|
+
agent: Agent;
|
|
38
|
+
/** The person it acted for. */
|
|
39
|
+
onBehalfOf: User;
|
|
40
|
+
/** Where the agent's own work came from. */
|
|
41
|
+
lineage: SessionOriginLineage;
|
|
42
|
+
};
|
|
43
|
+
/** What opened a session. */
|
|
44
|
+
export type SessionOrigin =
|
|
45
|
+
/** A message mentioned the agent. `message` is set for channel messages. */
|
|
46
|
+
{
|
|
47
|
+
kind: 'mentioned';
|
|
48
|
+
by: SessionOriginCaller;
|
|
49
|
+
message?: Message;
|
|
50
|
+
}
|
|
51
|
+
/** A person wrote in their private conversation with the agent. */
|
|
52
|
+
| {
|
|
53
|
+
kind: 'conversation';
|
|
54
|
+
by: User;
|
|
55
|
+
message?: Message;
|
|
56
|
+
}
|
|
57
|
+
/** The agent was added to a task's assignees. */
|
|
58
|
+
| {
|
|
59
|
+
kind: 'task_assigned';
|
|
60
|
+
by: SessionOriginCaller;
|
|
61
|
+
task: Task;
|
|
62
|
+
}
|
|
63
|
+
/** The task joined a project, and inherited the project's agents. */
|
|
64
|
+
| {
|
|
65
|
+
kind: 'project_inherited';
|
|
66
|
+
by: SessionOriginCaller;
|
|
67
|
+
task: Task;
|
|
68
|
+
project: Initiative;
|
|
69
|
+
}
|
|
70
|
+
/** A person opened the session directly, from the composer. */
|
|
71
|
+
| {
|
|
72
|
+
kind: 'requested';
|
|
73
|
+
by: User;
|
|
74
|
+
}
|
|
75
|
+
/** A tool handed the agent work, under this user's authority. */
|
|
76
|
+
| {
|
|
77
|
+
kind: 'dispatched';
|
|
78
|
+
onBehalfOf: User;
|
|
79
|
+
}
|
|
80
|
+
/** A routine fired. */
|
|
81
|
+
| {
|
|
82
|
+
kind: 'routine';
|
|
83
|
+
routine: Routine;
|
|
84
|
+
firing: 'scheduled' | 'manual' | 'event';
|
|
85
|
+
}
|
|
86
|
+
/** Nothing recorded it: an older session, or an unclaimed warm one. */
|
|
87
|
+
| {
|
|
88
|
+
kind: 'unknown';
|
|
89
|
+
};
|
|
90
|
+
/**
|
|
91
|
+
* A session's origin as handles. A message handle needs its channel, which is
|
|
92
|
+
* the session's own thread channel; other parents leave `message` unset.
|
|
93
|
+
*/
|
|
94
|
+
export declare function sessionOrigin(client: MacroClient, origin: TriggerOrigin, channelId: string | undefined): SessionOrigin;
|
|
@@ -5,7 +5,7 @@ export type { DecisionRequest, DecisionResponse, StructuredCompletionRequest, St
|
|
|
5
5
|
/**
|
|
6
6
|
* Shared cognition endpoints, charged to the authenticated acting user.
|
|
7
7
|
*
|
|
8
|
-
* @routing Use when generating structured objects or
|
|
8
|
+
* @routing Use when generating structured objects or classifying supplied content with Jev; not generating images (`macro.images`) or answering the user yourself.
|
|
9
9
|
*/
|
|
10
10
|
export declare class AiNamespace {
|
|
11
11
|
private readonly client;
|
|
@@ -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,19 +1,30 @@
|
|
|
1
|
-
import type {
|
|
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
|
-
*
|
|
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.
|
|
6
8
|
*
|
|
7
9
|
* @routing Use when inspecting or managing bots and their channel access; not an agent's instructions, which are agents.
|
|
8
10
|
*/
|
|
9
11
|
export declare class BotsNamespace {
|
|
10
12
|
private readonly client;
|
|
11
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>;
|
|
12
23
|
/**
|
|
13
24
|
* The authenticated bot's own record. Requires bot auth; with a user API
|
|
14
25
|
* key this throws (a user token has no bot identity).
|
|
15
26
|
*/
|
|
16
|
-
me(): Promise<
|
|
27
|
+
me(): Promise<BotRecord>;
|
|
17
28
|
/**
|
|
18
29
|
* Channels containing the authenticated bot. Requires bot auth.
|
|
19
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 @@
|
|
|
1
|
+
export {};
|