Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/advanced/telemetry.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,7 @@ Use `withSpan` to create custom spans within a function handler:
```typescript
import { withSpan } from 'iii-sdk/telemetry'

iii.registerFunction({ id: 'orders::process' }, async (data) => {
iii.registerFunction('orders::process', async (data) => {
return withSpan('validate-order', {}, async (span) => {
span.setAttribute('order.id', data.orderId)
const valid = await validateOrder(data)
Expand Down
63 changes: 26 additions & 37 deletions docs/api-reference/sdk-browser.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -184,20 +184,35 @@ unsubscribe()

### registerFunction


Registers a new function with a local handler or an HTTP invocation config.

**Signature**

```typescript
registerFunction(func: RegisterFunctionInput, handler: RemoteFunctionHandler) => FunctionRef
registerFunction(functionId: string, handler: RemoteFunctionHandler, options: RegisterFunctionOptions) => FunctionRef
```

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `func` | [`RegisterFunctionInput`](#registerfunctioninput) | Yes | - |
| `handler` | [`RemoteFunctionHandler`](#remotefunctionhandler) | Yes | - |
| `functionId` | `string` | Yes | Unique function identifier |
| `handler` | [`RemoteFunctionHandler`](#remotefunctionhandler) | Yes | Async handler for local execution, or an HTTP invocation config for external functions (Lambda, Cloudflare Workers, etc.) |
| `options` | [`RegisterFunctionOptions`](#registerfunctionoptions) | Yes | Optional function registration options (description, request/response formats, metadata) |

#### Example

```typescript
// Local handler
const ref = iii.registerFunction(
'greet',
async (data: { name: string }) => ({ message: `Hello, ${data.name}!` }),
{ description: 'Returns a greeting' },
)

