feat: support extra HTTP headers on API requests

[Nabal22]

Adds a --extra-headers option (and TOLGEE_EXTRA_HEADERS env var) to send extra HTTP headers with every Tolgee API request.

Useful for self-hosted instances behind a gateway (Cloudflare Access, WAF, reverse proxy) that requires auth headers.

Headers are comma-separated Name=Value pairs:
tolgee --extra-headers 'X-Foo=bar,X-Baz=qux' pull

Added unit tests for the parser. eslint, type check, and unit tests pass.

Closes #180

Summary by CodeRabbit

• New Features

  • CLI accepts a --extra-headers option (or TOLGEE_EXTRA_HEADERS) with comma-separated Name=Value pairs to inject custom HTTP headers into API requests; these headers are merged with existing request headers.
  • API client now accepts and exposes extra headers as part of its configuration snapshot.

• Tests

  • Added unit tests for header parsing, trimming, empty-input handling, and error cases.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d90d33c8-9a64-4655-9017-7d051a1cc240

📥 Commits

Reviewing files that changed from the base of the PR and between 1996ff7 and 1d794c4.

📒 Files selected for processing (1)

• src/client/ApiClient.ts

---

Walkthrough

Adds a new --extra-headers CLI option parsed into a header map, extends options and ApiClient types to carry extraHeaders, merges them into request headers, and wires the option into CLI initialization.

Changes

Extra HTTP Headers Support

Layer / File(s)	Summary
Header parsing utility and validation src/utils/extraHeaders.ts, test/unit/extraHeaders.test.ts	parseExtraHeadersArg() parses comma-separated Name=Value pairs into a header record with validation and error handling. Unit tests cover parsing correctness, whitespace trimming, value preservation, empty segments, and malformed input rejection.
Options type and CLI option definition src/options.ts	BaseOptions type extended with optional extraHeaders field. New exported EXTRA_HEADERS CLI option (--extra-headers) wired to TOLGEE_EXTRA_HEADERS and using the parser to convert input strings to header records.
API client header merging src/client/ApiClient.ts	ApiClientProps type updated to include optional extraHeaders. createApiClient() accepts and merges extraHeaders into OpenAPI client request headers. getSettings() now returns extraHeaders in the settings snapshot.
CLI registration and client initialization src/cli.ts	EXTRA_HEADERS option imported and registered as a global CLI option. Parsed extraHeaders from CLI options passed to API client constructor in preHandler.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I hop through flags, commas in tow,
Parsing names and values row by row,
From env to options, then into the call,
Extra headers delivered—quiet and small,
A rabbit's cheer for networking joy!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: support extra HTTP headers on API requests' clearly and specifically describes the main change: adding support for custom HTTP headers to API requests.
Linked Issues check	✅ Passed	The PR fully implements the requirement from issue #180 to allow custom headers on every API request, supporting comma-separated Name=Value pairs with comprehensive parsing and validation.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to implementing the custom headers feature: CLI option handling, API client configuration, header parsing utilities, and tests. No unrelated modifications detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

src/cli.ts (1)

187-187: 💤 Low value

extraHeaders not configurable via .tolgeerc.

Unlike API_KEY_OPT, PROJECT_ID_OPT, etc., EXTRA_HEADERS is registered without .default(config.extraHeaders), so it can only be set via the flag or TOLGEE_EXTRA_HEADERS. If config-file support is desired for parity, wire a default (and extend the Schema); otherwise this is fine as-is.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/cli.ts` at line 187, The EXTRA_HEADERS option is added via
program.addOption(EXTRA_HEADERS) but not wired to the loaded .tolgeerc config;
call EXTRA_HEADERS.default(config.extraHeaders) before program.addOption to use
the config value as the option default, and update the CLI configuration Schema
to include an extraHeaders field so the config parser accepts it (adjust any
types/validation in the Schema to match EXTRA_HEADERS' expected format). Ensure
this change references the EXTRA_HEADERS constant and the config/Schema used
when loading .tolgeerc in the same module.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/client/ApiClient.ts`:
- Around line 72-76: The headers object in ApiClient currently spreads
extraHeaders after USER_AGENT and apiKey, allowing callers to override protected
headers; update the headers creation in ApiClient (the object using USER_AGENT,
apiKey, and extraHeaders) to spread extraHeaders first (i.e., ...extraHeaders,
then 'user-agent': USER_AGENT and 'x-api-key': apiKey) so the CLI-managed
USER_AGENT and x-api-key remain authoritative and cannot be clobbered by
user-supplied headers.

---

Nitpick comments:
In `@src/cli.ts`:
- Line 187: The EXTRA_HEADERS option is added via
program.addOption(EXTRA_HEADERS) but not wired to the loaded .tolgeerc config;
call EXTRA_HEADERS.default(config.extraHeaders) before program.addOption to use
the config value as the option default, and update the CLI configuration Schema
to include an extraHeaders field so the config parser accepts it (adjust any
types/validation in the Schema to match EXTRA_HEADERS' expected format). Ensure
this change references the EXTRA_HEADERS constant and the config/Schema used
when loading .tolgeerc in the same module.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: cee9ee57-7eb4-4a78-8744-48ee14948fde

📥 Commits

Reviewing files that changed from the base of the PR and between c1652fc and 1996ff7.

📒 Files selected for processing (5)

• src/cli.ts
• src/client/ApiClient.ts
• src/options.ts
• src/utils/extraHeaders.ts
• test/unit/extraHeaders.test.ts