@flexprice/sdk 1.0.31 → 2.0.1

package/CONTRIBUTING.md

@@ -0,0 +1,26 @@
+# Contributing to This Repository
+
+Thank you for your interest in contributing to this repository. Please note that this repository contains generated code. As such, we do not accept direct changes or pull requests. Instead, we encourage you to follow the guidelines below to report issues and suggest improvements.
+
+## How to Report Issues
+
+If you encounter any bugs or have suggestions for improvements, please open an issue on GitHub. When reporting an issue, please provide as much detail as possible to help us reproduce the problem. This includes:
+
+- A clear and descriptive title
+- Steps to reproduce the issue
+- Expected and actual behavior
+- Any relevant logs, screenshots, or error messages
+- Information about your environment (e.g., operating system, software versions)
+    - For example can be collected using the `npx envinfo` command from your terminal if you have Node.js installed
+
+## Issue Triage and Upstream Fixes
+
+We will review and triage issues as quickly as possible. Our goal is to address bugs and incorporate improvements in the upstream source code. Fixes will be included in the next generation of the generated code.
+
+## Contact
+
+If you have any questions or need further assistance, please feel free to reach out by opening an issue.
+
+Thank you for your understanding and cooperation!
+
+The Maintainers

package/FUNCTIONS.md

@@ -0,0 +1,92 @@
+# Standalone Functions
+
+> [!NOTE]
+> This section is useful if you are using a bundler and targetting browsers and
+> runtimes where the size of an application affects performance and load times. 
+
+Every method in this SDK is also available as a standalone function. This
+alternative API is suitable when targetting the browser or serverless runtimes
+and using a bundler to build your application since all unused functionality
+will be tree-shaken away. This includes code for unused methods, Zod schemas,
+encoding helpers and response handlers. The result is dramatically smaller
+impact on the application's final bundle size which grows very slowly as you use
+more and more functionality from this SDK.
+
+Calling methods through the main SDK class remains a valid and generally more
+more ergonomic option. Standalone functions represent an optimisation for a
+specific category of applications.
+
+## Example
+
+```typescript
+import { FlexpriceCore } from "@flexprice/sdk/core.js";
+import { addonsCreateAddon } from "@flexprice/sdk/funcs/addons-create-addon.js";
+
+// Use `FlexpriceCore` for best tree-shaking performance.
+// You can create one instance of it to use across an application.
+const flexprice = new FlexpriceCore({
+  serverURL: "https://api.example.com",
+  apiKeyAuth: "<YOUR_API_KEY_HERE>",
+});
+
+async function run() {
+  const res = await addonsCreateAddon(flexprice, {
+    lookupKey: "<value>",
+    name: "<value>",
+    type: "multiple_instance",
+  });
+  if (res.ok) {
+    const { value: result } = res;
+    console.log(result);
+  } else {
+    console.log("addonsCreateAddon failed:", res.error);
+  }
+}
+
+run();
+```
+
+## Result types
+
+Standalone functions differ from SDK methods in that they return a
+`Result<Value, Error>` type to capture _known errors_ and document them using
+the type system. By avoiding throwing errors, application code maintains clear
+control flow and error-handling become part of the regular flow of application
+code.
+
+> We use the term "known errors" because standalone functions, and JavaScript
+> code in general, can still throw unexpected errors such as `TypeError`s,
+> `RangeError`s and `DOMException`s. Exhaustively catching all errors may be
+> something this SDK addresses in the future. Nevertheless, there is still a lot
+> of benefit from capturing most errors and turning them into values.
+
+The second reason for this style of programming is because these functions will
+typically be used in front-end applications where exception throwing is
+sometimes discouraged or considered unidiomatic. React and similar ecosystems
+and libraries tend to promote this style of programming so that components
+render useful content under all states (loading, success, error and so on).
+
+The general pattern when calling standalone functions looks like this:
+
+```typescript
+import { Core } from "<sdk-package-name>";
+import { fetchSomething } from "<sdk-package-name>/funcs/fetchSomething.js";
+
+const client = new Core();
+
+async function run() {
+  const result = await fetchSomething(client, { id: "123" });
+  if (!result.ok) {
+    // You can throw the error or handle it. It's your choice now.
+    throw result.error;
+  }
+
+  console.log(result.value);
+}
+
+run();
+```
+
+Notably, `result.error` above will have an explicit type compared to a try-catch
+variation where the error in the catch block can only be of type `unknown` (or
+`any` depending on your TypeScript settings).

