@openpump/sdk 0.1.0

package/README.md

@@ -0,0 +1,248 @@
+# @openpump/sdk
+
+TypeScript SDK for the OpenPump REST API. Zero runtime dependencies (uses global `fetch`), dual-format (ESM + CJS), fully typed.
+
+## Installation
+
+```bash
+# Internal workspace usage
+pnpm add @openpump/sdk
+```
+
+## Quick Start
+
+```ts
+import { OpenPump } from '@openpump/sdk';
+
+const op = new OpenPump({ apiKey: 'op_sk_live_...' });
+
+const wallets = await op.wallets.list();
+console.log(wallets);
+```
+
+## Configuration
+
+```ts
+const op = new OpenPump({
+  apiKey: 'op_sk_live_...',           // Required
+  baseUrl: 'https://api.openpump.io', // Default
+  timeout: 30_000,                     // Default (ms)
+});
+```
+
+## Resources
+
+### Wallets
+
+```ts
+// List all wallets
+const wallets = await op.wallets.list();
+
+// Create a wallet
+const wallet = await op.wallets.create({ label: 'Trading Wallet' });
+
+// Get a single wallet
+const w = await op.wallets.get('wallet-id');
+
+// Get balances (SOL + tokens)
+const balance = await op.wallets.getBalance('wallet-id');
+
+// Get deposit instructions
+const deposit = await op.wallets.getDepositInstructions('wallet-id');
+
+// Force-refresh balance (bypass 30s cache)
+const fresh = await op.wallets.refreshBalance('wallet-id');
+
+// Transfer SOL or SPL tokens
+const tx = await op.wallets.transfer('wallet-id', {
+  toAddress: 'recipient-public-key',
+  amountLamports: '100000000',
+});
+
+// Get transaction history
+const history = await op.wallets.getTransactions('wallet-id', {
+  type: 'buy',
+  limit: 20,
+  offset: 0,
+});
+```
+
+### Tokens
+
+```ts
+// List your tokens
+const tokens = await op.tokens.list();
+
+// Create a new PumpFun token
+const token = await op.tokens.create({
+  name: 'My Token',
+  symbol: 'MTK',
+  description: 'A cool token',
+  imageBase64: 'base64-encoded-image...',
+  imageType: 'image/png',
+  twitter: '@mytoken',
+  website: 'https://mytoken.com',
+});
+
+// Get market info (mainnet only)
+const market = await op.tokens.getMarketInfo('mint-address');
+
+// Get bonding curve state
+const curve = await op.tokens.getCurveState('mint-address');
+console.log(curve.currentPriceSOL, curve.graduationPercent);
+```
+
+### Trading
+
+```ts
+// Get a price quote
+const quote = await op.trading.getQuote('mint-address', {
+  action: 'buy',
+  solAmount: '1000000000',
+});
+
+// Get SOL cost for a specific token amount
+const cost = await op.trading.getQuoteBuyCost('mint-address', {
+  tokenAmount: '1000000',
+});
+
+// Buy tokens
+const buy = await op.trading.buy('mint-address', {
+  walletId: 'wallet-id',
+  amountLamports: '500000000',
+  slippageBps: 500,
+  priorityLevel: 'fast',
+});
+
+// Sell tokens
+const sell = await op.trading.sell('mint-address', {
+  walletId: 'wallet-id',
+  tokenAmount: 'all',
+  slippageBps: 500,
+});
+
+// Multi-wallet bundle sell (Jito bundles)
+const bundleSell = await op.trading.bundleSell('mint-address', {
+  walletSells: [
+    { walletId: 'w1', tokenAmount: 'all' },
+    { walletId: 'w2', tokenAmount: '500000' },
+  ],
+  slippageBps: 500,
+});
+```
+
+### Bundles
+
+```ts
+// Launch token + multi-wallet buy in a single Jito bundle
+const { jobId } = await op.bundles.launch({
+  devWalletId: 'wallet-1',
+  buyWalletIds: ['wallet-2', 'wallet-3'],
+  name: 'My Token',
+  symbol: 'MTK',
+  imageBase64: '...',
+  imageType: 'image/png',
+  walletBuyAmounts: ['500000000', '500000000'],
+});
+
+// Poll for completion
+const result = await op.jobs.poll(jobId, {
+  intervalMs: 2000,
+  timeoutMs: 60_000,
+  onProgress: (s) => console.log(`${s.progress}%`),
+});
+```
+
+### Jobs
+
+```ts
+// Get job status
+const status = await op.jobs.get('job-id');
+
+// Poll until completion with progress callback
+const result = await op.jobs.poll('job-id', {
+  intervalMs: 2000,
+  timeoutMs: 60_000,
+  onProgress: (s) => console.log(`${s.progress}%`),
+});
+
+// Poll with abort support
+const controller = new AbortController();
+const result = await op.jobs.poll('job-id', {
+  signal: controller.signal,
+});
+// Call controller.abort() to cancel polling
+```
+
+### Creator Fees
+
+```ts
+// Check accumulated fees
+const fees = await op.creatorFees.getAccumulatedFees('creator-address');
+console.log(fees.accumulatedSOL);
+
+// Claim fees
+const claim = await op.creatorFees.claim('creator-address');
+console.log(claim.signature);
+```
+
+## Error Handling
+
+The SDK throws typed errors that map to HTTP status codes:
+
+```ts
+import {
+  OpenPumpError,
+  AuthenticationError,
+  ValidationError,
+  NotFoundError,
+  RateLimitError,
+} from '@openpump/sdk';
+
+try {
+  await op.wallets.list();
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    // 401 - Invalid or expired API key
+    console.error(error.code, error.message);
+  } else if (error instanceof ValidationError) {
+    // 422 - Invalid input
+    console.error(error.details);
+  } else if (error instanceof NotFoundError) {
+    // 404 - Resource not found
+  } else if (error instanceof RateLimitError) {
+    // 429 - Too many requests
+  } else if (error instanceof OpenPumpError) {
+    // Any other API error
+    console.error(error.status, error.code, error.message);
+  }
+}
+```
+
+All error classes extend `OpenPumpError` with these properties:
+
+| Property  | Type      | Description                |
+|-----------|-----------|----------------------------|
+| `code`    | `string`  | Machine-readable error code |
+| `message` | `string`  | Human-readable description  |
+| `status`  | `number`  | HTTP status code            |
+| `details` | `unknown` | Optional validation details |
+
+## Build
+
+```bash
+pnpm --filter @openpump/sdk run build
+```
+
+Outputs ESM (`.js`), CJS (`.cjs`), and TypeScript declarations (`.d.ts`, `.d.cts`) to `dist/`.
+
+## Test
+
+```bash
+pnpm --filter @openpump/sdk exec npx vitest run
+```
+
+## Requirements
+
+- Node.js 18+ (global `fetch` required)
+- TypeScript 5.3+

