@fereai/sdk 0.1.0-dev.4

package/README.md

@@ -0,0 +1,19 @@
+# @fere/sdk
+
+TypeScript SDK for the FereAI Gateway API.
+
+## Install
+
+```bash
+npm install @fere/sdk
+```
+
+## Usage
+
+```typescript
+import { FereClient } from "@fere/sdk";
+
+const client = new FereClient({ apiKey: "your-api-key", baseUrl: "https://api.fere.ai" });
+```
+
+See the [FereAI docs](https://api.fere.ai) for full API reference.

package/dist/auth.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Auth module — Ed25519 keypair management and token lifecycle.
+ *
+ * Uses @noble/ed25519 for Ed25519 signing.
+ */
+export declare class AuthManager {
+    private readonly agentName;
+    private readonly baseUrl;
+    private readonly keyPath;
+    private secretKey;
+    private publicKey;
+    private agentId;
+    private token;
+    private tokenExpiresAt;
+    constructor(agentName: string, baseUrl?: string, keyPath?: string);
+    private loadOrCreateKeypair;
+    private getPublicKey;
+    getPublicKeyB64(): Promise<string>;
+    private sign;
+    private saveKeypair;
+    private readCreds;
+    ensureRegistered(): Promise<string>;
+    ensureToken(): Promise<string>;
+    authHeaders(): Record<string, string>;
+    /** Clear cached token to force refresh on next call. */
+    clearToken(): void;
+}

package/dist/auth.js

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * Auth module — Ed25519 keypair management and token lifecycle.
+ *
+ * Uses @noble/ed25519 for Ed25519 signing.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthManager = void 0;
+const ed = __importStar(require("@noble/ed25519"));
+const fs_1 = require("fs");
+const path_1 = require("path");
+const os_1 = require("os");
+class AuthManager {
+    agentName;
+    baseUrl;
+    keyPath;
+    secretKey = null;
+    publicKey = null;
+    agentId = null;
+    token = null;
+    tokenExpiresAt = 0;
+    constructor(agentName, baseUrl = "https://api.fereai.xyz", keyPath) {
+        this.agentName = agentName;
+        this.baseUrl = baseUrl.replace(/\/$/, "");
+        this.keyPath = keyPath ?? (0, path_1.join)((0, os_1.homedir)(), ".fere", "keys.json");
+    }
+    // ----------------------------------------------------------
+    // Keypair management
+    // ----------------------------------------------------------
+    loadOrCreateKeypair() {
+        if (this.secretKey)
+            return;
+        const creds = this.readCreds();
+        const entry = creds[this.baseUrl]?.[this.agentName];
+        if (entry?.secret_key) {
+            this.secretKey = Buffer.from(entry.secret_key, "base64");
+            this.publicKey = Buffer.from(entry.public_key, "base64");
+            this.agentId = entry.agent_id ?? null;
+        }
+        else {
+            this.secretKey = ed.utils.randomPrivateKey();
+            this.publicKey = null; // Will be derived on first use
+            this.saveKeypair();
+        }
+    }
+    async getPublicKey() {
+        this.loadOrCreateKeypair();
+        if (!this.publicKey) {
+            this.publicKey = await ed.getPublicKeyAsync(this.secretKey);
+            this.saveKeypair();
+        }
+        return this.publicKey;
+    }
+    async getPublicKeyB64() {
+        const pk = await this.getPublicKey();
+        return Buffer.from(pk).toString("base64");
+    }
+    async sign(message) {
+        this.loadOrCreateKeypair();
+        const pk = await this.getPublicKey();
+        const sig = await ed.signAsync(new TextEncoder().encode(message), this.secretKey);
+        return Buffer.from(sig).toString("base64");
+    }
+    saveKeypair() {
+        const creds = this.readCreds();
+        if (!creds[this.baseUrl])
+            creds[this.baseUrl] = {};
+        creds[this.baseUrl][this.agentName] = {
+            secret_key: Buffer.from(this.secretKey).toString("base64"),
+            public_key: this.publicKey
+                ? Buffer.from(this.publicKey).toString("base64")
+                : "",
+            agent_id: this.agentId ?? undefined,
+        };
+        const dir = (0, path_1.dirname)(this.keyPath);
+        if (!(0, fs_1.existsSync)(dir))
+            (0, fs_1.mkdirSync)(dir, { recursive: true });
+        (0, fs_1.writeFileSync)(this.keyPath, JSON.stringify(creds, null, 2));
+    }
+    readCreds() {
+        if ((0, fs_1.existsSync)(this.keyPath)) {
+            return JSON.parse((0, fs_1.readFileSync)(this.keyPath, "utf-8"));
+        }
+        return {};
+    }
+    // ----------------------------------------------------------
+    // Registration + token flow
+    // ----------------------------------------------------------
+    async ensureRegistered() {
+        this.loadOrCreateKeypair();
+        if (this.agentId)
+            return this.agentId;
+        const pubKey = await this.getPublicKeyB64();
+        // Step 1: Register
+        const regResp = await fetch(`${this.baseUrl}/v1/auth/register`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                agent_name: this.agentName,
+                public_key: pubKey,
+            }),
+        });
+        if (!regResp.ok)
+            throw new Error(`Registration failed: ${regResp.status}`);
+        const reg = (await regResp.json());
+        // Step 2: Sign challenge and verify
+        const sig = await this.sign(reg.challenge);
+        const verifyResp = await fetch(`${this.baseUrl}/v1/auth/verify`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                registration_id: reg.registration_id,
+                challenge: reg.challenge,
+                signature: sig,
+            }),
+        });
+        if (!verifyResp.ok)
+            throw new Error(`Verification failed: ${verifyResp.status}`);
+        const verify = (await verifyResp.json());
+        this.agentId = verify.agent_id;
+        this.saveKeypair();
+        return this.agentId;
+    }
+    async ensureToken() {
+        if (this.token && this.tokenExpiresAt > Date.now() / 1000 + 30) {
+            return this.token;
+        }
+        const agentId = await this.ensureRegistered();
+        const ts = Math.floor(Date.now() / 1000).toString();
+        const sig = await this.sign(ts);
+        const resp = await fetch(`${this.baseUrl}/v1/auth/token`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                agent_id: agentId,
+                timestamp: ts,
+                signature: sig,
+            }),
+        });
+        if (resp.status === 401) {
+            // Re-register
+            this.agentId = null;
+            const newAgentId = await this.ensureRegistered();
+            const newTs = Math.floor(Date.now() / 1000).toString();
+            const newSig = await this.sign(newTs);
+            const retryResp = await fetch(`${this.baseUrl}/v1/auth/token`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    agent_id: newAgentId,
+                    timestamp: newTs,
+                    signature: newSig,
+                }),
+            });
+            if (!retryResp.ok)
+                throw new Error(`Token request failed: ${retryResp.status}`);
+            const data = (await retryResp.json());
+            this.token = data.token;
+            this.tokenExpiresAt = Date.now() / 1000 + data.expires_in;
+            return this.token;
+        }
+        if (!resp.ok)
+            throw new Error(`Token request failed: ${resp.status}`);
+        const data = (await resp.json());
+        this.token = data.token;
+        this.tokenExpiresAt = Date.now() / 1000 + data.expires_in;
+        return this.token;
+    }
+    authHeaders() {
+        if (!this.token)
+            throw new Error("Call ensureToken() first");
+        return { Authorization: `Bearer ${this.token}` };
+    }
+    /** Clear cached token to force refresh on next call. */
+    clearToken() {
+        this.token = null;
+        this.tokenExpiresAt = 0;
+    }
+}
+exports.AuthManager = AuthManager;

