@skedulo/integration-sdk 0.2.4 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## [0.3.0] - 2026-05-21
+
+- **`BaseAdapterHandler`** — 12 standard route handlers (capabilities, setup, metadata, scheduled-pull, run-flow, run-all-flows, on-skedulo-event, on-vendor-event). Subclassing is now optional — `new BaseAdapterHandler({ adapter })` is enough for the common case.
+- **`AdapterRegistry`** auto-built from `adapter.integrationType` — no more hand-wired registries in consumers. `SyncRunner` accepts a registry; `SyncRunner.create()` removed.
+- **Adapter declares its own identity** — required `integrationType` + optional `capabilities` (`roles`, `lookupStrategy`, `allowNewDataFlows`, `hasDataFlows`). Handler derives userAgent and request-source labels from it.
+- **`Adapter.parseChangeEvent(body)`** — vendor change-event envelope parser lives on the adapter; `onVendorEvent` route dispatches via it. No handler subclass needed.
+- **Symmetric event endpoints** — `onSkeduloEvent` (Skedulo→vendor) and `onVendorEvent` (vendor→Skedulo) replace the directional `push`/`onChangeEvent` pair.
+- **`ProxyResult<T> { status, headers, output }`** — `ProxyClient.request<T>()` returns the envelope directly, replacing `unwrapProxy` boilerplate. Adapters can read `status` for stale-mapping detection without try/catch.
+- **`LookupStrategy` enum** (`IdMapping` / `ExternalId`) — replaces hardcoded `"idMapping"` strings.
+- **Upsert harness on `BaseAdapter`** — `runUpsertBatch`, `classifyHttpStatus`, `handleStaleMapping`, default `buildMappingEntries` replace duplicated upsert + stale-mapping logic in every adapter.
+- **`AdapterCapabilities` with `roles`** + `AdapterRoleError` — declarative source/target support so source-only adapters (e.g. Workday) can be modelled cleanly. Defaults to `[SOURCE, TARGET]` for back-compat.
+- **`source.beforeMap` now runs on the event path** in both strategies — payload normalisation lives in the adapter once, not duplicated in route handlers.
+- **`IdMappingSyncStrategy` dispatches `insert`/`update`** when adapters define them (falls back to `upsert` for legacy adapters); strips internal `__targetUID` marker on inserts.
+- **`skeduloAdapter` singleton** with `bootstrap()` / `checkBootstrap()` — no more direct `IdMappingService` usage in consumers.
+- **Testing harness** — `runAdapterContractTests({ createAdapter })` covers `integrationType`, capabilities, default `buildMappingEntries`. `mockProxyResult<T>()` builds `ProxyResult` mocks.
+- Lifted utilities: `unwrapProxy`, `okResponse`, `errorResponse`, `getQueryParam`, `isAdminRequest`, `requireAdmin`, `humanizeFieldName`.
+- New `docs/IMPLEMENTING-AN-INTEGRATION.md` — discovery + implementation guide for new adapters.
+
+## [0.2.4] - 2026-05-14
+
+### Added
+
+- **Delta sync / change detection** — `SyncRunner.run()` now manages the incremental cursor automatically. After each successful run it writes `lastRunAt` back to the integration service via `DataFlowService.updateCursor()`. On the next run, `flow.lastRunAt` is used as the cursor source (overrides `args.since`), with a configurable overlap window (`SyncRunOptions.cursorOverlapMs`, default 60 s) to cover records modified at the tail of the previous run.
+- **`Adapter.isChanged(raw, cursor)`** — optional per-record change gate. Return `false` to skip a record before it enters the pipeline. Takes precedence over `getRecordTimestamp` if both are implemented.
+- **`Adapter.getRecordTimestamp(raw)`** — alternative timestamp-based change gate. Return the record's modification timestamp; the SDK compares it against the effective cursor. Return `null` to treat the record as changed (safe fallback).
+- **`BatchResult.skipped`** — new counter for records excluded by the change detection gate (distinct from `filtered`, which covers `FilterSpec`-based exclusions).
+- **`UpsertOutcome.status: 'precondition'`** — new status for insert pre-condition failures (e.g. a required relation doesn't exist yet in the target system).
+- **`SyncResult.status: 'precondition_failed'`** — corresponding event-driven result status that surfaces a silent insert failure.
+- **`DataFlowClient.updateCursor()` / `DataFlowService.updateCursor()`** — new methods to persist the run cursor to the integration service.
+- **`DataFlow.lastRunAt`** — new field on `DataFlow`: the persisted cursor written by `SyncRunner` after each successful run. `null` means no prior run (full sync).
+- **`SyncRunOptions.cursorOverlapMs`** — configurable overlap buffer (default: `60_000` ms).
+- **`yarn typecheck`** — new script that type-checks both `src/` and `test/` without emitting output.
+
+---
+
+> **⚠️ v0.2.3 is deprecated.** It contains bugs in cursor accumulation and change detection. Upgrade directly to v0.2.4.
+
+---
+
 ## [0.2.2] - 2026-05-13
 
 - Add `hasDataFlows` to `IntegrationCapabilities` and `IdMappingService.checkSchema()` for setup status checks
@@ -14,12 +53,14 @@
 
 ### Added
 
-- **`IdMappingSyncStrategy`** — new sync strategy that resolves cross-system identity via the `IntegrationIdMapping` Skedulo custom object instead of ExternalId fields. 
+- **`IdMappingSyncStrategy`** — new sync strategy that resolves cross-system identity via the `IntegrationIdMapping` Skedulo custom object instead of ExternalId fields.
 
 ## [0.1.2] - 2026-05-08
+
 - Harden `compileFilter` against backtick and expr injection; guard `LOCAL_INTEGRATION_SERVICE` to localhost only; pre-validate filter spec in `_processBatch` to fail fast
 
 ## [0.1.1] - 2026-05-08
+
 - Make SampleRecord generic — each adapter returns native fields
 
 ### Updated
@@ -27,6 +68,7 @@
 ## [0.1.0] - 2026-05-07
 
 ### Added
+
 - Initial package scaffold with TypeScript config, Jest config, and build setup
 - `SyncService` and `SyncRunner` — batch and event-driven sync execution
 - `Adapter` interface — source, target, and metadata roles

package/README.md

@@ -67,6 +67,14 @@ export class MyAdapter extends BaseAdapter {
       const outcomes = ctx.pipeline?.outcomes ?? [];
     }
   }
