TypeScript SDK

Official TypeScript/JavaScript client for the Huntrecht Platform API v1. Works in Node.js 18+ and modern browsers.

Installation

npm install @huntrecht/sdk

Quick Start

import { HuntrechtClient } from '@huntrecht/sdk';

const client = new HuntrechtClient({
  clientId: 'hnt_your_client_id',
  clientSecret: 'your_secret',
});

// Authenticate (automatic on first request)
const tokens = await client.auth.token();
console.log(`✓ Authenticated (expires in ${tokens.expires_in}s)`);

// List orders
const orders = await client.orders.list({ status: 'pending' });
for (const order of orders.data) {
  console.log(`Order ${order.id}: ${order.commodity} - ${order.quantity}`);
}

// Get credit score
const score = await client.credit.score('customer@example.com');
console.log(`Credit score: ${score.data.credit_score} (${score.data.risk_level})`);

Authentication

// Using environment variables (Node.js)
const client = new HuntrechtClient();

// Using explicit credentials
const client = new HuntrechtClient({
  clientId: 'hnt_your_client_id',
  clientSecret: 'your_secret',
});

// With custom base URL
const client = new HuntrechtClient({
  baseUrl: 'https://api.huntrecht.com',
  clientId: 'hnt_abc',
  clientSecret: 'secret',
});

// With pre-existing token (skip auth)
const client = new HuntrechtClient({
  accessToken: 'existing_token',
});

Resource Modules

Auth

// Get access token
const tokens = await client.auth.token();

// Refresh token
const tokens = await client.auth.token({
  grantType: 'refresh_token',
  refreshToken: '...',
});

// Revoke token
await client.auth.revoke();

API Clients

// List API clients
const clients = await client.clients.list(userId);

// Create API client (secret shown only once)
const newClient = await client.clients.create(userId, {
  client_name: 'My Integration',
  scopes: ['read', 'orders:read', 'orders:write'],
});
console.log(`Secret: ${newClient.client_secret}`);

// Rotate secret
const rotated = await client.clients.rotateSecret(userId, 'hnt_abc');

// Delete client
await client.clients.delete(userId, 'hnt_abc');

Orders

// List orders
const orders = await client.orders.list({ page: 1, perPage: 20, status: 'pending' });

// Get order
const order = await client.orders.get('ord_abc123');

// Create order
const order = await client.orders.create({
  commodity: 'Gold',
  quantity: 100,
  deliveryTerms: 'FOB',
  destination: 'New York',
});

Payments

// List payments
const payments = await client.payments.list({ status: 'completed' });

// Get payment
const payment = await client.payments.get('pay_abc123');

// Create payment
const payment = await client.payments.create({
  subscription_id: 123,
  amount: 2500.00,
  currency: 'USD',
  payment_method: 'card',
});

Subscriptions

// List subscriptions
const subs = await client.subscriptions.list({
  status: 'active',
  includePaymentHistory: true,
});

// Get subscription
const sub = await client.subscriptions.get('sub_abc123');

Credit Risk

// Get credit score
const score = await client.credit.score('customer@example.com');

// Assess credit
const assessment = await client.credit.assess({
  customer_email: 'customer@example.com',
  include_recommendations: true,
});

KYC

// List KYC submissions
const kycs = await client.kyc.list({ status: 'pending' });

// Submit KYC
const result = await client.kyc.submit({
  company_name: 'Acme Corp',
  company_type: 'LLC',
  registration_number: '123456789',
});

Quotes

// List quotes
const quotes = await client.quotes.list();

// Request quote
const quote = await client.quotes.create({
  commodity: 'Copper',
  quantity: 500,
  unit: 'kg',
  delivery_location: 'Shanghai',
});

Users

// Get current user
const me = await client.users.me();

// Get user by ID
const user = await client.users.get('user_123');

Storefront

// List collections
const collections = await client.storefront.collections({ includeProducts: true });

// Get collection
const collection = await client.storefront.collection('b2b-wholesale');

// List products
const products = await client.storefront.products({ b2bOnly: true });

// Search products
const results = await client.storefront.search('copper wire', { b2bOnly: true });

Price Drops (Public)

// List recent price drops
const drops = await client.priceDrops.list({ limit: 10, minDiscount: 5.0 });

// Featured price drops
const featured = await client.priceDrops.featured();

Linked Payments

// Check eligibility
const eligibility = await client.linkedPayments.checkEligibility('cust_123');

// Link wallet
const wallet = await client.linkedPayments.linkWallet({
  customer_id: 'cust_123',
  wallet_address: '0xabc...',
  wallet_provider: 'metamask',
});

// Link bank
const bank = await client.linkedPayments.linkBank({
  customer_id: 'cust_123',
  plaid_access_token: 'access-sandbox-...',
});

// Get linked accounts
const accounts = await client.linkedPayments.linkedAccounts('cust_123');

Error Handling

import {
  HuntrechtError,
  AuthenticationError,
  RateLimitError,
  NotFoundError,
  ValidationError,
  PermissionError,
} from '@huntrecht/sdk';

try {
  const orders = await client.orders.list();
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Auth failed:', error.message);
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof PermissionError) {
    console.error('Insufficient permissions:', error.message);
  } else if (error instanceof NotFoundError) {
    console.error('Resource not found:', error.message);
  } else if (error instanceof ValidationError) {
    console.error('Validation failed:', error.message);
  } else if (error instanceof HuntrechtError) {
    console.error(`API error: ${error.message} (status=${error.status})`);
  }
}

Environment Variables

Variable	Description
HUNTRECHT_BASE_URL	API base URL (default: https://api.huntrecht.com)
HUNTRECHT_CLIENT_ID	OAuth2 client ID
HUNTRECHT_CLIENT_SECRET	OAuth2 client secret

Rate Limits

Rate limits are based on your subscription plan. The SDK handles 429 responses automatically with exponential backoff.

Plan	Requests/Minute
Starter	60
Basic	300
Standard	1,000
Pro	3,000
Enterprise	10,000

Browser Usage

The SDK uses native fetch and works in any modern browser:

import { HuntrechtClient } from '@huntrecht/sdk';

const client = new HuntrechtClient({
  clientId: 'hnt_abc',
  clientSecret: 'secret',
  // In browser, set base URL explicitly if different from default
  baseUrl: 'https://api.huntrecht.com',
});

const orders = await client.orders.list();