zudello-chat-sdk 0.1.1

package/README.md

@@ -0,0 +1,325 @@
+# 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`):
+
+```bash
+npm install
+npm run build
+```
+
+Verify the build completed successfully (check `dist/` folder).
+
+### 2. Publish to npm
+
+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. Rebuild the E2B Template
+
+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`).
+
+### 4. Verify E2B Template
+
+Check your E2B dashboard or run:
+
+```bash
+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
+
+```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"
+
+### 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
+
+```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
+
+### Search
+
+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
+});
+```
+
+### Auto-Pagination with Async Iterators
+
+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}`);
+```
+
+### Fetch Single Resource
+
+```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'
+});
+```
+
+### Create Resource
+
+```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 }
+        ]
+    }
+});
+```
+
+### Update Resource
+
+```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

package/dist/cjs/client.js

@@ -0,0 +1,124 @@
+"use strict";
+/**
+ * Zudello SDK Client
+ *
+ * Main client class for interacting with the Zudello API.
+ * Designed for use in E2B sandboxes with environment variable configuration.
+ *
+ * @example
+ * import { ZudelloClient } 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: 'Transaction',
+ *     module: 'PURCHASING',
+ *     submodule: 'INVOICE',
+ *     filter: { status: 'REVIEW' }
+ * });
+ *
+ * // Auto-pagination with async iterators
+ * for await (const invoice of client.search.list({ model: 'Transaction', module: 'PURCHASING' })) {
+ *     console.log(invoice.document_number);
+ * }
+ *
+ * // Create resources
+ * await client.resources.create({
+ *     model: 'Supplier',
+ *     data: { trading_name: 'ACME Corp', code: 'SUP-001' }
+ * });
+ *
+ * // Organisation-level admin (requires privileges)
+ * const users = await client.org.listUsers();
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZudelloClient = void 0;
+const client_1 = require("./http/client");
+const search_1 = require("./modules/search");
+const resources_1 = require("./modules/resources");
+const models_1 = require("./modules/models");
+const config_1 = require("./modules/config");
+const sentences_1 = require("./modules/sentences");
+const automation_1 = require("./modules/automation");
+const approvals_1 = require("./modules/approvals");
+const users_1 = require("./modules/users");
+const org_1 = require("./modules/org");
+const datasets_1 = require("./modules/datasets");
+const exports_1 = require("./modules/exports");
+const quick_actions_1 = require("./modules/quick-actions");
+const inboxes_1 = require("./modules/inboxes");
+/**
+ * Main client for the Zudello API.
+ *
+ * Configuration is read from environment variables by default:
+ * - `ZUDELLO_TOKEN`: Authentication token (required)
+ * - `ZUDELLO_ORG_ID`: Organization UUID (required)
+ * - `ZUDELLO_TEAM_ID`: Team UUID (required)
+ * - `ZUDELLO_CLUSTER_URL`: API cluster URL (required)
+ * - `ZUDELLO_AUTH_API_BASE`: Auth API base URL (required)
+ * - `ZUDELLO_USER_ID`: User UUID (optional)
+ * - `ZUDELLO_USER_EMAIL`: User email (optional)
+ *
+ * @throws {ZudelloConfigurationError} If required configuration is missing
+ *
+ * @example
+ * // Auto-configured from environment
+ * const client = new ZudelloClient();
+ *
+ * // Or explicit configuration
+ * const client = new ZudelloClient({
+ *     token: 'your-token',
+ *     organizationId: 'org-uuid',
+ *     teamId: 'team-uuid',
+ *     clusterUrl: 'api.1.global.zudello.io',
+ *     authApiBase: 'https://auth.zudello.io'
+ * });
+ */
+class ZudelloClient {
+    /** Search and fetch operations */
+    search;
+    /** Resource CRUD and batch operations */
+    resources;
+    /** Model introspection */
+    models;
+    /** Configuration, field settings, statuses, document types */
+    config;
+    /** Sentences (automation rules) */
+    sentences;
+    /** Scripts, triggers, and execution logs */
+    automation;
+    /** Approval workflows and bulk operations */
+    approvals;
+    /** Team users, notifications, language settings */
+    users;
+    /** Organisation-level admin (requires privileges) */
+    org;
+    /** Datasets (lookup tables, DOAs) */
+    datasets;
+    /** Export templates and data exports */
+    exports;
+    /** Quick actions */
+    quickActions;
+    /** Inboxes, budgets, contracts, messages */
+    inboxes;
+    constructor(config) {
+        const http = new client_1.HttpClient(config);
+        this.search = new search_1.SearchModule(http);
+        this.resources = new resources_1.ResourcesModule(http);
+        this.models = new models_1.ModelsModule(http);
+        this.config = new config_1.ConfigModule(http);
+        this.sentences = new sentences_1.SentencesModule(http);
+        this.automation = new automation_1.AutomationModule(http);
+        this.approvals = new approvals_1.ApprovalsModule(http);
+        this.users = new users_1.UsersModule(http);
+        this.org = new org_1.OrgModule(http);
+        this.datasets = new datasets_1.DatasetsModule(http);
+        this.exports = new exports_1.ExportsModule(http);
+        this.quickActions = new quick_actions_1.QuickActionsModule(http);
+        this.inboxes = new inboxes_1.InboxesModule(http);
+    }
+}
+exports.ZudelloClient = ZudelloClient;
+//# sourceMappingURL=client.js.map

