opticedge-cloud-utils 1.1.19 → 1.1.20

package/dist/tests/retry.test.js

@@ -0,0 +1,339 @@
+"use strict";
+/* eslint-disable @typescript-eslint/no-explicit-any */
+// tests/retry.test.ts
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const axios_1 = __importDefault(require("axios"));
+const src_1 = require("../src");
+describe('sleep()', () => {
+    const realAbortController = global.AbortController;
+    afterEach(() => {
+        // restore timers and AbortController if changed
+        jest.useRealTimers();
+        global.AbortController = realAbortController;
+        jest.clearAllMocks();
+    });
+    test('resolves after the specified delay', async () => {
+        jest.useFakeTimers();
+        const p = (0, src_1.sleep)(100);
+        // advance timers by the sleep duration
+        jest.advanceTimersByTime(100);
+        // allow the Promise microtask queue to run
+        await Promise.resolve();
+        await expect(p).resolves.toBeUndefined();
+    });
+    test('rejects immediately if signal is already aborted', async () => {
+        const ac = new AbortController();
+        ac.abort();
+        await expect((0, src_1.sleep)(50, ac.signal)).rejects.toThrow('Aborted');
+    });
+    test('rejects when aborted after scheduling', async () => {
+        jest.useFakeTimers();
+        const ac = new AbortController();
+        const p = (0, src_1.sleep)(1000, ac.signal);
+        // abort after the sleep has been scheduled but before timeout
+        ac.abort();
+        // allow the event-loop microtasks to run
+        await Promise.resolve();
+        await expect(p).rejects.toThrow('Aborted');
+        // advancing timers should not resolve the promise
+        jest.advanceTimersByTime(1000);
+        await Promise.resolve();
+        await expect(p).rejects.toThrow('Aborted');
+    });
+});
+describe('isRetryableDefault', () => {
+    test('returns false for falsy errors (covers `if (!err) return false`)', () => {
+        expect((0, src_1.isRetryableDefault)(null)).toBe(false);
+        expect((0, src_1.isRetryableDefault)(undefined)).toBe(false);
+        // Also check a falsy-but-not-nullish value is handled (should coerce to false at top)
+        expect((0, src_1.isRetryableDefault)(0)).toBe(false);
+    });
+    test('returns false for an object with no retryable properties', () => {
+        expect((0, src_1.isRetryableDefault)({})).toBe(false);
+        expect((0, src_1.isRetryableDefault)({ foo: 'bar' })).toBe(false);
+    });
+    test('matches message containing "timeout" (case-insensitive)', () => {
+        expect((0, src_1.isRetryableDefault)(new Error('Request timed out'))).toBe(true);
+        expect((0, src_1.isRetryableDefault)(new Error('TIMEOUT occurred'))).toBe(true);
+        expect((0, src_1.isRetryableDefault)({ message: 'this is a timeout error' })).toBe(true);
+    });
+    test('matches message containing "temporary"', () => {
+        expect((0, src_1.isRetryableDefault)(new Error('Temporary failure contacting host'))).toBe(true);
+        expect((0, src_1.isRetryableDefault)({ message: 'temporary issue' })).toBe(true);
+    });
+    test('matches message containing "unavailable"', () => {
+        expect((0, src_1.isRetryableDefault)(new Error('Service Unavailable'))).toBe(true);
+        expect((0, src_1.isRetryableDefault)({ message: 'unavailable resource' })).toBe(true);
+    });
+    test('matches message containing "econnreset" or "etimedout" (substrings, case-insensitive)', () => {
+        expect((0, src_1.isRetryableDefault)(new Error('ECONNRESET by peer'))).toBe(true);
+        expect((0, src_1.isRetryableDefault)(new Error('econnreset'))).toBe(true);
+        expect((0, src_1.isRetryableDefault)(new Error('ETIMEDOUT waiting for response'))).toBe(true);
+        expect((0, src_1.isRetryableDefault)({ message: 'some ETIMEDOUT occurred' })).toBe(true);
+    });
+    test('does not treat unrelated messages as retryable', () => {
+        expect((0, src_1.isRetryableDefault)(new Error('Bad request'))).toBe(false);
+        expect((0, src_1.isRetryableDefault)({ message: 'invalid parameter provided' })).toBe(false);
+    });
+    test('still returns true when message sits alongside other properties (defensive)', () => {
+        const errLike = {
+            code: undefined,
+            response: undefined,
+            message: 'temporary network hiccup'
+        };
+        expect((0, src_1.isRetryableDefault)(errLike)).toBe(true);
+    });
+});
+describe('isRetryableAxios()', () => {
+    // Helper to synthesize axios-like errors
+    function makeAxiosError(payload = {}) {
+        // minimal axios-style error: flag + response optionally
+        const err = new Error(payload.message ?? 'axios-err');
+        err.isAxiosError = true;
+        if (Object.prototype.hasOwnProperty.call(payload, 'response')) {
+            err.response = payload.response;
+        }
+        else if (payload.response === undefined && payload.noResponse) {
+            // explicit network/no-response: leave out response
+        }
+        if (payload.code)
+            err.code = payload.code;
+        if (payload.message)
+            err.message = payload.message;
+        return err;
+    }
+    test('returns false when err is falsy', () => {
+        expect((0, src_1.isRetryableAxios)(null)).toBe(false);
+        expect((0, src_1.isRetryableAxios)(undefined)).toBe(false);
+        // also check other falsy-ish values that shouldn't be considered retryable
+        expect((0, src_1.isRetryableAxios)(false)).toBe(false);
+        expect((0, src_1.isRetryableAxios)('')).toBe(false);
+    });
+    test('returns true for network/no-response axios errors', () => {
+        const networkErr = makeAxiosError({ noResponse: true });
+        expect(axios_1.default.isAxiosError(networkErr)).toBe(true); // sanity check
+        expect((0, src_1.isRetryableAxios)(networkErr)).toBe(true);
+    });
+    test('returns true for 500 server error', () => {
+        const serverErr = makeAxiosError({ response: { status: 500, data: {} } });
+        expect((0, src_1.isRetryableAxios)(serverErr)).toBe(true);
+    });
+    test('returns true for 503 server error', () => {
+        const serverErr = makeAxiosError({ response: { status: 503, data: {} } });
+        expect((0, src_1.isRetryableAxios)(serverErr)).toBe(true);
+    });
+    test('returns true for 429 rate limit', () => {
+        const rateErr = makeAxiosError({ response: { status: 429, data: {} } });
+        expect((0, src_1.isRetryableAxios)(rateErr)).toBe(true);
+    });
+    test('returns false for 400 client error (do not retry)', () => {
+        const badReq = makeAxiosError({ response: { status: 400, data: {} } });
+        expect((0, src_1.isRetryableAxios)(badReq)).toBe(false);
+    });
+    test('delegates to isRetryableDefault for non-axios errors', () => {
+        // make a network-style Node error that isRetryableDefault recognizes
+        const nodeErr = { code: 'ECONNRESET', message: 'socket closed' };
+        expect((0, src_1.isRetryableDefault)(nodeErr)).toBe(true); // sanity
+        expect((0, src_1.isRetryableAxios)(nodeErr)).toBe(true);
+    });
+    test('returns false for non-retryable non-axios error', () => {
+        const normalErr = new Error('something bad but not retryable');
+        // isRetryableDefault likely returns false for a plain Error w/o hint
+        expect((0, src_1.isRetryableDefault)(normalErr)).toBe(false);
+        expect((0, src_1.isRetryableAxios)(normalErr)).toBe(false);
+    });
+});
+describe('retry util', () => {
+    afterEach(() => {
+        jest.restoreAllMocks();
+    });
+    test('returns result when fn succeeds immediately', async () => {
+        const fn = jest.fn(async () => 'ok');
+        const res = await (0, src_1.retry)(fn, { retries: 3 });
+        expect(res).toBe('ok');
+        expect(fn).toHaveBeenCalledTimes(1);
+    });
+    test('retries on transient error and eventually succeeds; onRetry called expected times', async () => {
+        // fail twice with retryable error (gRPC code 14), then succeed
+        let calls = 0;
+        const fn = jest.fn(async () => {
+            calls++;
+            if (calls <= 2) {
+                const e = new Error('transient-gprc');
+                e.code = 14;
+                throw e;
+            }
+            return 'ok-after-retries';
+        });
+        const onRetry = jest.fn();
+        // Make delays zero by forcing Math.random to 0 so tests are deterministic and fast
+        const mathSpy = jest.spyOn(Math, 'random').mockReturnValue(0);
+        const res = await (0, src_1.retry)(fn, { retries: 5, baseDelayMs: 10, onRetry });
+        expect(res).toBe('ok-after-retries');
+        expect(fn).toHaveBeenCalledTimes(3);
+        // onRetry called for the 2 transient failures
+        expect(onRetry).toHaveBeenCalledTimes(2);
+        mathSpy.mockRestore();
+    });
+    test('non-retryable error is rethrown immediately', async () => {
+        const fn = jest.fn(async () => {
+            const e = new Error('bad request');
+            e.status = 400;
+            throw e;
+        });
+        await expect((0, src_1.retry)(fn, { retries: 3 })).rejects.toThrow('bad request');
+        expect(fn).toHaveBeenCalledTimes(1);
+    });
+    test('exhausts retries and throws final error preserving original', async () => {
+        const original = new Error('permanent transient-like');
+        original.code = 14; // make it retryable
+        const fn = jest.fn(async () => {
+            throw original;
+        });
+        // make delays 0 to run fast
+        jest.spyOn(Math, 'random').mockReturnValue(0);
+        await expect((0, src_1.retry)(fn, { retries: 2, baseDelayMs: 1 })).rejects.toHaveProperty('original', original);
+        // initial call + 2 retries = 3 attempts
+        expect(fn).toHaveBeenCalledTimes(3);
+    });
+    test('isRetryableDefault recognizes common shapes', () => {
+        const e1 = new Error('econnreset happened');
+        e1.code = 'ECONNRESET';
+        expect((0, src_1.isRetryableDefault)(e1)).toBe(true);
+        const e2 = new Error('http 500');
+        e2.response = { status: 500 };
+        expect((0, src_1.isRetryableDefault)(e2)).toBe(true);
+        const e3 = new Error('not retryable');
+        e3.status = 400;
+        expect((0, src_1.isRetryableDefault)(e3)).toBe(false);
+        const e4 = new Error('gRPC unavailable');
+        e4.code = 14;
+        expect((0, src_1.isRetryableDefault)(e4)).toBe(true);
+    });
+    test('abort signal aborts immediately when already aborted', async () => {
+        const controller = new AbortController();
+        controller.abort();
+        const fn = jest.fn(async () => 'should-not-run');
+        await expect((0, src_1.retry)(fn, { signal: controller.signal })).rejects.toThrow('Aborted');
+        // function should not be called at all because we check signal at loop start
+        expect(fn).toHaveBeenCalledTimes(0);
+    });
+    test('abort during wait causes rejection', async () => {
+        // Function will fail once (retryable), then retry -> sleep -> we abort during sleep.
+        let calls = 0;
+        const fn = jest.fn(async () => {
+            calls++;
+            if (calls === 1) {
+                const e = new Error('transient');
+                e.code = 14;
+                throw e;
+            }
+            return 'should-not-get-here';
+        });
+        // Make delay large so we can abort during sleep (but we will abort synchronously)
+        jest.spyOn(Math, 'random').mockReturnValue(1); // picks the max exp
+        const controller = new AbortController();
+        // Start the retry but abort immediately after allowing the utility to start.
+        // We do not await retry here yet; create a Promise and then abort and await
+        const p = (0, src_1.retry)(fn, { retries: 3, baseDelayMs: 200, signal: controller.signal });
+        // Abort immediately — this should cause the pending sleep to reject
+        controller.abort();
+        await expect(p).rejects.toThrow('Aborted');
+    });
+    test('abort during wait causes rejection and triggers onAbort (clears timeout)', async () => {
+        // Function will fail once (retryable), then retry -> sleep -> we abort during sleep.
+        let calls = 0;
+        const fn = jest.fn(async () => {
+            calls++;
+            if (calls === 1) {
+                const e = new Error('transient');
+                e.code = 14;
+                throw e;
+            }
+            return 'should-not-get-here';
+        });
+        // Make sure there is a non-zero delay so sleep schedules a timer
+        jest.spyOn(Math, 'random').mockReturnValue(0.5);
+        const controller = new AbortController();
+        // Start the retry (it will throw once, then call sleep)
+        const p = (0, src_1.retry)(fn, { retries: 3, baseDelayMs: 200, signal: controller.signal });
+        // Wait a tick so `sleep` has a chance to attach the abort listener and call setTimeout.
+        // Using setTimeout 0 (or small timeout) guarantees the timer and listener are attached.
+        await new Promise(resolve => setTimeout(resolve, 0));
+        // Now abort — this should call the onAbort handler inside sleep which clears the timeout
+        controller.abort();
+        await expect(p).rejects.toThrow('Aborted');
+        Math.random.mockRestore();
+    });
+    test('respects timeoutMs and breaks before waiting (covers timeout check)', async () => {
+        // Make the wrapped fn throw a retryable error once
+        const original = new Error('transient-timeout');
+        original.code = 14; // make it retryable via isRetryableDefault
+        const fn = jest.fn(async () => {
+            throw original;
+        });
+        // Force Math.random to 1 so delay === exp (max for that attempt)
+        const mathSpy = jest.spyOn(Math, 'random').mockReturnValue(1);
+        // Use a baseDelayMs larger than timeoutMs so elapsed + delay > timeoutMs triggers the "break"
+        await expect((0, src_1.retry)(fn, {
+            retries: 5,
+            baseDelayMs: 50, // exp for attempt 1 = 50
+            timeoutMs: 10 // 50 > 10 so we should break before sleeping
+        })).rejects.toHaveProperty('original', original);
+        // fn should only have been called once (no retry/sleep occurred)
+        expect(fn).toHaveBeenCalledTimes(1);
+        mathSpy.mockRestore();
+    });
+    test('omitted opts uses default retries and eventually succeeds', async () => {
+        // Fail twice with retryable error (gRPC code 14), then succeed
+        let calls = 0;
+        const fn = jest.fn(async () => {
+            calls++;
+            if (calls <= 2) {
+                const e = new Error('transient');
+                e.code = 14;
+                throw e;
+            }
+            return 'ok-defaults';
+        });
+        // Make delays deterministic & small (Math.random = 0 -> delay = 0)
+        jest.spyOn(Math, 'random').mockReturnValue(0);
+        const res = await (0, src_1.retry)(fn); // <- call WITHOUT opts to exercise default param
+        expect(res).toBe('ok-defaults');
+        // Called initial + 2 retries = 3 times
+        expect(fn).toHaveBeenCalledTimes(3);
+        Math.random.mockRestore();
+    });
+    test('omitted opts exhausts default retries (5 attempts total) and throws', async () => {
+        const original = new Error('always-transient');
+        original.code = 14; // make it retryable
+        const fn = jest.fn(async () => {
+            throw original;
+        });
+        // Make delays 0 so test runs fast
+        jest.spyOn(Math, 'random').mockReturnValue(0);
+        // Default retries is 4 -> total attempts = 5
+        await expect((0, src_1.retry)(fn)).rejects.toHaveProperty('original', original);
+        expect(fn).toHaveBeenCalledTimes(5);
+        Math.random.mockRestore();
+    });
+    test('final error message falls back to String(lastErr) when lastErr.message is undefined', async () => {
+        // original is a plain object (no .message)
+        const original = { code: 14, detail: 'plain-object-no-message' };
+        const fn = jest.fn(async () => {
+            throw original; // will be assigned to lastErr in retry()
+        });
+        // Make delays deterministic & fast
+        const mathSpy = jest.spyOn(Math, 'random').mockReturnValue(0);
+        // retries = 1 -> attempt will be 1 in finalErr message
+        await expect((0, src_1.retry)(fn, { retries: 1, baseDelayMs: 1 })).rejects.toMatchObject({
+            message: expect.stringContaining('[object Object]'),
+            // Ensure original error was preserved on the thrown final error
+            original
+        });
+        mathSpy.mockRestore();
+    });
+});