+
+  // Optional delta sync — implement one of these to enable per-record change detection
+  getRecordTimestamp(raw: Record<string, unknown>): Date | null {
+    const ts = raw['updatedAt'];
+    if (!ts) return null;
+    const d = new Date(String(ts));
+    return isNaN(d.getTime()) ? null : d;
+  }
 }
 ```
 
@@ -76,6 +84,7 @@ See [docs/ADAPTERS.md](./docs/ADAPTERS.md) for the full method reference and lif
 
 ```bash
 yarn build          # Compile TypeScript → dist/
+yarn typecheck      # Type-check src/ and test/ without emitting output
 yarn test           # Run all tests
 yarn test:coverage  # Run tests with coverage
 yarn format         # Format all src/ and test/ files with Prettier

package/dist/adapters/adapter-registry.d.ts

@@ -0,0 +1,9 @@
+import type { Adapter } from '../interfaces/adapter.interface';
+export declare class AdapterRegistry {
+    private readonly adapters;
+    constructor(adapters: Record<string, Adapter>);
+    register(systemName: string, adapter: Adapter): void;
+    entries(): Array<[string, Adapter]>;
+    resolve(system: string | undefined): Adapter;
+}
+//# sourceMappingURL=adapter-registry.d.ts.map

package/dist/adapters/adapter-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-registry.d.ts","sourceRoot":"","sources":["../../src/adapters/adapter-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAC;AAM/D,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0B;gBAEvC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAI7C,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IAIpD,OAAO,IAAI,KAAK,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAInC,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO;CAW7C"}

package/dist/adapters/adapter-registry.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdapterRegistry = void 0;
+// Resolves a system name to its registered Adapter. Consumers register every
+// adapter they want addressable — including the built-in `skeduloAdapter` when
+// needed. Throws an Error with a top-level numeric `.status = 400` for missing
+// or unknown systems — errorResponse() turns that into a 400 response body.
+class AdapterRegistry {
+    constructor(adapters) {
+        this.adapters = Object.assign({}, adapters);
+    }
+    register(systemName, adapter) {
+        this.adapters[systemName] = adapter;
+    }
+    entries() {
+        return Object.entries(this.adapters);
+    }
+    resolve(system) {
+        if (!system)
+            throw httpError(400, 'system is required');
+        const adapter = this.adapters[system];
+        if (!adapter) {
+            throw httpError(400, `Unsupported system: "${system}". Must be one of: ${Object.keys(this.adapters).join(', ')}`);
+        }
+        return adapter;
+    }
+}
+exports.AdapterRegistry = AdapterRegistry;
+function httpError(status, message) {
+    const err = new Error(message);
+    err.status = status;
+    return err;
+}
+//# sourceMappingURL=adapter-registry.js.map