package/dist/client.d.ts

@@ -0,0 +1,52 @@
+/**
+ * High-level SDK — developer-friendly wrapper that hides async tasks.
+ *
+ * Usage:
+ * ```ts
+ * const client = await FereClient.create({ agentName: "my-bot" });
+ * const result = await client.swap({
+ *   chain_id_in: 8453,
+ *   chain_id_out: 8453,
+ *   token_in: "0xEeee...EEeE",
+ *   token_out: "0x8335...2913",
+ *   amount: "1000000000000000000",
+ * });
+ * ```
+ */
+import type { ChatEvent, SwapRequest, LimitOrderRequest, HooksRequest, DepositRequest, WithdrawRequest } from "./types.js";
+export declare class FereClient {
+    private readonly api;
+    private constructor();
+    static create(opts: {
+        agentName: string;
+        baseUrl?: string;
+        keyPath?: string;
+    }): Promise<FereClient>;
+    chat(query: string, opts?: {
+        threadId?: string;
+        agent?: string;
+    }): Promise<Record<string, unknown>>;
+    chatStream(query: string, opts?: {
+        threadId?: string;
+        agent?: string;
+    }): AsyncGenerator<ChatEvent>;
+    swap(request: SwapRequest, timeout?: number): Promise<Record<string, unknown>>;
+    limitOrder(request: LimitOrderRequest, timeout?: number): Promise<Record<string, unknown>>;
+    setHooks(request: HooksRequest): Promise<unknown>;
+    deposit(request: DepositRequest, timeout?: number): Promise<Record<string, unknown>>;
+    withdraw(request: WithdrawRequest, timeout?: number): Promise<Record<string, unknown>>;
+    getWallets: () => Promise<unknown>;
+    getHoldings: () => Promise<unknown>;
+    getCredits: () => Promise<import("./types.js").CreditsInfo>;
+    getUser: () => Promise<unknown>;
+    getChains: () => Promise<unknown>;
+    getEarnInfo: () => Promise<unknown>;
+    getPositions: () => Promise<unknown>;
+    getThreads: (skip?: number, limit?: number) => Promise<unknown[]>;
+    getLimitOrders: (status?: string) => Promise<unknown[]>;
+    getNotifications: (opts?: {
+        limit?: number;
+        offset?: number;
+        type?: string;
+    }) => Promise<unknown>;
+}