package/README.md

@@ -1,337 +1,137 @@
-# FlexPrice JavaScript/TypeScript SDK
+# FlexPrice TypeScript / JavaScript SDK
 
-[![npm version](https://badge.fury.io/js/%40flexprice%2Fsdk.svg)](https://badge.fury.io/js/%40flexprice%2Fsdk)
-[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+Type-safe TypeScript/JavaScript client for the FlexPrice API: billing, metering, and subscription management for SaaS and usage-based products.
 
-Official TypeScript/JavaScript SDK for the FlexPrice API with modern ES7 module support and comprehensive type safety.
+## Requirements
 
-## Features
-
-- ✅ **Full TypeScript Support** - Complete type definitions for all API endpoints
-- ✅ **Modern ES7 Modules** - Native ES modules with CommonJS fallback
-- ✅ **Fetch API** - Built on modern web standards
-- ✅ **Browser Compatible** - Works in Node.js, Webpack, and Browserify
-- ✅ **Promise & Callback Support** - Flexible async patterns
-- ✅ **Comprehensive Documentation** - Auto-generated from OpenAPI specs
-- ✅ **Error Handling** - Detailed error messages and status codes
+- Node.js 18+ (or see [RUNTIMES.md](RUNTIMES.md) for supported runtimes)
 
 ## Installation
 
-### Published Package
-
 ```bash
-npm install @flexprice/sdk --save
+npm i @flexprice/sdk
 ```
 
-### Unpublished (Development)
+With pnpm, bun, or yarn:
 
 ```bash
-npm install PATH_TO_GENERATED_PACKAGE --save
+pnpm add @flexprice/sdk
+bun add @flexprice/sdk
+yarn add @flexprice/sdk
 ```
 
-## Quick Start
-
-### JavaScript (CommonJS)
-
-```javascript
-const FlexPrice = require("@flexprice/sdk");
-require("dotenv").config();
-
-// Configure the API client
-const defaultClient = FlexPrice.ApiClient.instance;
-defaultClient.basePath = "https://api.cloud.flexprice.io/v1";
-
-const apiKeyAuth = defaultClient.authentications["ApiKeyAuth"];
-apiKeyAuth.apiKey = process.env.FLEXPRICE_API_KEY;
-apiKeyAuth.in = "header";
-apiKeyAuth.name = "x-api-key";
-
-// Create an event
-const eventsApi = new FlexPrice.EventsApi();
-const eventRequest = {
-  event_name: "Sample Event",
-  external_customer_id: "customer-123",
-  properties: { source: "javascript_app" },
-  source: "javascript_app",
-  timestamp: new Date().toISOString(),
-};
-
-eventsApi.eventsPost(eventRequest, (error, data, response) => {
-  if (error) {
-    console.error("Error:", error);
-  } else {
-    console.log("Event created:", data);
-  }
-});
-```
+The package supports both CommonJS and ESM.
 
-### TypeScript (ES Modules)
+Then in your code:
 
 ```typescript
-import * as FlexPrice from "@flexprice/sdk";
-import * as dotenv from "dotenv";
-
-dotenv.config();
-
-// Configure the API client with type safety
-const defaultClient = FlexPrice.ApiClient.instance;
-defaultClient.basePath = "https://api.cloud.flexprice.io/v1";
-
-const apiKeyAuth = defaultClient.authentications["ApiKeyAuth"];
-apiKeyAuth.apiKey = process.env.FLEXPRICE_API_KEY!;
-apiKeyAuth.in = "header";
-apiKeyAuth.name = "x-api-key";
-
-// Type-safe API calls
-const eventsApi = new FlexPrice.EventsApi();
-const eventRequest: FlexPrice.DtoIngestEventRequest = {
-  eventName: "Sample Event",
-  externalCustomerId: "customer-123",
-  properties: { source: "typescript_app" },
-  source: "typescript_app",
-  timestamp: new Date().toISOString(),
-};
-
-try {
-  const result = await eventsApi.eventsPost({ event: eventRequest });
-  console.log("Event created:", result);
-} catch (error) {
-  console.error("Error:", error);
-}
-```
-
-### Browser Usage
-
-```html
-<script src="https://cdn.jsdelivr.net/npm/@flexprice/sdk/dist/flexprice-sdk.min.js"></script>
-<script>
-  // Configure the API client
-  const defaultClient = FlexPrice.ApiClient.instance;
-  defaultClient.basePath = "https://api.cloud.flexprice.io/v1";
-
-  const apiKeyAuth = defaultClient.authentications["ApiKeyAuth"];
-  apiKeyAuth.apiKey = "your-api-key-here";
-  apiKeyAuth.in = "header";
-  apiKeyAuth.name = "x-api-key";
-
-  // Use the SDK
-  const eventsApi = new FlexPrice.EventsApi();
-  // ... rest of your code
-</script>
+import { FlexPrice } from "@flexprice/sdk";
 ```
 
-## Environment Support
-
-### Node.js Environments
-
-- Node.js 16+
-- Webpack
-- Browserify
-
-### Language Levels
-
-- ES5 (requires Promises/A+ library)
-- ES6+
-- TypeScript 4.5+
-
-### Module Systems
+**All generated modules** (shared models, enums, errors, operation types, SDK types) are re-exported from the package root so you can import everything from one place. Run `npm run build` before publishing so both ESM and CommonJS entry points (`dist/esm/index.js` and `dist/commonjs/index.js`) include these re-exports; then `import` and `require("flexprice-ts-temp")` both expose types/enums from the root.
 
-- CommonJS
-- ES6 Modules
-- UMD (Universal Module Definition)
-
-## API Reference
-
-### Authentication
-
-All API requests require authentication using an API key:
-
-```javascript
-const apiKeyAuth = defaultClient.authentications["ApiKeyAuth"];
-apiKeyAuth.apiKey = "sk_your_api_key_here";
-apiKeyAuth.in = "header";
-apiKeyAuth.name = "x-api-key";
+```typescript
+import {
+  FlexPrice,
+  FeatureType,
+  Status,
+  FlexpriceError,
+  CreateCustomerRequest,
+  createPageIterator,
+} from "@flexprice/sdk";
+// No need for: .../dist/sdk/models/shared, .../errors, .../operations, .../types
 ```
 
-### Available APIs
-
-- **EventsApi** - Event ingestion and retrieval
-- **CustomersApi** - Customer management
-- **SubscriptionsApi** - Subscription management
-- **InvoicesApi** - Invoice operations
-- **PaymentsApi** - Payment processing
-- **PlansApi** - Plan management
-- **AddonsApi** - Addon management
-- **CouponsApi** - Coupon management
-- **WebhooksApi** - Webhook management
-
-### Common Patterns
-
-#### Creating Events
-
-```javascript
-const eventRequest = {
-  eventName: "user_signup",
-  externalCustomerId: "customer-123",
-  properties: {
-    plan: "premium",
-    source: "website",
-  },
-  source: "web_app",
-  timestamp: new Date().toISOString(),
-};
-
-eventsApi.eventsPost({ event: eventRequest }, callback);
-```
+Runnable samples are in the `examples/` directory.
 
-#### Creating Customers
+## Quick start
 
-```javascript
-const customerRequest = {
-  externalId: "customer-123",
-  email: "user@example.com",
-  name: "John Doe",
-  metadata: {
-    source: "signup_form",
-  },
-};
+Initialize the client with your server URL and API key, then create a customer and ingest an event:
 
-customersApi.customersPost({ customer: customerRequest }, callback);
-```
+```typescript
+import { FlexPrice } from "@flexprice/sdk";
 
-#### Error Handling
-
-```javascript
-eventsApi.eventsPost(eventRequest, (error, data, response) => {
-  if (error) {
-    if (error.status === 401) {
-      console.error("Authentication failed");
-    } else if (error.status === 400) {
-      console.error("Bad request:", error.response.body);
-    } else {
-      console.error("API Error:", error.message);
-    }
-  } else {
-    console.log("Success:", data);
-  }
+// Always include /v1 in the base URL; no trailing space or slash.
+const flexPrice = new FlexPrice({
+  serverURL: "https://us.api.flexprice.io/v1",
+  apiKeyAuth: process.env.FLEXPRICE_API_KEY ?? "YOUR_API_KEY",
 });
-```
-
-## Development
-
-### Building
-
-To build and compile the TypeScript sources to JavaScript:
-
-```bash
-npm install
-npm run build
-```
-
-### Publishing
 
-First build the package then run:
+async function main() {
+  // Create a customer
+  const customer = await flexPrice.customers.createCustomer({
+    externalId: "customer-123",
+    email: "user@example.com",
+    name: "Example Customer",
+  });
+  console.log(customer);
+
+  // Ingest an event (use snake_case for request body fields where required by the API)
+  const eventResult = await flexPrice.events.ingestEvent({
+    eventName: "Sample Event",
+    externalCustomerId: "customer-123",
+    properties: { source: "ts_sdk", environment: "test" },
+    source: "ts_sdk",
+  });
+  console.log(eventResult);
+}
 
-```bash
-npm publish
+main();
 ```
 
-### Testing
-
-```bash
-npm test
-```
+For more examples and all API operations, see the [API reference](https://docs.flexprice.io) and the [examples](examples/) in this repo.
 
-### Linting
+## Property names (snake_case)
 
-```bash
-npm run lint
-npm run lint:fix
-```
+For request bodies, the API often expects **snake_case** field names. The SDK may accept camelCase and serialize to snake_case; if you see validation errors, use the API shape:
 
-## Examples
+- Prefer: `event_name`, `external_customer_id`, `page_size`
+- Avoid using only camelCase in raw payloads if the API spec uses snake_case
 
-### Running JavaScript Example
+Check the [API reference](https://docs.flexprice.io) for the exact request shapes.
 
-```bash
-cd examples
-npm install
-npm start
-```
+## TypeScript
 
-### Running TypeScript Example
+The package ships with TypeScript definitions. Use the client with full type safety:
 
-```bash
-cd examples
-npm install
-npm run start:ts
-```
+```typescript
+import { FlexPrice } from "@flexprice/sdk";
 
-### Building TypeScript Example
+const flexPrice = new FlexPrice({
+  serverURL: "https://us.api.flexprice.io/v1",
+  apiKeyAuth: process.env.FLEXPRICE_API_KEY!,
+});
 
-```bash
-cd examples
-npm run build:ts
-npm run start:built
+const result = await flexPrice.events.ingestEvent({
+  eventName: "usage",
+  externalCustomerId: "cust_123",
+  properties: { units: 10 },
+  source: "backend",
+});
 ```
 
-## Troubleshooting
-
-### Authentication Issues
-
-- Ensure your API key starts with `sk_`
-- Verify the key is active and has required permissions
-- Check that the `x-api-key` header is being sent correctly
-
-### Property Naming
-
-Use the correct property names based on the TypeScript interfaces:
-
-- ✅ TypeScript: `eventName`, `externalCustomerId`, `externalId`
-- ✅ API JSON: `event_name`, `external_customer_id`, `external_id`
-- ❌ Mixed: `event_name` in TypeScript or `eventName` in JSON
-
-### Parameter Passing
-
-Pass parameters in the correct format for each API method:
-
-- ✅ `eventsApi.eventsPost({ event: eventRequest }, callback)`
-- ✅ `customersApi.customersPost({ customer: customerRequest }, callback)`
-- ❌ `eventsApi.eventsPost(eventRequest, callback)` (missing wrapper object)
+## Authentication
 
-### TypeScript Issues
+- Set the API key via `apiKeyAuth` when constructing `FlexPrice`. The SDK sends it in the `x-api-key` header.
+- Use environment variables (e.g. `FLEXPRICE_API_KEY`) and never expose keys in client-side or public code. Get keys from your [FlexPrice dashboard](https://app.flexprice.io) or docs.
 
-- Ensure you have TypeScript 4.5+ installed
-- Use proper type imports: `import * as FlexPrice from '@flexprice/sdk'`
-- Check that your `tsconfig.json` includes the SDK types
-
-### Network Issues
-
-- Verify your internet connection
-- Check firewall/proxy settings
-- Ensure the API host is accessible from your environment
-
-## Browser Considerations
-
-When using in browsers:
-
-- CORS restrictions may apply - ensure your domain is whitelisted
-- Never expose API keys in client-side code
-- Use a proxy or backend service for sensitive operations
-- Some features may be limited in browser environments
-
-## TypeScript Definitions
+## Features
 
-The package includes comprehensive TypeScript definitions that are automatically resolved via `package.json`. All API endpoints, request/response types, and configuration options are fully typed.
+- Full API coverage (customers, plans, events, invoices, payments, entitlements, etc.)
+- TypeScript types for requests and responses
+- Built-in retries and error handling
+- ESM and CommonJS support
 
-## License
+For a full list of operations, see the [API reference](https://docs.flexprice.io) and the [examples](examples/) in this repo.
 
-This SDK is licensed under the MIT License. See the LICENSE file for details.
+## Troubleshooting
 
-## Support
+- **Missing or invalid API key:** Ensure `apiKeyAuth` is set and the key is active. Use server-side only.
+- **Wrong server URL:** Use `https://us.api.flexprice.io/v1`. Always include `/v1`; no trailing space or slash.
+- **Validation or 4xx errors:** Confirm request body field names (snake_case vs camelCase) and required fields against the [API docs](https://docs.flexprice.io).
+- **Parameter passing:** Pass the request object directly to methods (e.g. `ingestEvent({ ... })`), not wrapped in an extra key, unless the SDK docs say otherwise.
 
-For support and questions:
+## Documentation
 
-- Check the [API Documentation](https://docs.flexprice.io)
-- Open an issue on [GitHub](https://github.com/flexprice/javascript-sdk)
-- Contact support at [support@flexprice.io](mailto:support@flexprice.io)
+- [FlexPrice API documentation](https://docs.flexprice.io)
+- [TypeScript SDK examples](examples/) in this repo

package/RUNTIMES.md

@@ -0,0 +1,48 @@
+# Supported JavaScript runtimes
+
+This SDK is intended to be used in JavaScript runtimes that support ECMAScript 2020 or newer. The SDK uses the following features:
+
+- [Web Fetch API][web-fetch]
+- [Web Streams API][web-streams] and in particular `ReadableStream`
+- [Async iterables][async-iter] using `Symbol.asyncIterator`
+
+[web-fetch]: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API
+[web-streams]: https://developer.mozilla.org/en-US/docs/Web/API/Streams_API
+[async-iter]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols
+
+Runtime environments that are explicitly supported are:
+
+- Evergreen browsers which include: Chrome, Safari, Edge, Firefox
+- Node.js active and maintenance LTS releases
+  - Currently, this is v18 and v20
+- Bun v1 and above
+- Deno v1.39
+  - Note that Deno does not currently have native support for streaming file uploads backed by the filesystem ([issue link][deno-file-streaming])
+
+[deno-file-streaming]: https://github.com/denoland/deno/issues/11018
+
+## Recommended TypeScript compiler options
+
+The following `tsconfig.json` options are recommended for projects using this
+SDK in order to get static type support for features like async iterables,
+streams and `fetch`-related APIs ([`for await...of`][for-await-of],
+[`AbortSignal`][abort-signal], [`Request`][request], [`Response`][response] and
+so on):
+
+[for-await-of]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of
+[abort-signal]: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
+[request]: https://developer.mozilla.org/en-US/docs/Web/API/Request
+[response]: https://developer.mozilla.org/en-US/docs/Web/API/Response
+
+```jsonc
+{
+  "compilerOptions": {
+    "target": "es2020", // or higher
+    "lib": ["es2020", "dom", "dom.iterable"]
+  }
+}
+```
+
+While `target` can be set to older ECMAScript versions, it may result in extra,
+unnecessary compatibility code being generated if you are not targeting old
+runtimes.

package/USAGE.md

@@ -0,0 +1,23 @@
+<!-- Start SDK Example Usage [usage] -->
+```typescript
+import { Flexprice } from "@flexprice/sdk";
+
+const flexprice = new Flexprice({
+  serverURL: "https://api.example.com",
+  apiKeyAuth: "<YOUR_API_KEY_HERE>",
+});
+
+async function run() {
+  const result = await flexprice.addons.createAddon({
+    lookupKey: "<value>",
+    name: "<value>",
+    type: "multiple_instance",
+  });
+
+  console.log(result);
+}
+
+run();
+
+```
+<!-- End SDK Example Usage [usage] -->

package/docs/lib/utils/retryconfig.md

@@ -0,0 +1,24 @@
+# RetryConfig
+
+Allows customizing the default retry configuration. It is only permitted in methods that accept retry policies.
+
+## Fields
+
+| Name                      | Type                                | Description                                                                                | Example     |
+| ------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------ | ----------- |
+| `strategy`                | `"backoff" | "none"`                | The retry strategy to use.                                                                 | `"backoff"` |
+| `backoff`                 | [BackoffStrategy](#backoffstrategy) | When strategy is "backoff", this configurates for the backoff parameters.                  |             |
+| `retryConnectionErrors`   | `*boolean*`                         | When strategy is "backoff", this determines whether or not to retry on connection errors.  | `true`      |
+
+## BackoffStrategy
+
+The backoff strategy allows retrying a request with an exponential backoff between each retry.
+
+### Fields
+
+| Name               | Type         | Description                               | Example  |
+| ------------------ | ------------ | ----------------------------------------- | -------- |
+| `initialInterval`  | `*number*`   | The initial interval in milliseconds.     | `500`    |
+| `maxInterval`      | `*number*`   | The maximum interval in milliseconds.     | `60000`  |
+| `exponent`         | `*number*`   | The exponent to use for the backoff.      | `1.5`    |
+| `maxElapsedTime`   | `*number*`   | The maximum elapsed time in milliseconds. | `300000` |

package/docs/sdk/models/activate-subscription-request.md

@@ -0,0 +1,21 @@
+# ActivateSubscriptionRequest
+
+## Example Usage
+
+```typescript
+import { ActivateSubscriptionRequest } from "@flexprice/sdk/sdk/models";
+
+let value: ActivateSubscriptionRequest = {
+  id: "<id>",
+  body: {
+    startDate: "<value>",
+  },
+};
+```
+
+## Fields
+
+| Field                                                                                                     | Type                                                                                                      | Required                                                                                                  | Description                                                                                               |
+| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `id`                                                                                                      | *string*                                                                                                  | :heavy_check_mark:                                                                                        | Subscription ID                                                                                           |
+| `body`                                                                                                    | [models.DtoActivateDraftSubscriptionRequest](../../sdk/models/dto-activate-draft-subscription-request.md) | :heavy_check_mark:                                                                                        | Activate Draft Subscription Request                                                                       |

package/docs/sdk/models/addon-association-entity-type.md

@@ -0,0 +1,17 @@
+# AddonAssociationEntityType
+
+## Example Usage
+
+```typescript
+import { AddonAssociationEntityType } from "@flexprice/sdk/sdk/models";
+
+let value: AddonAssociationEntityType = "plan";
+```
+
+## Values
+
+This is an open enum. Unrecognized values will be captured as the `Unrecognized<string>` branded type.
+
+```typescript
+"subscription" | "plan" | "addon" | Unrecognized<string>
+```