@vulcx/sdk 0.2.0

package/README.md

@@ -0,0 +1,148 @@
+# @vulcx/sdk
+
+TypeScript SDK for the Vulcx DEX aggregator API. Works in Node.js, browsers, and any JavaScript runtime with `fetch`.
+
+## Install
+
+```bash
+npm install @vulcx/sdk
+```
+
+Or via CDN:
+
+```html
+<script src="https://unpkg.com/@vulcx/sdk"></script>
+```
+
+## Quick Start
+
+```typescript
+import { VulcxSDK } from "@vulcx/sdk";
+
+const vulcx = new VulcxSDK({
+  apiKey: "vulcx_your_api_key_here",
+  chain: "solana", // or "fogo"
+});
+
+// Get a quote
+const quote = await vulcx.quote({
+  inputMint: "So11111111111111111111111111111111111111112",
+  outputMint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+  amount: "1000000000", // 1 SOL in lamports
+  swapMode: "ExactIn",
+  slippageBps: 50,
+});
+
+console.log(`Output: ${quote.amountOut}, Impact: ${quote.priceImpactPercent}`);
+```
+
+## API
+
+### `new VulcxSDK(config)`
+
+| Parameter   | Type     | Default                       | Description                |
+| ----------- | -------- | ----------------------------- | -------------------------- |
+| `apiKey`    | `string` | **required**                  | Your API key               |
+| `chain`     | `string` | `"solana"`                    | `"solana"` or `"fogo"`     |
+| `baseUrl`   | `string` | `"https://api.vulcx.xyz"` | API base URL               |
+| `timeout`   | `number` | `30000`                       | Request timeout in ms      |
+| `retries`   | `number` | `2`                           | Retry count for 429/5xx    |
+
+### `sdk.quote(params): Promise<QuoteResponse>`
+
+```typescript
+const quote = await vulcx.quote({
+  inputMint: "So111...",
+  outputMint: "EPjFW...",
+  amount: "1000000000",
+  swapMode: "ExactIn", // or "ExactOut"
+  slippageBps: 50, // optional, default 50
+});
+```
+
+### `sdk.swap(params): Promise<SwapResponse>`
+
+Returns a base64-encoded unsigned transaction.
+
+```typescript
+const swap = await vulcx.swap({
+  userWallet: "9WzDX...",
+  inputMint: "So111...",
+  outputMint: "EPjFW...",
+  amount: "1000000000",
+  swapMode: "ExactIn",
+  slippageBps: 50,
+  skipSimulation: false,
+});
+
+// Sign and send swap.transaction with your wallet adapter
+```
+
+### `sdk.instructions(params): Promise<InstructionsResponse>`
+
+Returns raw instructions for composability.
+
+```typescript
+const ixs = await vulcx.instructions({
+  userWallet: "9WzDX...",
+  inputMint: "So111...",
+  outputMint: "EPjFW...",
+  amount: "1000000000",
+  swapMode: "ExactIn",
+});
+
+// Build your own transaction with ixs.instructions
+```
+
+## Error Handling
+
+```typescript
+import { VulcxSDK, NoRouteError, RateLimitError, AuthError } from "@vulcx/sdk";
+
+try {
+  const quote = await vulcx.quote({ ... });
+} catch (err) {
+  if (err instanceof NoRouteError) {
+    console.log("No route found between tokens");
+  } else if (err instanceof RateLimitError) {
+    console.log("Rate limited, try again later");
+  } else if (err instanceof AuthError) {
+    console.log("Invalid API key");
+  }
+}
+```
+
+## Framework Examples
+
+### React
+
+```tsx
+import { VulcxSDK } from "@vulcx/sdk";
+import { useEffect, useState } from "react";
+
+const sdk = new VulcxSDK({ apiKey: "vulcx_..." });
+
+function SwapPage() {
+  const [quote, setQuote] = useState(null);
+
+  useEffect(() => {
+    sdk.quote({
+      inputMint: "So111...",
+      outputMint: "EPjFW...",
+      amount: "1000000000",
+      swapMode: "ExactIn",
+    }).then(setQuote);
+  }, []);
+
+  return <div>{quote && <p>Output: {quote.amountOut}</p>}</div>;
+}
+```
+
+### Node.js
+
+```javascript
+const { VulcxSDK } = require("@vulcx/sdk");
+
+const sdk = new VulcxSDK({ apiKey: process.env.VULCX_KEY });
+const quote = await sdk.quote({ ... });
+```

