@ultra-network/sdk-ts

Official TypeScript client for the Ultra Network Public API v1.

Typed for trips, suppliers, and bookings. The types are generated from the same OpenAPI document that powers the API, MCP server, and CLI — so the SDK never drifts from the contract.

Install

npm install @ultra-network/sdk-ts

Requires Node 20+ (or any runtime with a global fetch). Zero runtime dependencies.

Quick start

import { UltraClient } from '@ultra-network/sdk-ts';

const ultra = new UltraClient({ apiKey: process.env.ULTRA_API_KEY! });

// Browse preferred hotel suppliers
const { data, page } = await ultra.suppliers.list({ category: 'hotel', limit: 25 });

// Build a trip
const trip = await ultra.trips.create({ client_id, title: 'Cartagena anniversary' });
await ultra.trips.items.create(trip.id, {
  type: 'accommodation',
  title: 'Casa San Agustín',
  day_index: 0,
});

// Record a booking
const booking = await ultra.bookings.create({
  trip_id: trip.id,
  supplier_source: 'manual',
  venue_name: 'Casa San Agustín',
  total: { amount: 120000, currency: 'USD' },
});

Errors

Every non-2xx response throws UltraApiError. Branch on code, never message:

import { UltraApiError } from '@ultra-network/sdk-ts';

try {
  await ultra.trips.get(id);
} catch (err) {
  if (err instanceof UltraApiError && err.code === 'not_found') {
    // handle the missing trip; err.requestId mirrors the X-Request-Id header
  }
}

Pagination

List methods return { data, page } with an opaque keyset cursor. Pass page.next_cursor back as cursor:

let cursor: string | undefined;
const all = [];
do {
  const res = await ultra.trips.list({ cursor });
  all.push(...res.data);
  cursor = res.page.next_cursor ?? undefined;
} while (cursor);

Configuration

| Option | Default | Notes | | --- | --- | --- | | apiKey | — | Required. Bearer key (ulk_…) from the developer dashboard. | | baseUrl | https://ultranetwork.co/api/v1 | Override for staging or self-hosted. | | fetch | global fetch | Pass a custom implementation on runtimes without one. |

Spec-driven

Types live in src/generated/schema.d.ts, regenerated from the live OpenAPI spec with npm run generate. Same contract, every surface — see the MCP server and CLI.

Links

• Developer hub — https://ultranetwork.co/developers
• Interactive API reference — https://ultranetwork.co/api/v1/docs

License

MIT