@lasersell/lasersell-sdk 0.1.0

package/src/exitApi.ts

@@ -0,0 +1,385 @@
+import {
+  LOW_LATENCY_RETRY_POLICY,
+  retryAsync,
+  type RetryPolicy,
+} from "./retry.js";
+import type { MarketContextMsg } from "./stream/proto.js";
+
+const ERROR_BODY_SNIPPET_LEN = 220;
+
+export const EXIT_API_BASE_URL = "https://api.lasersell.io";
+export const LOCAL_EXIT_API_BASE_URL = "http://localhost:8080";
+
+export const EXIT_API_DEFAULTS = {
+  connect_timeout_ms: 200,
+  attempt_timeout_ms: 900,
+  max_attempts: 2,
+  backoff_ms: 25,
+  jitter_ms: 25,
+} as const;
+
+export type SellOutput = "SOL" | "USD1";
+
+/** Transaction send mode for the exit API. */
+export type SendMode = "helius_sender" | "astralane" | "rpc";
+
+export interface BuildSellTxRequest {
+  mint: string;
+  user_pubkey: string;
+  amount_tokens: number;
+  slippage_bps?: number;
+  mode?: string;
+  output?: SellOutput;
+  market_context?: MarketContextMsg;
+  /** Transaction send mode: `"helius_sender"`, `"astralane"`, or `"rpc"`. */
+  send_mode?: SendMode;
+  /** Optional tip amount in lamports for the transaction. */
+  tip_lamports?: number;
+}
+
+export interface BuildBuyTxRequest {
+  mint: string;
+  user_pubkey: string;
+  amount_quote_units: number;
+  slippage_bps?: number;
+  mode?: string;
+  /** Transaction send mode: `"helius_sender"`, `"astralane"`, or `"rpc"`. */
+  send_mode?: SendMode;
+  /** Optional tip amount in lamports for the transaction. */
+  tip_lamports?: number;
+}
+
+export interface BuildTxResponse {
+  tx: string;
+  route?: unknown;
+  debug?: unknown;
+}
+
+export interface ExitApiClientOptions {
+  // Kept for parity with the Rust SDK. Fetch does not expose a strict
+  // connection-only timeout across environments.
+  connect_timeout_ms: number;
+  attempt_timeout_ms: number;
+  retry_policy: RetryPolicy;
+  fetch_impl: FetchLike;
+}
+
+export type ExitApiErrorKind =
+  | "transport"
+  | "http_status"
+  | "envelope_status"
+  | "parse";
+
+export class ExitApiError extends Error {
+  readonly kind: ExitApiErrorKind;
+  readonly status?: number;
+  readonly body?: string;
+  readonly detail?: string;
+
+  private constructor(
+    kind: ExitApiErrorKind,
+    message: string,
+    options?: {
+      cause?: unknown;
+      status?: number;
+      body?: string;
+      detail?: string;
+    },
+  ) {
+    super(message, { cause: options?.cause });
+    this.name = "ExitApiError";
+    this.kind = kind;
+    this.status = options?.status;
+    this.body = options?.body;
+    this.detail = options?.detail;
+  }
+
+  static transport(cause: unknown): ExitApiError {
+    return new ExitApiError(
+      "transport",
+      `request failed: ${stringifyError(cause)}`,
+      { cause },
+    );
+  }
+
+  static httpStatus(status: number, body: string): ExitApiError {
+    return new ExitApiError("http_status", `http status ${status}: ${body}`, {
+      status,
+      body,
+    });
+  }
+
+  static envelopeStatus(status: string, detail: string): ExitApiError {
+    return new ExitApiError(
+      "envelope_status",
+      `exit-api status ${status}: ${detail}`,
+      { detail },
+    );
+  }
+
+  static parse(message: string, cause?: unknown): ExitApiError {
+    return new ExitApiError("parse", `failed to parse response: ${message}`, {
+      cause,
+    });
+  }
+
+  isRetryable(): boolean {
+    if (this.kind === "transport") {
+      return true;
+    }
+
+    if (this.kind === "http_status") {
+      return (
+        (this.status !== undefined && this.status >= 500) || this.status === 429
+      );
+    }
+
+    return false;
+  }
+}
+
+export class ExitApiClient {
+  private readonly apiKey?: string;
+  private readonly connectTimeoutMs: number;
+  private readonly attemptTimeoutMs: number;
+  private readonly retryPolicy: RetryPolicy;
+  private readonly fetchImpl: FetchLike;
+  private local = false;
+  private baseUrlOverride?: string;
+
+  constructor(
+    apiKey?: string,
+    options: Partial<ExitApiClientOptions> = {},
+  ) {
+    this.apiKey = apiKey;
+    this.connectTimeoutMs =
+      options.connect_timeout_ms ?? EXIT_API_DEFAULTS.connect_timeout_ms;
+    this.attemptTimeoutMs =
+      options.attempt_timeout_ms ?? EXIT_API_DEFAULTS.attempt_timeout_ms;
+    this.retryPolicy = options.retry_policy
+      ? { ...options.retry_policy }
+      : {
+          max_attempts: EXIT_API_DEFAULTS.max_attempts,
+          initial_backoff_ms: EXIT_API_DEFAULTS.backoff_ms,
+          max_backoff_ms: EXIT_API_DEFAULTS.backoff_ms,
+          jitter_ms: EXIT_API_DEFAULTS.jitter_ms,
+        };
+    this.fetchImpl = options.fetch_impl ?? globalThis.fetch;
+
+    if (typeof this.fetchImpl !== "function") {
+      throw new Error(
+        "No fetch implementation available. Provide options.fetch_impl in environments without global fetch.",
+      );
+    }
+  }
+
+  static withApiKey(apiKey: string): ExitApiClient {
+    return new ExitApiClient(apiKey);
+  }
+
+  static withOptions(
+    apiKey: string | undefined,
+    options: Partial<ExitApiClientOptions>,
+  ): ExitApiClient {
+    return new ExitApiClient(apiKey, options);
+  }
+
+  withLocalMode(local: boolean): this {
+    this.local = local;
+    return this;
+  }
+
+  withBaseUrl(baseUrl: string): this {
+    this.baseUrlOverride = baseUrl.trim().replace(/\/+$/, "");
+    return this;
+  }
+
+  async buildSellTx(request: BuildSellTxRequest): Promise<BuildTxResponse> {
+    return await this.buildTx("/v1/sell", request);
+  }
+
+  async buildSellTxB64(request: BuildSellTxRequest): Promise<string> {
+    const response = await this.buildSellTx(request);
+    return response.tx;
+  }
+
+  async buildBuyTx(request: BuildBuyTxRequest): Promise<BuildTxResponse> {
+    return await this.buildTx("/v1/buy", request);
+  }
+
+  private async buildTx<T extends object>(
+    path: string,
+    request: T,
+  ): Promise<BuildTxResponse> {
+    const endpoint = this.endpoint(path);
+    return await retryAsync(
+      this.retryPolicy,
+      async () => await this.sendAttempt(endpoint, request),
+      (error: unknown) =>
+        error instanceof ExitApiError && error.isRetryable(),
+    );
+  }
+
+  private endpoint(path: string): string {
+    return `${this.baseUrl()}${path}`;
+  }
+
+  private baseUrl(): string {
+    if (this.baseUrlOverride !== undefined) {
+      return this.baseUrlOverride;
+    }
+    if (this.local) {
+      return LOCAL_EXIT_API_BASE_URL;
+    }
+    return EXIT_API_BASE_URL;
+  }
+
+  private async sendAttempt<T extends object>(
+    endpoint: string,
+    request: T,
+  ): Promise<BuildTxResponse> {
+    const timeoutMs = Math.max(this.connectTimeoutMs, this.attemptTimeoutMs);
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+      controller.abort();
+    }, timeoutMs);
+
+    try {
+      const headers: Record<string, string> = {
+        "content-type": "application/json",
+      };
+
+      if (this.apiKey !== undefined) {
+        headers["x-api-key"] = this.apiKey;
+      }
+
+      const response = await this.fetchImpl(endpoint, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(request),
+        signal: controller.signal,
+      });
+
+      const body = await response.text();
+
+      if (!response.ok) {
+        throw ExitApiError.httpStatus(
+          response.status,
+          summarizeErrorBody(body),
+        );
+      }
+
+      return parseBuildTxResponse(body);
+    } catch (error) {
+      if (error instanceof ExitApiError) {
+        throw error;
+      }
+
+      throw ExitApiError.transport(error);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}
+
+export function parseBuildTxResponse(body: string): BuildTxResponse {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(body);
+  } catch (error) {
+    throw ExitApiError.parse("response was not valid JSON", error);
+  }
+
+  const obj = asRecord(parsed, "response");
+
+  const taggedStatus = asOptionalString(obj.status);
+  if (taggedStatus !== undefined) {
+    if (taggedStatus.toLowerCase() === "ok") {
+      const tx = asOptionalString(obj.tx) ?? asOptionalString(obj.unsigned_tx_b64);
+      if (tx === undefined) {
+        throw ExitApiError.parse("status=ok payload missing tx");
+      }
+      return {
+        tx,
+        route: obj.route,
+        debug: obj.debug,
+      };
+    }
+
+    const detail =
+      asOptionalString(obj.reason) ??
+      asOptionalString(obj.message) ??
+      asOptionalString(obj.error) ??
+      "unknown failure";
+
+    throw ExitApiError.envelopeStatus(taggedStatus, detail);
+  }
+
+  const legacyTx = asOptionalString(obj.unsigned_tx_b64);
+  if (legacyTx !== undefined) {
+    return {
+      tx: legacyTx,
+      route: obj.route,
+      debug: obj.debug,
+    };
+  }
+
+  const bareTx = asOptionalString(obj.tx);
+  if (bareTx !== undefined) {
+    return {
+      tx: bareTx,
+      route: obj.route,
+      debug: obj.debug,
+    };
+  }
+
+  throw ExitApiError.parse("response did not match any supported schema");
+}
+
+function summarizeErrorBody(body: string): string {
+  try {
+    const parsed = JSON.parse(body) as unknown;
+    const obj = asRecord(parsed, "error body");
+    const message =
+      asOptionalString(obj.error) ??
+      asOptionalString(obj.message) ??
+      asOptionalString(obj.reason);
+    if (message !== undefined) {
+      return message;
+    }
+  } catch {
+    // Ignore JSON parse errors and fall back to body snippet.
+  }
+
+  return body.slice(0, ERROR_BODY_SNIPPET_LEN);
+}
+
+type FetchLike = (
+  input: RequestInfo | URL,
+  init?: RequestInit,
+) => Promise<Response>;
+
+function asRecord(value: unknown, path: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw ExitApiError.parse(`${path} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function asOptionalString(value: unknown): string | undefined {
+  if (typeof value === "string") {
+    return value;
+  }
+  return undefined;
+}
+
+function stringifyError(error: unknown): string {
+  if (error instanceof Error) {
+    return `${error.name}: ${error.message}`;
+  }
+  return String(error);
+}
+
+export const DEFAULT_RETRY_POLICY: RetryPolicy = {
+  ...LOW_LATENCY_RETRY_POLICY,
+};

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./exitApi.js";
+export * from "./retry.js";
+export * from "./tx.js";
+export * from "./stream/index.js";
+export * as stream from "./stream/index.js";

package/src/retry.ts

@@ -0,0 +1,102 @@
+export interface RetryPolicy {
+  max_attempts: number;
+  initial_backoff_ms: number;
+  max_backoff_ms: number;
+  jitter_ms: number;
+}
+
+export const LOW_LATENCY_RETRY_POLICY: RetryPolicy = {
+  max_attempts: 2,
+  initial_backoff_ms: 25,
+  max_backoff_ms: 100,
+  jitter_ms: 25,
+};
+
+export function lowLatencyRetryPolicy(): RetryPolicy {
+  return { ...LOW_LATENCY_RETRY_POLICY };
+}
+
+export function delayForAttempt(policy: RetryPolicy, attempt: number): number {
+  let delay = Math.max(0, policy.initial_backoff_ms);
+
+  for (let i = 1; i < attempt; i += 1) {
+    delay = Math.min(delay * 2, Math.max(0, policy.max_backoff_ms));
+  }
+
+  return delay + jitterDurationMs(Math.max(0, policy.jitter_ms));
+}
+
+export async function retryAsync<T, E>(
+  policy: RetryPolicy,
+  op: (attempt: number) => Promise<T>,
+  shouldRetry: (error: E) => boolean,
+): Promise<T> {
+  const maxAttempts = Math.max(1, policy.max_attempts);
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      return await op(attempt);
+    } catch (error) {
+      const typedError = error as E;
+      if (attempt >= maxAttempts || !shouldRetry(typedError)) {
+        throw typedError;
+      }
+
+      const delay = delayForAttempt(policy, attempt);
+      if (delay > 0) {
+        await sleep(delay);
+      }
+    }
+  }
+
+  throw new Error("retryAsync reached an unreachable state");
+}
+
+export class TimeoutError extends Error {
+  readonly timeout_ms: number;
+
+  constructor(timeoutMs: number, message = "operation timed out") {
+    super(message);
+    this.name = "TimeoutError";
+    this.timeout_ms = timeoutMs;
+  }
+}
+
+export async function withTimeout<T>(
+  timeoutMs: number,
+  promise: Promise<T>,
+): Promise<T> {
+  if (timeoutMs <= 0) {
+    return promise;
+  }
+
+  return await new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new TimeoutError(timeoutMs));
+    }, timeoutMs);
+
+    promise
+      .then((value) => {
+        clearTimeout(timer);
+        resolve(value);
+      })
+      .catch((error) => {
+        clearTimeout(timer);
+        reject(error);
+      });
+  });
+}
+
+function jitterDurationMs(maxJitterMs: number): number {
+  if (maxJitterMs <= 0) {
+    return 0;
+  }
+
+  return Math.floor(Math.random() * (maxJitterMs + 1));
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}