@ultra-network/sdk-ts 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,575 @@
+interface components {
+  schemas: {
+    Money: {
+      /** Minor units (cents). 10000 = USD 100.00. */
+      amount: number;
+      /** ISO 4217 currency code. */
+      currency: string;
+    };
+    Error: {
+      error: {
+        code:
+          | 'unauthenticated'
+          | 'forbidden'
+          | 'not_found'
+          | 'method_not_allowed'
+          | 'validation_failed'
+          | 'rate_limited'
+          | 'conflict'
+          | 'internal_error'
+          | 'upstream_unavailable'
+          | 'feature_disabled';
+        message: string;
+        /** Same value as the X-Request-Id response header. */
+        request_id: string;
+        /** Optional structured context (e.g. Zod issues for validation_failed). */
+        details?: Record<string, unknown>;
+      };
+    };
+    PageMeta: {
+      /** Cursor for the next page. `null` when no more results. */
+      next_cursor: string | null;
+      has_more: boolean;
+      limit: number;
+    };
+    Trip: {
+      id: string;
+      organization_id: string;
+      title: string | null;
+      stage:
+        | 'enquiry_received'
+        | 'qualifying'
+        | 'draft_plan'
+        | 'proposal_sent'
+        | 'negotiating'
+        | 'booked'
+        | 'follow_up'
+        | 'in_progress'
+        | 'completed'
+        | 'lost'
+        | 'archived';
+      priority: 'low' | 'medium' | 'high' | 'urgent';
+      source: 'whatsapp' | 'sms' | 'email' | 'web_form' | 'widget' | 'manual' | 'phone';
+      destination: string | null;
+      origin_city: string | null;
+      start_date: string | null;
+      end_date: string | null;
+      party_size: number;
+      /** Indicative budget. May be advisor-internal — clients without view access see `null`. */
+      budget: components['schemas']['Money'] | null;
+      /** Lead traveller. PII (email, phone) is intentionally omitted from v1. */
+      client: { id: string; name: string } | null;
+      created_at: string;
+      updated_at: string;
+      booked_at: string | null;
+      completed_at: string | null;
+    };
+    CreateTripInput: {
+      /** Lead traveller — must already exist and belong to your org. */
+      client_id: string;
+      title?: string;
+      destination?: string;
+      origin_city?: string;
+      start_date?: string;
+      end_date?: string;
+      party_size?: number;
+      priority?: 'low' | 'medium' | 'high' | 'urgent';
+      source?: 'whatsapp' | 'sms' | 'email' | 'web_form' | 'widget' | 'manual' | 'phone';
+      budget?: components['schemas']['Money'];
+      special_requests?: string[];
+      /** Free-form notes attached to the trip. Stored but not surfaced in any public read. */
+      internal_notes?: string;
+    };
+    SupplierContact: {
+      name: string | null;
+      email: string | null;
+      phone: string | null;
+      website: string | null;
+    };
+    Supplier: {
+      id: string;
+      organization_id: string;
+      name: string;
+      category:
+        | 'hotel'
+        | 'restaurant'
+        | 'transport_car'
+        | 'transport_jet'
+        | 'transport_helicopter'
+        | 'flight'
+        | 'activity'
+        | 'cruise'
+        | 'tour'
+        | 'dmc'
+        | 'wholesale'
+        | 'platform'
+        | 'channel_manager'
+        | 'hub_marketplace'
+        | 'insurance'
+        | 'visa'
+        | 'other';
+      onboarding_status:
+        | 'pending_application'
+        | 'application_approved'
+        | 'profile_setup'
+        | 'documents_uploaded'
+        | 'agreement_pending'
+        | 'agreement_signed'
+        | 'active'
+        | 'suspended';
+      /** ISO 3166-1 alpha-2. */
+      country: string | null;
+      address: string | null;
+      logo_url: string | null;
+      cover_image_url: string | null;
+      is_active: boolean;
+      /** Hint that this supplier is on the Ultra preferred-partner list. A curation flag, not a quality score. */
+      is_preferred: boolean;
+      /** Null when the supplier is not fully onboarded (privacy gate). */
+      contact: components['schemas']['SupplierContact'] | null;
+      created_at: string;
+      updated_at: string;
+    };
+    Booking: {
+      id: string;
+      trip_id: string;
+      /** The supplier adapter that owns this booking (e.g. `hbt`, `drivado`, `manual`). */
+      supplier_source: string;
+      /** The supplier's own reference for this booking (PNR / confirmation code). */
+      supplier_booking_id: string | null;
+      venue_name: string;
+      venue_type: string | null;
+      destination: string | null;
+      check_in: string | null;
+      check_out: string | null;
+      guest_count: number | null;
+      total: components['schemas']['Money'];
+      status:
+        | 'provisional'
+        | 'confirmed'
+        | 'active'
+        | 'completed'
+        | 'expired'
+        | 'failed'
+        | 'cancelled'
+        | 'pending_supplier_confirmation'
+        | 'rejected'
+        | 'modified';
+      payment_status:
+        | 'pending'
+        | 'pending_confirmation'
+        | 'authorized'
+        | 'captured'
+        | 'partially_refunded'
+        | 'refunded'
+        | 'failed'
+        | 'cancelled'
+        | 'disputed';
+      /** Direct link to the supplier-issued voucher / itinerary PDF, when available. */
+      voucher_url: string | null;
+      created_at: string;
+      confirmed_at: string | null;
+      cancelled_at: string | null;
+      completed_at: string | null;
+      updated_at: string;
+    };
+    CreateBookingInput: {
+      /** The trip this booking belongs to. Must belong to your org. */
+      trip_id: string;
+      supplier_source?:
+        | 'manual'
+        | 'hbt'
+        | 'drivado'
+        | 'nuitee'
+        | 'ratestellar'
+        | 'saltours'
+        | 'mews'
+        | 'apaleo'
+        | 'tue'
+        | 'limohawk'
+        | 'oracle_ohip';
+      /** For `manual`: optional link to the trip item this confirms. For any adapter source: REQUIRED. */
+      plan_item_id?: string;
+      supplier_booking_id?: string;
+      venue_name?: string;
+      venue_type?: string;
+      destination?: string;
+      check_in?: string;
+      check_out?: string;
+      guest_count?: number;
+      total?: components['schemas']['Money'];
+      voucher_url?: string;
+      /** Lead guest. Required for adapter-dispatched sources; ignored for `manual`. */
+      guest?: {
+        first_name: string;
+        last_name: string;
+        email?: string;
+        phone?: string;
+        nationality?: string;
+      };
+    };
+    UpdateBookingInput: {
+      status?: components['schemas']['Booking']['status'];
+      payment_status?: components['schemas']['Booking']['payment_status'];
+      supplier_booking_id?: string | null;
+      voucher_url?: string | null;
+      cancellation_reason?: string;
+    };
+    TripItem: {
+      id: string;
+      type: 'accommodation' | 'transport' | 'activity' | 'dining' | 'other';
+      title: string;
+      /** 0-indexed day within the trip. Day 0 = arrival day. */
+      day_index: number;
+      location: string | null;
+      /** 24-hour HH:MM. Null when not scheduled. */
+      start_time: string | null;
+      end_time: string | null;
+      check_in: string | null;
+      check_out: string | null;
+      notes: string | null;
+      price: components['schemas']['Money'] | null;
+      supplier_source: string | null;
+    };
+    CreateTripItemInput: {
+      type: 'accommodation' | 'transport' | 'activity' | 'dining' | 'other';
+      title: string;
+      day_index: number;
+      location?: string;
+      start_time?: string;
+      end_time?: string;
+      check_in?: string;
+      check_out?: string;
+      notes?: string;
+      price?: components['schemas']['Money'];
+      supplier_source?: string;
+    };
+    UpdateTripItemInput: {
+      type?: 'accommodation' | 'transport' | 'activity' | 'dining' | 'other';
+      title?: string;
+      day_index?: number;
+      location?: string | null;
+      start_time?: string | null;
+      end_time?: string | null;
+      check_in?: string | null;
+      check_out?: string | null;
+      notes?: string | null;
+      price?: components['schemas']['Money'] | null;
+      supplier_source?: string | null;
+    };
+  };
+}
+
+/**
+ * @ultra-network/sdk-ts — official TypeScript client for the Ultra Network Public API v1.
+ *
+ * Types are derived from the same OpenAPI document that powers the API, MCP
+ * server, and CLI (see ./generated/schema). One contract, every surface.
+ *
+ *   import { UltraClient } from '@ultra-network/sdk-ts';
+ *   const ultra = new UltraClient({ apiKey: process.env.ULTRA_API_KEY! });
+ *   const { data } = await ultra.suppliers.list({ category: 'hotel' });
+ */
+
+type Schemas = components['schemas'];
+type Money = Schemas['Money'];
+type PageMeta = Schemas['PageMeta'];
+type Trip = Schemas['Trip'];
+type CreateTripInput = Schemas['CreateTripInput'];
+type Supplier = Schemas['Supplier'];
+type SupplierContact = Schemas['SupplierContact'];
+type Booking = Schemas['Booking'];
+type CreateBookingInput = Schemas['CreateBookingInput'];
+type UpdateBookingInput = Schemas['UpdateBookingInput'];
+type TripItem = Schemas['TripItem'];
+type CreateTripItemInput = Schemas['CreateTripItemInput'];
+type UpdateTripItemInput = Schemas['UpdateTripItemInput'];
+type ApiErrorCode = Schemas['Error']['error']['code'];
+/** A keyset-paginated list response. Pass `page.next_cursor` back as `cursor` for the next page. */
+interface Page<T> {
+    data: T[];
+    page: PageMeta;
+}
+interface UltraClientConfig {
+    /** Bearer API key (`ulk_…`), issued from the Ultra developer dashboard. */
+    apiKey: string;
+    /** API base URL. Defaults to the production API. */
+    baseUrl?: string;
+    /** Custom fetch implementation. Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+}
+interface ListParams {
+    cursor?: string;
+    limit?: number;
+}
+interface ListTripsParams extends ListParams {
+    stage?: Trip['stage'];
+    organization_id?: string;
+    updated_since?: string;
+}
+interface ListSuppliersParams extends ListParams {
+    category?: Supplier['category'];
+    country?: string;
+    organization_id?: string;
+    active_only?: boolean;
+    updated_since?: string;
+}
+interface ListBookingsParams extends ListParams {
+    trip_id?: string;
+    status?: Booking['status'];
+    updated_since?: string;
+}
+/** Thrown for any non-2xx response. Branch on `code`, never `message`. */
+declare class UltraApiError extends Error {
+    readonly code: ApiErrorCode | 'unknown';
+    readonly status: number;
+    readonly requestId?: string;
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, info: {
+        code: ApiErrorCode | 'unknown';
+        status: number;
+        requestId?: string;
+        details?: Record<string, unknown>;
+    });
+}
+declare class UltraClient {
+    #private;
+    constructor(config: UltraClientConfig);
+    readonly trips: {
+        list: (params?: ListTripsParams) => Promise<Page<{
+            id: string;
+            organization_id: string;
+            title: string | null;
+            stage: "enquiry_received" | "qualifying" | "draft_plan" | "proposal_sent" | "negotiating" | "booked" | "follow_up" | "in_progress" | "completed" | "lost" | "archived";
+            priority: "low" | "medium" | "high" | "urgent";
+            source: "whatsapp" | "sms" | "email" | "web_form" | "widget" | "manual" | "phone";
+            destination: string | null;
+            origin_city: string | null;
+            start_date: string | null;
+            end_date: string | null;
+            party_size: number;
+            budget: components["schemas"]["Money"] | null;
+            client: {
+                id: string;
+                name: string;
+            } | null;
+            created_at: string;
+            updated_at: string;
+            booked_at: string | null;
+            completed_at: string | null;
+        }>>;
+        create: (input: CreateTripInput) => Promise<{
+            id: string;
+            organization_id: string;
+            title: string | null;
+            stage: "enquiry_received" | "qualifying" | "draft_plan" | "proposal_sent" | "negotiating" | "booked" | "follow_up" | "in_progress" | "completed" | "lost" | "archived";
+            priority: "low" | "medium" | "high" | "urgent";
+            source: "whatsapp" | "sms" | "email" | "web_form" | "widget" | "manual" | "phone";
+            destination: string | null;
+            origin_city: string | null;
+            start_date: string | null;
+            end_date: string | null;
+            party_size: number;
+            budget: components["schemas"]["Money"] | null;
+            client: {
+                id: string;
+                name: string;
+            } | null;
+            created_at: string;
+            updated_at: string;
+            booked_at: string | null;
+            completed_at: string | null;
+        }>;
+        get: (id: string) => Promise<{
+            id: string;
+            organization_id: string;
+            title: string | null;
+            stage: "enquiry_received" | "qualifying" | "draft_plan" | "proposal_sent" | "negotiating" | "booked" | "follow_up" | "in_progress" | "completed" | "lost" | "archived";
+            priority: "low" | "medium" | "high" | "urgent";
+            source: "whatsapp" | "sms" | "email" | "web_form" | "widget" | "manual" | "phone";
+            destination: string | null;
+            origin_city: string | null;
+            start_date: string | null;
+            end_date: string | null;
+            party_size: number;
+            budget: components["schemas"]["Money"] | null;
+            client: {
+                id: string;
+                name: string;
+            } | null;
+            created_at: string;
+            updated_at: string;
+            booked_at: string | null;
+            completed_at: string | null;
+        }>;
+        items: {
+            list: (tripId: string, params?: ListParams) => Promise<Page<{
+                id: string;
+                type: "accommodation" | "transport" | "activity" | "dining" | "other";
+                title: string;
+                day_index: number;
+                location: string | null;
+                start_time: string | null;
+                end_time: string | null;
+                check_in: string | null;
+                check_out: string | null;
+                notes: string | null;
+                price: components["schemas"]["Money"] | null;
+                supplier_source: string | null;
+            }>>;
+            create: (tripId: string, input: CreateTripItemInput) => Promise<{
+                id: string;
+                type: "accommodation" | "transport" | "activity" | "dining" | "other";
+                title: string;
+                day_index: number;
+                location: string | null;
+                start_time: string | null;
+                end_time: string | null;
+                check_in: string | null;
+                check_out: string | null;
+                notes: string | null;
+                price: components["schemas"]["Money"] | null;
+                supplier_source: string | null;
+            }>;
+            update: (tripId: string, itemId: string, input: UpdateTripItemInput) => Promise<{
+                id: string;
+                type: "accommodation" | "transport" | "activity" | "dining" | "other";
+                title: string;
+                day_index: number;
+                location: string | null;
+                start_time: string | null;
+                end_time: string | null;
+                check_in: string | null;
+                check_out: string | null;
+                notes: string | null;
+                price: components["schemas"]["Money"] | null;
+                supplier_source: string | null;
+            }>;
+            remove: (tripId: string, itemId: string) => Promise<void>;
+        };
+    };
+    readonly suppliers: {
+        list: (params?: ListSuppliersParams) => Promise<Page<{
+            id: string;
+            organization_id: string;
+            name: string;
+            category: "hotel" | "restaurant" | "transport_car" | "transport_jet" | "transport_helicopter" | "flight" | "activity" | "cruise" | "tour" | "dmc" | "wholesale" | "platform" | "channel_manager" | "hub_marketplace" | "insurance" | "visa" | "other";
+            onboarding_status: "pending_application" | "application_approved" | "profile_setup" | "documents_uploaded" | "agreement_pending" | "agreement_signed" | "active" | "suspended";
+            country: string | null;
+            address: string | null;
+            logo_url: string | null;
+            cover_image_url: string | null;
+            is_active: boolean;
+            is_preferred: boolean;
+            contact: components["schemas"]["SupplierContact"] | null;
+            created_at: string;
+            updated_at: string;
+        }>>;
+        get: (id: string) => Promise<{
+            id: string;
+            organization_id: string;
+            name: string;
+            category: "hotel" | "restaurant" | "transport_car" | "transport_jet" | "transport_helicopter" | "flight" | "activity" | "cruise" | "tour" | "dmc" | "wholesale" | "platform" | "channel_manager" | "hub_marketplace" | "insurance" | "visa" | "other";
+            onboarding_status: "pending_application" | "application_approved" | "profile_setup" | "documents_uploaded" | "agreement_pending" | "agreement_signed" | "active" | "suspended";
+            country: string | null;
+            address: string | null;
+            logo_url: string | null;
+            cover_image_url: string | null;
+            is_active: boolean;
+            is_preferred: boolean;
+            contact: components["schemas"]["SupplierContact"] | null;
+            created_at: string;
+            updated_at: string;
+        }>;
+    };
+    readonly bookings: {
+        list: (params?: ListBookingsParams) => Promise<Page<{
+            id: string;
+            trip_id: string;
+            supplier_source: string;
+            supplier_booking_id: string | null;
+            venue_name: string;
+            venue_type: string | null;
+            destination: string | null;
+            check_in: string | null;
+            check_out: string | null;
+            guest_count: number | null;
+            total: components["schemas"]["Money"];
+            status: "provisional" | "confirmed" | "active" | "completed" | "expired" | "failed" | "cancelled" | "pending_supplier_confirmation" | "rejected" | "modified";
+            payment_status: "pending" | "pending_confirmation" | "authorized" | "captured" | "partially_refunded" | "refunded" | "failed" | "cancelled" | "disputed";
+            voucher_url: string | null;
+            created_at: string;
+            confirmed_at: string | null;
+            cancelled_at: string | null;
+            completed_at: string | null;
+            updated_at: string;
+        }>>;
+        create: (input: CreateBookingInput) => Promise<{
+            id: string;
+            trip_id: string;
+            supplier_source: string;
+            supplier_booking_id: string | null;
+            venue_name: string;
+            venue_type: string | null;
+            destination: string | null;
+            check_in: string | null;
+            check_out: string | null;
+            guest_count: number | null;
+            total: components["schemas"]["Money"];
+            status: "provisional" | "confirmed" | "active" | "completed" | "expired" | "failed" | "cancelled" | "pending_supplier_confirmation" | "rejected" | "modified";
+            payment_status: "pending" | "pending_confirmation" | "authorized" | "captured" | "partially_refunded" | "refunded" | "failed" | "cancelled" | "disputed";
+            voucher_url: string | null;
+            created_at: string;
+            confirmed_at: string | null;
+            cancelled_at: string | null;
+            completed_at: string | null;
+            updated_at: string;
+        }>;
+        get: (id: string) => Promise<{
+            id: string;
+            trip_id: string;
+            supplier_source: string;
+            supplier_booking_id: string | null;
+            venue_name: string;
+            venue_type: string | null;
+            destination: string | null;
+            check_in: string | null;
+            check_out: string | null;
+            guest_count: number | null;
+            total: components["schemas"]["Money"];
+            status: "provisional" | "confirmed" | "active" | "completed" | "expired" | "failed" | "cancelled" | "pending_supplier_confirmation" | "rejected" | "modified";
+            payment_status: "pending" | "pending_confirmation" | "authorized" | "captured" | "partially_refunded" | "refunded" | "failed" | "cancelled" | "disputed";
+            voucher_url: string | null;
+            created_at: string;
+            confirmed_at: string | null;
+            cancelled_at: string | null;
+            completed_at: string | null;
+            updated_at: string;
+        }>;
+        update: (id: string, input: UpdateBookingInput) => Promise<{
+            id: string;
+            trip_id: string;
+            supplier_source: string;
+            supplier_booking_id: string | null;
+            venue_name: string;
+            venue_type: string | null;
+            destination: string | null;
+            check_in: string | null;
+            check_out: string | null;
+            guest_count: number | null;
+            total: components["schemas"]["Money"];
+            status: "provisional" | "confirmed" | "active" | "completed" | "expired" | "failed" | "cancelled" | "pending_supplier_confirmation" | "rejected" | "modified";
+            payment_status: "pending" | "pending_confirmation" | "authorized" | "captured" | "partially_refunded" | "refunded" | "failed" | "cancelled" | "disputed";
+            voucher_url: string | null;
+            created_at: string;
+            confirmed_at: string | null;
+            cancelled_at: string | null;
+            completed_at: string | null;
+            updated_at: string;
+        }>;
+    };
+}
+/** Convenience factory — equivalent to `new UltraClient(config)`. */
+declare function createUltraClient(config: UltraClientConfig): UltraClient;
+
+export { type ApiErrorCode, type Booking, type CreateBookingInput, type CreateTripInput, type CreateTripItemInput, type ListBookingsParams, type ListParams, type ListSuppliersParams, type ListTripsParams, type Money, type Page, type PageMeta, type Supplier, type SupplierContact, type Trip, type TripItem, UltraApiError, UltraClient, type UltraClientConfig, type UpdateBookingInput, type UpdateTripItemInput, createUltraClient };

package/dist/index.js

@@ -0,0 +1,93 @@
+// src/index.ts
+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);
+}
+export {
+  UltraApiError,
+  UltraClient,
+  createUltraClient
+};
+//# sourceMappingURL=index.js.map