Experimental/zod validation

[cb-alish]

Zod based validation for the Request Query/Body Parameters.

[snyk-io]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[hivel-marco]

PR Complexity Score: 3.6 - Simple

View Breakdown

• Lines Changed: 184
• Files Changed: 13
• Complexity Added: 9
• Raw Score: 56.18

⚠️ Sensitive Data (PII/ Secrets) Detected

File	Types	Count
package-lock.json Line Type Preview 1292 Secret: Base64 High Entropy String [Base64 High Entropy String]	Base64 High Entropy String	1

Overview

This PR introduces optional request parameter validation using Zod schemas for POST actions in the Chargebee SDK. When enabled, requests are validated against action-specific schemas before the HTTP call, and a new ChargebeeZodValidationError is thrown on failures. It also adds a lazy schema loader that pulls validation schemas from generated files and exposes the new error class across ESM/CJS entry points.

Key Changes

• Adds enableValidation?: boolean to the environment/config types and public Chargebee.configure options to allow opt-in Zod-based request validation.
• Introduces a lazy-loading mechanism (validationLoader.getSchema) that locates and caches Zod schemas per {resource, action} from cjs/validation/... using a naming convention compatible with the SDK generator.
• Extends CreateChargebee to attach a validationSchema to each POST API call when validation is enabled, using getSchema to retrieve the appropriate Zod schema.
• Updates RequestWrapper to run schema.safeParse(params) for POST calls when enableValidation and validationSchema are present, throwing a new ChargebeeZodValidationError on any validation errors.
• Adds and exports a dedicated ChargebeeZodValidationError class that formats all Zod issues into a descriptive error message and exposes the underlying ZodError to consumers.
• Declares and exports ChargebeeZodValidationError in both CJS and ESM entry points (including worker variants) and updates type declarations so downstream TypeScript projects can catch and use it.
• Adds zod as a runtime dependency to support schema-based validation.

Risks & Considerations

• Validation currently runs only for POST actions with a discovered schema; other methods (GET, PUT, etc.) remain unvalidated even when enableValidation is true.
• The schema loader assumes specific file and symbol naming conventions (./validation/{resource}/{action}.validation.js and {camelAction}{PascalResource}BodySchema); discrepancies in generated validation files will result in schemas not being found (no validation) rather than explicit failures.
• The loader uses process.cwd() and createRequire to resolve the Chargebee CJS entry and validation files; atypical runtime environments, custom module resolution, or bundlers may impact its ability to locate schemas.
• Enabling validation may surface previously silent client-side parameter issues as runtime errors, potentially breaking existing integrations that relied on server-side validation only.

File-level change summary

File	Change summary
package-lock.json	Adds zod as a production dependency and records its resolved metadata.
package.json	Declares zod under dependencies for runtime use.
src/RequestWrapper.ts	Adds optional Zod-based parameter validation for POST calls and throws ChargebeeZodValidationError on failure.
src/chargebee.cjs.ts	Exports ChargebeeZodValidationError from the CommonJS entry point.
src/chargebee.cjs.worker.ts	Imports and re-exports ChargebeeZodValidationError from the worker CJS entry.
src/chargebee.esm.ts	Exports ChargebeeZodValidationError from the ESM entry point.
src/chargebee.esm.worker.ts	Exports ChargebeeZodValidationError from the worker ESM entry.
src/chargebeeZodValidationError.ts	Introduces an error class that wraps Zod errors and formats validation issues per action.
src/createChargebee.ts	Wires in lazy schema loading, attaching validationSchema to POST endpoints when validation is enabled.
src/types.d.ts	Extends internal Env and Config types and ResourceType with enableValidation and optional Zod validationSchema.
src/validationLoader.ts	Adds a lazy schema loader that resolves, caches, and returns Zod schemas based on resource and action naming conventions.
types/core.d.ts	Updates public Chargebee.configure options to include the enableValidation flag.
types/index.d.ts	Extends the public config type with enableValidation and declares the ChargebeeZodValidationError class for consumers.

[hivel-marco]

PR Complexity Score: 2.2 - Simple

View Breakdown

• Lines Changed: 103
• Files Changed: 6
• Complexity Added: 2
• Raw Score: 23.06

⚠️ Sensitive Data (PII/ Secrets) Detected

File	Types	Count
package-lock.json Line Type Preview 1292 Secret: Base64 High Entropy String [Base64 High Entropy String]	Base64 High Entropy String	1

Overview

This PR introduces optional request parameter validation using Zod for the Chargebee SDK. When enabled via a new enableValidation flag, SDK methods validate their input parameters against action-specific schemas before making HTTP calls, throwing a structured error on failure. The change touches request construction, environment/config types, error types, and documentation.

