# SDK Ecosystem

Release history for the Amigo TypeScript and Python SDKs.

{% hint style="info" %}
**TypeScript SDK**: v1.0.0-rc.1 | **Python SDK**: v1.0.0rc1
{% endhint %}

***

<details>

<summary>v1.0.0-rc.1 - New Resources, Breaking Changes, Branded Types (March 10, 2026)</summary>

First release candidate for both SDKs. Adds full CRUD for Agents, Context Graphs, and extended Services. Includes breaking changes to error handling, resource naming, and method signatures.

{% hint style="danger" %}
**Breaking changes**: TypeScript - `errors` namespace removed, positional params replaced with options objects. Python - `PermissionError` renamed to `ForbiddenError`, resource properties are now plural (`client.conversation` to `client.conversations`).
{% endhint %}

**Added**

**AgentResource** - Full CRUD for agents and agent versions:

* `createAgent` / `create_agent` - Create a new agent definition
* `getAgents` / `get_agents` - List agents with pagination
* `deleteAgent` / `delete_agent` - Deprecate an agent
* `createAgentVersion` / `create_agent_version` - Create a new agent version (supports dry run)
* `getAgentVersions` / `get_agent_versions` - List agent version history

**ContextGraphResource** - Full CRUD for context graphs and versions:

* `createContextGraph` / `create_context_graph` - Create a context graph
* `getContextGraphs` / `get_context_graphs` - List context graphs with pagination
* `deleteContextGraph` / `delete_context_graph` - Deprecate a context graph
* `createContextGraphVersion` / `create_context_graph_version` - Create a version (supports dry run)
* `getContextGraphVersions` / `get_context_graph_versions` - List version history

**ServiceResource extended**:

* `createService` / `create_service` - Create a new service
* `updateService` / `update_service` - Update a service
* `upsertVersionSet` / `upsert_version_set` - Create or update version sets (release, staging, dev)
* `deleteVersionSet` / `delete_version_set` - Remove a version set

**New Branded Types (TypeScript)**: `AgentId`, `ToolId`, `DynamicBehaviorSetId`, `MetricId`, `SimulationPersonaId`, `SimulationScenarioId`, `SimulationUnitTestId`, `SimulationUnitTestSetId`, `WebhookDestinationId`, `RoleId`, `ApiKeyId`

**Breaking Changes**

**TypeScript SDK**

**Removed `errors` namespace** - Import error classes individually.

| Impact | High | Action Required | Yes |
| ------ | ---- | --------------- | --- |

```typescript
// Before
import { errors } from '@amigo-ai/sdk'
throw new errors.NotFoundError(...)

// After
import { NotFoundError } from '@amigo-ai/sdk'
throw new NotFoundError(...)
```

**Options objects replace positional parameters** - Conversation and user methods now take options objects.

| Impact | High | Action Required | Yes |
| ------ | ---- | --------------- | --- |

```typescript
// Before
await client.conversations.getMessages(conversationId, limit, offset)

// After
await client.conversations.getMessages({ conversationId, limit, offset })
```

**`UserResource.get()` renamed to `getModel()`**

| Impact | Low | Action Required | If using `UserResource.get()` |
| ------ | --- | --------------- | ----------------------------- |

```typescript
// Before
const user = await client.users.get()

// After
const user = await client.users.getModel()
```

**Minimum Node.js version**: `engines.node >= 18` is now enforced in package.json. Removed rollup optional dependency.

**Python SDK**

**`PermissionError` renamed to `ForbiddenError`** - Avoids shadowing the Python builtin.

| Impact | High | Action Required | Yes |
| ------ | ---- | --------------- | --- |

```python
# Before
from amigo_sdk import PermissionError

# After
from amigo_sdk import ForbiddenError
```

**Sync `aclose()` renamed to `close()`** - Standard naming for sync context manager cleanup.

| Impact | Medium | Action Required | If using sync client |
| ------ | ------ | --------------- | -------------------- |

```python
# Before
client.aclose()

# After
client.close()
```

**Plural resource properties** - Resource accessors are now plural.

| Impact | High | Action Required | Yes |
| ------ | ---- | --------------- | --- |

