@swarm-tips/client 0.1.1 → 0.2.0

package/dist/coordination-game/protocol.js

@@ -0,0 +1,120 @@
+import { PublicKey } from "@solana/web3.js";
+import { COORDINATION_GAME_PROGRAM_ID } from "../contracts/index.js";
+const encoder = new TextEncoder();
+export const COORDINATION_GAME_TOURNAMENT_ID = 1n;
+export const GUESS_UNREVEALED = 255;
+export const REVEAL_TIMEOUT_SLOTS = 14400n;
+export function toGuessBit(value) {
+    if (value === 0 || value === 1)
+        return value;
+    throw new RangeError(`Expected 0 or 1, got ${value}`);
+}
+export function u64LE(value) {
+    if (value < 0n || value > 0xffffffffffffffffn) {
+        throw new RangeError("u64 value is out of range");
+    }
+    const bytes = new Uint8Array(8);
+    let remaining = value;
+    for (let index = 0; index < bytes.length; index += 1) {
+        bytes[index] = Number(remaining & 0xffn);
+        remaining >>= 8n;
+    }
+    return bytes;
+}
+function programId(programId) {
+    if (programId instanceof PublicKey)
+        return programId;
+    return programId
+        ? new PublicKey(programId)
+        : COORDINATION_GAME_PROGRAM_ID;
+}
+export function globalConfigPda(id) {
+    return PublicKey.findProgramAddressSync([encoder.encode("global_config")], programId(id));
+}
+export function gameCounterPda(id) {
+    return PublicKey.findProgramAddressSync([encoder.encode("game_counter")], programId(id));
+}
+export function gamePda(gameId, id) {
+    return PublicKey.findProgramAddressSync([encoder.encode("game"), u64LE(gameId)], programId(id));
+}
+export function tournamentPda(tournamentId, id) {
+    return PublicKey.findProgramAddressSync([encoder.encode("tournament"), u64LE(tournamentId)], programId(id));
+}
+export function playerProfilePda(tournamentId, wallet, id) {
+    return PublicKey.findProgramAddressSync([encoder.encode("player"), u64LE(tournamentId), wallet.toBytes()], programId(id));
+}
+export function escrowPda(tournamentId, wallet, id) {
+    return PublicKey.findProgramAddressSync([encoder.encode("escrow"), u64LE(tournamentId), wallet.toBytes()], programId(id));
+}
+export function playerSessionPda(wallet, session, id) {
+    return PublicKey.findProgramAddressSync([encoder.encode("game_session"), wallet.toBytes(), session.toBytes()], programId(id));
+}
+function viewOf(data) {
+    return new DataView(data.buffer, data.byteOffset, data.byteLength);
+}
+export function decodeGlobalConfig(data) {
+    const stakeOffset = 107;
+    if (data.length < stakeOffset + 8) {
+        throw new RangeError(`GlobalConfig is the pre-migration ${data.length}-byte layout and carries no stake_lamports`);
+    }
+    return {
+        authority: new PublicKey(data.subarray(8, 40)),
+        matchmaker: new PublicKey(data.subarray(40, 72)),
+        treasury: new PublicKey(data.subarray(72, 104)),
+        treasurySplitBps: data[104] | (data[105] << 8),
+        stakeLamports: new DataView(data.buffer, data.byteOffset + stakeOffset, 8).getBigUint64(0, true),
+    };
+}
+export function decodeTournament(data) {
+    const minimumLength = 8 + 8 + 32 + 8 + 8 + 8 + 8 + 1;
+    if (data.length < minimumLength) {
+        throw new RangeError(`Tournament account data too short: ${data.length} bytes`);
+    }
+    const view = viewOf(data);
+    return {
+        tournamentId: view.getBigUint64(8, true),
+        startTime: view.getBigInt64(48, true),
+        endTime: view.getBigInt64(56, true),
+        prizeLamports: view.getBigUint64(64, true),
+        gameCount: view.getBigUint64(72, true),
+        finalized: data[80] !== 0,
+    };
+}
+export function decodeTournamentStats(data) {
+    const tournament = decodeTournament(data);
+    return { gameCount: Number(tournament.gameCount), prizeLamports: tournament.prizeLamports };
+}
+function hasCommitted(commit) {
+    return Array.from(commit).some((byte) => byte !== 0);
+}
+export function deriveSolanaResumeState(game, wallet) {
+    if (!["active", "committing", "revealing"].includes(game.state))
+        return null;
+    const iAmP1 = game.playerOne === wallet;
+    const iAmP2 = game.playerTwo === wallet;
+    if (!iAmP1 && !iAmP2)
+        return null;
+    if ((iAmP1 ? game.p1Guess : game.p2Guess) !== GUESS_UNREVEALED)
+        return null;
+    const mine = hasCommitted(iAmP1 ? game.p1Commit : game.p2Commit);
+    const bothCommitted = hasCommitted(game.p1Commit) && hasCommitted(game.p2Commit);
+    return {
+        phase: !mine ? "active" : bothCommitted ? "revealing" : "committing",
+        iAmP1,
+        bothCommitted,
+    };
+}
+export function timeoutDeadlineSlot(game) {
+    const later = game.p1CommitSlot > game.p2CommitSlot ? game.p1CommitSlot : game.p2CommitSlot;
+    if (game.state === "active")
+        return game.activatedAtSlot + game.commitTimeoutSlots;
+    if (game.state === "committing")
+        return later + game.commitTimeoutSlots;
+    if (game.state === "revealing")
+        return later + REVEAL_TIMEOUT_SLOTS;
+    return null;
+}
+export function timeoutClaimableAtSlot(game, currentSlot) {
+    const deadline = timeoutDeadlineSlot(game);
+    return deadline !== null && currentSlot >= deadline;
+}

