JavaScript SDK

Official JavaScript/TypeScript SDK for the Heydeo API.

Installation

npm install @heydeo/sdk

Quick Start

import { HeydeoClient } from '@heydeo/sdk';

// Initialize the client
const client = new HeydeoClient({
  apiKey: process.env.HEYDEO_API_KEY,
  baseURL: 'https://api.heydeo.ai/v1', // optional
});

// Search for shipments
const shipments = await client.shipments.search({
  origin: 'US',
  destination: 'CN',
  hsCode: '8517',
  page: 1,
  limit: 20,
});

console.log(shipments);

Configuration

const client = new HeydeoClient({
  apiKey: 'your-api-key',           // Required
  baseURL: 'https://api.heydeo.ai/v1', // Optional
  timeout: 30000,                   // Optional (default: 30s)
  maxRetries: 3,                    // Optional (default: 3)
});

Shipments

Search Shipments

const shipments = await client.shipments.search({
  origin: 'US',
  destination: 'CN',
  hsCode: '8517',
  dateFrom: '2024-01-01',
  dateTo: '2024-12-31',
  page: 1,
  limit: 20,
});

Get Shipment Details

const shipment = await client.shipments.get('shipment-id');

HS Codes

Search HS Codes

const hsCodes = await client.hsCodes.search({
  query: 'smartphone',
  chapter: '85', // Optional
});

Get HS Code Details

const hsCode = await client.hsCodes.get('8517');

Buyers

Search Buyers

const buyers = await client.buyers.search({
  country: 'CN',
  hsCode: '8517',
  minVolume: 1000,
});

Get Buyer Details

const buyer = await client.buyers.get('buyer-id');

Documents

Generate Document

const document = await client.documents.generate({
  type: 'COMMERCIAL_INVOICE',
  shipmentId: 'shipment-id',
  data: {
    invoiceNumber: 'INV-001',
    seller: { name: 'Acme Corp', address: '...' },
    buyer: { name: 'Buyer Ltd', address: '...' },
    items: [
      { description: 'Product A', quantity: 100, unitPrice: 50 }
    ],
  },
});

Download Document

const pdf = await client.documents.download('document-id');

Error Handling

import { HeydeoError } from '@heydeo/sdk';

try {
  const shipments = await client.shipments.search({ origin: 'US' });
} catch (error) {
  if (error instanceof HeydeoError) {
    console.error('API Error:', error.message);
    console.error('Status:', error.status);
    console.error('Code:', error.code);
  } else {
    console.error('Unexpected error:', error);
  }
}

TypeScript

The SDK includes full TypeScript definitions:

import { 
  HeydeoClient, 
  Shipment, 
  HSCode, 
  Buyer,
  DocumentType 
} from '@heydeo/sdk';

const shipments: Shipment[] = await client.shipments.search({
  origin: 'US',
  destination: 'CN',
});

📚 Additional Resources