@arbium/enterprise-agent-connect-client 0.0.0-stage → 0.1.2-dev.d2aa5ca

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 (10) hide show
  1. package/lib/index.d.ts +1269 -0
  2. package/lib/index.js +235 -0
  3. package/lib/schema.d.ts +6439 -0
  4. package/lib/schema.js +5 -0
  5. package/lib/steps.d.ts +1422 -0
  6. package/lib/steps.js +716 -0
  7. package/lib/types.d.ts +62 -0
  8. package/lib/types.js +1 -0
  9. package/package.json +19 -4
  10. package/README.md +0 -3
package/lib/steps.d.ts ADDED
@@ -0,0 +1,1422 @@
1
+ import type { Agent, AgentStep, Capability, CertificateInfo, Check, CheckOutcome, ChosenOption, Connection, Connector, Field, LiveCheck, Limits, Provider, ProviderConnection, SiteAccess, Step, TeamsBot, TeamsPlace, TeamsRun, TeamsTrigger, TeamsTriggerInput } from "./types.js";
2
+ /** A copy block's text: a line with {scope} repeats once per scope, {scopes} becomes the
3
+ * scopes space-separated, and any other {key} is filled from the connection's settings.
4
+ * Unknown placeholders stay visible so a missing value is obvious. */
5
+ export declare function expandCopy(lines: string[], scopes: string[], config?: Record<string, string>,
6
+ /** How {scopes} is joined, e.g. ", " in click steps people read. */
7
+ joiner?: string): string;
8
+ /** {name} values the ticked capabilities fill into steps, later ones winning, e.g. the
9
+ * site role: read, or write once adding files is ticked. */
10
+ export declare function fillsFor(connector: Connector, ticked: readonly string[]): Record<string, string>;
11
+ /** The choice fields' values: the stored or typed one, else each field's first option, which
12
+ * also holds while the earlier choice a field `requires` is not made. */
13
+ export declare function choiceValues(connector: {
14
+ fields: Field[];
15
+ }, values: Record<string, string>): Record<string, string>;
16
+ /** True with no condition, or while its option is the chosen one. */
17
+ export declare const isChosen: (option: ChosenOption | undefined, chosen: Record<string, string>) => boolean;
18
+ /** The choice fields shown: one that `requires` an earlier choice only while it is made. */
19
+ export declare const askedFields: (fields: Field[], values: Record<string, string>) => Field[];
20
+ /** The steps that apply under the chosen options (a step with `option` only while chosen). */
21
+ export declare function chosenSteps(connector: Connector, steps: Step[], values: Record<string, string>): Step[];
22
+ /** Choices that change the permissions the setup steps ask for: made in step 1, with what
23
+ * agents may do, so the steps after it already show those permissions. */
24
+ export declare function permissionChoices(connector: Connector): Field[];
25
+ /** Permissions the chosen options need, e.g. Sites.Read.All for reading every site. */
26
+ export declare function optionScopes(connector: Connector, values: Record<string, string>): string[];
27
+ /** {site} and {siteRef} (how Graph and PowerShell name it: host, or host:/path) for a site's
28
+ * grant steps and note. */
29
+ export declare function siteFills(site: string): Record<string, string>;
30
+ /** The note to send whoever manages SharePoint: the connector's request with the site, the
31
+ * app and the role filled, and its first grant step's commands where it says
32
+ * {grantCommands}. */
33
+ /** The site grant steps for the site role the ticks need (`site_role`). */
34
+ export declare function grantSteps(connector: Connector, siteRole: string | undefined): Step[];
35
+ export declare function siteRequest(connector: Connector, site: string, scopes: string[], config: Record<string, string>): string;
36
+ /** The apps a key uses, in the order the apps are listed. */
37
+ export declare function keyApps(agent: Agent, connectors: Connector[]): Connector[];
38
+ /** How many active keys use an app (a disabled key uses nothing). */
39
+ export declare function keysUsing(agents: Agent[], connectorId: string): number;
40
+ /** The values a connected app reported for its discover probe, e.g. Jira project keys. */
41
+ export declare function discovered(connector: Connector, checks: Check[] | null): string[];
42
+ /** Parses free-typed list input ("KAN, SAM1") into values. */
43
+ export declare function splitList(raw: string): string[];
44
+ /** Shown under Click through for a step the vendor offers only as commands. */
45
+ export declare const CLICK_UNAVAILABLE = "Microsoft has no admin center page for this step: it is done only with commands. Open Commands, or send them to whoever manages it.";
46
+ /** What a free-typed list box shows: the admin's own text while it still parses to the
47
+ * saved values (so a typed comma or space stays put), else the values themselves. */
48
+ export declare function listText(typed: string, values: string[]): string;
49
+ /** Scopes or in-app permissions the ticked capabilities need, in connector order, each once. */
50
+ export declare function neededFor(connector: Connector, ticked: readonly string[], kind: "scopes" | "permissions"): string[];
51
+ /** The capabilities after ticking or unticking one, in connector order. Required ones stay on;
52
+ * a destructive one is only turned on when `confirm` accepts its warning. */
53
+ export declare function toggleCapability(connector: Connector, current: readonly string[], id: string, on: boolean, confirm: (warning: string) => boolean): string[];
54
+ export declare function destructiveWarning(connector: Connector, capability: Capability): string;
55
+ /** needs_steps: on, but a step on its page is not done yet. needs_attention: on, but a live
56
+ * check of it could not run, so whether it works is not known. */
57
+ export type AppStatus = "connected" | "needs_reconnect" | "not_connected" | "needs_steps" | "needs_attention";
58
+ /** The provider form's values to send: only the fields on show, so a secret typed and then
59
+ * hidden by going back to the certificate is not sent (a secret sent wins the sign-in). */
60
+ export declare function providerFields(fields: readonly {
61
+ id: string;
62
+ secret?: boolean;
63
+ }[], useSecret: boolean, values: Record<string, string>): Record<string, string>;
64
+ /** Whether a provider connection is usable by its apps. */
65
+ export declare function providerReady(connection: ProviderConnection | null): boolean;
66
+ /** A provider connection's status, as its card and page show it. */
67
+ export declare function providerStatus(connection: ProviderConnection | null): AppStatus;
68
+ /** The Integrations tab's layout: apps of their own first, then each provider's apps
69
+ * together under it, by their `order`, then name. Providers without apps are left out. */
70
+ export declare function groupByProvider<T extends {
71
+ provider?: string;
72
+ order?: number;
73
+ name: string;
74
+ }>(apps: T[], providers: Provider[]): {
75
+ provider: Provider | null;
76
+ apps: T[];
77
+ }[];
78
+ /** What the Integrations tab says about a provider connection: its certificate running out
79
+ * with no new one waiting (every app of it stops that day). */
80
+ export declare function certificateNotice(connection: ProviderConnection | null, now?: number): {
81
+ expiresAt: string;
82
+ } | null;
83
+ /** A certificate expiring within this many days is called out. */
84
+ export declare const CERTIFICATE_WARNING_DAYS = 30;
85
+ export declare function expiresSoon(info: CertificateInfo, now?: number): boolean;
86
+ /** How a provider connection signs in, in the admin's words. */
87
+ export declare function signInMethod(connection: ProviderConnection): string;
88
+ /** A saved connection whose last check failed needs reconnecting, as does one marked so; one
89
+ * whose check passed with a warning (e.g. Jira can browse no project yet) needs steps. */
90
+ export declare function appStatus(connection: Connection | null, healthy?: boolean, warned?: boolean): AppStatus;
91
+ /** A check that passed but found something to do. */
92
+ export declare function checkWarned(health: CheckOutcome | null | undefined): boolean;
93
+ /** What an app's own page shows, so it never contradicts its badge: a failed check, a failed
94
+ * recorded check, or a check that passed with a warning each offer Check again, and a warning
95
+ * leaves Prepare and "What agents can see" not done. */
96
+ export declare function appPageState(connection: Connection | null, health: CheckOutcome | null | undefined): {
97
+ notice: "failed" | "recorded" | "warned" | null;
98
+ prepareDone: boolean;
99
+ seeDone: boolean;
100
+ };
101
+ /** An app of its own on the Integrations tab: its stored status, then its live read-only
102
+ * check (failed: needs reconnecting; could not run: needs attention; warned: needs steps).
103
+ * Before the check answers (`checks` null in `integrationCards`), the stored status alone. */
104
+ export declare function cardStatus(connection: Connection | null, check: CheckOutcome | null): AppStatus;
105
+ /** A provider's status as its card and its page's header show it: the sign-in's, then its
106
+ * apps' (reconnecting, attention, steps), with how many apps are on and how many need steps
107
+ * or attention, each app counted by `appState`, as its row and its own page show it. */
108
+ export declare function providerSummary(definition: Provider, connection: ProviderConnection | null, apps: {
109
+ connector: Connector;
110
+ connection: Connection | null;
111
+ state: AppLive;
112
+ }[], confirmed: string[]): {
113
+ status: AppStatus;
114
+ on: number;
115
+ steps: number;
116
+ attention: number;
117
+ };
118
+ export type TeamsStep = {
119
+ label: string;
120
+ done: boolean;
121
+ detail?: string;
122
+ };
123
+ /** Where a bot's setup stands, in the order the admin does it. The service sees what Add to Teams
124
+ * made and what it published; Teams telling it the bot was added somewhere proves the rest. */
125
+ export declare function teamsSetup(bot: TeamsBot | null): TeamsStep[];
126
+ export declare function placeName(place: TeamsPlace): string;
127
+ /** The trigger form as typed: dollars per answer and per day, comma or space separated ids,
128
+ * the teams it answers in as ticked group ids. */
129
+ export type TriggerForm = {
130
+ enabled: boolean;
131
+ /** Kept as loaded, with its settings: the form edits a Claude trigger's fields only. */
132
+ runner: string;
133
+ settings: Record<string, unknown>;
134
+ managedAgentId: string;
135
+ environmentId: string;
136
+ vaultIds: string;
137
+ budgetDollars: string;
138
+ dailyDollars: string;
139
+ maxRunsPerHour: string;
140
+ replyMode: "mentions" | "all";
141
+ allowedTeams: string[];
142
+ allowedPeople: string;
143
+ anyoneInOrganization: boolean;
144
+ };
145
+ /** The service's default runner, the only one whose fields the trigger form edits. */
146
+ export declare const CLAUDE_RUNNER = "claude-managed-agents";
147
+ export declare function triggerForm(trigger: TeamsTrigger | null): TriggerForm;
148
+ /** The trigger to save, or what to fix. The service checks again, and that the Claude agent
149
+ * and environment exist under the organization's key. */
150
+ export declare function triggerInput(form: TriggerForm): {
151
+ ok: true;
152
+ value: Omit<TeamsTriggerInput, "by">;
153
+ } | {
154
+ ok: false;
155
+ error: string;
156
+ };
157
+ /** One answer in Recent Teams activity, in the admin's words. */
158
+ export declare function runSummary(run: TeamsRun): string;
159
+ /** An agent's address, limited to characters that are inert inside the commands it fills. */
160
+ export declare const AGENT_EMAIL: RegExp;
161
+ /** A Teams bot's name: the setup script hands it to az, which runs through cmd.exe on Windows,
162
+ * so only characters inert there (the same rule as the service's). */
163
+ export declare const BOT_NAME: RegExp;
164
+ /** A key's name as a starting bot name: other characters become spaces. */
165
+ export declare function botNameFrom(name: string): string;
166
+ /** {agentEmail} and {agentName} (the part before the @) for the add-an-agent steps. */
167
+ export declare function agentFills(email: string): Record<string, string>;
168
+ /** The add-an-agent steps for the apps ticked on a new key. */
169
+ export declare function agentSteps(provider: Provider, on: readonly string[]): AgentStep[];
170
+ /** What a new key's agent needs outside the service for the apps ticked on it: its email where an
171
+ * app opens the agent's own address (its mailbox), each provider's steps for those apps, and
172
+ * the apps that give each agent its own bot. Apps with nothing per agent add nothing. */
173
+ export declare function newKeySetup(ticked: Connector[], providers: Provider[]): {
174
+ addressed: {
175
+ id: string;
176
+ name: string;
177
+ description: string;
178
+ logo: string;
179
+ identity: string;
180
+ signsInAs?: "agentBot";
181
+ provider?: string;
182
+ order?: number;
183
+ connectionKind: "guided";
184
+ accountKey: string;
185
+ scopes?: string[];
186
+ setup: {
187
+ title: string;
188
+ body: string;
189
+ link?: {
190
+ label: string;
191
+ href: string;
192
+ };
193
+ copy?: string[];
194
+ shell?: "bash" | "powershell";
195
+ permissions?: boolean;
196
+ certificate?: boolean;
197
+ click?: string[];
198
+ clickUnavailable?: true;
199
+ siteRole?: "read" | "write";
200
+ agentCheck?: boolean;
201
+ confirm?: string;
202
+ live?: string;
203
+ settings?: {
204
+ id: string;
205
+ label: string;
206
+ help?: string;
207
+ placeholder?: string;
208
+ pattern: string;
209
+ }[];
210
+ option?: {
211
+ field: string;
212
+ value: string;
213
+ };
214
+ }[];
215
+ afterConnect: {
216
+ title: string;
217
+ body: string;
218
+ link?: {
219
+ label: string;
220
+ href: string;
221
+ };
222
+ copy?: string[];
223
+ shell?: "bash" | "powershell";
224
+ permissions?: boolean;
225
+ certificate?: boolean;
226
+ click?: string[];
227
+ clickUnavailable?: true;
228
+ siteRole?: "read" | "write";
229
+ agentCheck?: boolean;
230
+ confirm?: string;
231
+ live?: string;
232
+ settings?: {
233
+ id: string;
234
+ label: string;
235
+ help?: string;
236
+ placeholder?: string;
237
+ pattern: string;
238
+ }[];
239
+ option?: {
240
+ field: string;
241
+ value: string;
242
+ };
243
+ }[];
244
+ fields: {
245
+ id: string;
246
+ label: string;
247
+ help?: string;
248
+ placeholder?: string;
249
+ secret: boolean;
250
+ options?: {
251
+ value: string;
252
+ label: string;
253
+ description: string;
254
+ scopes?: string[];
255
+ }[];
256
+ requires?: {
257
+ field: string;
258
+ value: string;
259
+ };
260
+ }[];
261
+ capabilities: {
262
+ id: string;
263
+ label: string;
264
+ description: string;
265
+ required: boolean;
266
+ destructive: boolean;
267
+ costs?: boolean;
268
+ scopes: string[];
269
+ roles?: string[];
270
+ permissions: string[];
271
+ fill?: {
272
+ [key: string]: string;
273
+ };
274
+ note?: string;
275
+ forbidden?: string;
276
+ claudeKey?: boolean;
277
+ tools: string[];
278
+ }[];
279
+ limits: {
280
+ id: string;
281
+ label: string;
282
+ help: string;
283
+ kind: "list" | "text" | "map";
284
+ required: boolean;
285
+ pattern?: string;
286
+ keys?: string;
287
+ }[];
288
+ siteAccess?: {
289
+ grant: {
290
+ title: string;
291
+ body: string;
292
+ link?: {
293
+ label: string;
294
+ href: string;
295
+ };
296
+ copy?: string[];
297
+ shell?: "bash" | "powershell";
298
+ permissions?: boolean;
299
+ certificate?: boolean;
300
+ click?: string[];
301
+ clickUnavailable?: true;
302
+ siteRole?: "read" | "write";
303
+ agentCheck?: boolean;
304
+ confirm?: string;
305
+ live?: string;
306
+ settings?: {
307
+ id: string;
308
+ label: string;
309
+ help?: string;
310
+ placeholder?: string;
311
+ pattern: string;
312
+ }[];
313
+ option?: {
314
+ field: string;
315
+ value: string;
316
+ };
317
+ }[];
318
+ request: string;
319
+ write: string[];
320
+ };
321
+ agentAccess?: {
322
+ limit: string;
323
+ label: string;
324
+ path: string & (unknown & unknown);
325
+ granted: string;
326
+ notGranted: string;
327
+ notFound: string;
328
+ probes: {
329
+ [key: string]: {
330
+ method: "GET" | "POST" | "PATCH";
331
+ path: string & (unknown & unknown);
332
+ body?: unknown;
333
+ allowed: number[];
334
+ };
335
+ };
336
+ missing?: string;
337
+ };
338
+ verify: {
339
+ method: "GET" | "POST";
340
+ path: string;
341
+ label: string;
342
+ show: string;
343
+ match?: {
344
+ [key: string]: string | number | boolean;
345
+ };
346
+ body?: {
347
+ [key: string]: unknown;
348
+ };
349
+ ifEmpty?: string;
350
+ } | {
351
+ label: string;
352
+ check: string;
353
+ ifEmpty?: string;
354
+ };
355
+ discover?: {
356
+ method: "GET" | "POST";
357
+ path: string;
358
+ label: string;
359
+ show: string;
360
+ match?: {
361
+ [key: string]: string | number | boolean;
362
+ };
363
+ body?: {
364
+ [key: string]: unknown;
365
+ };
366
+ ifEmpty?: string;
367
+ } | {
368
+ label: string;
369
+ check: string;
370
+ ifEmpty?: string;
371
+ };
372
+ revoke: string;
373
+ http?: {
374
+ baseUrl: string;
375
+ auth: {
376
+ type: "header";
377
+ header: string;
378
+ value: string;
379
+ prefix?: string;
380
+ } | {
381
+ type: "bearer";
382
+ token: string;
383
+ } | {
384
+ type: "basic";
385
+ username: string;
386
+ password: string;
387
+ } | {
388
+ type: "oauth2";
389
+ tokenUrl: string;
390
+ clientId: string;
391
+ clientSecret: string;
392
+ scope?: string;
393
+ } | {
394
+ type: "query";
395
+ param: string;
396
+ value: string;
397
+ };
398
+ headers: {
399
+ [key: string]: string;
400
+ };
401
+ tools: {
402
+ name: string;
403
+ description: string;
404
+ method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
405
+ path: string;
406
+ params: {
407
+ [key: string]: {
408
+ type: "string" | "number" | "integer" | "boolean" | "array";
409
+ description: string;
410
+ in: "path" | "query" | "body";
411
+ name?: string;
412
+ required: boolean;
413
+ default?: (string | number | boolean) | (string | number | boolean)[];
414
+ enum?: (string | number | boolean)[];
415
+ items?: "string" | "number" | "integer" | "boolean";
416
+ join?: string;
417
+ limit?: string;
418
+ };
419
+ };
420
+ destructive: boolean;
421
+ answerLimits: {
422
+ field: string;
423
+ limit: string;
424
+ }[];
425
+ result?: {
426
+ items?: string;
427
+ fields?: string[];
428
+ };
429
+ paging?: {
430
+ param: string;
431
+ body: string;
432
+ } | {
433
+ param: string;
434
+ header: string;
435
+ } | {
436
+ param: string;
437
+ link: true;
438
+ };
439
+ }[];
440
+ allowInsecureHttp: boolean;
441
+ };
442
+ soap?: {
443
+ endpoint: string;
444
+ version: "1.1" | "1.2";
445
+ namespaces: {
446
+ [key: string]: string;
447
+ };
448
+ auth?: {
449
+ type: "header";
450
+ header: string;
451
+ value: string;
452
+ prefix?: string;
453
+ } | {
454
+ type: "bearer";
455
+ token: string;
456
+ } | {
457
+ type: "basic";
458
+ username: string;
459
+ password: string;
460
+ };
461
+ wsSecurity?: {
462
+ username: string;
463
+ password: string;
464
+ digest: boolean;
465
+ };
466
+ verify?: {
467
+ tool: string;
468
+ args: {
469
+ [key: string]: string | number | boolean;
470
+ };
471
+ show: string;
472
+ };
473
+ tools: {
474
+ name: string;
475
+ description: string;
476
+ operation: string;
477
+ soapAction?: string;
478
+ body: string;
479
+ params: {
480
+ [key: string]: {
481
+ type: "string" | "number" | "integer" | "boolean";
482
+ description: string;
483
+ required: boolean;
484
+ limit?: string;
485
+ };
486
+ };
487
+ result?: string;
488
+ fields?: string[];
489
+ readOnly: boolean;
490
+ destructive: boolean;
491
+ answerLimits: {
492
+ field: string;
493
+ limit: string;
494
+ }[];
495
+ }[];
496
+ allowInsecureHttp: boolean;
497
+ };
498
+ odata?: {
499
+ serviceRoot: string;
500
+ version: "2" | "4";
501
+ auth: {
502
+ type: "header";
503
+ header: string;
504
+ value: string;
505
+ prefix?: string;
506
+ } | {
507
+ type: "bearer";
508
+ token: string;
509
+ } | {
510
+ type: "basic";
511
+ username: string;
512
+ password: string;
513
+ } | {
514
+ type: "oauth2";
515
+ tokenUrl: string;
516
+ clientId: string;
517
+ clientSecret: string;
518
+ scope?: string;
519
+ } | {
520
+ type: "query";
521
+ param: string;
522
+ value: string;
523
+ };
524
+ headers: {
525
+ [key: string]: string;
526
+ };
527
+ csrf: boolean;
528
+ paging: "skip" | "server";
529
+ tools: {
530
+ name: string;
531
+ description: string;
532
+ kind: "list" | "get" | "create" | "update" | "function" | "action";
533
+ entitySet?: string;
534
+ function?: string;
535
+ key: {
536
+ [key: string]: {
537
+ type: "string" | "integer" | "number" | "decimal" | "boolean" | "guid" | "datetime" | "datetimeoffset";
538
+ description: string;
539
+ property?: string;
540
+ required?: boolean;
541
+ limit?: string;
542
+ };
543
+ };
544
+ filters: {
545
+ [key: string]: {
546
+ type: "string" | "integer" | "number" | "decimal" | "boolean" | "guid" | "datetime" | "datetimeoffset";
547
+ description: string;
548
+ property?: string;
549
+ required?: boolean;
550
+ limit?: string;
551
+ op: "eq" | "ne" | "gt" | "ge" | "lt" | "le" | "contains" | "startswith";
552
+ };
553
+ };
554
+ fields: {
555
+ [key: string]: {
556
+ type: "string" | "integer" | "number" | "decimal" | "boolean" | "guid" | "datetime" | "datetimeoffset";
557
+ description: string;
558
+ property?: string;
559
+ required?: boolean;
560
+ limit?: string;
561
+ };
562
+ };
563
+ params: {
564
+ [key: string]: {
565
+ type: "string" | "integer" | "number" | "decimal" | "boolean" | "guid" | "datetime" | "datetimeoffset";
566
+ description: string;
567
+ property?: string;
568
+ required?: boolean;
569
+ limit?: string;
570
+ };
571
+ };
572
+ select: string[];
573
+ orderBy?: string;
574
+ top: number;
575
+ destructive: boolean;
576
+ answerLimits: {
577
+ field: string;
578
+ limit: string;
579
+ }[];
580
+ }[];
581
+ allowInsecureHttp: boolean;
582
+ };
583
+ sql?: {
584
+ engine: "postgres" | "sqlserver" | "mysql" | "oracle";
585
+ host: string;
586
+ port?: number;
587
+ database: string;
588
+ auth: {
589
+ user: string;
590
+ password: string;
591
+ };
592
+ tls: "verify" | "insecure" | "off";
593
+ timeoutSeconds: number;
594
+ maxRows: number;
595
+ tools: {
596
+ name: string;
597
+ description: string;
598
+ sql: string;
599
+ params: {
600
+ [key: string]: {
601
+ type: "string" | "number" | "integer" | "boolean";
602
+ description: string;
603
+ required: boolean;
604
+ limit?: string;
605
+ };
606
+ };
607
+ write: boolean;
608
+ destructive: boolean;
609
+ answerLimits: {
610
+ column: string;
611
+ limit: string;
612
+ }[];
613
+ }[];
614
+ };
615
+ events?: {
616
+ types: {
617
+ id: string;
618
+ label: string;
619
+ }[];
620
+ fields: {
621
+ [key: string]: string;
622
+ };
623
+ limits: {
624
+ [key: string]: string;
625
+ };
626
+ webhook?: {
627
+ verify: {
628
+ type: "hmac-sha256";
629
+ header: string;
630
+ prefix: string;
631
+ } | {
632
+ type: "token";
633
+ header: string;
634
+ } | {
635
+ type: "none";
636
+ };
637
+ allowInsecure: boolean;
638
+ type: {
639
+ field: string;
640
+ } | {
641
+ header: string;
642
+ };
643
+ deliveryId?: {
644
+ field: string;
645
+ } | {
646
+ header: string;
647
+ };
648
+ timestamp?: {
649
+ at: {
650
+ field: string;
651
+ } | {
652
+ header: string;
653
+ };
654
+ unit: "s" | "ms" | "iso";
655
+ toleranceSeconds: number;
656
+ };
657
+ setup: {
658
+ title: string;
659
+ body: string;
660
+ link?: {
661
+ label: string;
662
+ href: string;
663
+ };
664
+ copy?: string[];
665
+ shell?: "bash" | "powershell";
666
+ permissions?: boolean;
667
+ certificate?: boolean;
668
+ click?: string[];
669
+ clickUnavailable?: true;
670
+ siteRole?: "read" | "write";
671
+ agentCheck?: boolean;
672
+ confirm?: string;
673
+ live?: string;
674
+ settings?: {
675
+ id: string;
676
+ label: string;
677
+ help?: string;
678
+ placeholder?: string;
679
+ pattern: string;
680
+ }[];
681
+ option?: {
682
+ field: string;
683
+ value: string;
684
+ };
685
+ }[];
686
+ register?: {
687
+ method: "GET" | "POST" | "PUT";
688
+ path: string;
689
+ body?: unknown;
690
+ location: string;
691
+ };
692
+ };
693
+ self?: {
694
+ request: {
695
+ method: "GET" | "POST" | "PUT";
696
+ path: string;
697
+ body?: unknown;
698
+ };
699
+ id: string;
700
+ fields: string[];
701
+ };
702
+ poll?: {
703
+ request: {
704
+ method: "GET" | "POST" | "PUT";
705
+ path: string;
706
+ body?: unknown;
707
+ };
708
+ filter?: string;
709
+ items: string;
710
+ wrap?: string;
711
+ cursor: string;
712
+ deliveryId: string[];
713
+ types: {
714
+ type: string;
715
+ same?: [string, string];
716
+ }[];
717
+ };
718
+ };
719
+ }[];
720
+ steps: {
721
+ provider: string;
722
+ step: {
723
+ title: string;
724
+ body: string;
725
+ link?: {
726
+ label: string;
727
+ href: string;
728
+ };
729
+ copy?: string[];
730
+ shell?: "bash" | "powershell";
731
+ permissions?: boolean;
732
+ certificate?: boolean;
733
+ click?: string[];
734
+ clickUnavailable?: true;
735
+ siteRole?: "read" | "write";
736
+ agentCheck?: boolean;
737
+ confirm?: string;
738
+ live?: string;
739
+ settings?: {
740
+ id: string;
741
+ label: string;
742
+ help?: string;
743
+ placeholder?: string;
744
+ pattern: string;
745
+ }[];
746
+ option?: {
747
+ field: string;
748
+ value: string;
749
+ };
750
+ apps: string[];
751
+ };
752
+ }[];
753
+ bots: {
754
+ id: string;
755
+ name: string;
756
+ description: string;
757
+ logo: string;
758
+ identity: string;
759
+ signsInAs?: "agentBot";
760
+ provider?: string;
761
+ order?: number;
762
+ connectionKind: "guided";
763
+ accountKey: string;
764
+ scopes?: string[];
765
+ setup: {
766
+ title: string;
767
+ body: string;
768
+ link?: {
769
+ label: string;
770
+ href: string;
771
+ };
772
+ copy?: string[];
773
+ shell?: "bash" | "powershell";
774
+ permissions?: boolean;
775
+ certificate?: boolean;
776
+ click?: string[];
777
+ clickUnavailable?: true;
778
+ siteRole?: "read" | "write";
779
+ agentCheck?: boolean;
780
+ confirm?: string;
781
+ live?: string;
782
+ settings?: {
783
+ id: string;
784
+ label: string;
785
+ help?: string;
786
+ placeholder?: string;
787
+ pattern: string;
788
+ }[];
789
+ option?: {
790
+ field: string;
791
+ value: string;
792
+ };
793
+ }[];
794
+ afterConnect: {
795
+ title: string;
796
+ body: string;
797
+ link?: {
798
+ label: string;
799
+ href: string;
800
+ };
801
+ copy?: string[];
802
+ shell?: "bash" | "powershell";
803
+ permissions?: boolean;
804
+ certificate?: boolean;
805
+ click?: string[];
806
+ clickUnavailable?: true;
807
+ siteRole?: "read" | "write";
808
+ agentCheck?: boolean;
809
+ confirm?: string;
810
+ live?: string;
811
+ settings?: {
812
+ id: string;
813
+ label: string;
814
+ help?: string;
815
+ placeholder?: string;
816
+ pattern: string;
817
+ }[];
818
+ option?: {
819
+ field: string;
820
+ value: string;
821
+ };
822
+ }[];
823
+ fields: {
824
+ id: string;
825
+ label: string;
826
+ help?: string;
827
+ placeholder?: string;
828
+ secret: boolean;
829
+ options?: {
830
+ value: string;
831
+ label: string;
832
+ description: string;
833
+ scopes?: string[];
834
+ }[];
835
+ requires?: {
836
+ field: string;
837
+ value: string;
838
+ };
839
+ }[];
840
+ capabilities: {
841
+ id: string;
842
+ label: string;
843
+ description: string;
844
+ required: boolean;
845
+ destructive: boolean;
846
+ costs?: boolean;
847
+ scopes: string[];
848
+ roles?: string[];
849
+ permissions: string[];
850
+ fill?: {
851
+ [key: string]: string;
852
+ };
853
+ note?: string;
854
+ forbidden?: string;
855
+ claudeKey?: boolean;
856
+ tools: string[];
857
+ }[];
858
+ limits: {
859
+ id: string;
860
+ label: string;
861
+ help: string;
862
+ kind: "list" | "text" | "map";
863
+ required: boolean;
864
+ pattern?: string;
865
+ keys?: string;
866
+ }[];
867
+ siteAccess?: {
868
+ grant: {
869
+ title: string;
870
+ body: string;
871
+ link?: {
872
+ label: string;
873
+ href: string;
874
+ };
875
+ copy?: string[];
876
+ shell?: "bash" | "powershell";
877
+ permissions?: boolean;
878
+ certificate?: boolean;
879
+ click?: string[];
880
+ clickUnavailable?: true;
881
+ siteRole?: "read" | "write";
882
+ agentCheck?: boolean;
883
+ confirm?: string;
884
+ live?: string;
885
+ settings?: {
886
+ id: string;
887
+ label: string;
888
+ help?: string;
889
+ placeholder?: string;
890
+ pattern: string;
891
+ }[];
892
+ option?: {
893
+ field: string;
894
+ value: string;
895
+ };
896
+ }[];
897
+ request: string;
898
+ write: string[];
899
+ };
900
+ agentAccess?: {
901
+ limit: string;
902
+ label: string;
903
+ path: string & (unknown & unknown);
904
+ granted: string;
905
+ notGranted: string;
906
+ notFound: string;
907
+ probes: {
908
+ [key: string]: {
909
+ method: "GET" | "POST" | "PATCH";
910
+ path: string & (unknown & unknown);
911
+ body?: unknown;
912
+ allowed: number[];
913
+ };
914
+ };
915
+ missing?: string;
916
+ };
917
+ verify: {
918
+ method: "GET" | "POST";
919
+ path: string;
920
+ label: string;
921
+ show: string;
922
+ match?: {
923
+ [key: string]: string | number | boolean;
924
+ };
925
+ body?: {
926
+ [key: string]: unknown;
927
+ };
928
+ ifEmpty?: string;
929
+ } | {
930
+ label: string;
931
+ check: string;
932
+ ifEmpty?: string;
933
+ };
934
+ discover?: {
935
+ method: "GET" | "POST";
936
+ path: string;
937
+ label: string;
938
+ show: string;
939
+ match?: {
940
+ [key: string]: string | number | boolean;
941
+ };
942
+ body?: {
943
+ [key: string]: unknown;
944
+ };
945
+ ifEmpty?: string;
946
+ } | {
947
+ label: string;
948
+ check: string;
949
+ ifEmpty?: string;
950
+ };
951
+ revoke: string;
952
+ http?: {
953
+ baseUrl: string;
954
+ auth: {
955
+ type: "header";
956
+ header: string;
957
+ value: string;
958
+ prefix?: string;
959
+ } | {
960
+ type: "bearer";
961
+ token: string;
962
+ } | {
963
+ type: "basic";
964
+ username: string;
965
+ password: string;
966
+ } | {
967
+ type: "oauth2";
968
+ tokenUrl: string;
969
+ clientId: string;
970
+ clientSecret: string;
971
+ scope?: string;
972
+ } | {
973
+ type: "query";
974
+ param: string;
975
+ value: string;
976
+ };
977
+ headers: {
978
+ [key: string]: string;
979
+ };
980
+ tools: {
981
+ name: string;
982
+ description: string;
983
+ method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
984
+ path: string;
985
+ params: {
986
+ [key: string]: {
987
+ type: "string" | "number" | "integer" | "boolean" | "array";
988
+ description: string;
989
+ in: "path" | "query" | "body";
990
+ name?: string;
991
+ required: boolean;
992
+ default?: (string | number | boolean) | (string | number | boolean)[];
993
+ enum?: (string | number | boolean)[];
994
+ items?: "string" | "number" | "integer" | "boolean";
995
+ join?: string;
996
+ limit?: string;
997
+ };
998
+ };
999
+ destructive: boolean;
1000
+ answerLimits: {
1001
+ field: string;
1002
+ limit: string;
1003
+ }[];
1004
+ result?: {
1005
+ items?: string;
1006
+ fields?: string[];
1007
+ };
1008
+ paging?: {
1009
+ param: string;
1010
+ body: string;
1011
+ } | {
1012
+ param: string;
1013
+ header: string;
1014
+ } | {
1015
+ param: string;
1016
+ link: true;
1017
+ };
1018
+ }[];
1019
+ allowInsecureHttp: boolean;
1020
+ };
1021
+ soap?: {
1022
+ endpoint: string;
1023
+ version: "1.1" | "1.2";
1024
+ namespaces: {
1025
+ [key: string]: string;
1026
+ };
1027
+ auth?: {
1028
+ type: "header";
1029
+ header: string;
1030
+ value: string;
1031
+ prefix?: string;
1032
+ } | {
1033
+ type: "bearer";
1034
+ token: string;
1035
+ } | {
1036
+ type: "basic";
1037
+ username: string;
1038
+ password: string;
1039
+ };
1040
+ wsSecurity?: {
1041
+ username: string;
1042
+ password: string;
1043
+ digest: boolean;
1044
+ };
1045
+ verify?: {
1046
+ tool: string;
1047
+ args: {
1048
+ [key: string]: string | number | boolean;
1049
+ };
1050
+ show: string;
1051
+ };
1052
+ tools: {
1053
+ name: string;
1054
+ description: string;
1055
+ operation: string;
1056
+ soapAction?: string;
1057
+ body: string;
1058
+ params: {
1059
+ [key: string]: {
1060
+ type: "string" | "number" | "integer" | "boolean";
1061
+ description: string;
1062
+ required: boolean;
1063
+ limit?: string;
1064
+ };
1065
+ };
1066
+ result?: string;
1067
+ fields?: string[];
1068
+ readOnly: boolean;
1069
+ destructive: boolean;
1070
+ answerLimits: {
1071
+ field: string;
1072
+ limit: string;
1073
+ }[];
1074
+ }[];
1075
+ allowInsecureHttp: boolean;
1076
+ };
1077
+ odata?: {
1078
+ serviceRoot: string;
1079
+ version: "2" | "4";
1080
+ auth: {
1081
+ type: "header";
1082
+ header: string;
1083
+ value: string;
1084
+ prefix?: string;
1085
+ } | {
1086
+ type: "bearer";
1087
+ token: string;
1088
+ } | {
1089
+ type: "basic";
1090
+ username: string;
1091
+ password: string;
1092
+ } | {
1093
+ type: "oauth2";
1094
+ tokenUrl: string;
1095
+ clientId: string;
1096
+ clientSecret: string;
1097
+ scope?: string;
1098
+ } | {
1099
+ type: "query";
1100
+ param: string;
1101
+ value: string;
1102
+ };
1103
+ headers: {
1104
+ [key: string]: string;
1105
+ };
1106
+ csrf: boolean;
1107
+ paging: "skip" | "server";
1108
+ tools: {
1109
+ name: string;
1110
+ description: string;
1111
+ kind: "list" | "get" | "create" | "update" | "function" | "action";
1112
+ entitySet?: string;
1113
+ function?: string;
1114
+ key: {
1115
+ [key: string]: {
1116
+ type: "string" | "integer" | "number" | "decimal" | "boolean" | "guid" | "datetime" | "datetimeoffset";
1117
+ description: string;
1118
+ property?: string;
1119
+ required?: boolean;
1120
+ limit?: string;
1121
+ };
1122
+ };
1123
+ filters: {
1124
+ [key: string]: {
1125
+ type: "string" | "integer" | "number" | "decimal" | "boolean" | "guid" | "datetime" | "datetimeoffset";
1126
+ description: string;
1127
+ property?: string;
1128
+ required?: boolean;
1129
+ limit?: string;
1130
+ op: "eq" | "ne" | "gt" | "ge" | "lt" | "le" | "contains" | "startswith";
1131
+ };
1132
+ };
1133
+ fields: {
1134
+ [key: string]: {
1135
+ type: "string" | "integer" | "number" | "decimal" | "boolean" | "guid" | "datetime" | "datetimeoffset";
1136
+ description: string;
1137
+ property?: string;
1138
+ required?: boolean;
1139
+ limit?: string;
1140
+ };
1141
+ };
1142
+ params: {
1143
+ [key: string]: {
1144
+ type: "string" | "integer" | "number" | "decimal" | "boolean" | "guid" | "datetime" | "datetimeoffset";
1145
+ description: string;
1146
+ property?: string;
1147
+ required?: boolean;
1148
+ limit?: string;
1149
+ };
1150
+ };
1151
+ select: string[];
1152
+ orderBy?: string;
1153
+ top: number;
1154
+ destructive: boolean;
1155
+ answerLimits: {
1156
+ field: string;
1157
+ limit: string;
1158
+ }[];
1159
+ }[];
1160
+ allowInsecureHttp: boolean;
1161
+ };
1162
+ sql?: {
1163
+ engine: "postgres" | "sqlserver" | "mysql" | "oracle";
1164
+ host: string;
1165
+ port?: number;
1166
+ database: string;
1167
+ auth: {
1168
+ user: string;
1169
+ password: string;
1170
+ };
1171
+ tls: "verify" | "insecure" | "off";
1172
+ timeoutSeconds: number;
1173
+ maxRows: number;
1174
+ tools: {
1175
+ name: string;
1176
+ description: string;
1177
+ sql: string;
1178
+ params: {
1179
+ [key: string]: {
1180
+ type: "string" | "number" | "integer" | "boolean";
1181
+ description: string;
1182
+ required: boolean;
1183
+ limit?: string;
1184
+ };
1185
+ };
1186
+ write: boolean;
1187
+ destructive: boolean;
1188
+ answerLimits: {
1189
+ column: string;
1190
+ limit: string;
1191
+ }[];
1192
+ }[];
1193
+ };
1194
+ events?: {
1195
+ types: {
1196
+ id: string;
1197
+ label: string;
1198
+ }[];
1199
+ fields: {
1200
+ [key: string]: string;
1201
+ };
1202
+ limits: {
1203
+ [key: string]: string;
1204
+ };
1205
+ webhook?: {
1206
+ verify: {
1207
+ type: "hmac-sha256";
1208
+ header: string;
1209
+ prefix: string;
1210
+ } | {
1211
+ type: "token";
1212
+ header: string;
1213
+ } | {
1214
+ type: "none";
1215
+ };
1216
+ allowInsecure: boolean;
1217
+ type: {
1218
+ field: string;
1219
+ } | {
1220
+ header: string;
1221
+ };
1222
+ deliveryId?: {
1223
+ field: string;
1224
+ } | {
1225
+ header: string;
1226
+ };
1227
+ timestamp?: {
1228
+ at: {
1229
+ field: string;
1230
+ } | {
1231
+ header: string;
1232
+ };
1233
+ unit: "s" | "ms" | "iso";
1234
+ toleranceSeconds: number;
1235
+ };
1236
+ setup: {
1237
+ title: string;
1238
+ body: string;
1239
+ link?: {
1240
+ label: string;
1241
+ href: string;
1242
+ };
1243
+ copy?: string[];
1244
+ shell?: "bash" | "powershell";
1245
+ permissions?: boolean;
1246
+ certificate?: boolean;
1247
+ click?: string[];
1248
+ clickUnavailable?: true;
1249
+ siteRole?: "read" | "write";
1250
+ agentCheck?: boolean;
1251
+ confirm?: string;
1252
+ live?: string;
1253
+ settings?: {
1254
+ id: string;
1255
+ label: string;
1256
+ help?: string;
1257
+ placeholder?: string;
1258
+ pattern: string;
1259
+ }[];
1260
+ option?: {
1261
+ field: string;
1262
+ value: string;
1263
+ };
1264
+ }[];
1265
+ register?: {
1266
+ method: "GET" | "POST" | "PUT";
1267
+ path: string;
1268
+ body?: unknown;
1269
+ location: string;
1270
+ };
1271
+ };
1272
+ self?: {
1273
+ request: {
1274
+ method: "GET" | "POST" | "PUT";
1275
+ path: string;
1276
+ body?: unknown;
1277
+ };
1278
+ id: string;
1279
+ fields: string[];
1280
+ };
1281
+ poll?: {
1282
+ request: {
1283
+ method: "GET" | "POST" | "PUT";
1284
+ path: string;
1285
+ body?: unknown;
1286
+ };
1287
+ filter?: string;
1288
+ items: string;
1289
+ wrap?: string;
1290
+ cursor: string;
1291
+ deliveryId: string[];
1292
+ types: {
1293
+ type: string;
1294
+ same?: [string, string];
1295
+ }[];
1296
+ };
1297
+ };
1298
+ }[];
1299
+ };
1300
+ /** The list limits a new key must be given for an app before it is made (e.g. SharePoint's
1301
+ * sites): required, and not the agent's own address, which comes from its email. */
1302
+ export declare function newKeyLimits(c: Connector): Connector["limits"];
1303
+ /** "App: Limit" for each required list limit still empty on a new key's ticked apps. */
1304
+ export declare function missingNewKeyLimits(ticked: Connector[], chosen: Record<string, Limits>): string[];
1305
+ /** The grants a new key starts with: each ticked app at what its page allows (its ceiling),
1306
+ * with the limits chosen on the form, and the agent's email as its address where the app
1307
+ * has one. */
1308
+ export declare function newKeyGrants(ticked: {
1309
+ connector: Connector;
1310
+ ceiling: string[];
1311
+ }[], email: string, chosen: Record<string, Limits>): {
1312
+ app: string;
1313
+ capabilities: string[];
1314
+ limits: Limits;
1315
+ }[];
1316
+ /** The keys whose `limit` (an agent's own address) is `value`, in any app. */
1317
+ export declare function keysWithAddress(agents: Agent[], connectors: Connector[], value: string): Agent[];
1318
+ /** The warning that active keys already hold an address, or null. */
1319
+ export declare function holdersNotice(holders: Agent[]): string | null;
1320
+ /** A numbered setup step: done (checked live), failing, not done yet, or marked done by the
1321
+ * admin. `confirm`: the service cannot check it, so the admin marks it. `locked`: an earlier step
1322
+ * it needs is not done yet. */
1323
+ export type StepStatus = {
1324
+ /** checking: its live check has not answered yet (the page shows before it does). */
1325
+ state: "done" | "failing" | "todo" | "marked" | "checking";
1326
+ confirm: boolean;
1327
+ detail: string;
1328
+ locked: boolean;
1329
+ /** Why it is locked, when that is more than the step before it. */
1330
+ why?: string;
1331
+ };
1332
+ /** Connecting a provider, before any app: its setup steps (registering its app, which only the
1333
+ * sign-in can prove, so the admin marks it; the certificate, made here, its upload proven by
1334
+ * the sign-in), then connecting, a live sign-in. Each step opens once the one before it
1335
+ * passes. `marks`: the steps the admin marked done; `secret`: the admin chose a client secret
1336
+ * over the certificate. */
1337
+ export declare function providerSteps(setup: Step[], connection: ProviderConnection | null, marks: string[], secret: boolean): StepStatus[];
1338
+ /** One numbered step on a provider app's page, in order: what agents may do, the app's setup
1339
+ * steps (all before turning on: they need only the provider's app ids), the Claude key a
1340
+ * ticked capability needs, turning it on, then what needs it on: its sites, and with
1341
+ * the shared app the steps the service cannot check. Turning on stays locked until every
1342
+ * step before it the admin confirms is marked, and reads as done only once every step is. */
1343
+ export type AppStep = {
1344
+ id: string;
1345
+ kind: "capabilities" | "setup" | "turnOn" | "sites" | "claudeKey";
1346
+ title: string;
1347
+ step?: Step;
1348
+ status: StepStatus;
1349
+ };
1350
+ export declare function appSteps(input: {
1351
+ connector: Connector;
1352
+ connection: Connection | null;
1353
+ /** The provider connection signs in, or the shared app is approved on turning on. */
1354
+ providerReady: boolean;
1355
+ /** Turning on approves the shared app, which asks for the app's permissions itself:
1356
+ * only the steps the service cannot check stay, after turning on (they need the app's ids). */
1357
+ approval?: boolean;
1358
+ /** The app's live check, run when its page loads. */
1359
+ health: CheckOutcome | null;
1360
+ /** The ceiling as ticked on the page. */
1361
+ ceiling: string[];
1362
+ /** Each added site's live access, for an app with `siteAccess`. */
1363
+ sites: SiteAccess[] | null;
1364
+ claudeKey: boolean;
1365
+ /** The `confirm` ids the admin marked done. */
1366
+ marks: string[];
1367
+ /** The set-up-once steps' own live checks (`Step.live`), null when they could not run. */
1368
+ live?: Record<string, LiveCheck> | null;
1369
+ /** The live checks have not answered yet: the steps they decide show as checking. */
1370
+ checking?: boolean;
1371
+ /** Values saved at steps with `settings` (the provider connection's config). */
1372
+ saved?: Record<string, string>;
1373
+ /** The choice fields as typed or stored: a step with `option` shows only while chosen. */
1374
+ choices?: Record<string, string>;
1375
+ }): AppStep[];
1376
+ /** A step whose text fills in a value saved at another step waits until it is saved: its
1377
+ * words would show the raw {name} and its commands would not run. */
1378
+ export declare function waitForSettings(steps: AppStep[], saved: Record<string, string>): AppStep[];
1379
+ /** The status an app's page shows by its name: needing steps while it is on but any step is
1380
+ * not done. */
1381
+ export declare function appPageStatus(connection: Connection | null, healthy: boolean, steps: AppStep[]): AppStatus;
1382
+ /** What an app's steps are checked against, read live and read only when a page loads
1383
+ * (`appStates` in agent-connect.ts). `health` or `sites` null: that check could not run. */
1384
+ export type AppLive = {
1385
+ health: CheckOutcome | null;
1386
+ sites: SiteAccess[] | null;
1387
+ claudeKey: boolean;
1388
+ live: Record<string, LiveCheck> | null;
1389
+ /** Not read yet: the page shows before its live checks answer (`CHECKING`). */
1390
+ checking?: true;
1391
+ };
1392
+ /** An app's live state before its checks answer: steps they decide show as checking, and its
1393
+ * status is the stored one. */
1394
+ export declare const CHECKING: AppLive;
1395
+ /** How a provider's app signs in: through the provider connection, or (nothing connected yet,
1396
+ * where the shared app is offered) by approving that app when turning it on. */
1397
+ export declare function signInRoute(definition: Provider, provider: ProviderConnection | null): {
1398
+ signsIn: boolean;
1399
+ approve: boolean;
1400
+ };
1401
+ /** A provider app's steps and status: the one computation behind its page's badge, its row on
1402
+ * the provider's page and the provider's header and card, so none contradicts another. A
1403
+ * check that could not run needs attention. `ceiling` and `choices`: as ticked and typed on
1404
+ * the app's page, else as saved. */
1405
+ export declare function appState(input: {
1406
+ definition: Provider;
1407
+ provider: ProviderConnection | null;
1408
+ connector: Connector;
1409
+ connection: Connection | null;
1410
+ state: AppLive;
1411
+ marks: string[];
1412
+ ceiling?: string[];
1413
+ choices?: Record<string, string>;
1414
+ }): {
1415
+ steps: AppStep[];
1416
+ status: AppStatus;
1417
+ };
1418
+ /** A key's own addresses (its mailbox), per app that has one, e.g. for its access checks. */
1419
+ export declare function agentAddresses(agent: Agent, connectors: Connector[]): {
1420
+ connector: Connector;
1421
+ value: string;
1422
+ }[];