@solworks/poll-api-client 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,62 @@
+import type { PollClientConfig, Bet, UserAccount, UserProfile, Balance, Wager, LeaderboardEntry, Friend, WalletTransaction, Notification, StreakInfo, ProbabilityPoint, CreateBetParams, PlaceWagerParams, VoteParams, CancelWagerParams, ApiToken } from './types.js';
+export declare class PollClient {
+    private apiUrl;
+    private token;
+    private fetchFn;
+    private clientId?;
+    constructor(config: PollClientConfig);
+    private request;
+    private buildUrl;
+    getAccount(): Promise<UserAccount>;
+    getProfile(uuid?: string): Promise<UserProfile>;
+    updateDisplayName(name: string): Promise<void>;
+    getXpBalance(): Promise<Balance>;
+    getUsdcBalance(): Promise<Balance>;
+    listPublicBets(params?: {
+        page?: number;
+    }): Promise<Bet[]>;
+    getTrendingBets(): Promise<Bet[]>;
+    getNewBets(): Promise<Bet[]>;
+    getBet(id: string): Promise<Bet>;
+    getMyBets(): Promise<Bet[]>;
+    createBet(params: CreateBetParams): Promise<Bet>;
+    joinBet(betAddress: string): Promise<unknown>;
+    placeWager(params: PlaceWagerParams): Promise<unknown>;
+    cancelWager(params: CancelWagerParams): Promise<unknown>;
+    initiateVote(betAddress: string): Promise<unknown>;
+    vote(params: VoteParams): Promise<unknown>;
+    settleBet(betAddress: string): Promise<unknown>;
+    getProbabilityHistory(betAddress: string): Promise<ProbabilityPoint[]>;
+    getMyWagers(params?: {
+        active?: boolean;
+    }): Promise<Wager[]>;
+    getLeaderboard(): Promise<LeaderboardEntry[]>;
+    getMyRanking(): Promise<LeaderboardEntry>;
+    getFriends(): Promise<Friend[]>;
+    sendFriendRequest(uuid: string): Promise<unknown>;
+    respondFriendRequest(id: string, accept: boolean): Promise<unknown>;
+    getFavouriteBets(): Promise<Bet[]>;
+    favouriteBet(betAddress: string): Promise<unknown>;
+    unfavouriteBet(betAddress: string): Promise<unknown>;
+    nudgeUser(betPubkey: string, recipientUuid: string): Promise<unknown>;
+    getWalletTransactions(): Promise<WalletTransaction[]>;
+    getNotifications(params?: {
+        page?: number;
+    }): Promise<Notification[]>;
+    markNotificationRead(id: string): Promise<unknown>;
+    getStreak(): Promise<StreakInfo>;
+    getTokens(): Promise<{
+        tokens: ApiToken[];
+    }>;
+    createToken(params: {
+        name: string;
+        scopes: string[];
+        expiresAt?: string;
+    }): Promise<{
+        token: string;
+        id: string;
+    }>;
+    revokeToken(tokenId: string): Promise<{
+        success: boolean;
+    }>;
+}

package/dist/client.js

