@flexprice/sdk 1.0.17 → 1.0.28

package/README.md

@@ -1,256 +1,337 @@
-# FlexPrice JavaScript SDK
+# FlexPrice JavaScript/TypeScript SDK
 
-This is the JavaScript client library for the FlexPrice API.
+[![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/)
+
+Official TypeScript/JavaScript SDK for the FlexPrice API with modern ES7 module support and comprehensive type safety.
+
+## 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
 
 ## Installation
 
-### Node.js
+### Published Package
 
 ```bash
 npm install @flexprice/sdk --save
 ```
 
-### Browser via CDN
+### Unpublished (Development)
 
-```html
-<script src="https://cdn.jsdelivr.net/npm/@flexprice/sdk/dist/flexprice-sdk.min.js"></script>
+```bash
+npm install PATH_TO_GENERATED_PACKAGE --save
 ```
 
-## Usage
+## Quick Start
+
+### JavaScript (CommonJS)
 
 ```javascript
-// Import the FlexPrice SDK
-const FlexPrice = require('@flexprice/sdk');
-// Or using ES modules:
-// import * as FlexPrice from '@flexprice/sdk';
-
-// Load environment variables (using dotenv package)
-require('dotenv').config();
-
-function main() {
-  try {
-    // Configure the API client with your API key
-    // API keys should start with 'sk_' followed by a unique identifier
-    const apiKey = process.env.FLEXPRICE_API_KEY;
-    const apiHost = process.env.FLEXPRICE_API_HOST || 'api.cloud.flexprice.io';
-    
-    if (!apiKey) {
-      console.error('ERROR: You must provide a valid FlexPrice API key');
-      process.exit(1);
-    }
+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";
 
-    // Initialize the API client with your API key
-    const defaultClient = FlexPrice.ApiClient.instance;
-    
-    // Set the base path directly to the API endpoint including /v1
-    defaultClient.basePath = `https://${apiHost}/v1`;
-    
-    // Configure API key authorization
-    const apiKeyAuth = defaultClient.authentications['ApiKeyAuth'];
-    apiKeyAuth.apiKey = apiKey;
-    apiKeyAuth.in = 'header';
-    apiKeyAuth.name = 'x-api-key';
-
-    // Generate a unique customer ID for this example
-    const customerId = `sample-customer-${Date.now()}`;
-
-    // Create API instances for different endpoints
-    const eventsApi = new FlexPrice.EventsApi();
-    const customersApi = new FlexPrice.CustomersApi();
-
-    // Step 1: Create a customer
-    console.log(`Creating customer with ID: ${customerId}...`);
-    
-    const customerRequest = {
-      externalId: customerId,
-      email: `example-${customerId}@example.com`,
-      name: 'Example Customer',
-      metadata: {
-        source: 'javascript-sdk-example',
-        createdAt: new Date().toISOString()
-      }
-    };
-
-    customersApi.customersPost({ 
-      dtoCreateCustomerRequest: customerRequest 
-    }, function(error, data, response) {
-      if (error) {
-        console.error('Error creating customer:', error);
-        return;
-      }
-      
-      console.log('Customer created successfully!');
-
-      // Step 2: Create an event
-      console.log('Creating event...');
-      
-      // Important: Use snake_case for all property names to match the API
-      const eventRequest = {
-        event_name: 'Sample Event',
-        external_customer_id: customerId,
-        properties: {
-          source: 'javascript_sample_app',
-          environment: 'test',
-          timestamp: new Date().toISOString()
-        },
-        source: 'javascript_sample_app',
-        timestamp: new Date().toISOString()
-      };
-
-      // Important: Pass the event directly without wrapping it
-      eventsApi.eventsPost(eventRequest, function(error, eventResult, response) {
-        if (error) {
-          console.error('Error creating event:', error);
-          return;
-        }
-        
-        console.log(`Event created successfully! ID: ${eventResult.event_id}`);
-
-        // Step 3: Retrieve events for this customer
-        console.log(`Retrieving events for customer ${customerId}...`);
-        
-        // Important: Use snake_case for parameter names
-        eventsApi.eventsGet({
-          external_customer_id: customerId
-        }, function(error, events, response) {
-          if (error) {
-            console.error('Error retrieving events:', error);
-            return;
-          }
-          
-          console.log(`Found ${events.events.length} events:`);
-          
-          events.events.forEach((event, index) => {
-            console.log(`Event ${index + 1}: ${event.id} - ${event.event_name}`);
-            console.log(`Properties: ${JSON.stringify(event.properties)}`);
-          });
-
-          console.log('Example completed successfully!');
-        });
-      });
-    });
-  } catch (error) {
-    console.error('Error:', error);
+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);
   }
+});
+```
+
+### TypeScript (ES Modules)
+
+```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
 