package/dist/coordination-game/solana.d.ts

@@ -0,0 +1,84 @@
+import { BN, Program } from "@coral-xyz/anchor";
+import { Connection, Keypair, PublicKey, Transaction, type Commitment, type TransactionInstruction, type VersionedTransaction } from "@solana/web3.js";
+import { type CoordinationGame } from "../contracts/index.js";
+import { type GlobalConfigData, type TournamentData } from "./protocol.js";
+export interface SolanaWalletSigner {
+    publicKey: PublicKey;
+    signTransaction<T extends Transaction | VersionedTransaction>(transaction: T): Promise<T>;
+    signAllTransactions?<T extends Transaction | VersionedTransaction>(transactions: T[]): Promise<T[]>;
+}
+export interface SolanaSessionStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+export interface CoordinationGameSolanaClientOptions {
+    connection?: Connection;
+    rpcUrl?: string;
+    wallet?: SolanaWalletSigner;
+    tournamentId?: bigint;
+    commitment?: Commitment;
+}
+export declare function generateSessionKeypair(): Keypair;
+export declare function readStoredSession(storage: SolanaSessionStorage, walletAddress: string, now?: () => number): Keypair | null;
+export declare function storeSession(storage: SolanaSessionStorage, session: Keypair, walletAddress: string, now?: () => number): void;
+export declare function clearSession(storage: SolanaSessionStorage): void;
+export declare class CoordinationGameSolanaClient {
+    readonly connection: Connection;
+    readonly wallet?: SolanaWalletSigner;
+    readonly tournamentId: bigint;
+    readonly commitment: Commitment;
+    constructor(options: CoordinationGameSolanaClientOptions);
+    program(wallet?: SolanaWalletSigner | undefined): Program<CoordinationGame>;
+    sessionProgram(session: Keypair): Program<CoordinationGame>;
+    private requireWallet;
+    liveStakeRemainingAccounts(): {
+        pubkey: PublicKey;
+        isSigner: boolean;
+        isWritable: boolean;
+    }[];
+    fetchTournament(tournamentId?: bigint): Promise<TournamentData | null>;
+    fetchGlobalConfig(): Promise<GlobalConfigData>;
+    buildCreatePlayerSessionInstruction(sessionPublicKey: PublicKey): Promise<TransactionInstruction>;
+    depositStake(tournament: PublicKey, session?: Keypair | null): Promise<string>;
+    buildCreateGameTransaction(input: {
+        stake: BN;
+        matchupCommitment: number[];
+        tournament: PublicKey;
+        escrow: PublicKey;
+        globalConfig: PublicKey;
+        matchmaker: PublicKey;
+        playerProfile: PublicKey;
+        gameCounter: PublicKey;
+        game: PublicKey;
+        session?: Keypair;
+        player?: PublicKey;
+    }): Promise<Transaction>;
+    buildJoinGameTransaction(input: {
+        game: PublicKey;
+        tournament: PublicKey;
+        escrow: PublicKey;
+        preInstructions?: TransactionInstruction[];
+        session?: Keypair;
+    }): Promise<{
+        transaction: Transaction;
+        payer: PublicKey;
+        matchmaker: PublicKey;
+    }>;
+    applyCosignature(transaction: Transaction, signer: PublicKey, signatureBase64: string): Promise<Transaction>;
+    messageBase64(transaction: Transaction): string;
+    signBroadcastAndConfirm(transaction: Transaction, session?: Keypair): Promise<string>;
+    commitGuess(commitment: number[], game: PublicKey, session?: Keypair | null): Promise<string>;
+    revealGuess(r: number[], rMatchup: number[] | null, accounts: Record<string, PublicKey>, session?: Keypair | null): Promise<string>;
+    closeGame(game: PublicKey, session?: Keypair | null): Promise<string>;
+    resolveTimeout(gameId: bigint, session?: Keypair | null): Promise<string>;
+    closeSessionByDelegate(session: Keypair, player: PublicKey): Promise<string>;
+    deriveAddresses(gameId: bigint, player: PublicKey): {
+        globalConfig: PublicKey;
+        gameCounter: PublicKey;
+        game: PublicKey;
+        tournament: PublicKey;
+        playerProfile: PublicKey;
+        escrow: PublicKey;
+    };
+}

