Upgrading from 0.19.x to 0.20.x

The 0.20.0 release reorganizes the SDK in a single breaking step: shared types moved into the new @iii-dev/helpers package, names were aligned across Node, Python, and Rust, observability moved into helpers, and the rest of the root surface was grouped into submodules. 0.20.0 is a clean break: the old root import paths are removed, not kept as deprecated aliases. Your app will not compile until every step below is applied. Two backward-compatible exceptions need no migration:

EnqueueResult (all languages) and TriggerActionVoid (Python) stay exported from the root SDK as companions to TriggerAction.
The standalone iii-observability packages remain published as deprecated shims. Migrate those at your own pace (Step 5).

For the rationale behind each change, see the 0.20.0 changelog.

Step 1: Add the new packages

Install the helpers package alongside the bumped SDK.

Node / TypeScript
Python
Rust

npm install iii-sdk@^0.20 @iii-dev/helpers

pip install "iii-sdk>=0.20" iii-helpers

cargo add iii-sdk@0.20 iii-helpers

Observability users can keep iii-observability (deprecated shim) for now or migrate it in Step 5.

Step 2: Rename the client handle

Rename ISdk (Node) and III (Rust) to IIIClient. Python already used IIIClient. In the same pass, rename the Rust telemetry config WorkerTelemetryMeta to TelemetryOptions.

Node / TypeScript
Python
Rust

// Before
import type { ISdk } from 'iii-sdk'
// After
import type { IIIClient } from 'iii-sdk'

# No change. Python already used IIIClient.

// Before
let sdk: III = /* ... */;
use iii_sdk::WorkerTelemetryMeta;
// After
let sdk: IIIClient = /* ... */;
use iii_sdk::TelemetryOptions;

Step 3: Update HTTP request/response types

Rename the buffered ApiRequest / ApiResponse types to HttpRequest / HttpResponse. They now live in the helpers http submodule, along with HttpAuthConfig and HttpInvocationConfig.

Node / TypeScript
Python
Rust

// Before
import { ApiRequest, ApiResponse } from 'iii-sdk'
// After
import { HttpRequest, HttpResponse } from '@iii-dev/helpers/http'

# Before
from iii import ApiRequest, ApiResponse
# After
from iii_helpers.http import HttpRequest, HttpResponse

// Before
use iii_sdk::{ApiRequest, ApiResponse};
// After
use iii_helpers::http::{HttpRequest, HttpResponse};

Only the buffered Api* types moved and were renamed. The streaming StreamRequest / StreamResponse types stay in the root SDK. Do not change them.

Step 4: Move shared types into @iii-dev/helpers

Shared types are grouped into four helpers submodules.

Group	Node	Python	Rust
http	`@iii-dev/helpers/http`	`iii_helpers.http`	`iii_helpers::http`
queue	`@iii-dev/helpers/queue`	`iii_helpers.queue`	`iii_helpers::queue`
stream	`@iii-dev/helpers/stream`	`iii_helpers.stream`	`iii_helpers::stream`
worker-connection-manager	`@iii-dev/helpers/worker-connection-manager`	`iii_helpers.worker_connection_manager`	`iii_helpers::worker_connection_manager`

UpdateOp, UpdateOpError, MergePath, UpdateSet, and UpdateMerge now live in the stream submodule; MergePath is a named export.

Node / TypeScript
Python
Rust

// Before
import { HttpAuthConfig } from 'iii-sdk'
// After
import { HttpAuthConfig } from '@iii-dev/helpers/http'

# Before
from iii import HttpInvocationConfig, AuthInput
# After
from iii_helpers.http import HttpInvocationConfig
from iii_helpers.worker_connection_manager import AuthInput

// Before
use iii_sdk::{HttpAuthConfig, StreamTriggerConfig};
// After
use iii_helpers::http::HttpAuthConfig;
use iii_helpers::stream::StreamTriggerConfig;

EnqueueResult is the exception in the queue submodule. Its canonical home is @iii-dev/helpers/queue (iii_helpers.queue / iii_helpers::queue), but it is also re-exported from the root SDK (iii-sdk / iii / iii_sdk) as the companion to TriggerAction.Enqueue. Do not migrate EnqueueResult.

For the complete list of moved symbols per submodule, see the Helpers reference.

Step 5: Update observability imports

Move observability imports into the helpers observability submodule.

Node / TypeScript
Python
Rust

// Before
import { Logger, initOtel, withSpan } from '@iii-dev/observability'
// After
import { Logger, initOtel, withSpan } from '@iii-dev/helpers/observability'

# Before
from iii_observability import Logger, init_otel, with_span
# After
from iii_helpers.observability import Logger, init_otel, with_span

// Before
use iii_observability::{Logger, init_otel, with_span};
// After
use iii_helpers::observability::{Logger, init_otel, with_span};