package/dist/index.cjs

@@ -0,0 +1,462 @@
+"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 index_exports = {};
+__export(index_exports, {
+  AuthenticationError: () => AuthenticationError,
+  InsufficientFundsError: () => InsufficientFundsError,
+  NotFoundError: () => NotFoundError,
+  OpenPump: () => OpenPump,
+  OpenPumpError: () => OpenPumpError,
+  RateLimitError: () => RateLimitError,
+  TransactionError: () => TransactionError,
+  ValidationError: () => ValidationError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var OpenPumpError = class extends Error {
+  constructor(code, message, status, details) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.details = details;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  name = "OpenPumpError";
+};
+var AuthenticationError = class extends OpenPumpError {
+  name = "AuthenticationError";
+  constructor(code, message, status, details) {
+    super(code, message, status, details);
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var RateLimitError = class extends OpenPumpError {
+  name = "RateLimitError";
+  constructor(code, message, status, details) {
+    super(code, message, status, details);
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var ValidationError = class extends OpenPumpError {
+  name = "ValidationError";
+  constructor(code, message, status, details) {
+    super(code, message, status, details);
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var NotFoundError = class extends OpenPumpError {
+  name = "NotFoundError";
+  constructor(code, message, status, details) {
+    super(code, message, status, details);
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var InsufficientFundsError = class extends OpenPumpError {
+  name = "InsufficientFundsError";
+  constructor(code, message, status, details) {
+    super(code, message, status, details);
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var TransactionError = class extends OpenPumpError {
+  name = "TransactionError";
+  constructor(code, message, status, details) {
+    super(code, message, status, details);
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+// src/http.ts
+var HttpClient = class {
+  _apiKey;
+  _baseUrl;
+  _timeout;
+  constructor(config) {
+    this._apiKey = config.apiKey;
+    this._baseUrl = config.baseUrl.replace(/\/+$/, "");
+    this._timeout = config.timeout;
+  }
+  async get(path, query) {
+    let url = `${this._baseUrl}${path}`;
+    if (query && Object.keys(query).length > 0) {
+      const params = new URLSearchParams(query);
+      url += `?${params.toString()}`;
+    }
+    const response = await fetch(url, {
+      headers: this._headers(),
+      signal: AbortSignal.timeout(this._timeout)
+    });
+    return this._handleResponse(response);
+  }
+  async post(path, body) {
+    const init = {
+      method: "POST",
+      headers: {
+        ...this._headers(),
+        "Content-Type": "application/json"
+      },
+      signal: AbortSignal.timeout(this._timeout)
+    };
+    if (body !== void 0) {
+      init.body = JSON.stringify(body);
+    }
+    const response = await fetch(`${this._baseUrl}${path}`, init);
+    return this._handleResponse(response);
+  }
+  async patch(path, body) {
+    const response = await fetch(`${this._baseUrl}${path}`, {
+      method: "PATCH",
+      headers: {
+        ...this._headers(),
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(this._timeout)
+    });
+    return this._handleResponse(response);
+  }
+  async delete(path) {
+    const response = await fetch(`${this._baseUrl}${path}`, {
+      method: "DELETE",
+      headers: this._headers(),
+      signal: AbortSignal.timeout(this._timeout)
+    });
+    return this._handleResponse(response);
+  }
+  _headers() {
+    return { Authorization: `Bearer ${this._apiKey}` };
+  }
+  async _handleResponse(response) {
+    if (!response.ok) {
+      await this._throwApiError(response);
+    }
+    const json = await response.json();
+    if (json !== null && typeof json === "object" && "data" in json) {
+      return json["data"];
+    }
+    return json;
+  }
+  async _throwApiError(response) {
+    let body = {};
+    try {
+      body = await response.json();
+    } catch {
+    }
+    const code = body.code ?? body.error ?? "UNKNOWN_ERROR";
+    const message = body.message ?? response.statusText;
+    const details = body.details;
+    switch (response.status) {
+      case 401: {
+        throw new AuthenticationError(code, message, 401, details);
+      }
+      case 404: {
+        throw new NotFoundError(code, message, 404, details);
+      }
+      case 422: {
+        throw new ValidationError(code, message, 422, details);
+      }
+      case 429: {
+        throw new RateLimitError(code, message, 429, details);
+      }
+      default: {
+        throw new OpenPumpError(code, message, response.status, details);
+      }
+    }
+  }
+};
+
+// src/resources/wallets.ts
+var Wallets = class {
+  constructor(_http) {
+    this._http = _http;
+  }
+  /** List all active wallets for the authenticated user. */
+  async list() {
+    return this._http.get("/api/wallets");
+  }
+  /** Create a new wallet with an optional label. */
+  async create(options) {
+    return this._http.post("/api/wallets", options ?? {});
+  }
+  /** Get a single wallet by ID. */
+  async get(walletId) {
+    return this._http.get(`/api/wallets/${walletId}`);
+  }
+  /** Get SOL + token balances for a wallet. */
+  async getBalance(walletId) {
+    return this._http.get(`/api/wallets/${walletId}/balance`);
+  }
+  /** Get deposit address and SOL minimums for a wallet. */
+  async getDepositInstructions(walletId) {
+    return this._http.get(`/api/wallets/${walletId}/deposit-instructions`);
+  }
+  /** Force a live RPC balance refresh, bypassing the 30s cache. */
+  async refreshBalance(walletId) {
+    return this._http.post(`/api/wallets/${walletId}/refresh-balance`);
+  }
+  /**
+   * Execute an on-chain SOL or SPL token transfer.
+   *
+   * @example
+   * ```ts
+   * const result = await op.wallets.transfer('wallet-id', {
+   *   toAddress: 'recipient-public-key',
+   *   amountLamports: '100000000',
+   * });
+   * console.log(result.signature);
+   * ```
+   */
+  async transfer(walletId, options) {
+    return this._http.post(`/api/wallets/${walletId}/transfer`, options);
+  }
+  /** Get paginated transfer history for a wallet. */
+  async getTransactions(walletId, options) {
+    const query = {};
+    if (options?.type !== void 0) query["type"] = options.type;
+    if (options?.limit !== void 0) query["limit"] = String(options.limit);
+    if (options?.offset !== void 0) query["offset"] = String(options.offset);
+    return this._http.get(`/api/wallets/${walletId}/transactions`, query);
+  }
+};
+
+// src/resources/tokens.ts
+var Tokens = class {
+  constructor(_http) {
+    this._http = _http;
+  }
+  /** List tokens created by the authenticated user. */
+  async list() {
+    return this._http.get("/api/tokens");
+  }
+  /**
+   * Create a new PumpFun token with IPFS metadata upload.
+   *
+   * @example
+   * ```ts
+   * const token = await op.tokens.create({
+   *   name: 'My Token',
+   *   symbol: 'MTK',
+   *   description: 'A cool token',
+   *   imageBase64: 'base64-encoded-image...',
+   *   imageType: 'image/png',
+   * });
+   * console.log(token.mint);
+   * ```
+   */
+  async create(options) {
+    return this._http.post("/api/tokens/create", options);
+  }
+  /** Get market info for a token (mainnet only, returns null on devnet). */
+  async getMarketInfo(mint) {
+    return this._http.get(`/api/tokens/${mint}/market-info`);
+  }
+  /** Get bonding curve state including price, market cap, and graduation progress. */
+  async getCurveState(mint) {
+    return this._http.get(`/api/tokens/${mint}/curve-state`);
+  }
+};
+
+// src/resources/trading.ts
+var Trading = class {
+  constructor(_http) {
+    this._http = _http;
+  }
+  /**
+   * Get a price quote for buying or selling a token.
+   *
+   * @example
+   * ```ts
+   * const quote = await op.trading.getQuote('So11...', {
+   *   action: 'buy',
+   *   solAmount: '1000000000',
+   * });
+   * console.log(quote.expectedTokens);
+   * ```
+   */
+  async getQuote(mint, options) {
+    const query = { action: options.action };
+    if (options.solAmount !== void 0) query["solAmount"] = options.solAmount;
+    if (options.tokenAmount !== void 0) query["tokenAmount"] = options.tokenAmount;
+    return this._http.get(`/api/tokens/${mint}/quote`, query);
+  }
+  /** Get the SOL cost to buy a specific number of tokens (inverse quote). */
+  async getQuoteBuyCost(mint, options) {
+    return this._http.get(`/api/tokens/${mint}/quote-buy-cost`, {
+      tokenAmount: options.tokenAmount
+    });
+  }
+  /** Execute a buy transaction for a token. */
+  async buy(mint, options) {
+    return this._http.post(`/api/tokens/${mint}/buy`, options);
+  }
+  /** Execute a sell transaction for a token. */
+  async sell(mint, options) {
+    return this._http.post(`/api/tokens/${mint}/sell`, options);
+  }
+  /** Multi-wallet sell packed into Jito bundles. */
+  async bundleSell(mint, options) {
+    return this._http.post(`/api/tokens/${mint}/bundle-sell`, options);
+  }
+};
+
+// src/resources/jobs.ts
+var Jobs = class {
+  constructor(_http) {
+    this._http = _http;
+  }
+  /** Get the current status of a job. */
+  async get(jobId) {
+    return this._http.get(`/api/jobs/${jobId}`);
+  }
+  /**
+   * Poll a job until it completes or the timeout is reached.
+   *
+   * @param jobId - The job ID to poll.
+   * @param options - Polling configuration.
+   * @returns The final job status (completed).
+   * @throws {Error} If the job fails or the timeout is reached.
+   *
+   * @example
+   * ```ts
+   * const launch = await op.bundles.launch({ ... });
+   * const result = await op.jobs.poll(launch.jobId, {
+   *   intervalMs: 2000,
+   *   timeoutMs: 60000,
+   *   onProgress: (s) => console.log(`Progress: ${s.progress}%`),
+   * });
+   * ```
+   */
+  async poll(jobId, options) {
+    const intervalMs = options?.intervalMs ?? 1e3;
+    const timeoutMs = options?.timeoutMs ?? 3e4;
+    const signal = options?.signal;
+    const onProgress = options?.onProgress;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      if (signal?.aborted) {
+        throw new Error("Job polling aborted");
+      }
+      const status = await this.get(jobId);
+      onProgress?.(status);
+      if (status.status === "completed") {
+        return status;
+      }
+      if (status.status === "failed") {
+        throw new Error(status.error ?? `Job ${jobId} failed`);
+      }
+      await new Promise((resolve, reject) => {
+        const timer = setTimeout(resolve, intervalMs);
+        signal?.addEventListener(
+          "abort",
+          () => {
+            clearTimeout(timer);
+            reject(new Error("Job polling aborted"));
+          },
+          { once: true }
+        );
+      });
+    }
+    throw new Error(`Job ${jobId} polling timed out after ${timeoutMs}ms`);
+  }
+};
+
+// src/resources/creator-fees.ts
+var CreatorFees = class {
+  constructor(_http) {
+    this._http = _http;
+  }
+  /** Get accumulated creator fees for a given creator address. */
+  async getAccumulatedFees(address) {
+    return this._http.get("/api/creator-fees", { address });
+  }
+  /** Claim accumulated creator fees for a wallet you own. */
+  async claim(creatorAddress) {
+    return this._http.post("/api/creator-fees/claim", { creatorAddress });
+  }
+};
+
+// src/resources/bundles.ts
+var Bundles = class {
+  constructor(_http) {
+    this._http = _http;
+  }
+  /**
+   * Launch a coordinated token creation + multi-wallet bundle buy.
+   * Returns a job ID for polling.
+   *
+   * @example
+   * ```ts
+   * const { jobId } = await op.bundles.launch({
+   *   devWalletId: 'wallet-1',
+   *   buyWalletIds: ['wallet-2', 'wallet-3'],
+   *   name: 'My Token',
+   *   symbol: 'MTK',
+   *   imageBase64: '...',
+   *   imageType: 'image/png',
+   *   walletBuyAmounts: ['500000000', '500000000'],
+   * });
+   * const result = await op.jobs.poll(jobId);
+   * ```
+   */
+  async launch(options) {
+    return this._http.post("/api/tokens/bundle-launch", options);
+  }
+};
+
+// src/client.ts
+var OpenPump = class {
+  wallets;
+  tokens;
+  trading;
+  jobs;
+  creatorFees;
+  bundles;
+  _http;
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new Error("apiKey is required");
+    }
+    this._http = new HttpClient({
+      apiKey: config.apiKey,
+      baseUrl: config.baseUrl ?? "https://api.openpump.io",
+      timeout: config.timeout ?? 3e4
+    });
+    this.wallets = new Wallets(this._http);
+    this.tokens = new Tokens(this._http);
+    this.trading = new Trading(this._http);
+    this.jobs = new Jobs(this._http);
+    this.creatorFees = new CreatorFees(this._http);
+    this.bundles = new Bundles(this._http);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuthenticationError,
+  InsufficientFundsError,
+  NotFoundError,
+  OpenPump,
+  OpenPumpError,
+  RateLimitError,
+  TransactionError,
+  ValidationError
+});
+//# sourceMappingURL=index.cjs.map