gcf-common-lib 0.35.0 → 0.38.0

package/.github/workflows/npm-publish.yml

@@ -1,36 +1,39 @@
-# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
-# For more information see: https://help.github.com/actions/language-and-framework-guides/publishing-nodejs-packages
-
-name: Node.js Package
-on: [ push ]
-
-# on:
-#  release:
-#    types: [created]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-      - run: npm ci
-#      - run: npm run build
-      - run: npm test
-
-  publish-npm:
-    needs: build
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          registry-url: https://registry.npmjs.org/
-      - run: npm ci
-#      - run: npm run build
-      - run: npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}
+# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
+# For more information see: https://help.github.com/actions/language-and-framework-guides/publishing-nodejs-packages
+
+name: Node.js Package
+on: [ push ]
+
+# on:
+#  release:
+#    types: [created]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+#      - run: npm run build
+      - run: npm test
+
+  publish-npm:
+    permissions:
+      contents: read # This is required for actions/checkout
+      id-token: write # This is required for publishing to npm
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org/
+      - run: npm ci
+#      - run: npm run build
+      - run: npm publish --provenance
+#        env:
+#          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}

package/.junie/guidelines.md

@@ -0,0 +1,108 @@
+# gcf-common-lib: Development Guidelines
+
+This document captures project-specific details to speed up work on this repository.
+It assumes an advanced Node/TypeScript developer familiar with Node 20+, npm, ESLint flat config, and the Node test runner.
+
+## 1) Build and Configuration
+
+- Runtime/Tooling versions
+  - Node: >= 20 (see package.json "engines"). Tested with Node 20.x.
+  - TypeScript: ^5.3 (dev dependency). The project extends `@tsconfig/node20`.
+- TypeScript config
+  - tsconfig.json extends `@tsconfig/node20`. It currently sets only `"compilerOptions.newLine": "crlf"`.
+  - `@tsconfig/node20` typically configures strict mode and `noEmit: true`. As a result, `npm run build` performs type-checking only and does not emit JS artifacts by default.
+  - If you need JS output, add an `outDir` and override `noEmit: false` in tsconfig.json (or create a separate tsconfig.build.json) and adjust the build script accordingly.
+- Build
+  - Type-check: `npm run build` (runs `tsc`). No compiled JS will be emitted with the current config.
+- Entry point / module resolution
+  - package.json sets `"main": "src/index"`. The published package is intended to be consumed by TS-aware builds, bundlers, or via transpilation. Node alone cannot `require('src')` TypeScript without a loader/transpiler.
+- Linting/Formatting
+  - ESLint flat config with:
+    - `@eslint/js` (base JS rules), `typescript-eslint` (TS rules), `eslint-plugin-unicorn`, and `eslint-plugin-promise`.
+    - Notable overrides: several `@typescript-eslint/*` rules are off (no-explicit-any, no-unused-vars, no-empty-function, no-empty-interface). `unicorn/prevent-abbreviations` is off. Additional rules enforce `block-scoped-var`, `no-loop-func`.
+  - Prettier is present as a dev dependency; there is no explicit npm script, run via `npx prettier --write .` if needed.
+  - Line endings: CRLF (Windows) per tsconfig; ensure your editor respects this to avoid noisy diffs.
+
+## 2) Testing
+
+- Framework
+  - Uses Node’s built-in test runner (`node:test`) with `node:assert/strict`.
+  - Default npm script: `npm test` runs `node --test ./test/`.
+
+- Important notes for this repo
+  - Some code paths interact with external services (Google Pub/Sub via `@google-cloud/pubsub`, AMQP via `amqplib`). Avoid hitting those in unit tests unless you have proper credentials and brokers.
+  - The repository contains `test/test.ts` (TypeScript) and a historical compiled `test/test.js`. The JS test tries to `require('../src')`, but the project does not emit JS builds by default, so Node cannot load TS sources as JS. Running the whole suite may therefore fail locally unless you:
+    - Compile TS to JS and point Node to the emitted entry, or
+    - Use a loader (e.g., ts-node / swc / tsx) to run TS directly, or
+    - Write tests in JS that import only pure functions that do not require transpilation.
+
+- Recommended local workflows
+  1) Run a single, deterministic JS test file (no external deps):
+     - Place a JS test under `test/` with a `.test.js` name, then run:
+       - `node --test .\test\your.test.js`
+     - Example (verified locally):
+       ```js
+       // test/sample.test.js
+       const { describe, it } = require('node:test');
+       const assert = require('node:assert/strict');
+       describe('sample', () => {
+         it('adds numbers', () => {
+           assert.equal(1 + 1, 2);
+         });
+         it('async works', async () => {
+           const v = await Promise.resolve('ok');
+           assert.equal(v, 'ok');
+         });
+       });
+       ```
+       - Run: `node --test .\test\sample.test.js`
+
+  2) Testing library functions without network calls:
+     - Prefer testing pure utilities from `src/utils.ts` (e.g., `ms`, `sec`, `A1` conversions, `safeJsonParse`). Create JS shims if needed or compile.
+     - For `GcfCommon.process(...)`, avoid network I/O by passing payloads that do not contain `topic`, `exchange`, or `queue` in metadata/attributes. The `response(...)` method publishes only if those are present. Example payload for a no-network test:
+       ```ts
+       const payload = { event: { '@type': 'type.googleapis.com/google.pubsub.v1.PubsubMessage', json: { ok: 1 }, attributes: {} }, context: undefined };
+       // No topic/exchange/queue -> response() becomes a no-op for network I/O
+       ```
+     - Alternatively, stub `GcfCommon.response` in tests:
+       ```js
+       const { GcfCommon } = require('../src');
+       const original = GcfCommon.response;
+       GcfCommon.response = async () => {}; // no-op
+       // ... run test logic ...
+       GcfCommon.response = original;
+       ```
+
+  3) Running TS tests
+     - Option A (compile): configure tsconfig to emit JS (e.g., to `dist/`), compile tests and source, and run Node against the emitted JS.
+     - Option B (loader): use a TS loader like `tsx` or `ts-node` to run TS under Node’s test runner. Example with tsx:
+       - Install dev dep: `npm i -D tsx`
+       - Run: `node --test --import tsx .\test\test.ts`
+       - Caveat: loader flags and support differ across Node versions; prefer pure JS tests if you want zero-config.
+
+- Integration tests (Pub/Sub, AMQP)
+  - Pub/Sub requires Google Application Default Credentials (e.g., set `GOOGLE_APPLICATION_CREDENTIALS=path\to\service-account.json`).
+  - AMQP requires a reachable broker URL; set `GcfCommon.amqpOptions.url` appropriately.
+  - These are not required for unit testing and should be skipped or stubbed in CI unless explicitly needed.
+
+## 3) Additional development information
+
+- Project layout
+  - `src/`: TypeScript sources (helpers for Pub/Sub, AMQP, Mongo, utilities, types, and `GcfCommon`).
+  - `test/`: Node test runner tests. Prefer `.test.js` files for frictionless execution without transpilation.
+- External services
+  - `GcfCommon.response(...)` conditionally publishes to Pub/Sub or AMQP if `topic`, `exchange`, or `queue` are present in payload metadata/attributes. Omit these in unit tests to avoid network calls.
+  - `GcfCommon.getOptions(...)` parses JSON options from metadata/attributes; it uses `safeJsonParse` with a fallback to avoid throwing.
+- Coding style
+  - Adhere to the ESLint setup, especially around promises and unicorn rules; long-lived abbreviations are allowed (prevent-abbreviations is off).
+  - Use CRLF line endings to match repo configuration.
+- CI/CD & publishing
+  - `publishConfig.access: public`; branch is `master` in metadata. If publishing, ensure you build/type-check and validate tests that do not require external services, or segregate integration tests under a separate command.
+
+## Quick Commands
+
+- Install deps: `npm ci`
+- Type-check build: `npm run build`
+- Run all JS tests in a file: `node --test .\test\some.test.js`
+- Lint (manual): `npx eslint .`
+- Format (manual): `npx prettier --write .`

