@devrev/airsync-sdk 2.0.0-beta.9 → 2.1.0-beta.0

package/dist/uploader/uploader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"uploader.d.ts","sourceRoot":"","sources":["../../src/uploader/uploader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAOtC,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAWzD,OAAO,EAEL,gBAAgB,EAChB,wBAAwB,EACxB,cAAc,EACd,cAAc,EACf,MAAM,uBAAuB,CAAC;AAE/B,qBAAa,QAAQ;IACnB,OAAO,CAAC,kBAAkB,CAAC,CAAU;IACrC,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,cAAc,CAAyB;IAC/C,OAAO,CAAC,gBAAgB,CAAU;gBAEtB,EAAE,KAAK,EAAE,OAAO,EAAE,gBAAgB,EAAE,EAAE,wBAAwB;IAW1E,mFAAmF;IAC7E,MAAM,CACV,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,EAAE,GAAG,MAAM,GAChC,OAAO,CAAC,cAAc,CAAC;IAwEpB,oBAAoB,CACxB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,cAAc,CAAC,gBAAgB,CAAC,CAAC;IA2B5C,mFAAmF;IAC7E,cAAc,CAClB,QAAQ,EAAE,gBAAgB,EAC1B,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC;IAmBzC,kFAAkF;IAC5E,cAAc,CAClB,QAAQ,EAAE,gBAAgB,EAC1B,UAAU,EAAE,kBAAkB,GAC7B,OAAO,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC;IAqCnC,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;QACvD,QAAQ,CAAC,EAAE,aAAa,CAAC;QACzB,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB,CAAC;IAgCF,oEAAoE;IAC9D,4BAA4B,CAAC,EACjC,QAAQ,GACT,EAAE;QACD,QAAQ,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO,CAAC;QACV,WAAW,CAAC,EAAE,oBAAoB,EAAE,CAAC;QACrC,KAAK,CAAC,EAAE;YAAE,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC;KAC7B,CAAC;YAuDY,sBAAsB;YAsBtB,gBAAgB;IAc9B,yEAAyE;IACnE,yBAAyB,CAAC,EAC9B,UAAU,EACV,SAAiB,GAClB,EAAE;QACD,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,OAAO,CAAC;KACrB,GAAG,OAAO,CAAC,cAAc,CAAC,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC;CA6B/C"}
+{"version":3,"file":"uploader.d.ts","sourceRoot":"","sources":["../../src/uploader/uploader.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAUtC,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAWzD,OAAO,EAEL,gBAAgB,EAChB,eAAe,EACf,wBAAwB,EACxB,cAAc,EACd,cAAc,EACf,MAAM,uBAAuB,CAAC;AAE/B,qBAAa,QAAQ;IACnB,OAAO,CAAC,kBAAkB,CAAC,CAAU;IACrC,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,cAAc,CAAyB;IAC/C,OAAO,CAAC,gBAAgB,CAAU;gBAEtB,EAAE,KAAK,EAAE,OAAO,EAAE,gBAAgB,EAAE,EAAE,wBAAwB;IAW1E,mFAAmF;IAC7E,MAAM,CACV,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,EAAE,GAAG,MAAM,GAChC,OAAO,CAAC,cAAc,CAAC;IAwEpB,oBAAoB,CACxB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,cAAc,CAAC,gBAAgB,CAAC,CAAC;IA2B5C,mFAAmF;IAC7E,cAAc,CAClB,QAAQ,EAAE,gBAAgB,EAC1B,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC;IAmBzC,kFAAkF;IAC5E,cAAc,CAClB,QAAQ,EAAE,gBAAgB,EAC1B,UAAU,EAAE,kBAAkB,GAC7B,OAAO,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC;IAqCzC;;;;OAIG;IACG,qBAAqB,CACzB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,QAAQ,SAA0B,GACjC,OAAO,CAAC,cAAc,CAAC,eAAe,CAAC,CAAC;IAkB3C,+DAA+D;IACzD,0BAA0B,CAC9B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,QAAQ,SAA0B,GACjC,OAAO,CAAC,cAAc,CAAC,eAAe,CAAC,CAAC;IAkB3C,+DAA+D;IACzD,uBAAuB,CAC3B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC;IAoBzC;;;;OAIG;IACG,uBAAuB,CAC3B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,kBAAkB,GAC7B,OAAO,CAAC,cAAc,CAAC;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IA6HnD,oDAAoD;YACtC,mBAAmB;IAsD3B,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;QACvD,QAAQ,CAAC,EAAE,aAAa,CAAC;QACzB,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB,CAAC;IAgCF,oEAAoE;IAC9D,4BAA4B,CAAC,EACjC,QAAQ,GACT,EAAE;QACD,QAAQ,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO,CAAC;QACV,WAAW,CAAC,EAAE,oBAAoB,EAAE,CAAC;QACrC,KAAK,CAAC,EAAE;YAAE,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC;KAC7B,CAAC;YAuDY,sBAAsB;YAsBtB,gBAAgB;IAc9B,yEAAyE;IACnE,yBAAyB,CAAC,EAC9B,UAAU,EACV,SAAiB,GAClB,EAAE;QACD,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,OAAO,CAAC;KACrB,GAAG,OAAO,CAAC,cAAc,CAAC,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC;CA6B/C"}

package/dist/uploader/uploader.interfaces.d.ts

@@ -40,6 +40,12 @@ export interface ArtifactToUpload {
         value: string;
     }[];
 }