package/dist/client.d.ts

@@ -0,0 +1,13 @@
+import type { SDKConfig, QuoteRequest, QuoteResponse, SwapRequest, SwapResponse, InstructionsRequest, InstructionsResponse } from "./types";
+export declare class VulcxSDK {
+    private readonly apiKey;
+    private readonly chain;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly retries;
+    constructor(config: SDKConfig);
+    quote(params: QuoteRequest): Promise<QuoteResponse>;
+    swap(params: SwapRequest): Promise<SwapResponse>;
+    instructions(params: InstructionsRequest): Promise<InstructionsResponse>;
+    private request;
+}

package/dist/errors.d.ts

@@ -0,0 +1,20 @@
+export declare class VulcxError extends Error {
+    readonly statusCode: number;
+    readonly body?: unknown | undefined;
+    constructor(message: string, statusCode: number, body?: unknown | undefined);
+}
+export declare class RateLimitError extends VulcxError {
+    constructor(body?: unknown);
+}
+export declare class NoRouteError extends VulcxError {
+    constructor(body?: unknown);
+}
+export declare class BadRequestError extends VulcxError {
+    constructor(message: string, body?: unknown);
+}
+export declare class AuthError extends VulcxError {
+    constructor(body?: unknown);
+}
+export declare class ServerError extends VulcxError {
+    constructor(message: string, body?: unknown);
+}

package/dist/index.cjs.js

@@ -0,0 +1,155 @@
+'use strict';
+
+class VulcxError extends Error {
+    constructor(message, statusCode, body) {
+        super(message);
+        this.statusCode = statusCode;
+        this.body = body;
+        this.name = "VulcxError";
+    }
+}
+class RateLimitError extends VulcxError {
+    constructor(body) {
+        super("Rate limit exceeded", 429, body);
+        this.name = "RateLimitError";
+    }
+}
+class NoRouteError extends VulcxError {
+    constructor(body) {
+        super("No route found", 404, body);
+        this.name = "NoRouteError";
+    }
+}
+class BadRequestError extends VulcxError {
+    constructor(message, body) {
+        super(message, 400, body);
+        this.name = "BadRequestError";
+    }
+}
+class AuthError extends VulcxError {
+    constructor(body) {
+        super("Invalid or missing API key", 401, body);
+        this.name = "AuthError";
+    }
+}
+class ServerError extends VulcxError {
+    constructor(message, body) {
+        super(message, 500, body);
+        this.name = "ServerError";
+    }
+}
+
+const DEFAULT_BASE_URL = "https://api.vulcx.xyz";
+const DEFAULT_TIMEOUT = 30000;
+const DEFAULT_RETRIES = 2;
+class VulcxSDK {
+    constructor(config) {
+        if (!config.apiKey)
+            throw new Error("apiKey is required");
+        this.apiKey = config.apiKey;
+        this.chain = config.chain ?? "solana";
+        this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+        this.retries = config.retries ?? DEFAULT_RETRIES;
+    }
+    async quote(params) {
+        const qs = new URLSearchParams({
+            inputMint: params.inputMint,
+            outputMint: params.outputMint,
+            amount: params.amount,
+            swapMode: params.swapMode,
+        });
+        if (params.slippageBps !== undefined) {
+            qs.set("slippageBps", String(params.slippageBps));
+        }
+        return this.request("GET", `/api/v1/quote?${qs}`);
+    }
+    async swap(params) {
+        return this.request("POST", "/api/v1/swap", params);
+    }
+    async instructions(params) {
+        return this.request("POST", "/api/v1/instructions", params);
+    }
+    async request(method, path, body) {
+        const separator = path.includes("?") ? "&" : "?";
+        const url = `${this.baseUrl}${path}${separator}chain=${this.chain}`;
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: "application/json",
+        };
+        if (body) {
+            headers["Content-Type"] = "application/json";
+        }
+        let lastError;
+        for (let attempt = 0; attempt <= this.retries; attempt++) {
+            if (attempt > 0) {
+                await sleep(Math.min(1000 * 2 ** (attempt - 1), 8000));
+            }
+            try {
+                const controller = new AbortController();
+                const timer = setTimeout(() => controller.abort(), this.timeout);
+                const res = await fetch(url, {
+                    method,
+                    headers,
+                    body: body ? JSON.stringify(body) : undefined,
+                    signal: controller.signal,
+                });
+                clearTimeout(timer);
+                if (res.ok) {
+                    const parsed = (await res.json());
+                    // API responses wrap the payload in {success, data}; hand back the
+                    // payload the way the method signatures promise.
+                    if (parsed && typeof parsed === "object" && "success" in parsed) {
+                        if (!parsed.success) {
+                            throw new VulcxError(parsed.error ?? "request failed", res.status, parsed);
+                        }
+                        return parsed.data;
+                    }
+                    return parsed;
+                }
+                const errBody = await res.json().catch(() => ({}));
+                const errMsg = errBody?.error ?? res.statusText;
+                switch (res.status) {
+                    case 401:
+                    case 403:
+                        throw new AuthError(errBody);
+                    case 400:
+                        throw new BadRequestError(errMsg, errBody);
+                    case 404:
+                        throw new NoRouteError(errBody);
+                    case 429:
+                        lastError = new RateLimitError(errBody);
+                        continue;
+                    default:
+                        if (res.status >= 500) {
+                            lastError = new ServerError(errMsg, errBody);
+                            continue;
+                        }
+                        throw new VulcxError(errMsg, res.status, errBody);
+                }
+            }
+            catch (err) {
+                if (err instanceof AuthError ||
+                    err instanceof BadRequestError ||
+                    err instanceof NoRouteError ||
+                    err instanceof VulcxError) {
+                    throw err;
+                }
+                lastError = err;
+            }
+        }
+        throw lastError ?? new Error("request failed");
+    }
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+
+exports.AuthError = AuthError;
+exports.BadRequestError = BadRequestError;
+exports.NoRouteError = NoRouteError;
+exports.RateLimitError = RateLimitError;
+exports.ServerError = ServerError;
+exports.VulcxError = VulcxError;
+exports.VulcxSDK = VulcxSDK;
+//# sourceMappingURL=index.cjs.js.map