The standalone iii-observability packages remain published as deprecated shims, so this is the one step you can defer. The internal-only Node entry @iii-dev/observability/internal moved to @iii-dev/helpers/observability/internal with no shim.

Step 6: Update error types and handling

Rename IIIInvocationError to InvocationError (Node iii-sdk/errors, Python iii.errors) and the Rust IIIError to Error (iii_sdk::errors::Error). The old names are removed from the root with no deprecated alias.

Node / TypeScript
Python
Rust

// Before
import { IIIInvocationError } from 'iii-sdk'
// After
import { InvocationError } from 'iii-sdk/errors'

# Before
from iii import IIIInvocationError
# After
from iii.errors import InvocationError

// Before
use iii_sdk::IIIError;
// After
use iii_sdk::errors::Error;

IIIForbiddenError and IIITimeoutError (Python) are removed. Branch on err.code instead, matching Node and Rust.

# Before
try:
    ...
except IIIForbiddenError:
    ...
# After
except InvocationError as err:
    if err.code == "forbidden":
        ...

Step 7: Adopt submodule paths (engine / protocol / internal / utils)

The root exports for these groups are removed with no alias. In Rust, IIIConnectionState moves to iii_sdk::runtime.

Node / TypeScript
Python
Rust

// Before
import { RegisterTriggerInput, EngineFunctions } from 'iii-sdk'
// After
import { RegisterTriggerInput } from 'iii-sdk/protocol'
import { EngineFunctions } from 'iii-sdk/engine'

# Before
from iii import TriggerRequest, extract_request_format
# After
from iii.protocol import TriggerRequest
from iii.utils import extract_request_format

// Before
use iii_sdk::{TriggerRequest, EngineFunctions};
// After
use iii_sdk::protocol::TriggerRequest;
use iii_sdk::engine::EngineFunctions;

TriggerActionVoid (Python) is also grouped under iii.trigger, but it stays exported from the package root as the companion to TriggerActionEnqueue. It is reachable from both iii and iii.trigger. No migration needed.

Step 8: Adopt the errors / channel / trigger / runtime submodules

The old root paths for these four groups are also removed in 0.20.0. Import each type from its submodule.

Node / TypeScript
Python
Rust

// Before
import { ChannelReader, FunctionRef } from 'iii-sdk'
// After
import { ChannelReader } from 'iii-sdk/channel'
import type { FunctionRef } from 'iii-sdk/runtime'

# Before
from iii import ChannelReader, FunctionRef
# After
from iii.channel import ChannelReader
from iii.runtime import FunctionRef

// Before
use iii_sdk::{ChannelReader, FunctionRef};
// After
use iii_sdk::channel::ChannelReader;
use iii_sdk::runtime::FunctionRef;

Step 9: Replace removed APIs

A few APIs were removed outright:

Rust UpdateBuilder → use UpdateSet / UpdateMerge directly.
Rust FieldPath → the retained MergePath is the merge/append path argument.
Rust Value re-export removed → depend on serde_json directly.
Node TriggerActionType alias removed → use the TriggerAction value.

Node / TypeScript
Python
Rust

// Before
import { TriggerActionType } from 'iii-sdk'
// After
// Use the TriggerAction value directly; the TriggerActionType alias is gone.

# No change.

// Before
use iii_sdk::{UpdateBuilder, FieldPath, Value};
// After
use iii_helpers::stream::{UpdateSet, UpdateMerge, MergePath};
use serde_json::Value;

Migration checklist

Add @iii-dev/helpers and bump iii-sdk to 0.20.x
Rename ISdk/III → IIIClient
Move buffered Api* → Http* from @iii-dev/helpers/http
Move shared types to helpers submodules
Move observability imports (deferrable)
Rename III*Error → InvocationError/Error
Adopt engine/protocol/internal/utils paths
Adopt errors/channel/trigger/runtime paths
Replace removed Rust/Node APIs

Result

The worker builds against iii-sdk 0.20.x with shared types imported from @iii-dev/helpers, aligned names across the three languages, and submodule import paths throughout. Only the iii-observability shim still emits a deprecation signal until Step 5 is applied.

​Step 1: Add the new packages

​Step 2: Rename the client handle

​Step 3: Update HTTP request/response types

​Step 4: Move shared types into @iii-dev/helpers

​Step 5: Update observability imports

​Step 6: Update error types and handling

​Step 7: Adopt submodule paths (engine / protocol / internal / utils)

​Step 8: Adopt the errors / channel / trigger / runtime submodules

​Step 9: Replace removed APIs

​Migration checklist

​Result

Step 1: Add the new packages

Step 2: Rename the client handle

Step 3: Update HTTP request/response types

Step 4: Move shared types into @iii-dev/helpers

Step 5: Update observability imports

Step 6: Update error types and handling

Step 7: Adopt submodule paths (engine / protocol / internal / utils)

Step 8: Adopt the errors / channel / trigger / runtime submodules

Step 9: Replace removed APIs

Migration checklist

Result