package/dist/adapters/adapter-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-registry.js","sourceRoot":"","sources":["../../src/adapters/adapter-registry.ts"],"names":[],"mappings":";;;AAEA,6EAA6E;AAC7E,+EAA+E;AAC/E,+EAA+E;AAC/E,4EAA4E;AAC5E,MAAa,eAAe;IAG1B,YAAY,QAAiC;QAC3C,IAAI,CAAC,QAAQ,qBAAQ,QAAQ,CAAE,CAAC;IAClC,CAAC;IAED,QAAQ,CAAC,UAAkB,EAAE,OAAgB;QAC3C,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC;IACtC,CAAC;IAED,OAAO;QACL,OAAO,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED,OAAO,CAAC,MAA0B;QAChC,IAAI,CAAC,MAAM;YAAE,MAAM,SAAS,CAAC,GAAG,EAAE,oBAAoB,CAAC,CAAC;QACxD,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACtC,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,SAAS,CACb,GAAG,EACH,wBAAwB,MAAM,sBAAsB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC5F,CAAC;QACJ,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;CACF;AA1BD,0CA0BC;AAED,SAAS,SAAS,CAAC,MAAc,EAAE,OAAe;IAChD,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,OAAO,CAA+B,CAAC;IAC7D,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC;IACpB,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/adapters/base-adapter-handler.d.ts

@@ -0,0 +1,105 @@
+import { LookupStrategy } from '../constants';
+import { type IntegrationContext } from '../context';
+import type { Adapter } from '../interfaces/adapter.interface';
+import { SyncRunner } from '../services/sync-runner';
+import { AdapterRegistry } from './adapter-registry';
+export type RouteHandler = (body: any, headers: any, method: string, path: string, skedContext: any, querystring?: string | Record<string, string> | null) => Promise<{
+    status: number;
+    body?: unknown;
+}>;
+export interface BaseAdapterHandlerConfig {
+    /** The vendor adapter. Its `integrationType` seeds the auto-built registry, userAgent and request sources. */
+    adapter: Adapter;
+    /**
+     * Optional. When omitted the handler builds
+     * `{ [adapter.integrationType]: adapter, skedulo: skeduloAdapter }`.
+     * Provide one only for multi-vendor functions that expose extra adapters.
+     */
+    registry?: AdapterRegistry;
+    /** Default record limit for /sample-records when callers don't specify one. Defaults to 5. */
+    sampleDefaultLimit?: number;
+}
+/**
+ * Base class implementing the 12 standard handler routes every integration
+ * function exposes (capabilities, setup, metadata, scheduled pull, etc.).
+ * Subclass and add the vendor-specific inbound webhook handler — the rest
+ * just works.
+ *
+ * Handlers are arrow-function properties so they can be passed as values
+ * (e.g. into a routes table) without rebinding `this`.
+ *
+ * Override any handler or the protected helpers (`createContext`,
+ * `createRunner`) when a vendor needs different behaviour.
+ */
+export declare class BaseAdapterHandler {
+    protected readonly config: BaseAdapterHandlerConfig;
+    protected readonly requestSources: {
+        admin: string;
+        scheduledPull: string;
+        runFlow: string;
+        skeduloEvent: string;
+        vendorEvent: string;
+    };
+    protected readonly userAgent: string;
+    protected readonly sampleDefaultLimit: number;
+    protected readonly integrationType: string;
+    protected readonly registry: AdapterRegistry;
+    protected readonly lookupStrategy: LookupStrategy;
+    constructor(config: BaseAdapterHandlerConfig);
+    protected createContext(skedContext: unknown, requestSource: string): IntegrationContext;
+    protected createRunner(): SyncRunner;
+    /** GET /capabilities */
+    getCapabilities: RouteHandler;
+    /** GET /setup — reports whether the Skedulo-side schema is bootstrapped. */
+    getSetupStatus: RouteHandler;
+    /** POST /setup — bootstraps the IntegrationIdMapping custom object. Idempotent. */
+    setup: RouteHandler;
+    /** GET /objects?system=<name> */
+    getObjects: RouteHandler;
+    /** GET /fields?system=<name>&object=<objectName> */
+    getFields: RouteHandler;
+    /** GET /templates?system=<name> */
+    getTemplates: RouteHandler;
+    /** GET /sample-apis?system=<name> */
+    getSampleAPIs: RouteHandler;
+    /** GET /sample-records?system=<name>&objectType=<obj>&limit=<n> */
+    getSampleRecords: RouteHandler;
+    /**
+     * POST /scheduled-pull — incremental sync of inbound flows on a schedule.
+     * Runs every active flow with triggerConfig.incremental, in executionOrder.
+     * SDK reads each flow's lastRunAt for the cursor.
+     */
+    scheduledPull: RouteHandler;
+    /**
+     * POST /run-all-flows — runs every active flow from scratch (since=null).
+     * Requires admin. Resets each flow's cursor so a full sync happens regardless
+     * of any previous lastRunAt.
+     */
+    runAllFlows: RouteHandler;
+    /**
+     * POST /run-flow — runs a single flow by ID from scratch. Used by the
+     * "Run now" UI button. Body: { flowId }.
+     */
+    runFlow: RouteHandler;
+    /**
+     * POST /on-skedulo-event — Skedulo triggered-action callback for
+     * OUTBOUND_TRIGGERED flows. Fires when a Skedulo record changes and that
+     * record is the source of a flow that targets the vendor.
+     * Body: { skeduloObject, recordId, operation, payload? }
+     *
+     * Pair: `onVendorEvent` handles the opposite direction (vendor → Skedulo).
+     */
+    onSkeduloEvent: RouteHandler;
+    /**
+     * POST /on-vendor-event — inbound real-time webhook from the vendor system.
+     *
+     * Dispatches via `adapter.parseChangeEvent(body)` — implement that on the
+     * adapter to opt in. Returns 501 if the adapter doesn't implement parsing.
+     *
+     * Envelope shape is vendor-specific, hence the parser lives on the adapter.
+     *
+     * Pair: `onSkeduloEvent` handles the opposite direction (Skedulo → vendor).
+     */
+    onVendorEvent: RouteHandler;
+}
+//# sourceMappingURL=base-adapter-handler.d.ts.map

