@devrev/airsync-sdk 2.0.0-beta.1 → 2.0.0-beta.11

package/dist/repo/repo.interfaces.d.ts

@@ -1,35 +1,26 @@
+import { AirSyncEvent } from '../types/extraction';
+import { RepoOptions, RuntimeOptions } from '../types/workers';
 import { Artifact } from '../uploader/uploader.interfaces';
-import { AirdropEvent } from '../types/extraction';
-import { WorkerAdapterOptions } from '../types/workers';
-/**
- * RepoInterface is an interface that defines the structure of a repo which is used to store and upload extracted data.
- */
+/** Stores and uploads extracted data. */
 export interface RepoInterface {
     itemType: string;
     normalize?: (record: object) => NormalizedItem | NormalizedAttachment;
+    overriddenOptions?: RepoOptions;
 }
-/**
- * RepoFactoryInterface is an interface that defines the structure of a repo factory which is used to create a repo.
- */
 export interface RepoFactoryInterface {
-    event: AirdropEvent;
+    event: AirSyncEvent;
     itemType: string;
     normalize?: (record: object) => NormalizedItem | NormalizedAttachment;
     onUpload: (artifact: Artifact) => void;
-    options?: WorkerAdapterOptions;
+    options?: RuntimeOptions;
+    skipConfirmation?: boolean;
 }
-/**
- * NormalizedItem is an interface of item after normalization.
- */
 export interface NormalizedItem {
     id: string;
     created_date: string;
     modified_date: string;
     data: object;
 }
