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	Use the provided ISO 8601 timestamp directly
now	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.NOW;
}

// 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.NOW;
}

// 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, value: "2024-01-01T00:00:00Z" }
extraction_end_time: { type: TimeValueType.NOW }

// 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, value: "2026-01-01T00:00:00Z" }
extraction_end_time: { type: TimeValueType.ABSOLUTE, 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.