@devrev/airsync-sdk 2.0.0-beta.10 → 2.0.0-beta.12

package/README.md

@@ -15,3 +15,4 @@ npm install @devrev/airsync-sdk
 - [Architecture](docs/ARCHITECTURE.md): how the SDK works and how it talks to the AirSync platform.
 - [Migration from v1](docs/MIGRATION.md): moving from `@devrev/ts-adaas` to `@devrev/airsync-sdk`.
 - [Contributing](docs/CONTRIBUTING.md): workflow, versioning and testing conventions.
+- [Release strategy](docs/RELEASE_STRATEGY.md): branch model, workflow choices and release safeguards.

package/dist/attachments-streaming/attachments-streaming-pool.js

@@ -73,7 +73,7 @@ class AttachmentsStreamingPool {
             Promise.all(initialPromises),
             this.adapter.timeoutSignal,
         ]);
-        if (this.delay) {
+        if (this.delay !== undefined) {
             return { status: 'delay', delaySeconds: this.delay };
         }
         return { status: 'success' };
@@ -81,7 +81,7 @@ class AttachmentsStreamingPool {
     async startPoolStreaming() {
         var _a;
         while (this.attachments.length > 0) {
-            if (this.delay) {
+            if (this.delay !== undefined) {
                 break;
             }
             if (this.adapter.isTimeout) {

package/dist/http/client.d.ts

@@ -1,3 +1,4 @@
-declare const axiosClient: import("axios").AxiosInstance;
+import { AxiosInstance } from 'axios';
+declare const axiosClient: Pick<AxiosInstance, 'get' | 'post'>;
 export { axiosClient };
 //# sourceMappingURL=client.d.ts.map

package/dist/http/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/http/client.ts"],"names":[],"mappings":"AAGA,QAAA,MAAM,WAAW,+BAEf,CAAC;AAmFH,OAAO,EAAE,WAAW,EAAE,CAAC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/http/client.ts"],"names":[],"mappings":"AAAA,OAAc,EAAc,aAAa,EAAE,MAAM,OAAO,CAAC;AAmGzD,QAAA,MAAM,WAAW,EAAE,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,MAAM,CAGpD,CAAC;AAEF,OAAO,EAAE,WAAW,EAAE,CAAC"}

package/dist/http/client.js

@@ -6,64 +6,75 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.axiosClient = void 0;
 const axios_1 = __importDefault(require("axios"));
 const axios_retry_1 = __importDefault(require("axios-retry"));
-const axiosClient = axios_1.default.create({
-    timeout: 30 * 1000,
-});
+function createAxiosClient() {
+    const client = axios_1.default.create({
+        timeout: 30 * 1000,
+    });
+    (0, axios_retry_1.default)(client, {
+        retries: 5,
+        shouldResetTimeout: true,
+        retryDelay: (retryCount, error) => {
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o;
+            let delay;
+            if (((_a = error.response) === null || _a === void 0 ? void 0 : _a.status) === 429) {
+                const retryAfter = ((_c = (_b = error.response) === null || _b === void 0 ? void 0 : _b.headers) === null || _c === void 0 ? void 0 : _c['retry-after']) ||
+                    ((_e = (_d = error.response) === null || _d === void 0 ? void 0 : _d.headers) === null || _e === void 0 ? void 0 : _e['Retry-After']);
+                delay = parseInt(retryAfter, 10) * 1000;
+            }
+            else {
+                delay = axios_retry_1.default.exponentialDelay(retryCount, error, 1000);
+            }
+            const requestId = ((_g = (_f = error.config) === null || _f === void 0 ? void 0 : _f.headers) === null || _g === void 0 ? void 0 : _g['x-request-id']) ||
+                ((_j = (_h = error.config) === null || _h === void 0 ? void 0 : _h.headers) === null || _j === void 0 ? void 0 : _j['X-Request-ID']);
+            const delayInSeconds = Math.round(delay / 1000);
+            console.warn(`Retrying request to ${(_k = error.config) === null || _k === void 0 ? void 0 : _k.url} in ${delayInSeconds}s due to ${(_m = (_l = error.response) === null || _l === void 0 ? void 0 : _l.status) !== null && _m !== void 0 ? _m : 'unknown'} error.`, Object.assign(Object.assign({ method: (_o = error.config) === null || _o === void 0 ? void 0 : _o.method }, (retryCount && { retryCount })), (requestId && { requestId })));
+            return delay;
+        },
+        retryCondition: (error) => {
+            var _a, _b, _c, _d, _e, _f, _g;
+            const retryAfter = ((_b = (_a = error.response) === null || _a === void 0 ? void 0 : _a.headers) === null || _b === void 0 ? void 0 : _b['retry-after']) ||
+                ((_d = (_c = error.response) === null || _c === void 0 ? void 0 : _c.headers) === null || _d === void 0 ? void 0 : _d['Retry-After']);
+            if (((_e = error.response) === null || _e === void 0 ? void 0 : _e.status) && error.response.status >= 500) {
+                return true;
+            }
+            // 429 only when a valid non-negative Retry-After header is present
+            else if (((_f = error.response) === null || _f === void 0 ? void 0 : _f.status) &&
+                error.response.status === 429 &&
+                retryAfter &&
+                !isNaN(Number(retryAfter)) &&
+                Number(retryAfter) >= 0) {
+                return true;
+            }
+            // Network errors for idempotent requests; 429 already handled above
+            else if (axios_retry_1.default.isNetworkOrIdempotentRequestError(error) &&
+                ((_g = error.response) === null || _g === void 0 ? void 0 : _g.status) !== 429) {
+                return true;
+            }
+            // axios-retry excludes ECONNABORTED (client-side timeout only, never a
+            // server response) from isNetworkError, so handle it here separately.
+            else if (error.code === 'ECONNABORTED') {
+                return true;
+            }
+            else {
+                return false;
+            }
+        },
+        onMaxRetryTimesExceeded(error) {
+            var _a, _b, _c, _d, _e, _f;
+            (_b = (_a = error.config) === null || _a === void 0 ? void 0 : _a.headers) === null || _b === void 0 ? true : delete _b.authorization;
+            (_d = (_c = error.config) === null || _c === void 0 ? void 0 : _c.headers) === null || _d === void 0 ? true : delete _d.Authorization;
+            (_e = error.request) === null || _e === void 0 ? true : delete _e._header;
+            console.error(`Request to ${(_f = error.config) === null || _f === void 0 ? void 0 : _f.url} failed after max retries. Error`, error);
+        },
+    });
+    return client;
+}
+let instance;
+const getInstance = () => (instance !== null && instance !== void 0 ? instance : (instance = createAxiosClient()));
+// Created on first use so that loading the SDK never calls axios.create(),
+// which breaks connector tests that mock axios.
+const axiosClient = {
+    get: async (...args) => getInstance().get(...args),
+    post: async (...args) => getInstance().post(...args),
+};
 exports.axiosClient = axiosClient;
-(0, axios_retry_1.default)(axiosClient, {
-    retries: 5,
-    shouldResetTimeout: true,
-    retryDelay: (retryCount, error) => {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o;
-        let delay;
-        if (((_a = error.response) === null || _a === void 0 ? void 0 : _a.status) === 429) {
-            const retryAfter = ((_c = (_b = error.response) === null || _b === void 0 ? void 0 : _b.headers) === null || _c === void 0 ? void 0 : _c['retry-after']) ||
-                ((_e = (_d = error.response) === null || _d === void 0 ? void 0 : _d.headers) === null || _e === void 0 ? void 0 : _e['Retry-After']);
-            delay = parseInt(retryAfter, 10) * 1000;
-        }
-        else {
-            delay = axios_retry_1.default.exponentialDelay(retryCount, error, 1000);
-        }
-        const requestId = ((_g = (_f = error.config) === null || _f === void 0 ? void 0 : _f.headers) === null || _g === void 0 ? void 0 : _g['x-request-id']) ||
-            ((_j = (_h = error.config) === null || _h === void 0 ? void 0 : _h.headers) === null || _j === void 0 ? void 0 : _j['X-Request-ID']);
-        const delayInSeconds = Math.round(delay / 1000);
-        console.warn(`Retrying request to ${(_k = error.config) === null || _k === void 0 ? void 0 : _k.url} in ${delayInSeconds}s due to ${(_m = (_l = error.response) === null || _l === void 0 ? void 0 : _l.status) !== null && _m !== void 0 ? _m : 'unknown'} error.`, Object.assign(Object.assign({ method: (_o = error.config) === null || _o === void 0 ? void 0 : _o.method }, (retryCount && { retryCount })), (requestId && { requestId })));
-        return delay;
-    },
-    retryCondition: (error) => {
-        var _a, _b, _c, _d, _e, _f, _g;
-        const retryAfter = ((_b = (_a = error.response) === null || _a === void 0 ? void 0 : _a.headers) === null || _b === void 0 ? void 0 : _b['retry-after']) ||
-            ((_d = (_c = error.response) === null || _c === void 0 ? void 0 : _c.headers) === null || _d === void 0 ? void 0 : _d['Retry-After']);
-        if (((_e = error.response) === null || _e === void 0 ? void 0 : _e.status) && error.response.status >= 500) {
-            return true;
-        }
-        // 429 only when a valid non-negative Retry-After header is present
-        else if (((_f = error.response) === null || _f === void 0 ? void 0 : _f.status) &&
-            error.response.status === 429 &&
-            retryAfter &&
-            !isNaN(Number(retryAfter)) &&
-            Number(retryAfter) >= 0) {
-            return true;
-        }
-        // Network errors for idempotent requests; 429 already handled above
-        else if (axios_retry_1.default.isNetworkOrIdempotentRequestError(error) &&
-            ((_g = error.response) === null || _g === void 0 ? void 0 : _g.status) !== 429) {
-            return true;
-        }
-        // axios-retry excludes ECONNABORTED (client-side timeout only, never a
-        // server response) from isNetworkError, so handle it here separately.
-        else if (error.code === 'ECONNABORTED') {
-            return true;
-        }
-        else {
-            return false;
-        }
-    },
-    onMaxRetryTimesExceeded(error) {
-        var _a, _b, _c, _d, _e, _f;
-        (_b = (_a = error.config) === null || _a === void 0 ? void 0 : _a.headers) === null || _b === void 0 ? true : delete _b.authorization;
-        (_d = (_c = error.config) === null || _c === void 0 ? void 0 : _c.headers) === null || _d === void 0 ? true : delete _d.Authorization;
-        (_e = error.request) === null || _e === void 0 ? true : delete _e._header;
-        console.error(`Request to ${(_f = error.config) === null || _f === void 0 ? void 0 : _f.url} failed after max retries. Error`, error);
-    },
-});

package/dist/multithreading/adapters/loading-adapter.d.ts

@@ -17,6 +17,7 @@ export declare class LoadingAdapter<ConnectorState> extends BaseAdapter<Connecto
      * an item type the connector can't load, which fails the phase.
      */
     private loadFiles;
+    private initializeFilesToLoad;
     private getLoaderBatches;
     private loadItem;
     /** Maps a non-success connector response to a delay or a failed report. */

package/dist/multithreading/adapters/loading-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loading-adapter.d.ts","sourceRoot":"","sources":["../../../src/multithreading/adapters/loading-adapter.ts"],"names":[],"mappings":"AASA,OAAO,EAEL,wBAAwB,EAGxB,6BAA6B,EAE7B,qBAAqB,EAGrB,YAAY,EAGb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAkB,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEjE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAM7C,yFAAyF;AACzF,qBAAa,cAAc,CACzB,cAAc,CACd,SAAQ,WAAW,CAAC,cAAc,CAAC;IACnC,OAAO,CAAC,aAAa,CAAiB;IACtC,OAAO,CAAC,eAAe,CAAW;IAalC,IAAI,OAAO,IAAI,YAAY,EAAE,CAE5B;IAED,IAAI,cAAc,IAAI,MAAM,EAAE,CAE7B;IA2BK,aAAa,CAAC,EAClB,eAAe,GAChB,EAAE,qBAAqB,GAAG,OAAO,CAAC,UAAU,CAAC;IA8BxC,eAAe,CAAC,EACpB,MAAM,GACP,EAAE;QACD,MAAM,EAAE,6BAA6B,CAAC,wBAAwB,CAAC,CAAC;KACjE,GAAG,OAAO,CAAC,UAAU,CAAC;IAavB;;;;OAIG;YACW,SAAS;YAiFT,gBAAgB;YAuBhB,QAAQ;IA+HtB,2EAA2E;IAC3E,OAAO,CAAC,YAAY;YAwBN,cAAc;CA2C7B"}
+{"version":3,"file":"loading-adapter.d.ts","sourceRoot":"","sources":["../../../src/multithreading/adapters/loading-adapter.ts"],"names":[],"mappings":"AASA,OAAO,EAEL,wBAAwB,EAGxB,6BAA6B,EAE7B,qBAAqB,EAGrB,YAAY,EAGb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAkB,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEjE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAM7C,yFAAyF;AACzF,qBAAa,cAAc,CACzB,cAAc,CACd,SAAQ,WAAW,CAAC,cAAc,CAAC;IACnC,OAAO,CAAC,aAAa,CAAiB;IACtC,OAAO,CAAC,eAAe,CAAW;IAalC,IAAI,OAAO,IAAI,YAAY,EAAE,CAE5B;IAED,IAAI,cAAc,IAAI,MAAM,EAAE,CAE7B;IA2BK,aAAa,CAAC,EAClB,eAAe,GAChB,EAAE,qBAAqB,GAAG,OAAO,CAAC,UAAU,CAAC;IA6BxC,eAAe,CAAC,EACpB,MAAM,GACP,EAAE;QACD,MAAM,EAAE,6BAA6B,CAAC,wBAAwB,CAAC,CAAC;KACjE,GAAG,OAAO,CAAC,UAAU,CAAC;IAYvB;;;;OAIG;YACW,SAAS;YAqFT,qBAAqB;YAarB,gBAAgB;YA+BhB,QAAQ;IA+HtB,2EAA2E;IAC3E,OAAO,CAAC,YAAY;YAwBN,cAAc;CAiD7B"}

package/dist/multithreading/adapters/loading-adapter.js

@@ -46,9 +46,9 @@ class LoadingAdapter extends base_adapter_1.BaseAdapter {
                 console.warn('No item types to load, returning.');
                 return { status: 'success' };
             }
-            this.adapterState.sdkState.fromDevRev = {
-                filesToLoad: await this.getLoaderBatches(itemTypes),
-            };
+            const failure = await this.initializeFilesToLoad(itemTypes);
+            if (failure)
+                return failure;
         }
         return this.loadFiles('data', (fileToLoad) => {
             const itemTypeToLoad = itemTypesToLoad.find((itemTypeToLoad) => itemTypeToLoad.itemType === fileToLoad.itemType);
@@ -60,9 +60,9 @@ class LoadingAdapter extends base_adapter_1.BaseAdapter {
     }
     async loadAttachments({ create, }) {
         if (this.event.payload.event_type === extraction_1.EventType.StartLoadingAttachments) {
-            this.adapterState.sdkState.fromDevRev = {
-                filesToLoad: await this.getLoaderBatches(['attachment']),
-            };
+            const failure = await this.initializeFilesToLoad(['attachment']);
+            if (failure)
+                return failure;
         }
         return this.loadFiles('attachment', () => async (item) => this.loadAttachment({ item, create }));
     }
@@ -105,8 +105,11 @@ class LoadingAdapter extends base_adapter_1.BaseAdapter {
                         console.log(`Timeout detected during ${kind} loading. Returning progress to allow continuation.`);
                         return { status: 'progress' };
                     }
-                    const { report, rateLimit } = await load(transformerFile[i]);
-                    if (rateLimit === null || rateLimit === void 0 ? void 0 : rateLimit.delay) {
+                    const { report, rateLimit, error } = await load(transformerFile[i]);
+                    if (error) {
+                        return { status: 'error', error };
+                    }
+                    if (rateLimit) {
                         return { status: 'delay', delaySeconds: rateLimit.delay };
                     }
                     if (report) {
@@ -132,6 +135,17 @@ class LoadingAdapter extends base_adapter_1.BaseAdapter {
         }
         return { status: 'success' };
     }
+    async initializeFilesToLoad(supportedItemTypes) {
+        try {
+            this.adapterState.sdkState.fromDevRev = {
+                filesToLoad: await this.getLoaderBatches(supportedItemTypes),
+            };
+            return undefined;
+        }
+        catch (error) {
+            return { status: 'error', error: { message: (0, logger_1.serializeError)(error) } };
+        }
+    }
     async getLoaderBatches(supportedItemTypes) {
         var _a;
         const statsFileArtifactId = (_a = this.event.payload.event_data) === null || _a === void 0 ? void 0 : _a.stats_file;
@@ -142,7 +156,10 @@ class LoadingAdapter extends base_adapter_1.BaseAdapter {
             artifactId: statsFileArtifactId,
         });
         const statsFile = response;
-        if (statsFileError || statsFile.length === 0) {
+        if (statsFileError) {
+            throw new Error(`Failed to download loader stats file ${statsFileArtifactId}. ${(0, logger_1.serializeError)(statsFileError)}`);
+        }
+        if (statsFile.length === 0) {
             return [];
         }
         return (0, loading_adapter_helpers_1.getFilesToLoad)({ supportedItemTypes, statsFile });
@@ -267,6 +284,11 @@ class LoadingAdapter extends base_adapter_1.BaseAdapter {
         }
         catch (error) {
             console.warn('Failed to create sync mapper record.', (0, logger_1.serializeError)(error));
+            return {
+                error: {
+                    message: 'Failed to create sync mapper record. ' + (0, logger_1.serializeError)(error),
+                },
+            };
         }
         return {
             report: {

package/dist/state/base-state.d.ts

@@ -39,8 +39,8 @@ export declare abstract class BaseState<ConnectorState> {
     init(initialState: ConnectorState): Promise<void>;
     /**
      * Normalizes fetched state into the `{ connectorState, sdkState }` envelope.
-     * Versioned envelopes are read by `stateVersion`; unversioned ones (2.0.0
-     * betas) by their keys; anything else is a flat v1 blob split by
+     * Envelopes are recognized by their keys and validate `stateVersion` when
+     * present; anything else is a flat v1 blob split by
      * `V1_SDK_STATE_KEYS`.
      */
     private normalizeFetchedState;

package/dist/state/base-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base-state.d.ts","sourceRoot":"","sources":["../../src/state/base-state.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGnD,OAAO,EAEL,QAAQ,EAER,cAAc,EAEf,MAAM,oBAAoB,CAAC;AAE5B;;;;GAIG;AACH,8BAAsB,SAAS,CAAC,cAAc;IAC5C,SAAS,CAAC,eAAe,EAAE,cAAc,CAAC;IAC1C,SAAS,CAAC,SAAS,EAAE,QAAQ,CAAC;IAC9B,SAAS,CAAC,gBAAgB,EAAE,eAAe,CAAM;IACjD,SAAS,CAAC,QAAQ,CAAC,eAAe,EAAE,QAAQ,CAAC;IAC7C,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IACvC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,SAAS,CAAS;gBAGxB,EAAE,KAAK,EAAE,YAAY,EAAE,EAAE,cAAc,CAAC,cAAc,CAAC,EACvD,eAAe,EAAE,QAAQ;IAY3B,2EAA2E;IAC3E,IAAI,KAAK,IAAI,cAAc,CAE1B;IAED,IAAI,KAAK,CAAC,KAAK,EAAE,cAAc,EAE9B;IAED,uEAAuE;IACvE,IAAI,QAAQ,IAAI,QAAQ,CAEvB;IAED,IAAI,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAE3B;IAED,IAAI,eAAe,IAAI,eAAe,CAErC;IAED;;;;OAIG;IACG,mCAAmC,CACvC,oBAAoB,CAAC,EAAE,oBAAoB,GAC1C,OAAO,CAAC,IAAI,CAAC;IAwChB;;;;OAIG;IACG,IAAI,CAAC,YAAY,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAuDvD;;;;;OAKG;IACH,OAAO,CAAC,qBAAqB;IA2C7B,OAAO,CAAC,YAAY;IAepB;;;OAGG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IA0C1B,UAAU,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAqBjE"}
+{"version":3,"file":"base-state.d.ts","sourceRoot":"","sources":["../../src/state/base-state.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGnD,OAAO,EAEL,QAAQ,EAER,cAAc,EAEf,MAAM,oBAAoB,CAAC;AAE5B;;;;GAIG;AACH,8BAAsB,SAAS,CAAC,cAAc;IAC5C,SAAS,CAAC,eAAe,EAAE,cAAc,CAAC;IAC1C,SAAS,CAAC,SAAS,EAAE,QAAQ,CAAC;IAC9B,SAAS,CAAC,gBAAgB,EAAE,eAAe,CAAM;IACjD,SAAS,CAAC,QAAQ,CAAC,eAAe,EAAE,QAAQ,CAAC;IAC7C,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IACvC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,SAAS,CAAS;gBAGxB,EAAE,KAAK,EAAE,YAAY,EAAE,EAAE,cAAc,CAAC,cAAc,CAAC,EACvD,eAAe,EAAE,QAAQ;IAY3B,2EAA2E;IAC3E,IAAI,KAAK,IAAI,cAAc,CAE1B;IAED,IAAI,KAAK,CAAC,KAAK,EAAE,cAAc,EAE9B;IAED,uEAAuE;IACvE,IAAI,QAAQ,IAAI,QAAQ,CAEvB;IAED,IAAI,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAE3B;IAED,IAAI,eAAe,IAAI,eAAe,CAErC;IAED;;;;OAIG;IACG,mCAAmC,CACvC,oBAAoB,CAAC,EAAE,oBAAoB,GAC1C,OAAO,CAAC,IAAI,CAAC;IAwChB;;;;OAIG;IACG,IAAI,CAAC,YAAY,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAuDvD;;;;;OAKG;IACH,OAAO,CAAC,qBAAqB;IAyC7B,OAAO,CAAC,YAAY;IAepB;;;OAGG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IA0C1B,UAAU,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAqBjE"}

package/dist/state/base-state.js

@@ -137,8 +137,8 @@ class BaseState {
     }
     /**
      * Normalizes fetched state into the `{ connectorState, sdkState }` envelope.
-     * Versioned envelopes are read by `stateVersion`; unversioned ones (2.0.0
-     * betas) by their keys; anything else is a flat v1 blob split by
+     * Envelopes are recognized by their keys and validate `stateVersion` when
+     * present; anything else is a flat v1 blob split by
      * `V1_SDK_STATE_KEYS`.
      */
     normalizeFetchedState(parsed) {
@@ -146,16 +146,13 @@ class BaseState {
             throw new Error('Fetched state is not a JSON object.');
         }
         const record = parsed;
-        if (record.stateVersion !== undefined) {
-            if (record.stateVersion !== state_interfaces_1.STATE_VERSION) {
+        if ('connectorState' in record || 'sdkState' in record) {
+            if (record.stateVersion !== undefined &&
+                record.stateVersion !== state_interfaces_1.STATE_VERSION) {
                 throw new Error(`Unsupported state version ${String(record.stateVersion)}; this SDK reads version ${state_interfaces_1.STATE_VERSION}.`);
             }
             return this.readEnvelope(record);
         }
-        // Envelopes written by 2.0.0 betas carry no version marker.
-        if ('connectorState' in record || 'sdkState' in record) {
-            return this.readEnvelope(record);
-        }
         // Legacy flat v1 blob: split known SDK keys out of the connector state.
         const connectorState = {};
         const sdkState = {};

package/dist/state/extraction-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extraction-state.d.ts","sourceRoot":"","sources":["../../src/state/extraction-state.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAsB,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAGxE,sGAAsG;AACtG,qBAAa,eAAe,CAAC,cAAc,CAAE,SAAQ,SAAS,CAAC,cAAc,CAAC;gBAChE,MAAM,EAAE,cAAc,CAAC,cAAc,CAAC;IAIlD;;;;OAIG;IACH,uBAAuB,IAAI,IAAI;CAyHhC;AAED,wBAAsB,qBAAqB,CAAC,cAAc,EAAE,EAC1D,KAAK,EACL,YAAY,EACZ,oBAAoB,EACpB,OAAO,GACR,EAAE,cAAc,CAAC,cAAc,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC,cAAc,CAAC,CAAC,CAkB3E"}
+{"version":3,"file":"extraction-state.d.ts","sourceRoot":"","sources":["../../src/state/extraction-state.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAsB,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAGxE,sGAAsG;AACtG,qBAAa,eAAe,CAAC,cAAc,CAAE,SAAQ,SAAS,CAAC,cAAc,CAAC;gBAChE,MAAM,EAAE,cAAc,CAAC,cAAc,CAAC;IAIlD;;;;OAIG;IACH,uBAAuB,IAAI,IAAI;CA4HhC;AAED,wBAAsB,qBAAqB,CAAC,cAAc,EAAE,EAC1D,KAAK,EACL,YAAY,EACZ,oBAAoB,EACpB,OAAO,GACR,EAAE,cAAc,CAAC,cAAc,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC,cAAc,CAAC,CAAC,CAkB3E"}

package/dist/state/extraction-state.js

@@ -21,6 +21,7 @@ class ExtractionState extends base_state_1.BaseState {
      * all other events reuse those cached boundaries. Validates extract_from < extract_to.
      */
     resolveExtractionWindow() {
+        var _a, _b;
         const sdkState = this.sdkState;
         const eventContext = this.event.payload.event_context;
         const overrideExtractFrom = (value) => {
@@ -29,10 +30,15 @@ class ExtractionState extends base_state_1.BaseState {
             }
             eventContext.extract_from = value;
         };
-        if (this.event.payload.event_type === extraction_1.EventType.StartExtractingData &&
-            !sdkState.lastSyncStarted) {
-            sdkState.lastSyncStarted = new Date().toISOString();
-            console.log(`Setting lastSyncStarted to ${sdkState.lastSyncStarted}.`);
+        if (this.event.payload.event_type === extraction_1.EventType.StartExtractingData) {
+            if (!sdkState.lastSyncStarted) {
+                sdkState.lastSyncStarted = new Date().toISOString();
+                console.log(`Setting lastSyncStarted to ${sdkState.lastSyncStarted}.`);
+            }
+            // A sync that failed before attachments must not leak its SSOR records into this one.
+            if ((_b = (_a = sdkState.toDevRev) === null || _a === void 0 ? void 0 : _a.deferredSsorArtifacts) === null || _b === void 0 ? void 0 : _b.length) {
+                sdkState.toDevRev.deferredSsorArtifacts = [];
+            }
         }
         if (this.event.payload.event_type === extraction_1.EventType.StartExtractingMetadata) {
             const timeFields = [

package/dist/types/errors.d.ts

@@ -1,7 +1,7 @@
 /**
- * Error codes the platform reacts to (e.g. stopping periodic syncs). Set them
- * on `ErrorRecord.code`; the platform matches the code exactly, so the SDK
- * sends it as the whole wire message.
+ * Platform-recognized error codes (CommonError), mapped by the snap-in manager
+ * in `internal/common/errors_snapin.go`. Set them on `ErrorRecord.code`; the SDK
+ * sends exactly `ERROR_CODE=<code>` as the wire message.
  */
 export declare enum AirSyncErrorCode {
     EXTERNAL_SYNC_UNIT_DELETED = "EXTERNAL_SYNC_UNIT_DELETED",

package/dist/types/errors.js

@@ -5,9 +5,9 @@ exports.formatErrorCode = formatErrorCode;
 const ERROR_PREFIX = 'ERROR_CODE';
 const ERROR_DELIMITER = '=';
 /**
- * Error codes the platform reacts to (e.g. stopping periodic syncs). Set them
- * on `ErrorRecord.code`; the platform matches the code exactly, so the SDK
- * sends it as the whole wire message.
+ * Platform-recognized error codes (CommonError), mapped by the snap-in manager
+ * in `internal/common/errors_snapin.go`. Set them on `ErrorRecord.code`; the SDK
+ * sends exactly `ERROR_CODE=<code>` as the wire message.
  */
 var AirSyncErrorCode;
 (function (AirSyncErrorCode) {

package/dist/types/extraction.d.ts

@@ -109,10 +109,6 @@ export interface EventContext {
     mode: string;
     request_id: string;
     request_id_adaas: string;
-    /** @deprecated Never read by the SDK; kept because connectors still branch on it. */
-    reset_extraction?: boolean;
-    /** @deprecated Use extraction_start_time/extraction_end_time (resolved into extract_from/extract_to). */
-    reset_extract_from?: boolean;
     run_id: string;
     sequence_version: string;
     snap_in_slug: string;

package/dist/types/extraction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extraction.d.ts","sourceRoot":"","sources":["../../src/types/extraction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,+CAA+C,CAAC;AAClF,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAE3D,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAEhD,iDAAiD;AACjD,oBAAY,SAAS;IAEnB,gCAAgC,yCAAyC;IACzE,uBAAuB,8BAA8B;IACrD,0BAA0B,iCAAiC;IAC3D,mBAAmB,0BAA0B;IAC7C,sBAAsB,6BAA6B;IACnD,2BAA2B,mCAAmC;IAC9D,0BAA0B,iCAAiC;IAC3D,6BAA6B,oCAAoC;IACjE,sCAAsC,+CAA+C;IAGrF,gBAAgB,uBAAuB;IACvC,mBAAmB,0BAA0B;IAC7C,uBAAuB,8BAA8B;IACrD,0BAA0B,iCAAiC;IAC3D,wBAAwB,gCAAgC;IACxD,kCAAkC,2CAA2C;CAC9E;AAED,iDAAiD;AACjD,oBAAY,kBAAkB;IAE5B,8BAA8B,uCAAuC;IACrE,+BAA+B,wCAAwC;IACvE,0BAA0B,iCAAiC;IAC3D,yBAAyB,gCAAgC;IACzD,sBAAsB,6BAA6B;IACnD,uBAAuB,8BAA8B;IACrD,sBAAsB,6BAA6B;IACnD,qBAAqB,4BAA4B;IACjD,kBAAkB,yBAAyB;IAC3C,mBAAmB,0BAA0B;IAC7C,0BAA0B,kCAAkC;IAC5D,2BAA2B,mCAAmC;IAC9D,4BAA4B,mCAAmC;IAC/D,2BAA2B,kCAAkC;IAC7D,wBAAwB,+BAA+B;IACvD,yBAAyB,gCAAgC;IACzD,qCAAqC,8CAA8C;IACnF,sCAAsC,+CAA+C;CACtF;AAED,uEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,oBAAY,gBAAgB;IAC1B,YAAY,iBAAiB;IAC7B,WAAW,gBAAgB;CAC5B;AAED,8EAA8E;AAC9E,oBAAY,QAAQ;IAClB,WAAW,OAAO;IAClB,YAAY,OAAO;IACnB,eAAe,YAAO;IACtB,YAAY,OAAO;IACnB,OAAO,MAAM;IACb,OAAO,MAAM;IACb,KAAK,MAAM;CACZ;AAED;;;GAGG;AACH,oBAAY,aAAa;IACvB,cAAc,mBAAmB;IACjC,2BAA2B,gCAAgC;IAC3D,cAAc,mBAAmB;IACjC,0BAA0B,+BAA+B;IACzD,YAAY,iBAAiB;IAC7B,aAAa,kBAAkB;IAC/B,SAAS,cAAc;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,aAAa,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,MAAM,CAAC;IACzB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,uBAAuB,EAAE,MAAM,CAAC;IAChC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,oBAAoB,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,CAAC,EAAE,gBAAgB,CAAC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,qFAAqF;IACrF,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,yGAAyG;IACzG,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,KAAK,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,uEAAuE;IACvE,qBAAqB,CAAC,EAAE,SAAS,CAAC;IAClC,mEAAmE;IACnE,mBAAmB,CAAC,EAAE,SAAS,CAAC;IAChC,mGAAmG;IACnG,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,kFAAkF;AAClF,oBAAY,aAAa;IACvB,IAAI,SAAS;IACb,KAAK,UAAU;CAChB;AAED,mGAAmG;AACnG,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,EAAE,aAAa,CAAC;CACjC;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;IAEvB,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,0BAA0B,CAAC,EAAE,aAAa,EAAE,CAAC;CAC9C;AAED,MAAM,WAAW,cAAc;IAC7B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAG/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAG9B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,gDAAgD;AAChD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE;QACP,OAAO,EAAE;YACP,qBAAqB,EAAE,MAAM,CAAC;SAC/B,CAAC;QACF,kBAAkB,EAAE,MAAM,CAAC;QAC3B,UAAU,EAAE,MAAM,CAAC;QACnB,0DAA0D;QAC1D,OAAO,EAAE,MAAM,CAAC;QAChB,iDAAiD;QACjD,OAAO,EAAE,MAAM,CAAC;QAChB,gEAAgE;QAChE,SAAS,EAAE,MAAM,CAAC;QAClB,yDAAyD;QACzD,kBAAkB,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,OAAO,EAAE,cAAc,CAAC;IACxB,kBAAkB,EAAE;QAClB,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,UAAU,EAAE,SAAS,CAAC;CACvB;AAED,8CAA8C;AAC9C,MAAM,WAAW,SAAS;IACxB,iDAAiD;IACjD,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,2EAA2E;IAE3E,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,cAAc;IAC7B,eAAe,EAAE,cAAc,CAAC;IAChC,aAAa,EAAE,YAAY,CAAC;IAC5B,UAAU,EAAE,SAAS,CAAC;IACtB,UAAU,CAAC,EAAE,SAAS,CAAC;CACxB;AAED,gDAAgD;AAChD,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,YAAY,CAAC;IAC5B,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB,eAAe,CAAC,EAAE,cAAc,CAAC;CAClC;AAED,MAAM,MAAM,yCAAyC,GAAG,CAAC,EACvD,IAAI,EACJ,KAAK,GACN,EAAE,uCAAuC,KAAK,OAAO,CAAC,yCAAyC,CAAC,CAAC;AAElG,MAAM,WAAW,uCAAuC;IACtD,IAAI,EAAE,oBAAoB,CAAC;IAC3B,KAAK,EAAE,YAAY,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IAEjC,IAAI,EAAE,GAAG,CAAC;IAEV,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC9B;AAED,gEAAgE;AAChE,MAAM,MAAM,yCAAyC,GACjD;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,UAAU,EAAE,kBAAkB,CAAA;CAAE,GACrD;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,CAAC;AAE5C;;;;GAIG;AACH,MAAM,MAAM,2BAA2B,GACnC;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GACrB;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,WAAW,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAEpE,MAAM,MAAM,uCAAuC,CACjD,KAAK,EACL,QAAQ,EACR,cAAc,IACZ,CAAC,EACH,WAAW,EACX,OAAO,EACP,SAAS,GACV,EAAE;IACD,WAAW,EAAE,KAAK,CAAC;IACnB,OAAO,EAAE,iBAAiB,CAAC,cAAc,CAAC,CAAC;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,KAAK,QAAQ,CAAC;AAEf,MAAM,MAAM,iCAAiC,GAAG,CAAC,EAC/C,UAAU,EACV,MAAM,GACP,EAAE;IACD,UAAU,EAAE,oBAAoB,CAAC;IACjC,MAAM,EAAE,yCAAyC,CAAC;CACnD,KAAK,OAAO,CAAC,2BAA2B,CAAC,CAAC;AAE3C,MAAM,MAAM,wCAAwC,CAAC,QAAQ,EAAE,cAAc,IAC3E,CAAC,EACC,kBAAkB,EAClB,OAAO,EACP,MAAM,GACP,EAAE;IACD,kBAAkB,EAAE,QAAQ,CAAC;IAC7B,OAAO,EAAE,iBAAiB,CAAC,cAAc,CAAC,CAAC;IAC3C,MAAM,EAAE,yCAAyC,CAAC;CACnD,KAAK,OAAO,CAAC,2BAA2B,CAAC,CAAC;AAE7C,MAAM,WAAW,kCAAkC,CACjD,cAAc,EACd,KAAK,EACL,QAAQ;IAER,OAAO,EAAE,uCAAuC,CAC9C,KAAK,EACL,QAAQ,EACR,cAAc,CACf,CAAC;IACF,QAAQ,EAAE,wCAAwC,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;CAC9E"}
+{"version":3,"file":"extraction.d.ts","sourceRoot":"","sources":["../../src/types/extraction.ts"],"names":[],"mappings":"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"}

package/docs/MIGRATION.md

@@ -9,11 +9,14 @@ own:
 It ships in the package at `node_modules/@devrev/airsync-sdk/docs/MIGRATION.md`
 (read it from disk; the `exports` map only blocks `import`/`require`). Before
 v2 is installed, use
-`https://raw.githubusercontent.com/devrev/adaas-sdk/v2/docs/MIGRATION.md`.
+`https://raw.githubusercontent.com/devrev/adaas-sdk/v2/docs/MIGRATION.md`
+(use `main` after GA). The installed guide always takes precedence.
 
-**The wire protocol is unchanged.** Event payloads, routes, headers, the
-artifact flow and every event-type and `ERROR_CODE=…` string are identical to
-v1. Only the TypeScript API changed, all at once, with no compatibility shims.
+**The modern wire protocol is unchanged.** Event names, routes, headers,
+artifact formats and `ERROR_CODE=…` strings remain compatible with platforms
+that send modern events. Legacy `EXTRACTION_*` event names are intentionally
+unsupported. The public TypeScript API changes all at once, without deprecated
+aliases; runtime differences are described below.
 
 ---
 
@@ -21,7 +24,8 @@ v1. Only the TypeScript API changed, all at once, with no compatibility shims.
 
 **Rules.** Work autonomously; when a rewrite is ambiguous, pick the option
 that preserves runtime behavior and note it in `MIGRATION_REVIEW.md`. Migrate
-source **and** tests. Never change a runtime string value. Don't add comments
+source **and** tests. Preserve runtime string values except the documented
+legacy event-string replacements in §3 and §11. Don't add comments
 about the migration; the `// v1` / `// v2` labels here are reading aids. Leave
 no compile errors or orphaned imports. A section with no hits is a no-op.
 Existing comments and commented-out code that describe v1 behavior (`emit`,
@@ -30,12 +34,17 @@ v2; templates are copied into new connectors, so stale comments spread.
 
 1. **Locate the package.** Find the `package.json` that depends on
    `@devrev/ts-adaas` (generated connectors keep it in `code/`). Run everything
-   from there. If it already depends on `@devrev/airsync-sdk` only, report
-   "already on v2" and stop.
+   from there. If it already depends on `@devrev/airsync-sdk`, inspect its
+   installed version and migration review. Early betas still need the
+   changes under **Rare cases** below; upgrade to the selected v2 version
+   and verify source, tests and local runners against this guide. Stop only
+   when the current-contract migration and verification are complete.
 2. **Start from green latest v1.** If behind the latest stable 1.x, upgrade and
    apply the release notes of every release in between that mentions a
    migration (the last ones were 1.16.0–1.18.0), then get tsc/lint/build/test
-   green on v1. Record failures that remain as **Pre-existing**.
+   green on v1. If the upgrade alone breaks tsc with axios type mismatches,
+   bump the connector's `axios` to the version that SDK release depends on.
+   Record failures that remain as **Pre-existing**.
 3. **Install v2.**
    ```bash
    npm uninstall @devrev/ts-adaas
@@ -51,15 +60,19 @@ v2; templates are copied into new connectors, so stale comments spread.
 5. **Verify**: `npm install && npx tsc --noEmit && npm run lint && npm run build && npm test`.
    If tsconfig excludes folders the connector still runs (`test/`, a local
    runner), type-check them too: use the repo's `tsconfig.test.json` if it has
-   one, otherwise a temporary tsconfig that extends `tsconfig.json` with
-   `"include": ["src", "test"]` and `npx tsc --noEmit -p` it. Fix and rerun,
+   one, otherwise a temporary tsconfig that extends `tsconfig.json` and
+   overrides `"include": ["src", "test"]`, `"exclude": ["node_modules", "dist"]`,
+   `"rootDir": "."` and `"noEmit": true` (the base `exclude` and `rootDir` still
+   apply otherwise), then `npx tsc -p` it. Fix and rerun,
    at most 4 attempts; the migration must add no new failures compared to
    step 2.
 6. **Sweep.** This must return nothing except legitimate hits (an
    `EventEmitter.emit`, the connector's own `axiosClient` from §9,
-   `@devrev/typescript-sdk` in `package.json` from §1, `git config --local`):
+   `@devrev/typescript-sdk` in `package.json` from §1, `git config --local`,
+   legacy event names in fields the SDK doesn't read, such as
+   `event_type_adaas`):
    ```bash
-   grep -rnE "@devrev/ts-adaas|airsync-sdk/dist|\bprocessTask\b|WorkerAdapter|\.emit\(|hasWorkerEmitted|Airdrop(Event|Message)|axiosClient|(format|serialize)AxiosError|workerPath:|overridenOptions|skipConfirmation|isLocalDevelopment|--local|-- local\b|@devrev/typescript-sdk|(Extractor|Loader)EventType|ExtractionCommonError|ERROR_CODE=|sdkState|onUpload|uploadedArtifacts|currentEventDataLength|EXTRACTION_(DATA|METADATA|ATTACHMENTS|EXTERNAL_SYNC_UNITS)_" \
+   grep -rnE "@devrev/ts-adaas|airsync-sdk/dist|\bprocessTask\b|\bWorkerAdapter\b|\.emit\(|hasWorkerEmitted|\bAirdrop(Event|Message)\b|axiosClient|(format|serialize)AxiosError|workerPath:|overridenOptions|skipConfirmation|isLocalDevelopment|--local|-- local\b|@devrev/typescript-sdk|(Extractor|Loader)EventType|ExtractionCommonError|ERROR_CODE=|reset_(extraction|extract_from)|sdkState|onUpload|uploadedArtifacts|currentEventDataLength|EXTRACTION_(DATA|METADATA|ATTACHMENTS|EXTERNAL_SYNC_UNITS)_" \
      --include='*.ts' --include='*.js' --include='*.json' --include='*.yml' --include='*.yaml' --include='*.md' --include='*.mdc' --include='*.sh' . \
      | grep -vE 'node_modules|/dist/|/coverage/|package-lock.json|MIGRATION_REVIEW.md'
    ```
@@ -80,7 +93,7 @@ v2; templates are copied into new connectors, so stale comments spread.
    helpers (§4), paths that emitted nothing (§4), `onTimeout` bodies kept (§4),
    delay values that look like milliseconds or headers (§4), the cursor decision
    (§8), ESU repo rewrites (§7), mapper error handling (§10), and a v1 baseline
-   upgrade.
+   upgrade. Record the exact installed versions.
    ```markdown
    # v2 Migration Review
    Migrated `@devrev/ts-adaas` 1.20.2 → `@devrev/airsync-sdk` 2.0.0.
@@ -134,7 +147,10 @@ The shapes are unchanged. `AirSyncEvent.context` now also declares `user_id`,
 `payload.event_context`). Delete a hand-rolled context type that added these
 (e.g. `interface CustomAirdropEvent extends AirdropEvent { context: CustomContext }`):
 a narrower `context` no longer satisfies `AirSyncEvent`. Keep only the fields
-the SDK type lacks.
+the SDK type lacks. These fields are required, so typed mock events must set
+them. `execution_metadata` is typed `{ devrev_endpoint }`; a custom type that
+widened it with `@devrev/typescript-sdk` fields goes too, along with mock values
+for fields nothing reads.
 
 Deprecated `EventContext` aliases are removed. Use the current names:
 
@@ -147,12 +163,18 @@ Deprecated `EventContext` aliases are removed. Use the current names:
 | `sync_run`, `sync_run_id` | `run_id` |
 | `uuid` | `request_id_adaas` |
 
-Rename these keys in fixture and test `event_context` objects too. Untyped
+Rename these keys in fixture and test `event_context` objects too. When an
+object already has the new key (or has two old keys for one new one, like
+`dev_user` and `dev_user_id`), keep the existing new-name value, otherwise the
+first old one, and drop the rest. Untyped
 JSON still compiles, but the SDK reads only the current names (e.g. state
 requests carry `request_id_adaas`).
 
-`reset_extraction` and `reset_extract_from` remain (the SDK never read them);
-leave connector logic that uses them alone.
+`reset_extraction` and `reset_extract_from` are removed. Delete these keys
+from fixtures and remove connector branches that read them. The SDK never
+interpreted either flag. Configure backfills through the platform's
+`extraction_start_time` / `extraction_end_time`; connectors read the
+SDK-resolved `extract_from` / `extract_to` for the sync window (§8).
 
 ## 3. `spawn`
 
@@ -246,14 +268,14 @@ processExtractionTask({
 |----|----|
 | `emit(XxxDone)` | `return { status: 'success' }` |
 | `emit(XxxProgress, { progress })` | `return { status: 'progress' }` |
-| `emit(XxxDelayed, { delay })` | `return { status: 'delay', delaySeconds: delay }` — keep the same number; the platform always read it as seconds. If it is clearly milliseconds or a raw `Retry-After` header, keep the behavior (`Number(header)`) and flag it in the review |
+| `emit(XxxDelayed, { delay })` | `return { status: 'delay', delaySeconds: delay }` — keep the same number; the platform always read it as seconds. A raw `Retry-After` header stays `Number(header)`. If it is clearly milliseconds (a `*_MS` constant, a value in the thousands, "ms" in the message), keep the number, flag it and list it under **Unresolved**: v1 waited that many seconds too, and fixing it changes behavior |
 | `emit(XxxDelayed)` with no `delay` | `delaySeconds` is required; use the connector's existing default retry constant, else `0` (what v1 effectively sent), and flag it |
 | `emit(XxxError, { error })` | `return { status: 'error', error }` — `error` is required; fall back to `{ message: '<phase> failed' }` |
 | `emit(XxxDone, { error })` (finished with warnings) | `return { status: 'success' }` and log the error. Returning `error` would fail the phase |
 | `emit(ExternalSyncUnitExtractionDone, { external_sync_units })` | push to a repo, then `success` (§7) |
 | `emit(MetadataExtractionDone, { pre_extraction_item_counts })` | `adapter.preExtractionItemCounts = counts`, then `success` |
 | a path that **emitted nothing** (a `catch` that only logs, a branch that falls through) | `{ status: 'error', error: { message } }`, or rethrow. In v1 the SDK reported these as a phase error ("Worker exited without emitting"); never turn them into `success` or `progress` |
-| any `emit(XxxDone)` after `loadItemTypes` / `loadAttachments` / `streamAttachments`, guarded (`!adapter.hasWorkerEmitted && !adapter.isTimeout`) or not | `return adapter.loadItemTypes(...)` (or the other call). Never discard their result and return `success`: v1 emitted their `delay` / `error` itself. Drop the guard and any module-level "already emitted" flags |
+| any `emit(XxxDone)` after `loadItemTypes` / `loadAttachments` / `streamAttachments`, guarded (`!adapter.hasWorkerEmitted && !adapter.isTimeout`) or not | `return adapter.loadItemTypes(...)` (or the other call). Never discard their result and return `success`: v1 emitted their `delay` / `error` itself. Drop the guard and any module-level "already emitted" flags. If v1 did more work after the call and then emitted `Done` with an `error`, return the call's result and log that error |
 
 In non-resumable phases (external sync units, state deletion), `progress` and
 `delay` become `*Error`.
@@ -282,7 +304,16 @@ If a helper **emitted and then kept going** (no throw), the caller often
 emitted again later, e.g. `DataExtractionDone` after the loop, and v1 dropped
 every emit after the first. Record the first result the same way, stop the
 work that followed it (return out of the loop or extractor), and return it
-from the task. Unawaited emits inside loops count too.
+from the task. Unawaited emits inside loops count too. When the emitting helper
+is deep in the call stack, throw an error class that carries the `TaskResult`
+instead (`class TaskResultError extends Error { constructor(readonly result: TaskResult) { super(); } }`),
+stop the extractor, and return `e.result` from the task's outermost `catch`.
+A free-function handler that must keep only the first result stores it per
+adapter (`WeakMap<adapter, TaskResult>`) and the task reads it back.
+
+A helper that returned `{ delay?, error? }` and emitted only when one was set
+needs an explicit result when neither is set: `success` if the caller carried
+on, otherwise `error`.
 
 If a helper (often the HTTP client's 429 handler) **emitted and then threw a
 sentinel error** that call sites rethrow, keep the throw, drop the emit, and map
@@ -321,6 +352,11 @@ helpers, assert on the return value.
     custom error. Make its body safe to run after a completed task. A custom
     "Lambda timeout" `onTimeout` on a task that emits on every path is
     deleted; v1 never ran it.
+  - `onTimeout` runs only after the task has returned, in v1 and v2, so
+    cleanup there (cancelling a rate limiter, aborting requests) never
+    interrupted a stuck task. Check the public `adapter.isTimeout` between
+    batches and perform any needed cancellation inside the task.
+    `timeoutSignal` is internal and unavailable to connector code.
 - Don't call `process.exit()` or `postState()` in `onTimeout`; the SDK saves
   state and exits.
 
@@ -331,10 +367,16 @@ now wrong**, and `Boolean(await repo.push(x))` or `if (!(await …push(x)))`
 compiles but is always falsy. Make wrappers `await repo.push(x)` and return
 `true` (or `void`). Keep a top-level `try/catch` that maps an error to `delay`
 (e.g. a thrown 429); otherwise it's only needed for a custom message.
+Find every unawaited `repo.push()` / `repo.upload()`, including calls in
+helpers and loops, and await it before advancing the cursor or returning.
+An unhandled upload rejection can bypass the task's error handling.
 `loadItemTypes` and `loadAttachments` don't throw: a `create` / `update` that
 throws becomes their `error` result, so a 429 must be returned as
 `{ status: 'delay', delaySeconds }` from the callback (§6). A `catch` around
 them that checks `isAxiosError(e) && status === 429` is dead; delete it.
+Failures fetching loader stats or reading/writing sync mapper records fail
+the phase and retain the current cursor. A connector callback returning
+`status: 'error'` still counts that item as failed and continues.
 
 `ProcessTaskInterface<T>` and `TaskAdapterInterface<T>` now take the
 **adapter** type: `ProcessTaskInterface<ExtractionAdapter<State>>`, not
@@ -355,7 +397,9 @@ async function extractList(adapter: ExtractionAdapter<State>) { ... }
 | `event`, `state`, `mappers`, `postState`, `uploadArtifact`, `downloadArtifact`, `isTimeout`, `extractionScope` | both |
 
 - The adapters and `Repo` are **type-only**: `new ExtractionAdapter(...)` and
-  `class X extends LoadingAdapter<S>` don't compile; `interface X extends …`
+  `class X extends LoadingAdapter<S>` or `extends Repo` (test doubles that
+  subclassed `Repo` through `dist/`) don't compile; use a plain object with
+  the methods the code calls. `interface X extends …`
   does. SDK internals (`emit`, `sdkState`, `options`, constructors, …) aren't
   public. `isTimeout` and `artifacts` are read-only.
 - `adapter.mappers` works in extraction as in v1; keep those calls and only
@@ -423,7 +467,9 @@ return { status: 'success' }; // was a bare `return;`
   as `skip` are dropped; every `success` creates or updates a mapper record.
 - Shared helpers typed as these responses change too. Callers that read
   `result.delay` or interpolate `${result.error}` (now an object) switch on
-  `result.status`.
+  `result.status`. A helper that only builds delays and errors returns the
+  narrowed type (`Extract<…, { status: 'delay' | 'error' }>`), so callers and
+  tests can read `delaySeconds` and `error` without a check.
 - An error `code` returned from the stream callback is only logged; the pool
   skips that attachment.
 - `httpStream` is typed `HttpStreamResponse` (`{ data, headers }`); an axios
@@ -439,6 +485,14 @@ its state fields and tests. Workarounds typically override the
 `ssor_attachment` repo's `onUpload`, splice `uploadedArtifacts`, adjust
 `currentEventDataLength`, or stash artifact refs in state.
 
+- A worker whose only job was re-injecting those refs returns
+  `{ status: 'success' }` (or its remaining work); keep its phase wired.
+- A connector's own `{ itemType: 'ssor_attachment' }` repo entry can stay.
+- Tests that mocked the deep `Uploader` use adapter doubles instead:
+  `{ uploadArtifact: jest.fn(), downloadArtifact: jest.fn() }`.
+- If the workaround stashed refs in connector state, syncs between data done and
+  attachments done lose them after the upgrade; drain them first.
+
 ## 7. External sync units go through a repo
 
 `EventData.external_sync_units` is removed. Push them to a repo:
@@ -466,9 +520,14 @@ the emit.
 - **Persisted state** becomes `{ stateVersion: 2, connectorState, sdkState }`.
   A v1 blob is migrated automatically on first read: known SDK keys move to
   `sdkState` and everything else becomes connector state. **Rolling back to v1
-  after a v2 worker has run is not supported**; drain or reset syncs first. A
+  after a v2 worker has persisted state is not supported**. A drained sync
+  still has a v2 envelope: recovery needs a verified saved v1 state together
+  with the v1 connector, or an explicit reset/reinitialization and reimport.
+  Upgrade between runs, after v1 workers have finished. A
   v1 state with a top-level key named `connectorState` or `sdkState` is
-  misread; rename it before upgrading.
+  misread. Rename it in a staged v1 deployment and migrate its persisted
+  value before upgrading, or explicitly reset/reimport. A top-level
+  connector-owned `stateVersion` in a flat v1 blob is preserved.
 - **Sync window**: read
   `adapter.event.payload.event_context.extract_from` / `extract_to`. The SDK
   resolves them from the platform's time values, or from the last successful
@@ -479,17 +538,34 @@ the emit.
 **`lastSyncStarted` / `lastSuccessfulSyncStarted`: rename or repoint.**
 Getting this wrong compiles but silently breaks incremental sync.
 
-- **Not in the connector's `State` interface** (it came from the SDK): delete
-  writes, and repoint reads to `extract_from`.
+These rules cover **top-level** state keys only; the v1 migration moves only
+those. A cursor nested in the connector's own object (`state.extractor.lastSuccessfulSyncStarted`)
+is connector-owned: leave it alone.
+
+- **Not in the connector's `State` interface**, or declared but never written
+  by the connector (it came from the SDK): delete writes, and repoint reads to
+  `extract_from`.
 - **Declared and used as the connector's own cursor** (derived from data, or
   read alongside `extract_from`): **rename** it (e.g. →
-  `lastSuccessfulWindowStart`) everywhere, including fixtures. Otherwise the v1
-  auto-migration moves it into SDK state and the connector loses it.
+  `lastSuccessfulWindowStart`) everywhere, including fixtures. Before
+  deploying v2, use a staged v1 deployment to copy the persisted value into
+  the new connector key, retaining the legacy key for v1 SDK bookkeeping.
+  Alternatively, explicitly reset/reimport. A source-only rename does not
+  migrate persisted data: the v1 auto-migration moves the old key into SDK
+  state and leaves the new connector key unset.
 - **Declared but only mirrors the SDK**: its only writes are "now" when data
   extraction starts and a copy on finish. Treat it as not declared, **even if
   it is read next to `extract_from`**. Renaming would leave it empty after the
   upgrade, because the v1 value moves into SDK state.
 
+After repointing, branches that chose between the two
+(`reset_extract_from ? extract_from : lastSuccessfulSyncStarted`) read the same
+value; collapse them and drop the `reset_extract_from` read. If the connector
+already used `extract_from` for something else (e.g. a skip filter) and the
+cursor for a second window (e.g. "re-emit and bump the floor"), repointing
+merges the two, so code below the window may become dead. Flag that low
+confidence.
+
 `extract_from` equals the last successful sync start only when the platform
 sends no time window. If a repointed read feeds logic beyond "skip items older
 than this" (e.g. distinguishing first syncs), flag it as low confidence; there
@@ -514,7 +590,7 @@ import axios from 'axios';
 import axiosRetry from 'axios-retry';
 
 export const axiosClient = axios.create();
-axiosRetry(axiosClient, {
+axiosRetry(axiosClient as Parameters<typeof axiosRetry>[0], {
   retries: 5,
   retryDelay: (retryCount, error) => axiosRetry.exponentialDelay(retryCount, error, 1000),
   retryCondition: (error) =>
@@ -528,6 +604,9 @@ axiosRetry(axiosClient, {
 });
 ```
 
+The cast is needed under ts-jest, which can resolve axios's `.d.ts` and
+`.d.cts` to different types.
+
 A deep import of the SDK's internal client (`dist/http/axios-client-internal`)
 relied on more: a 30 s timeout, retries of 429s that send `Retry-After` (waiting
 that long) and of `ECONNABORTED`. Reproduce what the connector depends on with
@@ -623,8 +702,10 @@ in minor versions, so give `switch` statements over it a `default`.
 
 ## 12. Error codes
 
-`ExtractionCommonError` is now `AirSyncErrorCode`. Its values are bare codes,
-and you set them on `error.code`:
+`ExtractionCommonError` is now `AirSyncErrorCode`. These remain the platform's
+known common error codes (`CommonError`), mapped by the snap-in manager in
+`internal/common/errors_snapin.go`. Their values are bare codes, and you set
+them on `error.code`:
 
 ```ts
 // v1
@@ -636,9 +717,11 @@ return {
 };
 ```
 
-The platform only recognizes a code when the message is exactly
-`ERROR_CODE=<code>`, so the SDK sends just that and logs your `message`. Write
-a useful `message`. Raw `'ERROR_CODE=…'` strings and connector helpers that
+`error.code` is an SDK input field. Before sending the callback, the SDK
+converts it into `event_data.error.message = 'ERROR_CODE=<code>'` and omits
+the `code` property. The backend continues reading the common error from
+`error.message`; your human-readable `message` goes to the logs. Write a
+useful `message`. Raw `'ERROR_CODE=…'` strings and connector helpers that
 return them (`HISTORICAL_DONE`, `authErrorCode(e)`) still work at runtime but
 are migrated too: make the helper return `AirSyncErrorCode | undefined`, set it
 as `code`, and update tests that pin the literal. The wire string doesn't
@@ -674,7 +757,9 @@ change.
 - For a deleted `onTimeout`, drop the tests of its body and assert it's
   `undefined`. A factory like `processExtractionTask: (_config) => jest.fn()`
   discards the config; use `processExtractionTask: jest.fn()` and read
-  `mocked.mock.calls[0][0].onTimeout`. Tests of a deleted SSOR workaround go with it.
+  `mocked.mock.calls[0][0].onTimeout`. Capture it in a module-level `const`
+  right after importing the worker: `jest.clearAllMocks()` in a `beforeEach`
+  wipes the calls. Tests of a deleted SSOR workaround go with it.
 
 ## 14. Smaller changes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devrev/airsync-sdk",
-  "version": "2.0.0-beta.10",
+  "version": "2.0.0-beta.12",
   "description": "Typescript SDK for building AirSync snap-ins on the DevRev platform.",
   "type": "commonjs",
   "main": "./dist/index.js",
@@ -26,7 +26,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/devrev/adaas-sdk.git"
+    "url": "git+https://github.com/devrev/airsync-sdk.git"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org"