package/.prettierrc

@@ -1,10 +1,10 @@
-{
-  "printWidth": 120,
-  "trailingComma": "all",
-  "tabWidth": 2,
-  "semi": true,
-  "singleQuote": true,
-  "arrowParens": "avoid",
-  "bracketSameLine": true,
-  "endOfLine": "crlf"
-}
+{
+  "printWidth": 120,
+  "trailingComma": "all",
+  "tabWidth": 2,
+  "semi": true,
+  "singleQuote": true,
+  "arrowParens": "avoid",
+  "bracketSameLine": true,
+  "endOfLine": "crlf"
+}

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Code of Conduct
+
+We follow the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.
+
+- Be respectful and inclusive.
+- Use welcoming and inclusive language.
+- Be considerate of differing viewpoints and experiences.
+- Gracefully accept constructive criticism.
+- Focus on what is best for the community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting the maintainers.
+
+For more details, see https://www.contributor-covenant.org/version/2/1/code_of_conduct/

package/CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing to gcf-common-lib
+
+Thank you for your interest in contributing!
+
+This project targets Node >= 20 and TypeScript ^5.3. It uses ESLint (flat config) and Node’s built-in test runner. Please follow the guidelines below.
+
+## Development setup
+
+- Prerequisites: Node 20.x, npm 10+.
+- Install dependencies:
+  ```sh
+  npm ci
+  ```
+- Type-check build (no emit by default):
+  ```sh
+  npm run build
+  ```
+
+## Coding standards
+
+- TypeScript strict mode (via `@tsconfig/node20`).
+- Line endings: CRLF (Windows) per tsconfig. Configure your editor to use CRLF to avoid noisy diffs.
+- Linting: ESLint flat config (`eslint.config.mjs`) with `@eslint/js`, `typescript-eslint`, `eslint-plugin-unicorn`, and `eslint-plugin-promise`.
+  - Run manually:
+    ```sh
+    npx eslint .
+    ```
+- Formatting: Prettier is available; run manually when needed:
+  ```sh
+  npx prettier --write .
+  ```
+
+## Testing
+
+- Framework: Node’s built-in test runner (`node:test`) with `node:assert/strict`).
+- Default script runs tests under `test/`:
+  ```sh
+  npm test
+  ```
+- Keep unit tests deterministic and offline by default.
+  - Avoid network I/O (Pub/Sub, AMQP) in tests; omit `topic`, `exchange`, or `queue` attributes, or stub `GcfCommon.response` in tests.
+  - Prefer JS tests under `test/*.test.js` so they run without transpilation.
+- Optional: to run TypeScript tests, use a loader (e.g., `tsx`) or compile first. See `.junie/guidelines.md` for options.
+
+## Commit messages and PRs
+
+- Keep changes small and focused. Reference any related issue in the PR description.
+- Include rationale in code comments for non-obvious behavior.
+- Ensure `npm run build` passes and local tests are green.
+
+## Release process
+
+- Follow semantic versioning (semver). Document notable changes in the README and/or CHANGELOG when applicable.
+- Publishing requires that metadata (description, keywords, license) is set and tests/type-check pass.
+
+## Security
+
+- Do not include secrets in the repository or logs. Prefer environment variables for configuration.
+
+Thanks for contributing!

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 gcf-common maintainers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1 +1,110 @@
-# gcf-common
+# gcf-common-lib
+
+Common helpers for Google Cloud Functions (GCF) and Node services:
+- Orchestrate handlers and conditional response publishing via Pub/Sub or AMQP (RabbitMQ).
+- Utilities: time helpers (ms/sec), Excel A1 conversions, safeJsonParse, simple delay/timeout.
+- Helpers for AMQP and MongoDB lifecycles.
+
+This library targets Node >= 20 and TypeScript. It is designed to be consumed by TS-aware builds or transpiled output.
+
+## Installation
+
+```sh
+npm i gcf-common-lib
+```
+
+## Quick start
+
+### Process an event without network I/O
+Pass a payload without `topic`, `exchange`, or `queue` to avoid publishing in unit tests or offline flows.
+
+```ts
+import { GcfCommon } from 'gcf-common-lib';
+
+export async function handler(payload: any) {
+  return { ok: 1 };
+}
+
+// Example payload: Pub/Sub-like message without routing attributes
+const payload = {
+  event: { '@type': 'type.googleapis.com/google.pubsub.v1.PubsubMessage', json: { hello: 'world' }, attributes: {} },
+  context: undefined,
+};
+
+await GcfCommon.process(payload, handler);
+```
+
+### Publish a response to Pub/Sub
+Set the `topic` attribute in metadata/attributes. Response attributes are coerced to strings; common fields `request_id`, `consumer_id`, `app_id`, `env` are propagated if present.
+
+```ts
+import { GcfCommon } from 'gcf-common-lib';
+
+const payload = {
+  event: { '@type': 'type.googleapis.com/google.pubsub.v1.PubsubMessage', json: {}, attributes: { topic: 'projects/my-proj/topics/my-topic', request_id: 'r1' } },
+  context: undefined,
+};
+
+await GcfCommon.process(payload, async () => ({ result: 42 }));
+// GcfCommon.response() will publish to the provided topic
+```
+
+### Publish a response to AMQP (RabbitMQ)
+Provide either `exchange` (with optional `queue` as routing key) or a `queue`.
+
+```ts
+import { GcfCommon } from 'gcf-common-lib';
+
+GcfCommon.amqpOptions.url = 'amqp://guest:guest@localhost:5672';
+
+const payload = {
+  event: { '@type': 'type.googleapis.com/google.pubsub.v1.PubsubMessage', json: {}, attributes: { exchange: 'events', queue: 'route.key', request_id: 'r1' } },
+  context: undefined,
+};
+
+await GcfCommon.process(payload, async () => ({ result: 42 }));
+```
+
+## API overview
+
+### GcfCommon
+- `process<TResponse, E = TEvent>(payload: TPayload<E>, handler: (p: TPayload<E>) => Promise<any> | any): Promise<any>`
+  - Runs handler, then calls `response(...)` with handler result; on error publishes a structured error via `buildResponse(error)` and rethrows.
+- `response<E = TEvent>(payload: TPayload<E>, json?: TResponse, attributes?: Dict<any>): Promise<void>`
+  - Publishes to Pub/Sub if `topic` is present; to AMQP if `exchange` or `queue` is present. Attributes are stringified.
+- `buildResponse(error: Error): TResponse`
+- `getOptions(payload: TPayload): Promise<Dict<any>>`
+  - Parses JSON from `options` attribute with `safeJsonParse` and `{}` fallback.
+- `getMetadataOrAttribute<E = TEvent>(payload: TPayload<E>): TMetadataOrAttributes`
+  - Extracts attributes from GCS finalize, Pub/Sub publish events, or HTTP request body shape.
+- `getRequestMessage(request: express.Request)`
+
+### Utils
+- `ms({ w?, d?, h?, m?, s? }): number`
+- `sec({ w?, d?, h?, m?, s? }): number`
+- `indexToA1(idx: number): string`
+- `A1ToIndex(value: string): number`
+- `colNumToA1(columnNumber: number): string`
+- `A1ToColNum(value: string): number`
+- `safeJsonParse<T>(value: string, fallback?: T): T | undefined`
+- `delay(seconds: number): Promise<void>`
+- `timeoutAfter(seconds?: number): Promise<void>`
+
+### AmqpHelper
+- `withAmqpConn(fn, url)` — acquire AMQP connection (Bluebird disposer) and run `fn`.
+- `withAmqpCh(fn, url, useConfirmChannel = false, prefetch = 1)` — channel lifecycle helper.
+- `publishAmqp(ch, exchange | undefined, routingKey, json, options?)`
+- `sendToQueueConfAmqp(ch: ConfirmChannel, queue, json, options?)`
+
+### MongoHelper
+- `collectionExists(client, name)`
+- `collectionSafeGet(client, name, options?, afterCreate?)`
+- `withMongoClient(fn, url, options?)` — maintains a shared client in-process.
+
+## Testing
+- Uses Node’s built-in test runner (`node:test`).
+- Prefer JS tests under `test/*.test.js` for zero-transpilation.
+- Avoid network I/O in unit tests by omitting `topic`, `exchange`, and `queue` attributes or by stubbing `GcfCommon.response`.
+
+## License
+MIT. See LICENSE.