package/dist/index.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs.js","sources":["../src/errors.ts","../src/client.ts"],"sourcesContent":[null,null],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,140 @@
+type SwapMode = "ExactIn" | "ExactOut";
+type Chain = "solana" | "fogo";
+type PriceImpactSeverity = "none" | "low" | "moderate" | "high" | "extreme";
+interface SDKConfig {
+    apiKey: string;
+    chain?: Chain;
+    baseUrl?: string;
+    timeout?: number;
+    retries?: number;
+}
+interface QuoteRequest {
+    inputMint: string;
+    outputMint: string;
+    amount: string;
+    swapMode: SwapMode;
+    slippageBps?: number;
+}
+interface RouteInfo {
+    poolAddress: string;
+    poolType: string;
+    percent: number;
+    inputMint: string;
+    outputMint: string;
+}
+interface QuoteResponse {
+    inputMint: string;
+    outputMint: string;
+    amountIn: string;
+    amountOut: string;
+    priceImpactBps: number;
+    priceImpactPercent: string;
+    priceImpactSeverity: PriceImpactSeverity;
+    priceImpactWarning: string;
+    feeBps: number;
+    routes: RouteInfo[];
+    routePath: string[];
+    hopCount: number;
+    otherAmountThreshold: string;
+}
+interface SwapRequest {
+    userWallet: string;
+    inputMint: string;
+    outputMint: string;
+    amount: string;
+    swapMode: SwapMode;
+    slippageBps?: number;
+    skipSimulation?: boolean;
+}
+interface SimulationResult {
+    success: boolean;
+    computeUnitsConsumed: number;
+    computeUnitsTotal: number;
+    logs: string[];
+    error: string;
+    slippageExceeded: boolean;
+    insufficientFunds: boolean;
+    accountsNeeded: string[];
+}
+interface SwapResponse {
+    transaction: string;
+    lastValidBlockHeight: number;
+    amountIn: string;
+    amountOut: string;
+    minAmountOut?: string;
+    maxAmountIn?: string;
+    feeAmount: string;
+    simulation?: SimulationResult;
+    computeUnitsEstimate: number;
+    route: string[];
+    hopCount: number;
+    pools: string[];
+    isSplitRoute: boolean;
+    splitPercents?: number[];
+}
+interface InstructionsRequest {
+    userWallet: string;
+    inputMint: string;
+    outputMint: string;
+    amount: string;
+    swapMode: SwapMode;
+    slippageBps?: number;
+}
+interface RawAccountMeta {
+    publicKey: string;
+    isSigner: boolean;
+    isWritable: boolean;
+}
+interface RawInstruction {
+    programId: string;
+    accounts: RawAccountMeta[];
+    data: string;
+}
+interface InstructionsResponse {
+    instructions: RawInstruction[];
+    addressLookupTableAddresses: string[];
+    amountIn: string;
+    amountOut: string;
+    otherAmountThreshold: string;
+    feeAmount: string;
+    hopCount: number;
+    route: string[];
+    pools: string[];
+}
+
+declare class VulcxSDK {
+    private readonly apiKey;
+    private readonly chain;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly retries;
+    constructor(config: SDKConfig);
+    quote(params: QuoteRequest): Promise<QuoteResponse>;
+    swap(params: SwapRequest): Promise<SwapResponse>;
+    instructions(params: InstructionsRequest): Promise<InstructionsResponse>;
+    private request;
+}
+
+declare class VulcxError extends Error {
+    readonly statusCode: number;
+    readonly body?: unknown | undefined;
+    constructor(message: string, statusCode: number, body?: unknown | undefined);
+}
+declare class RateLimitError extends VulcxError {
+    constructor(body?: unknown);
+}
+declare class NoRouteError extends VulcxError {
+    constructor(body?: unknown);
+}
+declare class BadRequestError extends VulcxError {
+    constructor(message: string, body?: unknown);
+}
+declare class AuthError extends VulcxError {
+    constructor(body?: unknown);
+}
+declare class ServerError extends VulcxError {
+    constructor(message: string, body?: unknown);
+}
+
+export { AuthError, BadRequestError, NoRouteError, RateLimitError, ServerError, VulcxError, VulcxSDK };
+export type { Chain, InstructionsRequest, InstructionsResponse, PriceImpactSeverity, QuoteRequest, QuoteResponse, RawAccountMeta, RawInstruction, RouteInfo, SDKConfig, SimulationResult, SwapMode, SwapRequest, SwapResponse };

