@simple-ai-lab/sdk 0.1.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/dist/index.d.cts CHANGED
@@ -1,186 +1,747 @@
1
1
  import { z } from 'zod';
2
+ export { A as ActionContext, a as ActionHandler, B as BatchUpsertResult, D as DataClient, b as DataFilter, c as DataRecord, d as DeleteResult, F as FacetsResult, I as IngestBatchStatus, L as ListOptions, e as ListResult, M as MAX_BATCH_ROWS, f as MAX_QUERY_SIZE, Q as QueryInput, g as QueryResult, R as RecordPayload, h as RecordResult, S as SIMPLE_ACTION_BRAND, i as SimpleAI, j as SimpleAIOptions, k as batchUpsertRowsSchema, l as dataColumnPathSchema, m as dataFilterSchema, n as defineAction, o as listOptionsSchema, q as queryInputSchema, r as recordPayloadSchema, t as tableNameSchema } from './code-action-CDt77m7I.cjs';
2
3
 
3
- type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
4
- type HttpClient = {
5
- request: (args: {
4
+ type ActionsIoScalarType = 'string' | 'number' | 'boolean';
5
+ type ActionsIoSchemaNode = {
6
+ type: ActionsIoScalarType;
7
+ description: string;
8
+ nullable: boolean;
9
+ } | {
10
+ type: 'object';
11
+ description: string;
12
+ nullable: boolean;
13
+ properties: Record<string, ActionsIoSchemaNode>;
14
+ required: string[];
15
+ additionalProperties: boolean;
16
+ } | {
17
+ type: 'array';
18
+ description: string;
19
+ nullable: boolean;
20
+ items?: ActionsIoSchemaNode;
21
+ };
22
+ type ActionsIoSchema = {
23
+ type: 'object';
24
+ description: string;
25
+ properties: Record<string, ActionsIoSchemaNode>;
26
+ required: string[];
27
+ additionalProperties: boolean;
28
+ };
29
+ type HttpActionValues = {
30
+ actionType: 'http';
31
+ name: string;
32
+ description: string;
33
+ inputSchema: ActionsIoSchema;
34
+ outputSchema: ActionsIoSchema;
35
+ outputMappings: Record<string, string>;
36
+ operation: {
37
+ type: 'request';
6
38
  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
7
- path: string;
8
- query?: Record<string, string>;
9
- body?: unknown;
10
- }) => Promise<unknown>;
39
+ urlTemplate: string;
40
+ headers: {
41
+ name: string;
42
+ valueTemplate: string;
43
+ }[];
44
+ bodyTemplate: string | null;
45
+ };
46
+ };
47
+ type CodeActionValues = {
48
+ actionType: 'code';
49
+ name: string;
50
+ description: string;
51
+ inputSchema: ActionsIoSchema;
52
+ outputSchema: ActionsIoSchema;
53
+ outputMappings: Record<string, string>;
54
+ operation: {
55
+ type: 'execute';
56
+ language: 'typescript';
57
+ source: string;
58
+ compiledJs: string | null;
59
+ runtime: 'cloudflare-worker';
60
+ timeoutMs: number;
61
+ };
62
+ };
63
+ type CustomDataActionValues = {
64
+ actionType: 'custom_data';
65
+ name: string;
66
+ description: string;
67
+ inputSchema: ActionsIoSchema;
68
+ outputSchema: ActionsIoSchema;
69
+ outputMappings: Record<string, string>;
70
+ operation: {
71
+ type: 'query';
72
+ sql: string;
73
+ } | {
74
+ type: 'search';
75
+ table: string;
76
+ bodyTemplate: string;
77
+ };
78
+ };
79
+ type KnowledgeBaseActionValues = {
80
+ actionType: 'knowledge_base';
81
+ name: string;
82
+ description: string;
83
+ inputSchema: ActionsIoSchema;
84
+ outputSchema: ActionsIoSchema;
85
+ outputMappings: Record<string, string>;
86
+ operation: {
87
+ type: 'search';
88
+ knowledgeBaseIds: string[];
89
+ bodyTemplate: string;
90
+ };
91
+ };
92
+ type ActionVersionValues = HttpActionValues | CodeActionValues | CustomDataActionValues | KnowledgeBaseActionValues;
93
+ type ActionContract = {
94
+ inputSchema: ActionsIoSchema;
95
+ outputSchema: ActionsIoSchema;
96
+ };
97
+ type InlineActionDefinition = {
98
+ kind: 'inline';
99
+ key: string;
100
+ contract: ActionContract;
101
+ compile: (options: ActionCompileOptions) => ActionVersionValues;
102
+ };
103
+ type ReferencedActionDefinition = {
104
+ kind: 'reference';
105
+ key: string;
106
+ versionUuid: string;
107
+ contract: ActionContract | null;
108
+ };
109
+ type ActionDefinition = InlineActionDefinition | ReferencedActionDefinition;
110
+ type AgentActionInput = {
111
+ source: 'agent';
112
+ description: string;
113
+ } | {
114
+ source: 'template';
115
+ value: string;
116
+ };
117
+ /** Maps each Action output name to the Agent parameter that should receive its value. */
118
+ type ActionOutputParameters = Record<string, string>;
119
+ type CallableActionDefinition = {
120
+ kind: 'callable';
121
+ key: string;
122
+ action: ActionDefinition;
123
+ name: string;
124
+ description: string;
125
+ inputs: Record<string, AgentActionInput>;
126
+ outputParameters: ActionOutputParameters;
127
+ };
128
+ type ActionRunDefinition = {
129
+ kind: 'run';
130
+ key: string;
131
+ action: ActionDefinition;
132
+ inputs: Record<string, string>;
133
+ outputParameters: ActionOutputParameters;
134
+ };
135
+ type SourceFileReference = {
136
+ kind: 'source-file';
137
+ path: string;
138
+ };
139
+ type CommonActionConfig<TInputShape extends z.ZodRawShape, TOutputShape extends z.ZodRawShape> = {
140
+ key: string;
141
+ name: string;
142
+ description: string;
143
+ input: z.ZodObject<TInputShape>;
144
+ output: z.ZodObject<TOutputShape>;
145
+ outputMappings: Record<string, string>;
146
+ };
147
+ type HttpActionConfig<TInputShape extends z.ZodRawShape, TOutputShape extends z.ZodRawShape> = CommonActionConfig<TInputShape, TOutputShape> & {
148
+ request: {
149
+ method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
150
+ url: string;
151
+ headers?: Record<string, string>;
152
+ body?: string | null;
153
+ };
154
+ };
155
+ type CodeActionConfig<TInputShape extends z.ZodRawShape, TOutputShape extends z.ZodRawShape> = CommonActionConfig<TInputShape, TOutputShape> & {
156
+ source: string | SourceFileReference;
157
+ timeoutMs?: number;
158
+ };
159
+ type CustomDataQueryActionConfig<TInputShape extends z.ZodRawShape, TOutputShape extends z.ZodRawShape> = CommonActionConfig<TInputShape, TOutputShape> & {
160
+ sql: string;
11
161
  };
162
+ type CustomDataSearchActionConfig<TInputShape extends z.ZodRawShape, TOutputShape extends z.ZodRawShape> = CommonActionConfig<TInputShape, TOutputShape> & {
163
+ table: string;
164
+ body: string;
165
+ };
166
+ type KnowledgeBaseSearchActionConfig<TInputShape extends z.ZodRawShape, TOutputShape extends z.ZodRawShape> = CommonActionConfig<TInputShape, TOutputShape> & {
167
+ knowledgeBaseIds: string[];
168
+ body: string;
169
+ };
170
+ type ActionCompileOptions = {
171
+ readSourceFile?: (path: string) => string;
172
+ };
173
+ declare function actionsIoSchemaFromZod<TShape extends z.ZodRawShape>(schema: z.ZodObject<TShape>): ActionsIoSchema;
174
+ declare const action: {
175
+ http<TInputShape extends z.ZodRawShape, TOutputShape extends z.ZodRawShape>(config: HttpActionConfig<TInputShape, TOutputShape>): InlineActionDefinition;
176
+ code<TInputShape extends z.ZodRawShape, TOutputShape extends z.ZodRawShape>(config: CodeActionConfig<TInputShape, TOutputShape>): InlineActionDefinition;
177
+ customDataQuery<TInputShape extends z.ZodRawShape, TOutputShape extends z.ZodRawShape>(config: CustomDataQueryActionConfig<TInputShape, TOutputShape>): InlineActionDefinition;
178
+ customDataSearch<TInputShape extends z.ZodRawShape, TOutputShape extends z.ZodRawShape>(config: CustomDataSearchActionConfig<TInputShape, TOutputShape>): InlineActionDefinition;
179
+ knowledgeBaseSearch<TInputShape extends z.ZodRawShape, TOutputShape extends z.ZodRawShape>(config: KnowledgeBaseSearchActionConfig<TInputShape, TOutputShape>): InlineActionDefinition;
180
+ ref(config: {
181
+ key: string;
182
+ versionUuid: string;
183
+ contract?: ActionContract;
184
+ }): ReferencedActionDefinition;
185
+ callable(config: Omit<CallableActionDefinition, "kind">): CallableActionDefinition;
186
+ run(config: Omit<ActionRunDefinition, "kind">): ActionRunDefinition;
187
+ fromAgent(description: string): AgentActionInput;
188
+ from(value: string): AgentActionInput;
189
+ };
190
+ declare function compileAction(definition: InlineActionDefinition, options?: ActionCompileOptions): ActionVersionValues;
191
+ declare function sourceFile(path: string): SourceFileReference;
12
192
 
193
+ type BackgroundNoise = 'office' | 'coffee_shop' | 'driving' | 'restaurant' | 'street' | 'airport' | 'shopping_mall' | 'park' | 'off';
194
+ type InterruptionMode = 'harder' | 'medium' | 'easier' | 'always';
195
+ type RemoteReference = {
196
+ uuid: string;
197
+ };
198
+ type PromptReference = {
199
+ kind: 'inline';
200
+ text: string | null;
201
+ example: string | null;
202
+ generatedExamples?: unknown;
203
+ } | {
204
+ kind: 'file';
205
+ path: string;
206
+ example: string | null;
207
+ } | {
208
+ kind: 'version';
209
+ versionId: string;
210
+ };
211
+ type ExtractionField = {
212
+ name: string;
213
+ type: string;
214
+ description: string;
215
+ required: boolean;
216
+ enum?: (string | number | boolean)[];
217
+ items?: ExtractionField;
218
+ properties?: ExtractionField[];
219
+ };
220
+ type AgentV2EdgeWire = {
221
+ uuid: string;
222
+ toNodeUuid: string;
223
+ description: string;
224
+ priority: number;
225
+ condition: {
226
+ variable: string;
227
+ operator: string;
228
+ value: string;
229
+ } | null;
230
+ };
231
+ type EnabledWithDescription = {
232
+ enabled: boolean;
233
+ description: string | null;
234
+ };
235
+ type TransferCapability = {
236
+ enabled: boolean;
237
+ phoneNumber: string | null;
238
+ timeout: number;
239
+ mode: 'cold' | 'warm';
240
+ description: string | null;
241
+ voicemailMessage: string | null;
242
+ };
243
+ type NodeBuiltInCapabilities = {
244
+ alwaysAvailable?: EnabledWithDescription;
245
+ transfer?: TransferCapability;
246
+ };
247
+ type PromptWire = {
248
+ type: 'inline';
249
+ prompt: string | null;
250
+ example: string | null;
251
+ generatedExamples?: unknown;
252
+ } | {
253
+ type: 'reference';
254
+ promptVersionId: string;
255
+ };
256
+ type ActionUseSiteWire = {
257
+ actionUseSiteUuid: string;
258
+ actionVersionUuid: string;
259
+ inputMappings: Record<string, string>;
260
+ outputParameterMappings: Record<string, string>;
261
+ };
262
+ type ToolUseSiteWire = ActionUseSiteWire & {
263
+ name: string;
264
+ description: string;
265
+ inputDescriptions: Record<string, string>;
266
+ };
267
+ type AgentV2ConfigWire = {
268
+ voice: {
269
+ voiceUuid: string | null;
270
+ backgroundNoise: BackgroundNoise;
271
+ };
272
+ llm: {
273
+ model: string;
274
+ llmModelUuid: string | null;
275
+ temperature: number;
276
+ };
277
+ speech: {
278
+ language: string;
279
+ keyterms: string[];
280
+ };
281
+ call: {
282
+ agentSpeaksFirst: boolean;
283
+ firstSentence: string | null;
284
+ maxCallLengthSeconds: number;
285
+ record: boolean;
286
+ checkInAfterSilence: {
287
+ enabled: boolean;
288
+ prompt: string | null;
289
+ };
290
+ endCallAfterExtendedSilence: boolean;
291
+ pciEnabled: boolean;
292
+ backgroundNoise?: {
293
+ trackName: string;
294
+ gainMultiplier?: number;
295
+ };
296
+ interruptionConfig?: {
297
+ mode: InterruptionMode;
298
+ } | null;
299
+ };
300
+ preCallWebhook: {
301
+ enabled: boolean;
302
+ url: string | null;
303
+ authToken: string | null;
304
+ timeout: number;
305
+ parameters: string[];
306
+ };
307
+ builtInTools: {
308
+ dtmf: EnabledWithDescription;
309
+ hangup: {
310
+ enabled: boolean;
311
+ description: string | null;
312
+ message: string | null;
313
+ };
314
+ transfer: TransferCapability;
315
+ };
316
+ assignedToolIds: string[];
317
+ toolUseSites?: ToolUseSiteWire[];
318
+ automaticActions: {
319
+ beforeCallStart: (ActionUseSiteWire & {
320
+ trigger: 'before_call_start';
321
+ }) | null;
322
+ };
323
+ knowledgeBaseIds: string[];
324
+ abTestGroupIds: string[];
325
+ };
326
+ type AgentV2NodeBaseWire = {
327
+ uuid: string;
328
+ name: string;
329
+ isRoot: boolean;
330
+ position: {
331
+ x: number;
332
+ y: number;
333
+ };
334
+ behavior: {
335
+ waitAfterExecuting: number;
336
+ [key: string]: number | undefined;
337
+ };
338
+ edges: AgentV2EdgeWire[];
339
+ builtInTools?: NodeBuiltInCapabilities;
340
+ };
341
+ type AgentV2NodeWire = (AgentV2NodeBaseWire & {
342
+ type: 'global';
343
+ prompt: PromptWire;
344
+ }) | (AgentV2NodeBaseWire & {
345
+ type: 'standard';
346
+ prompt: PromptWire;
347
+ toolUuids: string[];
348
+ toolUseSiteUuids?: string[];
349
+ knowledgeBaseUuids: string[];
350
+ customDataTableNames: string[];
351
+ builtInTools: NodeBuiltInCapabilities;
352
+ sopSpec: unknown;
353
+ overrides: {
354
+ voice?: {
355
+ voiceUuid: string | null;
356
+ };
357
+ llm?: {
358
+ model: string | null;
359
+ llmModelUuid: string | null;
360
+ temperature: number | null;
361
+ };
362
+ };
363
+ perTurnWebhook?: {
364
+ enabled: boolean;
365
+ url: string;
366
+ authToken?: string | null;
367
+ } | null;
368
+ perTurnExtractionFields?: ExtractionField[] | null;
369
+ perTurnAction?: (ActionUseSiteWire & {
370
+ trigger: 'every_turn';
371
+ }) | null;
372
+ }) | (AgentV2NodeBaseWire & {
373
+ type: 'http';
374
+ url: string;
375
+ method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
376
+ headers: Record<string, string>;
377
+ body: unknown;
378
+ responseSelectors: {
379
+ name: string;
380
+ value: string;
381
+ }[];
382
+ runInBackground: boolean;
383
+ backgroundMessage: string | null;
384
+ executionMessage: string | null;
385
+ mockResponseData: unknown;
386
+ builtInTools: NodeBuiltInCapabilities;
387
+ }) | (AgentV2NodeBaseWire & {
388
+ type: 'action_node';
389
+ actionVersionUuid: string;
390
+ inputMappings: Record<string, string>;
391
+ outputParameterMappings: Record<string, string>;
392
+ runInBackground: boolean;
393
+ backgroundMessage: string | null;
394
+ executionMessage: string | null;
395
+ mockResponseData: unknown;
396
+ builtInTools: NodeBuiltInCapabilities;
397
+ }) | (AgentV2NodeBaseWire & {
398
+ type: 'extract';
399
+ fields: ExtractionField[];
400
+ executionMessage: string | null;
401
+ builtInTools: NodeBuiltInCapabilities;
402
+ }) | (AgentV2NodeBaseWire & {
403
+ type: 'say';
404
+ executionMessage: string | null;
405
+ overrides: {
406
+ voice?: {
407
+ voiceUuid: string | null;
408
+ };
409
+ };
410
+ builtInTools: NodeBuiltInCapabilities;
411
+ }) | (AgentV2NodeBaseWire & {
412
+ type: 'end_call';
413
+ executionMessage: string | null;
414
+ builtInTools: NodeBuiltInCapabilities;
415
+ }) | (AgentV2NodeBaseWire & {
416
+ type: 'routing';
417
+ description: string;
418
+ builtInTools: NodeBuiltInCapabilities;
419
+ }) | (AgentV2NodeBaseWire & {
420
+ type: 'ab_test';
421
+ abTestGroupUuid: string;
422
+ builtInTools: NodeBuiltInCapabilities;
423
+ }) | (AgentV2NodeBaseWire & {
424
+ type: 'transfer';
425
+ executionMessage: string | null;
426
+ builtInTools: NodeBuiltInCapabilities & {
427
+ transfer: TransferCapability;
428
+ };
429
+ }) | (AgentV2NodeBaseWire & {
430
+ type: 'transfer_chat';
431
+ executionMessage?: string | null;
432
+ mode?: 'five9' | 'teammate_handoff';
433
+ five9TenantName: string;
434
+ five9CampaignName: string;
435
+ five9ContactMapping: Record<string, unknown>;
436
+ five9AttributesMapping: Record<string, unknown>[];
437
+ builtInTools: NodeBuiltInCapabilities;
438
+ });
439
+ type AgentV2CommitContentWire = {
440
+ config: AgentV2ConfigWire;
441
+ nodes: AgentV2NodeWire[];
442
+ summaryPrompt: string | null;
443
+ };
444
+ type EdgeDefinition = {
445
+ key?: string;
446
+ to: string;
447
+ when: string;
448
+ priority?: number;
449
+ condition?: {
450
+ variable: string;
451
+ operator: string;
452
+ value: string;
453
+ } | null;
454
+ };
455
+ type NodeBaseDefinition = {
456
+ key: string;
457
+ name: string;
458
+ root?: boolean;
459
+ position?: {
460
+ x: number;
461
+ y: number;
462
+ };
463
+ waitAfterExecuting?: number;
464
+ edges?: EdgeDefinition[];
465
+ alwaysAvailable?: EnabledWithDescription;
466
+ };
467
+ type GlobalNodeDefinition = NodeBaseDefinition & {
468
+ type: 'global';
469
+ prompt: PromptReference;
470
+ };
471
+ type PromptNodeDefinition = NodeBaseDefinition & {
472
+ type: 'prompt';
473
+ prompt: PromptReference;
474
+ actions?: CallableActionDefinition[];
475
+ knowledgeBases?: RemoteReference[];
476
+ customDataTables?: string[];
477
+ sopSpec?: unknown;
478
+ voiceOverride?: {
479
+ voiceUuid: string | null;
480
+ };
481
+ llmOverride?: {
482
+ model: string | null;
483
+ modelUuid: string | null;
484
+ temperature: number | null;
485
+ };
486
+ vadMinSilenceDuration?: number;
487
+ waitAfterTransfer?: number;
488
+ perTurnWebhook?: {
489
+ enabled: boolean;
490
+ url: string;
491
+ authToken?: string | null;
492
+ } | null;
493
+ perTurnExtraction?: z.ZodObject<z.ZodRawShape> | null;
494
+ perTurnAction?: ActionRunDefinition | null;
495
+ transfer?: Pick<TransferCapability, 'enabled'> & Partial<Omit<TransferCapability, 'enabled'>>;
496
+ };
497
+ type ActionNodeDefinition = NodeBaseDefinition & {
498
+ type: 'action';
499
+ action: ActionDefinition;
500
+ inputs: Record<string, string>;
501
+ outputParameters?: ActionOutputParameters;
502
+ runInBackground?: boolean;
503
+ backgroundMessage?: string | null;
504
+ executionMessage?: string | null;
505
+ mockResponseData?: unknown;
506
+ };
13
507
  /**
14
- * Request wire schemas for the Simple AI public REST API (`/api/v1`).
508
+ * An HTTP request node in the Agent graph.
15
509
  *
16
- * These deliberately mirror the server's own schemas (see
17
- * `projects/server-v2/src/domains/data/query-schemas.ts` and
18
- * `domains/data/public/types.ts`); a contract test in server-v2 keeps the two
19
- * in sync. Responses are typed but not strictly validated, so additive server
20
- * changes never break deployed SDK consumers.
510
+ * Prefer `action.http(...)` plus `node.action(...)` for new work: Actions are
511
+ * versioned and reusable, HTTP nodes are neither. This exists so Agents that
512
+ * already contain HTTP nodes can be pulled into, edited as, and published from
513
+ * real source instead of an opaque snapshot.
21
514
  */
22
- /** Hard cap on hits a single query may return. */
23
- declare const MAX_QUERY_SIZE = 50;
24
- /** Maximum rows accepted by a single batch-upsert chunk. */
25
- declare const MAX_BATCH_ROWS = 1000;
26
- declare const tableNameSchema: z.ZodString;
27
- declare const dataColumnPathSchema: z.ZodString;
28
- declare const dataFilterSchema: z.ZodObject<{
29
- column: z.ZodString;
30
- values: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
31
- }, z.core.$strip>;
32
- type DataFilter = z.infer<typeof dataFilterSchema>;
33
- declare const queryInputSchema: z.ZodObject<{
34
- tableName: z.ZodString;
35
- filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
36
- column: z.ZodString;
37
- values: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
38
- }, z.core.$strip>>>;
39
- text: z.ZodOptional<z.ZodString>;
40
- size: z.ZodOptional<z.ZodNumber>;
41
- from: z.ZodOptional<z.ZodNumber>;
42
- }, z.core.$strip>;
43
- type QueryInput = z.input<typeof queryInputSchema>;
44
- declare const listOptionsSchema: z.ZodObject<{
45
- page: z.ZodOptional<z.ZodNumber>;
46
- perPage: z.ZodOptional<z.ZodNumber>;
47
- orderBy: z.ZodOptional<z.ZodString>;
48
- orderDirection: z.ZodOptional<z.ZodEnum<{
49
- asc: "asc";
50
- desc: "desc";
51
- }>>;
52
- filters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
53
- }, z.core.$strip>;
54
- type ListOptions = z.input<typeof listOptionsSchema>;
55
- declare const recordPayloadSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
56
- type RecordPayload = z.infer<typeof recordPayloadSchema>;
57
- declare const batchUpsertRowsSchema: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
58
- type DataRecord = Record<string, unknown>;
59
- type QueryResult = {
60
- records: DataRecord[];
61
- total: number;
62
- };
63
- type ListResult = {
64
- records: DataRecord[];
65
- total_count: number;
66
- page: number;
67
- per_page: number;
68
- };
69
- type RecordResult = {
70
- record: DataRecord;
71
- };
72
- type DeleteResult = {
73
- success: boolean;
74
- message: string;
75
- };
76
- type BatchUpsertResult = {
77
- ingestBatchId: string;
78
- status: string;
79
- };
80
- type IngestBatchStatus = {
81
- id: string;
82
- tableName: string;
83
- status: string;
84
- rowCount: number;
85
- upsertedCount: number | null;
86
- errorMessage: string | null;
87
- createdAt: string;
88
- startedAt: string | null;
89
- finishedAt: string | null;
90
- };
91
- type FacetsResult = Record<string, unknown>;
92
-
93
- /**
94
- * Custom data tables — query, read, and write your organization's records.
95
- * Wraps the `/api/v1/data` REST endpoints.
96
- */
97
- declare class DataClient {
98
- #private;
99
- constructor(http: HttpClient);
100
- /** Facet-filtered search over an indexed table (Elasticsearch-backed, max 50 hits). */
101
- query<TRecord extends DataRecord = DataRecord>(input: QueryInput): Promise<{
102
- records: TRecord[];
103
- total: number;
104
- }>;
105
- /** Facet values for an indexed table. */
106
- facets(tableName: string): Promise<FacetsResult>;
107
- /** Paginated listing straight from the relational store. */
108
- list<TRecord extends DataRecord = DataRecord>(tableName: string, options?: ListOptions): Promise<{
109
- records: TRecord[];
110
- total_count: number;
111
- page: number;
112
- per_page: number;
113
- }>;
114
- get<TRecord extends DataRecord = DataRecord>(tableName: string, id: number): Promise<{
115
- record: TRecord;
116
- }>;
117
- create<TRecord extends DataRecord = DataRecord>(tableName: string, payload: RecordPayload): Promise<{
118
- record: TRecord;
119
- }>;
120
- update<TRecord extends DataRecord = DataRecord>(tableName: string, id: number, payload: RecordPayload): Promise<{
121
- record: TRecord;
122
- }>;
123
- delete(tableName: string, id: number): Promise<DeleteResult>;
124
- /** Deletes every record in the table. Irreversible. */
125
- deleteAll(tableName: string): Promise<DeleteResult>;
515
+ type HttpNodeDefinition = NodeBaseDefinition & {
516
+ type: 'http';
517
+ url: string;
518
+ method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
519
+ headers?: Record<string, string>;
520
+ body?: unknown;
521
+ responseSelectors?: {
522
+ name: string;
523
+ value: string;
524
+ }[];
525
+ runInBackground?: boolean;
526
+ backgroundMessage?: string | null;
527
+ executionMessage?: string | null;
528
+ mockResponseData?: unknown;
529
+ };
530
+ type ExtractNodeDefinition = NodeBaseDefinition & {
531
+ type: 'extract';
532
+ schema: z.ZodObject<z.ZodRawShape>;
533
+ message?: string | null;
534
+ };
535
+ type SayNodeDefinition = NodeBaseDefinition & {
536
+ type: 'say';
537
+ /** `null` for a say node that has not been given its line yet. */
538
+ text: string | null;
539
+ voiceUuid?: string | null;
540
+ waitAfterSay?: number;
541
+ };
542
+ type EndCallNodeDefinition = NodeBaseDefinition & {
543
+ type: 'end-call';
544
+ message?: string | null;
545
+ };
546
+ type RouteNodeDefinition = NodeBaseDefinition & {
547
+ type: 'route';
548
+ description: string;
549
+ };
550
+ type AbTestNodeDefinition = NodeBaseDefinition & {
551
+ type: 'ab-test';
552
+ abTestGroupUuid: string;
553
+ };
554
+ type TransferNodeDefinition = NodeBaseDefinition & {
555
+ type: 'transfer';
556
+ message?: string | null;
557
+ phoneNumber: string;
558
+ mode?: 'cold' | 'warm';
559
+ timeout?: number;
560
+ description?: string | null;
561
+ voicemailMessage?: string | null;
562
+ waitAfterTransfer?: number;
563
+ };
564
+ type TransferChatNodeDefinition = NodeBaseDefinition & {
565
+ type: 'transfer-chat';
566
+ message?: string | null;
567
+ mode: 'five9' | 'teammate_handoff';
568
+ five9TenantName?: string;
569
+ five9CampaignName?: string;
570
+ five9ContactMapping?: Record<string, unknown>;
571
+ five9AttributesMapping?: Record<string, unknown>[];
572
+ };
573
+ type NodeDefinition = GlobalNodeDefinition | PromptNodeDefinition | ActionNodeDefinition | HttpNodeDefinition | ExtractNodeDefinition | SayNodeDefinition | EndCallNodeDefinition | RouteNodeDefinition | AbTestNodeDefinition | TransferNodeDefinition | TransferChatNodeDefinition;
574
+ type AgentDefinition = {
575
+ kind: 'agent-definition';
576
+ key: string;
577
+ name: string;
578
+ description: string | null;
579
+ branch: string;
580
+ modality: 'voice' | 'text';
581
+ folderUuid: string | null;
582
+ analyzerUuids: string[];
583
+ tagUuids: string[];
584
+ containmentConfig: unknown;
585
+ voice: {
586
+ voiceUuid: string | null;
587
+ backgroundNoise: BackgroundNoise;
588
+ };
589
+ llm: {
590
+ model: string;
591
+ modelUuid: string | null;
592
+ temperature: number;
593
+ };
594
+ speech: {
595
+ language: string;
596
+ keyterms: string[];
597
+ };
598
+ call: {
599
+ agentSpeaksFirst: boolean;
600
+ firstSentence: string | null;
601
+ maxCallLengthSeconds: number;
602
+ record: boolean;
603
+ checkInAfterSilence: {
604
+ enabled: boolean;
605
+ prompt: string | null;
606
+ };
607
+ endCallAfterExtendedSilence: boolean;
608
+ pciEnabled: boolean;
609
+ /**
610
+ * Background noise track, when it differs from `voice.backgroundNoise`.
611
+ *
612
+ * The product keeps the selected track after noise is switched off, so the
613
+ * two can legitimately disagree (`voice: 'off'`, track: `'coffee_shop'`).
614
+ * `null` mirrors `voice.backgroundNoise`, which is the common case.
615
+ */
616
+ backgroundNoiseTrack: BackgroundNoise | null;
617
+ /** `null` omits the gain entirely rather than sending a default. */
618
+ backgroundNoiseGain: number | null;
619
+ /** `null` omits interruption config entirely rather than defaulting it. */
620
+ interruptionMode: InterruptionMode | null;
621
+ };
622
+ preCallWebhook: {
623
+ enabled: boolean;
624
+ url: string | null;
625
+ authToken: string | null;
626
+ timeout: number;
627
+ parameters: string[];
628
+ };
629
+ capabilities: {
630
+ dtmf: EnabledWithDescription;
631
+ hangup: EnabledWithDescription & {
632
+ message: string | null;
633
+ };
634
+ transfer: TransferCapability;
635
+ };
636
+ knowledgeBases: RemoteReference[];
637
+ beforeCallAction: ActionRunDefinition | null;
638
+ summaryPrompt: string | null;
126
639
  /**
127
- * Asynchronous bulk upsert (max 1000 rows per call). Rows are FULL-ROW
128
- * REPLACE on key conflict — omitted columns are cleared, not preserved.
129
- * Returns a batch handle; poll `getBatch` for completion.
640
+ * A/B test groups on the Agent.
641
+ *
642
+ * `null` derives the set from `ab-test` nodes, which is what authoring in code
643
+ * produces. Pulled Agents can carry groups with no corresponding node, so they
644
+ * set this explicitly.
130
645
  */
131
- batchUpsert(tableName: string, rows: RecordPayload[]): Promise<BatchUpsertResult>;
132
- /** Status of an async upsert batch created by `batchUpsert`. */
133
- getBatch(ingestBatchId: string): Promise<IngestBatchStatus>;
134
- }
135
-
136
- type SimpleAIOptions = {
137
- /** API key (dashboard: Settings → API Keys). Defaults to SIMPLE_API_KEY — inside code actions this is injected automatically. */
138
- apiKey?: string;
139
- /** API base URL. Defaults to SIMPLE_BASE_URL, then the production API. */
140
- baseUrl?: string;
141
- /** Custom fetch implementation (for testing or instrumentation). */
142
- fetch?: FetchLike;
143
- };
144
- declare class SimpleAI {
145
- /** Custom data tables — query, read, and write records. */
146
- readonly data: DataClient;
147
- constructor(options?: SimpleAIOptions);
148
- }
149
-
150
- /**
151
- * Brand the code-action runner uses to recognize `defineAction` handlers. The
152
- * runner calls the default export with `{ inputs, config }` either way; the
153
- * wrapper adds the authenticated `client` to the handler's context.
154
- */
155
- declare const SIMPLE_ACTION_BRAND: unique symbol;
156
- type ActionContext<TInputs = Record<string, unknown>> = {
157
- /** The Action's declared inputs, already validated against its input schema. */
158
- inputs: TInputs;
159
- /** Your organization's configuration variables. */
160
- config: Record<string, string>;
161
- /** The Simple AI SDK, authenticated for your organization. */
162
- client: SimpleAI;
163
- };
164
- type ActionHandler<TInputs = Record<string, unknown>, TResult = unknown> = ((args: {
165
- inputs: TInputs;
166
- config: Record<string, string>;
167
- }) => Promise<TResult>) & {
168
- [SIMPLE_ACTION_BRAND]: true;
646
+ abTestGroupIds: string[] | null;
647
+ nodes: NodeDefinition[];
169
648
  };
170
- /**
171
- * Define a code action with a typed context and an org-authenticated SDK
172
- * client. The returned value must be your module's default export.
173
- *
174
- * ```ts
175
- * import { defineAction } from '@simple-ai-lab/sdk';
176
- *
177
- * export default defineAction(async ({ inputs, config, client }) => {
178
- * const { records } = await client.data.query({ tableName: 'customers', text: inputs.email });
179
- * return { found: records.length > 0 };
180
- * });
181
- * ```
182
- */
183
- declare function defineAction<TInputs = Record<string, unknown>, TResult = unknown>(handler: (context: ActionContext<TInputs>) => Promise<TResult> | TResult): ActionHandler<TInputs, TResult>;
649
+ type AgentDefinitionInput = {
650
+ key: string;
651
+ name: string;
652
+ description?: string | null;
653
+ branch: string;
654
+ modality?: 'voice' | 'text';
655
+ folderUuid?: string | null;
656
+ analyzerUuids?: string[];
657
+ tagUuids?: string[];
658
+ containmentConfig?: unknown;
659
+ voice?: {
660
+ voiceUuid?: string | null;
661
+ backgroundNoise?: BackgroundNoise;
662
+ };
663
+ llm?: {
664
+ model?: string;
665
+ modelUuid?: string | null;
666
+ temperature?: number;
667
+ };
668
+ speech?: {
669
+ language?: string;
670
+ keyterms?: string[];
671
+ };
672
+ call?: Partial<AgentDefinition['call']>;
673
+ preCallWebhook?: Partial<AgentDefinition['preCallWebhook']>;
674
+ capabilities?: {
675
+ dtmf?: Partial<EnabledWithDescription>;
676
+ hangup?: Partial<EnabledWithDescription & {
677
+ message: string | null;
678
+ }>;
679
+ transfer?: Partial<TransferCapability>;
680
+ };
681
+ knowledgeBases?: RemoteReference[];
682
+ beforeCallAction?: ActionRunDefinition | null;
683
+ summaryPrompt?: string | null;
684
+ abTestGroupIds?: string[] | null;
685
+ nodes: NodeDefinition[];
686
+ };
687
+ type AgentIdentityKind = 'node' | 'edge' | 'action-use-site' | 'action-version-placeholder';
688
+ type AgentCompileOptions = {
689
+ actionVersionUuids?: Record<string, string>;
690
+ identity?: (input: {
691
+ kind: AgentIdentityKind;
692
+ key: string;
693
+ }) => string | undefined;
694
+ readPromptFile?: (path: string) => string;
695
+ readActionSourceFile?: (path: string) => string;
696
+ allowUnresolvedActionVersions?: boolean;
697
+ };
698
+ type CompiledAgentProject = {
699
+ agent: {
700
+ key: string;
701
+ name: string;
702
+ description: string | null;
703
+ modality: 'voice' | 'text';
704
+ folderUuid: string | null;
705
+ analyzerUuids: string[];
706
+ tagUuids: string[];
707
+ containmentConfig: unknown;
708
+ };
709
+ branch: {
710
+ name: string;
711
+ };
712
+ actions: {
713
+ key: string;
714
+ versionUuid: string;
715
+ values: ActionVersionValues;
716
+ }[];
717
+ content: AgentV2CommitContentWire;
718
+ };
719
+ declare function defineAgent(input: AgentDefinitionInput): AgentDefinition;
720
+ declare const node: {
721
+ global(config: Omit<GlobalNodeDefinition, "type">): GlobalNodeDefinition;
722
+ prompt(config: Omit<PromptNodeDefinition, "type">): PromptNodeDefinition;
723
+ action(config: Omit<ActionNodeDefinition, "type">): ActionNodeDefinition;
724
+ http(config: Omit<HttpNodeDefinition, "type">): HttpNodeDefinition;
725
+ extract(config: Omit<ExtractNodeDefinition, "type">): ExtractNodeDefinition;
726
+ say(config: Omit<SayNodeDefinition, "type">): SayNodeDefinition;
727
+ endCall(config: Omit<EndCallNodeDefinition, "type">): EndCallNodeDefinition;
728
+ route(config: Omit<RouteNodeDefinition, "type">): RouteNodeDefinition;
729
+ abTest(config: Omit<AbTestNodeDefinition, "type">): AbTestNodeDefinition;
730
+ transfer(config: Omit<TransferNodeDefinition, "type">): TransferNodeDefinition;
731
+ transferChat(config: Omit<TransferChatNodeDefinition, "type">): TransferChatNodeDefinition;
732
+ };
733
+ declare const prompt: {
734
+ inline(text: string | null, example?: string | null, generatedExamples?: unknown): PromptReference;
735
+ file(path: string, example?: string | null): PromptReference;
736
+ version(versionId: string): PromptReference;
737
+ };
738
+ declare function reference(uuid: string): RemoteReference;
739
+ declare function canonicalAuthoringKey(value: string, fallback: string): string;
740
+ declare function canonicalAuthoringKeys(values: {
741
+ value: string;
742
+ fallback: string;
743
+ }[]): string[];
744
+ declare function compileAgent(definition: AgentDefinition, options?: AgentCompileOptions): CompiledAgentProject;
184
745
 
185
746
  /** Error thrown for any non-2xx response from the Simple AI API. */
186
747
  declare class SimpleAIError extends Error {
@@ -199,4 +760,21 @@ declare class SimpleAIError extends Error {
199
760
  });
200
761
  }
