TypeScript SDK

Status

A first-class TypeScript SDK package is on the roadmap. Until it ships, integrate via a typed fetch wrapper, the same pattern the marketplace frontend uses in frontend/lib/domains/leases/api/mutations.ts.

Minimal client

import { ulid } from "ulid";

type ApiResponse<T> = { data: T };

export class MarketplaceClient {
  constructor(
    private readonly baseUrl: string,
    private readonly token: string,
  ) {}

  async listValidators(limit = 20): Promise<ApiResponse<unknown[]>> {
    const res = await fetch(`${this.baseUrl}/v1/validators?limit=${limit}`, {
      headers: { "Authorization": `Bearer ${this.token}` },
    });
    if (!res.ok) throw new Error(`listValidators failed: ${res.status}`);
    return res.json() as Promise<ApiResponse<unknown[]>>;
  }

  async createLease(input: {
    validator_id: string;
    epoch_start: number;
    epoch_count: number;
  }): Promise<
    ApiResponse<{
      lease_id: string;
      payment: {
        solana_pay_url: string;
        amount_lamports: number;
        memo: string;
      };
    }>
  > {
    const res = await fetch(`${this.baseUrl}/v1/leases`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${this.token}`,
        "Idempotency-Key": ulid(), // must be a 26-char ULID
      },
      body: JSON.stringify(input),
    });
    if (!res.ok) throw new Error(`createLease failed: ${res.status}`);
    return res.json() as Promise<
      ApiResponse<{
        lease_id: string;
        payment: {
          solana_pay_url: string;
          amount_lamports: number;
          memo: string;
        };
      }>
    >;
  }
}

Type generation

Generate strongly-typed request and response shapes from the committed OpenAPI spec:

npx openapi-typescript https://docs.swqos.dev/openapi.json --output types/api.ts

This is the same command the marketplace frontend's CI runs to keep frontend/types/api.ts in sync with the backend (the build fails on a diff).