@unito/integration-sdk 2.4.4 → 3.0.1

package/CLAUDE.md

@@ -0,0 +1,80 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Is
+
+`@unito/integration-sdk` — a TypeScript framework for building REST API integrations compatible with the Unito Integration API Specification. It wraps Express 5 and provides handler routing, middleware chains for request parsing, structured logging, a Provider HTTP client for downstream APIs, and standardized error handling.
+
+## Commands
+
+```bash
+npm install              # Install deps (also runs compile via prepare hook)
+npm run compile          # Build ESM (tsc) + CJS (rollup)
+npm run compile:watch    # Watch mode recompile
+npm test                 # Run all tests
+ONLY=Handler npm test    # Run tests matching pattern "Handler"
+npm run test:debug       # Run tests with --inspect-brk
+npm run lint             # ESLint --fix + Prettier --write on src/ and test/
+```
+
+Tests use **Node.js built-in test runner** (`node:test` + `node:assert/strict`) with `ts-node/esm` loader — no compilation needed to run tests. HTTP mocking uses `nock`.
+
+## Architecture
+
+### Request Flow
+
+```
+HTTP Request
+  → finish (error/log hooks on response end)
+  → express.json (1MB limit)
+  → start (records hrtime)
+  → correlationId (generates/extracts X-Correlation-Id)
+  → logger (structured logger decorated with correlation ID)
+  → credentials (decodes base64 JSON from X-Unito-Credentials header)
+  → secrets (decodes base64 JSON from X-Unito-Secrets header)
+  → filters / search / selects / relations (parse query params)
+  → signal (AbortSignal from X-Unito-Operation-Deadline timestamp)
+  → Handler routes (user-registered)
+  → errors middleware (catches, formats HttpError responses)
+  → notFound middleware (404 fallback)
+```
+
+### Core Classes
+
+**Integration** (`src/integration.ts`) — entry point. Call `addHandler(path, handlers)` to register routes, then `start()`. All handlers must be added before `start()` — the server exits on violation.
+
+**Handler** (`src/handler.ts`) — takes a path and a handlers object, generates an Express Router. Path determines routing:
+- `/things/:thingId` — last segment is `:variable` → item route. `getItem` at `GET /things/:thingId`, `getCollection` at `GET /things`, `createItem` at `POST /things`, etc.
+- `/things` — no trailing variable → either item-level or collection-level ops, but not both on the same path.
+
+Handler types (pick one per `addHandler` call):
+- `ItemHandlers` — getItem, getCollection, createItem, updateItem, deleteItem
+- `BlobHandlers` — getBlob, createBlob
+- `CredentialAccountHandlers` — getCredentialAccount
+- `ParseWebhookHandlers`, `WebhookSubscriptionHandlers`, `AcknowledgeWebhookHandlers`
+
+**Provider** (`src/resources/provider.ts`) — HTTP client for calling downstream provider APIs. Initialized with `prepareRequest` (returns base URL + auth headers), optional `rateLimiter`, and optional `customErrorHandler`. Methods: `get`, `post`, `put`, `patch`, `delete`, `streamingGet`, `postForm`, `postStream`, `putBuffer`.
+
+**Context** (`src/resources/context.ts`) — typed context object passed to every handler. Contains `credentials`, `secrets`, `logger`, `signal`, `params`, `query`. GetCollectionContext additionally has `filters`, `search`, `selects`, `relations`. Create/Update contexts have `body`.
+
+**HttpErrors** (`src/httpErrors.ts`) — throw these from handlers for proper error responses. BadRequestError(400), UnauthorizedError(401), ForbiddenError(403), NotFoundError(404), TimeoutError(408), UnprocessableEntityError(422), ProviderInstanceLockedError(423), RateLimitExceededError(429). The latter two support `retryAfter`.
+
+### Logging
+
+Logger (`src/resources/logger.ts`) produces Datadog-compatible structured JSON in production, colored output in dev. Keys are auto-converted to snake_case. Sensitive fields (access_token, password, email, etc.) are auto-redacted. Log size truncated at 20KB (configurable via `MAX_LOG_MESSAGE_SIZE` env var).
+
+### Cache
+
+`Cache.create(redisUrl?)` returns a Redis-backed or local in-memory cache via the `cachette` library.
+
+## Code Conventions
+
+- **ES Modules** — `"type": "module"` in package.json. All internal imports use `.js` extensions (`import X from './foo.js'`).
+- **Dual output** — ESM via `tsc`, CJS via Rollup. Published with conditional exports.
+- **Strict TypeScript** — strict mode, noUncheckedIndexedAccess, exactOptionalPropertyTypes, no unused locals/params.
+- **Branded types** — e.g. `type Path = string & { __brand: 'Path' }` with assertion functions (`asserts path is Path`).
+- **No barrel files** — import directly from source modules, not from index re-exports.
+- **Prettier** — single quotes, trailing commas, 120 char width, no parens on single-param arrows.
+- **Test files** — `test/**/*.test.ts` mirroring src structure. Use `describe`/`it`/`beforeEach`/`afterEach` from `node:test`, assertions from `node:assert/strict`, mocking with `mock.method()`.
+- **Express typing** — `res.locals` is typed via global Express namespace augmentation.