package/dist/index.esm.js

@@ -0,0 +1,147 @@
+class VulcxError extends Error {
+    constructor(message, statusCode, body) {
+        super(message);
+        this.statusCode = statusCode;
+        this.body = body;
+        this.name = "VulcxError";
+    }
+}
+class RateLimitError extends VulcxError {
+    constructor(body) {
+        super("Rate limit exceeded", 429, body);
+        this.name = "RateLimitError";
+    }
+}
+class NoRouteError extends VulcxError {
+    constructor(body) {
+        super("No route found", 404, body);
+        this.name = "NoRouteError";
+    }
+}
+class BadRequestError extends VulcxError {
+    constructor(message, body) {
+        super(message, 400, body);
+        this.name = "BadRequestError";
+    }
+}
+class AuthError extends VulcxError {
+    constructor(body) {
+        super("Invalid or missing API key", 401, body);
+        this.name = "AuthError";
+    }
+}
+class ServerError extends VulcxError {
+    constructor(message, body) {
+        super(message, 500, body);
+        this.name = "ServerError";
+    }
+}
+
+const DEFAULT_BASE_URL = "https://api.vulcx.xyz";
+const DEFAULT_TIMEOUT = 30000;
+const DEFAULT_RETRIES = 2;
+class VulcxSDK {
+    constructor(config) {
+        if (!config.apiKey)
+            throw new Error("apiKey is required");
+        this.apiKey = config.apiKey;
+        this.chain = config.chain ?? "solana";
+        this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+        this.retries = config.retries ?? DEFAULT_RETRIES;
+    }
+    async quote(params) {
+        const qs = new URLSearchParams({
+            inputMint: params.inputMint,
+            outputMint: params.outputMint,
+            amount: params.amount,
+            swapMode: params.swapMode,
+        });
+        if (params.slippageBps !== undefined) {
+            qs.set("slippageBps", String(params.slippageBps));
+        }
+        return this.request("GET", `/api/v1/quote?${qs}`);
+    }
+    async swap(params) {
+        return this.request("POST", "/api/v1/swap", params);
+    }
+    async instructions(params) {
+        return this.request("POST", "/api/v1/instructions", params);
+    }
+    async request(method, path, body) {
+        const separator = path.includes("?") ? "&" : "?";
+        const url = `${this.baseUrl}${path}${separator}chain=${this.chain}`;
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: "application/json",
+        };
+        if (body) {
+            headers["Content-Type"] = "application/json";
+        }
+        let lastError;
+        for (let attempt = 0; attempt <= this.retries; attempt++) {
+            if (attempt > 0) {
+                await sleep(Math.min(1000 * 2 ** (attempt - 1), 8000));
+            }
+            try {
+                const controller = new AbortController();
+                const timer = setTimeout(() => controller.abort(), this.timeout);
+                const res = await fetch(url, {
+                    method,
+                    headers,
+                    body: body ? JSON.stringify(body) : undefined,
+                    signal: controller.signal,
+                });
+                clearTimeout(timer);
+                if (res.ok) {
+                    const parsed = (await res.json());
+                    // API responses wrap the payload in {success, data}; hand back the
+                    // payload the way the method signatures promise.
+                    if (parsed && typeof parsed === "object" && "success" in parsed) {
+                        if (!parsed.success) {
+                            throw new VulcxError(parsed.error ?? "request failed", res.status, parsed);
+                        }
+                        return parsed.data;
+                    }
+                    return parsed;
+                }
+                const errBody = await res.json().catch(() => ({}));
+                const errMsg = errBody?.error ?? res.statusText;
+                switch (res.status) {
+                    case 401:
+                    case 403:
+                        throw new AuthError(errBody);
+                    case 400:
+                        throw new BadRequestError(errMsg, errBody);
+                    case 404:
+                        throw new NoRouteError(errBody);
+                    case 429:
+                        lastError = new RateLimitError(errBody);
+                        continue;
+                    default:
+                        if (res.status >= 500) {
+                            lastError = new ServerError(errMsg, errBody);
+                            continue;
+                        }
+                        throw new VulcxError(errMsg, res.status, errBody);
+                }
+            }
+            catch (err) {
+                if (err instanceof AuthError ||
+                    err instanceof BadRequestError ||
+                    err instanceof NoRouteError ||
+                    err instanceof VulcxError) {
+                    throw err;
+                }
+                lastError = err;
+            }
+        }
+        throw lastError ?? new Error("request failed");
+    }
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+
+export { AuthError, BadRequestError, NoRouteError, RateLimitError, ServerError, VulcxError, VulcxSDK };
+//# sourceMappingURL=index.esm.js.map

