weconnect-3pl

Official TypeScript/JavaScript SDK for the WeConnect 3PL API. A thin, fully-typed wrapper over the REST API (/api/v1) — authenticate with your tenant API key and call typed methods instead of writing fetch by hand.

• ✅ Works in Node 18+ and modern browsers (uses global fetch)
• ✅ Full TypeScript types for every request and response
• ✅ Throws a typed WeConnectApiError (code, status, message)
• ✅ Helper to verify inbound webhook signatures

Install

npm install weconnect-3pl

Local development install

Working against a local checkout instead? Build (npm run build) then install the folder directly — matching your consumer's package manager (npm install <path> / pnpm add <path> / yarn add <path>) — or npm pack and install the tarball.

Quick start

import { WeConnectClient } from "weconnect-3pl";

const client = new WeConnectClient({
  apiKey: process.env.WECONNECT_API_KEY!, // wc_live_…
  baseUrl: "https://app.weconnect3pl.com", // your API origin
});

// List fulfillment centers
const centers = await client.centers.list();

// Register a product
const product = await client.products.create({ sku: "MUG-WHT", name: "White Mug" });

// Set on-hand quantity for a SKU at a center (writes the immutable ledger)
const item = await client.inventory.adjust({
  centerId: centers[0].id,
  sku: "MUG-WHT",
  mode: "SET", // or "ADJUST" with `delta`
  quantity: 100,
  reason: "cycle count",
});

// Read that product's history
const history = await client.inventory.history({ productId: product.id, limit: 50 });
console.log(history.totalCount, history.items);

API surface

| Group | Methods | | ----- | ------- | | client.centers | list(), get(id), create(input), update(id, input) | | client.products | list({ search? }), get(id), create(input), update(id, input) | | client.inventory | list({ centerId?, productId?, search? }), adjust(input), history({ centerId?, productId?, type?, from?, to?, limit?, offset? }) | | client.shipments | list({ direction?, status? }), get(id), create(input), updateStatus(id, status), refreshTracking(id) | | client.transfers | list({ status? }), create(input), updateStatus(id, status) | | client.tracking | list({ shipmentId? }) |

GraphQL

Prefer GraphQL? The same client exposes a typed GraphQL client at client.graphql (talking to POST /api/graphql with the same API key), or import WeConnectGraphQLClient directly:

import { WeConnectClient, WeConnectGraphQLClient } from "weconnect-3pl";

const client = new WeConnectClient({ apiKey, baseUrl });

// Typed convenience methods
const centers = await client.graphql.centers();
const metrics = await client.graphql.overviewMetrics();
const item = await client.graphql.adjustInventory({ centerId, sku: "MUG-WHT", mode: "ADJUST", delta: 7 });
const history = await client.graphql.inventoryHistory({ productId, limit: 50 });

// Or run any custom operation with your own types
const gql = new WeConnectGraphQLClient({ apiKey, baseUrl });
const { products } = await gql.request<{ products: { sku: string }[] }>(
  `query { products { sku name } }`,
);

Available on client.graphql / WeConnectGraphQLClient: centers, products, inventory, inventoryHistory, shipments, transfers, trackingEvents, overviewMetrics, plus mutations createCenter, updateCenter, createProduct, updateProduct, adjustInventory, createShipment, updateShipmentStatus, refreshShipmentTracking, createTransfer, updateTransferStatus, and the generic request<TData, TVariables>(query, variables?). GraphQL result types are exported as Gql* (e.g. GqlShipment).

Error handling

import { WeConnectApiError } from "weconnect-3pl";

try {
  await client.centers.get("does-not-exist");
} catch (err) {
  if (err instanceof WeConnectApiError) {
    console.error(err.status, err.code, err.message); // e.g. 404 NOT_FOUND "Not found"
  }
}

Verifying webhooks (Node)

When WeConnect forwards events to your endpoint it signs the body with your endpoint secret. Verify it before trusting the payload:

import { verifyWebhookSignature, SIGNATURE_HEADER } from "weconnect-3pl";

// e.g. inside an Express handler with the RAW body
const ok = verifyWebhookSignature(
  process.env.WEBHOOK_SECRET!,
  rawBody, // the exact bytes, not parsed JSON
  req.headers[SIGNATURE_HEADER] as string,
);
if (!ok) return res.status(401).end();

Node < 18

Global fetch isn't available before Node 18 — pass your own:

import fetch from "node-fetch";
const client = new WeConnectClient({ apiKey, baseUrl, fetch: fetch as any });

License

MIT