A comprehensive NestJS module for integrating with BigCommerce APIs. Provides type-safe, validated services for managing companies, customers, orders, products, payments, and more.
npm install @edgebound/bigcommerceA comprehensive NestJS module for integrating with BigCommerce APIs. Provides type-safe, validated services for managing companies, customers, orders, products, payments, and more.
- 🔒 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
``bash`
npm install @edgebound/bigcommerceor
pnpm add @edgebound/bigcommerceor
yarn add @edgebound/bigcommerce
`bash`
npm install @nestjs/common @nestjs/config zod neverthrow neverthrow-result-utils reflect-metadata rxjs p-limit
`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 {}
`
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
`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;
}
);
}
}
`
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 });
`
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
}
]
}
});
`
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);
`
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
}
]);
`
Manage payment methods.
`typescript`
// Get available payment methods
await paymentsService.getPaymentMethods();
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();
`
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();
`
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);
}
}
);
`
Services provide getAll* methods that automatically handle pagination:
`typescript`
// Fetches all pages automatically
const allCustomers = await customersService.getAllCustomersBy({
'company:in': ['Acme Corp']
});
Batch operations are automatically processed with optimal concurrency:
`typescript`
// Processes in batches with controlled concurrency
await productsService.setProductsInventory('Stock update', [
// ... hundreds of items
]);
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
});
Failed requests are automatically retried with exponential backoff:
`typescript`
// Automatically retries on transient failures
await ordersService.getOrder(12345);
The module uses sensible defaults for batch sizes, concurrency limits, and retry policies. These are defined in the DEFAULTS constant.
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
}
})
Full TypeScript support with exported types:
`typescript``
import type {
CreateCompanySchema,
CreateCompanyResponseSchema,
FindCustomersCriteriaSchema,
// ... and many more
} from '@edgebound/bigcommerce';
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
MIT
For issues and feature requests, please open an issue on the GitHub repository.