package/dist/src/helpers.d.ts

@@ -13,3 +13,17 @@ import { Filter } from './index.js';
 export declare function getApplicableFilters(context: {
     filters: Filter[];
 }, fields: FieldSchema[]): Filter[];
+/**
+ * Use this helper function to build the query params for a collection next page URL.
+ * It re-encodes the parsed filters and selects back into query-param form,
+ * so integrations can easily construct `nextPage` URLs.
+ *
+ * @example
+ * const params = buildCollectionQueryParams({ filters: context.filters, selects: context.selects });
+ * params.append('cursor', nextCursor);
+ * return { info: { nextPage: `/items?${params.toString()}` }, data: [...] };
+ */
+export declare function buildCollectionQueryParams(params?: {
+    filters?: Filter[];
+    selects?: string[];
+}): URLSearchParams;

package/dist/src/helpers.js

@@ -26,3 +26,23 @@ export function getApplicableFilters(context, fields) {
     }
     return applicableFilters;
 }
+/**
+ * Use this helper function to build the query params for a collection next page URL.
+ * It re-encodes the parsed filters and selects back into query-param form,
+ * so integrations can easily construct `nextPage` URLs.
+ *
+ * @example
+ * const params = buildCollectionQueryParams({ filters: context.filters, selects: context.selects });
+ * params.append('cursor', nextCursor);
+ * return { info: { nextPage: `/items?${params.toString()}` }, data: [...] };
+ */
+export function buildCollectionQueryParams(params) {
+    const result = new URLSearchParams();
+    if (params?.filters?.length) {
+        result.set('filter', params.filters.map(f => `${f.field}${f.operator}${(f.values ?? []).map(encodeURIComponent).join('|')}`).join(','));
+    }
+    if (params?.selects?.length) {
+        result.set('select', params.selects.map(encodeURIComponent).join(','));
+    }
+    return result;
+}

package/dist/src/index.cjs

@@ -1305,7 +1305,13 @@ class Provider {
                                 if (body.error) {
                                     reject(this.handleError(400, body.error.message, options));
                                 }
-                                resolve({ status: 201, headers: response.headers, body });
+                                resolve({
+                                    status: 201,
+                                    headers: Object.fromEntries(Object.entries(response.headers)
+                                        .filter((entry) => entry[1] !== undefined)
+                                        .map(([key, value]) => [key, Array.isArray(value) ? value.join(',') : value])),
+                                    body,
+                                });
                             }
                             catch (error) {
                                 reject(this.handleError(500, `Failed to parse response body: "${error}"`, options));
@@ -1404,7 +1410,9 @@ class Provider {
                                 const body = responseBody ? JSON.parse(responseBody) : undefined;
                                 safeResolve({
                                     status: response.statusCode || 200,
-                                    headers: response.headers,
+                                    headers: Object.fromEntries(Object.entries(response.headers)
+                                        .filter((entry) => entry[1] !== undefined)
+                                        .map(([key, value]) => [key, Array.isArray(value) ? value.join(',') : value])),
                                     body,
                                 });
                             }
@@ -1624,7 +1632,11 @@ class Provider {
             }
             else if (response.status === 204 || response.body === null) {
                 // No content: return without inspecting the body
-                return { status: response.status, headers: response.headers, body: undefined };
+                return {
+                    status: response.status,
+                    headers: Object.fromEntries(response.headers.entries()),
+                    body: undefined,
+                };
             }
             const responseContentType = response.headers.get('content-type');
             let body;
@@ -1655,7 +1667,7 @@ class Provider {
             else {
                 throw this.handleError(500, 'Unsupported Content-Type', options);
             }
-            return { status: response.status, headers: response.headers, body };
+            return { status: response.status, headers: Object.fromEntries(response.headers.entries()), body };
         };
         return this.rateLimiter ? this.rateLimiter(options, callToProvider) : callToProvider();
     }
@@ -1693,6 +1705,26 @@ function getApplicableFilters(context, fields) {
     }
     return applicableFilters;
 }