// Later, remove the function
ref.unregister()
```

### registerService

Expand Down Expand Up @@ -373,7 +388,7 @@ The `iii-sdk` package provides additional entry points:

## Types

[`MessageType`](#messagetype) · [`ChannelReader`](#channelreader) · [`ChannelWriter`](#channelwriter) · [`Channel`](#channel) · [`FunctionRef`](#functionref) · [`HttpAuthConfig`](#httpauthconfig) · [`HttpInvocationConfig`](#httpinvocationconfig) · [`InitOptions`](#initoptions) · [`RegisterFunctionInput`](#registerfunctioninput) · [`RegisterFunctionMessage`](#registerfunctionmessage) · [`RegisterServiceInput`](#registerserviceinput) · [`RegisterTriggerInput`](#registertriggerinput) · [`RegisterTriggerMessage`](#registertriggermessage) · [`RegisterTriggerTypeInput`](#registertriggertypeinput) · [`RegisterTriggerTypeMessage`](#registertriggertypemessage) · [`RemoteFunctionHandler`](#remotefunctionhandler) · [`StreamChannelRef`](#streamchannelref) · [`Trigger`](#trigger) · [`TriggerHandler`](#triggerhandler) · [`TriggerInfo`](#triggerinfo) · [`TriggerRequest`](#triggerrequest) · [`TriggerTypeInfo`](#triggertypeinfo) · [`TriggerTypeRef`](#triggertyperef) · [`IStream`](#istream) · [`DeleteResult`](#deleteresult) · [`StreamSetResult`](#streamsetresult) · [`StreamUpdateResult`](#streamupdateresult) · [`DeleteResult`](#deleteresult)
[`MessageType`](#messagetype) · [`ChannelReader`](#channelreader) · [`ChannelWriter`](#channelwriter) · [`Channel`](#channel) · [`FunctionRef`](#functionref) · [`InitOptions`](#initoptions) · [`RegisterFunctionMessage`](#registerfunctionmessage) · [`RegisterFunctionOptions`](#registerfunctionoptions) · [`RegisterServiceInput`](#registerserviceinput) · [`RegisterTriggerInput`](#registertriggerinput) · [`RegisterTriggerMessage`](#registertriggermessage) · [`RegisterTriggerTypeInput`](#registertriggertypeinput) · [`RegisterTriggerTypeMessage`](#registertriggertypemessage) · [`RemoteFunctionHandler`](#remotefunctionhandler) · [`StreamChannelRef`](#streamchannelref) · [`Trigger`](#trigger) · [`TriggerHandler`](#triggerhandler) · [`TriggerInfo`](#triggerinfo) · [`TriggerRequest`](#triggerrequest) · [`TriggerTypeInfo`](#triggertypeinfo) · [`TriggerTypeRef`](#triggertyperef) · [`IStream`](#istream) · [`DeleteResult`](#deleteresult) · [`StreamSetResult`](#streamsetresult) · [`StreamUpdateResult`](#streamupdateresult) · [`DeleteResult`](#deleteresult)

### MessageType

Expand Down Expand Up @@ -421,31 +436,6 @@ Handle returned by ISdk.registerFunction. Contains the function's
| `id` | `string` | Yes | The unique function identifier. |
| `unregister` | `() => void` | Yes | Removes this function from the engine. |

### HttpAuthConfig

Authentication configuration for HTTP-invoked functions.

- `hmac` -- HMAC signature verification using a shared secret.
- `bearer` -- Bearer token authentication.
- `api_key` -- API key sent via a custom header.

```typescript
type HttpAuthConfig = unknown | unknown | unknown
```

### HttpInvocationConfig

Configuration for registering an HTTP-invoked function (Lambda, Cloudflare
Workers, etc.) instead of a local handler.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `auth` | [`HttpAuthConfig`](#httpauthconfig) | No | Authentication configuration. |
| `headers` | `Record<string, string>` | No | Custom headers to send with the request. |
| `method` | `"GET" \| "POST" \| "PUT" \| "PATCH" \| "DELETE"` | No | HTTP method. Defaults to `POST`. |
| `timeout_ms` | `number` | No | Timeout in milliseconds. |
| `url` | `string` | Yes | URL to invoke. |

### InitOptions

Configuration options passed to registerWorker.
Expand All @@ -456,24 +446,23 @@ Configuration options passed to registerWorker.
| `invocationTimeoutMs` | `number` | No | Default timeout for `trigger()` in milliseconds. Defaults to `30000`. |
| `reconnectionConfig` | `Partial<IIIReconnectionConfig>` | No | WebSocket reconnection behavior. |

### RegisterFunctionInput

```typescript
type RegisterFunctionInput = Omit<RegisterFunctionMessage, "message_type">
```

### RegisterFunctionMessage

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | `string` | No | The description of the function |
| `id` | `string` | Yes | The path of the function (use :: for namespacing, e.g. external::my_lambda) |
| `invocation` | [`HttpInvocationConfig`](#httpinvocationconfig) | No | HTTP invocation config for external HTTP functions (Lambda, Cloudflare Workers, etc.) |
| `message_type` | [`MessageType`](#messagetype).RegisterFunction | Yes | - |
| `metadata` | `Record<string, unknown>` | No | - |
| `request_format` | `RegisterFunctionFormat` | No | The request format of the function |
| `response_format` | `RegisterFunctionFormat` | No | The response format of the function |

### RegisterFunctionOptions

```typescript
type RegisterFunctionOptions = Omit<RegisterFunctionMessage, "message_type" | "id">
```

### RegisterServiceInput

```typescript
Expand Down
49 changes: 38 additions & 11 deletions docs/api-reference/sdk-node.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -198,20 +198,47 @@ unsubscribe()

### registerFunction


Registers a new function with a local handler or an HTTP invocation config.

**Signature**