package/docs/plan.md

@@ -0,0 +1,211 @@
+# gcf-common-lib: Improvement Plan
+
+Last updated: 2025-08-16
+Owner: gcf-common maintainers
+
+## Purpose and Scope
+This plan translates docs/tasks.md into an actionable roadmap. It sequences work to minimize risk: start with repo hygiene and tests, then architectural refactors, followed by reliability/observability and CI. It is grounded in the current repository state:
+- Node >= 20, TypeScript ^5.3, ESLint flat config; CRLF line endings.
+- tsconfig extends @tsconfig/node20; build does type-checking only (noEmit typical).
+- package.json: main points to "src/index" (TS), no exports/types mapping, minimal scripts, empty license/description.
+- README is nearly empty.
+- GcfCommon in src/index.ts handles orchestration plus direct Pub/Sub/AMQP publishing; commented-out RxJS timeout and safeGetAttributes exist.
+- utils.ts provides pure helpers (ms, sec, A1 conversions, safeJsonParse, timeoutAfter, delay).
+- test/test.ts is TS and triggers network I/O (sets topic=\"test\"); Node cannot run TS tests without a loader by default.
+
+## Guiding Goals and Constraints
+- Keep unit tests deterministic and offline by default; avoid network calls unless explicitly enabled.
+- Support Node 20+ and strict TypeScript; maintain CRLF to avoid noisy diffs.
+- Favor small, incremental changes; document behavioral intent and breaking changes.
+- Distribution decision must be explicit: TS-only consumers vs emitted JS.
+
+## Phased Delivery (Recommended)
+- Phase 0 (Hygiene): Documentation, metadata, scripts, deterministic tests for utilities and core flows.
+- Phase 1 (Architecture): Extract transports and metadata parsing; remove/comment legacy code; introduce timeout mechanics.
+- Phase 2 (Reliability & Observability): Retries/backoff, minimal logger, validation, security/config centralization.
+- Phase 3 (DX & CI): Lint/format, examples, CI workflow, versioning/release.
+
+---
+
+## 1) Documentation and Repository Metadata
+Rationale: Clear docs and metadata reduce onboarding friction and prevent misuse. Current README and package.json lack essential information.
+Actions:
+- Expand README: overview, install, quick start (Pub/Sub + AMQP flows), examples for GcfCommon.process and response behavior.
+- API docs: brief signatures/examples for GcfCommon, AmqpHelper, MongoHelper, utils.
+- Add CONTRIBUTING.md (dev setup, coding standards, testing strategy, release process) and optionally CODE_OF_CONDUCT.md.
+- Set SPDX license in package.json and add LICENSE file.
+- Fill package.json description and keywords.
+Acceptance Criteria:
+- README contains clear quick start and usage examples; package metadata is complete; API sections outline major functions with examples.
+Risks/Mitigations:
+- API drift: Automate with simple typedoc or hand-maintained JSDoc; keep short examples stable.
+
+## 2) Testing Strategy and Coverage
+Rationale: Current tests are TS and trigger network I/O. Node test runner can run JS tests without loaders; pure utilities are ideal.
+Actions:
+- Default runnable tests (no transpilation): add JS tests under test/*.test.js for utils (ms, sec, A1 conversions, safeJsonParse) and core GcfCommon flows without network I/O.
+- Gate network tests behind env flags (e.g., INTEGRATION_PUBSUB=1, INTEGRATION_AMQP=1) and skip by default in CI.
+- Add unit tests for GcfCommon.process that avoid network I/O (omit topic/exchange/queue) including error path and buildResponse.
+- Add tests for getMetadataOrAttribute across GCS finalize, Pub/Sub publish, and HTTP request payloads (using request body shape).
+- Optional TS tests: if kept, add loader (tsx) and npm script: "test:ts": "node --test --import tsx .\\test\\**/*.ts".
+- Add c8 for coverage and script: "test:coverage".
+Acceptance Criteria:
+- Running `npm test` executes JS tests successfully without external services.
+- Coverage report generated by `npm run test:coverage`; core branches in GcfCommon and utils are covered.
+Risks/Mitigations:
+- Flaky network tests: disabled by default; run only with explicit env flags.
+
+## 3) Build and Packaging
+Rationale: package.json points to TS entry; consumers without TS loaders may fail. Decision needed for distribution model.
+Decision Path:
+- Option A (TS-only, default recommendation short-term):
+  - Add "types": "src/index.d.ts" (or rely on TS source types), and an "exports" map that points to source for TS-aware builds. Document that consumers need TS transpilation.
+- Option B (Emit JS):
+  - Add tsconfig.build.json (noEmit: false, outDir: dist). Update scripts: build, clean, prepare. Add exports/types pointing to dist.
+- Validate CJS/ESM interop.
+Acceptance Criteria:
+- Readme states model explicitly; package.json has correct fields; a simple consumer setup works for both ESM/CJS.
+Risks/Mitigations:
+- Breaking resolution for existing consumers: publish as minor with clear note; provide migration guide.
+
+## 4) Architectural Separation of Concerns
+Rationale: GcfCommon.response mixes transport concerns; separation improves testability and reliability features (retries, backoff).
+Actions:
+- Extract PubSubTransport and AmqpTransport implementing a common interface: publish(payload, json, attributes, context).
+- Extract metadata/attributes parsing into a utility with explicit type guards; unify attribute coercion to strings.
+- Keep GcfCommon.process focused on orchestration (handler, timeout, and delegating response publishing).
+Acceptance Criteria:
+- response() delegates to transport(s) selected by metadata; core orchestration has no direct SDK calls.
+Risks/Mitigations:
+- Refactor risk: Introduce transports behind current API; maintain functional parity first.
+
+## 5) Reliability: Retries, Timeouts, Backoff
+Rationale: Network calls fail transiently; timeouts prevent unbounded work.
+Actions:
+- Implement configurable retries with exponential backoff and jitter for Pub/Sub and AMQP publishes (max attempts, base delay).
+- Add configurable timeout to GcfCommon.process using AbortController or Promise.race. Remove/comment the RxJS approach entirely or guard behind feature flag.
+- Document idempotency: propagate correlationId/request_id; ensure publish options set correlationId where applicable.
+Acceptance Criteria:
+- Transient publish failures are retried; process() can be configured to timeout; RxJS code is removed or feature-flagged.
+
+## 6) Logging and Observability
+Rationale: console.log is noisy and unstructured.
+Actions:
+- Introduce minimal logger interface with levels (debug/info/warn/error) and structured context (request_id, app_id, env).
+- Add debug logs around metadata extraction and transport selection; redact sensitive fields.
+- Provide hooks to plug external loggers (e.g., pass in a logger or set a factory) without hard dependency.
+Acceptance Criteria:
+- No direct console.log in core paths; structured logs present; redaction rules applied.
+
+## 7) Input Validation and Typing
+Rationale: Inputs come from varied sources (Pub/Sub, GCS, HTTP) and may be ill-formed.
+Actions:
+- Validate/normalize metadata/attributes (ensure strings; verify topic/exchange/queue formats).
+- Make getOptions generic: getOptions<T = Dict<any>>(...): Promise<T> with optional schema (e.g., zod) for runtime validation; still use safeJsonParse fallback.
+- Tighten TResponse typing; mark readonly where applicable; optionally add branded identifiers (RequestId, ConsumerId).
+Acceptance Criteria:
+- Invalid metadata is rejected or sanitized; getOptions infers type with optional runtime validation.
+
+## 8) AMQP Helper Modernization
+Rationale: Modern async/await patterns improve clarity; configuration should be validated.
+Actions:
+- Replace Bluebird disposers with async/await and try/finally (retain confirm channel variant as needed).
+- Validate connection URL and emit clear error when amqpOptions.url is missing.
+- Support configurable prefetch and confirm mode in options.
+- Implement publish backpressure handling and retries with reconnection on channel/connection errors.
+Acceptance Criteria:
+- AmqpHelper uses async/await; fails fast on missing URL; supports prefetch/confirm; has retry/reconnect logic.
+
+## 9) Mongo Client Lifecycle and Locking
+Rationale: Avoid global leaks; ensure resilience.
+Actions:
+- Review MongoHelper.withMongoClient; manage a shared client with health checks or expose a close method.
+- Add ping/healthcheck and transient error handling.
+- Deprecate MongoLock formally (annotate, document alternative using findOneAndUpdate with TTL index).
+Acceptance Criteria:
+- Predictable client lifecycle; documented locking alternative; healthcheck passes under transient faults.
+
+## 10) Dead Code and Comments Cleanup
+Rationale: Commented code increases confusion.
+Actions:
+- Remove or finalize the commented RxJS timeout code in GcfCommon.
+- Remove the commented safeGetAttributes path or implement a proper version that fetches Storage metadata when needed.
+- Add JSDoc for public APIs and rationale for non-obvious behavior.
+Acceptance Criteria:
+- No stale commented blocks; public APIs carry JSDoc.
+
+## 11) Pub/Sub Specifics and Payload Handling
+Rationale: Attribute types and size limits matter for reliability.
+Actions:
+- Validate attribute sizes and JSON payload limits; document constraints.
+- Consider enabling message ordering; document how to set ordering keys.
+- Ensure attributes are consistently strings; add a helper for coercion (already partially in response()).
+Acceptance Criteria:
+- Publishing respects constraints; ordering documented; attributes normalized.
+
+## 12) Security and Configuration
+Rationale: Sensitive config should be centralized and redacted in logs.
+Actions:
+- Centralize configuration (AMQP URL, Pub/Sub defaults) with environment variable support and typed config loader.
+- Redact sensitive fields in logs and propagate only safe metadata to responses.
+- Run `npm audit` regularly; schedule weekly dependency update checks.
+Acceptance Criteria:
+- Single config source with types; logs redact secrets; audit script/process documented.
+
+## 13) Linting, Formatting, and Scripts
+Rationale: Consistency and quick feedback loops.
+Actions:
+- Add npm scripts: "lint", "lint:fix", "format"; ensure Prettier integration.
+- Consider enabling additional ESLint rules (promise rules, no-floating-promises) where pragmatic.
+- Add .editorconfig to enforce CRLF and common conventions.
+Acceptance Criteria:
+- Lint and format run clean; repo observes CRLF and style conventions.
+
+## 14) Continuous Integration
+Rationale: Automated checks ensure quality across environments.
+Actions:
+- Add GitHub Actions workflow (Node 20.x) to run lint, type-check, and unit tests (JS tests only by default). Cache npm and enable problem matchers.
+Acceptance Criteria:
+- CI runs on PRs and main; caches dependencies; surfaces lint/type/test results quickly.
+
+## 15) Examples and Developer Experience
+Rationale: Concrete examples accelerate adoption and testing.
+Actions:
+- Add examples/ with a minimal handler using GcfCommon.process showing both no-network and networked responses.
+- Document how to stub response publishing in tests; show amqpOptions runtime configuration.
+Acceptance Criteria:
+- Copy-pasteable examples work locally; docs describe stubbing approach and config patterns.
+
+## 16) Versioning and Release Process
+Rationale: Predictable releases and migration guidance.
+Actions:
+- Adopt semantic versioning explicitly; add CHANGELOG and automate release notes (GitHub Releases).
+- Document any breaking changes from architectural refactors and provide migration steps.
+Acceptance Criteria:
+- CHANGELOG maintained; releases include notes; migration guides exist for breaking changes.
+
+---
+
+## Prioritized Backlog (First Pass)
+1) Phase 0
+- README overhaul; package.json metadata; LICENSE.
+- JS unit tests for utils and GcfCommon.process (no network). Add c8 coverage.
+- Add npm scripts: lint, format; ensure ESLint/Prettier run.
+
+2) Phase 1
+- Extract transports (PubSubTransport, AmqpTransport) and metadata parsing utility.
+- Implement process() timeout (AbortController/Promise.race). Remove RxJS commented code.
+
+3) Phase 2
+- Retry/backoff with jitter for publishes; attribute coercion helper; input validation.
+- Minimal logger and redaction; central config loader.
+
+4) Phase 3
+- CI workflow; examples/; decide and implement distribution model (TS-only short-term or emit JS) and document.
+- Versioning: CHANGELOG and release notes automation.
+
+## Acceptance Gates per Phase
+- Phase 0 Gate: `npm test` passes offline; README explains usage; coverage report available; lint/format scripts present.
+- Phase 1 Gate: response() delegates to transports; process() timeout configurable; no stale commented code.
+- Phase 2 Gate: retries and validation in place; structured logging with redaction; config centralized.
+- Phase 3 Gate: CI green on PRs; examples runnable; packaging decision implemented and documented; release notes process live.