+/**
+ * Use this helper function to build the query params for a collection next page URL.
+ * It re-encodes the parsed filters and selects back into query-param form,
+ * so integrations can easily construct `nextPage` URLs.
+ *
+ * @example
+ * const params = buildCollectionQueryParams({ filters: context.filters, selects: context.selects });
+ * params.append('cursor', nextCursor);
+ * return { info: { nextPage: `/items?${params.toString()}` }, data: [...] };
+ */
+function buildCollectionQueryParams(params) {
+    const result = new URLSearchParams();
+    if (params?.filters?.length) {
+        result.set('filter', params.filters.map(f => `${f.field}${f.operator}${(f.values ?? []).map(encodeURIComponent).join('|')}`).join(','));
+    }
+    if (params?.selects?.length) {
+        result.set('select', params.selects.map(encodeURIComponent).join(','));
+    }
+    return result;
+}
 
 exports.Api = integrationApi__namespace;
 exports.Cache = Cache;
@@ -1701,4 +1733,5 @@ exports.HttpErrors = httpErrors;
 exports.Integration = Integration;
 exports.NULL_LOGGER = NULL_LOGGER;
 exports.Provider = Provider;
+exports.buildCollectionQueryParams = buildCollectionQueryParams;
 exports.getApplicableFilters = getApplicableFilters;

package/dist/src/index.d.ts

@@ -7,6 +7,6 @@ export type { Secrets } from './middlewares/secrets.js';
 export type { Credentials } from './middlewares/credentials.js';
 export type { Filter } from './middlewares/filters.js';
 export * as HttpErrors from './httpErrors.js';
-export { getApplicableFilters } from './helpers.js';
+export { buildCollectionQueryParams, getApplicableFilters } from './helpers.js';
 export * from './resources/context.js';
 export { type default as Logger, NULL_LOGGER } from './resources/logger.js';

package/dist/src/index.js

@@ -5,7 +5,7 @@ export { default as Integration } from './integration.js';
 export * from './handler.js';
 export { Provider, } from './resources/provider.js';
 export * as HttpErrors from './httpErrors.js';
-export { getApplicableFilters } from './helpers.js';
+export { buildCollectionQueryParams, getApplicableFilters } from './helpers.js';
 export * from './resources/context.js';
 export { NULL_LOGGER } from './resources/logger.js';
 /* c8 ignore stop */

package/dist/src/resources/provider.d.ts

@@ -1,6 +1,5 @@
 import FormData from 'form-data';
 import * as stream from 'stream';
-import { IncomingHttpHeaders } from 'http';
 import * as HttpErrors from '../httpErrors.js';
 import { Credentials } from '../middlewares/credentials.js';
 import Logger from '../resources/logger.js';