-main();
+```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>
 ```
 
-## Running the Example
+## Environment Support
 
-To run the provided example:
+### Node.js Environments
 
-1. Clone the repository:
-   ```bash
-   git clone https://github.com/flexprice/javascript-sdk.git
-   cd javascript-sdk/examples
-   ```
+- Node.js 16+
+- Webpack
+- Browserify
 
-2. Install dependencies:
-   ```bash
-   npm install
-   ```
+### Language Levels
 
-3. Create a `.env` file with your API credentials:
-   ```bash
-   cp .env.sample .env
-   # Edit .env with your API key
-   ```
+- ES5 (requires Promises/A+ library)
+- ES6+
+- TypeScript 4.5+
 
-4. Run the example:
-   ```bash
-   npm start
-   ```
+### Module Systems
 
-## Features
+- CommonJS
+- ES6 Modules
+- UMD (Universal Module Definition)
 
-- Complete API coverage
-- CommonJS and ES Module support
-- Browser compatibility
-- Detailed documentation
-- Error handling
-- TypeScript definitions
+## API Reference
 
-## Documentation
+### Authentication
 
-For detailed API documentation, refer to the code comments and the official FlexPrice API documentation.
+All API requests require authentication using an API key:
 
-## Troubleshooting
+```javascript
+const apiKeyAuth = defaultClient.authentications["ApiKeyAuth"];
+apiKeyAuth.apiKey = "sk_your_api_key_here";
+apiKeyAuth.in = "header";
+apiKeyAuth.name = "x-api-key";
+```
 
-### Authentication Issues
+### Available APIs
 
-If you see errors related to authentication:
+- **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
 
-- Make sure your API key starts with `sk_` (for server-side usage)
-- Check that the key is active and has the necessary permissions
-- Use the `x-api-key` header for authentication (the SDK handles this for you)
+### Common Patterns
 
-### Property Names
+#### Creating Events
 
-Always use snake_case for property names in requests:
-- ✅ `event_name`, `external_customer_id`, `page_size`
-- ❌ `eventName`, `externalCustomerId`, `pageSize`
+```javascript
+const eventRequest = {
+  eventName: "user_signup",
+  externalCustomerId: "customer-123",
+  properties: {
+    plan: "premium",
+    source: "website",
+  },
+  source: "web_app",
+  timestamp: new Date().toISOString(),
+};
 
-### Parameter Passing
+eventsApi.eventsPost({ event: eventRequest }, callback);
+```
 
-Pass parameters directly to methods like eventsPost:
-- ✅ `eventsApi.eventsPost(eventRequest, callback)`
-- ❌ `eventsApi.eventsPost({ dtoIngestEventRequest: eventRequest }, callback)`
+#### Creating Customers
 
-### Callback vs Promise Error
+```javascript
+const customerRequest = {
+  externalId: "customer-123",
+  email: "user@example.com",
+  name: "John Doe",
+  metadata: {
+    source: "signup_form",
+  },
+};
+
+customersApi.customersPost({ customer: customerRequest }, callback);
+```
 
-The SDK uses callback-style API calls instead of Promises. If you see an error like:
+#### 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);
+  }
+});
 ```
-Warning: superagent request was sent twice, because both .end() and .then() were called.
+
+## Development
+
+### Building
+
+To build and compile the TypeScript sources to JavaScript:
+
+```bash
+npm install
+npm run build
 ```
 
-Make sure you're using the callback pattern shown in the examples, not trying to `await` the API calls.
+### Publishing
 
-### Network or Connectivity Issues
+First build the package then run:
 
-If you encounter network-related errors:
+```bash
+npm publish
+```
 
-- Check your internet connection
-- Verify that the API host is accessible from your environment
-- Look for firewall or proxy settings that might block API requests
+### Testing
 
-### Using the SDK in a Browser
+```bash
+npm test
+```
 
-When using the SDK in a browser, remember:
+### Linting
 
-- CORS restrictions might apply - ensure your domain is whitelisted
-- Never expose API keys in client-side code - use a proxy or backend service
-- Some features might be limited in browser environments
+```bash
+npm run lint
+npm run lint:fix
+```
 
-## TypeScript Usage
+## Examples
 
-The package includes TypeScript definitions:
+### Running JavaScript Example
 
-```typescript
-import * as FlexPrice from '@flexprice/sdk';
+```bash
+cd examples
+npm install
+npm start
+```
 
-// Configure the client
-const client = FlexPrice.ApiClient.instance;
-// ... rest of the configuration
+### Running TypeScript Example
 
