zudello-chat-sdk

TypeScript SDK for the Zudello API, designed for AI agent code execution in E2B sandboxes.

Setup Instructions

Follow these steps to publish the SDK and rebuild the E2B template.

Prerequisites:
- Node.js 20+
- npm account (for publishing)
- E2B account and API key

$3

From this directory (zudello-sdk):

``bash
npm install
npm run build
`

Verify the build completed successfully (check dist/ folder).

$3

Make sure you're logged into npm:

`bash
npm login
`

Bump version and publish:

`bash


For patch version bump (0.1.0 -> 0.1.1)

npm version patch

Or for minor version bump (0.1.0 -> 0.2.0)

npm version minor

Publish to npm

npm publish
`

$3

The E2B template needs to be rebuilt to include the latest SDK version:

`bash


Navigate to the E2B template directory (sibling to this repo)

cd ../e2b-zudello-template

Install E2B CLI if not already installed

npm install -g @e2b/cli

Login to E2B (if not already)

e2b auth login

Build the template (this takes a few minutes)

e2b template build
`

Note the template ID after building (should be zudello-chat-sandbox).

$3

Check your E2B dashboard or run:

`bash
e2b template list
`

You should see zudello-chat-sandbox with an updated timestamp.

$3

If the template ID changed, update it in:
- ../inapp-chat/src/lib/services/code-execution.ts

Look for ZUDELLO_TEMPLATE_ID or similar constant.

$3

`bash
cd ../inapp-chat
npm run dev
`

Then test with the Zudello agent by asking it to execute TypeScript code that uses the SDK.

Example test prompt:
> "Use code execution to list all pending invoices and their totals"

$3

Build errors:
- Run npm run typecheck to see type errors
- Check tsconfig.json paths

npm publish fails:
- Ensure you're logged in: npm whoami
- Check package name isn't taken
- Verify version was bumped

E2B template build fails:
- Check E2B API key is set: e2b auth status
- Review e2b.Dockerfile for errors
- Check E2B logs: e2b template logs

---

Installation

`bash
npm install zudello-chat-sdk
`

Quick Start

`typescript
import { ZudelloClient, MODELS, MODULES, SUBMODULES } from 'zudello-chat-sdk';

// Zero-config: reads from environment variables
const client = new ZudelloClient();

// Search for pending invoices
const invoices = await client.search.query({
model: MODELS.Transaction,
module: MODULES.PURCHASING,
submodule: SUBMODULES.INVOICE,
filter: { status: 'REVIEW', total__gt: 1000 },
select: ['uuid', 'document_number', 'total', 'status']
});

console.log(Found ${invoices.metadata?.count} invoices);
for (const invoice of invoices.data ?? []) {
console.log(${invoice.document_number}: $${invoice.total});
}
`

Environment Variables

The SDK reads configuration from environment variables by default:

| Variable | Required | Description |
|----------|----------|-------------|
| ZUDELLO_TOKEN | Yes | Authentication token |
| ZUDELLO_ORG_ID | Yes | Organization UUID |
| ZUDELLO_TEAM_ID | Yes | Team UUID |
| ZUDELLO_CLUSTER_URL | Yes | API cluster URL (e.g., api.1.global.zudello.io) |
| ZUDELLO_AUTH_API_BASE | Yes | Auth API base URL |
| ZUDELLO_USER_ID | No | User UUID |
| ZUDELLO_USER_EMAIL | No | User email |

Core Operations

$3

Search for resources with filtering and pagination:

`typescript
const invoices = await client.search.query({
model: 'Transaction',
module: 'PURCHASING',
submodule: 'INVOICE',
filter: {
status__in: ['REVIEW', 'APPROVAL'],
total__gt: 1000,
supplier__trading_name__icontains: 'acme'
},
select: ['uuid', 'document_number', 'total', 'date_due'],
order_by: ['-total', 'date_due'],
limit: 50
});
`

$3

Iterate over all matching records automatically:

`typescript
let totalValue = 0;

for await (const invoice of client.search.list({
model: 'Transaction',
module: 'PURCHASING',
submodule: 'INVOICE',
filter: { status: 'APPROVAL' },
select: ['uuid', 'document_number', 'total', 'status']
})) {
totalValue += invoice.total;
console.log(${invoice.document_number}: $${invoice.total});
}

console.log(Total pending approval: $${totalValue});
`

$3

`typescript
const supplier = await client.search.fetch('Supplier', { uuid: 'supplier-uuid-123' });
console.log(supplier.data?.trading_name);

// With related data
const invoice = await client.search.fetch('Transaction', { uuid: 'invoice-uuid' }, {
includeModels: 'supplier,lines,attachments'
});
`

$3

`typescript
const newPO = await client.resources.create({
model: 'Transaction',
module: 'PURCHASING',
submodule: 'ORDER',
data: {
supplier: 'supplier-uuid',
lines: [
{ description: 'Item 1', quantity: 10, unit_price: 99.99 }
]
}
});
`

$3

`typescript
const updated = await client.resources.update({
model: 'Transaction',
uuid: 'invoice-uuid',
data: { status: 'READY' }
});
`

Filter Operators

Append these suffixes to field names:

- __in - Value in list: status__in: ['REVIEW', 'APPROVAL']
- __gt, __gte - Greater than (or equal): total__gt: 1000
- __lt, __lte - Less than (or equal): total__lt: 5000
- __range - Value in range: total__range: [1000, 5000]
- __icontains - Case-insensitive contains: trading_name__icontains: 'acme'
- __startswith - Starts with: document_number__startswith: 'INV'
- __isnull - Is null check: supplier__isnull: false

Error Handling

`typescript
import {
ZudelloClient,
ZudelloAuthenticationError,
ZudelloValidationError,
ZudelloAPIError
} from 'zudello-chat-sdk';

try {
const result = await client.search.query({ model: 'Transaction' });
} catch (error) {
if (error instanceof ZudelloAuthenticationError) {
console.log('Token expired or invalid');
} else if (error instanceof ZudelloValidationError) {
console.log('Invalid request:', error.message);
} else if (error instanceof ZudelloAPIError) {
console.log(API error ${error.statusCode}:, error.message);
}
}
`

Model Introspection

`typescript
// List all available models
const models = await client.models.list();

// Get schema for a model
const schema = await client.models.getSchema('Transaction');
console.log('Fields:', Object.keys(schema.fields ?? {}));

// Get field metadata
const fields = await client.models.getFieldMetadata({
module: 'PURCHASING',
submodule: 'INVOICE',
section: 'filters'
});
`

Type-Safe Constants

Use exported constants for type safety:

`typescript
import { MODELS, MODULES, SUBMODULES, STATUS_KEYS } from 'zudello-chat-sdk';

const invoices = await client.search.query({
model: MODELS.Transaction,
module: MODULES.PURCHASING,
submodule: SUBMODULES.INVOICE,
filter: { status: STATUS_KEYS.REVIEW }
});
`

E2B Sandbox Usage

This SDK is designed for use in E2B sandboxes. Environment variables are automatically injected:

`typescript
// In E2B sandbox - just create the client
import { ZudelloClient } from 'zudello-chat-sdk';

const client = new ZudelloClient(); // Auto-configured from env vars

// All Zudello operations now available
const invoices = await client.search.query({
model: 'Transaction',
module: 'PURCHASING',
submodule: 'INVOICE'
});
``

License

MIT