package/dist/client.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * High-level SDK — developer-friendly wrapper that hides async tasks.
+ *
+ * Usage:
+ * ```ts
+ * const client = await FereClient.create({ agentName: "my-bot" });
+ * const result = await client.swap({
+ *   chain_id_in: 8453,
+ *   chain_id_out: 8453,
+ *   token_in: "0xEeee...EEeE",
+ *   token_out: "0x8335...2913",
+ *   amount: "1000000000000000000",
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FereClient = void 0;
+const low_level_js_1 = require("./low-level.js");
+const DEFAULT_TIMEOUT = 120;
+class FereClient {
+    api;
+    constructor(api) {
+        this.api = api;
+    }
+    static async create(opts) {
+        const api = new low_level_js_1.FereAPI(opts);
+        await api.authenticate();
+        return new FereClient(api);
+    }
+    // ----------------------------------------------------------
+    // Chat
+    // ----------------------------------------------------------
+    async chat(query, opts) {
+        const result = {};
+        const toolResponses = [];
+        for await (const event of this.api.chat(query, opts)) {
+            switch (event.event) {
+                case "meta":
+                    result.chat_id = event.data.chat_id;
+                    break;
+                case "tool_response":
+                    toolResponses.push(event.data);
+                    break;
+                case "answer":
+                    result.answer = event.data.text ?? "";
+                    break;
+                case "done":
+                    result.done = event.data;
+                    break;
+                case "error":
+                    throw new Error(String(event.data.message ?? JSON.stringify(event.data)));
+            }
+        }
+        if (toolResponses.length > 0) {
+            result.tool_responses = toolResponses;
+        }
+        return result;
+    }
+    async *chatStream(query, opts) {
+        yield* this.api.chat(query, opts);
+    }
+    // ----------------------------------------------------------
+    // Trading (blocks until complete)
+    // ----------------------------------------------------------
+    async swap(request, timeout = DEFAULT_TIMEOUT) {
+        return this.api.createSwap(request, {
+            wait: true,
+            timeout,
+        });
+    }
+    async limitOrder(request, timeout = DEFAULT_TIMEOUT) {
+        return this.api.createLimitOrder(request, {
+            wait: true,
+            timeout,
+        });
+    }
+    async setHooks(request) {
+        return this.api.setHooks(request);
+    }
+    // ----------------------------------------------------------
+    // Earn (blocks until complete)
+    // ----------------------------------------------------------
+    async deposit(request, timeout = DEFAULT_TIMEOUT) {
+        return this.api.deposit(request, {
+            wait: true,
+            timeout,
+        });
+    }
+    async withdraw(request, timeout = DEFAULT_TIMEOUT) {
+        return this.api.withdraw(request, {
+            wait: true,
+            timeout,
+        });
+    }
+    // ----------------------------------------------------------
+    // Read-only (pass-through)
+    // ----------------------------------------------------------
+    getWallets = () => this.api.getWallets();
+    getHoldings = () => this.api.getHoldings();
+    getCredits = () => this.api.getCredits();
+    getUser = () => this.api.getUser();
+    getChains = () => this.api.getChains();
+    getEarnInfo = () => this.api.getEarnInfo();
+    getPositions = () => this.api.getPositions();
+    getThreads = (skip, limit) => this.api.getThreads(skip, limit);
+    getLimitOrders = (status) => this.api.getLimitOrders(status);
+    getNotifications = (opts) => this.api.getNotifications(opts);
+}
+exports.FereClient = FereClient;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { FereAPI } from "./low-level.js";
+export { FereClient } from "./client.js";
+export { AuthManager } from "./auth.js";
+export type { ChatEvent, TaskResponse, TaskStatusResponse, SwapRequest, LimitOrderRequest, HooksRequest, DepositRequest, WithdrawRequest, CreditsInfo, WalletInfo, } from "./types.js";
+export { TaskTimeoutError } from "./types.js";

package/dist/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskTimeoutError = exports.AuthManager = exports.FereClient = exports.FereAPI = void 0;
+var low_level_js_1 = require("./low-level.js");
+Object.defineProperty(exports, "FereAPI", { enumerable: true, get: function () { return low_level_js_1.FereAPI; } });
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "FereClient", { enumerable: true, get: function () { return client_js_1.FereClient; } });
+var auth_js_1 = require("./auth.js");
+Object.defineProperty(exports, "AuthManager", { enumerable: true, get: function () { return auth_js_1.AuthManager; } });
+var types_js_1 = require("./types.js");
+Object.defineProperty(exports, "TaskTimeoutError", { enumerable: true, get: function () { return types_js_1.TaskTimeoutError; } });

package/dist/low-level.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Low-level SDK — 1:1 typed wrappers around every gateway endpoint.
+ */
+import type { ChatEvent, CreditsInfo, DepositRequest, HooksRequest, LimitOrderRequest, SwapRequest, TaskResponse, TaskStatusResponse, WithdrawRequest } from "./types.js";
+export declare class FereAPI {
+    private readonly baseUrl;
+    private readonly auth;
+    constructor(opts: {
+        agentName: string;
+        baseUrl?: string;
+        keyPath?: string;
+    });
+    authenticate(): Promise<string>;
+    private headers;
+    private authedGet;
+    private authedPost;
+    private authedDelete;
+    chat(query: string, opts?: {
+        threadId?: string;
+        agent?: string;
+    }): AsyncGenerator<ChatEvent>;
+    getThreads(skip?: number, limit?: number): Promise<unknown[]>;
+    getThread(threadId: string): Promise<unknown[]>;
+    createSwap(request: SwapRequest, opts?: {
+        wait?: boolean;
+        timeout?: number;
+    }): Promise<TaskResponse | Record<string, unknown>>;
+    createLimitOrder(request: LimitOrderRequest, opts?: {
+        wait?: boolean;
+        timeout?: number;
+    }): Promise<TaskResponse | Record<string, unknown>>;
+    getLimitOrders(status?: string): Promise<unknown[]>;
+    getLimitOrder(orderId: string): Promise<unknown>;
+    cancelLimitOrder(orderId: string): Promise<unknown>;
+    setHooks(request: HooksRequest): Promise<unknown>;
+    getWallets(): Promise<unknown>;
+    getHoldings(): Promise<unknown>;
+    getEarnInfo(): Promise<unknown>;
+    deposit(request: DepositRequest, opts?: {
+        wait?: boolean;
+        timeout?: number;
+    }): Promise<TaskResponse | Record<string, unknown>>;
+    withdraw(request: WithdrawRequest, opts?: {
+        wait?: boolean;
+        timeout?: number;
+    }): Promise<TaskResponse | Record<string, unknown>>;
+    getPositions(): Promise<unknown>;
+    getTask(taskId: string): Promise<TaskStatusResponse>;
+    getNotifications(opts?: {
+        limit?: number;
+        offset?: number;
+        type?: string;
+    }): Promise<unknown>;
+    notificationStream(): AsyncGenerator<ChatEvent>;
+    getCredits(): Promise<CreditsInfo>;
+    getUser(): Promise<unknown>;
+    getChains(): Promise<unknown>;
+}

package/dist/low-level.js

@@ -0,0 +1,268 @@
+"use strict";
+/**
+ * Low-level SDK — 1:1 typed wrappers around every gateway endpoint.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FereAPI = void 0;
+const auth_js_1 = require("./auth.js");
+const DEFAULT_BASE_URL = "https://api.fereai.xyz";
+class FereAPI {
+    baseUrl;
+    auth;
+    constructor(opts) {
+        this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+        this.auth = new auth_js_1.AuthManager(opts.agentName, this.baseUrl, opts.keyPath);
+    }
+    async authenticate() {
+        return this.auth.ensureToken();
+    }
+    async headers() {
+        await this.auth.ensureToken();
+        return {
+            ...this.auth.authHeaders(),
+            "Content-Type": "application/json",
+        };
+    }
+    async authedGet(path, params) {
+        const h = await this.headers();
+        const url = new URL(`${this.baseUrl}${path}`);
+        if (params)
+            Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
+        let resp = await fetch(url.toString(), { headers: h });
+        if (resp.status === 401) {
+            this.auth.clearToken();
+            const h2 = await this.headers();
+            resp = await fetch(url.toString(), { headers: h2 });
+        }
+        if (!resp.ok)
+            throw new Error(`GET ${path} failed: ${resp.status}`);
+        return resp.json();
+    }
+    async authedPost(path, body, params) {
+        const h = await this.headers();
+        const url = new URL(`${this.baseUrl}${path}`);
+        if (params)
+            Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
+        let resp = await fetch(url.toString(), {
+            method: "POST",
+            headers: h,
+            body: JSON.stringify(body),
+        });
+        if (resp.status === 401) {
+            this.auth.clearToken();
+            const h2 = await this.headers();
+            resp = await fetch(url.toString(), {
+                method: "POST",
+                headers: h2,
+                body: JSON.stringify(body),
+            });
+        }
+        if (!resp.ok)
+            throw new Error(`POST ${path} failed: ${resp.status}`);
+        return resp.json();
+    }
+    async authedDelete(path) {
+        const h = await this.headers();
+        let resp = await fetch(`${this.baseUrl}${path}`, {
+            method: "DELETE",
+            headers: h,
+        });
+        if (resp.status === 401) {
+            this.auth.clearToken();
+            const h2 = await this.headers();
+            resp = await fetch(`${this.baseUrl}${path}`, {
+                method: "DELETE",
+                headers: h2,
+            });
+        }
+        if (!resp.ok)
+            throw new Error(`DELETE ${path} failed: ${resp.status}`);
+        return resp.json();
+    }
+    // ----------------------------------------------------------
+    // Chat
+    // ----------------------------------------------------------
+    async *chat(query, opts) {
+        const h = await this.headers();
+        const body = {
+            query,
+            stream: true,
+            agent: opts?.agent ?? "ProAgent",
+            ...(opts?.threadId ? { thread_id: opts.threadId } : {}),
+        };
+        const resp = await fetch(`${this.baseUrl}/v1/chat`, {
+            method: "POST",
+            headers: h,
+            body: JSON.stringify(body),
+        });
+        if (!resp.ok)
+            throw new Error(`Chat failed: ${resp.status}`);
+        if (!resp.body)
+            return;
+        const reader = resp.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        let eventType = "";
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split("\n");
+            buffer = lines.pop() ?? "";
+            for (const line of lines) {
+                if (line.startsWith("event:")) {
+                    eventType = line.slice(6).trim();
+                }
+                else if (line.startsWith("data:")) {
+                    const data = JSON.parse(line.slice(5).trim());
+                    yield { event: eventType, data };
+                }
+            }
+        }
+    }
+    async getThreads(skip = 0, limit = 10) {
+        return this.authedGet("/v1/chat/threads", {
+            skip: String(skip),
+            limit: String(limit),
+        });
+    }
+    async getThread(threadId) {
+        return this.authedGet(`/v1/chat/threads/${threadId}`);
+    }
+    // ----------------------------------------------------------
+    // Trading
+    // ----------------------------------------------------------
+    async createSwap(request, opts) {
+        const params = {};
+        if (opts?.wait) {
+            params.wait = "true";
+            params.timeout = String(opts.timeout ?? 60);
+        }
+        return this.authedPost("/v1/swap", request, params);
+    }
+    async createLimitOrder(request, opts) {
+        const params = {};
+        if (opts?.wait) {
+            params.wait = "true";
+            params.timeout = String(opts.timeout ?? 60);
+        }
+        return this.authedPost("/v1/limit-orders", request, params);
+    }
+    async getLimitOrders(status) {
+        const params = {};
+        if (status)
+            params.status = status;
+        return this.authedGet("/v1/limit-orders", params);
+    }
+    async getLimitOrder(orderId) {
+        return this.authedGet(`/v1/limit-orders/${orderId}`);
+    }
+    async cancelLimitOrder(orderId) {
+        return this.authedDelete(`/v1/limit-orders/${orderId}`);
+    }
+    async setHooks(request) {
+        return this.authedPost("/v1/hooks", request);
+    }
+    // ----------------------------------------------------------
+    // Wallets
+    // ----------------------------------------------------------
+    async getWallets() {
+        return this.authedGet("/v1/wallets");
+    }
+    async getHoldings() {
+        return this.authedGet("/v1/holdings");
+    }
+    // ----------------------------------------------------------
+    // Earn
+    // ----------------------------------------------------------
+    async getEarnInfo() {
+        const resp = await fetch(`${this.baseUrl}/v1/earn`);
+        if (!resp.ok)
+            throw new Error(`GET /v1/earn failed: ${resp.status}`);
+        return resp.json();
+    }
+    async deposit(request, opts) {
+        const params = {};
+        if (opts?.wait) {
+            params.wait = "true";
+            params.timeout = String(opts.timeout ?? 60);
+        }
+        return this.authedPost("/v1/earn/deposit", request, params);
+    }
+    async withdraw(request, opts) {
+        const params = {};
+        if (opts?.wait) {
+            params.wait = "true";
+            params.timeout = String(opts.timeout ?? 60);
+        }
+        return this.authedPost("/v1/earn/withdraw", request, params);
+    }
+    async getPositions() {
+        return this.authedGet("/v1/earn/positions");
+    }
+    // ----------------------------------------------------------
+    // Tasks
+    // ----------------------------------------------------------
+    async getTask(taskId) {
+        return this.authedGet(`/v1/tasks/${taskId}`);
+    }
+    // ----------------------------------------------------------
+    // Notifications
+    // ----------------------------------------------------------
+    async getNotifications(opts) {
+        const params = {};
+        if (opts?.limit !== undefined)
+            params.limit = String(opts.limit);
+        if (opts?.offset !== undefined)
+            params.offset = String(opts.offset);
+        if (opts?.type)
+            params.type = opts.type;
+        return this.authedGet("/v1/notifications", params);
+    }
+    async *notificationStream() {
+        const h = await this.headers();
+        const resp = await fetch(`${this.baseUrl}/v1/notifications/stream`, {
+            headers: h,
+        });
+        if (!resp.ok || !resp.body)
+            return;
+        const reader = resp.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        let eventType = "";
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split("\n");
+            buffer = lines.pop() ?? "";
+            for (const line of lines) {
+                if (line.startsWith("event:")) {
+                    eventType = line.slice(6).trim();
+                }
+                else if (line.startsWith("data:")) {
+                    const data = JSON.parse(line.slice(5).trim());
+                    yield { event: eventType, data };
+                }
+            }
+        }
+    }
+    // ----------------------------------------------------------
+    // Credits / User / Chains
+    // ----------------------------------------------------------
+    async getCredits() {
+        return this.authedGet("/v1/credits");
+    }
+    async getUser() {
+        return this.authedGet("/v1/user");
+    }
+    async getChains() {
+        const resp = await fetch(`${this.baseUrl}/v1/chains`);
+        if (!resp.ok)
+            throw new Error(`GET /v1/chains failed: ${resp.status}`);
+        return resp.json();
+    }
+}
+exports.FereAPI = FereAPI;

package/dist/types.d.ts

@@ -0,0 +1,87 @@
+/** Typed request/response models for the FereAI Gateway API. */
+export interface TaskResponse {
+    task_id: string;
+    status: string;
+    poll_url?: string;
+    notification_stream?: string;
+}
+export interface TaskStatusResponse {
+    task_id: string;
+    status: string;
+    result?: Record<string, unknown>;
+}
+export interface ChatEvent {
+    event: string;
+    data: Record<string, unknown>;
+}
+export interface TokenInfo {
+    token: string;
+    expires_in: number;
+}
+export interface RegisterInfo {
+    registration_id: string;
+    challenge: string;
+}
+export interface WalletInfo {
+    address: string;
+    chain_type: string;
+}
+export interface CreditsInfo {
+    credits_available: number | null;
+}
+export interface SwapRequest {
+    chain_id_in: number;
+    chain_id_out: number;
+    token_in: string;
+    token_out: string;
+    amount: string;
+    slippage_bps?: number;
+    dryrun?: boolean;
+    stop_loss?: {
+        price_percentage: number;
+        sell_percentage: number;
+    };
+    take_profit?: {
+        price_percentage: number;
+        sell_percentage: number;
+    };
+    cancel_conditional_orders?: boolean;
+}
+export interface LimitOrderRequest {
+    chain_id_in: number;
+    chain_id_out: number;
+    token_in: string;
+    token_out: string;
+    amount: string;
+    price_usd_trigger: number;
+    trigger_token_address: string;
+    trigger_token_chain: string;
+    condition: "gte" | "lte";
+    slippage_bps?: number;
+    query?: string;
+}
+export interface HooksRequest {
+    chain_id: number;
+    token_address: string;
+    stop_loss?: {
+        price_percentage: number;
+        sell_percentage: number;
+    };
+    take_profit?: {
+        price_percentage: number;
+        sell_percentage: number;
+    };
+}
+export interface DepositRequest {
+    amount_usdc: number;
+    position_id?: string;
+}
+export interface WithdrawRequest {
+    position_id: string;
+    amount_usdc: number;
+}
+export declare class TaskTimeoutError extends Error {
+    readonly taskId: string;
+    readonly timeout: number;
+    constructor(taskId: string, timeout: number);
+}

package/dist/types.js

@@ -0,0 +1,15 @@
+"use strict";
+/** Typed request/response models for the FereAI Gateway API. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskTimeoutError = void 0;
+class TaskTimeoutError extends Error {
+    taskId;
+    timeout;
+    constructor(taskId, timeout) {
+        super(`Task ${taskId} did not complete within ${timeout}s`);
+        this.name = "TaskTimeoutError";
+        this.taskId = taskId;
+        this.timeout = timeout;
+    }
+}
+exports.TaskTimeoutError = TaskTimeoutError;

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@fereai/sdk",
+  "version": "0.1.0-dev.4",
+  "description": "TypeScript SDK for the FereAI Gateway API",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc"
+  },
+  "dependencies": {
+    "@noble/ed25519": "^2.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0",
+    "typescript": "^5.5"
+  },
+  "license": "MIT",
+  "author": "Fere AI <info@fere.ai>"
+}