-// Type-safe API calls with correct property names
-const api = new FlexPrice.EventsApi();
+```bash
+cd examples
+npm install
+npm run start:ts
+```
 
-const eventRequest = {
-  event_name: 'Sample Event',
-  external_customer_id: 'customer-123',
-  properties: { key: 'value' },
-  source: 'typescript_example',
-  timestamp: new Date().toISOString()
-};
+### Building TypeScript Example
 
-api.eventsPost(eventRequest, (error, data, response) => {
-  if (error) {
-    console.error(error);
-  } else {
-    console.log(data);
-  }
-});
-``` 
+```bash
+cd examples
+npm run build:ts
+npm run start:built
+```
+
+## 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)
+
+### TypeScript Issues
+
+- 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
+
+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.
+
+## License
+
+This SDK is licensed under the MIT License. See the LICENSE file for details.
+
+## Support
+
+For support and questions:
+
+- 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)

package/package.json

@@ -1,54 +1,42 @@
 {
   "name": "@flexprice/sdk",
-  "version": "1.0.17",
-  "description": "Official JavaScript SDK of Flexprice",
-  "license": "Apache 2.0",
-  "homepage": "https://flexprice.io",
+  "version": "1.0.28",
+  "description": "Official TypeScript/JavaScript SDK of Flexprice",
+  "author": "Flexprice",
   "repository": {
     "type": "git",
     "url": "https://github.com/flexprice/javascript-sdk.git"
   },
-  "publishConfig": {
-    "access": "public"
-  },
-  "main": "dist/index.js",
+  "main": "./dist/index.js",
+  "typings": "./dist/index.d.ts",
+  "module": "./dist/index.js",
+  "sideEffects": false,
   "scripts": {
-    "build": "babel src -d dist",
+    "build": "tsc",
     "prepare": "npm run build",
-    "test": "mocha --require @babel/register --recursive"
+    "test": "jest",
+    "lint": "eslint src/**/*.ts",
+    "lint:fix": "eslint src/**/*.ts --fix"
   },
-  "browser": {
-    "fs": false
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.19.17",
+    "@typescript-eslint/eslint-plugin": "^6.21.0",
+    "@typescript-eslint/parser": "^6.21.0",
+    "eslint": "^8.57.1",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.4.4",
+    "typescript": "^5.9.2"
   },
-  "dependencies": {
-    "@babel/cli": "^7.0.0",
-    "superagent": "^5.3.0"
+  "publishConfig": {
+    "access": "public"
   },
-  "devDependencies": {
-    "@babel/core": "^7.0.0",
-    "@babel/plugin-proposal-class-properties": "^7.0.0",
-    "@babel/plugin-proposal-decorators": "^7.0.0",
-    "@babel/plugin-proposal-do-expressions": "^7.0.0",
-    "@babel/plugin-proposal-export-default-from": "^7.0.0",
-    "@babel/plugin-proposal-export-namespace-from": "^7.0.0",
-    "@babel/plugin-proposal-function-bind": "^7.0.0",
-    "@babel/plugin-proposal-function-sent": "^7.0.0",
-    "@babel/plugin-proposal-json-strings": "^7.0.0",
-    "@babel/plugin-proposal-logical-assignment-operators": "^7.0.0",
-    "@babel/plugin-proposal-nullish-coalescing-operator": "^7.0.0",
-    "@babel/plugin-proposal-numeric-separator": "^7.0.0",
-    "@babel/plugin-proposal-optional-chaining": "^7.0.0",
-    "@babel/plugin-proposal-pipeline-operator": "^7.0.0",
-    "@babel/plugin-proposal-throw-expressions": "^7.0.0",
-    "@babel/plugin-syntax-dynamic-import": "^7.0.0",
-    "@babel/plugin-syntax-import-meta": "^7.0.0",
-    "@babel/preset-env": "^7.0.0",
-    "@babel/register": "^7.0.0",
-    "expect.js": "^0.3.1",
-    "mocha": "^8.0.1",
-    "sinon": "^7.2.0"
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "engines": {
+    "node": ">=16.0.0"
   },
-  "files": [
-    "dist"
-  ]
+  "keywords": "[\"flexprice\",\"sdk\",\"typescript\",\"javascript\",\"api\",\"billing\",\"pricing\",\"es7\",\"esmodules\",\"fetch\"]",
+  "files": "[\"dist\",\"src\",\"README.md\"]",
+  "exports": "{\".\": {\"import\": \"./dist/index.js\", \"require\": \"./dist/index.cjs\", \"types\": \"./dist/index.d.ts\"}, \"./package.json\": \"./package.json\"}"
 }