Key Changes

• Added an enableValidation configuration flag to the SDK’s config/environment types, allowing callers to opt into parameter validation for all requests that have associated Zod schemas.
• Introduced a new ChargebeeZodValidationError class that is thrown when validation fails, exposing actionName and the underlying ZodError for programmatic handling.
• Updated CreateChargebee to load and attach per-action Zod schemas (via getSchema) to apiCall metadata when validation is enabled.
• Extended RequestWrapper to validate query parameters (using params ?? {} for GET) and body parameters (when non-null for non-GET) against the attached schema before sending the HTTP request.
• Documented the new Zod-based validation behavior in the README, including configuration, usage examples, and an example error message.

Risks & Considerations

• Enabling enableValidation may surface validation errors in existing integrations that previously passed invalid or out-of-spec parameters, potentially requiring client-side fixes.
• The distinction between validating {} for omitted GET params and skipping validation for null params on non-GET requests is subtle and may lead to different behavior than expected if callers rely on null vs. undefined.
• The behavior depends on the completeness and correctness of the shipped Zod schemas; gaps or mismatches between schemas and API behavior could cause false positives or missed validations.
• Performance impact should be minimal for most use cases, but high-throughput clients may want to be aware of the extra Zod parsing work when enableValidation is turned on.

File-level change summary

File	Change summary
README.md	Documented the new Zod-based request parameter validation feature, configuration, usage, and example error messages.
src/RequestWrapper.ts	Added Zod-based parameter validation logic that runs before HTTP calls when enableValidation and an action validationSchema are present, throwing ChargebeeZodValidationError on failure.
src/createChargebee.ts	Wired in schema loading via getSchema and attached validationSchema to API call metadata when validation is enabled in the environment.
src/types.d.ts	Extended EnvType, Config, and ResourceType to support the enableValidation flag and an optional Zod validationSchema per action.
types/core.d.ts	Updated the public Config declaration to include the optional enableValidation flag.
types/index.d.ts	Exposed the enableValidation flag and declared the new ChargebeeZodValidationError class in the public TypeScript typings.

[hivel-marco]

PR Complexity Score: 2.3 - Simple

View Breakdown

• Lines Changed: 122
• Files Changed: 3
• Complexity Added: 9
• Raw Score: 24.94

⚠️ Sensitive Data (PII/ Secrets) Detected

File	Types	Count
package-lock.json Line Type Preview 1292 Secret: Base64 High Entropy String [Base64 High Entropy String]	Base64 High Entropy String	1

Overview

This PR introduces optional request parameter validation using Zod schemas for Chargebee API calls. It adds a lazy validation schema loader that works in both CJS and ESM contexts, and a dedicated error type for validation failures. The TypeScript declarations are updated to expose the new enableValidation option and the ChargebeeZodValidationError class.

Key Changes

• Adds enableValidation?: boolean to the Chargebee configuration, enabling opt-in validation of request parameters against Zod schemas before making API calls (for actions that have schemas).
• Introduces a ChargebeeZodValidationError class that wraps Zod’s ZodError, formats a human-readable message including the action name and issue paths, and exposes the original Zod error for programmatic inspection.
• Implements a lazy getSchema loader that resolves and caches action-specific Zod schemas from the chargebee CJS package’s cjs/validation directory, converting resource/action names between camelCase, PascalCase, and snake_case to match generator naming conventions.
• Ensures schema loading works from both CJS and ESM consumers by using createRequire anchored at the resolved chargebee CJS entry file, and returns null when no schema exists for a given resource/action pair.

Risks & Considerations

• The schema loader relies on resolving the chargebee CJS entry via process.cwd() and package.json; unusual project layouts or non-standard module resolution setups might break schema loading.
• Name transformations (camelCase ↔ snake_case ↔ PascalCase) must stay aligned with the generator’s JoiNamingStrategy.bodySchemaName; future changes in naming conventions could desynchronize schema discovery.
• Validation only applies where schemas exist; consumers must handle mixed behaviour where some actions are validated and others are not.
• Misconfigured or missing Zod schemas may surface as ChargebeeZodValidationError or silent null schema loads; reviewers should confirm that failure modes and error messaging are appropriate for their use cases.

File-level change summary

File	Change summary
src/chargebeeZodValidationError.ts	Adds a dedicated ChargebeeZodValidationError class that formats Zod validation issues and stores the associated action name and original ZodError.
src/validationLoader.ts	Implements a lazy, cached schema loader that resolves Zod validation schemas from the chargebee CJS package based on resource and action naming conventions.
types/index.d.ts	Extends the Chargebee config with an enableValidation flag and declares the ChargebeeZodValidationError class for TypeScript consumers.