```python
# Before
client.organization.get()
client.service.list()
client.conversation.create(...)

# After
client.organizations.get()
client.services.list()
client.conversations.create(...)
```

**Changed**

* **TypeScript**: `AmigoError` constructor now correctly maps `statusCode`/`errorCode` via `Object.assign` (was silently dropping fields)
* **Python**: `AmigoConfig` and all error classes exported from `__init__.py`
* **Python**: `scripts/` removed from wheel distribution; license and URLs added to `pyproject.toml`

**How to Get It**

```bash
# TypeScript
npm install @amigo-ai/sdk@1.0.0-rc.1

# Python
pip install amigo-sdk==1.0.0rc1
```

</details>

<details>

<summary>v0.5.0 - Webhook Type Safety, Rate Limit Headers, Cross-SDK Integration Tests (March 3, 2026)</summary>

Adds typed webhook event parsing with signature verification, rate limit header utilities, and a cross-SDK integration test suite.

**Added**

**Webhook Type Safety**:

* Typed interfaces/dataclasses for all webhook event types
* `parseWebhookEvent()` / `parse_webhook_event()` with HMAC-SHA256 signature verification
* Replay attack protection via configurable max age
* Exported from package root

**Rate Limit Header Exposure**:

* `RateLimitInfo` type with limit, remaining, reset fields
* `parseRateLimitHeaders()` / `parse_rate_limit_headers()` utility
* Parses `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` headers

**Cross-SDK Integration Tests**:

* End-to-end test: Python creates user → TypeScript creates conversation → Python interacts → TypeScript gets messages → Python finishes
* Runs nightly via GitHub Action

**Fixed**

* **Python**: Streaming timeout - httpx default 5s read timeout was killing streams before agent responses completed. Now uses 300s read timeout for streaming requests.

**Security**

* **Python**: Fixed `black` arbitrary file write vulnerability (Dependabot)
* **TypeScript**: Fixed `diff` DoS vulnerability in examples (Dependabot)
* **Both**: CodeQL workflow conflicts resolved

**How to Get It**

```bash
# TypeScript
npm install @amigo-ai/sdk@0.5.0

# Python
pip install amigo-sdk==0.5.0
```

</details>

<details>

<summary>v0.4.0 - Branded ID Types, Convenience Aliases, Type Safety (February 24, 2026)</summary>

Introduces compile-time ID type safety for TypeScript, convenience method aliases, and PEP 561 compliance for Python.

**Added**

**Branded ID Types (TypeScript)** - All ID parameters now use branded string types to prevent accidental ID swaps at compile time.

```typescript
import { conversationId, messageId } from '@amigo-ai/sdk'

// Compile-time error: ConversationId is not assignable to MessageId
const convId = conversationId('abc123')
const msgId = messageId('def456')
```

Available types: `ConversationId`, `MessageId`, `UserId`, `OrgId`, `InteractionId`, `ServiceId`

**Convenience Aliases** - Resource methods now include shorter aliases for common operations:

```typescript
// Both work - use whichever you prefer
const conversations = await client.conversations.getConversations()
const conversations = await client.conversations.list()
```

**Type Safety (Python)**:

* PEP 561 compliance: `py.typed` marker added for downstream type checking
* Explicit model exports replace wildcard barrel import in `models.py`
* `InteractionInput` TypedDict groups the 9+ parameters of `interact_with_conversation()` for cleaner call sites
* Streaming types tightened from `dict[str, Any]` to proper TypedDict

**Security**

* **TypeScript**: Error serialization sanitized to prevent bearer token leakage in logs. All 7 npm audit vulnerabilities resolved.
* **Python**: Response bodies in exceptions truncated to 500 chars and sanitized (token/key/secret fields stripped)

**How to Get It**

```bash
# TypeScript
npm install @amigo-ai/sdk@0.4.0

# Python
pip install amigo-sdk==0.4.0
```

</details>

***

## Version Compatibility

| SDK            | Version    | API Compatibility | Python/Node  |
| -------------- | ---------- | ----------------- | ------------ |
| **TypeScript** | 1.0.0-rc.1 | API v0.7.0+       | Node 18+     |
| **Python**     | 1.0.0rc1   | API v0.7.0+       | Python 3.11+ |