Skip to main content

Node.js SDK

Installation​

npm install @flexops/sdk

Quick Start​

import { FlexOps } from '@flexops/sdk';

const client = new FlexOps({ apiKey: 'your-api-key' });

// Get shipping rates
const rates = await client.rates.get({
  from: { zip: '80202', country: 'US' },
  to: { zip: '10001', country: 'US' },
  parcel: { weight: 2.5, length: 10, width: 8, height: 4 },
});

console.log(rates.rates[0].carrier, rates.rates[0].totalPrice);

Configuration​

const client = new FlexOps({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.flexops.io/v1',  // optional
  timeout: 30000,                         // ms, default 30s
  maxRetries: 3,                          // default 3
});

Shipping Operations​

Create a Label​

const label = await client.labels.create({
  carrier: 'usps',
  service: 'priority',
  from: {
    name: 'Warehouse',
    street1: '123 Main St',
    city: 'Denver',
    state: 'CO',
    zip: '80202',
    country: 'US',
  },
  to: {
    name: 'Customer',
    street1: '456 Broadway',
    city: 'New York',
    state: 'NY',
    zip: '10001',
    country: 'US',
  },
  parcel: { weight: 2.5, length: 10, width: 8, height: 4 },
}, {
  idempotencyKey: 'order-12345',
});

console.log(label.trackingNumber);
console.log(label.labelUrl);

Track a Shipment​

const tracking = await client.tracking.get('9400111899223456789012');

console.log(tracking.status);        // 'in_transit'
console.log(tracking.estimatedDelivery);
tracking.events.forEach(e => console.log(e.timestamp, e.description));

Validate an Address​

const result = await client.addresses.validate({
  street1: '123 Main St',
  city: 'Denver',
  state: 'CO',
  zip: '80202',
  country: 'US',
});

if (result.isValid) {
  console.log('Validated:', result.normalized);
}

Batch Label Creation​

const batch = await client.labels.createBatch([
  { carrier: 'usps', service: 'priority', from: {...}, to: {...}, parcel: {...} },
  { carrier: 'usps', service: 'priority', from: {...}, to: {...}, parcel: {...} },
]);

batch.results.forEach(r => {
  if (r.success) console.log(r.label.trackingNumber);
  else console.error(r.error);
});

Webhook Verification​

import { verifyWebhookSignature } from '@flexops/sdk';

app.post('/webhooks/flexops', (req, res) => {
  const isValid = verifyWebhookSignature(
    req.body,
    req.headers['x-flexops-signature'],
    'whsec_your_secret'
  );

  if (!isValid) return res.status(401).send('Invalid signature');

  const event = req.body;
  switch (event.type) {
    case 'tracking.delivered':
      handleDelivery(event.data);
      break;
  }

  res.status(200).send('OK');
});

Error Handling​

import { FlexOpsError, RateLimitError } from '@flexops/sdk';

try {
  const label = await client.labels.create({...});
} catch (err) {
  if (err instanceof RateLimitError) {
    console.log(`Retry after ${err.retryAfter} seconds`);
  } else if (err instanceof FlexOpsError) {
    console.error(err.code, err.message);
  }
}

TypeScript Support​

The SDK is written in TypeScript and ships with full type definitions. All request/response objects are fully typed.

import type { Rate, Label, TrackingEvent } from '@flexops/sdk';