201
762
 
202
- export { type ActionContext, type ActionHandler, type BatchUpsertResult, DataClient, type DataFilter, type DataRecord, type DeleteResult, type FacetsResult, type IngestBatchStatus, type ListOptions, type ListResult, MAX_BATCH_ROWS, MAX_QUERY_SIZE, type QueryInput, type QueryResult, type RecordPayload, type RecordResult, SIMPLE_ACTION_BRAND, SimpleAI, SimpleAIError, type SimpleAIOptions, batchUpsertRowsSchema, dataColumnPathSchema, dataFilterSchema, defineAction, listOptionsSchema, queryInputSchema, recordPayloadSchema, tableNameSchema };
763
+ type AgentProjectSource = AgentDefinition | AgentSnapshotDefinition;
764
+ type SnapshotAction = {
765
+ key: string;
766
+ sourceVersionUuid: string;
767
+ values: ActionVersionValues;
768
+ };
769
+ type AgentSnapshotDefinition = {
770
+ kind: 'agent-snapshot';
771
+ agent: CompiledAgentProject['agent'];
772
+ branch: CompiledAgentProject['branch'];
773
+ actions: SnapshotAction[];
774
+ content: AgentV2CommitContentWire;
775
+ };
776
+ declare function defineAgentSnapshot(definition: Omit<AgentSnapshotDefinition, 'kind'>): AgentSnapshotDefinition;
777
+ declare function compileAgentProject(definition: AgentProjectSource, options?: AgentCompileOptions): CompiledAgentProject;
778
+ declare function collectActionVersionUuids(content: AgentV2CommitContentWire): string[];
779
+
780
+ export { type AbTestNodeDefinition, type ActionCompileOptions, type ActionDefinition, type ActionNodeDefinition, type ActionOutputParameters, type ActionRunDefinition, type ActionVersionValues, type ActionsIoSchema, type ActionsIoSchemaNode, type AgentActionInput, type AgentCompileOptions, type AgentDefinition, type AgentDefinitionInput, type AgentIdentityKind, type AgentProjectSource, type AgentSnapshotDefinition, type AgentV2CommitContentWire, type AgentV2ConfigWire, type AgentV2EdgeWire, type AgentV2NodeWire, type BackgroundNoise, type CallableActionDefinition, type CompiledAgentProject, type EdgeDefinition, type EnabledWithDescription, type EndCallNodeDefinition, type ExtractNodeDefinition, type ExtractionField, type GlobalNodeDefinition, type HttpNodeDefinition, type InlineActionDefinition, type InterruptionMode, type NodeDefinition, type PromptNodeDefinition, type PromptReference, type ReferencedActionDefinition, type RemoteReference, type RouteNodeDefinition, type SayNodeDefinition, SimpleAIError, type SnapshotAction, type SourceFileReference, type ToolUseSiteWire, type TransferCapability, type TransferChatNodeDefinition, type TransferNodeDefinition, action, actionsIoSchemaFromZod, canonicalAuthoringKey, canonicalAuthoringKeys, collectActionVersionUuids, compileAction, compileAgent, compileAgentProject, defineAgent, defineAgentSnapshot, node, prompt, reference, sourceFile };