package/dist/tests/secrets.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/secrets.test.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const secrets_1 = require("../src/secrets");
+const secret_manager_1 = require("@google-cloud/secret-manager");
+jest.mock('@google-cloud/secret-manager');
+// Mock implementation
+const mockAccessSecretVersion = jest.fn();
+secret_manager_1.SecretManagerServiceClient.mockImplementation(() => ({
+    accessSecretVersion: mockAccessSecretVersion
+}));
+describe('getSecret', () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+    it('returns secret value as string', async () => {
+        mockAccessSecretVersion.mockResolvedValue([
+            {
+                payload: { data: Buffer.from('super-secret-value') }
+            }
+        ]);
+        const result = await (0, secrets_1.getSecret)('test-project', 'test-secret');
+        expect(result).toBe('super-secret-value');
+        expect(mockAccessSecretVersion).toHaveBeenCalledWith({
+            name: 'projects/test-project/secrets/test-secret/versions/latest'
+        });
+    });
+    it('throws if projectId is missing', async () => {
+        await expect((0, secrets_1.getSecret)('', 'secret')).rejects.toThrow('projectId is required');
+    });
+    it('throws if secretName is missing', async () => {
+        await expect((0, secrets_1.getSecret)('project', '')).rejects.toThrow('secretName is required');
+    });
+    it('returns empty string if payload or data is missing', async () => {
+        mockAccessSecretVersion.mockResolvedValue([{}]); // no payload
+        const result = await (0, secrets_1.getSecret)('project', 'secret');
+        expect(result).toBe('');
+    });
+});

