@unito/integration-sdk 3.0.0 → 4.0.0

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

@@ -1705,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;
@@ -1713,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/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');
+        });
+    });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unito/integration-sdk",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "Integration SDK",
   "type": "module",
   "types": "dist/src/index.d.ts",
@@ -53,7 +53,7 @@
   },
   "dependencies": {
     "@types/express": "5.x",
-    "@unito/integration-api": "4.x",
+    "@unito/integration-api": "5.x",
     "busboy": "^1.6.0",
     "cachette": "4.x",
     "express": "^5.1",

package/src/helpers.ts

@@ -35,3 +35,30 @@ export function getApplicableFilters(context: { filters: Filter[] }, fields: Fie
 
   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?: { filters?: Filter[]; selects?: string[] }): URLSearchParams {
+  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/src/index.ts

@@ -14,7 +14,7 @@ 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';
 /* c8 ignore stop */

package/test/helpers.test.ts

@@ -2,7 +2,7 @@ import { FieldValueTypes, OperatorTypes, Semantics } from '@unito/integration-ap
 
 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', () => {
@@ -72,4 +72,113 @@ 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');
+    });
+  });
 });