@@ -55,7 +54,7 @@ export type RequestOptions = {
 export type Response<T> = {
     body: T;
     status: number;
-    headers: Headers | IncomingHttpHeaders;
+    headers: Record<string, string>;
 };
 export type PreparedRequest = {
     url: string;

package/dist/src/resources/provider.js

@@ -140,7 +140,13 @@ export class Provider {
                                 if (body.error) {
                                     reject(this.handleError(400, body.error.message, options));
                                 }
-                                resolve({ status: 201, headers: response.headers, body });
+                                resolve({
+                                    status: 201,
+                                    headers: Object.fromEntries(Object.entries(response.headers)
+                                        .filter((entry) => entry[1] !== undefined)
+                                        .map(([key, value]) => [key, Array.isArray(value) ? value.join(',') : value])),
+                                    body,
+                                });
                             }
                             catch (error) {
                                 reject(this.handleError(500, `Failed to parse response body: "${error}"`, options));
@@ -239,7 +245,9 @@ export class Provider {
                                 const body = responseBody ? JSON.parse(responseBody) : undefined;
                                 safeResolve({
                                     status: response.statusCode || 200,
-                                    headers: response.headers,
+                                    headers: Object.fromEntries(Object.entries(response.headers)
+                                        .filter((entry) => entry[1] !== undefined)
+                                        .map(([key, value]) => [key, Array.isArray(value) ? value.join(',') : value])),
                                     body,
                                 });
                             }
@@ -459,7 +467,11 @@ export class Provider {
             }
             else if (response.status === 204 || response.body === null) {
                 // No content: return without inspecting the body
-                return { status: response.status, headers: response.headers, body: undefined };
+                return {
+                    status: response.status,
+                    headers: Object.fromEntries(response.headers.entries()),
+                    body: undefined,
+                };
             }
             const responseContentType = response.headers.get('content-type');
             let body;
@@ -490,7 +502,7 @@ export class Provider {
             else {
                 throw this.handleError(500, 'Unsupported Content-Type', options);
             }
-            return { status: response.status, headers: response.headers, body };
+            return { status: response.status, headers: Object.fromEntries(response.headers.entries()), body };
         };
         return this.rateLimiter ? this.rateLimiter(options, callToProvider) : callToProvider();
     }

package/dist/test/helpers.test.js

@@ -1,7 +1,7 @@
 import { FieldValueTypes, OperatorTypes, Semantics } from '@unito/integration-api';
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
-import { getApplicableFilters } from '../src/helpers.js';
+import { buildCollectionQueryParams, getApplicableFilters } from '../src/helpers.js';
 describe('Helpers', () => {
     describe('getApplicableFilters', () => {
         it('returns only filters for defined fields', () => {
@@ -54,4 +54,98 @@ describe('Helpers', () => {
             assert.deepEqual(actual, []);
         });
     });
+    describe('buildCollectionQueryParams', () => {
+        it('encodes a single filter with one value', () => {
+            const result = buildCollectionQueryParams({
+                filters: [{ field: 'status', operator: OperatorTypes.EQUAL, values: ['active'] }],
+            });
+            assert.equal(result.get('filter'), 'status=active');
+            assert.equal(result.get('select'), null);
+        });
+        it('encodes filter values with special characters', () => {
+            const result = buildCollectionQueryParams({
+                filters: [{ field: 'status', operator: OperatorTypes.EQUAL, values: ['foo,bar'] }],
+            });
+            assert.equal(result.get('filter'), 'status=foo%2Cbar');
+        });
+        it('encodes filter values containing pipe characters', () => {
+            const result = buildCollectionQueryParams({
+                filters: [{ field: 'tags', operator: OperatorTypes.EQUAL, values: ['a|b'] }],
+            });
+            assert.equal(result.get('filter'), 'tags=a%7Cb');
+        });
+        it('joins multiple values for one filter with |', () => {
+            const result = buildCollectionQueryParams({
+                filters: [{ field: 'status', operator: OperatorTypes.EQUAL, values: ['active', 'pending'] }],
+            });
+            assert.equal(result.get('filter'), 'status=active|pending');
+        });
+        it('joins multiple filters with ,', () => {
+            const result = buildCollectionQueryParams({
+                filters: [
+                    { field: 'status', operator: OperatorTypes.EQUAL, values: ['active'] },
+                    { field: 'name', operator: OperatorTypes.INCLUDE, values: ['john'] },
+                ],
+            });
+            assert.equal(result.get('filter'), 'status=active,name*=john');
+        });
+        it('handles IS_NULL operator (no values)', () => {
+            const result = buildCollectionQueryParams({
+                filters: [{ field: 'status', operator: OperatorTypes.IS_NULL, values: [] }],
+            });
+            assert.equal(result.get('filter'), 'status!!');
+        });
+        it('handles IS_NULL operator with undefined values', () => {
+            const result = buildCollectionQueryParams({
+                filters: [{ field: 'status', operator: OperatorTypes.IS_NULL, values: undefined }],
+            });
+            assert.equal(result.get('filter'), 'status!!');
+        });
+        it('handles IS_NOT_NULL operator (no values)', () => {
+            const result = buildCollectionQueryParams({
+                filters: [{ field: 'assignee', operator: OperatorTypes.IS_NOT_NULL, values: [] }],
+            });
+            assert.equal(result.get('filter'), 'assignee!');
+        });
+        it('encodes selects', () => {
+            const result = buildCollectionQueryParams({
+                selects: ['name', 'dept.id'],
+            });
+            assert.equal(result.get('select'), 'name,dept.id');
+            assert.equal(result.get('filter'), null);
+        });
+        it('encodes selects with special characters', () => {
+            const result = buildCollectionQueryParams({
+                selects: ['field with spaces'],
+            });
+            assert.equal(result.get('select'), 'field%20with%20spaces');
+        });
+        it('encodes both filters and selects', () => {
+            const result = buildCollectionQueryParams({
+                filters: [{ field: 'status', operator: OperatorTypes.EQUAL, values: ['active'] }],
+                selects: ['name', 'status'],
+            });
+            assert.equal(result.get('filter'), 'status=active');
+            assert.equal(result.get('select'), 'name,status');
+        });
+        it('returns empty URLSearchParams when called with no arguments', () => {
+            const result = buildCollectionQueryParams();
+            assert.equal(result.toString(), '');
+        });
+        it('omits filter key for empty filters array', () => {
+            const result = buildCollectionQueryParams({ filters: [] });
+            assert.equal(result.get('filter'), null);
+        });
+        it('omits select key for empty selects array', () => {
+            const result = buildCollectionQueryParams({ selects: [] });
+            assert.equal(result.get('select'), null);
+        });
+        it('can be extended with additional params (e.g. cursor)', () => {
+            const result = buildCollectionQueryParams({
+                selects: ['name'],
+            });
+            result.append('cursor', 'abc123');
+            assert.equal(result.toString(), 'select=name&cursor=abc123');
+        });
+    });
 });