package/dist/index.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.esm.js","sources":["../src/errors.ts","../src/client.ts"],"sourcesContent":[null,null],"names":[],"mappings":"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"}

package/dist/index.umd.js

@@ -0,0 +1,161 @@
+(function (global, factory) {
+    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
+    typeof define === 'function' && define.amd ? define(['exports'], factory) :
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.VulcxSDK = {}));
+})(this, (function (exports) { 'use strict';
+
+    class VulcxError extends Error {
+        constructor(message, statusCode, body) {
+            super(message);
+            this.statusCode = statusCode;
+            this.body = body;
+            this.name = "VulcxError";
+        }
+    }
+    class RateLimitError extends VulcxError {
+        constructor(body) {
+            super("Rate limit exceeded", 429, body);
+            this.name = "RateLimitError";
+        }
+    }
+    class NoRouteError extends VulcxError {
+        constructor(body) {
+            super("No route found", 404, body);
+            this.name = "NoRouteError";
+        }
+    }
+    class BadRequestError extends VulcxError {
+        constructor(message, body) {
+            super(message, 400, body);
+            this.name = "BadRequestError";
+        }
+    }
+    class AuthError extends VulcxError {
+        constructor(body) {
+            super("Invalid or missing API key", 401, body);
+            this.name = "AuthError";
+        }
+    }
+    class ServerError extends VulcxError {
+        constructor(message, body) {
+            super(message, 500, body);
+            this.name = "ServerError";
+        }
+    }
+
+    const DEFAULT_BASE_URL = "https://api.vulcx.xyz";
+    const DEFAULT_TIMEOUT = 30000;
+    const DEFAULT_RETRIES = 2;
+    class VulcxSDK {
+        constructor(config) {
+            if (!config.apiKey)
+                throw new Error("apiKey is required");
+            this.apiKey = config.apiKey;
+            this.chain = config.chain ?? "solana";
+            this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+            this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+            this.retries = config.retries ?? DEFAULT_RETRIES;
+        }
+        async quote(params) {
+            const qs = new URLSearchParams({
+                inputMint: params.inputMint,
+                outputMint: params.outputMint,
+                amount: params.amount,
+                swapMode: params.swapMode,
+            });
+            if (params.slippageBps !== undefined) {
+                qs.set("slippageBps", String(params.slippageBps));
+            }
+            return this.request("GET", `/api/v1/quote?${qs}`);
+        }
+        async swap(params) {
+            return this.request("POST", "/api/v1/swap", params);
+        }
+        async instructions(params) {
+            return this.request("POST", "/api/v1/instructions", params);
+        }
+        async request(method, path, body) {
+            const separator = path.includes("?") ? "&" : "?";
+            const url = `${this.baseUrl}${path}${separator}chain=${this.chain}`;
+            const headers = {
+                Authorization: `Bearer ${this.apiKey}`,
+                Accept: "application/json",
+            };
+            if (body) {
+                headers["Content-Type"] = "application/json";
+            }
+            let lastError;
+            for (let attempt = 0; attempt <= this.retries; attempt++) {
+                if (attempt > 0) {
+                    await sleep(Math.min(1000 * 2 ** (attempt - 1), 8000));
+                }
+                try {
+                    const controller = new AbortController();
+                    const timer = setTimeout(() => controller.abort(), this.timeout);
+                    const res = await fetch(url, {
+                        method,
+                        headers,
+                        body: body ? JSON.stringify(body) : undefined,
+                        signal: controller.signal,
+                    });
+                    clearTimeout(timer);
+                    if (res.ok) {
+                        const parsed = (await res.json());
+                        // API responses wrap the payload in {success, data}; hand back the
+                        // payload the way the method signatures promise.
+                        if (parsed && typeof parsed === "object" && "success" in parsed) {
+                            if (!parsed.success) {
+                                throw new VulcxError(parsed.error ?? "request failed", res.status, parsed);
+                            }
+                            return parsed.data;
+                        }
+                        return parsed;
+                    }
+                    const errBody = await res.json().catch(() => ({}));
+                    const errMsg = errBody?.error ?? res.statusText;
+                    switch (res.status) {
+                        case 401:
+                        case 403:
+                            throw new AuthError(errBody);
+                        case 400:
+                            throw new BadRequestError(errMsg, errBody);
+                        case 404:
+                            throw new NoRouteError(errBody);
+                        case 429:
+                            lastError = new RateLimitError(errBody);
+                            continue;
+                        default:
+                            if (res.status >= 500) {
+                                lastError = new ServerError(errMsg, errBody);
+                                continue;
+                            }
+                            throw new VulcxError(errMsg, res.status, errBody);
+                    }
+                }
+                catch (err) {
+                    if (err instanceof AuthError ||
+                        err instanceof BadRequestError ||
+                        err instanceof NoRouteError ||
+                        err instanceof VulcxError) {
+                        throw err;
+                    }
+                    lastError = err;
+                }
+            }
+            throw lastError ?? new Error("request failed");
+        }
+    }
+    function sleep(ms) {
+        return new Promise((r) => setTimeout(r, ms));
+    }
+
+    exports.AuthError = AuthError;
+    exports.BadRequestError = BadRequestError;
+    exports.NoRouteError = NoRouteError;
+    exports.RateLimitError = RateLimitError;
+    exports.ServerError = ServerError;
+    exports.VulcxError = VulcxError;
+    exports.VulcxSDK = VulcxSDK;
+
+}));
+//# sourceMappingURL=index.umd.js.map

