chargebee 3.26.0 → 3.28.0

package/esm/telemetry/otel.js

@@ -0,0 +1,62 @@
+/*
+ * This file is auto-generated by Chargebee.
+ * For more information on how to make changes to this file, please see the README.
+ * Reach out to dx@chargebee.com for any questions.
+ * Copyright 2026 Chargebee Inc.
+ */
+import { context, propagation, SpanKind, SpanStatusCode, trace, } from '@opentelemetry/api';
+import { CHARGEBEE_SDK_NAME, } from './types.js';
+const tracer = trace.getTracer(CHARGEBEE_SDK_NAME);
+function toRecordedException(error) {
+    var _a;
+    const exception = new Error(error.message);
+    exception.name = (_a = error.chargebeeErrorCode) !== null && _a !== void 0 ? _a : 'ChargebeeAPIError';
+    return exception;
+}
+/**
+ * Ready-to-use OpenTelemetry adapter for the Chargebee SDK.
+ *
+ * Each SDK request becomes a CLIENT span attached to the active OpenTelemetry
+ * context (or a root span when none is active), and the W3C trace context is
+ * propagated to Chargebee so the trace continues server-side.
+ *
+ * Exporting (endpoint, service name, credentials) is configured by your own
+ * OpenTelemetry runtime via the standard `OTEL_*` environment variables — this
+ * adapter only uses the globally registered tracer from `@opentelemetry/api`.
+ *
+ * `@opentelemetry/api` is an optional peer dependency; install it to use this
+ * adapter. A default-exported, ready-to-use instance is provided.
+ */
+export class OtelTelemetryAdapter {
+    onRequestStart(ctx, requestHeaders) {
+        // startSpan adopts the active context's span as parent (or starts a root span if none).
+        const span = tracer.startSpan(ctx.spanName, {
+            kind: SpanKind.CLIENT,
+            attributes: ctx.startAttributes,
+        });
+        // Propagate W3C trace context to Chargebee so the trace continues server-side.
+        propagation.inject(trace.setSpan(context.active(), span), requestHeaders);
+        return span;
+    }
+    onRequestEnd(span, result) {
+        if (!span) {
+            return;
+        }
+        for (const [key, value] of Object.entries(result.endAttributes)) {
+            span.setAttribute(key, value);
+        }
+        if (result.error) {
+            span.recordException(toRecordedException(result.error));
+            span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: result.error.message,
+            });
+        }
+        else {
+            span.setStatus({ code: SpanStatusCode.OK });
+        }
+        span.end();
+    }
+}
+const otelDefaultAdapter = new OtelTelemetryAdapter();
+export default otelDefaultAdapter;

package/esm/telemetry/types.js

@@ -0,0 +1,44 @@
+/*
+ * This file is auto-generated by Chargebee.
+ * For more information on how to make changes to this file, please see the README.
+ * Reach out to dx@chargebee.com for any questions.
+ * Copyright 2026 Chargebee Inc.
+ */
+/** SDK identifier recorded on telemetry spans. */
+export const CHARGEBEE_SDK_NAME = 'chargebee-node';
+/** Standard span name prefix: chargebee.{resource}.{operation} */
+export const TELEMETRY_SPAN_NAME_PREFIX = 'chargebee';
+/**
+ * OTel HTTP semantic-convention prefix for request-header attributes:
+ * `http.request.header.<lowercased-name>` with string[] values.
+ */
+export const HTTP_REQUEST_HEADER_ATTRIBUTE_PREFIX = 'http.request.header.';
+/**
+ * Request headers whose (lowercased) name starts with this prefix are captured as span
+ * attributes. Using a prefix instead of a fixed list means any future `chargebee-*` header
+ * is picked up automatically, with no SDK upgrade required.
+ */
+export const CHARGEBEE_TELEMETRY_HEADER_PREFIX = 'chargebee-';
+/**
+ * Headers under this sub-prefix carry end-user PII (origin IP, email, device) and are
+ * excluded from spans by default. Chargebee namespaces such headers under
+ * `chargebee-request-origin-*`, so future PII headers stay excluded automatically.
+ */
+export const CHARGEBEE_TELEMETRY_HEADER_EXCLUDE_PREFIX = 'chargebee-request-origin-';
+/** Span attribute keys — shared across Chargebee SDKs. */
+export const TelemetryAttributeKeys = {
+    URL_FULL: 'url.full',
+    HTTP_REQUEST_METHOD: 'http.request.method',
+    HTTP_RESPONSE_STATUS_CODE: 'http.response.status_code',
+    SERVER_ADDRESS: 'server.address',
+    ERROR_TYPE: 'error.type',
+    CHARGEBEE_SITE: 'chargebee.site',
+    CHARGEBEE_API_VERSION: 'chargebee.api_version',
+    CHARGEBEE_RESOURCE: 'chargebee.resource',
+    CHARGEBEE_OPERATION: 'chargebee.operation',
+    CHARGEBEE_SDK_NAME: 'chargebee.sdk.name',
+    CHARGEBEE_SDK_VERSION: 'chargebee.sdk.version',
+    CHARGEBEE_ERROR_CODE: 'chargebee.error.code',
+    CHARGEBEE_ERROR_TYPE: 'chargebee.error.type',
+    CHARGEBEE_ERROR_PARAM: 'chargebee.error.param',
+};