+/** Multipart upload state returned by the artifacts upload endpoints. */
+export interface MultipartUpload {
+    id: string;
+    url: string;
+    cursor: string;
+}
 export interface UploadResponse {
     artifact?: Artifact;
     error?: ErrorRecord;

package/dist/uploader/uploader.interfaces.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"uploader.interfaces.d.ts","sourceRoot":"","sources":["../../src/uploader/uploader.interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,YAAY,CAAC;IACpB,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,uFAAuF;IACvF,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,MAAM,cAAc,CAAC,CAAC,IACxB;IAAE,QAAQ,EAAE,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAEzC,oBAAY,iBAAiB;IAC3B,iBAAiB,wBAAwB;IACzC,iBAAiB,wBAAwB;IACzC,kBAAkB,yBAAyB;IAC3C,kBAAkB,yBAAyB;CAC5C;AAED,iEAAiE;AACjE,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,CAAC,iBAAiB,CAAC,iBAAiB,CAAC,CAAC,EAAE,MAAM,CAAC;IAC/C,CAAC,iBAAiB,CAAC,iBAAiB,CAAC,CAAC,EAAE,MAAM,CAAC;IAC/C,CAAC,iBAAiB,CAAC,kBAAkB,CAAC,CAAC,EAAE,MAAM,CAAC;IAChD,CAAC,iBAAiB,CAAC,kBAAkB,CAAC,CAAC,EAAE,MAAM,CAAC;CACjD;AAED,MAAM,MAAM,kBAAkB,GAAG,IAAI,CACnC,QAAQ,EACN,iBAAiB,CAAC,iBAAiB,GACnC,iBAAiB,CAAC,iBAAiB,GACnC,iBAAiB,CAAC,kBAAkB,GACpC,iBAAiB,CAAC,kBAAkB,CACvC,CAAC;AAEF,iDAAiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE;QACT,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;KACf,EAAE,CAAC;CACL;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE;QACF,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,SAAS,EAAE;QACT,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,QAAQ,CAAC,EAAE;QACT,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB"}
+{"version":3,"file":"uploader.interfaces.d.ts","sourceRoot":"","sources":["../../src/uploader/uploader.interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,YAAY,CAAC;IACpB,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,uFAAuF;IACvF,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,MAAM,cAAc,CAAC,CAAC,IACxB;IAAE,QAAQ,EAAE,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAEzC,oBAAY,iBAAiB;IAC3B,iBAAiB,wBAAwB;IACzC,iBAAiB,wBAAwB;IACzC,kBAAkB,yBAAyB;IAC3C,kBAAkB,yBAAyB;CAC5C;AAED,iEAAiE;AACjE,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,CAAC,iBAAiB,CAAC,iBAAiB,CAAC,CAAC,EAAE,MAAM,CAAC;IAC/C,CAAC,iBAAiB,CAAC,iBAAiB,CAAC,CAAC,EAAE,MAAM,CAAC;IAC/C,CAAC,iBAAiB,CAAC,kBAAkB,CAAC,CAAC,EAAE,MAAM,CAAC;IAChD,CAAC,iBAAiB,CAAC,kBAAkB,CAAC,CAAC,EAAE,MAAM,CAAC;CACjD;AAED,MAAM,MAAM,kBAAkB,GAAG,IAAI,CACnC,QAAQ,EACN,iBAAiB,CAAC,iBAAiB,GACnC,iBAAiB,CAAC,iBAAiB,GACnC,iBAAiB,CAAC,kBAAkB,GACpC,iBAAiB,CAAC,kBAAkB,CACvC,CAAC;AAEF,iDAAiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE;QACT,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;KACf,EAAE,CAAC;CACL;AAED,yEAAyE;AACzE,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE;QACF,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,SAAS,EAAE;QACT,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,QAAQ,CAAC,EAAE;QACT,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB"}

package/dist/uploader/uploader.js

@@ -4,6 +4,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Uploader = void 0;
+const http_1 = __importDefault(require("http"));
+const https_1 = __importDefault(require("https"));
 const form_data_1 = __importDefault(require("form-data"));
 const js_jsonl_1 = require("js-jsonl");
 const constants_1 = require("../common/constants");
@@ -136,6 +138,201 @@ class Uploader {
             return { error };
         }
     }
+    /**
+     * Creates an S3 multipart upload for an artifact whose size is not known.
+     * The returned URL is for part 1; subsequent URLs are obtained with
+     * getNextMultipartUploadPart.
+     */
+    async createMultipartUpload(filename, fileType, partSize = constants_1.S3_MULTIPART_CHUNK_SIZE) {
+        const url = `${this.devrevApiEndpoint}/internal/artifacts.upload.create`;
+        try {
+            const response = await client_1.axiosClient.post(url, {
+                file_name: (0, uploader_helpers_1.truncateFilename)(filename),
+                file_type: fileType,
+                part_size: partSize,
+            }, { headers: Object.assign({}, this.defaultHeaders) });
+            return { response: response.data };
+        }
+        catch (error) {
+            return { error };
+        }
+    }
+    /** Gets a presigned URL for the next multipart upload part. */
+    async getNextMultipartUploadPart(artifactId, cursor, partSize = constants_1.S3_MULTIPART_CHUNK_SIZE) {
+        const url = `${this.devrevApiEndpoint}/internal/artifacts.upload.next`;
+        try {
+            const response = await client_1.axiosClient.post(url, {
+                id: artifactId,
+                cursor,
+                part_size: partSize,
+            }, { headers: Object.assign({}, this.defaultHeaders) });
+            return { response: response.data };
+        }
+        catch (error) {
+            return { error };
+        }
+    }
+    /** Finalizes and publishes an S3 multipart artifact upload. */
+    async completeMultipartUpload(artifactId, cursor) {
+        const url = `${this.devrevApiEndpoint}/internal/artifacts.upload.complete`;
+        try {
+            const response = await client_1.axiosClient.post(url, {
+                id: artifactId,
+                cursor,
+            }, { headers: Object.assign({}, this.defaultHeaders) });
+            if (response.status >= 200 && response.status < 300) {
+                return { response };
+            }
+            return { error: response };
+        }
+        catch (error) {
+            return { error };
+        }
+    }
+    /**
+     * Streams an attachment of unknown size through an S3 multipart upload.
+     * At most one 10 MiB part is buffered at a time. The final part may be
+     * smaller than S3's 5 MiB minimum.
+     */
+    async streamArtifactMultipart(filename, fileType, fileStream) {
+        try {
+            const iterator = fileStream.data[Symbol.asyncIterator]();
+            let pendingChunk;
+            // Read a complete part before requesting its presigned URL. The gateway
+            // signs Content-Length using part_size, so the requested part size must
+            // be the exact byte length that will be sent (including the final part).
+            const readPart = async () => {
+                const chunks = [];
+                let length = 0;
+                while (length < constants_1.S3_MULTIPART_CHUNK_SIZE) {
+                    let chunk = pendingChunk;
+                    pendingChunk = undefined;
+                    if (!chunk) {
+                        const next = await iterator.next();
+                        if (next.done) {
+                            break;
+                        }
+                        chunk = Buffer.isBuffer(next.value)
+                            ? next.value
+                            : Buffer.from(next.value);
+                    }
+                    if (chunk.length === 0) {
+                        continue;
+                    }
+                    const capacity = constants_1.S3_MULTIPART_CHUNK_SIZE - length;
+                    if (chunk.length <= capacity) {
+                        chunks.push(chunk);
+                        length += chunk.length;
+                    }
+                    else {
+                        chunks.push(chunk.subarray(0, capacity));
+                        pendingChunk = chunk.subarray(capacity);
+                        length += capacity;
+                    }
+                }
+                return length > 0 ? Buffer.concat(chunks, length) : undefined;
+            };
+            let part = await readPart();
+            if (!part) {
+                throw new Error('Cannot complete a multipart upload with an empty file.');
+            }
+            const { response: createdUpload, error: createError } = await this.createMultipartUpload(filename, fileType, part.length);
+            if (createError || !createdUpload) {
+                return {
+                    error: createError !== null && createError !== void 0 ? createError : new Error('Multipart upload creation returned no response.'),
+                };
+            }
+            const artifactId = createdUpload.id;
+            let cursor = createdUpload.cursor;
+            let uploadUrl = createdUpload.url;
+            if (!artifactId || !cursor || !uploadUrl) {
+                return {
+                    error: new Error('Multipart upload creation returned incomplete upload information.'),
+                };
+            }
+            while (part) {
+                const { response, error } = await this.uploadMultipartPart(uploadUrl, part, part.length);
+                if (error || !response) {
+                    return {
+                        error: error !== null && error !== void 0 ? error : new Error('Multipart part upload returned no response.'),
+                    };
+                }
+                const nextPart = part.length === constants_1.S3_MULTIPART_CHUNK_SIZE
+                    ? await readPart()
+                    : undefined;
+                if (!nextPart) {
+                    break;
+                }
+                const { response: nextUpload, error: nextError } = await this.getNextMultipartUploadPart(artifactId, cursor, nextPart.length);
+                if (nextError || !(nextUpload === null || nextUpload === void 0 ? void 0 : nextUpload.url) || !nextUpload.cursor) {
+                    return {
+                        error: nextError !== null && nextError !== void 0 ? nextError : new Error('Could not obtain the next multipart upload URL.'),
+                    };
+                }
+                part = nextPart;
+                uploadUrl = nextUpload.url;
+                cursor = nextUpload.cursor;
+            }
+            const { error: completeError } = await this.completeMultipartUpload(artifactId, cursor);
+            if (completeError) {
+                return { error: completeError };
+            }
+            return { response: { artifact_id: artifactId } };
+        }
+        catch (error) {
+            return { error };
+        }
+        finally {
+            (0, uploader_helpers_1.destroyHttpStream)(fileStream);
+        }
+    }
+    /** Uploads one raw part to its presigned S3 URL. */
+    async uploadMultipartPart(uploadUrl, part, contentLength) {
+        try {
+            // Use Node's native request instead of Axios for the presigned request.
+            // Axios may normalize, remove, or recalculate Content-Length; that is
+            // not allowed when the presigned URL includes this header in its
+            // signature.
+            const parsedUrl = new URL(uploadUrl);
+            const transport = parsedUrl.protocol === 'https:' ? https_1.default : http_1.default;
+            const response = await new Promise((resolve, reject) => {
+                const request = transport.request(parsedUrl, {
+                    method: 'PUT',
+                    headers: {
+                        'Content-Length': String(contentLength),
+                    },
+                }, (incomingResponse) => {
+                    const chunks = [];
+                    incomingResponse.on('data', (chunk) => chunks.push(chunk));
+                    incomingResponse.on('end', () => {
+                        var _a, _b;
+                        const data = Buffer.concat(chunks);
+                        const status = (_a = incomingResponse.statusCode) !== null && _a !== void 0 ? _a : 0;
+                        const axiosResponse = {
+                            data,
+                            status,
+                            statusText: (_b = incomingResponse.statusMessage) !== null && _b !== void 0 ? _b : '',
+                            headers: incomingResponse.headers,
+                            config: {},
+                            request,
+                        };
+                        if (status >= 200 && status < 400) {
+                            resolve(axiosResponse);
+                        }
+                        else {
+                            reject(new Error(`Multipart part upload returned HTTP ${status}.`));
+                        }
+                    });
+                });
+                request.once('error', reject);
+                request.end(part);
+            });
+            return { response };
+        }
+        catch (error) {
+            return { error };
+        }
+    }
     async confirmArtifactUpload(artifactId) {
         const url = `${this.devrevApiEndpoint}/internal/airdrop.artifacts.confirm-upload`;
         try {

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,40 +34,58 @@ 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
    npm install @devrev/airsync-sdk@beta   # @latest after GA
    ```
-   If the installed `docs/MIGRATION.md` differs from this copy, switch to it.
+   Rename or remove `overrides` / `resolutions` entries keyed on
+   `@devrev/ts-adaas`; `npm uninstall` leaves them behind. If the installed
+   `docs/MIGRATION.md` differs from this copy, switch to it.
 4. **Apply §1–§14 in order** across source and tests. After §1, search by
    symbol (`\.emit\(`, `WorkerAdapter`, `sync_mapper_record`, …), not by the old
    package name; test files that import nothing from the SDK still need
    changes.
 5. **Verify**: `npm install && npx tsc --noEmit && npm run lint && npm run build && npm test`.
-   If tsconfig excludes tests, the test run is their type check. Fix and rerun,
+   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` 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):
+   `EventEmitter.emit`, the connector's own `axiosClient` from §9,
+   `@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|@devrev/typescript-sdk|(Extractor|Loader)EventType|ExtractionCommonError|ERROR_CODE=|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' . \
+   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'
    ```
    The sweep covers `test/` and other folders that tsc, lint and jest often
    exclude. A hit there is real: `@devrev/typescript-sdk` must be in
    `package.json` (§1), and a `local` argv must become the env var (§3).
+   Also check `package.json` scripts and shell scripts for a bare `local`
+   argument (`npm run test:server -- local`, `main.ts local`).
    Also grep `getByExternalId|getByTargetId` and check each call against §10:
    existence checks there compile but silently invert.
    Then rewrite any connector docs (`README`, `AGENTS.md`, `CLAUDE.md`, `docs/`)
-   that describe v1 behavior.
+   that describe v1 behavior, including text that paraphrases DevRev docs with
+   legacy event names.
 7. **Write `MIGRATION_REVIEW.md`** at the repo root: one line per section that
    changed code with `high` / `medium` / `low confidence`, a sentence on what
    to verify for medium/low, and the final check results with an
@@ -71,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.
@@ -99,7 +121,7 @@ v2; templates are copied into new connectors, so stale comments spread.
   root equivalent are listed in §11. Never import the SDK's internal HTTP client
   (`dist/http/axios-client-internal`): use the connector's own client (§9).
 - **Node.js ≥ 20.** Bump the connector's `engines`, CI image and `.nvmrc` if
-  they pin older. Dependabot / CI configs that name `@devrev/ts-adaas` switch to
+  they pin older. `@types/node` can stay as it is. Dependabot / CI configs that name `@devrev/ts-adaas` switch to
   `@devrev/airsync-sdk`.
 - `ts-node` and `@devrev/typescript-sdk` are no longer SDK dependencies. A
   connector that runs `.ts` workers directly needs `ts-node` in its own
@@ -107,7 +129,7 @@ v2; templates are copied into new connectors, so stale comments spread.
   it. The template's local test server (`code/test/runner.ts`, and the copy
   `airsync start-worker` writes to `code/.snapin-test/`) imports
   `@devrev/typescript-sdk/dist/snap-ins`, so template connectors add it to
-  `devDependencies`. Most connectors exclude `test/` from tsc, lint and jest,
+  `devDependencies` (`1.1.78`, the version the template pins). Most connectors exclude `test/` from tsc, lint and jest,
   so the gates pass and the local worker then fails with
   `Cannot find module '@devrev/typescript-sdk/dist/snap-ins'`.
   `InputData` (the type of `event.input_data`) is now exported from the
@@ -125,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:
 
@@ -138,8 +163,18 @@ Deprecated `EventContext` aliases are removed. Use the current names:
 | `sync_run`, `sync_run_id` | `run_id` |
 | `uuid` | `request_id_adaas` |
 
-`reset_extraction` and `reset_extract_from` remain (the SDK never read them);
-leave connector logic that uses them alone.
+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` 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`
 
@@ -233,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`.
@@ -265,6 +300,21 @@ If a shared `handleError` emitted from many `catch` blocks that rethrow, v1
 kept only the first emit. Record the first result (`firstError ??= …`) and
 return it from the task's outermost `catch`.
 
+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. 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
 it in the task's outermost `catch`:
@@ -301,7 +351,12 @@ helpers, assert on the return value.
     v1 (the task had a path that didn't emit) **and** it did real work or set a
     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.
+    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.
 
@@ -312,6 +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
@@ -332,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
@@ -400,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
@@ -416,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:
@@ -443,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
@@ -456,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
@@ -491,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) =>
@@ -505,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
@@ -550,6 +652,10 @@ return record?.sync_mapper_record.external_ids[0];
 - Hand-written structural types (`{ getByTargetId(): Promise<{ data?: … }> }`)
   keep `.data` compiling. Replace them with `Pick<Mappers, 'getByTargetId'>`.
 - Replace 404 `catch` branches with a `null` check.
+- A **generic `catch`** around a lookup (no 404 test) also handled "not
+  found": it reported an item error, logged a warning or tried the next ID.
+  With `null` that path no longer runs, so add a `null` branch that does what
+  the `catch` did, and keep the `catch` for other failures.
 - Replace `isAxiosError` checks on mapper calls with
   `e instanceof AirSyncHttpError` / `e.status`. Checks on the connector's own
   HTTP calls stay.
@@ -596,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
@@ -609,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
@@ -645,7 +755,11 @@ change.
   `status` unions (§6), mapper `null` / unwrapped bodies (§10), `code` on
   errors (§12), renamed state fields and the removed SDK fields (§8).
 - For a deleted `onTimeout`, drop the tests of its body and assert it's
-  `undefined`. Tests of a deleted SSOR workaround go with it.
+  `undefined`. A factory like `processExtractionTask: (_config) => jest.fn()`
+  discards the config; use `processExtractionTask: jest.fn()` and read
+  `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