@unito/integration-sdk 4.1.0 → 4.2.0

package/dist/src/index.cjs

@@ -6,6 +6,7 @@ var crypto = require('crypto');
 var util = require('util');
 var express = require('express');
 var busboy = require('busboy');
+var fs = require('fs');
 var https = require('https');
 
 function _interopNamespaceDefault(e) {
@@ -1190,6 +1191,10 @@ class Provider {
      * The Rate Limiter function to use to limit the rate of calls made to the provider based on the caller's credentials.
      */
     rateLimiter = undefined;
+    static recordingSeq = 0;
+    static get recordingPath() {
+        return process.env.UNITO_SCHEMA_SNAPSHOT_RECORD_PATH;
+    }
     /**
      * Function called before each request to define the Provider's base URL and any specific headers to add to the requests.
      *
@@ -1313,9 +1318,7 @@ class Provider {
                                 }
                                 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])),
+                                    headers: Provider.normalizeNodeHeaders(response.headers),
                                     body,
                                 });
                             }
@@ -1416,9 +1419,7 @@ class Provider {
                                 const body = responseBody ? JSON.parse(responseBody) : undefined;
                                 safeResolve({
                                     status: response.statusCode || 200,
-                                    headers: Object.fromEntries(Object.entries(response.headers)
-                                        .filter((entry) => entry[1] !== undefined)
-                                        .map(([key, value]) => [key, Array.isArray(value) ? value.join(',') : value])),
+                                    headers: Provider.normalizeNodeHeaders(response.headers),
                                     body,
                                 });
                             }
@@ -1632,6 +1633,32 @@ class Provider {
                     },
                 },
             });
+            // Record raw response for schema-snapshot coverage analysis.
+            // Clone the response before consuming the body so recording doesn't interfere with normal flow.
+            // Only record JSON-like responses (skip binary streams and raw body requests).
+            if (Provider.recordingPath &&
+                !options.rawBody &&
+                headers.Accept !== 'application/octet-stream' &&
+                response.status < 400) {
+                try {
+                    const cloned = response.clone();
+                    const recordBody = await cloned.json().catch(() => undefined);
+                    if (recordBody !== undefined) {
+                        Provider.recordingSeq++;
+                        const entry = JSON.stringify({
+                            seq: Provider.recordingSeq,
+                            url: absoluteUrl,
+                            method: options.method,
+                            status: response.status,
+                            body: recordBody,
+                        });
+                        fs.appendFileSync(Provider.recordingPath, entry + '\n');
+                    }
+                }
+                catch {
+                    // Recording failure should never break the integration.
+                }
+            }
             if (response.status >= 400) {
                 const textResult = await response.text();
                 throw this.handleError(response.status, textResult, options);
@@ -1677,6 +1704,15 @@ class Provider {
         };
         return this.rateLimiter ? this.rateLimiter(options, callToProvider) : callToProvider();
     }
+    /**
+     * Normalizes Node.js IncomingHttpHeaders (which may have undefined or string[] values)
+     * into a flat Record<string, string> by joining array values and dropping undefined entries.
+     */
+    static normalizeNodeHeaders(headers) {
+        return Object.fromEntries(Object.entries(headers)
+            .filter((entry) => entry[1] !== undefined)
+            .map(([key, value]) => [key, Array.isArray(value) ? value.join(',') : value]));
+    }
     handleError(responseStatus, message, options) {
         const customError = this.customErrorHandler?.(responseStatus, message, options);
         return customError ?? buildHttpError(responseStatus, message);

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

@@ -80,6 +80,8 @@ export declare class Provider {
      * The Rate Limiter function to use to limit the rate of calls made to the provider based on the caller's credentials.
      */
     protected rateLimiter: RateLimiter | undefined;
+    private static recordingSeq;
+    private static get recordingPath();
     /**
      * Function called before each request to define the Provider's base URL and any specific headers to add to the requests.
      *
@@ -219,5 +221,10 @@ export declare class Provider {
     delete<T = undefined>(endpoint: string, options: RequestOptions, body?: RequestBody | null): Promise<Response<T>>;
     private generateAbsoluteUrl;
     private fetchWrapper;
+    /**
+     * Normalizes Node.js IncomingHttpHeaders (which may have undefined or string[] values)
+     * into a flat Record<string, string> by joining array values and dropping undefined entries.
+     */
+    private static normalizeNodeHeaders;
     private handleError;
 }

package/dist/src/resources/provider.js

@@ -1,3 +1,4 @@
+import fs from 'fs';
 import https from 'https';
 import { buildHttpError } from '../errors.js';
 /**
@@ -19,6 +20,10 @@ export class Provider {
      * The Rate Limiter function to use to limit the rate of calls made to the provider based on the caller's credentials.
      */
     rateLimiter = undefined;
+    static recordingSeq = 0;
+    static get recordingPath() {
+        return process.env.UNITO_SCHEMA_SNAPSHOT_RECORD_PATH;
+    }
     /**
      * Function called before each request to define the Provider's base URL and any specific headers to add to the requests.
      *
@@ -142,9 +147,7 @@ export class Provider {
                                 }
                                 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])),
+                                    headers: Provider.normalizeNodeHeaders(response.headers),
                                     body,
                                 });
                             }
@@ -245,9 +248,7 @@ export class Provider {
                                 const body = responseBody ? JSON.parse(responseBody) : undefined;
                                 safeResolve({
                                     status: response.statusCode || 200,
-                                    headers: Object.fromEntries(Object.entries(response.headers)
-                                        .filter((entry) => entry[1] !== undefined)
-                                        .map(([key, value]) => [key, Array.isArray(value) ? value.join(',') : value])),
+                                    headers: Provider.normalizeNodeHeaders(response.headers),
                                     body,
                                 });
                             }
@@ -461,6 +462,32 @@ export class Provider {
                     },
                 },
             });
+            // Record raw response for schema-snapshot coverage analysis.
+            // Clone the response before consuming the body so recording doesn't interfere with normal flow.
+            // Only record JSON-like responses (skip binary streams and raw body requests).
+            if (Provider.recordingPath &&
+                !options.rawBody &&
+                headers.Accept !== 'application/octet-stream' &&
+                response.status < 400) {
+                try {
+                    const cloned = response.clone();
+                    const recordBody = await cloned.json().catch(() => undefined);
+                    if (recordBody !== undefined) {
+                        Provider.recordingSeq++;
+                        const entry = JSON.stringify({
+                            seq: Provider.recordingSeq,
+                            url: absoluteUrl,
+                            method: options.method,
+                            status: response.status,
+                            body: recordBody,
+                        });
+                        fs.appendFileSync(Provider.recordingPath, entry + '\n');
+                    }
+                }
+                catch {
+                    // Recording failure should never break the integration.
+                }
+            }
             if (response.status >= 400) {
                 const textResult = await response.text();
                 throw this.handleError(response.status, textResult, options);
@@ -506,6 +533,15 @@ export class Provider {
         };
         return this.rateLimiter ? this.rateLimiter(options, callToProvider) : callToProvider();
     }
+    /**
+     * Normalizes Node.js IncomingHttpHeaders (which may have undefined or string[] values)
+     * into a flat Record<string, string> by joining array values and dropping undefined entries.
+     */
+    static normalizeNodeHeaders(headers) {
+        return Object.fromEntries(Object.entries(headers)
+            .filter((entry) => entry[1] !== undefined)
+            .map(([key, value]) => [key, Array.isArray(value) ? value.join(',') : value]));
+    }
     handleError(responseStatus, message, options) {
         const customError = this.customErrorHandler?.(responseStatus, message, options);
         return customError ?? buildHttpError(responseStatus, message);

package/dist/test/resources/provider.test.js

@@ -1,5 +1,6 @@
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
+import fs from 'fs';
 import { Readable } from 'stream';
 import nock from 'nock';
 import https from 'https';
@@ -1225,4 +1226,114 @@ describe('Provider', () => {
         // Verify the signal is indeed aborted
         assert.ok(abortController.signal.aborted, 'Signal should be aborted');
     });
+    describe('response recording', () => {
+        it('records JSON responses to JSONL file when env var is set', async () => {
+            const tmpFile = `/tmp/provider-recording-test-${Date.now()}.jsonl`;
+            process.env.UNITO_SCHEMA_SNAPSHOT_RECORD_PATH = tmpFile;
+            try {
+                const recordingProvider = new Provider({
+                    prepareRequest: () => ({
+                        url: 'https://www.myApi.com',
+                        headers: { 'Content-Type': 'application/json' },
+                    }),
+                });
+                nock('https://www.myApi.com').get('/items').reply(200, { id: '123', name: 'Test', priority: 'high' });
+                await recordingProvider.get('/items', {
+                    credentials: { unitoCredentialId: '123' },
+                    logger,
+                });
+                const content = fs.readFileSync(tmpFile, 'utf-8');
+                const lines = content.trim().split('\n');
+                assert.equal(lines.length, 1);
+                const entry = JSON.parse(lines[0]);
+                assert.ok(typeof entry.seq === 'number' && entry.seq > 0, `seq should be a positive number, got ${entry.seq}`);
+                assert.equal(entry.url, 'https://www.myApi.com/items');
+                assert.equal(entry.method, 'GET');
+                assert.equal(entry.status, 200);
+                assert.deepEqual(entry.body, { id: '123', name: 'Test', priority: 'high' });
+            }
+            finally {
+                delete process.env.UNITO_SCHEMA_SNAPSHOT_RECORD_PATH;
+                try {
+                    fs.unlinkSync(tmpFile);
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        });
+        it('does not record when env var is not set', async () => {
+            delete process.env.UNITO_SCHEMA_SNAPSHOT_RECORD_PATH;
+            const noRecordProvider = new Provider({
+                prepareRequest: () => ({
+                    url: 'https://www.myApi.com',
+                    headers: { 'Content-Type': 'application/json' },
+                }),
+            });
+            nock('https://www.myApi.com').get('/no-record').reply(200, { id: '123' });
+            await noRecordProvider.get('/no-record', {
+                credentials: { unitoCredentialId: '123' },
+                logger,
+            });
+            // No assertion needed — just ensure no crash.
+        });
+        it('does not record stream responses', async () => {
+            const tmpFile = `/tmp/provider-recording-stream-test-${Date.now()}.jsonl`;
+            process.env.UNITO_SCHEMA_SNAPSHOT_RECORD_PATH = tmpFile;
+            try {
+                const recordingProvider = new Provider({
+                    prepareRequest: () => ({
+                        url: 'https://www.myApi.com',
+                        headers: {},
+                    }),
+                });
+                nock('https://www.myApi.com')
+                    .get('/download')
+                    .reply(200, 'binary-data', { 'Content-Type': 'application/octet-stream' });
+                await recordingProvider.streamingGet('/download', {
+                    credentials: { unitoCredentialId: '123' },
+                    logger,
+                });
+                assert.equal(fs.existsSync(tmpFile), false);
+            }
+            finally {
+                delete process.env.UNITO_SCHEMA_SNAPSHOT_RECORD_PATH;
+                try {
+                    fs.unlinkSync(tmpFile);
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        });
+        it('increments seq across multiple requests', async () => {
+            const tmpFile = `/tmp/provider-recording-seq-test-${Date.now()}.jsonl`;
+            process.env.UNITO_SCHEMA_SNAPSHOT_RECORD_PATH = tmpFile;
+            try {
+                const recordingProvider = new Provider({
+                    prepareRequest: () => ({
+                        url: 'https://www.myApi.com',
+                        headers: { 'Content-Type': 'application/json' },
+                    }),
+                });
+                nock('https://www.myApi.com').get('/a').reply(200, { id: '1' }).get('/b').reply(200, { id: '2' });
+                await recordingProvider.get('/a', { credentials: { unitoCredentialId: '123' }, logger });
+                await recordingProvider.get('/b', { credentials: { unitoCredentialId: '123' }, logger });
+                const lines = fs.readFileSync(tmpFile, 'utf-8').trim().split('\n');
+                assert.equal(lines.length, 2);
+                const seq1 = JSON.parse(lines[0]).seq;
+                const seq2 = JSON.parse(lines[1]).seq;
+                assert.equal(seq2, seq1 + 1, `second seq (${seq2}) should be first seq (${seq1}) + 1`);
+            }
+            finally {
+                delete process.env.UNITO_SCHEMA_SNAPSHOT_RECORD_PATH;
+                try {
+                    fs.unlinkSync(tmpFile);
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        });
+    });
 });

package/package.json

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

package/src/resources/provider.ts

@@ -1,3 +1,4 @@
+import fs from 'fs';
 import https from 'https';
 import FormData from 'form-data';
 import * as stream from 'stream';
@@ -85,6 +86,12 @@ export class Provider {
    * The Rate Limiter function to use to limit the rate of calls made to the provider based on the caller's credentials.
    */
   protected rateLimiter: RateLimiter | undefined = undefined;
+
+  private static recordingSeq = 0;
+  private static get recordingPath(): string | undefined {
+    return process.env.UNITO_SCHEMA_SNAPSHOT_RECORD_PATH;
+  }
+
   /**
    * Function called before each request to define the Provider's base URL and any specific headers to add to the requests.
    *
@@ -232,11 +239,7 @@ export class Provider {
                 }
                 resolve({
                   status: 201,
-                  headers: Object.fromEntries(
-                    Object.entries(response.headers)
-                      .filter((entry): entry is [string, string | string[]] => entry[1] !== undefined)
-                      .map(([key, value]) => [key, Array.isArray(value) ? value.join(',') : value]),
-                  ),
+                  headers: Provider.normalizeNodeHeaders(response.headers),
                   body,
                 });
               } catch (error) {
@@ -353,11 +356,7 @@ export class Provider {
                 const body = responseBody ? JSON.parse(responseBody) : undefined;
                 safeResolve({
                   status: response.statusCode || 200,
-                  headers: Object.fromEntries(
-                    Object.entries(response.headers)
-                      .filter((entry): entry is [string, string | string[]] => entry[1] !== undefined)
-                      .map(([key, value]) => [key, Array.isArray(value) ? value.join(',') : value]),
-                  ),
+                  headers: Provider.normalizeNodeHeaders(response.headers),
                   body,
                 });
               } catch (error) {
@@ -613,6 +612,34 @@ export class Provider {
         },
       );
 
+      // Record raw response for schema-snapshot coverage analysis.
+      // Clone the response before consuming the body so recording doesn't interfere with normal flow.
+      // Only record JSON-like responses (skip binary streams and raw body requests).
+      if (
+        Provider.recordingPath &&
+        !options.rawBody &&
+        headers.Accept !== 'application/octet-stream' &&
+        response.status < 400
+      ) {
+        try {
+          const cloned = response.clone();
+          const recordBody = await cloned.json().catch(() => undefined);
+          if (recordBody !== undefined) {
+            Provider.recordingSeq++;
+            const entry = JSON.stringify({
+              seq: Provider.recordingSeq,
+              url: absoluteUrl,
+              method: options.method,
+              status: response.status,
+              body: recordBody,
+            });
+            fs.appendFileSync(Provider.recordingPath, entry + '\n');
+          }
+        } catch {
+          // Recording failure should never break the integration.
+        }
+      }
+
       if (response.status >= 400) {
         const textResult = await response.text();
         throw this.handleError(response.status, textResult, options);
@@ -663,6 +690,18 @@ export class Provider {
     return this.rateLimiter ? this.rateLimiter(options, callToProvider) : callToProvider();
   }
 
+  /**
+   * Normalizes Node.js IncomingHttpHeaders (which may have undefined or string[] values)
+   * into a flat Record<string, string> by joining array values and dropping undefined entries.
+   */
+  private static normalizeNodeHeaders(headers: Record<string, string | string[] | undefined>): Record<string, string> {
+    return Object.fromEntries(
+      Object.entries(headers)
+        .filter((entry): entry is [string, string | string[]] => entry[1] !== undefined)
+        .map(([key, value]) => [key, Array.isArray(value) ? value.join(',') : value]),
+    );
+  }
+
   private handleError(responseStatus: number, message: string, options: RequestOptions): HttpErrors.HttpError {
     const customError = this.customErrorHandler?.(responseStatus, message, options);
 

package/test/resources/provider.test.ts

@@ -1,5 +1,6 @@
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
+import fs from 'fs';
 import { Readable } from 'stream';
 import nock from 'nock';
 import https from 'https';
@@ -1461,4 +1462,128 @@ describe('Provider', () => {
     // Verify the signal is indeed aborted
     assert.ok(abortController.signal.aborted, 'Signal should be aborted');
   });
+
+  describe('response recording', () => {
+    it('records JSON responses to JSONL file when env var is set', async () => {
+      const tmpFile = `/tmp/provider-recording-test-${Date.now()}.jsonl`;
+      process.env.UNITO_SCHEMA_SNAPSHOT_RECORD_PATH = tmpFile;
+
+      try {
+        const recordingProvider = new Provider({
+          prepareRequest: () => ({
+            url: 'https://www.myApi.com',
+            headers: { 'Content-Type': 'application/json' },
+          }),
+        });
+
+        nock('https://www.myApi.com').get('/items').reply(200, { id: '123', name: 'Test', priority: 'high' });
+
+        await recordingProvider.get('/items', {
+          credentials: { unitoCredentialId: '123' },
+          logger,
+        });
+
+        const content = fs.readFileSync(tmpFile, 'utf-8');
+        const lines = content.trim().split('\n');
+        assert.equal(lines.length, 1);
+
+        const entry = JSON.parse(lines[0]!);
+        assert.ok(typeof entry.seq === 'number' && entry.seq > 0, `seq should be a positive number, got ${entry.seq}`);
+        assert.equal(entry.url, 'https://www.myApi.com/items');
+        assert.equal(entry.method, 'GET');
+        assert.equal(entry.status, 200);
+        assert.deepEqual(entry.body, { id: '123', name: 'Test', priority: 'high' });
+      } finally {
+        delete process.env.UNITO_SCHEMA_SNAPSHOT_RECORD_PATH;
+        try {
+          fs.unlinkSync(tmpFile);
+        } catch {
+          /* ignore */
+        }
+      }
+    });
+
+    it('does not record when env var is not set', async () => {
+      delete process.env.UNITO_SCHEMA_SNAPSHOT_RECORD_PATH;
+
+      const noRecordProvider = new Provider({
+        prepareRequest: () => ({
+          url: 'https://www.myApi.com',
+          headers: { 'Content-Type': 'application/json' },
+        }),
+      });
+
+      nock('https://www.myApi.com').get('/no-record').reply(200, { id: '123' });
+
+      await noRecordProvider.get('/no-record', {
+        credentials: { unitoCredentialId: '123' },
+        logger,
+      });
+      // No assertion needed — just ensure no crash.
+    });
+
+    it('does not record stream responses', async () => {
+      const tmpFile = `/tmp/provider-recording-stream-test-${Date.now()}.jsonl`;
+      process.env.UNITO_SCHEMA_SNAPSHOT_RECORD_PATH = tmpFile;
+
+      try {
+        const recordingProvider = new Provider({
+          prepareRequest: () => ({
+            url: 'https://www.myApi.com',
+            headers: {},
+          }),
+        });
+
+        nock('https://www.myApi.com')
+          .get('/download')
+          .reply(200, 'binary-data', { 'Content-Type': 'application/octet-stream' });
+
+        await recordingProvider.streamingGet('/download', {
+          credentials: { unitoCredentialId: '123' },
+          logger,
+        });
+
+        assert.equal(fs.existsSync(tmpFile), false);
+      } finally {
+        delete process.env.UNITO_SCHEMA_SNAPSHOT_RECORD_PATH;
+        try {
+          fs.unlinkSync(tmpFile);
+        } catch {
+          /* ignore */
+        }
+      }
+    });
+
+    it('increments seq across multiple requests', async () => {
+      const tmpFile = `/tmp/provider-recording-seq-test-${Date.now()}.jsonl`;
+      process.env.UNITO_SCHEMA_SNAPSHOT_RECORD_PATH = tmpFile;
+
+      try {
+        const recordingProvider = new Provider({
+          prepareRequest: () => ({
+            url: 'https://www.myApi.com',
+            headers: { 'Content-Type': 'application/json' },
+          }),
+        });
+
+        nock('https://www.myApi.com').get('/a').reply(200, { id: '1' }).get('/b').reply(200, { id: '2' });
+
+        await recordingProvider.get('/a', { credentials: { unitoCredentialId: '123' }, logger });
+        await recordingProvider.get('/b', { credentials: { unitoCredentialId: '123' }, logger });
+
+        const lines = fs.readFileSync(tmpFile, 'utf-8').trim().split('\n');
+        assert.equal(lines.length, 2);
+        const seq1 = JSON.parse(lines[0]!).seq;
+        const seq2 = JSON.parse(lines[1]!).seq;
+        assert.equal(seq2, seq1 + 1, `second seq (${seq2}) should be first seq (${seq1}) + 1`);
+      } finally {
+        delete process.env.UNITO_SCHEMA_SNAPSHOT_RECORD_PATH;
+        try {
+          fs.unlinkSync(tmpFile);
+        } catch {
+          /* ignore */
+        }
+      }
+    });
+  });
 });