@devrev/airsync-sdk 2.0.0-beta.2 → 2.0.0-beta.3

package/dist/multithreading/process-task.js

@@ -1,60 +1,108 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.processTask = processTask;
+exports.processExtractionTask = processExtractionTask;
+exports.processLoadingTask = processLoadingTask;
 const node_worker_threads_1 = require("node:worker_threads");
 const logger_1 = require("../logger/logger");
 const logger_context_1 = require("../logger/logger.context");
-const state_1 = require("../state/state");
+const extraction_state_1 = require("../state/extraction-state");
+const loading_state_1 = require("../state/loading-state");
 const workers_1 = require("../types/workers");
-const worker_adapter_1 = require("./worker-adapter/worker-adapter");
-function processTask({ task, onTimeout, }) {
-    if (node_worker_threads_1.isMainThread) {
-        return;
-    }
-    void (async () => {
-        await (0, logger_context_1.runWithSdkLogContext)(async () => {
-            try {
-                const event = node_worker_threads_1.workerData.event;
-                const initialState = node_worker_threads_1.workerData.initialState;
-                const initialDomainMapping = node_worker_threads_1.workerData.initialDomainMapping;
-                const options = node_worker_threads_1.workerData.options;
-                // eslint-disable-next-line no-global-assign
-                console = new logger_1.Logger({ event, options });
-                const adapterState = await (0, state_1.createAdapterState)({
-                    event,
-                    initialState,
-                    initialDomainMapping,
-                    options,
-                });
-                const adapter = new worker_adapter_1.WorkerAdapter({
-                    event,
-                    adapterState,
-                    options,
-                });
-                node_worker_threads_1.parentPort === null || node_worker_threads_1.parentPort === void 0 ? void 0 : node_worker_threads_1.parentPort.on(workers_1.WorkerEvent.WorkerMessage, (message) => {
-                    if (message.subject !== workers_1.WorkerMessageSubject.WorkerMessageExit) {
-                        return;
-                    }
-                    console.log('Timeout received. Waiting for the task to finish.');
-                    adapter.isTimeout = true;
-                });
-                await (0, logger_context_1.runWithUserLogContext)(async () => task({ adapter }));
-                if (adapter.isTimeout && !adapter.hasWorkerEmitted) {
-                    await (0, logger_context_1.runWithUserLogContext)(async () => onTimeout({ adapter }));
+const extraction_adapter_1 = require("./adapters/extraction-adapter");
+const loading_adapter_1 = require("./adapters/loading-adapter");
+/**
+ * Shared worker-thread driver. Builds the logger context, runs the task and
+ * (on timeout) the onTimeout callback against the provided adapter, and wires
+ * the error/exit plumbing. The adapter is constructed by the caller so each
+ * entry point can build its own typed adapter.
+ */
+async function runWorkerTask(buildAdapter, { task, onTimeout }) {
+    await (0, logger_context_1.runWithSdkLogContext)(async () => {
+        try {
+            const adapter = await buildAdapter();
+            node_worker_threads_1.parentPort === null || node_worker_threads_1.parentPort === void 0 ? void 0 : node_worker_threads_1.parentPort.on(workers_1.WorkerEvent.WorkerMessage, (message) => {
+                if (message.subject !== workers_1.WorkerMessageSubject.WorkerMessageExit) {
+                    return;
                 }
-                process.exit(0);
+                console.log('Timeout received. Waiting for the task to finish.');
+                adapter.isTimeout = true;
+            });
+            await (0, logger_context_1.runWithUserLogContext)(async () => task({ adapter }));
+            if (adapter.isTimeout && !adapter.hasWorkerEmitted) {
+                await (0, logger_context_1.runWithUserLogContext)(async () => onTimeout({ adapter }));
             }
-            catch (error) {
-                (0, logger_context_1.runWithUserLogContext)(() => {
-                    const errorMessage = `Error while processing task. ${(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);
+            process.exit(0);
+        }
+        catch (error) {
+            (0, logger_context_1.runWithUserLogContext)(() => {
+                const errorMessage = `Error while processing task. ${(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);
+            });
+        }
+    });
+}
+/**
+ * Entry point for an extraction worker. Builds an {@link ExtractionAdapter} and
+ * runs the provided task against it.
+ *
+ * @public
+ */
+function processExtractionTask({ task, onTimeout, }) {
+    if (node_worker_threads_1.isMainThread) {
+        return;
+    }
+    void runWorkerTask(async () => {
+        const event = node_worker_threads_1.workerData.event;
+        const initialState = node_worker_threads_1.workerData.initialState;
+        const initialDomainMapping = node_worker_threads_1.workerData.initialDomainMapping;
+        const options = node_worker_threads_1.workerData.options;
+        // eslint-disable-next-line no-global-assign
+        console = new logger_1.Logger({ event, options });
+        const adapterState = await (0, extraction_state_1.createExtractionState)({
+            event,
+            initialState,
+            initialDomainMapping,
+            options,
+        });
+        return new extraction_adapter_1.ExtractionAdapter({
+            event,
+            adapterState,
+            options,
+        });
+    }, { task, onTimeout });
+}
+/**
+ * Entry point for a loading worker. Builds a {@link LoadingAdapter} and runs the
+ * provided task against it.
+ *
+ * @public
+ */
+function processLoadingTask({ task, onTimeout, }) {
+    if (node_worker_threads_1.isMainThread) {
+        return;
+    }
+    void runWorkerTask(async () => {
+        const event = node_worker_threads_1.workerData.event;
+        const initialState = node_worker_threads_1.workerData.initialState;
+        const initialDomainMapping = node_worker_threads_1.workerData.initialDomainMapping;
+        const options = node_worker_threads_1.workerData.options;
+        // eslint-disable-next-line no-global-assign
+        console = new logger_1.Logger({ event, options });
+        const adapterState = await (0, loading_state_1.createLoadingState)({
+            event,
+            initialState,
+            initialDomainMapping,
+            options,
+        });
+        return new loading_adapter_1.LoadingAdapter({
+            event,
+            adapterState,
+            options,
         });
-    })();
+    }, { task, onTimeout });
 }

package/dist/multithreading/process-task.test.js

@@ -46,18 +46,18 @@ jest.mock('../logger/logger.context', () => ({
     runWithSdkLogContext: jest.fn((fn) => fn()),
     runWithUserLogContext: jest.fn((fn) => fn()),
 }));
-jest.mock('../state/state', () => ({
-    createAdapterState: jest.fn(),
+jest.mock('../state/extraction-state', () => ({
+    createExtractionState: jest.fn(),
 }));
-jest.mock('./worker-adapter/worker-adapter', () => ({
-    WorkerAdapter: jest.fn().mockImplementation(() => ({
+jest.mock('./adapters/extraction-adapter', () => ({
+    ExtractionAdapter: jest.fn().mockImplementation(() => ({
         isTimeout: false,
         hasWorkerEmitted: false,
     })),
 }));
 const process_task_1 = require("./process-task");
-const state_1 = require("../state/state");
-const worker_adapter_1 = require("./worker-adapter/worker-adapter");
+const extraction_state_1 = require("../state/extraction-state");
+const extraction_adapter_1 = require("./adapters/extraction-adapter");
 const test_utils_1 = require("../common/test-utils");
 function setWorkerData(data) {
     global.__workerData__ = data;
@@ -67,9 +67,9 @@ function makeEvent(eventType = extraction_1.EventType.StartExtractingData) {
         payload: { event_type: eventType },
     });
 }
-// Flush the microtask queue enough to let the async IIFE inside processTask run.
+// Flush the microtask queue enough to let the async IIFE inside processExtractionTask run.
 const flush = async () => new Promise((r) => setTimeout(r, 0));
-describe(process_task_1.processTask.name, () => {
+describe(process_task_1.processExtractionTask.name, () => {
     let processExitSpy;
     beforeEach(() => {
         jest.clearAllMocks();
@@ -77,7 +77,7 @@ describe(process_task_1.processTask.name, () => {
         processExitSpy = jest
             .spyOn(process, 'exit')
             .mockImplementation((() => { }));
-        state_1.createAdapterState.mockResolvedValue({});
+        extraction_state_1.createExtractionState.mockResolvedValue({});
     });
     afterEach(() => {
         processExitSpy.mockRestore();
@@ -90,11 +90,11 @@ describe(process_task_1.processTask.name, () => {
         // onTimeout must be skipped. This is the guard the integration suite cannot
         // target cleanly because it requires a precise race between emit and timeout.
         const mockAdapter = { isTimeout: true, hasWorkerEmitted: true };
-        worker_adapter_1.WorkerAdapter.mockImplementation(() => mockAdapter);
+        extraction_adapter_1.ExtractionAdapter.mockImplementation(() => mockAdapter);
         const task = jest.fn().mockResolvedValue(undefined);
         const onTimeout = jest.fn().mockResolvedValue(undefined);
         // Act
-        (0, process_task_1.processTask)({ task, onTimeout });
+        (0, process_task_1.processExtractionTask)({ task, onTimeout });
         await flush();
         // Assert
         expect(onTimeout).not.toHaveBeenCalled();
@@ -105,11 +105,11 @@ describe(process_task_1.processTask.name, () => {
         const event = makeEvent();
         setWorkerData({ event, initialState: {}, options: {} });
         const mockAdapter = { isTimeout: false, hasWorkerEmitted: false };
-        worker_adapter_1.WorkerAdapter.mockImplementation(() => mockAdapter);
+        extraction_adapter_1.ExtractionAdapter.mockImplementation(() => mockAdapter);
         const task = jest.fn().mockResolvedValue(undefined);
         const onTimeout = jest.fn().mockResolvedValue(undefined);
         // Act
-        (0, process_task_1.processTask)({ task, onTimeout });
+        (0, process_task_1.processExtractionTask)({ task, onTimeout });
         await flush();
         // Grab the handler registered for WorkerMessage events and invoke it with
         // subjects that must NOT flip isTimeout (log messages, unknown subjects).
@@ -126,12 +126,12 @@ describe(process_task_1.processTask.name, () => {
         const event = makeEvent();
         setWorkerData({ event, initialState: {}, options: {} });
         const mockAdapter = { isTimeout: false, hasWorkerEmitted: false };
-        worker_adapter_1.WorkerAdapter.mockImplementation(() => mockAdapter);
+        extraction_adapter_1.ExtractionAdapter.mockImplementation(() => mockAdapter);
         const taskError = new Error('task boom');
         const task = jest.fn().mockRejectedValue(taskError);
         const onTimeout = jest.fn().mockResolvedValue(undefined);
         // Act
-        (0, process_task_1.processTask)({ task, onTimeout });
+        (0, process_task_1.processExtractionTask)({ task, onTimeout });
         await flush();
         // Assert
         expect(mockParentPortPostMessage).toHaveBeenCalledWith(expect.objectContaining({

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

@@ -0,0 +1,75 @@
+import { InitialDomainMapping } from '../types/common';
+import { AirSyncEvent } from '../types/extraction';
+import { ExtractionScope } from '../types/workers';
+import { BaseSdkState, StateInterface } from './state.interfaces';
+/**
+ * BaseState owns the state lifecycle shared by every sync mode: connector vs.
+ * SDK state separation, fetch/init/post against the platform, the v1->v2
+ * migration shim, and the snap-in-version-gated initial domain mapping install.
+ *
+ * Mode-specific subclasses (`ExtractionState`, `LoadingState`) narrow `sdkState`
+ * to their own SDK state shape and add mode-specific setup in their factories.
+ *
+ * @typeParam ConnectorState - the connector-owned state shape
+ * @typeParam SdkState - the SDK bookkeeping shape for this mode
+ */
+export declare abstract class BaseState<ConnectorState, SdkState extends BaseSdkState> {
+    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. This is 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 does
+     * not match the version in the event context. Shared by all modes so that a
+     * loading run still installs the mapping if extraction has not done so.
+     */
+    installInitialDomainMappingIfNeeded(initialDomainMapping?: InitialDomainMapping): Promise<void>;
+    /**
+     * Initializes the state for this adapter instance by fetching from API
+     * or creating an initial state if none exists (404).
+     *
+     * Reads both the v2 `{ connectorState, sdkState }` envelope and a legacy flat
+     * v1 blob (connector keys merged with SDK keys), migrating the latter on read.
+     * Always persists the v2 envelope going forward.
+     * @param initialState The initial connector state provided by the spawn function
+     */
+    init(initialState: ConnectorState): Promise<void>;
+    /**
+     * Normalizes a parsed on-disk state into the `{ connectorState, sdkState }`
+     * envelope, migrating a legacy flat v1 blob if needed.
+     *
+     * - v2 envelope (`{ connectorState, sdkState }`): used as-is.
+     * - v1 flat blob: SDK-owned keys (`V1_SDK_STATE_KEYS`) split into `sdkState`,
+     *   everything else becomes connector state.
+     * - Malformed envelope (one side present, the other missing) fails loud.
+     */
+    private normalizeFetchedState;
+    /**
+     *  Updates the state of the adapter by posting to API.
+     *  Persists the v2 `{ connectorState, sdkState }` envelope.
+     * @param {object} state - The connector state to be updated
+     */
+    postState(state?: ConnectorState): Promise<void>;
+    /**
+     *  Fetches the state of the adapter from API.
+     * @return  The raw state data from API
+     */
+    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;AAEnD,OAAO,EAEL,YAAY,EACZ,cAAc,EAEf,MAAM,oBAAoB,CAAC;AAE5B;;;;;;;;;;GAUG;AACH,8BAAsB,SAAS,CAAC,cAAc,EAAE,QAAQ,SAAS,YAAY;IAC3E,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,mFAAmF;IACnF,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;;;;;;;;OAQG;IACG,IAAI,CAAC,YAAY,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAkDvD;;;;;;;;OAQG;IACH,OAAO,CAAC,qBAAqB;IAyC7B;;;;OAIG;IACG,SAAS,CAAC,KAAK,CAAC,EAAE,cAAc;IA4DtC;;;OAGG;IACG,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,261 @@
+"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 axios_1 = __importDefault(require("axios"));
+const node_worker_threads_1 = require("node:worker_threads");
+const install_initial_domain_mapping_1 = require("../common/install-initial-domain-mapping");
+const axios_client_internal_1 = require("../http/axios-client-internal");
+const logger_1 = require("../logger/logger");
+const workers_1 = require("../types/workers");
+const state_interfaces_1 = require("./state.interfaces");
+/**
+ * BaseState owns the state lifecycle shared by every sync mode: connector vs.
+ * SDK state separation, fetch/init/post against the platform, the v1->v2
+ * migration shim, and the snap-in-version-gated initial domain mapping install.
+ *
+ * Mode-specific subclasses (`ExtractionState`, `LoadingState`) narrow `sdkState`
+ * to their own SDK state shape and add mode-specific setup in their factories.
+ *
+ * @typeParam ConnectorState - the connector-owned state shape
+ * @typeParam SdkState - the SDK bookkeeping shape for this mode
+ */
+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. This is 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 does
+     * not match the version in the event context. Shared by all modes so that 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);
+        }
+    }
+    /**
+     * Initializes the state for this adapter instance by fetching from API
+     * or creating an initial state if none exists (404).
+     *
+     * Reads both the v2 `{ connectorState, sdkState }` envelope and a legacy flat
+     * v1 blob (connector keys merged with SDK keys), migrating the latter on read.
+     * Always persists the v2 envelope going forward.
+     * @param initialState The initial connector state provided by the spawn function
+     */
+    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) {
+            if (axios_1.default.isAxiosError(error) && ((_a = error.response) === null || _a === void 0 ? void 0 : _a.status) === 404) {
+                console.log('State not found. Initializing state with initial state.');
+                this.state = initialState;
+                this.sdkState = Object.assign({}, this.initialSdkState);
+                await this.postState();
+            }
+            else {
+                const errorMessage = `Failed to init state. ${(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);
+            }
+        }
+    }
+    /**
+     * Normalizes a parsed on-disk state into the `{ connectorState, sdkState }`
+     * envelope, migrating a legacy flat v1 blob if needed.
+     *
+     * - v2 envelope (`{ connectorState, sdkState }`): used as-is.
+     * - v1 flat blob: SDK-owned keys (`V1_SDK_STATE_KEYS`) split into `sdkState`,
+     *   everything else becomes connector state.
+     * - Malformed envelope (one side present, the other missing) fails loud.
+     */
+    normalizeFetchedState(parsed) {
+        if (parsed === null || typeof parsed !== 'object') {
+            throw new Error('Fetched state is not a JSON object.');
+        }
+        const record = parsed;
+        const hasConnector = 'connectorState' in record;
+        const hasSdk = 'sdkState' in record;
+        if (hasConnector || hasSdk) {
+            if (!hasConnector || !hasSdk) {
+                throw new Error('Malformed state envelope: expected both "connectorState" and "sdkState".');
+            }
+            return {
+                connectorState: record.connectorState,
+                sdkState: Object.assign(Object.assign({}, this.initialSdkState), record.sdkState),
+            };
+        }
+        // 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),
+        };
+    }
+    /**
+     *  Updates the state of the adapter by posting to API.
+     *  Persists the v2 `{ connectorState, sdkState }` envelope.
+     * @param {object} state - The connector state to be updated
+     */
+    async postState(state) {
+        const url = this.workerUrl + '.update';
+        this.state = state || this.state;
+        const envelope = {
+            connectorState: this.state,
+            sdkState: this.sdkState,
+        };
+        let stringifiedState;
+        try {
+            stringifiedState = JSON.stringify(envelope);
+        }
+        catch (error) {
+            const errorMessage = `Failed to stringify state. ${(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);
+        }
+        try {
+            await axios_client_internal_1.axiosClient.post(url, {
+                state: stringifiedState,
+            }, {
+                headers: {
+                    Authorization: this.devrevToken,
+                },
+                params: {
+                    sync_unit: this.syncUnitId,
+                    request_id: this.requestId,
+                },
+            });
+            console.log('State updated successfully to', {
+                connectorState: (0, logger_1.getPrintableState)(this.state),
+                sdkState: (0, logger_1.getPrintableState)(this.sdkState),
+            });
+        }
+        catch (error) {
+            const errorMessage = `Failed to update the state. ${(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 the state of the adapter from API.
+     * @return  The raw state data from API
+     */
+    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 axios_client_internal_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,29 @@
+import { BaseState } from './base-state';
+import { ExtractionSdkState, StateInterface } from './state.interfaces';
+/**
+ * ExtractionState is the per-mode state for extraction workers. It narrows
+ * `sdkState` to `ExtractionSdkState` (extraction boundaries + attachments
+ * bookkeeping) on top of the shared lifecycle provided by `BaseState`.
+ */
+export declare class ExtractionState<ConnectorState> extends BaseState<ConnectorState, ExtractionSdkState> {
+    constructor(params: StateInterface<ConnectorState>);
+    /**
+     * Resolves the extraction window onto the event context.
+     *
+     * On StartExtractingMetadata: resolve fresh from the TimeValue objects in the
+     * event context and cache them as pending boundaries (always overwrite).
+     * On all other events: reuse the pending boundaries cached during
+     * StartExtractingMetadata. Finally, validate that extract_from < extract_to.
+     */
+    resolveExtractionWindow(): void;
+}
+/**
+ * Creates and initializes an `ExtractionState` for an extraction worker.
+ *
+ * For non-stateless events this fetches/migrates persisted state, installs the
+ * initial domain mapping if the snap-in version changed, then resolves the
+ * extraction window (time-value resolution + pending boundary reuse) and
+ * validates it.
+ */
+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":"AAQA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EACL,kBAAkB,EAElB,cAAc,EACf,MAAM,oBAAoB,CAAC;AAE5B;;;;GAIG;AACH,qBAAa,eAAe,CAAC,cAAc,CAAE,SAAQ,SAAS,CAC5D,cAAc,EACd,kBAAkB,CACnB;gBACa,MAAM,EAAE,cAAc,CAAC,cAAc,CAAC;IAIlD;;;;;;;OAOG;IACH,uBAAuB,IAAI,IAAI;CA8EhC;AAED;;;;;;;GAOG;AACH,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"}