```typescript
registerFunction(func: RegisterFunctionInput, handler: RemoteFunctionHandler) => FunctionRef
registerFunction(functionId: string, handler: HttpInvocationConfig | RemoteFunctionHandler<any, any>, options: RegisterFunctionOptions) => FunctionRef
```

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `func` | [`RegisterFunctionInput`](#registerfunctioninput) | Yes | - |
| `handler` | [`RemoteFunctionHandler`](#remotefunctionhandler) | Yes | - |
| `functionId` | `string` | Yes | Unique function identifier |
| `handler` | [`HttpInvocationConfig`](#httpinvocationconfig) \| [`RemoteFunctionHandler`](#remotefunctionhandler)&lt;any, any&gt; | Yes | Async handler for local execution, or an HTTP invocation config for external functions (Lambda, Cloudflare Workers, etc.) |
| `options` | [`RegisterFunctionOptions`](#registerfunctionoptions) | Yes | Optional function registration options (description, request/response formats, metadata) |

#### Example

```typescript
// Local handler
const ref = iii.registerFunction(
'greet',
async (data: { name: string }) => ({ message: `Hello, ${data.name}!` }),
{ description: 'Returns a greeting' },
)

// HTTP invocation
const lambdaRef = iii.registerFunction(
'external::my-lambda',
{
url: 'https://abc123.lambda-url.us-east-1.on.aws',
method: 'POST',
timeout_ms: 30_000,
auth: { type: 'bearer', token_key: 'LAMBDA_AUTH_TOKEN' },
},
{ description: 'Proxied Lambda function' },
)

// Later, remove the function
ref.unregister()
```

### registerService

Expand Down Expand Up @@ -495,7 +522,7 @@ logger.warn('Retry attempt', { attempt: 3, maxRetries: 5, endpoint: '/api/charge

## Types

[`MessageType`](#messagetype) · [`ChannelReader`](#channelreader) · [`ChannelWriter`](#channelwriter) · [`Channel`](#channel) · [`FunctionRef`](#functionref) · [`HttpAuthConfig`](#httpauthconfig) · [`HttpInvocationConfig`](#httpinvocationconfig) · [`InitOptions`](#initoptions) · [`RegisterFunctionInput`](#registerfunctioninput) · [`RegisterFunctionMessage`](#registerfunctionmessage) · [`RegisterServiceInput`](#registerserviceinput) · [`RegisterTriggerInput`](#registertriggerinput) · [`RegisterTriggerMessage`](#registertriggermessage) · [`RegisterTriggerTypeInput`](#registertriggertypeinput) · [`RegisterTriggerTypeMessage`](#registertriggertypemessage) · [`RemoteFunctionHandler`](#remotefunctionhandler) · [`StreamChannelRef`](#streamchannelref) · [`Trigger`](#trigger) · [`TriggerHandler`](#triggerhandler) · [`TriggerInfo`](#triggerinfo) · [`TriggerRequest`](#triggerrequest) · [`TriggerTypeInfo`](#triggertypeinfo) · [`TriggerTypeRef`](#triggertyperef) · [`IStream`](#istream) · [`DeleteResult`](#deleteresult) · [`StreamSetResult`](#streamsetresult) · [`StreamUpdateResult`](#streamupdateresult) · [`DeleteResult`](#deleteresult) · [`IIIReconnectionConfig`](#iiireconnectionconfig) · [`OtelConfig`](#otelconfig) · [`ReconnectionConfig`](#reconnectionconfig) · [`FunctionInfo`](#functioninfo) · [`FunctionsAvailableCallback`](#functionsavailablecallback) · [`RegisterFunctionFormat`](#registerfunctionformat)
[`MessageType`](#messagetype) · [`ChannelReader`](#channelreader) · [`ChannelWriter`](#channelwriter) · [`Channel`](#channel) · [`FunctionRef`](#functionref) · [`HttpAuthConfig`](#httpauthconfig) · [`HttpInvocationConfig`](#httpinvocationconfig) · [`InitOptions`](#initoptions) · [`RegisterFunctionMessage`](#registerfunctionmessage) · [`RegisterFunctionOptions`](#registerfunctionoptions) · [`RegisterServiceInput`](#registerserviceinput) · [`RegisterTriggerInput`](#registertriggerinput) · [`RegisterTriggerMessage`](#registertriggermessage) · [`RegisterTriggerTypeInput`](#registertriggertypeinput) · [`RegisterTriggerTypeMessage`](#registertriggertypemessage) · [`RemoteFunctionHandler`](#remotefunctionhandler) · [`StreamChannelRef`](#streamchannelref) · [`Trigger`](#trigger) · [`TriggerHandler`](#triggerhandler) · [`TriggerInfo`](#triggerinfo) · [`TriggerRequest`](#triggerrequest) · [`TriggerTypeInfo`](#triggertypeinfo) · [`TriggerTypeRef`](#triggertyperef) · [`IStream`](#istream) · [`DeleteResult`](#deleteresult) · [`StreamSetResult`](#streamsetresult) · [`StreamUpdateResult`](#streamupdateresult) · [`DeleteResult`](#deleteresult) · [`IIIReconnectionConfig`](#iiireconnectionconfig) · [`OtelConfig`](#otelconfig) · [`ReconnectionConfig`](#reconnectionconfig) · [`FunctionInfo`](#functioninfo) · [`FunctionsAvailableCallback`](#functionsavailablecallback) · [`RegisterFunctionFormat`](#registerfunctionformat)

### MessageType

Expand Down Expand Up @@ -591,12 +618,6 @@ Configuration options passed to registerWorker.
| `reconnectionConfig` | Partial&lt;[`IIIReconnectionConfig`](#iiireconnectionconfig)&gt; | No | WebSocket reconnection behavior. |
| `workerName` | `string` | No | Display name for this worker. Defaults to `hostname:pid`. |

### RegisterFunctionInput

```typescript
type RegisterFunctionInput = Omit<RegisterFunctionMessage, "message_type">
```

### RegisterFunctionMessage

| Name | Type | Required | Description |
Expand All @@ -609,6 +630,12 @@ type RegisterFunctionInput = Omit<RegisterFunctionMessage, "message_type">
| `request_format` | [`RegisterFunctionFormat`](#registerfunctionformat) | No | The request format of the function |
| `response_format` | [`RegisterFunctionFormat`](#registerfunctionformat) | No | The response format of the function |

### RegisterFunctionOptions

```typescript
type RegisterFunctionOptions = Omit<RegisterFunctionMessage, "message_type" | "id">
```

### RegisterServiceInput

```typescript
Expand Down
30 changes: 14 additions & 16 deletions docs/api-reference/sdk-python.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ create_channel(buffer_size: int | None = None)

```python
ch = iii.create_channel()
fn = iii.register_function({"id": "producer"}, producer_handler)
fn = iii.register_function("producer", producer_handler)
iii.trigger({"function_id": "producer", "payload": {"output": ch.writer_ref}})
```

Expand Down Expand Up @@ -91,7 +91,7 @@ async (buffer_size: int | None = None)

```python
ch = await iii.create_channel_async()
fn = iii.register_function({"id": "producer"}, producer_handler)
fn = iii.register_function("producer", producer_handler)
await iii.trigger_async({"function_id": "producer", "payload": {"output": ch.writer_ref}})
```

Expand Down Expand Up @@ -348,26 +348,26 @@ from the handler's type hints when not explicitly provided.
**Signature**

```python
register_function(func_or_id: RegisterFunctionInput | dict[str, Any] | str, handler_or_invocation: RemoteFunctionHandler | HttpInvocationConfig, description: str | None = None, metadata: dict[str, Any] | None = None, request_format: RegisterFunctionFormat | dict[str, Any] | None = None, response_format: RegisterFunctionFormat | dict[str, Any] | None = None)
register_function(function_id: str, handler_or_invocation: RemoteFunctionHandler | HttpInvocationConfig, description: str | None = None, metadata: dict[str, Any] | None = None, request_format: RegisterFunctionFormat | dict[str, Any] | None = None, response_format: RegisterFunctionFormat | dict[str, Any] | None = None)
```

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `func_or_id` | [`RegisterFunctionInput`](#registerfunctioninput) \| dict[str, Any] \| str | Yes | A ``RegisterFunctionInput``, dict with ``id``, or a plain string function ID. When a string is passed, use keyword arguments for ``description``, ``metadata``, ``request_format``, and ``response_format``. |
| `function_id` | `str` | Yes | The unique function identifier (use `::` for namespacing, e.g. `external::my_lambda`). |
| `handler_or_invocation` | RemoteFunctionHandler \| [`HttpInvocationConfig`](#httpinvocationconfig) | Yes | A callable handler or ``HttpInvocationConfig``. Callable handlers receive one positional argument (``data`` -- the trigger payload) and may return a value. |
| `description` | `str \| None` | No | Human-readable description (only with string ID). |
| `metadata` | `dict[str, Any] \| None` | No | Arbitrary metadata (only with string ID). |
| `request_format` | [`RegisterFunctionFormat`](#registerfunctionformat) \| dict[str, Any] \| None | No | Schema describing expected input (only with string ID). Auto-extracted from handler type hints when omitted. |
| `response_format` | [`RegisterFunctionFormat`](#registerfunctionformat) \| dict[str, Any] \| None | No | Schema describing expected output (only with string ID). Auto-extracted from handler type hints when omitted. |
| `description` | `str \| None` | No | Human-readable description. |
| `metadata` | `dict[str, Any] \| None` | No | Arbitrary metadata. |
| `request_format` | [`RegisterFunctionFormat`](#registerfunctionformat) \| dict[str, Any] \| None | No | Schema describing expected input. Auto-extracted from handler type hints when omitted. |
| `response_format` | [`RegisterFunctionFormat`](#registerfunctionformat) \| dict[str, Any] \| None | No | Schema describing expected output. Auto-extracted from handler type hints when omitted. |

#### Example

```python
def greet(data):
return {'message': f"Hello, {data['name']}!"}
fn = iii.register_function({"id": "greet", "description": "Greets a user"}, greet)
fn = iii.register_function("greet", greet, description="Greets a user")
fn.unregister()
from pydantic import BaseModel
class GreetInput(BaseModel):
Expand Down Expand Up @@ -715,7 +715,7 @@ logger.warn('Retry attempt', {'attempt': 3, 'max_retries': 5, 'endpoint': '/api/

## Types

[`InitOptions`](#initoptions) · [`ReconnectionConfig`](#reconnectionconfig) · [`TelemetryOptions`](#telemetryoptions) · [`HttpInvocationConfig`](#httpinvocationconfig) · [`RegisterFunctionFormat`](#registerfunctionformat) · [`RegisterFunctionInput`](#registerfunctioninput) · [`RegisterServiceInput`](#registerserviceinput) · [`RegisterTriggerInput`](#registertriggerinput) · [`RegisterTriggerTypeInput`](#registertriggertypeinput) · [`TriggerActionEnqueue`](#triggeractionenqueue) · [`TriggerActionVoid`](#triggeractionvoid) · [`TriggerRequest`](#triggerrequest) · [`IStream`](#istream) · [`OtelConfig`](#otelconfig) · [`TriggerHandler`](#triggerhandler)
[`InitOptions`](#initoptions) · [`ReconnectionConfig`](#reconnectionconfig) · [`TelemetryOptions`](#telemetryoptions) · [`HttpInvocationConfig`](#httpinvocationconfig) · [`RegisterFunctionFormat`](#registerfunctionformat) · [`RegisterFunctionOptions`](#registerfunctionoptions) · [`RegisterServiceInput`](#registerserviceinput) · [`RegisterTriggerInput`](#registertriggerinput) · [`RegisterTriggerTypeInput`](#registertriggertypeinput) · [`TriggerActionEnqueue`](#triggeractionenqueue) · [`TriggerActionVoid`](#triggeractionvoid) · [`TriggerRequest`](#triggerrequest) · [`IStream`](#istream) · [`OtelConfig`](#otelconfig) · [`TriggerHandler`](#triggerhandler)

### InitOptions

Expand Down Expand Up @@ -779,18 +779,16 @@ Format definition for function parameters.
| `required` | `bool` | No | Whether the parameter is required. |
| `type` | `str` | Yes | Type string (``string``, ``number``, ``boolean``, ``object``, ``array``, ``null``, ``map``). |

### RegisterFunctionInput
### RegisterFunctionOptions

Input for registering a function — matches Node.js RegisterFunctionInput.
Optional configuration passed as keyword arguments when using the string ID form of `register_function`.

Comment on lines +782 to 785
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Drop the stale “string ID form” wording.

register_function is now documented with a required function_id: str, so this still implies the old object-based overload exists. Please rename this section and scrub the earlier func_or_id wording so the reference matches the new API.

Suggested wording
-Optional configuration passed as keyword arguments when using the string ID form of `register_function`.
+Optional keyword arguments accepted by `register_function`.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
### RegisterFunctionOptions
Input for registering a function — matches Node.js RegisterFunctionInput.
Optional configuration passed as keyword arguments when using the string ID form of `register_function`.
### RegisterFunctionOptions
Optional keyword arguments accepted by `register_function`.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/api-reference/sdk-python.mdx` around lines 782 - 785, Rename the section
and remove stale "string ID form" wording: update the heading and description
for RegisterFunctionOptions to reflect the current API that register_function
requires function_id: str (remove references to "string ID form" and any
mentions of func_or_id), and ensure all earlier occurrences in this document
that mention func_or_id or the old object-based overload are scrubbed or
rewritten to reference the new required parameter name function_id and the
current usage of register_function.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | `str \| None` | No | Human-readable description. |
| `id` | `str` | No | Unique function identifier. |
| `invocation` | [`HttpInvocationConfig`](#httpinvocationconfig) \| None | No | HTTP invocation config for externally hosted functions. |
| `metadata` | `dict[str, Any] \| None` | No | Arbitrary metadata attached to the function. |
| `request_format` | [`RegisterFunctionFormat`](#registerfunctionformat) \| dict[str, Any] \| None | No | Schema describing expected input. |
| `response_format` | [`RegisterFunctionFormat`](#registerfunctionformat) \| dict[str, Any] \| None | No | Schema describing expected output. |
| `request_format` | [`RegisterFunctionFormat`](#registerfunctionformat) \| dict[str, Any] \| None | No | Schema describing expected input. Auto-extracted from handler type hints when omitted. |
| `response_format` | [`RegisterFunctionFormat`](#registerfunctionformat) \| dict[str, Any] \| None | No | Schema describing expected output. Auto-extracted from handler type hints when omitted. |

### RegisterServiceInput

Expand Down
8 changes: 4 additions & 4 deletions docs/architecture/channels.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -207,8 +207,8 @@ def sender_handler(input_data):

return result

iii_client.register_function({"id": "data.processor"}, processor_handler)
iii_client.register_function({"id": "data.sender"}, sender_handler)
iii_client.register_function("data.processor", processor_handler)
iii_client.register_function("data.sender", sender_handler)
```
</Tab>
<Tab title="Rust">
Expand Down Expand Up @@ -449,8 +449,8 @@ def coordinator_handler(input_data):

return {"messages": messages, "binaryResult": binary_result}

iii_client.register_function({"id": "stream.worker"}, worker_handler)
iii_client.register_function({"id": "stream.coordinator"}, coordinator_handler)
iii_client.register_function("stream.worker", worker_handler)
iii_client.register_function("stream.coordinator", coordinator_handler)
```
</Tab>
<Tab title="Rust">
Expand Down
Loading
Loading