package/esm/validationLoader.js

@@ -0,0 +1,56 @@
+/**
+ * Lazy schema loader for opt-in Zod validation.
+ *
+ * Schemas are loaded on first use. Node.js automatically caches imported modules,
+ * so repeated imports of the same schema file are efficient.
+ *
+ * Each resource module lives at {@code schema/<resource_snake>.schema.ts}
+ * and exports one body schema per action.
+ *
+ * The body schema const name follows {@code ZodNamingStrategy.bodySchemaName} in sdk-generator:
+ * {@code {PascalAction}{PascalResource}BodySchema}
+ *
+ * Uses native dynamic import() - TypeScript transpiles appropriately for ESM/CJS targets.
+ */
+function toCamel(s) {
+    return s.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+function toPascal(s) {
+    const camel = toCamel(s);
+    return camel.charAt(0).toUpperCase() + camel.slice(1);
+}
+/** Matches ZodNamingStrategy.bodySchemaName() in sdk-generator. */
+function schemaConstName(resourceKey, actionName) {
+    return toPascal(actionName) + toPascal(resourceKey) + 'BodySchema';
+}
+/** camelCase resource key → snake_case module basename (e.g. virtualBankAccount → virtual_bank_account). */
+function resourceSchemaBasename(resourceKey) {
+    return resourceKey
+        .replace(/([A-Z])/g, '_$1')
+        .toLowerCase()
+        .replace(/^_/, '');
+}
+/**
+ * Load the Zod schema for a given resource + action.
+ * Returns null if no schema file exists for this combination.
+ *
+ * Node.js automatically caches the imported modules, so repeated calls
+ * for the same resource will reuse the cached module.
+ *
+ * TypeScript compiler handles module system differences:
+ * - ESM build: keeps await import() as-is
+ * - CJS build: transpiles to require() or Promise-based equivalent
+ */
+export async function getSchema(resourceKey, actionName) {
+    var _a;
+    const base = resourceSchemaBasename(resourceKey);
+    const constName = schemaConstName(resourceKey, actionName);
+    try {
+        const mod = await import(`./schema/${base}.schema.js`);
+        const schema = (_a = mod[constName]) !== null && _a !== void 0 ? _a : null;
+        return schema;
+    }
+    catch (_b) {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chargebee",
-  "version": "3.26.0",
+  "version": "3.28.0",
   "description": "A library for integrating with Chargebee.",
   "scripts": {
     "prepack": "npm install && npm run build",
@@ -34,33 +34,49 @@
     }
   ],
   "exports": {
-    "types": "./types/index.d.ts",
-    "browser": {
-      "import": "./esm/chargebee.esm.worker.js",
-      "require": "./cjs/chargebee.cjs.worker.js"
+    ".": {
+      "types": "./types/index.d.ts",
+      "browser": {
+        "import": "./esm/chargebee.esm.worker.js",
+        "require": "./cjs/chargebee.cjs.worker.js"
+      },
+      "worker": {
+        "import": "./esm/chargebee.esm.worker.js",
+        "require": "./cjs/chargebee.cjs.worker.js"
+      },
+      "workerd": {
+        "import": "./esm/chargebee.esm.worker.js",
+        "require": "./cjs/chargebee.cjs.worker.js"
+      },
+      "deno": {
+        "import": "./esm/chargebee.esm.worker.js",
+        "require": "./cjs/chargebee.cjs.worker.js"
+      },
+      "bun": {
+        "import": "./esm/chargebee.esm.worker.js",
+        "require": "./cjs/chargebee.cjs.worker.js"
+      },
+      "default": {
+        "import": "./esm/chargebee.esm.js",
+        "require": "./cjs/chargebee.cjs.js"
+      }
     },
-    "worker": {
-      "import": "./esm/chargebee.esm.worker.js",
-      "require": "./cjs/chargebee.cjs.worker.js"
-    },
-    "workerd": {
-      "import": "./esm/chargebee.esm.worker.js",
-      "require": "./cjs/chargebee.cjs.worker.js"
-    },
-    "deno": {
-      "import": "./esm/chargebee.esm.worker.js",
-      "require": "./cjs/chargebee.cjs.worker.js"
-    },
-    "bun": {
-      "import": "./esm/chargebee.esm.worker.js",
-      "require": "./cjs/chargebee.cjs.worker.js"
-    },
-    "default": {
-      "import": "./esm/chargebee.esm.js",
-      "require": "./cjs/chargebee.cjs.js"
+    "./telemetry/otel": {
+      "types": "./types/telemetry/otel.d.ts",
+      "import": "./esm/telemetry/otel.js",
+      "require": "./cjs/telemetry/otel.js"
+    }
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.9.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
     }
   },
   "devDependencies": {
+    "@opentelemetry/api": "^1.9.0",
     "@types/chai": "^4.3.5",
     "@types/mocha": "^10.0.10",
     "@types/node": "20.12.0",
@@ -75,5 +91,8 @@
     "semi": true,
     "singleQuote": true,
     "parser": "typescript"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
   }
 }

package/types/core.d.ts

@@ -5,6 +5,8 @@ declare module 'chargebee' {
     timeout?: number;
     timemachineWaitInMillis?: number;
     exportWaitInMillis?: number;
+    /** When true, request parameters are validated against Zod schemas before each HTTP call (where a schema exists). */
+    enableValidation?: boolean;
   }
   export type ChargebeeResponse<T> = T & {
     headers: { [key: string]: string };

package/types/index.d.ts

@@ -168,12 +168,86 @@ declare module 'chargebee' {
      * @httpClient optional http client implementation, default http client will be used if not provided
      */
     httpClient?: HttpClientInterface;
+
+    /**
+     * @telemetryAdapter optional telemetry adapter for observability (e.g. OpenTelemetry)
+     */
+    telemetryAdapter?: TelemetryAdapter;
+
+    /**
+     * @enableValidation When true, every request's parameters are validated against each endpoint's generated Zod schema before the HTTP request is sent. Violations throw `ChargebeeZodValidationError` with structured Zod issues. Calls with no params argument are validated as `{}`. Required resource ids in the URL path are still checked separately.
+     */
+    enableValidation?: boolean;
   };
 
   export interface HttpClientInterface {
     makeApiRequest: (request: Request, timeout: number) => Promise<Response>;
   }
 
+  export type RequestTelemetryHandle = unknown;
+
+  export const TelemetryAttributeKeys: {
+    readonly URL_FULL: 'url.full';
+    readonly HTTP_REQUEST_METHOD: 'http.request.method';
+    readonly HTTP_RESPONSE_STATUS_CODE: 'http.response.status_code';
+    readonly SERVER_ADDRESS: 'server.address';
+    readonly ERROR_TYPE: 'error.type';
+    readonly CHARGEBEE_SITE: 'chargebee.site';
+    readonly CHARGEBEE_API_VERSION: 'chargebee.api_version';
+    readonly CHARGEBEE_RESOURCE: 'chargebee.resource';
+    readonly CHARGEBEE_OPERATION: 'chargebee.operation';
+    readonly CHARGEBEE_SDK_NAME: 'chargebee.sdk.name';
+    readonly CHARGEBEE_SDK_VERSION: 'chargebee.sdk.version';
+    readonly CHARGEBEE_ERROR_CODE: 'chargebee.error.code';
+    readonly CHARGEBEE_ERROR_TYPE: 'chargebee.error.type';
+    readonly CHARGEBEE_ERROR_PARAM: 'chargebee.error.param';
+  };
+
+  export type RequestTelemetryContext = {
+    spanName: string;
+    resource: string;
+    operation: string;
+    httpMethod: string;
+    httpUrl: string;
+    serverAddress: string;
+    chargebeeSite: string;
+    chargebeeApiVersion: 'v1' | 'v2';
+    sdkName: string;
+    sdkVersion: string;
+    /**
+     * Prebuilt span attributes — pass these to your tracer. Captured `chargebee-*` request
+     * headers appear as `http.request.header.<name>` with string[] values per OTel semconv.
+     */
+    startAttributes: Record<string, string | string[]>;
+  };
+
+  export type RequestTelemetryError = {
+    message: string;
+    chargebeeErrorCode?: string;
+    chargebeeApiErrorType?: string;
+    chargebeeErrorParam?: string;
+  };
+
+  export type RequestTelemetryResult = {
+    httpStatusCode: number;
+    durationMs: number;
+    error?: RequestTelemetryError;
+    /** Prebuilt span attributes — pass these to your tracer. */
+    endAttributes: Record<string, string | number>;
+  };
+
+  /**
+   * Optional telemetry adapter. Implement as a class or plain object — the SDK
+   * keeps it by reference (never deep-cloned). Wire OpenTelemetry or other tools here.
+   */
+  export interface TelemetryAdapter<THandle = RequestTelemetryHandle> {
+    onRequestStart(
+      context: RequestTelemetryContext,
+      requestHeaders: Record<string, string | number>,
+    ): THandle | void;
+    onRequestEnd(handle: THandle | void, result: RequestTelemetryResult): void;
+  }
+
   export type RetryConfig = {
     /**
      * @enabled whether to enable retry logic, default value is false
@@ -451,4 +525,15 @@ declare module 'chargebee' {
     name: string;
     readonly rawBody?: string;
   }
+
+  /**
+   * Thrown when `enableValidation` is on and request parameters fail the action's Zod schema.
+   * Carries `actionName` and the original `ZodError` (issues, `flatten()`, etc.) for programmatic handling.
+   */
+  export class ChargebeeZodValidationError extends Error {
+    constructor(actionName: string, zodError: import('zod').ZodError);
+    name: string;
+    readonly actionName: string;
+    readonly zodError: import('zod').ZodError;
+  }
 }

package/types/telemetry/otel.d.ts

@@ -0,0 +1,22 @@
+declare module 'chargebee/telemetry/otel' {
+  import type {
+    RequestTelemetryContext,
+    RequestTelemetryResult,
+    TelemetryAdapter,
+  } from 'chargebee';
+  /**
+   * Ready-to-use OpenTelemetry adapter for the Chargebee SDK. Exporting is
+   * configured by your own OpenTelemetry runtime via the standard `OTEL_*`
+   * environment variables; this adapter only uses the globally registered
+   * tracer from `@opentelemetry/api` (an optional peer dependency).
+   */
+  export class OtelTelemetryAdapter implements TelemetryAdapter {
+    onRequestStart(
+      ctx: RequestTelemetryContext,
+      requestHeaders: Record<string, string | number>,
+    ): unknown;
+    onRequestEnd(handle: unknown, result: RequestTelemetryResult): void;
+  }
+  const otelDefaultAdapter: OtelTelemetryAdapter;
+  export default otelDefaultAdapter;
+}