@@ -0,0 +1,200 @@
+import { PollApiError } from './errors.js';
+export class PollClient {
+    apiUrl;
+    token;
+    fetchFn;
+    clientId;
+    constructor(config) {
+        const url = config.apiUrl.replace(/\/+$/, '');
+        if (!url.startsWith('https://') && !url.startsWith('http://localhost') && !url.startsWith('http://127.0.0.1')) {
+            throw new Error('API URL must use HTTPS (except localhost for development)');
+        }
+        this.apiUrl = url;
+        this.token = config.token;
+        this.fetchFn = config.fetch ?? globalThis.fetch;
+        this.clientId = config.clientId;
+    }
+    async request(method, path, body) {
+        const url = `${this.apiUrl}${path}`;
+        const headers = {
+            'Authorization': `Bearer ${this.token}`,
+            'Content-Type': 'application/json',
+        };
+        if (this.clientId) {
+            headers['X-Client'] = this.clientId;
+        }
+        let response;
+        try {
+            response = await this.fetchFn(url, {
+                method,
+                headers,
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+            });
+        }
+        catch (err) {
+            throw new PollApiError(0, `Network error: ${err.message}`);
+        }
+        if (!response.ok) {
+            let errorBody;
+            let errorMessage;
+            try {
+                errorBody = await response.json();
+                errorMessage =
+                    errorBody?.error ??
+                        errorBody?.message ??
+                        response.statusText;
+            }
+            catch {
+                try {
+                    const text = await response.text();
+                    errorMessage = text || response.statusText;
+                    errorBody = text;
+                }
+                catch {
+                    errorMessage = response.statusText;
+                }
+            }
+            throw new PollApiError(response.status, errorMessage, errorBody);
+        }
+        return response.json();
+    }
+    buildUrl(path, params) {
+        if (!params)
+            return path;
+        const searchParams = new URLSearchParams();
+        for (const [key, value] of Object.entries(params)) {
+            if (value !== undefined) {
+                searchParams.set(key, String(value));
+            }
+        }
+        const qs = searchParams.toString();
+        return qs ? `${path}?${qs}` : path;
+    }
+    // ── User ──────────────────────────────────────────────────────────────
+    async getAccount() {
+        return this.request('GET', '/api/user/account');
+    }
+    async getProfile(uuid) {
+        const path = uuid ? `/api/user/profile/${uuid}` : '/api/user/profile';
+        return this.request('GET', path);
+    }
+    async updateDisplayName(name) {
+        await this.request('POST', '/api/user/account/displayname', {
+            displayName: name,
+        });
+    }
+    async getXpBalance() {
+        return this.request('GET', '/api/user/balance');
+    }
+    async getUsdcBalance() {
+        return this.request('GET', '/api/user/usdc/balance');
+    }
+    // ── Bets ──────────────────────────────────────────────────────────────
+    async listPublicBets(params) {
+        const path = this.buildUrl('/api/bets-usdc/all/public', params);
+        return this.request('GET', path);
+    }
+    async getTrendingBets() {
+        return this.request('GET', '/api/bets-usdc/all/public/trending');
+    }
+    async getNewBets() {
+        return this.request('GET', '/api/bets-usdc/all/public/new');
+    }
+    async getBet(id) {
+        return this.request('GET', `/api/bets-usdc/all/public/single/${id}`);
+    }
+    async getMyBets() {
+        return this.request('GET', '/api/bets-usdc/mine');
+    }
+    async createBet(params) {
+        return this.request('POST', '/api/bets-usdc', params);
+    }
+    async joinBet(betAddress) {
+        return this.request('POST', '/api/bets-usdc/join', { betAddress });
+    }
+    async placeWager(params) {
+        return this.request('POST', '/api/bets-usdc/wager', params);
+    }
+    async cancelWager(params) {
+        return this.request('POST', '/api/bets-usdc/wager/cancel', params);
+    }
+    async initiateVote(betAddress) {
+        return this.request('POST', '/api/bets-usdc/vote/initiate', {
+            betAddress,
+        });
+    }
+    async vote(params) {
+        return this.request('POST', '/api/bets-usdc/vote', params);
+    }
+    async settleBet(betAddress) {
+        return this.request('POST', '/api/bets-usdc/settle', { betAddress });
+    }
+    async getProbabilityHistory(betAddress) {
+        return this.request('GET', `/api/bets-usdc/all/public/single/${betAddress}/probability-history`);
+    }
+    // ── Wagers ────────────────────────────────────────────────────────────
+    async getMyWagers(params) {
+        const path = this.buildUrl('/api/bets-usdc/wagers', params);
+        return this.request('GET', path);
+    }
+    // ── Leaderboard ───────────────────────────────────────────────────────
+    async getLeaderboard() {
+        return this.request('GET', '/api/leaderboard');
+    }
+    async getMyRanking() {
+        return this.request('GET', '/api/leaderboard/me');
+    }
+    // ── Social ────────────────────────────────────────────────────────────
+    async getFriends() {
+        return this.request('GET', '/api/user/friends');
+    }
+    async sendFriendRequest(uuid) {
+        return this.request('POST', '/api/user/friends/request', { uuid });
+    }
+    async respondFriendRequest(id, accept) {
+        const action = accept ? 'accept' : 'decline';
+        return this.request('PUT', `/api/user/friends/request/${id}/${action}`);
+    }
+    async getFavouriteBets() {
+        return this.request('GET', '/api/user/favourites/bets');
+    }
+    async favouriteBet(betAddress) {
+        return this.request('POST', '/api/user/favourites/bets', {
+            betAddress,
+        });
+    }
+    async unfavouriteBet(betAddress) {
+        return this.request('DELETE', `/api/user/favourites/bets/${betAddress}`);
+    }
+    async nudgeUser(betPubkey, recipientUuid) {
+        return this.request('POST', `/api/nudge/${betPubkey}/${recipientUuid}`);
+    }
+    // ── Wallet ────────────────────────────────────────────────────────────
+    async getWalletTransactions() {
+        return this.request('GET', '/api/user/wallet/transactions');
+    }
+    // ── Notifications ─────────────────────────────────────────────────────
+    async getNotifications(params) {
+        const path = this.buildUrl('/api/user/notifications', params);
+        return this.request('GET', path);
+    }
+    async markNotificationRead(id) {
+        return this.request('POST', '/api/user/notification/read', {
+            notificationId: id,
+        });
+    }
+    // ── Meta ──────────────────────────────────────────────────────────────
+    async getStreak() {
+        return this.request('GET', '/api/user/streak');
+    }
+    // ── Tokens ────────────────────────────────────────────────────────────
+    async getTokens() {
+        return this.request('GET', '/api/auth/tokens');
+    }
+    async createToken(params) {
+        return this.request('POST', '/api/auth/token', params);
+    }
+    async revokeToken(tokenId) {
+        return this.request('DELETE', `/api/auth/token/${tokenId}`);
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+export declare class PollApiError extends Error {
+    statusCode: number;
+    errorMessage: string;
+    rawResponse?: unknown | undefined;
+    constructor(statusCode: number, errorMessage: string, rawResponse?: unknown | undefined);
+}

package/dist/errors.js

@@ -0,0 +1,12 @@
+export class PollApiError extends Error {
+    statusCode;
+    errorMessage;
+    rawResponse;
+    constructor(statusCode, errorMessage, rawResponse) {
+        super(`API Error ${statusCode}: ${errorMessage}`);
+        this.statusCode = statusCode;
+        this.errorMessage = errorMessage;
+        this.rawResponse = rawResponse;
+        this.name = 'PollApiError';
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { PollClient } from './client.js';
+export { PollApiError } from './errors.js';
+export type { PollClientConfig, Bet, UserAccount, UserProfile, Balance, Wager, LeaderboardEntry, Friend, WalletTransaction, Notification, StreakInfo, ProbabilityPoint, CreateBetParams, PlaceWagerParams, VoteParams, CancelWagerParams, ApiToken, } from './types.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { PollClient } from './client.js';
+export { PollApiError } from './errors.js';

package/dist/types.d.ts

@@ -0,0 +1,118 @@
+export interface PollClientConfig {
+    apiUrl: string;
+    token: string;
+    fetch?: typeof globalThis.fetch;
+    clientId?: string;
+}
+export interface Bet {
+    id: string;
+    question: string;
+    options: string[];
+    status: string;
+    totalVolume: number;
+    createdAt: string;
+    betAddress?: string;
+    inviteCode?: string;
+    [key: string]: unknown;
+}
+export interface UserAccount {
+    id: number;
+    uuid: string;
+    displayName: string | null;
+    email: string | null;
+    xpBalance: number;
+    balance: number;
+    [key: string]: unknown;
+}
+export interface UserProfile {
+    id: number;
+    uuid: string;
+    displayName: string | null;
+    [key: string]: unknown;
+}
+export interface Balance {
+    xp: number;
+    usdc?: number;
+    error: string | null;
+}
+export interface Wager {
+    id: string;
+    betAddress: string;
+    amount: number;
+    optionIndex: number;
+    status: string;
+    [key: string]: unknown;
+}
+export interface LeaderboardEntry {
+    userId: number;
+    uuid: string;
+    displayName: string | null;
+    rank: number;
+    points: number;
+    [key: string]: unknown;
+}
+export interface Friend {
+    id: number;
+    uuid: string;
+    displayName: string | null;
+    [key: string]: unknown;
+}
+export interface WalletTransaction {
+    signature: string;
+    type: string;
+    amount: number;
+    createdAt: string;
+    [key: string]: unknown;
+}
+export interface Notification {
+    id: string;
+    type: string;
+    title: string;
+    body?: string;
+    read: boolean;
+    createdAt: string;
+    [key: string]: unknown;
+}
+export interface StreakInfo {
+    currentStreak: number;
+    longestStreak: number;
+    [key: string]: unknown;
+}
+export interface ProbabilityPoint {
+    timestamp: string;
+    probability: number;
+    [key: string]: unknown;
+}
+export interface CreateBetParams {
+    question: string;
+    options: string[];
+    type: string;
+    amount?: number;
+    expiresAt?: string;
+    [key: string]: unknown;
+}
+export interface PlaceWagerParams {
+    betAddress: string;
+    optionIndex: number;
+    amount: number;
+    [key: string]: unknown;
+}
+export interface VoteParams {
+    betAddress: string;
+    optionIndex: number;
+    [key: string]: unknown;
+}
+export interface CancelWagerParams {
+    betAddress: string;
+    wagerAddress: string;
+    [key: string]: unknown;
+}
+export interface ApiToken {
+    id: string;
+    name: string;
+    tokenPrefix: string;
+    scopes: string[];
+    createdAt: string;
+    lastUsedAt: string | null;
+    expiresAt: string | null;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@solworks/poll-api-client",
+  "version": "0.1.0",
+  "description": "Typed HTTP client for the Poll.fun REST API",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:unit": "vitest run tests/unit"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^3.0.0"
+  }
+}

package/tests/fixtures/index.ts

@@ -0,0 +1,54 @@
+import type { Bet, UserAccount, Wager } from '../../src/types';
+
+let counter = 0;
+function nextId(): string {
+  counter++;
+  return `fixture-${counter}-${Date.now()}`;
+}
+
+export function createBetFixture(overrides?: Partial<Bet>): Bet {
+  return {
+    id: nextId(),
+    question: 'Will BTC hit $100k by end of year?',
+    options: ['Yes', 'No'],
+    status: 'OPEN',
+    totalVolume: 5000,
+    createdAt: '2026-01-15T12:00:00.000Z',
+    betAddress: `bet_${nextId()}`,
+    inviteCode: 'ABC123',
+    ...overrides,
+  };
+}
+
+export function createUserFixture(overrides?: Partial<UserAccount>): UserAccount {
+  const id = counter++;
+  return {
+    id,
+    uuid: `user-uuid-${id}`,
+    displayName: `TestUser${id}`,
+    email: `user${id}@test.com`,
+    xpBalance: 1000,
+    balance: 250,
+    ...overrides,
+  };
+}
+
+export function createWagerFixture(overrides?: Partial<Wager>): Wager {
+  return {
+    id: nextId(),
+    betAddress: `bet_${nextId()}`,
+    amount: 100,
+    optionIndex: 0,
+    status: 'PLACED',
+    ...overrides,
+  };
+}
+
+export function createTokenFixture(): string {
+  const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
+  let suffix = '';
+  for (let i = 0; i < 32; i++) {
+    suffix += chars[Math.floor(Math.random() * chars.length)];
+  }
+  return `polld_${suffix}`;
+}

package/tests/helpers/mock-fetch.ts

@@ -0,0 +1,45 @@
+import { vi } from 'vitest';
+
+export function createMockFetch(): ReturnType<typeof vi.fn> & typeof globalThis.fetch {
+  return vi.fn() as ReturnType<typeof vi.fn> & typeof globalThis.fetch;
+}
+
+export function mockJsonResponse(data: unknown, status = 200): Response {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    statusText: statusTextForCode(status),
+    json: () => Promise.resolve(data),
+    text: () => Promise.resolve(JSON.stringify(data)),
+    headers: new Headers({ 'content-type': 'application/json' }),
+    redirected: false,
+    type: 'basic' as ResponseType,
+    url: '',
+    clone: () => mockJsonResponse(data, status),
+    body: null,
+    bodyUsed: false,
+    arrayBuffer: () => Promise.resolve(new ArrayBuffer(0)),
+    blob: () => Promise.resolve(new Blob()),
+    formData: () => Promise.resolve(new FormData()),
+    bytes: () => Promise.resolve(new Uint8Array()),
+  } as Response;
+}
+
+export function mockErrorResponse(error: string, status: number): Response {
+  return mockJsonResponse({ error }, status);
+}
+
+function statusTextForCode(status: number): string {
+  const map: Record<number, string> = {
+    200: 'OK',
+    201: 'Created',
+    204: 'No Content',
+    400: 'Bad Request',
+    401: 'Unauthorized',
+    403: 'Forbidden',
+    404: 'Not Found',
+    500: 'Internal Server Error',
+    502: 'Bad Gateway',
+  };
+  return map[status] ?? 'Unknown';
+}

package/tests/unit/client.test.ts

@@ -0,0 +1,166 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { PollClient } from '../../src/client';
+import { PollApiError } from '../../src/errors';
+import { createMockFetch, mockJsonResponse, mockErrorResponse } from '../helpers/mock-fetch';
+import { createUserFixture } from '../fixtures';
+
+describe('PollClient core request logic', () => {
+  let mockFetch: ReturnType<typeof createMockFetch>;
+
+  beforeEach(() => {
+    mockFetch = createMockFetch();
+  });
+
+  it('sets Authorization header correctly', async () => {
+    const user = createUserFixture();
+    mockFetch.mockResolvedValue(mockJsonResponse(user));
+
+    const client = new PollClient({
+      apiUrl: 'https://api.poll.fun',
+      token: 'my-secret-token',
+      fetch: mockFetch,
+    });
+
+    await client.getAccount();
+
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+    const [url, init] = mockFetch.mock.calls[0];
+    expect(url).toBe('https://api.poll.fun/api/user/account');
+    expect(init.headers['Authorization']).toBe('Bearer my-secret-token');
+    expect(init.headers['Content-Type']).toBe('application/json');
+  });
+
+  it('sets X-Client header if clientId provided', async () => {
+    const user = createUserFixture();
+    mockFetch.mockResolvedValue(mockJsonResponse(user));
+
+    const client = new PollClient({
+      apiUrl: 'https://api.poll.fun',
+      token: 'tok',
+      fetch: mockFetch,
+      clientId: 'poll-mcp',
+    });
+
+    await client.getAccount();
+
+    const [, init] = mockFetch.mock.calls[0];
+    expect(init.headers['X-Client']).toBe('poll-mcp');
+  });
+
+  it('does not set X-Client header if clientId not provided', async () => {
+    const user = createUserFixture();
+    mockFetch.mockResolvedValue(mockJsonResponse(user));
+
+    const client = new PollClient({
+      apiUrl: 'https://api.poll.fun',
+      token: 'tok',
+      fetch: mockFetch,
+    });
+
+    await client.getAccount();
+
+    const [, init] = mockFetch.mock.calls[0];
+    expect(init.headers['X-Client']).toBeUndefined();
+  });
+
+  it('handles 401 errors', async () => {
+    mockFetch.mockResolvedValue(mockErrorResponse('Unauthorized', 401));
+
+    const client = new PollClient({
+      apiUrl: 'https://api.poll.fun',
+      token: 'bad-token',
+      fetch: mockFetch,
+    });
+
+    await expect(client.getAccount()).rejects.toThrow(PollApiError);
+    await expect(client.getAccount()).rejects.toMatchObject({
+      statusCode: 401,
+      errorMessage: 'Unauthorized',
+    });
+  });
+
+  it('handles 403 scope errors', async () => {
+    mockFetch.mockResolvedValue(
+      mockErrorResponse('Insufficient scope: requires bets:read', 403)
+    );
+
+    const client = new PollClient({
+      apiUrl: 'https://api.poll.fun',
+      token: 'tok',
+      fetch: mockFetch,
+    });
+
+    await expect(client.getAccount()).rejects.toThrow(PollApiError);
+    await expect(client.getAccount()).rejects.toMatchObject({
+      statusCode: 403,
+      errorMessage: 'Insufficient scope: requires bets:read',
+    });
+  });
+
+  it('handles 502 non-JSON errors', async () => {
+    const response502: Response = {
+      ok: false,
+      status: 502,
+      statusText: 'Bad Gateway',
+      json: () => Promise.reject(new Error('not JSON')),
+      text: () => Promise.resolve('<html>Bad Gateway</html>'),
+      headers: new Headers(),
+      redirected: false,
+      type: 'basic' as ResponseType,
+      url: '',
+      clone: () => response502,
+      body: null,
+      bodyUsed: false,
+      arrayBuffer: () => Promise.resolve(new ArrayBuffer(0)),
+      blob: () => Promise.resolve(new Blob()),
+      formData: () => Promise.resolve(new FormData()),
+      bytes: () => Promise.resolve(new Uint8Array()),
+    } as Response;
+
+    mockFetch.mockResolvedValue(response502);
+
+    const client = new PollClient({
+      apiUrl: 'https://api.poll.fun',
+      token: 'tok',
+      fetch: mockFetch,
+    });
+
+    await expect(client.getAccount()).rejects.toThrow(PollApiError);
+    await expect(client.getAccount()).rejects.toMatchObject({
+      statusCode: 502,
+      errorMessage: '<html>Bad Gateway</html>',
+    });
+  });
+
+  it('handles network errors (fetch throws)', async () => {
+    mockFetch.mockRejectedValue(new Error('ECONNREFUSED'));
+
+    const client = new PollClient({
+      apiUrl: 'https://api.poll.fun',
+      token: 'tok',
+      fetch: mockFetch,
+    });
+
+    await expect(client.getAccount()).rejects.toThrow(PollApiError);
+    await expect(client.getAccount()).rejects.toMatchObject({
+      statusCode: 0,
+      errorMessage: 'Network error: ECONNREFUSED',
+    });
+  });
+
+  it('strips trailing slashes from apiUrl', async () => {
+    const user = createUserFixture();
+    mockFetch.mockResolvedValue(mockJsonResponse(user));
+
+    const client = new PollClient({
+      apiUrl: 'https://api.poll.fun///',
+      token: 'tok',
+      fetch: mockFetch,
+    });
+
+    await client.getAccount();
+
+    const [url] = mockFetch.mock.calls[0];
+    expect(url).toBe('https://api.poll.fun/api/user/account');
+  });
+});

package/tests/unit/endpoints/bets.test.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { PollClient } from '../../../src/client';
+import { createMockFetch, mockJsonResponse } from '../../helpers/mock-fetch';
+import { createBetFixture } from '../../fixtures';
+
+describe('Bets endpoints', () => {
+  let mockFetch: ReturnType<typeof createMockFetch>;
+  let client: PollClient;
+
+  beforeEach(() => {
+    mockFetch = createMockFetch();
+    client = new PollClient({
+      apiUrl: 'https://api.poll.fun',
+      token: 'test-token',
+      fetch: mockFetch,
+    });
+  });
+
+  it('listPublicBets sends correct GET', async () => {
+    const bets = [createBetFixture(), createBetFixture()];
+    mockFetch.mockResolvedValue(mockJsonResponse(bets));
+
+    const result = await client.listPublicBets();
+
+    expect(result).toEqual(bets);
+    const [url, init] = mockFetch.mock.calls[0];
+    expect(url).toBe('https://api.poll.fun/api/bets-usdc/all/public');
+    expect(init.method).toBe('GET');
+  });
+
+  it('listPublicBets with page param', async () => {
+    const bets = [createBetFixture()];
+    mockFetch.mockResolvedValue(mockJsonResponse(bets));
+
+    await client.listPublicBets({ page: 2 });
+
+    const [url] = mockFetch.mock.calls[0];
+    expect(url).toBe('https://api.poll.fun/api/bets-usdc/all/public?page=2');
+  });
+
+  it('getTrendingBets sends correct GET', async () => {
+    const bets = [createBetFixture()];
+    mockFetch.mockResolvedValue(mockJsonResponse(bets));
+
+    const result = await client.getTrendingBets();
+
+    expect(result).toEqual(bets);
+    const [url, init] = mockFetch.mock.calls[0];
+    expect(url).toBe('https://api.poll.fun/api/bets-usdc/all/public/trending');
+    expect(init.method).toBe('GET');
+  });
+
+  it('getBet sends GET with ID', async () => {
+    const bet = createBetFixture({ id: 'bet-123' });
+    mockFetch.mockResolvedValue(mockJsonResponse(bet));
+
+    const result = await client.getBet('bet-123');
+
+    expect(result).toEqual(bet);
+    const [url, init] = mockFetch.mock.calls[0];
+    expect(url).toBe('https://api.poll.fun/api/bets-usdc/all/public/single/bet-123');
+    expect(init.method).toBe('GET');
+  });
+
+  it('createBet sends POST with body', async () => {
+    const newBet = createBetFixture();
+    mockFetch.mockResolvedValue(mockJsonResponse(newBet));
+
+    const params = {
+      question: 'Will it rain tomorrow?',
+      options: ['Yes', 'No'],
+      type: 'XP',
+      amount: 100,
+    };
+
+    const result = await client.createBet(params);
+
+    expect(result).toEqual(newBet);
+    const [url, init] = mockFetch.mock.calls[0];
+    expect(url).toBe('https://api.poll.fun/api/bets-usdc');
+    expect(init.method).toBe('POST');
+    expect(JSON.parse(init.body)).toEqual(params);
+  });
+
+  it('placeWager sends POST with body', async () => {
+    mockFetch.mockResolvedValue(mockJsonResponse({ success: true }));
+
+    const params = {
+      betAddress: 'bet_abc',
+      optionIndex: 1,
+      amount: 50,
+    };
+
+    await client.placeWager(params);
+
+    const [url, init] = mockFetch.mock.calls[0];
+    expect(url).toBe('https://api.poll.fun/api/bets-usdc/wager');
+    expect(init.method).toBe('POST');
+    expect(JSON.parse(init.body)).toEqual(params);
+  });
+
+  it('vote sends POST with body', async () => {
+    mockFetch.mockResolvedValue(mockJsonResponse({ success: true }));
+
+    const params = {
+      betAddress: 'bet_abc',
+      optionIndex: 0,
+    };
+
+    await client.vote(params);
+
+    const [url, init] = mockFetch.mock.calls[0];
+    expect(url).toBe('https://api.poll.fun/api/bets-usdc/vote');
+    expect(init.method).toBe('POST');
+    expect(JSON.parse(init.body)).toEqual(params);
+  });
+});

package/tests/unit/endpoints/leaderboard.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { PollClient } from '../../../src/client';
+import { createMockFetch, mockJsonResponse } from '../../helpers/mock-fetch';
+
+describe('Leaderboard endpoints', () => {
+  let mockFetch: ReturnType<typeof createMockFetch>;
+  let client: PollClient;
+
+  beforeEach(() => {
+    mockFetch = createMockFetch();
+    client = new PollClient({
+      apiUrl: 'https://api.poll.fun',
+      token: 'test-token',
+      fetch: mockFetch,
+    });
+  });
+
+  it('getLeaderboard sends correct GET', async () => {
+    const entries = [
+      { userId: 1, uuid: 'u1', displayName: 'User1', rank: 1, points: 1000 },
+      { userId: 2, uuid: 'u2', displayName: 'User2', rank: 2, points: 800 },
+    ];
+    mockFetch.mockResolvedValue(mockJsonResponse(entries));
+
+    const result = await client.getLeaderboard();
+
+    expect(result).toEqual(entries);
+    const [url, init] = mockFetch.mock.calls[0];
+    expect(url).toBe('https://api.poll.fun/api/leaderboard');
+    expect(init.method).toBe('GET');
+  });
+
+  it('getMyRanking sends correct GET', async () => {
+    const entry = { userId: 1, uuid: 'u1', displayName: 'Me', rank: 5, points: 500 };
+    mockFetch.mockResolvedValue(mockJsonResponse(entry));
+
+    const result = await client.getMyRanking();
+
+    expect(result).toEqual(entry);
+    const [url, init] = mockFetch.mock.calls[0];
+    expect(url).toBe('https://api.poll.fun/api/leaderboard/me');
+    expect(init.method).toBe('GET');
+  });
+});

package/tests/unit/endpoints/social.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { PollClient } from '../../../src/client';
+import { createMockFetch, mockJsonResponse } from '../../helpers/mock-fetch';
+
+describe('Social endpoints', () => {
+  let mockFetch: ReturnType<typeof createMockFetch>;
+  let client: PollClient;
+
+  beforeEach(() => {
+    mockFetch = createMockFetch();
+    client = new PollClient({
+      apiUrl: 'https://api.poll.fun',
+      token: 'test-token',
+      fetch: mockFetch,
+    });
+  });
+
+  it('getFriends sends correct GET', async () => {
+    const friends = [
+      { id: 1, uuid: 'f1', displayName: 'Friend1' },
+      { id: 2, uuid: 'f2', displayName: 'Friend2' },
+    ];
+    mockFetch.mockResolvedValue(mockJsonResponse(friends));
+
+    const result = await client.getFriends();
+
+    expect(result).toEqual(friends);
+    const [url, init] = mockFetch.mock.calls[0];
+    expect(url).toBe('https://api.poll.fun/api/user/friends');
+    expect(init.method).toBe('GET');
+  });
+
+  it('sendFriendRequest sends POST', async () => {
+    mockFetch.mockResolvedValue(mockJsonResponse({ success: true }));
+
+    await client.sendFriendRequest('target-uuid');
+
+    const [url, init] = mockFetch.mock.calls[0];
+    expect(url).toBe('https://api.poll.fun/api/user/friends/request');
+    expect(init.method).toBe('POST');
+    expect(JSON.parse(init.body)).toEqual({ uuid: 'target-uuid' });
+  });
+
+  it('favouriteBet sends POST', async () => {
+    mockFetch.mockResolvedValue(mockJsonResponse({ success: true }));
+
+    await client.favouriteBet('bet_xyz');
+
+    const [url, init] = mockFetch.mock.calls[0];
+    expect(url).toBe('https://api.poll.fun/api/user/favourites/bets');
+    expect(init.method).toBe('POST');
+    expect(JSON.parse(init.body)).toEqual({ betAddress: 'bet_xyz' });
+  });
+
+  it('unfavouriteBet sends DELETE', async () => {
+    mockFetch.mockResolvedValue(mockJsonResponse({ success: true }));
+
+    await client.unfavouriteBet('bet_xyz');
+
+    const [url, init] = mockFetch.mock.calls[0];
+    expect(url).toBe('https://api.poll.fun/api/user/favourites/bets/bet_xyz');
+    expect(init.method).toBe('DELETE');
+  });
+});

package/tests/unit/endpoints/user.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { PollClient } from '../../../src/client';
+import { createMockFetch, mockJsonResponse } from '../../helpers/mock-fetch';
+import { createUserFixture } from '../../fixtures';
+
+describe('User endpoints', () => {
+  let mockFetch: ReturnType<typeof createMockFetch>;
+  let client: PollClient;
+
+  beforeEach(() => {
+    mockFetch = createMockFetch();
+    client = new PollClient({
+      apiUrl: 'https://api.poll.fun',
+      token: 'test-token',
+      fetch: mockFetch,
+    });
+  });
+
+  it('getAccount sends correct GET', async () => {
+    const user = createUserFixture();
+    mockFetch.mockResolvedValue(mockJsonResponse(user));
+
+    const result = await client.getAccount();
+
+    expect(result).toEqual(user);
+    const [url, init] = mockFetch.mock.calls[0];
+    expect(url).toBe('https://api.poll.fun/api/user/account');
+    expect(init.method).toBe('GET');
+  });
+
+  it('getProfile without uuid', async () => {
+    const profile = { id: 1, uuid: 'abc', displayName: 'Test' };
+    mockFetch.mockResolvedValue(mockJsonResponse(profile));
+
+    const result = await client.getProfile();
+
+    expect(result).toEqual(profile);
+    const [url] = mockFetch.mock.calls[0];
+    expect(url).toBe('https://api.poll.fun/api/user/profile');
+  });
+
+  it('getProfile with uuid sends GET /api/user/profile/:uuid', async () => {
+    const profile = { id: 2, uuid: 'user-uuid-123', displayName: 'OtherUser' };
+    mockFetch.mockResolvedValue(mockJsonResponse(profile));
+
+    const result = await client.getProfile('user-uuid-123');
+
+    expect(result).toEqual(profile);
+    const [url] = mockFetch.mock.calls[0];
+    expect(url).toBe('https://api.poll.fun/api/user/profile/user-uuid-123');
+  });
+
+  it('updateDisplayName sends POST', async () => {
+    mockFetch.mockResolvedValue(mockJsonResponse({}));
+
+    await client.updateDisplayName('NewName');
+
+    const [url, init] = mockFetch.mock.calls[0];
+    expect(url).toBe('https://api.poll.fun/api/user/account/displayname');
+    expect(init.method).toBe('POST');
+    expect(JSON.parse(init.body)).toEqual({ displayName: 'NewName' });
+  });
+
+  it('getXpBalance sends correct GET', async () => {
+    const balance = { xp: 500, error: null };
+    mockFetch.mockResolvedValue(mockJsonResponse(balance));
+
+    const result = await client.getXpBalance();
+
+    expect(result).toEqual(balance);
+    const [url, init] = mockFetch.mock.calls[0];
+    expect(url).toBe('https://api.poll.fun/api/user/balance');
+    expect(init.method).toBe('GET');
+  });
+});

package/tests/unit/endpoints/wallet.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { PollClient } from '../../../src/client';
+import { createMockFetch, mockJsonResponse } from '../../helpers/mock-fetch';
+
+describe('Wallet endpoints', () => {
+  let mockFetch: ReturnType<typeof createMockFetch>;
+  let client: PollClient;
+
+  beforeEach(() => {
+    mockFetch = createMockFetch();
+    client = new PollClient({
+      apiUrl: 'https://api.poll.fun',
+      token: 'test-token',
+      fetch: mockFetch,
+    });
+  });
+
+  it('getWalletTransactions sends correct GET', async () => {
+    const txns = [
+      {
+        signature: 'sig123',
+        type: 'DEPOSIT',
+        amount: 100,
+        createdAt: '2026-01-01T00:00:00.000Z',
+      },
+      {
+        signature: 'sig456',
+        type: 'WITHDRAWAL',
+        amount: 50,
+        createdAt: '2026-01-02T00:00:00.000Z',
+      },
+    ];
+    mockFetch.mockResolvedValue(mockJsonResponse(txns));
+
+    const result = await client.getWalletTransactions();
+
+    expect(result).toEqual(txns);
+    const [url, init] = mockFetch.mock.calls[0];
+    expect(url).toBe('https://api.poll.fun/api/user/wallet/transactions');
+    expect(init.method).toBe('GET');
+  });
+});

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "node",
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "tests"]
+}

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config';
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    testTimeout: 15000,
+  },
+});