@edgebound/bigcommerce 0.3.2 → 0.4.0

package/README.md

@@ -0,0 +1,473 @@
+# @edgebound/bigcommerce
+
+A comprehensive NestJS module for integrating with BigCommerce APIs. Provides type-safe, validated services for managing companies, customers, orders, products, payments, and more.
+
+## Features
+
+- 🔒 **Type-safe** - Full TypeScript support with Zod validation
+- 🔄 **Automatic retries** - Built-in retry logic for failed requests
+- 📦 **Batch operations** - Efficient concurrent processing for bulk operations
+- 🔌 **NestJS integration** - Native dependency injection support
+- ✅ **Input validation** - Automatic request validation using Zod schemas
+- 🚀 **Pagination helpers** - Automatic pagination handling for large datasets
+
+## Installation
+
+```bash
+npm install @edgebound/bigcommerce
+# or
+pnpm add @edgebound/bigcommerce
+# or
+yarn add @edgebound/bigcommerce
+```
+
+### Peer Dependencies
+
+```bash
+npm install @nestjs/common @nestjs/config zod neverthrow neverthrow-result-utils reflect-metadata rxjs p-limit
+```
+
+## Quick Start
+
+### 1. Import the Module
+
+```typescript
+import { Module } from '@nestjs/common';
+import { BigCommerceModule } from '@edgebound/bigcommerce';
+
+@Module({
+  imports: [
+    // Option 1: Use environment variables (default)
+    BigCommerceModule,
+    
+    // Option 2: Provide configuration directly
+    BigCommerceModule.forRootAsync({
+      store: {
+        hash: 'your-store-hash'
+      },
+      credentials: {
+        clientId: 'your-client-id',
+        clientSecret: 'your-client-secret',
+        accessToken: 'your-access-token'
+      }
+    })
+  ],
+})
+export class AppModule {}
+```
+
+### 2. Environment Variables (Option 1)
+
+Create a `.env` file:
+
+```env
+BIGCOMMERCE_STORE_HASH=your-store-hash
+BIGCOMMERCE_CLIENT_ID=your-client-id
+BIGCOMMERCE_CLIENT_SECRET=your-client-secret
+BIGCOMMERCE_ACCESS_TOKEN=your-access-token
+```
+
+### 3. Use Services
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { BigCommerceCompaniesService, BigCommerceOrdersService } from '@edgebound/bigcommerce';
+
+@Injectable()
+export class MyService {
+  constructor(
+    private readonly companiesService: BigCommerceCompaniesService,
+    private readonly ordersService: BigCommerceOrdersService,
+  ) {}
+
+  async createCompany() {
+    const result = await this.companiesService.createCompany({
+      company_name: 'Acme Corporation',
+      company_email: 'contact@acme.com',
+    });
+
+    return result.match(
+      (company) => company,
+      (error) => {
+        throw error;
+      }
+    );
+  }
+}
+```
+
+## Available Services
+
+### BigCommerceCompaniesService
+
+Manage B2B companies, users, roles, and company settings.
+
+```typescript
+// Create a company
+await companiesService.createCompany({
+  company_name: 'Acme Corp',
+  company_email: 'contact@acme.com'
+});
+
+// Create a company user
+await companiesService.createCompanyUser({
+  email: 'john@acme.com',
+  first_name: 'John',
+  last_name: 'Doe',
+  company_id: 1,
+  role_id: 2
+});
+
+// Set company credit limit
+await companiesService.setCompanyCredit({
+  companyId: 1,
+  data: {
+    credit_limit: 10000,
+    currency_code: 'USD'
+  }
+});
+
+// Assign sales staff to companies
+await companiesService.assignSalesStaffToCompany({
+  assignments: [
+    { companyId: 1, salesStaffId: 10 },
+    { companyId: 2, salesStaffId: 11 }
+  ]
+});
+
+// Get company details
+await companiesService.getCompanyDetails({ companyId: 1 });
+
+// Get all company roles (auto-paginated)
+await companiesService.getAllCompanyRoles();
+
+// Get all company extra fields (auto-paginated)
+await companiesService.getAllCompanyExtraFields();
+
+// Set payment methods for a company
+await companiesService.setCompanyPaymentMethods({
+  companyId: 1,
+  data: {
+    payment_methods: ['credit_card', 'purchase_order']
+  }
+});
+
+// Get user by customer ID
+await companiesService.getUserByCustomerId({ customerId: 123 });
+```
+
+### BigCommerceCustomersService
+
+Manage customers, customer groups, and customer addresses.
+
+```typescript
+// Create customer group
+await customersService.createCustomerGroup({
+  name: 'VIP Customers',
+  discount_rules: [
+    {
+      type: 'price_list',
+      price_list_id: 1
+    }
+  ]
+});
+
+// Find customers with criteria
+await customersService.findCustomers({
+  'email:in': ['john@example.com', 'jane@example.com'],
+  page: 1,
+  limit: 50
+});
+
+// Get all customers (auto-paginated)
+await customersService.getAllCustomersBy({
+  'company:in': ['Acme Corp']
+});
+
+// Find customer addresses
+await customersService.findCustomerAddresses({
+  'customer_id:in': [1, 2, 3],
+  page: 1,
+  limit: 50
+});
+
+// Get all customer addresses (auto-paginated)
+await customersService.getAllCustomerAddressesBy({
+  'customer_id:in': [1, 2, 3]
+});
+
+// Find customer groups
+await customersService.findCustomersGroups({
+  page: 1,
+  limit: 50
+});
+
+// Get all customer groups (auto-paginated)
+await customersService.getAllCustomerGroupsBy();
+
+// Get specific customer
+await customersService.getCustomer(123);
+
+// Set customer group price list
+await customersService.setCustomerGroupPriceList({
+  customerGroupId: 1,
+  data: {
+    discount_rules: [
+      {
+        type: 'price_list',
+        price_list_id: 2
+      }
+    ]
+  }
+});
+```
+
+### BigCommerceOrdersService
+
+Manage orders, shipping addresses, and order products.
+
+```typescript
+// Find orders with criteria
+await ordersService.findOrders({
+  min_date_created: '2024-01-01',
+  status_id: 11,
+  page: 1,
+  limit: 50
+});
+
+// Get all orders (auto-paginated)
+await ordersService.getAllOrdersBy({
+  min_date_created: '2024-01-01',
+  status_id: 11
+});
+
+// Get specific order
+await ordersService.getOrder(12345);
+
+// Find order shipping addresses
+await ordersService.findOrderShippingAddresses(12345, 1, 50);
+
+// Get all order shipping addresses (auto-paginated)
+await ordersService.getAllOrderShippingAddresses(12345);
+
+// Find order products
+await ordersService.findOrderProducts(12345, 1, 50);
+
+// Get all order products (auto-paginated)
+await ordersService.getAllOrderProducts(12345);
+```
+
+### BigCommerceProductsService
+
+Manage product inventory and visibility.
+
+```typescript
+// Set products inventory in batch
+await productsService.setProductsInventory('Inventory adjustment', [
+  {
+    product_id: 1,
+    variant_id: 10,
+    location_id: 1,
+    quantity: 100
+  },
+  {
+    product_id: 2,
+    variant_id: 20,
+    location_id: 1,
+    quantity: 50
+  }
+]);
+
+// Update products in batch
+await productsService.updateProducts([
+  {
+    id: 1,
+    name: 'Updated Product Name',
+    price: 29.99
+  },
+  {
+    id: 2,
+    is_visible: true
+  }
+]);
+
+// Set product visibility
+await productsService.setProductVisibility([
+  {
+    id: 1,
+    is_visible: true
+  },
+  {
+    id: 2,
+    is_visible: false
+  }
+]);
+```
+
+### BigCommercePaymentsService
+
+Manage payment methods.
+
+```typescript
+// Get available payment methods
+await paymentsService.getPaymentMethods();
+```
+
+### BigCommercePriceListsService
+
+Manage price lists.
+
+```typescript
+// Create price list
+await priceListsService.createPriceList({
+  name: 'Wholesale Prices',
+  active: true
+});
+
+// Find price lists with criteria
+await priceListsService.findPriceLists({
+  page: 1,
+  limit: 50
+});
+
+// Get all price lists (auto-paginated)
+await priceListsService.getAllPriceListsBy();
+```
+
+### BigCommerceSalesStaffService
+
+Manage sales staff assignments.
+
+```typescript
+// Find sales staff with criteria
+await salesStaffService.findSalesStaff({
+  limit: 50,
+  offset: 0
+});
+
+// Get all sales staff (auto-paginated)
+await salesStaffService.getAllSalesStaffBy();
+```
+
+## Error Handling
+
+All service methods return `ResultAsync` from the `neverthrow` library, providing type-safe error handling:
+
+```typescript
+const result = await companiesService.createCompany({
+  company_name: 'Acme Corp',
+  company_email: 'contact@acme.com'
+});
+
+result.match(
+  (company) => {
+    console.log('Company created:', company);
+  },
+  (error) => {
+    if (error instanceof InputDataValidationError) {
+      console.error('Validation error:', error.details);
+    } else if (error instanceof BigCommerceError) {
+      console.error('API error:', error.message);
+    } else {
+      console.error('Unknown error:', error);
+    }
+  }
+);
+```
+
+## Advanced Features
+
+### Automatic Pagination
+
+Services provide `getAll*` methods that automatically handle pagination:
+
+```typescript
+// Fetches all pages automatically
+const allCustomers = await customersService.getAllCustomersBy({
+  'company:in': ['Acme Corp']
+});
+```
+
+### Batch Operations with Concurrency
+
+Batch operations are automatically processed with optimal concurrency:
+
+```typescript
+// Processes in batches with controlled concurrency
+await productsService.setProductsInventory('Stock update', [
+  // ... hundreds of items
+]);
+```
+
+### Input Validation
+
+All inputs are automatically validated using Zod schemas:
+
+```typescript
+// Invalid input will be caught before making API request
+await companiesService.createCompany({
+  company_name: '', // Error: company_name is required
+});
+```
+
+### Automatic Retries
+
+Failed requests are automatically retried with exponential backoff:
+
+```typescript
+// Automatically retries on transient failures
+await ordersService.getOrder(12345);
+```
+
+## Configuration
+
+### Default Configuration
+
+The module uses sensible defaults for batch sizes, concurrency limits, and retry policies. These are defined in the `DEFAULTS` constant.
+
+### Custom Configuration
+
+You can override defaults by providing custom configuration:
+
+```typescript
+BigCommerceModule.forRootAsync({
+  store: {
+    hash: process.env.BIGCOMMERCE_STORE_HASH
+  },
+  credentials: {
+    clientId: process.env.BIGCOMMERCE_CLIENT_ID,
+    clientSecret: process.env.BIGCOMMERCE_CLIENT_SECRET,
+    accessToken: process.env.BIGCOMMERCE_ACCESS_TOKEN
+  }
+})
+```
+
+## TypeScript Support
+
+Full TypeScript support with exported types:
+
+```typescript
+import type {
+  CreateCompanySchema,
+  CreateCompanyResponseSchema,
+  FindCustomersCriteriaSchema,
+  // ... and many more
+} from '@edgebound/bigcommerce';
+```
+
+## API Reference
+
+For detailed API documentation, refer to the JSDoc comments in the source code. Each service method includes:
+
+- Parameter descriptions
+- Return type information
+- Usage examples
+- Error scenarios
+
+## License
+
+MIT
+
+## Support
+
+For issues and feature requests, please open an issue on the GitHub repository.

package/dist/bigcommerce-entities/addresses/index.d.ts

@@ -0,0 +1,2 @@
+export * from './schemas';
+//# sourceMappingURL=index.d.ts.map

package/dist/bigcommerce-entities/addresses/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/bigcommerce-entities/addresses/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC"}

package/dist/bigcommerce-entities/addresses/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./schemas"), exports);
+//# sourceMappingURL=index.js.map

package/dist/bigcommerce-entities/addresses/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/bigcommerce-entities/addresses/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,4CAA0B"}

package/dist/{addresses.d.mts → bigcommerce-entities/addresses/schemas/address.schema.d.ts}

@@ -1,6 +1,5 @@
 import * as z from 'zod';
-
-declare const AddressSchema: z.ZodObject<{
+export declare const AddressSchema: z.ZodObject<{
     first_name: z.ZodString;
     last_name: z.ZodString;
     company: z.ZodString;
@@ -18,10 +17,4 @@ declare const AddressSchema: z.ZodObject<{
         value: z.ZodString;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-
-declare const AddressFormFieldSchema: z.ZodObject<{
-    name: z.ZodString;
-    value: z.ZodString;
-}, z.core.$strip>;
-
-export { AddressFormFieldSchema, AddressSchema };
+//# sourceMappingURL=address.schema.d.ts.map

package/dist/bigcommerce-entities/addresses/schemas/address.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.schema.d.ts","sourceRoot":"","sources":["../../../../src/bigcommerce-entities/addresses/schemas/address.schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAGzB,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;iBAcxB,CAAC"}

package/dist/bigcommerce-entities/addresses/schemas/address.schema.js

@@ -0,0 +1,54 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AddressSchema = void 0;
+const z = __importStar(require("zod"));
+const form_field_schema_1 = require("./form-field.schema");
+exports.AddressSchema = z.object({
+    first_name: z.string(),
+    last_name: z.string(),
+    company: z.string(),
+    street_1: z.string(),
+    street_2: z.string(),
+    city: z.string(),
+    state: z.string(),
+    zip: z.string(),
+    country: z.string(),
+    country_iso2: z.string(),
+    phone: z.string(),
+    email: z.string(),
+    form_fields: z.array(form_field_schema_1.AddressFormFieldSchema),
+});
+//# sourceMappingURL=address.schema.js.map

package/dist/bigcommerce-entities/addresses/schemas/address.schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.schema.js","sourceRoot":"","sources":["../../../../src/bigcommerce-entities/addresses/schemas/address.schema.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,uCAAyB;AACzB,2DAA6D;AAEhD,QAAA,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;IACf,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE;IACxB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,0CAAsB,CAAC;CAC7C,CAAC,CAAC"}

package/dist/bigcommerce-entities/addresses/schemas/form-field.schema.d.ts

@@ -0,0 +1,6 @@
+import * as z from 'zod';
+export declare const AddressFormFieldSchema: z.ZodObject<{
+    name: z.ZodString;
+    value: z.ZodString;
+}, z.core.$strip>;
+//# sourceMappingURL=form-field.schema.d.ts.map

package/dist/bigcommerce-entities/addresses/schemas/form-field.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-field.schema.d.ts","sourceRoot":"","sources":["../../../../src/bigcommerce-entities/addresses/schemas/form-field.schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB,eAAO,MAAM,sBAAsB;;;iBAGjC,CAAC"}

package/dist/bigcommerce-entities/addresses/schemas/form-field.schema.js

@@ -0,0 +1,42 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AddressFormFieldSchema = void 0;
+const z = __importStar(require("zod"));
+exports.AddressFormFieldSchema = z.object({
+    name: z.string(),
+    value: z.string(),
+});
+//# sourceMappingURL=form-field.schema.js.map

package/dist/bigcommerce-entities/addresses/schemas/form-field.schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-field.schema.js","sourceRoot":"","sources":["../../../../src/bigcommerce-entities/addresses/schemas/form-field.schema.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,uCAAyB;AAEZ,QAAA,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;CAClB,CAAC,CAAC"}

package/dist/bigcommerce-entities/addresses/schemas/index.d.ts

@@ -0,0 +1,3 @@
+export * from './address.schema';
+export * from './form-field.schema';
+//# sourceMappingURL=index.d.ts.map

package/dist/bigcommerce-entities/addresses/schemas/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/bigcommerce-entities/addresses/schemas/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC"}

package/dist/bigcommerce-entities/addresses/schemas/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./address.schema"), exports);
+__exportStar(require("./form-field.schema"), exports);
+//# sourceMappingURL=index.js.map

package/dist/bigcommerce-entities/addresses/schemas/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/bigcommerce-entities/addresses/schemas/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,mDAAiC;AACjC,sDAAoC"}