package/dist/adapters/base-adapter-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-adapter-handler.d.ts","sourceRoot":"","sources":["../../src/adapters/base-adapter-handler.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAA4B,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC/E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAErD,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAKrD,MAAM,MAAM,YAAY,GAAG,CACzB,IAAI,EAAE,GAAG,EACT,OAAO,EAAE,GAAG,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,GAAG,EAChB,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,KACjD,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAEjD,MAAM,WAAW,wBAAwB;IACvC,8GAA8G;IAC9G,OAAO,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,8FAA8F;IAC9F,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAID;;;;;;;;;;;GAWG;AACH,qBAAa,kBAAkB;IAejB,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,wBAAwB;IAb/D,SAAS,CAAC,QAAQ,CAAC,cAAc,EAAE;QACjC,KAAK,EAAE,MAAM,CAAC;QACd,aAAa,EAAE,MAAM,CAAC;QACtB,OAAO,EAAE,MAAM,CAAC;QAChB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IACrC,SAAS,CAAC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IAC9C,SAAS,CAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAC3C,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IAC7C,SAAS,CAAC,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;gBAEnB,MAAM,EAAE,wBAAwB;IAmB/D,SAAS,CAAC,aAAa,CAAC,WAAW,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,GAAG,kBAAkB;IAOxF,SAAS,CAAC,YAAY,IAAI,UAAU;IAMpC,wBAAwB;IACxB,eAAe,EAAE,YAAY,CAE3B;IAEF,4EAA4E;IAC5E,cAAc,EAAE,YAAY,CAQ1B;IAEF,mFAAmF;IACnF,KAAK,EAAE,YAAY,CAQjB;IAIF,iCAAiC;IACjC,UAAU,EAAE,YAAY,CAWtB;IAEF,oDAAoD;IACpD,SAAS,EAAE,YAAY,CAgBrB;IAEF,mCAAmC;IACnC,YAAY,EAAE,YAAY,CAQxB;IAEF,qCAAqC;IACrC,aAAa,EAAE,YAAY,CAQzB;IAEF,mEAAmE;IACnE,gBAAgB,EAAE,YAAY,CAsB5B;IAIF;;;;OAIG;IACH,aAAa,EAAE,YAAY,CAiDzB;IAEF;;;;OAIG;IACH,WAAW,EAAE,YAAY,CAqEvB;IAEF;;;OAGG;IACH,OAAO,EAAE,YAAY,CA6BnB;IAEF;;;;;;;OAOG;IACH,cAAc,EAAE,YAAY,CAuC1B;IAEF;;;;;;;;;OASG;IACH,aAAa,EAAE,YAAY,CAsCzB;CACH"}

package/dist/adapters/base-adapter-handler.js