package/dist/coordination-game/solana.js

@@ -0,0 +1,262 @@
+import { AnchorProvider, Program } from "@coral-xyz/anchor";
+import { Buffer } from "buffer";
+import { Connection, Keypair, SystemProgram, Transaction, } from "@solana/web3.js";
+import { COORDINATION_GAME_IDL } from "../contracts/index.js";
+import { SwarmClientError } from "../errors.js";
+import { decodeGlobalConfig, decodeTournament, escrowPda, gameCounterPda, gamePda, globalConfigPda, playerProfilePda, playerSessionPda, tournamentPda, } from "./protocol.js";
+const SESSION_STORAGE_KEY = "coordination-session";
+const SESSION_TTL_MS = 24 * 60 * 60 * 1000;
+function walletForSession(session) {
+    return {
+        publicKey: session.publicKey,
+        async signTransaction(transaction) {
+            if (transaction instanceof Transaction)
+                transaction.partialSign(session);
+            else
+                transaction.sign([session]);
+            return transaction;
+        },
+        async signAllTransactions(transactions) {
+            for (const transaction of transactions)
+                await this.signTransaction(transaction);
+            return transactions;
+        },
+    };
+}
+function readonlyWallet() {
+    const keypair = Keypair.generate();
+    return {
+        publicKey: keypair.publicKey,
+        signTransaction: async (transaction) => transaction,
+        signAllTransactions: async (transactions) => transactions,
+    };
+}
+function anchorProgram(connection, wallet, commitment) {
+    const provider = new AnchorProvider(connection, wallet, { commitment, skipPreflight: false });
+    return new Program(COORDINATION_GAME_IDL, provider);
+}
+export function generateSessionKeypair() { return Keypair.generate(); }
+export function readStoredSession(storage, walletAddress, now = Date.now) {
+    const raw = storage.getItem(SESSION_STORAGE_KEY);
+    if (!raw)
+        return null;
+    try {
+        const value = JSON.parse(raw);
+        if (!Array.isArray(value.secretKey) || value.secretKey.length !== 64 || typeof value.createdAt !== "number" || value.wallet !== walletAddress || now() - value.createdAt > SESSION_TTL_MS) {
+            storage.removeItem(SESSION_STORAGE_KEY);
+            return null;
+        }
+        return Keypair.fromSecretKey(Uint8Array.from(value.secretKey));
+    }
+    catch {
+        storage.removeItem(SESSION_STORAGE_KEY);
+        return null;
+    }
+}
+export function storeSession(storage, session, walletAddress, now = Date.now) {
+    storage.setItem(SESSION_STORAGE_KEY, JSON.stringify({
+        secretKey: Array.from(session.secretKey),
+        createdAt: now(),
+        wallet: walletAddress,
+    }));
+}
+export function clearSession(storage) {
+    storage.removeItem(SESSION_STORAGE_KEY);
+}
+export class CoordinationGameSolanaClient {
+    connection;
+    wallet;
+    tournamentId;
+    commitment;
+    constructor(options) {
+        if (!options.connection && !options.rpcUrl) {
+            throw new SwarmClientError({ code: "INVALID_ARGUMENT", operation: "solana.constructor", message: "connection or rpcUrl is required" });
+        }
+        this.connection = options.connection ?? new Connection(options.rpcUrl, options.commitment ?? "confirmed");
+        this.wallet = options.wallet;
+        this.tournamentId = options.tournamentId ?? 1n;
+        this.commitment = options.commitment ?? "confirmed";
+    }
+    program(wallet = this.wallet) {
+        return anchorProgram(this.connection, wallet ?? readonlyWallet(), this.commitment);
+    }
+    sessionProgram(session) {
+        return anchorProgram(this.connection, walletForSession(session), this.commitment);
+    }
+    requireWallet() {
+        if (!this.wallet)
+            throw new SwarmClientError({ code: "INVALID_ARGUMENT", operation: "solana.wallet", message: "A wallet signer is required" });
+        return this.wallet;
+    }
+    liveStakeRemainingAccounts() {
+        return [{ pubkey: globalConfigPda()[0], isSigner: false, isWritable: false }];
+    }
+    async fetchTournament(tournamentId = this.tournamentId) {
+        const info = await this.connection.getAccountInfo(tournamentPda(tournamentId)[0]);
+        return info ? decodeTournament(new Uint8Array(info.data)) : null;
+    }
+    async fetchGlobalConfig() {
+        const info = await this.connection.getAccountInfo(globalConfigPda()[0]);
+        if (!info)
+            throw new SwarmClientError({ code: "INVALID_RESPONSE", operation: "solana.fetchGlobalConfig", message: "GlobalConfig account not found on-chain" });
+        return decodeGlobalConfig(new Uint8Array(info.data));
+    }
+    async buildCreatePlayerSessionInstruction(sessionPublicKey) {
+        const wallet = this.requireWallet();
+        return this.program(wallet).methods.createPlayerSession().accountsPartial({ sessionKey: sessionPublicKey }).instruction();
+    }
+    async depositStake(tournament, session) {
+        const wallet = this.requireWallet();
+        const escrow = escrowPda(this.tournamentId, wallet.publicKey)[0];
+        if (session) {
+            return this.sessionProgram(session).methods.depositStakeSession().accountsPartial({
+                player: wallet.publicKey,
+                sessionAuthority: playerSessionPda(wallet.publicKey, session.publicKey)[0],
+                tournament,
+                escrow,
+            }).remainingAccounts(this.liveStakeRemainingAccounts()).rpc();
+        }
+        return this.program(wallet).methods.depositStake().accountsPartial({ tournament, escrow }).remainingAccounts(this.liveStakeRemainingAccounts()).rpc();
+    }
+    async buildCreateGameTransaction(input) {
+        const wallet = this.requireWallet();
+        if (input.session) {
+            const player = input.player ?? wallet.publicKey;
+            return this.sessionProgram(input.session).methods.createGameSession(input.stake, input.matchupCommitment).accountsPartial({
+                game: input.game,
+                gameCounter: input.gameCounter,
+                playerProfile: input.playerProfile,
+                escrow: input.escrow,
+                tournament: input.tournament,
+                globalConfig: input.globalConfig,
+                matchmaker: input.matchmaker,
+                player,
+                sessionAuthority: playerSessionPda(player, input.session.publicKey)[0],
+                sessionSigner: input.session.publicKey,
+                systemProgram: SystemProgram.programId,
+            }).transaction();
+        }
+        return this.program(wallet).methods.createGame(input.stake, input.matchupCommitment).accountsPartial({
+            game: input.game,
+            gameCounter: input.gameCounter,
+            playerProfile: input.playerProfile,
+            escrow: input.escrow,
+            tournament: input.tournament,
+            globalConfig: input.globalConfig,
+            matchmaker: input.matchmaker,
+            player: wallet.publicKey,
+            systemProgram: SystemProgram.programId,
+        }).transaction();
+    }
+    async buildJoinGameTransaction(input) {
+        const wallet = this.requireWallet();
+        const config = await this.fetchGlobalConfig();
+        const globalConfig = globalConfigPda()[0];
+        const program = input.session ? this.sessionProgram(input.session) : this.program(wallet);
+        const builder = input.session
+            ? program.methods.joinGameSession().accountsPartial({
+                player: wallet.publicKey,
+                sessionAuthority: playerSessionPda(wallet.publicKey, input.session.publicKey)[0],
+                game: input.game,
+                tournament: input.tournament,
+                escrow: input.escrow,
+                globalConfig,
+                matchmaker: config.matchmaker,
+            })
+            : program.methods.joinGame().accountsPartial({
+                game: input.game,
+                tournament: input.tournament,
+                escrow: input.escrow,
+                globalConfig,
+                matchmaker: config.matchmaker,
+            });
+        const transaction = await builder.preInstructions(input.preInstructions ?? []).transaction();
+        const latest = await this.connection.getLatestBlockhash(this.commitment);
+        transaction.recentBlockhash = latest.blockhash;
+        transaction.lastValidBlockHeight = latest.lastValidBlockHeight;
+        const payer = input.session?.publicKey ?? wallet.publicKey;
+        transaction.feePayer = payer;
+        transaction.signatures = [
+            { publicKey: payer, signature: null },
+            { publicKey: config.matchmaker, signature: null },
+        ];
+        return { transaction, payer, matchmaker: config.matchmaker };
+    }
+    async applyCosignature(transaction, signer, signatureBase64) {
+        const index = transaction.signatures.findIndex((entry) => entry.publicKey.equals(signer));
+        if (index < 0)
+            throw new SwarmClientError({ code: "TRANSACTION_MISMATCH", operation: "solana.applyCosignature", message: "Cosigner is not a required signer" });
+        transaction.signatures[index] = { publicKey: signer, signature: Buffer.from(signatureBase64, "base64") };
+        return transaction;
+    }
+    messageBase64(transaction) {
+        return Buffer.from(transaction.serializeMessage()).toString("base64");
+    }
+    async signBroadcastAndConfirm(transaction, session) {
+        const wallet = this.requireWallet();
+        let signed;
+        if (session) {
+            transaction.partialSign(session);
+            signed = transaction;
+        }
+        else {
+            signed = await wallet.signTransaction(transaction);
+        }
+        const signature = await this.connection.sendRawTransaction(signed.serialize());
+        await this.connection.confirmTransaction(signature, this.commitment);
+        return signature;
+    }
+    async commitGuess(commitment, game, session) {
+        const wallet = this.requireWallet();
+        if (session)
+            return this.sessionProgram(session).methods.commitGuessSession(commitment).accountsPartial({ player: wallet.publicKey, sessionAuthority: playerSessionPda(wallet.publicKey, session.publicKey)[0], game }).rpc();
+        return this.program(wallet).methods.commitGuess(commitment).accountsPartial({ game }).rpc();
+    }
+    async revealGuess(r, rMatchup, accounts, session) {
+        const wallet = this.requireWallet();
+        if (session)
+            return this.sessionProgram(session).methods.revealGuessSession(r, rMatchup).accountsPartial({ ...accounts, player: wallet.publicKey, sessionAuthority: playerSessionPda(wallet.publicKey, session.publicKey)[0] }).rpc();
+        return this.program(wallet).methods.revealGuess(r, rMatchup).accountsPartial(accounts).rpc();
+    }
+    async closeGame(game, session) {
+        const wallet = this.requireWallet();
+        if (session)
+            return this.sessionProgram(session).methods.closeGame().accountsPartial({ game, caller: session.publicKey }).rpc();
+        return this.program(wallet).methods.closeGame().accountsPartial({ game }).rpc();
+    }
+    async resolveTimeout(gameId, session) {
+        const wallet = this.requireWallet();
+        const program = session ? this.sessionProgram(session) : this.program(wallet);
+        const gameKey = gamePda(gameId)[0];
+        const game = await program.account.game.fetch(gameKey);
+        const config = await this.fetchGlobalConfig();
+        const tournamentId = BigInt(game.tournamentId.toString());
+        return program.methods.resolveTimeout().accountsPartial({
+            game: gameKey,
+            p1Profile: playerProfilePda(tournamentId, game.playerOne)[0],
+            p2Profile: playerProfilePda(tournamentId, game.playerTwo)[0],
+            tournament: tournamentPda(tournamentId)[0],
+            globalConfig: globalConfigPda()[0],
+            treasury: config.treasury,
+            playerOneWallet: game.playerOne,
+            playerTwoWallet: game.playerTwo,
+            caller: session?.publicKey ?? wallet.publicKey,
+        }).rpc();
+    }
+    async closeSessionByDelegate(session, player) {
+        return this.sessionProgram(session).methods.closeSessionByDelegate().accountsPartial({
+            sessionAuthority: playerSessionPda(player, session.publicKey)[0],
+            sessionSigner: session.publicKey,
+        }).rpc();
+    }
+    deriveAddresses(gameId, player) {
+        return {
+            globalConfig: globalConfigPda()[0],
+            gameCounter: gameCounterPda()[0],
+            game: gamePda(gameId)[0],
+            tournament: tournamentPda(this.tournamentId)[0],
+            playerProfile: playerProfilePda(this.tournamentId, player)[0],
+            escrow: escrowPda(this.tournamentId, player)[0],
+        };
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,19 @@
+export type SwarmClientErrorCode = "INVALID_ARGUMENT" | "INVALID_RESPONSE" | "NETWORK_ERROR" | "HTTP_ERROR" | "TIMEOUT" | "TRANSACTION_MISMATCH" | "TRANSACTION_FAILED" | "STORAGE_ERROR" | "WEBSOCKET_ERROR";
+export interface SwarmClientErrorOptions {
+    code: SwarmClientErrorCode;
+    operation: string;
+    message: string;
+    retryable?: boolean;
+    cause?: unknown;
+    status?: number;
+}
+/** Stable error boundary shared by every headless client entrypoint. */
+export declare class SwarmClientError extends Error {
+    readonly code: SwarmClientErrorCode;
+    readonly operation: string;
+    readonly retryable: boolean;
+    readonly cause?: unknown;
+    readonly status?: number;
+    constructor(options: SwarmClientErrorOptions);
+}
+export declare function errorMessage(error: unknown, fallback: string): string;

package/dist/errors.js

@@ -0,0 +1,20 @@
+/** Stable error boundary shared by every headless client entrypoint. */
+export class SwarmClientError extends Error {
+    code;
+    operation;
+    retryable;
+    cause;
+    status;
+    constructor(options) {
+        super(options.message);
+        this.name = "SwarmClientError";
+        this.code = options.code;
+        this.operation = options.operation;
+        this.retryable = options.retryable ?? false;
+        this.cause = options.cause;
+        this.status = options.status;
+    }
+}
+export function errorMessage(error, fallback) {
+    return error instanceof Error && error.message ? error.message : fallback;
+}

package/dist/http.d.ts

@@ -0,0 +1,21 @@
+export type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+export interface HttpClientOptions {
+    baseUrl: string;
+    fetch?: FetchLike;
+    network?: string;
+    getToken?: () => string | null | undefined;
+}
+export declare class HttpClient {
+    readonly baseUrl: string;
+    readonly network?: string;
+    private readonly fetchImpl;
+    private readonly getToken?;
+    constructor(options: HttpClientOptions);
+    withNetwork(path: string): string;
+    request<T>(path: string, init?: RequestInit & {
+        token?: string | null;
+    }): Promise<T>;
+    get<T>(path: string, token?: string | null): Promise<T>;
+    post<T>(path: string, body?: unknown, token?: string | null): Promise<T>;
+    patch<T>(path: string, body?: unknown, token?: string | null): Promise<T>;
+}

package/dist/http.js

@@ -0,0 +1,101 @@
+import { SwarmClientError, errorMessage } from "./errors.js";
+export class HttpClient {
+    baseUrl;
+    network;
+    fetchImpl;
+    getToken;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/$/, "");
+        this.network = options.network;
+        const candidate = options.fetch ?? globalThis.fetch;
+        if (!candidate)
+            throw new SwarmClientError({
+                code: "INVALID_ARGUMENT",
+                operation: "http.constructor",
+                message: "A fetch implementation is required",
+            });
+        this.fetchImpl = candidate.bind(globalThis);
+        this.getToken = options.getToken;
+    }
+    withNetwork(path) {
+        if (!this.network || this.network === "mainnet")
+            return path;
+        const separator = path.includes("?") ? "&" : "?";
+        return `${path}${separator}network=${encodeURIComponent(this.network)}`;
+    }
+    async request(path, init = {}) {
+        const operation = `${init.method ?? "GET"} ${path}`;
+        const token = init.token ?? this.getToken?.();
+        const headers = {
+            "Content-Type": "application/json",
+            ...init.headers,
+        };
+        if (token)
+            headers.Authorization = `Bearer ${token}`;
+        let response;
+        try {
+            response = await this.fetchImpl(`${this.baseUrl}${this.withNetwork(path)}`, {
+                ...init,
+                headers,
+            });
+        }
+        catch (cause) {
+            throw new SwarmClientError({
+                code: "NETWORK_ERROR",
+                operation,
+                message: errorMessage(cause, "Network request failed"),
+                retryable: true,
+                cause,
+            });
+        }
+        if (!response.ok) {
+            const raw = await response.text().catch(() => "");
+            let message = `HTTP ${response.status}`;
+            try {
+                const body = JSON.parse(raw);
+                message = body.message ?? body.error ?? message;
+            }
+            catch {
+                if (raw.trim())
+                    message = raw.slice(0, 500);
+            }
+            throw new SwarmClientError({
+                code: "HTTP_ERROR",
+                operation,
+                message,
+                retryable: response.status === 408 || response.status === 429 || response.status >= 500,
+                status: response.status,
+            });
+        }
+        if (response.status === 204)
+            return undefined;
+        try {
+            return (await response.json());
+        }
+        catch (cause) {
+            throw new SwarmClientError({
+                code: "INVALID_RESPONSE",
+                operation,
+                message: "Response was not valid JSON",
+                cause,
+            });
+        }
+    }
+    get(path, token) {
+        return this.request(path, { method: "GET", token });
+    }
+    post(path, body, token) {
+        return this.request(path, {
+            method: "POST",
+            body: body === undefined ? undefined : JSON.stringify(body),
+            token,
+        });
+    }
+    patch(path, body, token) {
+        return this.request(path, {
+            method: "PATCH",
+            body: body === undefined ? undefined : JSON.stringify(body),
+            token,
+        });
+    }
+}

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 /** The unified client package version. Functional APIs live in typed subpaths. */
-export declare const CLIENT_VERSION: "0.1.0";
+export declare const CLIENT_VERSION: "0.2.0";
 export declare const CLIENT_MANIFEST_SCHEMA: "swarm.client-manifest/v1";
+export { SwarmClientError } from "./errors.js";
+export type { SwarmClientErrorCode, SwarmClientErrorOptions } from "./errors.js";

package/dist/index.js

@@ -1,3 +1,4 @@
 /** The unified client package version. Functional APIs live in typed subpaths. */
-export const CLIENT_VERSION = "0.1.0";
+export const CLIENT_VERSION = "0.2.0";
 export const CLIENT_MANIFEST_SCHEMA = "swarm.client-manifest/v1";
+export { SwarmClientError } from "./errors.js";