-/**
- * NormalizedAttachment is an interface of attachment after normalization.
- */
 export interface NormalizedAttachment {
     url: string;
     id: string;
@@ -37,10 +28,10 @@ export interface NormalizedAttachment {
     parent_id: string;
     author_id?: string;
     inline?: boolean;
-    grand_parent_id?: number | string;
+    content_type?: string;
+    created_date?: string;
+    modified_date?: string;
+    grand_parent_id?: string;
 }
-/**
- * Item is an interface that defines the structure of an item.
- */
 export type Item = Record<string, any>;
 //# sourceMappingURL=repo.interfaces.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"repo.interfaces.d.ts","sourceRoot":"","sources":["../../src/repo/repo.interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAE3D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,cAAc,GAAG,oBAAoB,CAAC;CACvE;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,YAAY,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,cAAc,GAAG,oBAAoB,CAAC;IACtE,QAAQ,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC;IACvC,OAAO,CAAC,EAAE,oBAAoB,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IAIjB,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACnC;AAED;;GAEG;AAEH,MAAM,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC"}
+{"version":3,"file":"repo.interfaces.d.ts","sourceRoot":"","sources":["../../src/repo/repo.interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAE3D,yCAAyC;AACzC,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,cAAc,GAAG,oBAAoB,CAAC;IACtE,iBAAiB,CAAC,EAAE,WAAW,CAAC;CACjC;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,YAAY,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,cAAc,GAAG,oBAAoB,CAAC;IACtE,QAAQ,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC;IACvC,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAGD,MAAM,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC"}

package/dist/repo/repo.js

@@ -3,13 +3,19 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Repo = void 0;
 const constants_1 = require("../common/constants");
 const uploader_1 = require("../uploader/uploader");
+const repo_helpers_1 = require("./repo.helpers");
 class Repo {
-    constructor({ event, itemType, normalize, onUpload, options, }) {
+    /** @internal */
+    constructor({ event, itemType, normalize, onUpload, options, skipConfirmation, }) {
+        this.dateRanges = {
+            creationDate: {},
+            modifiedDate: {},
+        };
         this.items = [];
         this.itemType = itemType;
         this.normalize = normalize;
         this.onUpload = onUpload;
-        this.uploader = new uploader_1.Uploader({ event, options });
+        this.uploader = new uploader_1.Uploader({ event, options, skipConfirmation });
         this.options = options;
         this.uploadedArtifacts = [];
     }
@@ -17,17 +23,33 @@ class Repo {
         return this.items;
     }
     async upload(batch) {
+        var _a;
         const itemsToUpload = batch || this.items;
         if (itemsToUpload.length > 0) {
+            for (const item of itemsToUpload) {
+                const createdDate = item === null || item === void 0 ? void 0 : item.created_date;
+                if (createdDate != null) {
+                    const createdMs = (0, repo_helpers_1.toValidTimestamp)(createdDate);
+                    if (createdMs !== undefined) {
+                        (0, repo_helpers_1.updateRange)(this.dateRanges.creationDate, createdMs);
+                    }
+                }
+                const modifiedDate = item === null || item === void 0 ? void 0 : item.modified_date;
+                if (modifiedDate != null && modifiedDate !== '') {
+                    const modifiedMs = (0, repo_helpers_1.toValidTimestamp)(modifiedDate);
+                    if (modifiedMs !== undefined) {
+                        (0, repo_helpers_1.updateRange)(this.dateRanges.modifiedDate, modifiedMs);
+                    }
+                }
+            }
             console.log(`Uploading ${itemsToUpload.length} items of type ${this.itemType}. `);
             const { artifact, error } = await this.uploader.upload(this.itemType, itemsToUpload);
             if (error || !artifact) {
-                console.error('Error while uploading batch', error);
-                return error;
+                console.error(`Error while uploading batch of ${itemsToUpload.length} items of type ${this.itemType}.`, error);
+                throw new Error((_a = error === null || error === void 0 ? void 0 : error.message) !== null && _a !== void 0 ? _a : `Upload failed for item type "${this.itemType}" without artifact.`);
             }
             this.onUpload(artifact);
             this.uploadedArtifacts.push(artifact);
-            // Clear the uploaded items from the main items array if no batch was specified
             if (!batch) {
                 this.items = [];
             }
@@ -37,39 +59,31 @@ class Repo {
             console.log(`No items to upload for type ${this.itemType}. Skipping upload.`);
         }
     }
+    /** Buffers items and uploads every full batch. Throws if an upload fails. */
     async push(items) {
         var _a;
         let recordsToPush;
         if (!items || items.length === 0) {
             console.log(`No items to push for type ${this.itemType}. Skipping push.`);
-            return true;
+            return;
         }
-        // Normalize items if needed
         if (this.normalize &&
-            this.itemType != constants_1.AIRDROP_DEFAULT_ITEM_TYPES.EXTERNAL_DOMAIN_METADATA &&
-            this.itemType != constants_1.AIRDROP_DEFAULT_ITEM_TYPES.SSOR_ATTACHMENT) {
+            this.itemType != constants_1.AirSyncDefaultItemTypes.EXTERNAL_DOMAIN_METADATA &&
+            this.itemType != constants_1.SSOR_ATTACHMENT) {
             recordsToPush = items.map((item) => this.normalize(item));
         }
         else {
             recordsToPush = items;
         }
-        // Add the new records to the items array
         this.items.push(...recordsToPush);
-        // Upload in batches while the number of items exceeds the batch size
         const batchSize = ((_a = this.options) === null || _a === void 0 ? void 0 : _a.batchSize) || constants_1.ARTIFACT_BATCH_SIZE;
         while (this.items.length >= batchSize) {
-            // Slice out a batch of batchSize items to upload
-            const batch = this.items.splice(0, batchSize);
-            try {
-                // Upload the batch
-                await this.upload(batch);
-            }
-            catch (error) {
-                console.error('Error while uploading batch', error);
-                return false;
-            }
+            // Items leave the repo only after their batch uploaded, so a failed
+            // batch is still there for the next flush.
+            const batch = this.items.slice(0, batchSize);
+            await this.upload(batch);
+            this.items.splice(0, batchSize);
         }
-        return true;
     }
 }
 exports.Repo = Repo;

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

@@ -0,0 +1,58 @@
+import { InitialDomainMapping } from '../types/common';
+import { AirSyncEvent } from '../types/extraction';
+import { ExtractionScope } from '../types/workers';
+import { SdkState, StateInterface } from './state.interfaces';
+/**
+ * State lifecycle shared by all sync modes: connector/SDK state separation,
+ * fetch/init/post, the v1 to v2 migration shim, and the snap-in-version-gated
+ * initial domain mapping install. Subclasses seed the SDK-owned state.
+ */
+export declare abstract class BaseState<ConnectorState> {
+    protected _connectorState: ConnectorState;
+    protected _sdkState: SdkState;
+    protected _extractionScope: ExtractionScope;
+    protected readonly initialSdkState: SdkState;
+    protected readonly event: AirSyncEvent;
+    private workerUrl;
+    private devrevToken;
+    private syncUnitId;
+    private requestId;
+    constructor({ event, initialState }: StateInterface<ConnectorState>, initialSdkState: SdkState);
+    /** Connector-owned state; what `adapter.state` exposes to snap-in code. */
+    get state(): ConnectorState;
+    set state(value: ConnectorState);
+    /** SDK-internal bookkeeping state. Never exposed to connector code. */
+    get sdkState(): SdkState;
+    set sdkState(value: SdkState);
+    get extractionScope(): ExtractionScope;
+    /**
+     * Installs the initial domain mapping when the snap-in version in state
+     * differs from the event context. Shared by all modes so a loading run still
+     * installs the mapping if extraction has not done so.
+     */
+    installInitialDomainMappingIfNeeded(initialDomainMapping?: InitialDomainMapping): Promise<void>;
+    /**
+     * Fetches state from API, or creates the initial state on 404. Reads both
+     * the v2 envelope and a legacy flat v1 blob (migrated on read); always
+     * persists the v2 envelope going forward.
+     */
+    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
+     * `V1_SDK_STATE_KEYS`.
+     */
+    private normalizeFetchedState;
+    private readEnvelope;
+    /**
+     * Posts the v2 envelope (connector and SDK state as they are now) to the
+     * API. Throws on failure so a caller can stop before a risky external write.
+     */
+    postState(): Promise<void>;
+    fetchState(): Promise<{
+        state: string;
+        objects?: string;
+    }>;
+}
+//# sourceMappingURL=base-state.d.ts.map

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

@@ -0,0 +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"}

package/dist/state/base-state.js

@@ -0,0 +1,242 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseState = void 0;
+const node_worker_threads_1 = require("node:worker_threads");
+const axios_1 = __importDefault(require("axios"));
+const client_1 = require("../http/client");
+const logger_1 = require("../logger/logger");
+const workers_1 = require("../types/workers");
+const install_initial_domain_mapping_1 = require("./install-initial-domain-mapping");
+const state_interfaces_1 = require("./state.interfaces");
+/**
+ * State lifecycle shared by all sync modes: connector/SDK state separation,
+ * fetch/init/post, the v1 to v2 migration shim, and the snap-in-version-gated
+ * initial domain mapping install. Subclasses seed the SDK-owned state.
+ */
+class BaseState {
+    constructor({ event, initialState }, initialSdkState) {
+        this._extractionScope = {};
+        this.event = event;
+        this.initialSdkState = initialSdkState;
+        this._connectorState = initialState;
+        this._sdkState = Object.assign({}, initialSdkState);
+        this.workerUrl = event.payload.event_context.worker_data_url;
+        this.devrevToken = event.context.secrets.service_account_token;
+        this.syncUnitId = event.payload.event_context.sync_unit_id;
+        this.requestId = event.payload.event_context.request_id_adaas;
+    }
+    /** Connector-owned state; what `adapter.state` exposes to snap-in code. */
+    get state() {
+        return this._connectorState;
+    }
+    set state(value) {
+        this._connectorState = value;
+    }
+    /** SDK-internal bookkeeping state. Never exposed to connector code. */
+    get sdkState() {
+        return this._sdkState;
+    }
+    set sdkState(value) {
+        this._sdkState = value;
+    }
+    get extractionScope() {
+        return this._extractionScope;
+    }
+    /**
+     * Installs the initial domain mapping when the snap-in version in state
+     * differs from the event context. Shared by all modes so a loading run still
+     * installs the mapping if extraction has not done so.
+     */
+    async installInitialDomainMappingIfNeeded(initialDomainMapping) {
+        const snapInVersionId = this.event.context.snap_in_version_id;
+        const hasSnapInVersionInState = 'snapInVersionId' in this.sdkState;
+        const shouldUpdateIDM = !hasSnapInVersionInState ||
+            this.sdkState.snapInVersionId !== snapInVersionId;
+        if (!shouldUpdateIDM) {
+            console.log(`Snap-in version in state matches the version in event context "${snapInVersionId}". Skipping initial domain mapping installation.`);
+            return;
+        }
+        try {
+            console.log(`Snap-in version in state "${this.sdkState.snapInVersionId}" does not match the version in event context "${snapInVersionId}". Installing initial domain mapping.`);
+            if (initialDomainMapping) {
+                await (0, install_initial_domain_mapping_1.installInitialDomainMapping)(this.event, initialDomainMapping);
+                this.sdkState.snapInVersionId = snapInVersionId;
+            }
+            else {
+                throw new Error('No initial domain mapping was passed to spawn function. Skipping initial domain mapping installation.');
+            }
+        }
+        catch (error) {
+            const errorMessage = `Error while installing initial domain mapping. ${(0, logger_1.serializeError)(error)}`;
+            console.error(errorMessage);
+            node_worker_threads_1.parentPort === null || node_worker_threads_1.parentPort === void 0 ? void 0 : node_worker_threads_1.parentPort.postMessage({
+                subject: workers_1.WorkerMessageSubject.WorkerMessageFailed,
+                payload: { message: errorMessage },
+            });
+            process.exit(1);
+        }
+    }
+    /**
+     * Fetches state from API, or creates the initial state on 404. Reads both
+     * the v2 envelope and a legacy flat v1 blob (migrated on read); always
+     * persists the v2 envelope going forward.
+     */
+    async init(initialState) {
+        var _a;
+        try {
+            const { state: stringifiedState, objects } = await this.fetchState();
+            if (!stringifiedState) {
+                throw new Error('No state found in response.');
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(stringifiedState);
+            }
+            catch (error) {
+                throw new Error(`Failed to parse state. ${error}`);
+            }
+            const { connectorState, sdkState } = this.normalizeFetchedState(parsed);
+            this.state = connectorState;
+            this.sdkState = sdkState;
+            console.log('State fetched successfully. Current state', {
+                connectorState: (0, logger_1.getPrintableState)(this.state),
+                sdkState: (0, logger_1.getPrintableState)(this.sdkState),
+            });
+            if (objects) {
+                try {
+                    this._extractionScope = JSON.parse(objects);
+                }
+                catch (error) {
+                    console.warn(`Failed to parse extractionScope. ${error}`);
+                }
+            }
+        }
+        catch (error) {
+            try {
+                if (!(axios_1.default.isAxiosError(error) && ((_a = error.response) === null || _a === void 0 ? void 0 : _a.status) === 404)) {
+                    throw error;
+                }
+                console.log('State not found. Initializing state with initial state.');
+                this.state = initialState;
+                this.sdkState = Object.assign({}, this.initialSdkState);
+                await this.postState();
+            }
+            catch (initError) {
+                const errorMessage = `Failed to init state. ${(0, logger_1.serializeError)(initError)}`;
+                console.error(errorMessage);
+                node_worker_threads_1.parentPort === null || node_worker_threads_1.parentPort === void 0 ? void 0 : node_worker_threads_1.parentPort.postMessage({
+                    subject: workers_1.WorkerMessageSubject.WorkerMessageFailed,
+                    payload: { message: errorMessage },
+                });
+                process.exit(1);
+            }
+        }
+    }
+    /**
+     * 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
+     * `V1_SDK_STATE_KEYS`.
+     */
+    normalizeFetchedState(parsed) {
+        if (parsed === null || typeof parsed !== 'object') {
+            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) {
+                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 = {};
+        for (const [key, value] of Object.entries(record)) {
+            if (state_interfaces_1.V1_SDK_STATE_KEYS.has(key)) {
+                sdkState[key] = value;
+            }
+            else {
+                connectorState[key] = value;
+            }
+        }
+        return {
+            connectorState: connectorState,
+            sdkState: Object.assign(Object.assign({}, this.initialSdkState), sdkState),
+        };
+    }
+    readEnvelope(record) {
+        if (!('connectorState' in record) || !('sdkState' in record)) {
+            throw new Error('Malformed state envelope: expected both "connectorState" and "sdkState".');
+        }
+        return {
+            connectorState: record.connectorState,
+            sdkState: Object.assign(Object.assign({}, this.initialSdkState), record.sdkState),
+        };
+    }
+    /**
+     * Posts the v2 envelope (connector and SDK state as they are now) to the
+     * API. Throws on failure so a caller can stop before a risky external write.
+     */
+    async postState() {
+        const url = this.workerUrl + '.update';
+        const envelope = {
+            stateVersion: state_interfaces_1.STATE_VERSION,
+            connectorState: this.state,
+            sdkState: this.sdkState,
+        };
+        let stringifiedState;
+        try {
+            stringifiedState = JSON.stringify(envelope);
+        }
+        catch (error) {
+            throw new Error(`Failed to stringify state. ${(0, logger_1.serializeError)(error)}`);
+        }
+        try {
+            await client_1.axiosClient.post(url, {
+                state: stringifiedState,
+            }, {
+                headers: {
+                    Authorization: this.devrevToken,
+                },
+                params: {
+                    sync_unit: this.syncUnitId,
+                    request_id: this.requestId,
+                },
+            });
+        }
+        catch (error) {
+            throw new Error(`Failed to update the state. ${(0, logger_1.serializeError)(error)}`);
+        }
+        console.log('State updated successfully to', {
+            connectorState: (0, logger_1.getPrintableState)(this.state),
+            sdkState: (0, logger_1.getPrintableState)(this.sdkState),
+        });
+    }
+    async fetchState() {
+        var _a, _b;
+        console.log(`Fetching state with sync unit id ${this.syncUnitId} and request id ${this.requestId}.`);
+        const url = this.workerUrl + '.get';
+        const response = await client_1.axiosClient.get(url, {
+            headers: {
+                Authorization: this.devrevToken,
+            },
+            params: {
+                sync_unit: this.syncUnitId,
+                request_id: this.requestId,
+            },
+        });
+        return {
+            state: (_a = response.data) === null || _a === void 0 ? void 0 : _a.state,
+            objects: (_b = response.data) === null || _b === void 0 ? void 0 : _b.objects,
+        };
+    }
+}
+exports.BaseState = BaseState;

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

@@ -0,0 +1,14 @@
+import { BaseState } from './base-state';
+import { StateInterface } from './state.interfaces';
+/** State for extraction workers: seeds extraction SDK state and adds extraction-window resolution. */
+export declare class ExtractionState<ConnectorState> extends BaseState<ConnectorState> {
+    constructor(params: StateInterface<ConnectorState>);
+    /**
+     * Resolves the extraction window onto the event context. StartExtractingMetadata
+     * resolves fresh from the event's TimeValues and overwrites the pending boundaries;
+     * all other events reuse those cached boundaries. Validates extract_from < extract_to.
+     */
+    resolveExtractionWindow(): void;
+}
+export declare function createExtractionState<ConnectorState>({ event, initialState, initialDomainMapping, options, }: StateInterface<ConnectorState>): Promise<ExtractionState<ConnectorState>>;
+//# sourceMappingURL=extraction-state.d.ts.map

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

@@ -0,0 +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;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

@@ -0,0 +1,146 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExtractionState = void 0;
+exports.createExtractionState = createExtractionState;
+const node_worker_threads_1 = require("node:worker_threads");
+const constants_1 = require("../common/constants");
+const logger_1 = require("../logger/logger");
+const extraction_1 = require("../types/extraction");
+const workers_1 = require("../types/workers");
+const base_state_1 = require("./base-state");
+const state_interfaces_1 = require("./state.interfaces");
+const time_value_resolver_1 = require("./time-value-resolver");
+/** State for extraction workers: seeds extraction SDK state and adds extraction-window resolution. */
+class ExtractionState extends base_state_1.BaseState {
+    constructor(params) {
+        super(params, state_interfaces_1.extractionSdkState);
+    }
+    /**
+     * Resolves the extraction window onto the event context. StartExtractingMetadata
+     * resolves fresh from the event's TimeValues and overwrites the pending boundaries;
+     * 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) => {
+            if (eventContext.extract_from !== undefined) {
+                eventContext.original_extract_from = eventContext.extract_from;
+            }
+            eventContext.extract_from = value;
+        };
+        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 = [
+                {
+                    source: 'extraction_start_time',
+                    target: 'extract_from',
+                    pending: 'pendingWorkersOldest',
+                },
+                {
+                    source: 'extraction_end_time',
+                    target: 'extract_to',
+                    pending: 'pendingWorkersNewest',
+                },
+            ];
+            for (const { source, target, pending } of timeFields) {
+                const timeValue = eventContext[source];
+                if (timeValue && timeValue.type) {
+                    try {
+                        const resolved = (0, time_value_resolver_1.resolveTimeValue)(timeValue, sdkState);
+                        if (target === 'extract_from') {
+                            overrideExtractFrom(resolved);
+                        }
+                        else {
+                            eventContext[target] = resolved;
+                        }
+                        sdkState[pending] = resolved;
+                        console.log(`Resolved ${target} to ${resolved}. Stored in ${pending}.`);
+                    }
+                    catch (error) {
+                        const errorMessage = `Failed to resolve ${source}: ${(0, logger_1.serializeError)(error)}`;
+                        console.error(errorMessage);
+                        node_worker_threads_1.parentPort === null || node_worker_threads_1.parentPort === void 0 ? void 0 : node_worker_threads_1.parentPort.postMessage({
+                            subject: workers_1.WorkerMessageSubject.WorkerMessageFailed,
+                            payload: { message: errorMessage },
+                        });
+                        process.exit(1);
+                    }
+                }
+                else if (target === 'extract_from') {
+                    // Non-CPv2 platforms send no TimeValue: prefer the last successful
+                    // sync start, else the extract_from the platform supplied directly.
+                    const fallback = sdkState.lastSuccessfulSyncStarted || eventContext.extract_from;
+                    if (fallback) {
+                        if (sdkState.lastSuccessfulSyncStarted) {
+                            overrideExtractFrom(fallback);
+                        }
+                        sdkState.pendingWorkersOldest = fallback;
+                        console.log(`Using ${sdkState.lastSuccessfulSyncStarted
+                            ? 'lastSuccessfulSyncStarted'
+                            : 'platform-provided extract_from'} as extract_from: ${fallback}. Stored in pendingWorkersOldest.`);
+                    }
+                }
+            }
+        }
+        else {
+            const pendingExtractFrom = sdkState.pendingWorkersOldest || sdkState.lastSuccessfulSyncStarted;
+            if (pendingExtractFrom) {
+                if (eventContext.extract_from !== pendingExtractFrom) {
+                    overrideExtractFrom(pendingExtractFrom);
+                }
+                console.log(`Using ${sdkState.pendingWorkersOldest
+                    ? 'pendingWorkersOldest'
+                    : 'lastSuccessfulSyncStarted'} as extract_from: ${pendingExtractFrom}.`);
+            }
+            else {
+                console.log('pendingWorkersOldest is not set in state. extract_from will not be populated for this invocation.');
+            }
+            if (sdkState.pendingWorkersNewest) {
+                eventContext.extract_to = sdkState.pendingWorkersNewest;
+                console.log(`Reusing pendingWorkersNewest as extract_to: ${sdkState.pendingWorkersNewest}.`);
+            }
+            else {
+                console.log('pendingWorkersNewest is not set in state. extract_to will not be populated for this invocation.');
+            }
+        }
+        if (eventContext.extract_from && eventContext.extract_to) {
+            if (eventContext.extract_from >= eventContext.extract_to) {
+                const errorMessage = `Invalid extraction window: extract_from (${eventContext.extract_from}) must be older than extract_to (${eventContext.extract_to}). This indicates an error in the platform.`;
+                console.error(errorMessage);
+                node_worker_threads_1.parentPort === null || node_worker_threads_1.parentPort === void 0 ? void 0 : node_worker_threads_1.parentPort.postMessage({
+                    subject: workers_1.WorkerMessageSubject.WorkerMessageFailed,
+                    payload: { message: errorMessage },
+                });
+                process.exit(1);
+            }
+        }
+    }
+}
+exports.ExtractionState = ExtractionState;
+async function createExtractionState({ event, initialState, initialDomainMapping, options, }) {
+    // Clone so the caller's initialState is never mutated.
+    const deepCloneInitialState = structuredClone(initialState);
+    const state = new ExtractionState({
+        event,
+        initialState: deepCloneInitialState,
+        initialDomainMapping,
+        options,
+    });
+    if (!constants_1.STATELESS_EVENT_TYPES.includes(event.payload.event_type)) {
+        await state.init(deepCloneInitialState);
+        await state.installInitialDomainMappingIfNeeded(initialDomainMapping);
+        state.resolveExtractionWindow();
+    }
+    return state;
+}

package/dist/state/install-initial-domain-mapping.d.ts

@@ -0,0 +1,4 @@
+import { InitialDomainMapping } from '../types/common';
+import { AirSyncEvent } from '../types/extraction';
+export declare function installInitialDomainMapping(event: AirSyncEvent, initialDomainMappingJson: InitialDomainMapping): Promise<void>;
+//# sourceMappingURL=install-initial-domain-mapping.d.ts.map

package/dist/state/install-initial-domain-mapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-initial-domain-mapping.d.ts","sourceRoot":"","sources":["../../src/state/install-initial-domain-mapping.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,wBAAsB,2BAA2B,CAC/C,KAAK,EAAE,YAAY,EACnB,wBAAwB,EAAE,oBAAoB,GAC7C,OAAO,CAAC,IAAI,CAAC,CAwFf"}