@trayio/cdk-runtime 5.21.0 → 5.22.0-unstable

package/dist/connector/operation/CompositeOperationExecution.d.ts

@@ -2,12 +2,17 @@ import { OperationHandlerAuth, OperationHandlerContext, OperationHandlerResult,
 import { CompositeOperationHandler } from '@trayio/cdk-dsl/connector/operation/CompositeOperationHandler';
 import AbstractOperationExecution from './AbstractOperationExecution';
 import { OperationHandlerInvocationFactory } from './OperationHandlerInvocationFactory';
+import { PollingServiceClient } from '../polling/PollingServiceClient';
 export declare class CompositeOperationExecution<AUTH extends OperationHandlerAuth<unknown, unknown>, IN, OUT> extends AbstractOperationExecution<AUTH, IN, OUT> {
     private handlerInvocationFactory;
     private handler;
     handlerType: OperationHandlerType;
-    constructor(handlerInvocationFactory: OperationHandlerInvocationFactory, handler: CompositeOperationHandler<AUTH, IN, OUT>, handlerType: OperationHandlerType);
+    private operationName;
+    private pollingServiceClient;
+    constructor(handlerInvocationFactory: OperationHandlerInvocationFactory, handler: CompositeOperationHandler<AUTH, IN, OUT>, handlerType: OperationHandlerType, operationName: string, pollingServiceClient: PollingServiceClient);
     execute(ctx: OperationHandlerContext<AUTH>, input: IN): Promise<OperationHandlerResult<OUT>>;
+    private executePollingLifecycle;
+    private mapCaughtError;
     private isError;
 }
 //# sourceMappingURL=CompositeOperationExecution.d.ts.map

package/dist/connector/operation/CompositeOperationExecution.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CompositeOperationExecution.d.ts","sourceRoot":"","sources":["../../../src/connector/operation/CompositeOperationExecution.ts"],"names":[],"mappings":"AAEA,OAAO,EACN,oBAAoB,EACpB,uBAAuB,EACvB,sBAAsB,EAEtB,oBAAoB,EACpB,MAAM,sDAAsD,CAAC;AAC9D,OAAO,EAAE,yBAAyB,EAAE,MAAM,+DAA+D,CAAC;AAE1G,OAAO,0BAA0B,MAAM,8BAA8B,CAAC;AACtE,OAAO,EAAE,iCAAiC,EAAE,MAAM,qCAAqC,CAAC;AAExF,qBAAa,2BAA2B,CACvC,IAAI,SAAS,oBAAoB,CAAC,OAAO,EAAE,OAAO,CAAC,EACnD,EAAE,EACF,GAAG,CACF,SAAQ,0BAA0B,CAAC,IAAI,EAAE,EAAE,EAAE,GAAG,CAAC;IAClD,OAAO,CAAC,wBAAwB,CAAoC;IACpE,OAAO,CAAC,OAAO,CAA2C;IAC1D,WAAW,EAAE,oBAAoB,CAAC;gBAGjC,wBAAwB,EAAE,iCAAiC,EAC3D,OAAO,EAAE,yBAAyB,CAAC,IAAI,EAAE,EAAE,EAAE,GAAG,CAAC,EACjD,WAAW,EAAE,oBAAoB;IAQ5B,OAAO,CACZ,GAAG,EAAE,uBAAuB,CAAC,IAAI,CAAC,EAClC,KAAK,EAAE,EAAE,GACP,OAAO,CAAC,sBAAsB,CAAC,GAAG,CAAC,CAAC;IAgCvC,OAAO,CAAC,OAAO;CAQf"}
+{"version":3,"file":"CompositeOperationExecution.d.ts","sourceRoot":"","sources":["../../../src/connector/operation/CompositeOperationExecution.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,oBAAoB,EACpB,uBAAuB,EAEvB,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,sDAAsD,CAAC;AAC9D,OAAO,EAAE,yBAAyB,EAAE,MAAM,+DAA+D,CAAC;AAE1G,OAAO,0BAA0B,MAAM,8BAA8B,CAAC;AACtE,OAAO,EAAE,iCAAiC,EAAE,MAAM,qCAAqC,CAAC;AACxF,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAQvE,qBAAa,2BAA2B,CACvC,IAAI,SAAS,oBAAoB,CAAC,OAAO,EAAE,OAAO,CAAC,EACnD,EAAE,EACF,GAAG,CACF,SAAQ,0BAA0B,CAAC,IAAI,EAAE,EAAE,EAAE,GAAG,CAAC;IAClD,OAAO,CAAC,wBAAwB,CAAoC;IACpE,OAAO,CAAC,OAAO,CAA2C;IAC1D,WAAW,EAAE,oBAAoB,CAAC;IAClC,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,oBAAoB,CAAuB;gBAGlD,wBAAwB,EAAE,iCAAiC,EAC3D,OAAO,EAAE,yBAAyB,CAAC,IAAI,EAAE,EAAE,EAAE,GAAG,CAAC,EACjD,WAAW,EAAE,oBAAoB,EACjC,aAAa,EAAE,MAAM,EACrB,oBAAoB,EAAE,oBAAoB;IAUrC,OAAO,CACZ,GAAG,EAAE,uBAAuB,CAAC,IAAI,CAAC,EAClC,KAAK,EAAE,EAAE,GACP,OAAO,CAAC,sBAAsB,CAAC,GAAG,CAAC,CAAC;YAgCzB,uBAAuB;IAuBrC,OAAO,CAAC,cAAc;IAmBtB,OAAO,CAAC,OAAO;CAQf"}

package/dist/connector/operation/CompositeOperationExecution.js

@@ -6,17 +6,35 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CompositeOperationExecution = void 0;
 const OperationHandler_1 = require("@trayio/cdk-dsl/connector/operation/OperationHandler");
 const AbstractOperationExecution_1 = __importDefault(require("./AbstractOperationExecution"));
+const CompositeOperationExecutionPolling_1 = require("./CompositeOperationExecutionPolling");
 class CompositeOperationExecution extends AbstractOperationExecution_1.default {
     handlerInvocationFactory;
     handler;
     handlerType;
-    constructor(handlerInvocationFactory, handler, handlerType) {
+    operationName;
+    pollingServiceClient;
+    constructor(handlerInvocationFactory, handler, handlerType, operationName, pollingServiceClient) {
         super();
         this.handlerInvocationFactory = handlerInvocationFactory;
         this.handler = handler;
         this.handlerType = handlerType;
+        this.operationName = operationName;
+        this.pollingServiceClient = pollingServiceClient;
     }
     async execute(ctx, input) {
+        if ((0, CompositeOperationExecutionPolling_1.isPollingLifecycle)(this.handlerType)) {
+            return this.executePollingLifecycle(ctx, input);
+        }
+        if (this.handlerType === OperationHandler_1.OperationHandlerType.TriggerPollDedup) {
+            return (0, CompositeOperationExecutionPolling_1.runTriggerPollDedup)({
+                ctx,
+                input,
+                handler: this.handler,
+                handlerInvocationFactory: this.handlerInvocationFactory,
+                validateOperationResponse: (r) => this.validateOperationResponse(r),
+                mapCaughtError: (e) => this.mapCaughtError(e),
+            });
+        }
         const handlerInvocation = this.handlerInvocationFactory(ctx);
         try {
             const result = await this.handler.handlerFunction(ctx, input, handlerInvocation);
@@ -24,14 +42,33 @@ class CompositeOperationExecution extends AbstractOperationExecution_1.default {
             return result;
         }
         catch (error) {
-            if (this.isError(error)) {
-                return OperationHandler_1.OperationHandlerResult.failure(OperationHandler_1.OperationHandlerError.connectorError(error.message));
-            }
-            if (typeof error === 'string') {
-                return OperationHandler_1.OperationHandlerResult.failure(OperationHandler_1.OperationHandlerError.connectorError(error));
-            }
-            return OperationHandler_1.OperationHandlerResult.failure(OperationHandler_1.OperationHandlerError.connectorError('Operation failed with unknown error'));
+            return this.mapCaughtError(error);
+        }
+    }
+    async executePollingLifecycle(ctx, input) {
+        try {
+            const pollingInput = (input ?? {});
+            await (0, CompositeOperationExecutionPolling_1.runPollingRegisterOrDeregister)({
+                ctx,
+                handlerType: this.handlerType,
+                operationName: this.operationName,
+                pollingInput,
+                pollingServiceClient: this.pollingServiceClient,
+            });
+            return OperationHandler_1.OperationHandlerResult.success({});
+        }
+        catch (error) {
+            return this.mapCaughtError(error);
+        }
+    }
+    mapCaughtError(error) {
+        if (this.isError(error)) {
+            return OperationHandler_1.OperationHandlerResult.failure(OperationHandler_1.OperationHandlerError.connectorError(error.message));
+        }
+        if (typeof error === 'string') {
+            return OperationHandler_1.OperationHandlerResult.failure(OperationHandler_1.OperationHandlerError.connectorError(error));
         }
+        return OperationHandler_1.OperationHandlerResult.failure(OperationHandler_1.OperationHandlerError.connectorError('Operation failed with unknown error'));
     }
     // TODO: Move to commons
     isError(error) {

package/dist/connector/operation/CompositeOperationExecution.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=CompositeOperationExecution.unit.test.d.ts.map

package/dist/connector/operation/CompositeOperationExecution.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CompositeOperationExecution.unit.test.d.ts","sourceRoot":"","sources":["../../../src/connector/operation/CompositeOperationExecution.unit.test.ts"],"names":[],"mappings":""}

package/dist/connector/operation/CompositeOperationExecution.unit.test.js

@@ -0,0 +1,276 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const OperationHandler_1 = require("@trayio/cdk-dsl/connector/operation/OperationHandler");
+const CompositeOperationHandler_1 = require("@trayio/cdk-dsl/connector/operation/CompositeOperationHandler");
+const PollingTypes_1 = require("@trayio/cdk-dsl/connector/operation/PollingTypes");
+const CompositeOperationExecution_1 = require("./CompositeOperationExecution");
+const noopHandlerInvocationFactory = () => (() => undefined);
+const fakePollingContext = () => ({
+    auth: {
+        authType: 'TOKEN',
+        authId: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
+        user: {},
+        app: {},
+    },
+    connectorName: 'salesforce',
+    connectorVersion: '7.2.0',
+    executionToken: 'exec-jwt',
+    publicUrl: 'https://trigger.example.test/tab-123',
+    organizationId: 'org-uuid',
+    workspaceId: 'ws-uuid',
+    projectId: '7fa00000-1111-2222-3333-444455556666',
+});
+const createFakePollingServiceClient = () => {
+    const registerCalls = [];
+    const deregisterCalls = [];
+    const client = {
+        register: jest.fn((payload, token) => {
+            registerCalls.push([payload, token]);
+            return Promise.resolve();
+        }),
+        deregister: jest.fn((payload, token) => {
+            deregisterCalls.push([payload, token]);
+            return Promise.resolve();
+        }),
+    };
+    return { client, registerCalls, deregisterCalls };
+};
+describe('CompositeOperationExecution polling lifecycle branch', () => {
+    it('calls PollingServiceClient.register with ctx + input fields on TriggerPollCreate, never invoking handlerFunction', async () => {
+        const { client, registerCalls } = createFakePollingServiceClient();
+        const handlerFunction = jest.fn();
+        const handler = new CompositeOperationHandler_1.CompositeOperationHandler(handlerFunction);
+        const execution = new CompositeOperationExecution_1.CompositeOperationExecution(noopHandlerInvocationFactory, handler, OperationHandler_1.OperationHandlerType.TriggerPollCreate, 'new_records_poll', client);
+        const input = {
+            pollingInterval: { value: 15, unit: PollingTypes_1.PollingIntervalUnit.Minutes },
+            maxFailureCount: 50,
+            initialCursor: { since: 't0' },
+        };
+        const result = await execution.execute(fakePollingContext(), input);
+        expect(result.isSuccess).toBe(true);
+        expect(handlerFunction).not.toHaveBeenCalled();
+        expect(registerCalls).toHaveLength(1);
+        const [payload, token] = registerCalls[0];
+        expect(payload).toEqual({
+            connectorName: 'salesforce',
+            connectorVersion: '7.2.0',
+            registeredHandlerName: 'new_records_poll',
+            authenticationId: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
+            organizationId: 'org-uuid',
+            workspaceId: 'ws-uuid',
+            projectId: '7fa00000-1111-2222-3333-444455556666',
+            publicUrl: 'https://trigger.example.test/tab-123',
+            pollingInterval: {
+                value: 15,
+                unit: PollingTypes_1.PollingIntervalUnit.Minutes,
+            },
+            maxFailureCount: 50,
+            initialCursor: { since: 't0' },
+        });
+        expect(token).toBe('exec-jwt');
+    });
+    it('calls PollingServiceClient.deregister on TriggerPollDestroy, never invoking handlerFunction', async () => {
+        const { client, deregisterCalls } = createFakePollingServiceClient();
+        const handlerFunction = jest.fn();
+        const handler = new CompositeOperationHandler_1.CompositeOperationHandler(handlerFunction);
+        const execution = new CompositeOperationExecution_1.CompositeOperationExecution(noopHandlerInvocationFactory, handler, OperationHandler_1.OperationHandlerType.TriggerPollDestroy, 'new_records_poll_destroy', client);
+        const result = await execution.execute(fakePollingContext(), {});
+        expect(result.isSuccess).toBe(true);
+        expect(handlerFunction).not.toHaveBeenCalled();
+        expect(deregisterCalls).toHaveLength(1);
+        const [payload, token] = deregisterCalls[0];
+        expect(payload).toEqual({
+            connectorName: 'salesforce',
+            connectorVersion: '7.2.0',
+            registeredHandlerName: 'new_records_poll_destroy',
+            publicUrl: 'https://trigger.example.test/tab-123',
+            preserveCursor: true,
+        });
+        expect(token).toBe('exec-jwt');
+    });
+    it('surfaces a consolidated failure listing every missing ctx field on register', async () => {
+        const { client, registerCalls } = createFakePollingServiceClient();
+        const handler = new CompositeOperationHandler_1.CompositeOperationHandler(jest.fn());
+        const execution = new CompositeOperationExecution_1.CompositeOperationExecution(noopHandlerInvocationFactory, handler, OperationHandler_1.OperationHandlerType.TriggerPollCreate, 'new_records_poll', client);
+        const result = await execution.execute({}, {});
+        expect(registerCalls).toHaveLength(0);
+        expect(result.isFailure).toBe(true);
+        const error = result._tag === 'Failure' ? result.error.message : '';
+        expect(error).toMatch(/ctx\.connectorName/);
+        expect(error).toMatch(/ctx\.connectorVersion/);
+        expect(error).toMatch(/ctx\.executionToken/);
+        expect(error).toMatch(/ctx\.publicUrl/);
+    });
+    it('fails register when the auth/org/workspace/project ctx fields are missing', async () => {
+        const { client, registerCalls } = createFakePollingServiceClient();
+        const handler = new CompositeOperationHandler_1.CompositeOperationHandler(jest.fn());
+        const execution = new CompositeOperationExecution_1.CompositeOperationExecution(noopHandlerInvocationFactory, handler, OperationHandler_1.OperationHandlerType.TriggerPollCreate, 'new_records_poll', client);
+        // Base polling ctx is present, but the identity fields the PS register
+        // payload requires are not.
+        const incompleteCtx = {
+            connectorName: 'x',
+            connectorVersion: '1',
+            executionToken: 'tok',
+            publicUrl: 'u',
+        };
+        const result = await execution.execute(incompleteCtx, {});
+        expect(registerCalls).toHaveLength(0);
+        expect(result.isFailure).toBe(true);
+        const error = result._tag === 'Failure' ? result.error.message : '';
+        expect(error).toMatch(/ctx\.auth\.authId/);
+        expect(error).toMatch(/ctx\.organizationId/);
+        expect(error).toMatch(/ctx\.workspaceId/);
+        expect(error).toMatch(/ctx\.projectId/);
+    });
+    it('deregister does NOT require the register-only ctx fields', async () => {
+        const { client, deregisterCalls } = createFakePollingServiceClient();
+        const handler = new CompositeOperationHandler_1.CompositeOperationHandler(jest.fn());
+        const execution = new CompositeOperationExecution_1.CompositeOperationExecution(noopHandlerInvocationFactory, handler, OperationHandler_1.OperationHandlerType.TriggerPollDestroy, 'new_records_poll_destroy', client);
+        // Only the base four ctx fields; auth / org / workspace / project absent.
+        const destroyOnlyCtx = {
+            connectorName: 'x',
+            connectorVersion: '1',
+            executionToken: 'tok',
+            publicUrl: 'u',
+        };
+        const result = await execution.execute(destroyOnlyCtx, {});
+        expect(result.isSuccess).toBe(true);
+        expect(deregisterCalls).toHaveLength(1);
+    });
+    it('maps a PollingServiceClient error into an OperationHandlerResult failure', async () => {
+        const client = {
+            register: jest.fn(() => Promise.reject(new Error('boom'))),
+            deregister: jest.fn(),
+        };
+        const handler = new CompositeOperationHandler_1.CompositeOperationHandler(jest.fn());
+        const execution = new CompositeOperationExecution_1.CompositeOperationExecution(noopHandlerInvocationFactory, handler, OperationHandler_1.OperationHandlerType.TriggerPollCreate, 'new_records_poll', client);
+        const result = await execution.execute(fakePollingContext(), {});
+        expect(result.isFailure).toBe(true);
+        const message = result._tag === 'Failure' ? result.error.message : '';
+        expect(message).toBe('boom');
+    });
+});
+describe('CompositeOperationExecution polling dedup branch', () => {
+    it('short-circuits on a Polling Service failure envelope with a UserInputError before the dev body runs', async () => {
+        const { client } = createFakePollingServiceClient();
+        const handlerFunction = jest.fn();
+        const handler = new CompositeOperationHandler_1.CompositeOperationHandler(handlerFunction);
+        const execution = new CompositeOperationExecution_1.CompositeOperationExecution(noopHandlerInvocationFactory, handler, OperationHandler_1.OperationHandlerType.TriggerPollDedup, 'new_records_request', client);
+        const input = {
+            input: { tableName: 't' },
+            event: { error: 'upstream_gave_up', message: 'boom' },
+        };
+        const result = await execution.execute({}, input);
+        expect(handlerFunction).not.toHaveBeenCalled();
+        expect(result.isFailure).toBe(true);
+        const failure = result._tag === 'Failure' ? result.error : null;
+        expect(failure._tag).toBe('UserInputError');
+        expect(failure.message).toBe('boom');
+    });
+    it('stringifies a non-string message on the failure envelope for the UserInputError body', async () => {
+        const { client } = createFakePollingServiceClient();
+        const handler = new CompositeOperationHandler_1.CompositeOperationHandler(jest.fn());
+        const execution = new CompositeOperationExecution_1.CompositeOperationExecution(noopHandlerInvocationFactory, handler, OperationHandler_1.OperationHandlerType.TriggerPollDedup, 'new_records_request', client);
+        const input = {
+            input: {},
+            event: {
+                error: 'upstream_gave_up',
+                message: { code: 404, detail: 'nope' },
+            },
+        };
+        const result = await execution.execute({}, input);
+        expect(result.isFailure).toBe(true);
+        const message = result._tag === 'Failure' ? result.error.message : '';
+        expect(message).toBe(JSON.stringify({ code: 404, detail: 'nope' }));
+    });
+    it("lifts the dev's triggerDeduplicationId from body to metadata while preserving the body on success", async () => {
+        const { client } = createFakePollingServiceClient();
+        const handlerFunction = jest
+            .fn()
+            .mockResolvedValue(OperationHandler_1.OperationHandlerResult.success({ triggerDeduplicationId: 'evt-42' }));
+        const handler = new CompositeOperationHandler_1.CompositeOperationHandler(handlerFunction);
+        const execution = new CompositeOperationExecution_1.CompositeOperationExecution(noopHandlerInvocationFactory, handler, OperationHandler_1.OperationHandlerType.TriggerPollDedup, 'new_records_request', client);
+        const input = {
+            input: { tableName: 't' },
+            event: { id: 'evt-42', payload: { foo: 'bar' } },
+        };
+        const result = await execution.execute({}, input);
+        expect(handlerFunction).toHaveBeenCalledTimes(1);
+        expect(result.isSuccess).toBe(true);
+        expect(result._tag === 'Success' ? result.value : null).toEqual({
+            triggerDeduplicationId: 'evt-42',
+        });
+        expect(result.metadata).toEqual({ triggerDeduplicationId: 'evt-42' });
+    });
+    it('merges the lifted triggerDeduplicationId with metadata the dev already set (e.g. usage)', async () => {
+        const { client } = createFakePollingServiceClient();
+        const handlerFunction = jest
+            .fn()
+            .mockResolvedValue(OperationHandler_1.OperationHandlerResult.success({ triggerDeduplicationId: 'evt-9' }, { usage: [{ unitType: 'calls', consumed: 1 }] }));
+        const handler = new CompositeOperationHandler_1.CompositeOperationHandler(handlerFunction);
+        const execution = new CompositeOperationExecution_1.CompositeOperationExecution(noopHandlerInvocationFactory, handler, OperationHandler_1.OperationHandlerType.TriggerPollDedup, 'new_records_request', client);
+        const result = await execution.execute({}, {
+            input: {},
+            event: { id: 'evt-9' },
+        });
+        expect(result.isSuccess).toBe(true);
+        expect(result.metadata).toEqual({
+            usage: [{ unitType: 'calls', consumed: 1 }],
+            triggerDeduplicationId: 'evt-9',
+        });
+    });
+    it('forwards a dev-returned failure result as-is (no body lift)', async () => {
+        const { client } = createFakePollingServiceClient();
+        const handlerFunction = jest
+            .fn()
+            .mockResolvedValue(OperationHandler_1.OperationHandlerResult.failure(OperationHandler_1.OperationHandlerError.userInputError('dev-said-no')));
+        const handler = new CompositeOperationHandler_1.CompositeOperationHandler(handlerFunction);
+        const execution = new CompositeOperationExecution_1.CompositeOperationExecution(noopHandlerInvocationFactory, handler, OperationHandler_1.OperationHandlerType.TriggerPollDedup, 'new_records_request', client);
+        const result = await execution.execute({}, {
+            input: {},
+            event: { id: 'evt-1' },
+        });
+        expect(handlerFunction).toHaveBeenCalledTimes(1);
+        expect(result.isFailure).toBe(true);
+        const message = result._tag === 'Failure' ? result.error.message : '';
+        expect(message).toBe('dev-said-no');
+    });
+    it('does not treat a real event as a failure envelope unless BOTH error and message keys are present', async () => {
+        const { client } = createFakePollingServiceClient();
+        const handlerFunction = jest
+            .fn()
+            .mockResolvedValue(OperationHandler_1.OperationHandlerResult.success({ triggerDeduplicationId: 'evt-1' }));
+        const handler = new CompositeOperationHandler_1.CompositeOperationHandler(handlerFunction);
+        const execution = new CompositeOperationExecution_1.CompositeOperationExecution(noopHandlerInvocationFactory, handler, OperationHandler_1.OperationHandlerType.TriggerPollDedup, 'new_records_request', client);
+        // Real event with only `error` (no `message`) -- not the failure envelope.
+        const result = await execution.execute({}, {
+            input: {},
+            event: { error: 'something' },
+        });
+        expect(handlerFunction).toHaveBeenCalledTimes(1);
+        expect(result.isSuccess).toBe(true);
+    });
+});
+describe('CompositeOperationExecution non-polling path (regression baseline)', () => {
+    it('invokes handlerFunction for non-polling handler types and returns its result', async () => {
+        const { client } = createFakePollingServiceClient();
+        const success = OperationHandler_1.OperationHandlerResult.success({ echoed: 42 });
+        const handlerFunction = jest.fn().mockResolvedValue(success);
+        const handler = new CompositeOperationHandler_1.CompositeOperationHandler(handlerFunction);
+        const execution = new CompositeOperationExecution_1.CompositeOperationExecution(noopHandlerInvocationFactory, handler, OperationHandler_1.OperationHandlerType.TriggerRequest, 'some_request_op', client);
+        const ctx = {};
+        const input = { foo: 'bar' };
+        const result = await execution.execute(ctx, input);
+        expect(handlerFunction).toHaveBeenCalledTimes(1);
+        expect(handlerFunction).toHaveBeenCalledWith(ctx, input, expect.any(Function));
+        expect(result).toBe(success);
+    });
+    it('does not call the PollingServiceClient for non-polling handler types', async () => {
+        const { client, registerCalls, deregisterCalls } = createFakePollingServiceClient();
+        const handler = new CompositeOperationHandler_1.CompositeOperationHandler(jest.fn().mockResolvedValue(OperationHandler_1.OperationHandlerResult.success({})));
+        const execution = new CompositeOperationExecution_1.CompositeOperationExecution(noopHandlerInvocationFactory, handler, OperationHandler_1.OperationHandlerType.Regular, 'plain_regular_op', client);
+        await execution.execute({}, {});
+        expect(registerCalls).toHaveLength(0);
+        expect(deregisterCalls).toHaveLength(0);
+    });
+});

package/dist/connector/operation/CompositeOperationExecutionFactory.d.ts

@@ -2,9 +2,11 @@ import { OperationHandlerAuth, OperationHandlerType } from '@trayio/cdk-dsl/conn
 import { CompositeOperationHandler } from '@trayio/cdk-dsl/connector/operation/CompositeOperationHandler';
 import { OperationExecution } from './OperationExecution';
 import { OperationHandlerInvocationFactory } from './OperationHandlerInvocationFactory';
+import { PollingServiceClient } from '../polling/PollingServiceClient';
 export declare class CompositeOperationExecutionFactory {
     private handlerInvocationFactory;
-    constructor(handlerInvocationFactory: OperationHandlerInvocationFactory);
-    executionFrom<AUTH extends OperationHandlerAuth<unknown, unknown>, IN, OUT>(handler: CompositeOperationHandler<AUTH, IN, OUT>, handlerType: OperationHandlerType): OperationExecution<AUTH, IN, OUT>;
+    private pollingServiceClient;
+    constructor(handlerInvocationFactory: OperationHandlerInvocationFactory, pollingServiceClient: PollingServiceClient);
+    executionFrom<AUTH extends OperationHandlerAuth<unknown, unknown>, IN, OUT>(handler: CompositeOperationHandler<AUTH, IN, OUT>, handlerType: OperationHandlerType, operationName: string): OperationExecution<AUTH, IN, OUT>;
 }
 //# sourceMappingURL=CompositeOperationExecutionFactory.d.ts.map

package/dist/connector/operation/CompositeOperationExecutionFactory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CompositeOperationExecutionFactory.d.ts","sourceRoot":"","sources":["../../../src/connector/operation/CompositeOperationExecutionFactory.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,oBAAoB,EACpB,oBAAoB,EACpB,MAAM,sDAAsD,CAAC;AAC9D,OAAO,EAAE,yBAAyB,EAAE,MAAM,+DAA+D,CAAC;AAC1G,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D,OAAO,EAAE,iCAAiC,EAAE,MAAM,qCAAqC,CAAC;AAExF,qBAAa,kCAAkC;IAC9C,OAAO,CAAC,wBAAwB,CAAoC;gBAExD,wBAAwB,EAAE,iCAAiC;IAIvE,aAAa,CAAC,IAAI,SAAS,oBAAoB,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,EAAE,EAAE,GAAG,EACzE,OAAO,EAAE,yBAAyB,CAAC,IAAI,EAAE,EAAE,EAAE,GAAG,CAAC,EACjD,WAAW,EAAE,oBAAoB,GAC/B,kBAAkB,CAAC,IAAI,EAAE,EAAE,EAAE,GAAG,CAAC;CAOpC"}
+{"version":3,"file":"CompositeOperationExecutionFactory.d.ts","sourceRoot":"","sources":["../../../src/connector/operation/CompositeOperationExecutionFactory.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,oBAAoB,EACpB,oBAAoB,EACpB,MAAM,sDAAsD,CAAC;AAC9D,OAAO,EAAE,yBAAyB,EAAE,MAAM,+DAA+D,CAAC;AAC1G,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D,OAAO,EAAE,iCAAiC,EAAE,MAAM,qCAAqC,CAAC;AACxF,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAEvE,qBAAa,kCAAkC;IAC9C,OAAO,CAAC,wBAAwB,CAAoC;IACpE,OAAO,CAAC,oBAAoB,CAAuB;gBAGlD,wBAAwB,EAAE,iCAAiC,EAC3D,oBAAoB,EAAE,oBAAoB;IAM3C,aAAa,CAAC,IAAI,SAAS,oBAAoB,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,EAAE,EAAE,GAAG,EACzE,OAAO,EAAE,yBAAyB,CAAC,IAAI,EAAE,EAAE,EAAE,GAAG,CAAC,EACjD,WAAW,EAAE,oBAAoB,EACjC,aAAa,EAAE,MAAM,GACnB,kBAAkB,CAAC,IAAI,EAAE,EAAE,EAAE,GAAG,CAAC;CASpC"}

package/dist/connector/operation/CompositeOperationExecutionFactory.js

@@ -4,11 +4,13 @@ exports.CompositeOperationExecutionFactory = void 0;
 const CompositeOperationExecution_1 = require("./CompositeOperationExecution");
 class CompositeOperationExecutionFactory {
     handlerInvocationFactory;
-    constructor(handlerInvocationFactory) {
+    pollingServiceClient;
+    constructor(handlerInvocationFactory, pollingServiceClient) {
         this.handlerInvocationFactory = handlerInvocationFactory;
+        this.pollingServiceClient = pollingServiceClient;
     }
-    executionFrom(handler, handlerType) {
-        return new CompositeOperationExecution_1.CompositeOperationExecution(this.handlerInvocationFactory, handler, handlerType);
+    executionFrom(handler, handlerType, operationName) {
+        return new CompositeOperationExecution_1.CompositeOperationExecution(this.handlerInvocationFactory, handler, handlerType, operationName, this.pollingServiceClient);
     }
 }
 exports.CompositeOperationExecutionFactory = CompositeOperationExecutionFactory;

package/dist/connector/operation/CompositeOperationExecutionPolling.d.ts

@@ -0,0 +1,33 @@
+import { OperationHandlerAuth, OperationHandlerContext, OperationHandlerResult, OperationHandlerType } from '@trayio/cdk-dsl/connector/operation/OperationHandler';
+import { CompositeOperationHandler } from '@trayio/cdk-dsl/connector/operation/CompositeOperationHandler';
+import { PollingTriggerInput } from '@trayio/cdk-dsl/connector/operation/PollingTypes';
+import { PollingServiceClient } from '../polling/PollingServiceClient';
+import { OperationHandlerInvocationFactory } from './OperationHandlerInvocationFactory';
+export type PollingTriggerInvocationInput = PollingTriggerInput & {
+    initialCursor?: string | null;
+};
+export declare const isPollingLifecycle: (handlerType: OperationHandlerType) => boolean;
+/**
+ * Polling dedup (`_request`) dispatch. Runs the Polling Service failure
+ * envelope short-circuit before the dev body, then lifts the dev's
+ * `triggerDeduplicationId` from the response body into
+ * `OperationHandlerResult.metadata` so ConnectorInvocationDomain's existing
+ * AppTalk metadata forwarding picks it up unchanged. The body is preserved
+ * as returned by the dev.
+ */
+export declare function runTriggerPollDedup<AUTH extends OperationHandlerAuth<unknown, unknown>, IN, OUT>(args: {
+    ctx: OperationHandlerContext<AUTH>;
+    input: IN;
+    handler: CompositeOperationHandler<AUTH, IN, OUT>;
+    handlerInvocationFactory: OperationHandlerInvocationFactory;
+    validateOperationResponse: (r: OperationHandlerResult<OUT>) => void;
+    mapCaughtError: (e: unknown) => OperationHandlerResult<OUT>;
+}): Promise<OperationHandlerResult<OUT>>;
+export declare function runPollingRegisterOrDeregister<AUTH extends OperationHandlerAuth<unknown, unknown>>(args: {
+    ctx: OperationHandlerContext<AUTH>;
+    handlerType: OperationHandlerType.TriggerPollCreate | OperationHandlerType.TriggerPollDestroy;
+    operationName: string;
+    pollingInput: PollingTriggerInvocationInput;
+    pollingServiceClient: PollingServiceClient;
+}): Promise<void>;
+//# sourceMappingURL=CompositeOperationExecutionPolling.d.ts.map

package/dist/connector/operation/CompositeOperationExecutionPolling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CompositeOperationExecutionPolling.d.ts","sourceRoot":"","sources":["../../../src/connector/operation/CompositeOperationExecutionPolling.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,oBAAoB,EACpB,uBAAuB,EAEvB,sBAAsB,EAEtB,oBAAoB,EAEpB,MAAM,sDAAsD,CAAC;AAC9D,OAAO,EAAE,yBAAyB,EAAE,MAAM,+DAA+D,CAAC;AAC1G,OAAO,EAAE,mBAAmB,EAAE,MAAM,kDAAkD,CAAC;AAEvF,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AACvE,OAAO,EAAE,iCAAiC,EAAE,MAAM,qCAAqC,CAAC;AAExF,MAAM,MAAM,6BAA6B,GAAG,mBAAmB,GAAG;IACjE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,CAAC;AAuEF,eAAO,MAAM,kBAAkB,gBACjB,oBAAoB,KAC/B,OAEqD,CAAC;AAoCzD;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACxC,IAAI,SAAS,oBAAoB,CAAC,OAAO,EAAE,OAAO,CAAC,EACnD,EAAE,EACF,GAAG,EACF,IAAI,EAAE;IACP,GAAG,EAAE,uBAAuB,CAAC,IAAI,CAAC,CAAC;IACnC,KAAK,EAAE,EAAE,CAAC;IACV,OAAO,EAAE,yBAAyB,CAAC,IAAI,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;IAClD,wBAAwB,EAAE,iCAAiC,CAAC;IAC5D,yBAAyB,EAAE,CAAC,CAAC,EAAE,sBAAsB,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC;IACpE,cAAc,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,sBAAsB,CAAC,GAAG,CAAC,CAAC;CAC5D,GAAG,OAAO,CAAC,sBAAsB,CAAC,GAAG,CAAC,CAAC,CAiCvC;AAED,wBAAgB,8BAA8B,CAC7C,IAAI,SAAS,oBAAoB,CAAC,OAAO,EAAE,OAAO,CAAC,EAClD,IAAI,EAAE;IACP,GAAG,EAAE,uBAAuB,CAAC,IAAI,CAAC,CAAC;IACnC,WAAW,EACR,oBAAoB,CAAC,iBAAiB,GACtC,oBAAoB,CAAC,kBAAkB,CAAC;IAC3C,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,6BAA6B,CAAC;IAC5C,oBAAoB,EAAE,oBAAoB,CAAC;CAC3C,GAAG,OAAO,CAAC,IAAI,CAAC,CAiDhB"}

package/dist/connector/operation/CompositeOperationExecutionPolling.js

@@ -0,0 +1,142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runPollingRegisterOrDeregister = exports.runTriggerPollDedup = exports.isPollingLifecycle = void 0;
+const OperationHandler_1 = require("@trayio/cdk-dsl/connector/operation/OperationHandler");
+const requirePollingCtxFields = (ctx) => {
+    const missing = [];
+    if (!ctx.connectorName)
+        missing.push('ctx.connectorName');
+    if (!ctx.connectorVersion)
+        missing.push('ctx.connectorVersion');
+    if (!ctx.executionToken)
+        missing.push('ctx.executionToken');
+    if (!ctx.publicUrl)
+        missing.push('ctx.publicUrl');
+    if (missing.length > 0) {
+        throw new Error(`polling lifecycle is missing required context fields: ${missing.join(', ')}`);
+    }
+    return {
+        connectorName: ctx.connectorName,
+        connectorVersion: ctx.connectorVersion,
+        executionToken: ctx.executionToken,
+        publicUrl: ctx.publicUrl,
+    };
+};
+const requirePollingRegisterCtxFields = (ctx) => {
+    const base = requirePollingCtxFields(ctx);
+    const missing = [];
+    if (!ctx.auth?.authId)
+        missing.push('ctx.auth.authId');
+    if (!ctx.organizationId)
+        missing.push('ctx.organizationId');
+    if (!ctx.workspaceId)
+        missing.push('ctx.workspaceId');
+    if (!ctx.projectId)
+        missing.push('ctx.projectId');
+    if (missing.length > 0) {
+        throw new Error(`polling register is missing required context fields: ${missing.join(', ')}`);
+    }
+    return {
+        ...base,
+        authenticationId: ctx.auth.authId,
+        organizationId: ctx.organizationId,
+        workspaceId: ctx.workspaceId,
+        projectId: ctx.projectId,
+    };
+};
+const isPollingLifecycle = (handlerType) => handlerType === OperationHandler_1.OperationHandlerType.TriggerPollCreate ||
+    handlerType === OperationHandler_1.OperationHandlerType.TriggerPollDestroy;
+exports.isPollingLifecycle = isPollingLifecycle;
+/**
+ * Polling Service failure envelope.
+ *
+ * After `maxFailureCount` consecutive non-recoverable failures from the dev's
+ * poll handler, the Polling Service posts a synthetic `{ error, message }`
+ * payload into the dedup (`_request`) operation instead of a real event. The
+ * connector cannot deduplicate that, so the runtime surfaces it as a
+ * platform userInputError before the dev's dedup body runs.
+ *
+ * Returns the short-circuit failure result when the event matches, or null
+ * when it is a real event that should flow to the dev body.
+ */
+const detectPollingFailureEnvelope = (event) => {
+    if (event === null ||
+        event === undefined ||
+        typeof event !== 'object' ||
+        !('error' in event) ||
+        !('message' in event)) {
+        return null;
+    }
+    const payload = event;
+    return OperationHandler_1.OperationHandlerResult.failure(OperationHandler_1.OperationHandlerError.userInputError(typeof payload.message === 'string'
+        ? payload.message
+        : JSON.stringify(payload.message)));
+};
+/**
+ * Polling dedup (`_request`) dispatch. Runs the Polling Service failure
+ * envelope short-circuit before the dev body, then lifts the dev's
+ * `triggerDeduplicationId` from the response body into
+ * `OperationHandlerResult.metadata` so ConnectorInvocationDomain's existing
+ * AppTalk metadata forwarding picks it up unchanged. The body is preserved
+ * as returned by the dev.
+ */
+async function runTriggerPollDedup(args) {
+    const { ctx, input, handler, handlerInvocationFactory, validateOperationResponse, mapCaughtError, } = args;
+    const event = input?.event;
+    const envelope = detectPollingFailureEnvelope(event);
+    if (envelope !== null) {
+        return envelope;
+    }
+    const handlerInvocation = handlerInvocationFactory(ctx);
+    try {
+        const result = await handler.handlerFunction(ctx, input, handlerInvocation);
+        validateOperationResponse(result);
+        if (!result.isSuccess) {
+            return result;
+        }
+        const body = result.value;
+        const mergedMetadata = {
+            ...(result.metadata ?? {}),
+            triggerDeduplicationId: body.triggerDeduplicationId,
+        };
+        return OperationHandler_1.OperationHandlerResult.success(result.value, mergedMetadata);
+    }
+    catch (error) {
+        return mapCaughtError(error);
+    }
+}
+exports.runTriggerPollDedup = runTriggerPollDedup;
+function runPollingRegisterOrDeregister(args) {
+    const { ctx, handlerType, operationName: registeredHandlerName, pollingInput, pollingServiceClient, } = args;
+    switch (handlerType) {
+        case OperationHandler_1.OperationHandlerType.TriggerPollCreate: {
+            const registerCtx = requirePollingRegisterCtxFields(ctx);
+            return pollingServiceClient.register({
+                connectorName: registerCtx.connectorName,
+                connectorVersion: registerCtx.connectorVersion,
+                registeredHandlerName,
+                authenticationId: registerCtx.authenticationId,
+                organizationId: registerCtx.organizationId,
+                workspaceId: registerCtx.workspaceId,
+                projectId: registerCtx.projectId,
+                publicUrl: registerCtx.publicUrl,
+                pollingInterval: pollingInput.pollingInterval,
+                maxFailureCount: pollingInput.maxFailureCount,
+                initialCursor: pollingInput.initialCursor,
+            }, registerCtx.executionToken);
+        }
+        case OperationHandler_1.OperationHandlerType.TriggerPollDestroy: {
+            const destroyCtx = requirePollingCtxFields(ctx);
+            return pollingServiceClient.deregister({
+                connectorName: destroyCtx.connectorName,
+                connectorVersion: destroyCtx.connectorVersion,
+                registeredHandlerName,
+                publicUrl: destroyCtx.publicUrl,
+                preserveCursor: true,
+            }, destroyCtx.executionToken);
+        }
+        default:
+            throw new Error(`polling lifecycle called for non-polling handler type: ${String(handlerType)}`);
+    }
+}
+exports.runPollingRegisterOrDeregister = runPollingRegisterOrDeregister;

package/dist/connector/operation/OperationExecutionFactory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OperationExecutionFactory.d.ts","sourceRoot":"","sources":["../../../src/connector/operation/OperationExecutionFactory.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,gBAAgB,EAEhB,MAAM,2DAA2D,CAAC;AACnE,OAAO,EACN,oBAAoB,EAEpB,MAAM,sDAAsD,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG1D,OAAO,EAAE,iCAAiC,EAAE,MAAM,qCAAqC,CAAC;AAGxF,qBAAa,yBAAyB;IACrC,OAAO,CAAC,mCAAmC,CAAsC;IACjF,OAAO,CAAC,6BAA6B,CAAgC;IACrE,OAAO,CAAC,kCAAkC,CAAqC;gBAG9E,UAAU,EAAE,UAAU,EACtB,WAAW,EAAE,WAAW,EACxB,iCAAiC,EAAE,iCAAiC;IAYrE,aAAa,CAAC,IAAI,SAAS,oBAAoB,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,EAAE,EAAE,GAAG,EACzE,OAAO,EAAE,gBAAgB,CAAC,IAAI,EAAE,EAAE,EAAE,GAAG,CAAC,GACtC,kBAAkB,CAAC,IAAI,EAAE,EAAE,EAAE,GAAG,CAAC;IAWpC,OAAO,CAAC,2BAA2B;CAsBnC"}
+{"version":3,"file":"OperationExecutionFactory.d.ts","sourceRoot":"","sources":["../../../src/connector/operation/OperationExecutionFactory.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,gBAAgB,EAEhB,MAAM,2DAA2D,CAAC;AACnE,OAAO,EACN,oBAAoB,EAEpB,MAAM,sDAAsD,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG1D,OAAO,EAAE,iCAAiC,EAAE,MAAM,qCAAqC,CAAC;AAIxF,qBAAa,yBAAyB;IACrC,OAAO,CAAC,mCAAmC,CAAsC;IACjF,OAAO,CAAC,6BAA6B,CAAgC;IACrE,OAAO,CAAC,kCAAkC,CAAqC;gBAG9E,UAAU,EAAE,UAAU,EACtB,WAAW,EAAE,WAAW,EACxB,iCAAiC,EAAE,iCAAiC;IAerE,aAAa,CAAC,IAAI,SAAS,oBAAoB,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,EAAE,EAAE,GAAG,EACzE,OAAO,EAAE,gBAAgB,CAAC,IAAI,EAAE,EAAE,EAAE,GAAG,CAAC,GACtC,kBAAkB,CAAC,IAAI,EAAE,EAAE,EAAE,GAAG,CAAC;IAWpC,OAAO,CAAC,2BAA2B;CAsBnC"}

package/dist/connector/operation/OperationExecutionFactory.js

@@ -4,6 +4,7 @@ exports.OperationExecutionFactory = void 0;
 const HttpOperationExecutionFactory_1 = require("./HttpOperationExecutionFactory");
 const CompositeOperationExecutionFactory_1 = require("./CompositeOperationExecutionFactory");
 const OperationExecutionValidationFactory_1 = require("./OperationExecutionValidationFactory");
+const PollingServiceClient_1 = require("../polling/PollingServiceClient");
 class OperationExecutionFactory {
     operationExecutionValidationFactory;
     httpOperationExecutionFactory;
@@ -13,7 +14,7 @@ class OperationExecutionFactory {
             new OperationExecutionValidationFactory_1.OperationExecutionValidationFactory();
         this.httpOperationExecutionFactory = new HttpOperationExecutionFactory_1.HttpOperationExecutionFactory(httpClient, fileStorage);
         this.compositeOperationExecutionFactory =
-            new CompositeOperationExecutionFactory_1.CompositeOperationExecutionFactory(operationHandlerInvocationFactory);
+            new CompositeOperationExecutionFactory_1.CompositeOperationExecutionFactory(operationHandlerInvocationFactory, new PollingServiceClient_1.PollingServiceClient(httpClient));
     }
     executionFrom(handler) {
         const executionFromImplementation = this.executionFromImplementation(handler);
@@ -25,7 +26,7 @@ class OperationExecutionFactory {
             case 'HttpOperationHandler':
                 return this.httpOperationExecutionFactory.executionFrom(handler.implementation, handler.globalConfiguration, handler.handlerType);
             case 'CompositeOperationHandler':
-                return this.compositeOperationExecutionFactory.executionFrom(handler.implementation, handler.handlerType);
+                return this.compositeOperationExecutionFactory.executionFrom(handler.implementation, handler.handlerType, handler.name);
         }
     }
 }

package/dist/connector/polling/PollingServiceClient.d.ts

@@ -0,0 +1,50 @@
+import { HttpClient } from '@trayio/commons/http/HttpClient';
+import { PollingInterval } from '@trayio/cdk-dsl/connector/operation/PollingTypes';
+export type PollingServiceRegisterPayload = {
+    connectorName: string;
+    connectorVersion: string;
+    /**
+     * The registered handler name (e.g. `"new_records_poll"`). The client
+     * normalizes to the canonical `_poll`-suffixed form before sending.
+     */
+    registeredHandlerName: string;
+    /** Platform identity that the Polling Service keys the registration against. */
+    authenticationId: string;
+    organizationId: string;
+    workspaceId: string;
+    projectId: string;
+    publicUrl: string;
+    pollingInterval?: PollingInterval;
+    maxFailureCount?: number;
+    initialCursor?: string | null;
+};
+export type PollingServiceDeregisterPayload = {
+    connectorName: string;
+    connectorVersion: string;
+    /**
+     * The registered handler name (e.g. `"new_records_poll_destroy"`). The
+     * client normalizes to the canonical `_poll`-suffixed form before sending.
+     */
+    registeredHandlerName: string;
+    publicUrl: string;
+    /**
+     * When true, the Polling Service retains the trigger's cursor so that a
+     * subsequent re-register (e.g. after a workflow is disabled then re-enabled)
+     * resumes from where polling stopped. The runtime always sends `true`
+     * today.
+     */
+    preserveCursor: boolean;
+};
+/**
+ * Internal HTTP client used by the runtime when invoking polling trigger
+ * create / destroy operations. Not exported from the public `@trayio/cdk-runtime`
+ * surface; connector developers must not call this directly.
+ */
+export declare class PollingServiceClient {
+    private httpClient;
+    constructor(httpClient: HttpClient);
+    register(payload: PollingServiceRegisterPayload, executionToken: string): Promise<void>;
+    deregister(payload: PollingServiceDeregisterPayload, executionToken: string): Promise<void>;
+    private sendJson;
+}
+//# sourceMappingURL=PollingServiceClient.d.ts.map

package/dist/connector/polling/PollingServiceClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PollingServiceClient.d.ts","sourceRoot":"","sources":["../../../src/connector/polling/PollingServiceClient.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAE7D,OAAO,EAGN,eAAe,EAEf,MAAM,kDAAkD,CAAC;AA0B1D,MAAM,MAAM,6BAA6B,GAAG;IAC3C,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,qBAAqB,EAAE,MAAM,CAAC;IAC9B,gFAAgF;IAChF,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,+BAA+B,GAAG;IAC7C,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,qBAAqB,EAAE,MAAM,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,cAAc,EAAE,OAAO,CAAC;CACxB,CAAC;AA4BF;;;;GAIG;AACH,qBAAa,oBAAoB;IACpB,OAAO,CAAC,UAAU;gBAAV,UAAU,EAAE,UAAU;IAEpC,QAAQ,CACb,OAAO,EAAE,6BAA6B,EACtC,cAAc,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC;IAwBV,UAAU,CACf,OAAO,EAAE,+BAA+B,EACxC,cAAc,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC;YAaF,QAAQ;CAgCtB"}

package/dist/connector/polling/PollingServiceClient.js

@@ -0,0 +1,128 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PollingServiceClient = void 0;
+const stream_1 = require("stream");
+const E = __importStar(require("fp-ts/Either"));
+const Http_1 = require("@trayio/commons/http/Http");
+const PollingTypes_1 = require("@trayio/cdk-dsl/connector/operation/PollingTypes");
+const POLLING_SERVICE_URL_ENV = 'TRAY_POLLING_SERVICE_URL';
+const EXECUTION_TOKEN_HEADER = 'X-Tray-Execution-Token';
+const TRIGGERS_REGISTER_PATH = '/triggers/register';
+const POLL_SUFFIX = '_poll';
+const POLL_DESTROY_SUFFIX = '_poll_destroy';
+/**
+ * PS keys register+deregister against the canonical `_poll`-suffixed
+ * operation name. `_poll_destroy` handlers rewrite to the matching `_poll`
+ * name so both sides of the lifecycle target the same PS record.
+ */
+const toCanonicalPollOperationName = (registeredHandlerName) => {
+    if (registeredHandlerName.endsWith(POLL_DESTROY_SUFFIX)) {
+        return `${registeredHandlerName.slice(0, -POLL_DESTROY_SUFFIX.length)}${POLL_SUFFIX}`;
+    }
+    return registeredHandlerName;
+};
+const pollingIntervalToMinutes = (interval) => {
+    switch (interval.unit) {
+        case PollingTypes_1.PollingIntervalUnit.Minutes:
+            return interval.value;
+        case PollingTypes_1.PollingIntervalUnit.Hours:
+            return interval.value * 60;
+        default:
+            throw new Error(`Unsupported pollingInterval.unit: ${interval.unit}`);
+    }
+};
+const resolveEndpoint = () => {
+    const baseUrl = process.env[POLLING_SERVICE_URL_ENV];
+    if (!baseUrl) {
+        throw new Error(`${POLLING_SERVICE_URL_ENV} env var is not set; the polling service cannot be reached`);
+    }
+    return `${baseUrl.replace(/\/$/, '')}${TRIGGERS_REGISTER_PATH}`;
+};
+const bodyToReadable = (payload) => stream_1.Readable.from(JSON.stringify(payload));
+/**
+ * Internal HTTP client used by the runtime when invoking polling trigger
+ * create / destroy operations. Not exported from the public `@trayio/cdk-runtime`
+ * surface; connector developers must not call this directly.
+ */
+class PollingServiceClient {
+    httpClient;
+    constructor(httpClient) {
+        this.httpClient = httpClient;
+    }
+    async register(payload, executionToken) {
+        const intervalMinutes = pollingIntervalToMinutes(payload.pollingInterval ?? PollingTypes_1.DEFAULT_POLLING_INTERVAL);
+        const maxFailureCount = payload.maxFailureCount ?? PollingTypes_1.DEFAULT_MAX_FAILURE_COUNT;
+        const body = {
+            connectorName: payload.connectorName,
+            connectorVersion: payload.connectorVersion,
+            operationName: toCanonicalPollOperationName(payload.registeredHandlerName),
+            authenticationId: payload.authenticationId,
+            organizationId: payload.organizationId,
+            workspaceId: payload.workspaceId,
+            projectId: payload.projectId,
+            publicUrl: payload.publicUrl,
+            interval: intervalMinutes,
+            maxFailureCount,
+            initialCursor: payload.initialCursor ?? null,
+        };
+        await this.sendJson(Http_1.HttpMethod.Post, executionToken, body);
+    }
+    async deregister(payload, executionToken) {
+        const body = {
+            connectorName: payload.connectorName,
+            connectorVersion: payload.connectorVersion,
+            operationName: toCanonicalPollOperationName(payload.registeredHandlerName),
+            publicUrl: payload.publicUrl,
+            preserveCursor: payload.preserveCursor,
+        };
+        await this.sendJson(Http_1.HttpMethod.Delete, executionToken, body);
+    }
+    async sendJson(method, executionToken, body) {
+        if (!executionToken) {
+            throw new Error('polling service call requires an execution token (ctx.executionToken)');
+        }
+        const url = resolveEndpoint();
+        const request = Http_1.HttpRequest.create({
+            headers: {
+                [Http_1.HttpHeader.ContentType]: 'application/json',
+                [EXECUTION_TOKEN_HEADER]: executionToken,
+            },
+            body: bodyToReadable(body),
+        });
+        const responseE = await this.httpClient.execute(method, url, request)();
+        if (E.isLeft(responseE)) {
+            throw responseE.left;
+        }
+        const response = responseE.right;
+        if (response.statusCode < 200 || response.statusCode >= 300) {
+            throw new Error(`polling service ${method} ${url} failed with status ${response.statusCode}`);
+        }
+        // Drain the body so the underlying HTTP connection can be released.
+        // We don't need the payload; the status code is authoritative.
+        response.body.resume();
+    }
+}
+exports.PollingServiceClient = PollingServiceClient;

package/dist/connector/polling/PollingServiceClient.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=PollingServiceClient.unit.test.d.ts.map

package/dist/connector/polling/PollingServiceClient.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PollingServiceClient.unit.test.d.ts","sourceRoot":"","sources":["../../../src/connector/polling/PollingServiceClient.unit.test.ts"],"names":[],"mappings":""}

package/dist/connector/polling/PollingServiceClient.unit.test.js

@@ -0,0 +1,218 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const stream_1 = require("stream");
+const TE = __importStar(require("fp-ts/TaskEither"));
+const Http_1 = require("@trayio/commons/http/Http");
+const PollingTypes_1 = require("@trayio/cdk-dsl/connector/operation/PollingTypes");
+const PollingServiceClient_1 = require("./PollingServiceClient");
+const BASE_URL = 'https://polling.example.test';
+const ENDPOINT_PATH = '/triggers/register';
+const ENV_VAR = 'TRAY_POLLING_SERVICE_URL';
+const createMockHttpClient = (capture) => ({
+    execute: jest.fn().mockImplementation((method, url, request) => TE.tryCatch(async () => {
+        const chunks = [];
+        for await (const chunk of request.body) {
+            chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+        }
+        const raw = Buffer.concat(chunks).toString('utf8');
+        capture.push({
+            method,
+            url,
+            headers: request.headers,
+            body: raw.length > 0 ? JSON.parse(raw) : undefined,
+        });
+        return {
+            statusCode: 200,
+            headers: {},
+            body: stream_1.Readable.from(''),
+        };
+    }, (reason) => new Error(String(reason)))),
+});
+const minimalRegister = (overrides = {}) => ({
+    connectorName: 'x',
+    connectorVersion: '1.0.0',
+    registeredHandlerName: 'x_poll',
+    authenticationId: 'auth-uuid',
+    organizationId: 'org-id',
+    workspaceId: 'ws-id',
+    projectId: 'project-uuid',
+    publicUrl: 'u',
+    ...overrides,
+});
+describe('PollingServiceClient', () => {
+    let originalEnv;
+    beforeEach(() => {
+        originalEnv = process.env[ENV_VAR];
+        process.env[ENV_VAR] = BASE_URL;
+    });
+    afterEach(() => {
+        if (originalEnv === undefined) {
+            delete process.env[ENV_VAR];
+        }
+        else {
+            process.env[ENV_VAR] = originalEnv;
+        }
+    });
+    describe('register', () => {
+        it('POSTs to /triggers/register with the full payload and execution token header', async () => {
+            const captured = [];
+            const client = new PollingServiceClient_1.PollingServiceClient(createMockHttpClient(captured));
+            await client.register({
+                connectorName: 'salesforce',
+                connectorVersion: '7.2.0',
+                registeredHandlerName: 'new_records_poll',
+                authenticationId: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
+                organizationId: 'org-uuid',
+                workspaceId: 'ws-uuid',
+                projectId: '7fa00000-1111-2222-3333-444455556666',
+                publicUrl: 'https://trigger.example.test/abc',
+                pollingInterval: {
+                    value: 10,
+                    unit: PollingTypes_1.PollingIntervalUnit.Minutes,
+                },
+                maxFailureCount: 42,
+                initialCursor: 'cursor-0',
+            }, 'exec-jwt-token');
+            expect(captured).toHaveLength(1);
+            const call = captured[0];
+            expect(call.method).toBe(Http_1.HttpMethod.Post);
+            expect(call.url).toBe(`${BASE_URL}${ENDPOINT_PATH}`);
+            expect(call.headers).toMatchObject({
+                'Content-Type': 'application/json',
+                'X-Tray-Execution-Token': 'exec-jwt-token',
+            });
+            expect(call.body).toEqual({
+                connectorName: 'salesforce',
+                connectorVersion: '7.2.0',
+                operationName: 'new_records_poll',
+                authenticationId: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
+                organizationId: 'org-uuid',
+                workspaceId: 'ws-uuid',
+                projectId: '7fa00000-1111-2222-3333-444455556666',
+                publicUrl: 'https://trigger.example.test/abc',
+                interval: 10,
+                maxFailureCount: 42,
+                initialCursor: 'cursor-0',
+            });
+        });
+        it('sends interval in minutes for PollingIntervalUnit.Minutes', async () => {
+            const captured = [];
+            const client = new PollingServiceClient_1.PollingServiceClient(createMockHttpClient(captured));
+            await client.register(minimalRegister({
+                pollingInterval: {
+                    value: 15,
+                    unit: PollingTypes_1.PollingIntervalUnit.Minutes,
+                },
+            }), 'tok');
+            expect(captured[0].body.interval).toBe(15);
+        });
+        it('converts hours to minutes', async () => {
+            const captured = [];
+            const client = new PollingServiceClient_1.PollingServiceClient(createMockHttpClient(captured));
+            await client.register(minimalRegister({
+                pollingInterval: { value: 2, unit: PollingTypes_1.PollingIntervalUnit.Hours },
+            }), 'tok');
+            expect(captured[0].body.interval).toBe(120);
+        });
+        it('falls back to defaults (5 min, maxFailureCount 30, null cursor) when omitted', async () => {
+            const captured = [];
+            const client = new PollingServiceClient_1.PollingServiceClient(createMockHttpClient(captured));
+            await client.register(minimalRegister(), 'tok');
+            expect(captured[0].body).toMatchObject({
+                interval: 5,
+                maxFailureCount: 30,
+                initialCursor: null,
+            });
+        });
+        it('trims trailing slashes from the PS base URL', async () => {
+            process.env[ENV_VAR] = `${BASE_URL}/`;
+            const captured = [];
+            const client = new PollingServiceClient_1.PollingServiceClient(createMockHttpClient(captured));
+            await client.register(minimalRegister(), 'tok');
+            expect(captured[0].url).toBe(`${BASE_URL}${ENDPOINT_PATH}`);
+        });
+        it('throws when TRAY_POLLING_SERVICE_URL env var is unset', async () => {
+            delete process.env[ENV_VAR];
+            const client = new PollingServiceClient_1.PollingServiceClient(createMockHttpClient([]));
+            await expect(client.register(minimalRegister(), 'tok')).rejects.toThrow(/TRAY_POLLING_SERVICE_URL/);
+        });
+        it('throws when execution token is an empty string', async () => {
+            const client = new PollingServiceClient_1.PollingServiceClient(createMockHttpClient([]));
+            await expect(client.register(minimalRegister(), '')).rejects.toThrow(/execution token/);
+        });
+        it('throws when PS returns a non-2xx status', async () => {
+            const errorClient = {
+                execute: () => TE.right({
+                    statusCode: 500,
+                    headers: {},
+                    body: stream_1.Readable.from(''),
+                }),
+            };
+            const client = new PollingServiceClient_1.PollingServiceClient(errorClient);
+            await expect(client.register(minimalRegister(), 'tok')).rejects.toThrow(/failed with status 500/);
+        });
+    });
+    describe('deregister', () => {
+        it('DELETEs /triggers/register with canonical op name, preserveCursor flag and execution token header', async () => {
+            const captured = [];
+            const client = new PollingServiceClient_1.PollingServiceClient(createMockHttpClient(captured));
+            await client.deregister({
+                connectorName: 'salesforce',
+                connectorVersion: '7.2.0',
+                registeredHandlerName: 'new_records_poll_destroy',
+                publicUrl: 'https://trigger.example.test/abc',
+                preserveCursor: true,
+            }, 'exec-jwt-token');
+            expect(captured).toHaveLength(1);
+            const call = captured[0];
+            expect(call.method).toBe(Http_1.HttpMethod.Delete);
+            expect(call.url).toBe(`${BASE_URL}${ENDPOINT_PATH}`);
+            expect(call.headers).toMatchObject({
+                'X-Tray-Execution-Token': 'exec-jwt-token',
+            });
+            expect(call.body).toEqual({
+                connectorName: 'salesforce',
+                connectorVersion: '7.2.0',
+                operationName: 'new_records_poll',
+                publicUrl: 'https://trigger.example.test/abc',
+                preserveCursor: true,
+            });
+        });
+        it('leaves an already-canonical _poll name unchanged', async () => {
+            const captured = [];
+            const client = new PollingServiceClient_1.PollingServiceClient(createMockHttpClient(captured));
+            await client.deregister({
+                connectorName: 'x',
+                connectorVersion: '1.0.0',
+                registeredHandlerName: 'x_poll',
+                publicUrl: 'u',
+                preserveCursor: false,
+            }, 'tok');
+            expect(captured[0].body.operationName).toBe('x_poll');
+            expect(captured[0].body.preserveCursor).toBe(false);
+        });
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trayio/cdk-runtime",
-  "version": "5.21.0",
+  "version": "5.22.0-unstable",
   "description": "A Runtime that executes connector operations defined using the CDK DSL",
   "exports": {
     "./*": "./dist/*.js"
@@ -14,10 +14,10 @@
     "node": ">=18.x"
   },
   "dependencies": {
-    "@trayio/axios": "5.21.0",
-    "@trayio/cdk-dsl": "5.21.0",
-    "@trayio/express": "5.21.0",
-    "@trayio/winston": "5.21.0",
+    "@trayio/axios": "5.22.0-unstable",
+    "@trayio/cdk-dsl": "5.22.0-unstable",
+    "@trayio/express": "5.22.0-unstable",
+    "@trayio/winston": "5.22.0-unstable",
     "mime": "3.0.0",
     "uuid": "9.0.0"
   },
@@ -34,5 +34,6 @@
   ],
   "devDependencies": {
     "just-permutations": "^2.2.1"
-  }
+  },
+  "stableVersion": "0.0.0"
 }