Add support for Control Protocol V2

[gasperzgonec]

Description

This PR implements the Enhanced Control Protocol V2 for the ADaaS SDK. It introduces a time-value resolution system where the platform sends TimeValue objects describing extraction time boundaries, and the SDK resolves them into concrete ISO 8601 timestamps for the developer. The SDK also tracks extraction boundaries (workers_oldest / workers_newest) in persisted state, enabling windowed and incremental extraction scenarios.

Old Code (Deprecated)

// Previously, re-extraction was all-or-nothing:
const event = createEvent({
  eventContextOverrides: {
    reset_extract_from: true, // Forces complete re-extraction from scratch
    extract_from: '2026-01-01T00:00:00Z',
  },
});

New Code (Recommended)

import { ExtractionTimeDirection, TimeValueType } from '@devrev/adaas-sdk';

// Platform sends TimeValue objects; SDK resolves them automatically.
// Developer just reads the resolved timestamps:
const start = adapter.event.payload.event_context.extraction_start;
const end = adapter.event.payload.event_context.extraction_end;

How It Works

1. Platform sends extraction_start_time and extraction_end_time as TimeValue objects (e.g. { type: "workers_newest" } or { type: "absolute", value: "2026-01-01T00:00:00Z" })
2. SDK resolves these against worker state (workers_oldest, workers_newest) and writes concrete ISO 8601 timestamps to extraction_start and extraction_end
3. Developer reads extraction_start / extraction_end — no awareness of TimeValue needed
4. SDK updates workers_oldest / workers_newest boundaries on extraction completion

Supported TimeValue Types

Type	Resolution
absolute_time	Use the provided ISO 8601 timestamp directly
current_time	Current time
unbounded	undefined — no bound, extract all available
workers_oldest	Oldest extraction timestamp from state
workers_newest	Newest extraction timestamp from state
workers_oldest_minus_window	Subtract duration (e.g. 7d, 2m) from workers_oldest
workers_newest_plus_window	Add duration to workers_newest

Scenario: Initial Import — periodic sync from last known point

// Platform sends:
extraction_start_time: {
  type: TimeValueType.UNBOUNDED;
}
extraction_end_time: {
  type: TimeValueType.CURRENT_TIME;
}

// Developer sees (resolved by SDK):
extraction_start: undefined;
extraction_end: '2026-02-26T15:30:00.000Z'; // current time

Scenario: Normal Import — periodic sync from last known point

// Platform sends:
extraction_start_time: {
  type: TimeValueType.WORKERS_NEWEST;
}
extraction_end_time: {
  type: TimeValueType.CURRENT_TIME;
}

// Developer sees (resolved by SDK):
extraction_start: '2024-06-01T00:00:00.000Z'; // from state
extraction_end: '2026-02-26T15:30:00.000Z'; // current time

Scenario: POC Import — from a specific date to now

// Platform sends:
extraction_start_time: { type: TimeValueType.ABSOLUTE_TIME, value: "2024-01-01T00:00:00Z" }
extraction_end_time: { type: TimeValueType.CURRENT_TIME }

// Developer sees:
extraction_start: "2024-01-01T00:00:00Z"
extraction_end:   "2026-02-26T15:30:00.000Z"

Scenario: Computer Import — historical with window

// Platform sends:
extraction_start_time: { type: TimeValueType.WORKERS_OLDEST_MINUS_WINDOW, value: "7d" }
extraction_end_time: { type: TimeValueType.WORKERS_OLDEST }

// Developer sees (SDK subtracts 7 days from workers_oldest):
extraction_start: "2023-12-25T00:00:00.000Z"
extraction_end:   "2024-01-01T00:00:00.000Z"

Scenario: Reconciliation — specific date range

// Platform sends (as a fork sync unit):
extraction_start_time: { type: TimeValueType.ABSOLUTE_TIME, value: "2026-01-01T00:00:00Z" }
extraction_end_time: { type: TimeValueType.ABSOLUTE_TIME, value: "2026-03-31T23:59:59Z" }

// Developer sees:
extraction_start: "2026-01-01T00:00:00Z"
extraction_end:   "2026-03-31T23:59:59Z"

What's New

• TimeValueType enum + TimeValue interface: New types for platform-to-SDK time communication (7 time value types)
• EventContext: Added extraction_start_time/extraction_end_time (raw TimeValue from platform), and extraction_start/extraction_end (resolved ISO 8601 strings for developers). Deprecated extract_from, reset_extract_from, and updated reset_extraction deprecation message.
• SdkState: Added workers_oldest, workers_newest — SDK manages these automatically
• Resolution logic: New src/common/time-value-resolver.ts with duration parsing (7d, 2m, 1y) and time value resolution against worker state
• Boundary updates: SDK expands workers_oldest/workers_newest on extraction completion based on direction

Connected Issues

• #ISS-260925

Checklist

• Tests added/updated and ran with npm run test OR no tests needed.
• Ran backwards compatibility tests with npm run test:backwards-compatibility.
• Code formatted and checked with npm run lint.
• Tested airdrop-template linked to this PR.
• Documentation updated and provided a link to PR / new docs OR no docs needed.

[GasperSenk]

Is the import { ExtractionTimeDirection, TimeValueType } from '@devrev/adaas-sdk'; a reliquary of the previous proposal?
The idea behind using TimeValue objects is to abstract the directions historical/sync, ... away into concrete timestamps developer should use.

I do have one more question about how and who defines the values that are the source of workers_oldest and workers_newest.

I would like to highlight the edge cases where
If the workers timestamp is set by the modified date in the last returned object.

• We have a potential edge case where the window is smaller than the difference between two successive objects.

If the workers timestamp is defined by the timestamp calculated from the last syncs timestamp +- window.

• There is a potential edge case where the changes in external platform are still buffering and will only be surfaced with modified_date in the past.

It sounds complicated, but it could potentially be solved by saving both the window and work timestamps.

1. And use the work timestamp for the workers_oldest and workers_newest.
2. But when the difference between saved window timestamp and work timestamp is similar to the windows size - which would happen when no works were extracted in the previous sync, advance the workers timestamp by lets say half the window size.
3. If then the next sync extracts changes in the first half of the time window we know there was a problem with record processing in the source system and we have to step back and extract more items.

I know this complicated, but it might be good to first start storing oldest_item, newest_item, oldest_window, newest_window timestamps for each record type in the state, even if we don't use them for now.

[Aakkash-Suresh]

LGTM