@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

npm install @edgebound/bigcommerce
# or
pnpm add @edgebound/bigcommerce
# or
yarn add @edgebound/bigcommerce

Peer Dependencies

npm install @nestjs/common @nestjs/config zod neverthrow neverthrow-result-utils reflect-metadata rxjs p-limit

Quick Start

1. Import the Module

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:

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

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: '[email protected]',
    });

    return result.match(
      (company) => company,
      (error) => {
        throw error;
      }
    );
  }
}

Available Services

BigCommerceCompaniesService

Manage B2B companies, users, roles, and company settings.

// Create a company
await companiesService.createCompany({
  company_name: 'Acme Corp',
  company_email: '[email protected]'
});

// Create a company user
await companiesService.createCompanyUser({
  email: '[email protected]',
  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.

// 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': ['[email protected]', '[email protected]'],
  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.

// 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.

// 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.

// Get available payment methods
await paymentsService.getPaymentMethods();

BigCommercePriceListsService

Manage price lists.

// 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.

// 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:

const result = await companiesService.createCompany({
  company_name: 'Acme Corp',
  company_email: '[email protected]'
});

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:

// 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:

// Processes in batches with controlled concurrency
await productsService.setProductsInventory('Stock update', [
  // ... hundreds of items
]);

Input Validation

All inputs are automatically validated using Zod schemas:

// 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:

// 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:

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:

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.