feat(init): validate config at entry — close #15, #18

[AndresL230]

Summary

• Adds synchronous validateConfig(config) (src/core/validate-config.ts) called at the top of init(), before any side effects (interceptor patch, timer, transport).
• Closes Node SDK cloud mode accepts empty projectId, produces 404 URLs #15 (Critical): cloud mode no longer accepts an empty projectId and produces /projects//telemetry 404s — init() throws with a dashboard link instead.
• Closes Mode detection is silent — invalid API key auto-enters cloud mode and fails #18 (Medium): malformed apiKey (non-rc- prefix, literal string "undefined", empty) is rejected at init with an actionable message; secret is redacted to an 8-char preview in the error.
• Local mode (no apiKey) remains validation-free.

Behavior change

Previously-broken cloud configs (silent 404s or 401s forever) now throw at init(). No real telemetry is lost — these users were never shipping data. Consider a 0.2.0 bump and a "Breaking" callout if you want to signal the new throwing contract explicitly.

Test plan

• 13 unit tests for validateConfig (tests/validate-config.test.ts)
• 7 integration tests in tests/init.test.ts pinning that throws gate the interceptor install (regression contract: isInstalled() === false after throw)
• Full suite: 212/212 unit + 7/7 dist bundle tests pass
• npm run lint clean
• npm run build clean (ESM + CJS + DTS)
• Manual sanity: node -e "require('./dist/cjs/index.cjs').init({apiKey:'bad'})" throws with the expected message

Closes #15
Closes #18

Summary by CodeRabbit

• New Features

  • SDK now performs synchronous configuration validation at initialization, requiring cloud-mode configurations to have a properly-formatted API key and project ID, while local mode requires no validation.

• Documentation

  • Updated README with validation behavior details for both cloud and local modes.

• Tests

  • Added comprehensive test coverage for configuration validation scenarios.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 22a52825-32c1-44ca-8fc7-c4335a1f7b78

📥 Commits

Reviewing files that changed from the base of the PR and between 49f0da5 and 7f37c88.

📒 Files selected for processing (5)

• README.md
• src/core/validate-config.ts
• src/init.ts
• tests/init.test.ts
• tests/validate-config.test.ts

---

📝 Walkthrough

Walkthrough

This PR adds synchronous pre-flight validation to the ReCost Node SDK's init() function. When cloud mode is enabled (via apiKey), the SDK now rejects invalid configurations immediately: apiKey must start with "rc-" and projectId must be non-empty. Local mode requires no validation. Invalid configs throw before any SDK installation occurs.

Changes

Configuration validation for cloud mode

Layer / File(s)	Summary
Validation rules, unit tests, and documentation src/core/validate-config.ts, tests/validate-config.test.ts, README.md	validateConfig() enforces apiKey format ("rc-" prefix) and requires non-empty projectId in cloud mode. Errors include dashboard URL and redacted key previews. Unit tests verify all acceptance/rejection cases, error-message safety, and local-mode exemption. README documents validation behavior for users.
Init flow integration and end-to-end tests src/init.ts, tests/init.test.ts	init() imports and invokes validateConfig() after the enabled gate, failing fast before interceptor installation. Existing resilience tests updated to use valid cloud-mode config. New test suite verifies invalid configs throw before isInstalled() returns true, and that a failed init() does not leave a stale module-level handle.

Sequence Diagram

sequenceDiagram
  participant Caller
  participant init
  participant validateConfig
  participant Transport
  Caller->>init: init(config)
  init->>init: check enabled gate
  alt enabled is false
    init-->>Caller: return disabled handle
  else enabled is true
    init->>validateConfig: validateConfig(config)
    alt invalid config
      validateConfig-->>Caller: throw Error
    else valid config
      validateConfig-->>init: return
      init->>Transport: install interceptor
      init->>init: start flush timer
      init-->>Caller: return handle
    end
  end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 The rabbits hop through configs true,
Validation guards what users do—
No empty keys, no missing projectId sight,
Cloud mode now fails fast, before the flight! 🚀

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(init): validate config at entry — close #15, #18' accurately summarizes the main change: adding configuration validation at SDK initialization entry point.
Linked Issues check	✅ Passed	The PR fully implements requirements from #15 and #18: validates projectId presence in cloud mode, rejects malformed apiKey values, redacts secrets in errors, maintains local-mode validation-free behavior, and includes comprehensive unit and integration tests.
Out of Scope Changes check	✅ Passed	All changes are tightly scoped to configuration validation at init: new validateConfig module, init integration, comprehensive tests, and README documentation of validation behavior.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/init-config-validation

---

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.}