Skip to content
Skunivo Help Center

Skunivo Node.js SDK

The first official Skunivo SDK is the TypeScript-first Skunivo Node.js SDK package @skunivo/sdk.

The SDK targets the public organization API authenticated with API keys. It does not use human session cookies, admin routes or private panel contracts.

Current Status

Section titled “Current Status”

The SDK is currently a local pre-release package in sdks/skunivo-sdk-js. It covers all 71 operations in the public OpenAPI contract, is licensed under Apache 2.0, and remains marked private: true, so npm installation is not the supported path yet.

Use it from this repository with a local file dependency:

{
  "dependencies": {
    "@skunivo/sdk": "file:../sdks/skunivo-sdk-js"
  }
}

Create A Client

Section titled “Create A Client”
import { SkunivoClient } from '@skunivo/sdk'


const client = new SkunivoClient({
  baseUrl: process.env.SKUNIVO_BASE_URL!,
  apiKey: process.env.SKUNIVO_API_KEY!,
  organizationId: process.env.SKUNIVO_ORGANIZATION_ID!
})

The client sends Authorization: Bearer <api-key> and X-Request-Id on requests. Write operations can send an Idempotency-Key.

Run The Local Examples

Section titled “Run The Local Examples”

The runnable examples are the fastest way to validate SDK usage against a real API environment:

Terminal window
cd skunivo-public-api-examples
pnpm install
cp .env.example .env
pnpm start

The examples build and consume the local SDK. They do not maintain a separate HTTP client for production integration logic.

Use the focused examples when you need capabilities beyond the basic flow:

Terminal window
pnpm advanced-inventory
pnpm reports
SKUNIVO_REPORT_FORMAT=xlsx pnpm reports

The advanced inventory example covers compositions, lots, lot balances and serials. The reports example requires reports:read, reports:export and an eligible plan.

Download Reports

Section titled “Download Reports”
import { writeFile } from 'node:fs/promises'


const exportJob = await client.reportExports.create({
  reportType: 'inventory_snapshot',
  format: 'xlsx'
})
const download = await client.reportExports.download(exportJob.id)


await writeFile(download.filename ?? 'inventory.xlsx', download.data)

Downloads return FileDownload: unchanged bytes in data, a safe contentType, and an optional filename parsed from Content-Disposition. The SDK never writes the file or exposes the Fetch Response.

Write Safely

Section titled “Write Safely”
import { createIdempotencyKey } from '@skunivo/sdk'


const product = await client.products.create(
  {
    name: 'Demo T-Shirt',
    sku: 'DEMO-TSHIRT-001',
    baseUnitCode: 'EA'
  },
  { idempotencyKey: createIdempotencyKey('product', 'demo-001') }
)

Use one idempotency key per logical write operation. Reuse the same key only when retrying the exact same request.

Handle Errors

Section titled “Handle Errors”
import { SkunivoApiError } from '@skunivo/sdk'


try {
  await client.balances.list()
} catch (error) {
  if (error instanceof SkunivoApiError) {
    console.error(error.status, error.code, error.requestId, error.details)
  }
}

Use code for programmatic handling and keep requestId in logs and support tickets.

Server-Side Only

Section titled “Server-Side Only”

Do not use server-side API keys directly from browser applications. Browser-facing products should call your backend, and your backend should call Skunivo with the SDK.

Future npm Installation

Section titled “Future npm Installation”

When npm publication is approved, installation will use:

Terminal window
pnpm add @skunivo/sdk

Before that happens, Skunivo must confirm package ownership, versioning policy, package metadata and publishConfig. Treat npm examples as future-facing until those release decisions are complete. The source package already includes Apache 2.0 LICENSE and NOTICE files and records AIMove Logistics LLC as its author and maintainer.