TypeScript SDK for Zudello API - designed for AI agent code execution in E2B sandboxes
npm install zudello-chat-sdkTypeScript SDK for the Zudello API, designed for AI agent code execution in E2B sandboxes.
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
From this directory (zudello-sdk):
``bash`
npm install
npm run build
Verify the build completed successfully (check dist/ folder).
Make sure you're logged into npm:
`bash`
npm login
Bump version and publish:
`bashFor patch version bump (0.1.0 -> 0.1.1)
npm version patch
$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-templateInstall E2B CLI if not already installed
npm install -g @e2b/cliLogin to E2B (if not already)
e2b auth loginBuild 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.tsLook 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 pathsnpm publish fails:
- Ensure you're logged in:
npm whoami
- Check package name isn't taken
- Verify version was bumpedE2B 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: falseError 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'
});
``MIT