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

1. Build the SDK

From this directory (zudello-sdk):

npm install
npm run build

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

2. Publish to npm

Make sure you're logged into npm:

npm login

Bump version and publish:

# 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. Rebuild the E2B Template

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

# 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).

4. Verify E2B Template

Check your E2B dashboard or run:

e2b template list

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

5. Update inapp-chat (if needed)

If the template ID changed, update it in:

• ../inapp-chat/src/lib/services/code-execution.ts

Look for ZUDELLO_TEMPLATE_ID or similar constant.

6. Test the Integration

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"

Troubleshooting

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 <template-id>

Installation

npm install zudello-chat-sdk

Quick Start

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

Search

Search for resources with filtering and pagination:

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
});

Auto-Pagination with Async Iterators

Iterate over all matching records automatically:

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}`);

Fetch Single Resource

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'
});

Create Resource

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 }
        ]
    }
});

Update Resource

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

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

// 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:

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:

// 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