@ultra-network/sdk-ts 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ultra Network
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# @ultra-network/sdk-ts
+
+Official TypeScript client for the [Ultra Network Public API v1](https://ultranetwork.co/developers).
+
+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
+
+```bash
+npm install @ultra-network/sdk-ts
+```
+
+Requires Node 20+ (or any runtime with a global `fetch`). Zero runtime dependencies.
+
+## Quick start
+
+```ts
+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`:
+
+```ts
+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`:
+
+```ts
+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](https://www.npmjs.com/package/@ultra-network/mcp) and [CLI](https://www.npmjs.com/package/@ultra-network/cli).
+
+## Links
+
+- Developer hub — https://ultranetwork.co/developers
+- Interactive API reference — https://ultranetwork.co/api/v1/docs
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,114 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  UltraApiError: () => UltraApiError,
+  UltraClient: () => UltraClient,
+  createUltraClient: () => createUltraClient
+});
+module.exports = __toCommonJS(src_exports);
+var UltraApiError = class extends Error {
+  code;
+  status;
+  requestId;
+  details;
+  constructor(message, info) {
+    super(message);
+    this.name = "UltraApiError";
+    this.code = info.code;
+    this.status = info.status;
+    this.requestId = info.requestId;
+    this.details = info.details;
+  }
+};
+var DEFAULT_BASE_URL = "https://ultranetwork.co/api/v1";
+var UltraClient = class {
+  #apiKey;
+  #baseUrl;
+  #fetch;
+  constructor(config) {
+    if (!config?.apiKey) throw new Error("UltraClient: `apiKey` is required.");
+    this.#apiKey = config.apiKey;
+    this.#baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.#fetch = config.fetch ?? globalThis.fetch;
+    if (typeof this.#fetch !== "function") {
+      throw new Error("UltraClient: no `fetch` available \u2014 pass `config.fetch` on runtimes without a global fetch.");
+    }
+  }
+  async #request(method, path, opts) {
+    const url = new URL(this.#baseUrl + path);
+    if (opts?.query) {
+      for (const [key, value] of Object.entries(opts.query)) {
+        if (value !== void 0 && value !== null) url.searchParams.set(key, String(value));
+      }
+    }
+    const headers = {
+      Authorization: `Bearer ${this.#apiKey}`,
+      Accept: "application/json"
+    };
+    if (opts?.body !== void 0) headers["Content-Type"] = "application/json";
+    const res = await this.#fetch(url.toString(), {
+      method,
+      headers,
+      body: opts?.body !== void 0 ? JSON.stringify(opts.body) : void 0
+    });
+    if (res.status === 204) return void 0;
+    const text = await res.text();
+    const json = text ? JSON.parse(text) : void 0;
+    if (!res.ok) {
+      const envelope = json?.error;
+      throw new UltraApiError(envelope?.message ?? `Ultra API request failed with status ${res.status}`, {
+        code: envelope?.code ?? "unknown",
+        status: res.status,
+        requestId: envelope?.request_id ?? res.headers.get("x-request-id") ?? void 0,
+        details: envelope?.details
+      });
+    }
+    return json;
+  }
+  trips = {
+    list: (params) => this.#request("GET", "/trips", { query: params }),
+    create: (input) => this.#request("POST", "/trips", { body: input }),
+    get: (id) => this.#request("GET", `/trips/${encodeURIComponent(id)}`),
+    items: {
+      list: (tripId, params) => this.#request("GET", `/trips/${encodeURIComponent(tripId)}/items`, { query: params }),
+      create: (tripId, input) => this.#request("POST", `/trips/${encodeURIComponent(tripId)}/items`, { body: input }),
+      update: (tripId, itemId, input) => this.#request("PATCH", `/trips/${encodeURIComponent(tripId)}/items/${encodeURIComponent(itemId)}`, {
+        body: input
+      }),
+      remove: (tripId, itemId) => this.#request("DELETE", `/trips/${encodeURIComponent(tripId)}/items/${encodeURIComponent(itemId)}`)
+    }
+  };
+  suppliers = {
+    list: (params) => this.#request("GET", "/suppliers", { query: params }),
+    get: (id) => this.#request("GET", `/suppliers/${encodeURIComponent(id)}`)
+  };
+  bookings = {
+    list: (params) => this.#request("GET", "/bookings", { query: params }),
+    create: (input) => this.#request("POST", "/bookings", { body: input }),
+    get: (id) => this.#request("GET", `/bookings/${encodeURIComponent(id)}`),
+    update: (id, input) => this.#request("PATCH", `/bookings/${encodeURIComponent(id)}`, { body: input })
+  };
+};
+function createUltraClient(config) {
+  return new UltraClient(config);
+}
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @ultra-network/sdk-ts — official TypeScript client for the Ultra Network Public API v1.\n *\n * Types are derived from the same OpenAPI document that powers the API, MCP\n * server, and CLI (see ./generated/schema). One contract, every surface.\n *\n *   import { UltraClient } from '@ultra-network/sdk-ts';\n *   const ultra = new UltraClient({ apiKey: process.env.ULTRA_API_KEY! });\n *   const { data } = await ultra.suppliers.list({ category: 'hotel' });\n */\nimport type { components } from './generated/schema';\n\ntype Schemas = components['schemas'];\n\nexport type Money = Schemas['Money'];\nexport type PageMeta = Schemas['PageMeta'];\nexport type Trip = Schemas['Trip'];\nexport type CreateTripInput = Schemas['CreateTripInput'];\nexport type Supplier = Schemas['Supplier'];\nexport type SupplierContact = Schemas['SupplierContact'];\nexport type Booking = Schemas['Booking'];\nexport type CreateBookingInput = Schemas['CreateBookingInput'];\nexport type UpdateBookingInput = Schemas['UpdateBookingInput'];\nexport type TripItem = Schemas['TripItem'];\nexport type CreateTripItemInput = Schemas['CreateTripItemInput'];\nexport type UpdateTripItemInput = Schemas['UpdateTripItemInput'];\nexport type ApiErrorCode = Schemas['Error']['error']['code'];\n\n/** A keyset-paginated list response. Pass `page.next_cursor` back as `cursor` for the next page. */\nexport interface Page<T> {\n  data: T[];\n  page: PageMeta;\n}\n\nexport interface UltraClientConfig {\n  /** Bearer API key (`ulk_…`), issued from the Ultra developer dashboard. */\n  apiKey: string;\n  /** API base URL. Defaults to the production API. */\n  baseUrl?: string;\n  /** Custom fetch implementation. Defaults to the global `fetch`. */\n  fetch?: typeof fetch;\n}\n\nexport interface ListParams {\n  cursor?: string;\n  limit?: number;\n}\n\nexport interface ListTripsParams extends ListParams {\n  stage?: Trip['stage'];\n  organization_id?: string;\n  updated_since?: string;\n}\n\nexport interface ListSuppliersParams extends ListParams {\n  category?: Supplier['category'];\n  country?: string;\n  organization_id?: string;\n  active_only?: boolean;\n  updated_since?: string;\n}\n\nexport interface ListBookingsParams extends ListParams {\n  trip_id?: string;\n  status?: Booking['status'];\n  updated_since?: string;\n}\n\n/** Thrown for any non-2xx response. Branch on `code`, never `message`. */\nexport class UltraApiError extends Error {\n  readonly code: ApiErrorCode | 'unknown';\n  readonly status: number;\n  readonly requestId?: string;\n  readonly details?: Record<string, unknown>;\n\n  constructor(\n    message: string,\n    info: { code: ApiErrorCode | 'unknown'; status: number; requestId?: string; details?: Record<string, unknown> },\n  ) {\n    super(message);\n    this.name = 'UltraApiError';\n    this.code = info.code;\n    this.status = info.status;\n    this.requestId = info.requestId;\n    this.details = info.details;\n  }\n}\n\nconst DEFAULT_BASE_URL = 'https://ultranetwork.co/api/v1';\n\ntype QueryValue = string | number | boolean | undefined;\n\nexport class UltraClient {\n  readonly #apiKey: string;\n  readonly #baseUrl: string;\n  readonly #fetch: typeof fetch;\n\n  constructor(config: UltraClientConfig) {\n    if (!config?.apiKey) throw new Error('UltraClient: `apiKey` is required.');\n    this.#apiKey = config.apiKey;\n    this.#baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/+$/, '');\n    this.#fetch = config.fetch ?? globalThis.fetch;\n    if (typeof this.#fetch !== 'function') {\n      throw new Error('UltraClient: no `fetch` available — pass `config.fetch` on runtimes without a global fetch.');\n    }\n  }\n\n  async #request<T>(\n    method: string,\n    path: string,\n    opts?: { query?: object; body?: unknown },\n  ): Promise<T> {\n    const url = new URL(this.#baseUrl + path);\n    if (opts?.query) {\n      for (const [key, value] of Object.entries(opts.query as Record<string, QueryValue>)) {\n        if (value !== undefined && value !== null) url.searchParams.set(key, String(value));\n      }\n    }\n\n    const headers: Record<string, string> = {\n      Authorization: `Bearer ${this.#apiKey}`,\n      Accept: 'application/json',\n    };\n    if (opts?.body !== undefined) headers['Content-Type'] = 'application/json';\n\n    const res = await this.#fetch(url.toString(), {\n      method,\n      headers,\n      body: opts?.body !== undefined ? JSON.stringify(opts.body) : undefined,\n    });\n\n    if (res.status === 204) return undefined as T;\n\n    const text = await res.text();\n    const json: unknown = text ? JSON.parse(text) : undefined;\n\n    if (!res.ok) {\n      const envelope = (json as { error?: Schemas['Error']['error'] } | undefined)?.error;\n      throw new UltraApiError(envelope?.message ?? `Ultra API request failed with status ${res.status}`, {\n        code: envelope?.code ?? 'unknown',\n        status: res.status,\n        requestId: envelope?.request_id ?? res.headers.get('x-request-id') ?? undefined,\n        details: envelope?.details,\n      });\n    }\n\n    return json as T;\n  }\n\n  readonly trips = {\n    list: (params?: ListTripsParams) => this.#request<Page<Trip>>('GET', '/trips', { query: params }),\n    create: (input: CreateTripInput) => this.#request<Trip>('POST', '/trips', { body: input }),\n    get: (id: string) => this.#request<Trip>('GET', `/trips/${encodeURIComponent(id)}`),\n    items: {\n      list: (tripId: string, params?: ListParams) =>\n        this.#request<Page<TripItem>>('GET', `/trips/${encodeURIComponent(tripId)}/items`, { query: params }),\n      create: (tripId: string, input: CreateTripItemInput) =>\n        this.#request<TripItem>('POST', `/trips/${encodeURIComponent(tripId)}/items`, { body: input }),\n      update: (tripId: string, itemId: string, input: UpdateTripItemInput) =>\n        this.#request<TripItem>('PATCH', `/trips/${encodeURIComponent(tripId)}/items/${encodeURIComponent(itemId)}`, {\n          body: input,\n        }),\n      remove: (tripId: string, itemId: string) =>\n        this.#request<void>('DELETE', `/trips/${encodeURIComponent(tripId)}/items/${encodeURIComponent(itemId)}`),\n    },\n  };\n\n  readonly suppliers = {\n    list: (params?: ListSuppliersParams) => this.#request<Page<Supplier>>('GET', '/suppliers', { query: params }),\n    get: (id: string) => this.#request<Supplier>('GET', `/suppliers/${encodeURIComponent(id)}`),\n  };\n\n  readonly bookings = {\n    list: (params?: ListBookingsParams) => this.#request<Page<Booking>>('GET', '/bookings', { query: params }),\n    create: (input: CreateBookingInput) => this.#request<Booking>('POST', '/bookings', { body: input }),\n    get: (id: string) => this.#request<Booking>('GET', `/bookings/${encodeURIComponent(id)}`),\n    update: (id: string, input: UpdateBookingInput) =>\n      this.#request<Booking>('PATCH', `/bookings/${encodeURIComponent(id)}`, { body: input }),\n  };\n}\n\n/** Convenience factory — equivalent to `new UltraClient(config)`. */\nexport function createUltraClient(config: UltraClientConfig): UltraClient {\n  return new UltraClient(config);\n}\n"],"mappings":"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","names":[]}