package/dist/index.umd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.umd.js","sources":["../src/errors.ts","../src/client.ts"],"sourcesContent":[null,null],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,106 @@
+export type SwapMode = "ExactIn" | "ExactOut";
+export type Chain = "solana" | "fogo";
+export type PriceImpactSeverity = "none" | "low" | "moderate" | "high" | "extreme";
+export interface SDKConfig {
+    apiKey: string;
+    chain?: Chain;
+    baseUrl?: string;
+    timeout?: number;
+    retries?: number;
+}
+export interface QuoteRequest {
+    inputMint: string;
+    outputMint: string;
+    amount: string;
+    swapMode: SwapMode;
+    slippageBps?: number;
+}
+export interface RouteInfo {
+    poolAddress: string;
+    poolType: string;
+    percent: number;
+    inputMint: string;
+    outputMint: string;
+}
+export interface QuoteResponse {
+    inputMint: string;
+    outputMint: string;
+    amountIn: string;
+    amountOut: string;
+    priceImpactBps: number;
+    priceImpactPercent: string;
+    priceImpactSeverity: PriceImpactSeverity;
+    priceImpactWarning: string;
+    feeBps: number;
+    routes: RouteInfo[];
+    routePath: string[];
+    hopCount: number;
+    otherAmountThreshold: string;
+}
+export interface SwapRequest {
+    userWallet: string;
+    inputMint: string;
+    outputMint: string;
+    amount: string;
+    swapMode: SwapMode;
+    slippageBps?: number;
+    skipSimulation?: boolean;
+}
+export interface SimulationResult {
+    success: boolean;
+    computeUnitsConsumed: number;
+    computeUnitsTotal: number;
+    logs: string[];
+    error: string;
+    slippageExceeded: boolean;
+    insufficientFunds: boolean;
+    accountsNeeded: string[];
+}
+export interface SwapResponse {
+    transaction: string;
+    lastValidBlockHeight: number;
+    amountIn: string;
+    amountOut: string;
+    minAmountOut?: string;
+    maxAmountIn?: string;
+    feeAmount: string;
+    simulation?: SimulationResult;
+    computeUnitsEstimate: number;
+    route: string[];
+    hopCount: number;
+    pools: string[];
+    isSplitRoute: boolean;
+    splitPercents?: number[];
+}
+export interface InstructionsRequest {
+    userWallet: string;
+    inputMint: string;
+    outputMint: string;
+    amount: string;
+    swapMode: SwapMode;
+    slippageBps?: number;
+}
+export interface RawAccountMeta {
+    publicKey: string;
+    isSigner: boolean;
+    isWritable: boolean;
+}
+export interface RawInstruction {
+    programId: string;
+    accounts: RawAccountMeta[];
+    data: string;
+}
+export interface InstructionsResponse {
+    instructions: RawInstruction[];
+    addressLookupTableAddresses: string[];
+    amountIn: string;
+    amountOut: string;
+    otherAmountThreshold: string;
+    feeAmount: string;
+    hopCount: number;
+    route: string[];
+    pools: string[];
+}
+export interface APIErrorBody {
+    error: string;
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@vulcx/sdk",
+  "version": "0.2.0",
+  "description": "TypeScript SDK for the Vulcx DEX aggregator API",
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.esm.js",
+  "browser": "dist/index.umd.js",
+  "unpkg": "dist/index.umd.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.esm.js",
+      "require": "./dist/index.cjs.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rollup -c",
+    "dev": "rollup -c -w",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@rollup/plugin-typescript": "^12.1.2",
+    "rollup": "^4.34.8",
+    "rollup-plugin-dts": "^6.1.1",
+    "tslib": "^2.8.1",
+    "typescript": "^5.7.3"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/argyros-ag/sdk"
+  },
+  "keywords": [
+    "solana",
+    "dex",
+    "aggregator",
+    "swap",
+    "fogo",
+    "vulcx"
+  ]
+}