@@ -0,0 +1,379 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseAdapterHandler = void 0;
+const crypto_1 = require("crypto");
+const constants_1 = require("../constants");
+const context_1 = require("../context");
+const sync_runner_1 = require("../services/sync-runner");
+const helpers_1 = require("../utils/helpers");
+const adapter_registry_1 = require("./adapter-registry");
+const skedulo_adapter_1 = require("./skedulo.adapter");
+const DEFAULT_SAMPLE_LIMIT = 5;
+/**
+ * Base class implementing the 12 standard handler routes every integration
+ * function exposes (capabilities, setup, metadata, scheduled pull, etc.).
+ * Subclass and add the vendor-specific inbound webhook handler — the rest
+ * just works.
+ *
+ * Handlers are arrow-function properties so they can be passed as values
+ * (e.g. into a routes table) without rebinding `this`.
+ *
+ * Override any handler or the protected helpers (`createContext`,
+ * `createRunner`) when a vendor needs different behaviour.
+ */
+class BaseAdapterHandler {
+    constructor(config) {
+        var _a, _c, _d, _e;
+        this.config = config;
+        // ── Admin ──────────────────────────────────────────────────────────────────
+        /** GET /capabilities */
+        this.getCapabilities = async () => {
+            return { status: 200, body: this.config.adapter.capabilities };
+        };
+        /** GET /setup — reports whether the Skedulo-side schema is bootstrapped. */
+        this.getSetupStatus = async (_b, _h, _m, _p, skedContext) => {
+            try {
+                const ctx = this.createContext(skedContext, this.requestSources.admin);
+                const status = await skedulo_adapter_1.skeduloAdapter.checkBootstrap(ctx);
+                return { status: 200, body: status };
+            }
+            catch (err) {
+                return (0, helpers_1.errorResponse)(err);
+            }
+        };
+        /** POST /setup — bootstraps the IntegrationIdMapping custom object. Idempotent. */
+        this.setup = async (_b, _h, _m, _p, skedContext) => {
+            try {
+                const ctx = this.createContext(skedContext, this.requestSources.admin);
+                await skedulo_adapter_1.skeduloAdapter.bootstrap(ctx);
+                return (0, helpers_1.okResponse)('Setup complete', { schema: this.integrationType });
+            }
+            catch (err) {
+                return (0, helpers_1.errorResponse)(err);
+            }
+        };
+        // ── Metadata (drives the mapping editor UI) ────────────────────────────────
+        /** GET /objects?system=<name> */
+        this.getObjects = async (_b, _h, _m, _p, skedContext, querystring) => {
+            var _a;
+            try {
+                const system = (_a = (0, helpers_1.getQueryParam)(querystring, 'system')) !== null && _a !== void 0 ? _a : this.integrationType;
+                const adapter = this.registry.resolve(system);
+                const objects = await adapter.getObjects(this.createContext(skedContext, this.requestSources.admin));
+                return { status: 200, body: { system, objects } };
+            }
+            catch (err) {
+                return (0, helpers_1.errorResponse)(err);
+            }
+        };
+        /** GET /fields?system=<name>&object=<objectName> */
+        this.getFields = async (_b, _h, _m, _p, skedContext, querystring) => {
+            var _a;
+            try {
+                const system = (_a = (0, helpers_1.getQueryParam)(querystring, 'system')) !== null && _a !== void 0 ? _a : this.integrationType;
+                const objectName = (0, helpers_1.getQueryParam)(querystring, 'object');
+                if (!objectName)
+                    return { status: 400, body: { message: 'object query parameter is required' } };
+                const adapter = this.registry.resolve(system);
+                const fields = await adapter.getFields(this.createContext(skedContext, this.requestSources.admin), objectName);
+                return { status: 200, body: { system, object: objectName, fields } };
+            }
+            catch (err) {
+                return (0, helpers_1.errorResponse)(err);
+            }
+        };
+        /** GET /templates?system=<name> */
+        this.getTemplates = async (_b, _h, _m, _p, _ctx, querystring) => {
+            var _a, _c, _d, _e;
+            try {
+                const system = (_a = (0, helpers_1.getQueryParam)(querystring, 'system')) !== null && _a !== void 0 ? _a : this.integrationType;
+                const templates = (_e = (await ((_d = (_c = this.registry.resolve(system)).getTemplates) === null || _d === void 0 ? void 0 : _d.call(_c)))) !== null && _e !== void 0 ? _e : [];
+                return { status: 200, body: { templates } };
+            }
+            catch (err) {
+                return (0, helpers_1.errorResponse)(err);
+            }
+        };
+        /** GET /sample-apis?system=<name> */
+        this.getSampleAPIs = async (_b, _h, _m, _p, _ctx, querystring) => {
+            var _a, _c, _d, _e;
+            try {
+                const system = (_a = (0, helpers_1.getQueryParam)(querystring, 'system')) !== null && _a !== void 0 ? _a : this.integrationType;
+                const apis = (_e = (_d = (_c = this.registry.resolve(system)).getSampleAPIs) === null || _d === void 0 ? void 0 : _d.call(_c)) !== null && _e !== void 0 ? _e : [];
+                return { status: 200, body: { apis } };
+            }
+            catch (err) {
+                return (0, helpers_1.errorResponse)(err);
+            }
+        };
+        /** GET /sample-records?system=<name>&objectType=<obj>&limit=<n> */
+        this.getSampleRecords = async (_b, _h, _m, _p, skedContext, querystring) => {
+            var _a, _c;
+            try {
+                const system = (_a = (0, helpers_1.getQueryParam)(querystring, 'system')) !== null && _a !== void 0 ? _a : this.integrationType;
+                const objectType = (0, helpers_1.getQueryParam)(querystring, 'objectType');
+                if (!objectType)
+                    return { status: 400, body: { message: 'objectType query parameter is required' } };
+                const limit = Number((_c = (0, helpers_1.getQueryParam)(querystring, 'limit')) !== null && _c !== void 0 ? _c : this.sampleDefaultLimit);
+                if (!Number.isInteger(limit) || limit <= 0) {
+                    return { status: 400, body: { message: 'limit must be a positive integer' } };
+                }
+                const adapter = this.registry.resolve(system);
+                const records = await adapter.fetchSampleRecords(this.createContext(skedContext, this.requestSources.runFlow), objectType, [], limit);
+                return { status: 200, body: { records } };
+            }
+            catch (err) {
+                return (0, helpers_1.errorResponse)(err);
+            }
+        };
+        // ── Sync ───────────────────────────────────────────────────────────────────
+        /**
+         * POST /scheduled-pull — incremental sync of inbound flows on a schedule.
+         * Runs every active flow with triggerConfig.incremental, in executionOrder.
+         * SDK reads each flow's lastRunAt for the cursor.
+         */
+        this.scheduledPull = async (_b, _h, _m, _p, skedContext) => {
+            try {
+                const ctx = this.createContext(skedContext, this.requestSources.scheduledPull);
+                const allInbound = await ctx.dataFlowService.listActive({
+                    integrationType: this.integrationType,
+                    targetSystem: 'skedulo',
+                });
+                const flows = allInbound
+                    .filter((f) => { var _a; return (_a = f.triggerConfig) === null || _a === void 0 ? void 0 : _a.incremental; })
+                    .sort((a, b) => { var _a, _c; return ((_a = a.executionOrder) !== null && _a !== void 0 ? _a : Infinity) - ((_c = b.executionOrder) !== null && _c !== void 0 ? _c : Infinity); });
+                if (flows.length === 0) {
+                    ctx.logger.info(`[scheduled-pull] no active incremental flows for ${this.integrationType}`);
+                    return (0, helpers_1.okResponse)('No active flows', { processed: 0 });
+                }
+                const runner = this.createRunner();
+                const results = {};
+                for (const flow of flows) {
+                    const startedAt = Date.now();
+                    try {
+                        const stats = await runner.run({
+                            flowId: flow.id,
+                            since: null,
+                            sourceSystem: this.integrationType,
+                            targetSystem: 'skedulo',
+                            options: { lookupStrategy: this.lookupStrategy },
+                        }, ctx);
+                        const durationMs = Date.now() - startedAt;
+                        ctx.logger.info(`[scheduled-pull] flow=${flow.id} ${flow.sourceObject}→${flow.targetObject} ` +
+                            `${JSON.stringify(stats)} took=${durationMs}ms`);
+                        results[flow.id] = Object.assign(Object.assign({}, stats), { durationMs });
+                    }
+                    catch (err) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        ctx.logger.error(`[scheduled-pull] flow=${flow.id} failed: ${msg}`);
+                        results[flow.id] = { error: msg };
+                    }
+                }
+                return (0, helpers_1.okResponse)('Scheduled pull tick complete', { processed: flows.length, results });
+            }
+            catch (err) {
+                return (0, helpers_1.errorResponse)(err);
+            }
+        };
+        /**
+         * POST /run-all-flows — runs every active flow from scratch (since=null).
+         * Requires admin. Resets each flow's cursor so a full sync happens regardless
+         * of any previous lastRunAt.
+         */
+        this.runAllFlows = async (_b, _h, _m, _p, skedContext) => {
+            var _a, _c, _d, _e;
+            try {
+                const denied = (0, helpers_1.requireAdmin)(skedContext, 'runAllFlows');
+                if (denied)
+                    return denied;
+                const ctx = this.createContext(skedContext, this.requestSources.admin);
+                const flows = await ctx.dataFlowService.listActive({
+                    integrationType: this.integrationType,
+                });
+                if (flows.length === 0) {
+                    return {
+                        status: 503,
+                        body: {
+                            message: `No active data flows found for ${this.integrationType}. Create flows first.`,
+                        },
+                    };
+                }
+                ctx.logger.info(`[run-all-flows] found ${flows.length} active flow(s): ` +
+                    flows.map((f) => `${f.sourceObject}→${f.targetObject}`).join(', '));
+                const sorted = [...flows].sort((a, b) => { var _a, _c; return ((_a = a.executionOrder) !== null && _a !== void 0 ? _a : Infinity) - ((_c = b.executionOrder) !== null && _c !== void 0 ? _c : Infinity); });
+                const runner = this.createRunner();
+                const results = {};
+                for (const flow of sorted) {
+                    if (!((_c = (_a = flow.mappingConfig) === null || _a === void 0 ? void 0 : _a.mappings) === null || _c === void 0 ? void 0 : _c.length)) {
+                        ctx.logger.warn(`[run-all-flows] skipping flow ${flow.id} (${flow.sourceObject}) — no mappingConfig`);
+                        results[String(flow.id)] = {
+                            flowId: flow.id,
+                            sourceObject: flow.sourceObject,
+                            targetObject: flow.targetObject,
+                            skipped: true,
+                            reason: 'no mappingConfig',
+                        };
+                        continue;
+                    }
+                    // Reset cursor so the SDK treats this as a full sync regardless of any prior lastRunAt.
+                    await ctx.dataFlowService.updateCursor(flow.id, null);
+                    ctx.logger.info(`[run-all-flows] syncing ${flow.sourceObject} → ${flow.targetObject}`);
+                    const stats = await runner.run({
+                        flowId: flow.id,
+                        since: null,
+                        sourceSystem: (_d = flow.sourceSystem) !== null && _d !== void 0 ? _d : this.integrationType,
+                        targetSystem: (_e = flow.targetSystem) !== null && _e !== void 0 ? _e : 'skedulo',
+                        options: { lookupStrategy: this.lookupStrategy },
+                    }, ctx);
+                    results[String(flow.id)] = Object.assign({ flowId: flow.id, sourceObject: flow.sourceObject, targetObject: flow.targetObject }, stats);
+                }
+                return (0, helpers_1.okResponse)('All flows completed successfully', { results });
+            }
+            catch (err) {
+                return (0, helpers_1.errorResponse)(err);
+            }
+        };
+        /**
+         * POST /run-flow — runs a single flow by ID from scratch. Used by the
+         * "Run now" UI button. Body: { flowId }.
+         */
+        this.runFlow = async (body, _h, _m, _p, skedContext) => {
+            var _a, _c;
+            try {
+                const denied = (0, helpers_1.requireAdmin)(skedContext, 'runFlow');
+                if (denied)
+                    return denied;
+                const { flowId } = (body !== null && body !== void 0 ? body : {});
+                if (!flowId)
+                    return { status: 400, body: { message: 'flowId is required' } };
+                const runId = (0, crypto_1.randomUUID)();
+                const ctx = this.createContext(skedContext, this.requestSources.runFlow);
+                const flow = await ctx.dataFlowService.getFlowById(flowId);
+                if (!flow)
+                    return { status: 404, body: { message: `Flow ${flowId} not found` } };
+                ctx.logger.info(`[run-flow] flowId=${flowId} runId=${runId} starting`);
+                const stats = await this.createRunner().run({
+                    flowId,
+                    since: null,
+                    sourceSystem: (_a = flow.sourceSystem) !== null && _a !== void 0 ? _a : this.integrationType,
+                    targetSystem: (_c = flow.targetSystem) !== null && _c !== void 0 ? _c : 'skedulo',
+                    options: { lookupStrategy: this.lookupStrategy },
+                }, ctx);
+                ctx.logger.info(`[run-flow] done: ${JSON.stringify(stats)}`);
+                return { status: 200, body: Object.assign({ runId, flowId }, stats) };
+            }
+            catch (err) {
+                return (0, helpers_1.errorResponse)(err);
+            }
+        };
+        /**
+         * POST /on-skedulo-event — Skedulo triggered-action callback for
+         * OUTBOUND_TRIGGERED flows. Fires when a Skedulo record changes and that
+         * record is the source of a flow that targets the vendor.
+         * Body: { skeduloObject, recordId, operation, payload? }
+         *
+         * Pair: `onVendorEvent` handles the opposite direction (vendor → Skedulo).
+         */
+        this.onSkeduloEvent = async (body, _h, _m, _p, skedContext) => {
+            var _a;
+            try {
+                const { skeduloObject, recordId, operation } = (body !== null && body !== void 0 ? body : {});
+                if (!skeduloObject || !recordId || !operation) {
+                    return {
+                        status: 400,
+                        body: { message: 'Missing required fields: skeduloObject, recordId, operation' },
+                    };
+                }
+                if (operation !== 'INSERT' && operation !== 'UPDATE' && operation !== 'DELETE') {
+                    return { status: 400, body: { message: `Unsupported operation: ${operation}` } };
+                }
+                const ctx = this.createContext(skedContext, this.requestSources.skeduloEvent);
+                const results = await this.createRunner().handleEvent({
+                    event: {
+                        integrationType: this.integrationType,
+                        objectType: skeduloObject,
+                        operation,
+                        recordId,
+                        payload: (_a = body === null || body === void 0 ? void 0 : body.payload) !== null && _a !== void 0 ? _a : {},
+                    },
+                    options: { lookupStrategy: this.lookupStrategy },
+                }, ctx);
+                if (results.some((r) => r.status === 'failed')) {
+                    return { status: 502, body: { message: 'Skedulo event processing failed', results } };
+                }
+                return (0, helpers_1.okResponse)('Skedulo event processed', { results });
+            }
+            catch (err) {
+                return (0, helpers_1.errorResponse)(err);
+            }
+        };
+        /**
+         * POST /on-vendor-event — inbound real-time webhook from the vendor system.
+         *
+         * Dispatches via `adapter.parseChangeEvent(body)` — implement that on the
+         * adapter to opt in. Returns 501 if the adapter doesn't implement parsing.
+         *
+         * Envelope shape is vendor-specific, hence the parser lives on the adapter.
+         *
+         * Pair: `onSkeduloEvent` handles the opposite direction (Skedulo → vendor).
+         */
+        this.onVendorEvent = async (body, _h, _m, _p, skedContext) => {
+            try {
+                const adapter = this.config.adapter;
+                if (!adapter.parseChangeEvent) {
+                    return {
+                        status: 501,
+                        body: { message: `${this.integrationType} adapter does not implement parseChangeEvent` },
+                    };
+                }
+                const parsed = adapter.parseChangeEvent(body);
+                if ('error' in parsed)
+                    return { status: 400, body: { message: parsed.error } };
+                const ctx = this.createContext(skedContext, this.requestSources.vendorEvent);
+                const results = await this.createRunner().handleEvent({ event: parsed.event, options: { lookupStrategy: this.lookupStrategy } }, ctx);
+                if (results.some((r) => r.status === 'precondition_failed')) {
+                    return {
+                        status: 412,
+                        body: {
+                            message: 'Integration not bootstrapped — run /setup then /run-all-flows',
+                            results,
+                        },
+                    };
+                }
+                if (results.some((r) => r.status === 'failed')) {
+                    return { status: 502, body: { message: 'Event processing failed', results } };
+                }
+                return (0, helpers_1.okResponse)(`${parsed.event.objectType} ${parsed.event.operation.toLowerCase()} processed`, { results });
+            }
+            catch (err) {
+                return (0, helpers_1.errorResponse)(err);
+            }
+        };
+        this.integrationType = config.adapter.integrationType;
+        const t = this.integrationType;
+        this.requestSources = {
+            admin: `${t}-admin`,
+            scheduledPull: `${t}-scheduled-pull`,
+            runFlow: `${t}-run-flow`,
+            skeduloEvent: `${t}-skedulo-event`,
+            vendorEvent: `${t}-vendor-event`,
+        };
+        this.userAgent = `${t}-function`;
+        this.sampleDefaultLimit = (_a = config.sampleDefaultLimit) !== null && _a !== void 0 ? _a : DEFAULT_SAMPLE_LIMIT;
+        this.registry =
+            (_c = config.registry) !== null && _c !== void 0 ? _c : new adapter_registry_1.AdapterRegistry({ [t]: config.adapter, skedulo: skedulo_adapter_1.skeduloAdapter });
+        this.lookupStrategy = (_e = (_d = config.adapter.capabilities) === null || _d === void 0 ? void 0 : _d.lookupStrategy) !== null && _e !== void 0 ? _e : constants_1.LookupStrategy.ExternalId;
+    }
+    // ── Protected helpers (override to customize) ──────────────────────────────
+    createContext(skedContext, requestSource) {
+        return (0, context_1.createIntegrationContext)(skedContext, this.integrationType, {
+            requestSource,
+            userAgent: this.userAgent,
+        });
+    }
+    createRunner() {
+        return new sync_runner_1.SyncRunner(this.registry);
+    }
+}
+exports.BaseAdapterHandler = BaseAdapterHandler;
+//# sourceMappingURL=base-adapter-handler.js.map