package/dist/cjs/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;;;AAEH,0CAA2C;AAC3C,6CAAgD;AAChD,mDAAsD;AACtD,6CAAgD;AAChD,6CAAgD;AAChD,mDAAsD;AACtD,qDAAwD;AACxD,mDAAsD;AACtD,2CAA8C;AAC9C,uCAA0C;AAC1C,iDAAoD;AACpD,+CAAkD;AAClD,2DAA6D;AAC7D,+CAAkD;AAIlD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAa,aAAa;IACxB,kCAAkC;IACzB,MAAM,CAAe;IAE9B,yCAAyC;IAChC,SAAS,CAAkB;IAEpC,0BAA0B;IACjB,MAAM,CAAe;IAE9B,8DAA8D;IACrD,MAAM,CAAe;IAE9B,mCAAmC;IAC1B,SAAS,CAAkB;IAEpC,4CAA4C;IACnC,UAAU,CAAmB;IAEtC,6CAA6C;IACpC,SAAS,CAAkB;IAEpC,mDAAmD;IAC1C,KAAK,CAAc;IAE5B,qDAAqD;IAC5C,GAAG,CAAY;IAExB,qCAAqC;IAC5B,QAAQ,CAAiB;IAElC,wCAAwC;IAC/B,OAAO,CAAgB;IAEhC,oBAAoB;IACX,YAAY,CAAqB;IAE1C,4CAA4C;IACnC,OAAO,CAAgB;IAEhC,YAAY,MAA4B;QACtC,MAAM,IAAI,GAAG,IAAI,mBAAU,CAAC,MAAM,CAAC,CAAC;QAEpC,IAAI,CAAC,MAAM,GAAG,IAAI,qBAAY,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,CAAC,SAAS,GAAG,IAAI,2BAAe,CAAC,IAAI,CAAC,CAAC;QAC3C,IAAI,CAAC,MAAM,GAAG,IAAI,qBAAY,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,CAAC,MAAM,GAAG,IAAI,qBAAY,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,CAAC,SAAS,GAAG,IAAI,2BAAe,CAAC,IAAI,CAAC,CAAC;QAC3C,IAAI,CAAC,UAAU,GAAG,IAAI,6BAAgB,CAAC,IAAI,CAAC,CAAC;QAC7C,IAAI,CAAC,SAAS,GAAG,IAAI,2BAAe,CAAC,IAAI,CAAC,CAAC;QAC3C,IAAI,CAAC,KAAK,GAAG,IAAI,mBAAW,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,CAAC,GAAG,GAAG,IAAI,eAAS,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,CAAC,QAAQ,GAAG,IAAI,yBAAc,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,CAAC,OAAO,GAAG,IAAI,uBAAa,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,CAAC,YAAY,GAAG,IAAI,kCAAkB,CAAC,IAAI,CAAC,CAAC;QACjD,IAAI,CAAC,OAAO,GAAG,IAAI,uBAAa,CAAC,IAAI,CAAC,CAAC;IACzC,CAAC;CACF;AAzDD,sCAyDC"}