package/dist/tests/task.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/task.test.js

@@ -0,0 +1,262 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/* eslint-disable @typescript-eslint/no-explicit-any */
+// tests/createTask.retry.test.ts
+const mockCreateTask = jest.fn();
+const mockQueuePath = jest.fn((projectId, region, queueId) => `projects/${projectId}/locations/${region}/queues/${queueId}`);
+// Mock Cloud Tasks client and protos (same as your original file)
+jest.mock('@google-cloud/tasks', () => {
+    return {
+        CloudTasksClient: jest.fn(() => ({
+            createTask: mockCreateTask,
+            queuePath: mockQueuePath
+        })),
+        protos: {
+            google: {
+                cloud: {
+                    tasks: {
+                        v2: {
+                            HttpMethod: {
+                                POST: 'POST'
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    };
+});
+// Mock the retry module so tests can inspect how createTask uses it.
+// We'll set mockRetry behavior in each test as needed.
+const realRetryModule = jest.requireActual('../src/retry');
+const mockRetry = jest.fn();
+jest.mock('../src/retry', () => ({
+    // spread real exports so isRetryableDefault, isRetryableAxios etc remain available
+    ...realRetryModule,
+    // override only 'retry' with our mock
+    retry: (...args) => mockRetry(...args)
+}));
+const task_1 = require("../src/task");
+describe('isRetryableCloudTasks', () => {
+    test('returns false for falsy errors', () => {
+        expect((0, task_1.isRetryableCloudTasks)(null)).toBe(false);
+        expect((0, task_1.isRetryableCloudTasks)(undefined)).toBe(false);
+        // other falsy-ish values should also be non-retryable
+        expect((0, task_1.isRetryableCloudTasks)(false)).toBe(false);
+        expect((0, task_1.isRetryableCloudTasks)('')).toBe(false);
+    });
+    test('treats ALREADY_EXISTS (code: 6) as NOT retryable', () => {
+        expect((0, task_1.isRetryableCloudTasks)({ code: 6 })).toBe(false);
+        expect((0, task_1.isRetryableCloudTasks)({ grpcCode: 6 })).toBe(false);
+        expect((0, task_1.isRetryableCloudTasks)({ code: 'ALREADY_EXISTS' })).toBe(false);
+        expect((0, task_1.isRetryableCloudTasks)({ code: 'already_exists' })).toBe(false);
+    });
+    test('treats UNAVAILABLE (code: 14) as retryable', () => {
+        expect((0, task_1.isRetryableCloudTasks)({ code: 14 })).toBe(true);
+        expect((0, task_1.isRetryableCloudTasks)({ grpcCode: 14 })).toBe(true);
+    });
+    test('treats HTTP 5xx and 429 as retryable, 4xx not retryable', () => {
+        expect((0, task_1.isRetryableCloudTasks)({ response: { status: 500 } })).toBe(true);
+        expect((0, task_1.isRetryableCloudTasks)({ response: { status: 503 } })).toBe(true);
+        expect((0, task_1.isRetryableCloudTasks)({ response: { status: 429 } })).toBe(true);
+        expect((0, task_1.isRetryableCloudTasks)({ response: { status: 400 } })).toBe(false);
+        expect((0, task_1.isRetryableCloudTasks)({ response: { status: 404 } })).toBe(false);
+    });
+    test('treats node network errno like ECONNRESET as retryable (delegated to isRetryableDefault)', () => {
+        // isRetryableDefault recognizes typical node syscodes like 'ECONNRESET'
+        expect((0, task_1.isRetryableCloudTasks)({ code: 'ECONNRESET' })).toBe(true);
+        expect((0, task_1.isRetryableCloudTasks)({ code: 'ETIMEDOUT' })).toBe(true);
+        expect((0, task_1.isRetryableCloudTasks)({ code: 'EAI_AGAIN' })).toBe(true);
+    });
+    test('plain Error without hints is not retryable', () => {
+        expect((0, task_1.isRetryableCloudTasks)(new Error('oops'))).toBe(false);
+    });
+    test('non-standard objects without response but with message may or may not be retryable depending on heuristics', () => {
+        // This test documents the expected behavior: a message-only error generally is NOT retryable
+        // unless the message contains a retryable substring (e.g. "timeout" or "unavailable").
+        expect((0, task_1.isRetryableCloudTasks)({ message: 'socket closed' })).toBe(false);
+        expect((0, task_1.isRetryableCloudTasks)({ message: 'request timed out' })).toBe(true);
+        expect((0, task_1.isRetryableCloudTasks)({ message: 'temporarily unavailable' })).toBe(true);
+    });
+});
+describe('createTask (with retry)', () => {
+    const projectId = 'test-project';
+    const region = 'us-central1';
+    const queueId = 'test-queue';
+    const data = { test: 'data' };
+    const serviceAccount = 'test-sa@test.iam.gserviceaccount.com';
+    const audience = 'https://run-url';
+    const mockTaskName = 'projects/test-project/locations/us-central1/queues/test-queue/tasks/task-123';
+    let warnSpy;
+    beforeEach(() => {
+        mockCreateTask.mockReset();
+        mockQueuePath.mockClear();
+        mockRetry.mockReset();
+        // store the spy instance so we can assert against it safely
+        warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => { });
+    });
+    it('throws error if any required parameter is missing', async () => {
+        // Ensure retry / createTask are not called for parameter validation errors
+        await expect((0, task_1.createTask)('', 'region', 'queue', {}, 'serviceAccount', 'audience')).rejects.toThrow('Missing required parameters for Cloud Tasks setup');
+        await expect((0, task_1.createTask)('project', '', 'queue', {}, 'serviceAccount', 'audience')).rejects.toThrow('Missing required parameters for Cloud Tasks setup');
+        await expect((0, task_1.createTask)('project', 'region', '', {}, 'serviceAccount', 'audience')).rejects.toThrow('Missing required parameters for Cloud Tasks setup');
+        await expect((0, task_1.createTask)('project', 'region', 'queue', {}, '', 'audience')).rejects.toThrow('Missing required parameters for Cloud Tasks setup');
+        await expect((0, task_1.createTask)('project', 'region', 'queue', {}, 'serviceAccount', '')).rejects.toThrow('Missing required parameters for Cloud Tasks setup');
+        expect(mockCreateTask).not.toHaveBeenCalled();
+        expect(mockRetry).not.toHaveBeenCalled();
+    });
+    it('should create a task and return task name (calls retry once)', async () => {
+        // Configure retry mock to simply execute the provided function immediately.
+        mockRetry.mockImplementation(async (fn) => {
+            return await fn();
+        });
+        mockCreateTask.mockResolvedValue([{ name: mockTaskName }]);
+        const result = await (0, task_1.createTask)(projectId, region, queueId, data, serviceAccount, audience);
+        expect(result).toBe(mockTaskName);
+        expect(mockCreateTask).toHaveBeenCalledTimes(1);
+        expect(mockRetry).toHaveBeenCalledTimes(1);
+        // ensure the createTask was called with an object containing `task`
+        const calledArg = mockCreateTask.mock.calls[0][0];
+        expect(calledArg).toHaveProperty('task');
+    });
+    it('should throw error if task name is missing', async () => {
+        mockRetry.mockImplementation(async (fn) => {
+            return await fn();
+        });
+        mockCreateTask.mockResolvedValue([{}]); // Simulate missing name
+        await expect((0, task_1.createTask)(projectId, region, queueId, { foo: 'bar' }, serviceAccount, audience)).rejects.toThrow('Failed to create task: no name returned');
+    });
+    it('should include scheduleTime if delaySeconds is set', async () => {
+        mockRetry.mockImplementation(async (fn) => await fn());
+        mockCreateTask.mockResolvedValue([
+            { name: 'projects/test/locations/us-central1/queues/test/tasks/task-456' }
+        ]);
+        const delaySeconds = 120;
+        const before = Math.floor(Date.now() / 1000) + delaySeconds;
+        await (0, task_1.createTask)(projectId, region, queueId, { message: 'delayed' }, serviceAccount, audience, delaySeconds);
+        const taskArg = mockCreateTask.mock.calls[0][0].task;
+        const scheduleTime = taskArg.scheduleTime?.seconds;
+        const after = Math.floor(Date.now() / 1000) + delaySeconds;
+        expect(typeof scheduleTime).toBe('number');
+        expect(scheduleTime).toBeGreaterThanOrEqual(before);
+        expect(scheduleTime).toBeLessThanOrEqual(after);
+    });
+    it('retries on transient (UNAVAILABLE) error then succeeds', async () => {
+        // Simulate createTask: first call rejects with transient code 14, second call resolves.
+        mockCreateTask
+            .mockRejectedValueOnce({ code: 14, message: 'UNAVAILABLE' })
+            .mockResolvedValueOnce([{ name: mockTaskName }]);
+        // Implement a small retry simulator: call fn(); if it throws then call opts.onRetry and call fn() again.
+        mockRetry.mockImplementation(async (fn, opts) => {
+            try {
+                return await fn();
+            }
+            catch (err) {
+                // simulate onRetry callback being invoked by retry implementation
+                if (opts?.onRetry) {
+                    try {
+                        opts.onRetry(err, 1, 0);
+                    }
+                    catch {
+                        // ignore
+                    }
+                }
+                return await fn();
+            }
+        });
+        const result = await (0, task_1.createTask)(projectId, region, queueId, data, serviceAccount, audience);
+        expect(mockCreateTask).toHaveBeenCalledTimes(2);
+        expect(mockRetry).toHaveBeenCalledTimes(1);
+        expect(result).toBe(mockTaskName);
+    });
+    it('returns expected name if ALREADY_EXISTS and taskId provided (idempotent)', async () => {
+        // Simulate retry throwing ALREADY_EXISTS error (code: 6)
+        mockRetry.mockImplementation(async () => {
+            throw { code: 6, message: 'ALREADY_EXISTS' };
+        });
+        const taskId = 'task-123';
+        const expectedName = `projects/${projectId}/locations/${region}/queues/${queueId}/tasks/${taskId}`;
+        const result = await (0, task_1.createTask)(projectId, region, queueId, data, serviceAccount, audience, 0, {
+            taskId
+        });
+        // Should return expected name when ALREADY_EXISTS and taskId provided
+        expect(result).toBe(expectedName);
+        expect(mockRetry).toHaveBeenCalledTimes(1);
+    });
+    it('passes an isRetryable to retry that treats ALREADY_EXISTS as non-retryable and UNAVAILABLE as retryable', async () => {
+        // Spy on the options passed to retry and invoke isRetryable with sample errors
+        mockRetry.mockImplementation(async (fn, opts) => {
+            // Sanity: opts should exist and include isRetryable
+            expect(opts).toBeDefined();
+            expect(typeof opts.isRetryable).toBe('function');
+            const isRetryable = opts.isRetryable;
+            // ALREADY_EXISTS (gRPC code 6) should NOT be retryable
+            expect(isRetryable({ code: 6 })).toBe(false);
+            // UNAVAILABLE (gRPC code 14) should be retryable
+            expect(isRetryable({ code: 14 })).toBe(true);
+            expect(isRetryable({ code: 'ECONNRESET' })).toBe(true);
+            // Execute the function normally for this test
+            return await fn();
+        });
+        mockCreateTask.mockResolvedValue([{ name: mockTaskName }]);
+        const result = await (0, task_1.createTask)(projectId, region, queueId, data, serviceAccount, audience);
+        expect(result).toBe(mockTaskName);
+        expect(mockRetry).toHaveBeenCalledTimes(1);
+    });
+    it('invokes onRetry with actual error message and logs it', async () => {
+        // first call fails with a retryable transient error, second call succeeds
+        const expectedName = `projects/${projectId}/locations/${region}/queues/${queueId}/tasks/1`;
+        mockCreateTask
+            .mockRejectedValueOnce({ code: 14, message: 'UNAVAILABLE' }) // transient
+            .mockResolvedValueOnce([{ name: expectedName }]);
+        // Simulate retry behaviour: call fn(); if it throws, call onRetry(err, attempt, delay) then try fn() again.
+        mockRetry.mockImplementation(async (fn, opts) => {
+            try {
+                return await fn();
+            }
+            catch (err) {
+                if (opts?.onRetry) {
+                    opts.onRetry(err, 1, 0);
+                }
+                return await fn();
+            }
+        });
+        const result = await (0, task_1.createTask)(projectId, region, queueId, data, serviceAccount, audience);
+        expect(result).toBe(expectedName);
+        expect(mockCreateTask).toHaveBeenCalledTimes(2);
+        // assert onRetry logged the attempt and included the error message
+        expect(warnSpy.mock.calls.length).toBeGreaterThanOrEqual(1);
+        const warnMsg = warnSpy.mock.calls[0][0];
+        expect(warnMsg).toContain('createTask retry #1 in 0ms');
+        expect(warnMsg).toContain('UNAVAILABLE');
+    });
+    it('invokes onRetry with undefined error and logs "undefined" in message', async () => {
+        const expectedName = `projects/${projectId}/locations/${region}/queues/${queueId}/tasks/2`;
+        mockCreateTask
+            .mockRejectedValueOnce(new Error('boom')) // this will trigger catch in our mockRetry
+            .mockResolvedValueOnce([{ name: expectedName }]);
+        // This variant calls onRetry(undefined, ...) to exercise the err?.message ?? err branch.
+        mockRetry.mockImplementation(async (fn, opts) => {
+            try {
+                return await fn();
+            }
+            catch {
+                if (opts?.onRetry) {
+                    opts.onRetry(undefined, 1, 0); // pass undefined as the error
+                }
+                return await fn();
+            }
+        });
+        const result = await (0, task_1.createTask)(projectId, region, queueId, data, serviceAccount, audience);
+        expect(result).toBe(expectedName);
+        expect(mockCreateTask).toHaveBeenCalledTimes(2);
+        // Assert the onRetry prefix was logged
+        expect(warnSpy.mock.calls.length).toBeGreaterThanOrEqual(1);
+        const warnMsg = warnSpy.mock.calls[0][0];
+        expect(warnMsg).toContain('createTask retry #1 in 0ms');
+        // instead of requiring the exact 'undefined' substring (which can vary),
+        // assert there's something logged in the error slot (non-empty)
+        const afterPrefix = warnMsg.replace('createTask retry #1 in 0ms — ', '');
+        expect(afterPrefix.length).toBeGreaterThan(0);
+    });
+});

package/dist/tests/tw/utils.test.d.ts

@@ -0,0 +1 @@
+export {};