iii-browser-sdk 0.17.0 → 0.18.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.
@@ -0,0 +1,644 @@
1
+ //#region src/iii-types.d.ts
2
+ declare enum MessageType {
3
+ RegisterFunction = "registerfunction",
4
+ UnregisterFunction = "unregisterfunction",
5
+ InvokeFunction = "invokefunction",
6
+ InvocationResult = "invocationresult",
7
+ RegisterTriggerType = "registertriggertype",
8
+ RegisterTrigger = "registertrigger",
9
+ UnregisterTrigger = "unregistertrigger",
10
+ UnregisterTriggerType = "unregistertriggertype",
11
+ TriggerRegistrationResult = "triggerregistrationresult",
12
+ WorkerRegistered = "workerregistered"
13
+ }
14
+ type RegisterTriggerTypeMessage = {
15
+ message_type: MessageType.RegisterTriggerType;
16
+ id: string;
17
+ description: string;
18
+ };
19
+ type RegisterTriggerMessage = {
20
+ message_type: MessageType.RegisterTrigger;
21
+ id: string;
22
+ type: string;
23
+ function_id: string;
24
+ config: unknown;
25
+ };
26
+ type RegisterFunctionFormat = {
27
+ /**
28
+ * The name of the parameter
29
+ */
30
+ name?: string;
31
+ /**
32
+ * The description of the parameter
33
+ */
34
+ description?: string;
35
+ /**
36
+ * The type of the parameter
37
+ */
38
+ type?: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'null' | 'map' | 'integer';
39
+ /**
40
+ * The body of the parameter (for objects)
41
+ */
42
+ properties?: Record<string, unknown>;
43
+ /**
44
+ * The items of the parameter (for arrays)
45
+ */
46
+ items?: unknown;
47
+ /**
48
+ * Whether the parameter is required
49
+ */
50
+ required?: string[];
51
+ [key: string]: unknown;
52
+ };
53
+ type RegisterFunctionMessage = {
54
+ message_type: MessageType.RegisterFunction;
55
+ /**
56
+ * The path of the function (use :: for namespacing, e.g. external::my_lambda)
57
+ */
58
+ id: string;
59
+ /**
60
+ * The description of the function
61
+ */
62
+ description?: string;
63
+ /**
64
+ * The request format of the function
65
+ */
66
+ request_format?: RegisterFunctionFormat;
67
+ /**
68
+ * The response format of the function
69
+ */
70
+ response_format?: RegisterFunctionFormat;
71
+ metadata?: Record<string, unknown>;
72
+ };
73
+ /**
74
+ * Routing action for {@link TriggerRequest}. Determines how the engine
75
+ * handles the invocation.
76
+ *
77
+ * - `enqueue` -- Routes through a named queue for async processing.
78
+ * - `void` -- Fire-and-forget, no response.
79
+ */
80
+ type TriggerAction = {
81
+ type: 'enqueue';
82
+ queue: string;
83
+ } | {
84
+ type: 'void';
85
+ };
86
+ /**
87
+ * Input passed to the RBAC auth function during WebSocket upgrade.
88
+ * Contains the HTTP headers, query parameters, and client IP from the
89
+ * connecting worker's upgrade request.
90
+ */
91
+ type AuthInput = {
92
+ /** HTTP headers from the WebSocket upgrade request. */headers: Record<string, string>; /** Query parameters from the upgrade URL. Each key maps to an array of values to support repeated keys. */
93
+ query_params: Record<string, string[]>; /** IP address of the connecting client. */
94
+ ip_address: string;
95
+ };
96
+ /**
97
+ * Return value from the RBAC auth function. Controls which functions the
98
+ * authenticated worker can invoke and what context is forwarded to the
99
+ * middleware.
100
+ */
101
+ type AuthResult = {
102
+ /** Additional function IDs to allow beyond the `expose_functions` config. */allowed_functions: string[]; /** Function IDs to deny even if they match `expose_functions`. Takes precedence over allowed. */
103
+ forbidden_functions: string[]; /** Trigger type IDs the worker may register triggers for. When omitted, all types are allowed. */
104
+ allowed_trigger_types?: string[]; /** Whether the worker may register new trigger types. */
105
+ allow_trigger_type_registration: boolean; /** Whether the worker may register new functions. Defaults to `true` if omitted. */
106
+ allow_function_registration?: boolean; /** Arbitrary context forwarded to the middleware function on every invocation. */
107
+ context: Record<string, unknown>; /** Optional prefix applied to all function IDs registered by this worker. */
108
+ function_registration_prefix?: string;
109
+ };
110
+ /**
111
+ * Input passed to the RBAC middleware function on every function invocation
112
+ * through the RBAC port. The middleware can inspect, modify, or reject the
113
+ * call before it reaches the target function.
114
+ */
115
+ type MiddlewareFunctionInput = {
116
+ /** ID of the function being invoked. */function_id: string; /** Payload sent by the caller. */
117
+ payload: Record<string, unknown>; /** Routing action, if any. */
118
+ action?: TriggerAction; /** Auth context returned by the auth function for this session. */
119
+ context: Record<string, unknown>;
120
+ };
121
+ /**
122
+ * Input passed to the `on_trigger_type_registration_function_id` hook
123
+ * when a worker attempts to register a new trigger type through the RBAC port.
124
+ * Return an {@link OnTriggerTypeRegistrationResult} with the (possibly mapped)
125
+ * fields, or throw to deny the registration.
126
+ */
127
+ type OnTriggerTypeRegistrationInput = {
128
+ /** ID of the trigger type being registered. */trigger_type_id: string; /** Human-readable description of the trigger type. */
129
+ description: string; /** Auth context from `AuthResult.context` for this session. */
130
+ context: Record<string, unknown>;
131
+ };
132
+ /**
133
+ * Result returned from the `on_trigger_type_registration_function_id` hook.
134
+ * All fields are optional -- omitted fields keep the original value from the
135
+ * registration request.
136
+ */
137
+ type OnTriggerTypeRegistrationResult = {
138
+ /** Mapped trigger type ID. */trigger_type_id?: string; /** Mapped description. */
139
+ description?: string;
140
+ };
141
+ /**
142
+ * Input passed to the `on_trigger_registration_function_id` hook
143
+ * when a worker attempts to register a trigger through the RBAC port.
144
+ * Return an {@link OnTriggerRegistrationResult} with the (possibly mapped)
145
+ * fields, or throw to deny the registration.
146
+ */
147
+ type OnTriggerRegistrationInput = {
148
+ /** ID of the trigger being registered. */trigger_id: string; /** Trigger type identifier. */
149
+ trigger_type: string; /** ID of the function this trigger is bound to. */
150
+ function_id: string; /** Trigger-specific configuration. */
151
+ config: unknown; /** Auth context from `AuthResult.context` for this session. */
152
+ context: Record<string, unknown>;
153
+ };
154
+ /**
155
+ * Result returned from the `on_trigger_registration_function_id` hook.
156
+ * All fields are optional -- omitted fields keep the original value from the
157
+ * registration request.
158
+ */
159
+ type OnTriggerRegistrationResult = {
160
+ /** Mapped trigger ID. */trigger_id?: string; /** Mapped trigger type. */
161
+ trigger_type?: string; /** Mapped function ID. */
162
+ function_id?: string; /** Mapped trigger configuration. */
163
+ config?: unknown;
164
+ };
165
+ /**
166
+ * Input passed to the `on_function_registration_function_id` hook
167
+ * when a worker attempts to register a function through the RBAC port.
168
+ * Return an {@link OnFunctionRegistrationResult} with the (possibly mapped)
169
+ * fields, or throw to deny the registration.
170
+ */
171
+ type OnFunctionRegistrationInput = {
172
+ /** ID of the function being registered. */function_id: string; /** Human-readable description of the function. */
173
+ description?: string; /** Arbitrary metadata attached to the function. */
174
+ metadata?: Record<string, unknown>; /** Auth context from `AuthResult.context` for this session. */
175
+ context: Record<string, unknown>;
176
+ };
177
+ /**
178
+ * Result returned from the `on_function_registration_function_id` hook.
179
+ * All fields are optional -- omitted fields keep the original value from the
180
+ * registration request.
181
+ */
182
+ type OnFunctionRegistrationResult = {
183
+ /** Mapped function ID. */function_id?: string; /** Mapped description. */
184
+ description?: string; /** Mapped metadata. */
185
+ metadata?: Record<string, unknown>;
186
+ };
187
+ /**
188
+ * Result returned when a function is invoked with `TriggerAction.Enqueue`.
189
+ */
190
+ type EnqueueResult = {
191
+ /** Unique receipt ID for the enqueued message. */messageReceiptId: string;
192
+ };
193
+ /**
194
+ * Request object passed to {@link ISdk.trigger}.
195
+ *
196
+ * @typeParam TInput - Type of the payload.
197
+ */
198
+ type TriggerRequest<TInput = unknown> = {
199
+ /** ID of the function to invoke. */function_id: string; /** Payload to pass to the function. */
200
+ payload: TInput; /** Routing action. Omit for synchronous request/response. */
201
+ action?: TriggerAction; /** Override the default invocation timeout in milliseconds. */
202
+ timeoutMs?: number;
203
+ };
204
+ /**
205
+ * Serializable reference to one end of a streaming channel. Can be included
206
+ * in invocation payloads to pass channel endpoints between workers.
207
+ */
208
+ type StreamChannelRef = {
209
+ /** Unique channel identifier. */channel_id: string; /** Access key for authentication. */
210
+ access_key: string; /** Whether this ref is for reading or writing. */
211
+ direction: 'read' | 'write';
212
+ };
213
+ //#endregion
214
+ //#region src/channels.d.ts
215
+ /**
216
+ * Direction of a streaming channel endpoint. Mirrors the Rust SDK's
217
+ * `ChannelDirection` enum and matches the literal values used by
218
+ * {@link StreamChannelRef.direction}.
219
+ */
220
+ declare const ChannelDirection: {
221
+ readonly Read: "read";
222
+ readonly Write: "write";
223
+ };
224
+ type ChannelDirection = (typeof ChannelDirection)[keyof typeof ChannelDirection];
225
+ /**
226
+ * Discriminated runtime tag for an item observed on a streaming channel.
227
+ * Mirrors the Rust SDK's `ChannelItem` enum (`Text` / `Binary`). Carrier for
228
+ * factory + type-guard helpers so callers can construct and discriminate
229
+ * channel items without depending on Rust-specific shape.
230
+ */
231
+ type ChannelItem = {
232
+ type: 'text';
233
+ value: string;
234
+ } | {
235
+ type: 'binary';
236
+ value: Uint8Array;
237
+ };
238
+ declare const ChannelItem: {
239
+ /** Construct a text channel item. */readonly Text: (value: string) => ChannelItem; /** Construct a binary channel item. */
240
+ readonly Binary: (value: Uint8Array) => ChannelItem;
241
+ };
242
+ /**
243
+ * Write end of a streaming channel. Uses native browser WebSocket.
244
+ *
245
+ * @example
246
+ * ```typescript
247
+ * import { createChannel } from 'iii-browser-sdk/helpers'
248
+ * const channel = await createChannel(iii)
249
+ *
250
+ * channel.writer.sendMessage(JSON.stringify({ type: 'event', data: 'test' }))
251
+ * channel.writer.sendBinary(new Uint8Array([1, 2, 3]))
252
+ * channel.writer.close()
253
+ * ```
254
+ */
255
+ declare class ChannelWriter {
256
+ private static readonly FRAME_SIZE;
257
+ private ws;
258
+ private wsReady;
259
+ private readonly pendingMessages;
260
+ private readonly url;
261
+ constructor(engineWsBase: string, ref: StreamChannelRef);
262
+ private ensureConnected;
263
+ /** Send a text message through the channel. */
264
+ sendMessage(msg: string): void;
265
+ /** Send binary data through the channel. */
266
+ sendBinary(data: Uint8Array): void;
267
+ /** Close the channel writer. */
268
+ close(): void;
269
+ private sendRaw;
270
+ }
271
+ /**
272
+ * Read end of a streaming channel. Uses native browser WebSocket.
273
+ *
274
+ * @example
275
+ * ```typescript
276
+ * import { createChannel } from 'iii-browser-sdk/helpers'
277
+ * const channel = await createChannel(iii)
278
+ *
279
+ * channel.reader.onMessage((msg) => console.log('Got:', msg))
280
+ * channel.reader.onBinary((data) => console.log('Binary:', data.byteLength))
281
+ * ```
282
+ */
283
+ declare class ChannelReader {
284
+ private ws;
285
+ private connected;
286
+ private readonly messageCallbacks;
287
+ private readonly binaryCallbacks;
288
+ private readonly url;
289
+ constructor(engineWsBase: string, ref: StreamChannelRef);
290
+ private ensureConnected;
291
+ /** Register a callback to receive text messages from the channel. */
292
+ onMessage(callback: (msg: string) => void): void;
293
+ /** Register a callback to receive binary data from the channel. */
294
+ onBinary(callback: (data: Uint8Array) => void): void;
295
+ /** Read all binary data from the channel until it closes. */
296
+ readAll(): Promise<Uint8Array>;
297
+ /** Close the channel reader. */
298
+ close(): void;
299
+ }
300
+ //#endregion
301
+ //#region src/iii-constants.d.ts
302
+ /**
303
+ * Constants for the III module.
304
+ */
305
+ /**
306
+ * Engine function paths for internal operations.
307
+ *
308
+ * Naming note: `LIST_TRIGGERS` / `INFO_TRIGGERS` cover trigger TYPES
309
+ * (templates). `LIST_REGISTERED_TRIGGERS` / `INFO_REGISTERED_TRIGGERS`
310
+ * cover trigger INSTANCES (subscriber rows). The old
311
+ * `engine::trigger-types::list` builtin has been removed and is now
312
+ * served by `engine::triggers::list`.
313
+ */
314
+ declare const EngineFunctions: {
315
+ readonly LIST_FUNCTIONS: "engine::functions::list";
316
+ readonly INFO_FUNCTIONS: "engine::functions::info";
317
+ readonly LIST_WORKERS: "engine::workers::list";
318
+ readonly INFO_WORKERS: "engine::workers::info";
319
+ readonly LIST_TRIGGERS: "engine::triggers::list";
320
+ readonly INFO_TRIGGERS: "engine::triggers::info";
321
+ readonly LIST_REGISTERED_TRIGGERS: "engine::registered-triggers::list";
322
+ readonly INFO_REGISTERED_TRIGGERS: "engine::registered-triggers::info";
323
+ readonly REGISTER_WORKER: "engine::workers::register";
324
+ };
325
+ /** Engine trigger types */
326
+ declare const EngineTriggers: {
327
+ readonly FUNCTIONS_AVAILABLE: "engine::functions-available";
328
+ };
329
+ /** Connection state for the III WebSocket */
330
+ type IIIConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'failed';
331
+ /** Configuration for WebSocket reconnection behavior */
332
+ interface IIIReconnectionConfig {
333
+ /** Starting delay in milliseconds (default: 1000ms) */
334
+ initialDelayMs: number;
335
+ /** Maximum delay cap in milliseconds (default: 30000ms) */
336
+ maxDelayMs: number;
337
+ /** Exponential backoff multiplier (default: 2) */
338
+ backoffMultiplier: number;
339
+ /** Random jitter factor 0-1 (default: 0.3) */
340
+ jitterFactor: number;
341
+ /** Maximum retry attempts, -1 for infinite (default: -1) */
342
+ maxRetries: number;
343
+ }
344
+ //#endregion
345
+ //#region src/triggers.d.ts
346
+ /**
347
+ * Configuration passed to a trigger handler when a trigger instance is
348
+ * registered or unregistered.
349
+ *
350
+ * @typeParam TConfig - Type of the trigger-specific configuration.
351
+ */
352
+ type TriggerConfig<TConfig> = {
353
+ /** Trigger instance ID. */id: string; /** Function to invoke when the trigger fires. */
354
+ function_id: string; /** Trigger-specific configuration. */
355
+ config: TConfig;
356
+ };
357
+ /**
358
+ * Handler interface for custom trigger types. Passed to
359
+ * `ISdk.registerTriggerType`.
360
+ *
361
+ * @typeParam TConfig - Type of the trigger-specific configuration.
362
+ *
363
+ * @example
364
+ * ```typescript
365
+ * const handler: TriggerHandler<{ interval: number }> = {
366
+ * async registerTrigger({ id, function_id, config }) {
367
+ * // Set up periodic invocation
368
+ * },
369
+ * async unregisterTrigger({ id, function_id, config }) {
370
+ * // Clean up
371
+ * },
372
+ * }
373
+ * ```
374
+ */
375
+ type TriggerHandler<TConfig> = {
376
+ /** Called when a trigger instance is registered. */registerTrigger(config: TriggerConfig<TConfig>): Promise<void>; /** Called when a trigger instance is unregistered. */
377
+ unregisterTrigger(config: TriggerConfig<TConfig>): Promise<void>;
378
+ };
379
+ //#endregion
380
+ //#region src/types.d.ts
381
+ /**
382
+ * Async function handler for a registered function. Receives the invocation
383
+ * payload and returns the result.
384
+ *
385
+ * @typeParam TInput - Type of the invocation payload.
386
+ * @typeParam TOutput - Type of the return value.
387
+ *
388
+ * @example
389
+ * ```typescript
390
+ * const handler: RemoteFunctionHandler<{ name: string }, { message: string }> =
391
+ * async (data) => ({ message: `Hello, ${data.name}!` })
392
+ * ```
393
+ */
394
+ type RemoteFunctionHandler<TInput = any, TOutput = any> = (data: TInput) => Promise<TOutput>;
395
+ type RegisterTriggerInput = Omit<RegisterTriggerMessage, 'message_type' | 'id'>;
396
+ type RegisterFunctionInput = Omit<RegisterFunctionMessage, 'message_type'>;
397
+ type RegisterFunctionOptions = Omit<RegisterFunctionMessage, 'message_type' | 'id'>;
398
+ type RegisterTriggerTypeInput = Omit<RegisterTriggerTypeMessage, 'message_type'>;
399
+ interface ISdk {
400
+ /**
401
+ * Registers a new trigger. A trigger is a way to invoke a function when a certain event occurs.
402
+ * @param trigger - The trigger to register
403
+ * @returns A trigger object that can be used to unregister the trigger
404
+ *
405
+ * @example
406
+ * ```typescript
407
+ * const trigger = iii.registerTrigger({
408
+ * type: 'cron',
409
+ * function_id: 'my-service::process-batch',
410
+ * config: { expression: '0 *\/5 * * * * *' },
411
+ * })
412
+ *
413
+ * // Later, remove the trigger
414
+ * trigger.unregister()
415
+ * ```
416
+ */
417
+ registerTrigger(trigger: RegisterTriggerInput): Trigger;
418
+ /**
419
+ * Registers a new function with a local handler or an HTTP invocation config.
420
+ * @param functionId - Unique function identifier
421
+ * @param handler - Async handler for local execution, or an HTTP invocation config for external functions (Lambda, Cloudflare Workers, etc.)
422
+ * @param options - Optional function registration options (description, request/response formats, metadata)
423
+ * @returns A handle that can be used to unregister the function
424
+ *
425
+ * @example
426
+ * ```typescript
427
+ * // Local handler
428
+ * const ref = iii.registerFunction(
429
+ * 'greet',
430
+ * async (data: { name: string }) => ({ message: `Hello, ${data.name}!` }),
431
+ * { description: 'Returns a greeting' },
432
+ * )
433
+ *
434
+ * // Later, remove the function
435
+ * ref.unregister()
436
+ * ```
437
+ */
438
+ registerFunction(functionId: string, handler: RemoteFunctionHandler, options?: RegisterFunctionOptions): FunctionRef;
439
+ /**
440
+ * Invokes a function using a request object.
441
+ *
442
+ * @param request - The trigger request containing function_id, payload, and optional action/timeout
443
+ * @returns The result of the function
444
+ *
445
+ * @example
446
+ * ```typescript
447
+ * // Synchronous invocation
448
+ * const result = await iii.trigger<{ name: string }, { message: string }>({
449
+ * function_id: 'greet',
450
+ * payload: { name: 'World' },
451
+ * timeoutMs: 5000,
452
+ * })
453
+ * console.log(result.message) // "Hello, World!"
454
+ *
455
+ * // Fire-and-forget
456
+ * await iii.trigger({
457
+ * function_id: 'send-email',
458
+ * payload: { to: 'user@example.com' },
459
+ * action: TriggerAction.Void(),
460
+ * })
461
+ *
462
+ * // Enqueue for async processing
463
+ * const receipt = await iii.trigger({
464
+ * function_id: 'process-order',
465
+ * payload: { orderId: '123' },
466
+ * action: TriggerAction.Enqueue({ queue: 'orders' }),
467
+ * })
468
+ * ```
469
+ */
470
+ trigger<TInput, TOutput>(request: TriggerRequest<TInput>): Promise<TOutput>;
471
+ /**
472
+ * Registers a new trigger type. A trigger type is a way to invoke a function when a certain event occurs.
473
+ * @param triggerType - The trigger type to register
474
+ * @param handler - The handler for the trigger type
475
+ * @returns A trigger type object that can be used to unregister the trigger type
476
+ *
477
+ * @example
478
+ * ```typescript
479
+ * type CronConfig = { expression: string }
480
+ *
481
+ * iii.registerTriggerType<CronConfig>(
482
+ * { id: 'cron', description: 'Fires on a cron schedule' },
483
+ * {
484
+ * async registerTrigger({ id, function_id, config }) {
485
+ * startCronJob(id, config.expression, () =>
486
+ * iii.trigger({ function_id, payload: {} }),
487
+ * )
488
+ * },
489
+ * async unregisterTrigger({ id }) {
490
+ * stopCronJob(id)
491
+ * },
492
+ * },
493
+ * )
494
+ * ```
495
+ */
496
+ registerTriggerType<TConfig>(triggerType: RegisterTriggerTypeInput, handler: TriggerHandler<TConfig>): TriggerTypeRef<TConfig>;
497
+ /**
498
+ * Unregisters a trigger type.
499
+ * @param triggerType - The trigger type to unregister
500
+ *
501
+ * @example
502
+ * ```typescript
503
+ * iii.unregisterTriggerType({ id: 'cron', description: 'Fires on a cron schedule' })
504
+ * ```
505
+ */
506
+ unregisterTriggerType(triggerType: RegisterTriggerTypeInput): void;
507
+ /**
508
+ * Gracefully shutdown the iii, cleaning up all resources.
509
+ *
510
+ * @example
511
+ * ```typescript
512
+ * await iii.shutdown()
513
+ * ```
514
+ */
515
+ shutdown(): Promise<void>;
516
+ /**
517
+ * Subscribe to connection-state transitions. The handler is fired immediately
518
+ * with the current state, then on every transition. Multiple listeners are
519
+ * supported. Returns an unsubscribe function.
520
+ *
521
+ * @example
522
+ * ```typescript
523
+ * const unsub = iii.addConnectionStateListener((state) => {
524
+ * console.log('connection state:', state)
525
+ * })
526
+ *
527
+ * // Later, stop receiving updates
528
+ * unsub()
529
+ * ```
530
+ */
531
+ addConnectionStateListener(handler: (state: IIIConnectionState) => void): () => void;
532
+ }
533
+ /**
534
+ * Handle returned by {@link ISdk.registerTrigger}. Use `unregister()` to
535
+ * remove the trigger from the engine.
536
+ */
537
+ type Trigger = {
538
+ /** Removes this trigger from the engine. */unregister(): void;
539
+ };
540
+ /**
541
+ * Handle returned by {@link ISdk.registerFunction}. Contains the function's
542
+ * `id` and an `unregister()` method.
543
+ */
544
+ type FunctionRef = {
545
+ /** The unique function identifier. */id: string; /** Removes this function from the engine. */
546
+ unregister: () => void;
547
+ };
548
+ /**
549
+ * Typed handle returned by {@link ISdk.registerTriggerType}.
550
+ *
551
+ * Provides convenience methods to register triggers and functions scoped
552
+ * to this trigger type, so callers don't need to repeat the `type` field.
553
+ *
554
+ * @typeParam TConfig - Trigger-specific configuration type.
555
+ *
556
+ * @example
557
+ * ```typescript
558
+ * type CronConfig = { expression: string }
559
+ *
560
+ * const cron = iii.registerTriggerType<CronConfig>(
561
+ * { id: 'cron', description: 'Fires on a cron schedule' },
562
+ * cronHandler,
563
+ * )
564
+ *
565
+ * // Register a trigger -- type is inferred as CronConfig
566
+ * cron.registerTrigger('my::fn', { expression: '0 *\/5 * * * * *' })
567
+ *
568
+ * // Register a function and bind a trigger in one call
569
+ * cron.registerFunction(
570
+ * 'my::fn',
571
+ * async (data) => { return { ok: true } },
572
+ * { expression: '0 *\/5 * * * * *' },
573
+ * )
574
+ * ```
575
+ */
576
+ type TriggerTypeRef<TConfig = unknown> = {
577
+ /** The trigger type identifier. */id: string;
578
+ /**
579
+ * Register a trigger bound to this trigger type.
580
+ *
581
+ * @param functionId - The function to invoke when the trigger fires.
582
+ * @param config - Trigger-specific configuration.
583
+ * @returns A {@link Trigger} handle with an `unregister()` method.
584
+ */
585
+ registerTrigger(functionId: string, config: TConfig): Trigger;
586
+ /**
587
+ * Register a function and immediately bind it to this trigger type.
588
+ *
589
+ * @param functionId - Unique function identifier.
590
+ * @param handler - Local function handler.
591
+ * @param config - Trigger-specific configuration.
592
+ * @returns A {@link FunctionRef} handle.
593
+ */
594
+ registerFunction(functionId: string, handler: RemoteFunctionHandler, config: TConfig): FunctionRef;
595
+ /**
596
+ * Unregister this trigger type from the engine.
597
+ */
598
+ unregister(): void;
599
+ };
600
+ /**
601
+ * A streaming channel pair for worker-to-worker data transfer. Created via
602
+ * the `createChannel` helper from `iii-browser-sdk/helpers`.
603
+ */
604
+ type Channel = {
605
+ /** Writer end of the channel. */writer: ChannelWriter; /** Reader end of the channel. */
606
+ reader: ChannelReader; /** Serializable reference to the writer (can be sent to other workers). */
607
+ writerRef: StreamChannelRef; /** Serializable reference to the reader (can be sent to other workers). */
608
+ readerRef: StreamChannelRef;
609
+ };
610
+ /**
611
+ * Incoming HTTP request received by a function registered with an HTTP trigger.
612
+ *
613
+ * @typeParam TBody - Type of the parsed request body.
614
+ */
615
+ type ApiRequest<TBody = unknown> = {
616
+ path_params: Record<string, string>;
617
+ query_params: Record<string, string | string[]>;
618
+ body: TBody;
619
+ headers: Record<string, string | string[]>;
620
+ method: string;
621
+ };
622
+ /**
623
+ * Structured API response returned from HTTP function handlers.
624
+ *
625
+ * @typeParam TStatus - HTTP status code literal type.
626
+ * @typeParam TBody - Type of the response body.
627
+ *
628
+ * @example
629
+ * ```typescript
630
+ * const response: ApiResponse = {
631
+ * status_code: 200,
632
+ * headers: { 'content-type': 'application/json' },
633
+ * body: { message: 'ok' },
634
+ * }
635
+ * ```
636
+ */
637
+ type ApiResponse<TStatus extends number = number, TBody = string | Record<string, unknown>> = {
638
+ /** HTTP status code. */status_code: TStatus; /** Response headers. */
639
+ headers?: Record<string, string>; /** Response body. */
640
+ body?: TBody;
641
+ };
642
+ //#endregion
643
+ export { OnTriggerRegistrationInput as A, AuthInput as C, MiddlewareFunctionInput as D, MessageType as E, RegisterTriggerMessage as F, RegisterTriggerTypeMessage as I, StreamChannelRef as L, OnTriggerTypeRegistrationInput as M, OnTriggerTypeRegistrationResult as N, OnFunctionRegistrationInput as O, RegisterFunctionMessage as P, TriggerAction as R, ChannelWriter as S, EnqueueResult as T, IIIConnectionState as _, ISdk as a, ChannelItem as b, RegisterTriggerInput as c, Trigger as d, TriggerTypeRef as f, EngineTriggers as g, EngineFunctions as h, FunctionRef as i, OnTriggerRegistrationResult as j, OnFunctionRegistrationResult as k, RegisterTriggerTypeInput as l, TriggerHandler as m, ApiResponse as n, RegisterFunctionInput as o, TriggerConfig as p, Channel as r, RegisterFunctionOptions as s, ApiRequest as t, RemoteFunctionHandler as u, IIIReconnectionConfig as v, AuthResult as w, ChannelReader as x, ChannelDirection as y, TriggerRequest as z };
644
+ //# sourceMappingURL=types-CP-lPyex.d.cts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types-CP-lPyex.d.cts","names":[],"sources":["../src/iii-types.ts","../src/channels.ts","../src/iii-constants.ts","../src/triggers.ts","../src/types.ts"],"mappings":"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"}