pog-mcp 0.1.0

package/dist/client.js

@@ -0,0 +1,728 @@
+/**
+ * client — typed HTTP access to the Proof of Goal API, with SIWS handled here.
+ *
+ * The whole point of this layer is that `login()` is one call. The real flow is
+ * four round-trips and an ed25519 signature:
+ *
+ *   1. GET  /api/auth/nonce?wallet=…            → single-use nonce
+ *   2. GET  /api/auth/message?wallet=…&nonce=…  → the exact text to sign
+ *   3. sign it locally
+ *   4. POST /api/auth/signin                    → bearer session
+ *
+ * Step 2 matters: the server builds the SIWS text (domain, URI, statement) and
+ * checks the parsed result on the way back in. Rebuilding that string here would
+ * work right up until SIWS_DOMAIN changes on a deploy and every login started
+ * failing signature verification for no visible reason. Ask, don't guess.
+ */
+import { signMessage } from './wallet.js';
+/**
+ * Largest page GET /api/leaderboard will serve (its MAX_LIMIT). Asking for it
+ * makes truncation detectable: a full page means there may be more.
+ */
+export const LEADERBOARD_MAX_LIMIT = 500;
+/** Tolerance for a server clock running ahead of ours. */
+const CLOCK_SKEW_MS = 2 * 60 * 1000;
+/**
+ * How long the API keeps a nonce (siws.ts NONCE_TTL_MS). A message issued
+ * before this is already dead on arrival, so signing it only hands out a
+ * signature for nothing.
+ */
+const NONCE_TTL_MS = 10 * 60 * 1000;
+/** Public deployment. Override with POG_API_URL to point at a local server. */
+export const DEFAULT_API_URL = 'https://api.pog.soccer';
+export class ApiError extends Error {
+    status;
+    path;
+    /**
+     * The `teamId` some rejections carry alongside the error. POST /api/teams
+     * answers 409 `{error:"team_exists", teamId}` — the id is the whole point of
+     * that response, so it must not be flattened away into the message.
+     */
+    teamId;
+    /**
+     * When to try again, in seconds — the whole point of a 429.
+     *
+     * The server always says this, twice over: `retry-after` on the response and,
+     * for the playoff cooldown, `retryAfterMs`/`nextMatchAt` in the body. Both
+     * used to be dropped on the floor, so an agent that woke a minute early got a
+     * sentence to read instead of a time to sleep until, and had to spend another
+     * call working out what the rejection already contained.
+     */
+    retryAfterSeconds;
+    /** The exact instant the next attempt is allowed, when the server names one. */
+    retryAt;
+    /** Requests left in this window, so an agent can PACE instead of only backing off. */
+    remaining;
+    constructor(status, path, message, teamId, extra) {
+        super(message);
+        this.status = status;
+        this.path = path;
+        this.name = 'ApiError';
+        if (teamId !== undefined)
+            this.teamId = teamId;
+        if (extra?.retryAfterSeconds !== undefined)
+            this.retryAfterSeconds = extra.retryAfterSeconds;
+        if (extra?.retryAt !== undefined)
+            this.retryAt = extra.retryAt;
+        if (extra?.remaining !== undefined)
+            this.remaining = extra.remaining;
+    }
+}
+function parseSiws(message) {
+    const lines = message.split('\n');
+    const domainLine = lines[0] ?? '';
+    const address = (lines[1] ?? '').trim();
+    const m = /^(\S+) wants you to sign in with your Solana account:$/.exec(domainLine.trim());
+    if (!m?.[1] || address.length === 0)
+        return null;
+    // Read the labelled fields exactly the way the server's own parser does
+    // (packages/api/src/lib/siws.ts): from line 5 on, splitting at the first
+    // ": ". Two parsers with different rules over the same bytes is the whole
+    // attack — the server's loop overwrites, so it takes the LAST occurrence,
+    // while a `.find()` here took the FIRST. A benign Nonce followed by an
+    // attacker's duplicate would then pass this check and authorise something
+    // else entirely.
+    //
+    // Duplicates are refused rather than resolved. Agreeing on "last wins" would
+    // close today's gap and reopen it the moment either parser changed; a message
+    // that needs a tie-break rule is not one we should be signing.
+    const fields = new Map();
+    for (let i = 5; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        const colon = line.indexOf(': ');
+        if (colon === -1)
+            continue;
+        const key = line.slice(0, colon).trim();
+        if (fields.has(key))
+            return null;
+        fields.set(key, line.slice(colon + 2).trim());
+    }
+    return {
+        domain: m[1],
+        address,
+        uri: fields.get('URI') ?? null,
+        version: fields.get('Version') ?? null,
+        chainId: fields.get('Chain ID') ?? null,
+        nonce: fields.get('Nonce') ?? null,
+        issuedAt: fields.get('Issued At') ?? null,
+        expirationTime: fields.get('Expiration Time') ?? null,
+    };
+}
+/**
+ * Hosts this client will sign a sign-in for, given the API it was pointed at.
+ *
+ * Exactly two: the API host, and the same host with a leading `api.` removed —
+ * because api.pog.soccer serves sign-ins for pog.soccer. That is a precise rule.
+ * The previous version compared the last two labels, which called evil.co.uk and
+ * pog.co.uk the same site and would have signed for either.
+ *
+ * `POG_SIWS_DOMAIN` overrides it outright for deployments that split differently.
+ */
+/** Loopback hosts — an attacker cannot be on the other end of these. */
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);
+/**
+ * Hosts this client will sign a sign-in for.
+ *
+ * The anchor is BUILT IN, not derived from POG_API_URL. Deriving it from the
+ * URL under suspicion was the flaw: point the client at evil.example and it
+ * would serve a message for evil.example, satisfy every field check, and get a
+ * signature from the persistent wallet. Thorough validation of a self-consistent
+ * forgery is still a forgery — the check has to start from something the
+ * attacker does not control.
+ *
+ * So: the known Proof of Goal domains by default; loopback automatically,
+ * because a local dev server is not a phishing target; anything else only with
+ * an explicit POG_SIWS_DOMAIN. A mistyped host therefore fails closed and says
+ * what to set.
+ *
+ * The ORIGIN has to clear that bar too, not just the domain in the message.
+ * Returning the production hosts for an arbitrary API URL left one attack whole:
+ * a hostile HTTPS host does not have to forge anything — it proxies the nonce
+ * and message straight from api.pog.soccer, hands back the genuine pog.soccer
+ * text, and every field check passes because every field is real. Then it keeps
+ * the signature and the session. HTTPS authenticates the relay, not the service
+ * behind it. So an origin we do not know is refused before a message is fetched.
+ */
+export function expectedSiwsHosts(apiOrigin, env = process.env) {
+    // HOSTNAME, not host: the port is not part of the identity being checked, and
+    // including it broke the documented local setup outright —
+    // POG_API_URL=http://localhost:3001 expects "localhost:3001" while the server
+    // signs for "localhost".
+    const host = hostnameOf(apiOrigin);
+    // Every loopback spelling is the same machine, and a dev server is not a
+    // phishing target.
+    const loopback = LOOPBACK.has(host);
+    // WHICH HOST WE TALK TO IS ITS OWN QUESTION, asked first.
+    //
+    // POG_SIWS_DOMAIN used to skip this check on the reasoning that "an explicit
+    // override IS the authorization". It is not — it authorizes the DOMAIN a
+    // message may name, and says nothing about where the message came from. With
+    // it set, a typo'd or tampered POG_API_URL could relay the real deployment's
+    // nonce and message, pass every field check (the fields are genuine), and keep
+    // the signature and session. The two halves have to be authorized separately.
+    const allowed = expectedApiHosts(env);
+    if (!loopback && !allowed.includes(host)) {
+        throw new Error(`Refusing to sign in through ${host}. This client only talks to ` +
+            `${allowed.join(', ')} or a local server — an unknown host can relay the real sign-in ` +
+            'message unchanged and keep the signature it collects, which no check on the message ' +
+            'can detect. Set POG_SIWS_DOMAIN to the domain your deployment signs for (its API may ' +
+            'then live on that host or on api.<domain>), or POG_API_HOST if the API is somewhere ' +
+            'else entirely.');
+    }
+    const override = env['POG_SIWS_DOMAIN']?.trim();
+    if (override)
+        return [hostnameOf(override)];
+    // The API defaults SIWS_DOMAIN to "localhost" regardless of which name you
+    // dialled it by, so returning only the dialled one made
+    // POG_API_URL=http://127.0.0.1:3001 refuse a perfectly good local login —
+    // while the README promised both forms needed no override.
+    if (loopback)
+        return [...LOOPBACK];
+    return TRUSTED_SIWS_HOSTS;
+}
+/**
+ * Hosts this client will send a wallet address to.
+ *
+ * Separate from the domains a MESSAGE may name, because they answer different
+ * questions and a deployment can legitimately split them: the product's own API
+ * lives at api.pog.soccer and signs for pog.soccer. So an operator who declares
+ * their domain gets that same relation for free — the domain itself, or `api.`
+ * in front of it — and POG_API_HOST is there for the topologies that are neither.
+ */
+export function expectedApiHosts(env = process.env) {
+    const explicit = env['POG_API_HOST']?.trim();
+    if (explicit)
+        return [hostnameOf(explicit)];
+    const domain = env['POG_SIWS_DOMAIN']?.trim();
+    if (domain) {
+        const d = hostnameOf(domain);
+        return [d, `api.${d}`];
+    }
+    return TRUSTED_SIWS_HOSTS;
+}
+/**
+ * The product's own domains, derived from DEFAULT_API_URL so the two cannot
+ * drift: the API host and the site it signs people in to.
+ */
+export const TRUSTED_SIWS_HOSTS = (() => {
+    const api = new URL(DEFAULT_API_URL).hostname.toLowerCase();
+    return api.startsWith('api.') ? [api, api.slice(4)] : [api];
+})();
+/**
+ * The hostname of an origin, a bare host, or a host:port — lowercased, port
+ * dropped. Accepts all three because the SIWS `domain` field is an RFC 3986
+ * authority and servers differ on whether they include the port.
+ */
+function hostnameOf(value) {
+    const trimmed = value.trim().toLowerCase();
+    // Only parse as a URL when it actually carries a scheme. `new URL` accepts
+    // "localhost:3001" as scheme "localhost:" with path "3001" and reports an
+    // EMPTY hostname — which would have compared equal for every such input.
+    if (/^[a-z][a-z0-9+.-]*:\/\//.test(trimmed)) {
+        try {
+            return new URL(trimmed).hostname;
+        }
+        catch {
+            // Fall through and treat it as an authority.
+        }
+    }
+    // A bare authority: strip any :port. IPv6 literals keep their brackets, which
+    // is what URL.hostname gives too.
+    if (trimmed.startsWith('['))
+        return /^\[[^\]]*\]/.exec(trimmed)?.[0] ?? trimmed;
+    return trimmed.split(':')[0] ?? trimmed;
+}
+/**
+ * Refuse to run the sign-in flow over plaintext to a remote host.
+ *
+ * Loopback is exempt: there is no path for anyone to sit on.
+ */
+export function assertTransportIsSafe(origin) {
+    let url;
+    try {
+        url = new URL(origin);
+    }
+    catch {
+        throw new Error(`Refusing to sign in: ${origin} is not a valid URL.`);
+    }
+    if (url.protocol === 'https:')
+        return;
+    if (LOOPBACK.has(url.hostname.toLowerCase()))
+        return;
+    throw new Error(`Refusing to sign in over ${url.protocol}// to ${url.host}. Anyone on the path could relay ` +
+        'a genuine sign-in message and keep the signature and session it produces. Use https, or ' +
+        'point POG_API_URL at localhost for local work.');
+}
+/**
+ * The site host this product signs people IN TO, as opposed to the API host.
+ */
+const TRUSTED_SITE_HOST = TRUSTED_SIWS_HOSTS[TRUSTED_SIWS_HOSTS.length - 1] ?? new URL(DEFAULT_API_URL).hostname;
+/**
+ * The exact `domain` a message may name, or `null` to check only the host.
+ *
+ * Loopback stays host-only: the local API signs "localhost" whichever spelling
+ * and port you dialled it by, and pinning that would refuse a perfectly good
+ * local login — the same exemption the host and URI checks already make.
+ */
+export function expectedSiwsDomain(apiOrigin, env = process.env) {
+    const override = env['POG_SIWS_DOMAIN']?.trim();
+    if (override)
+        return override;
+    if (LOOPBACK.has(hostnameOf(apiOrigin)))
+        return null;
+    return TRUSTED_SITE_HOST;
+}
+/**
+ * The exact URI(s) a message may name, or `null` to check only the host.
+ *
+ * The API builds this as `https://{SIWS_DOMAIN}` unless SIWS_URI overrides it,
+ * so the expected value is derivable and worth pinning: a compromised endpoint
+ * that can only vary scheme and path still gets a signature over a resource the
+ * operator never agreed to.
+ *
+ * Loopback stays host-only. Ports and schemes vary freely on a dev box, it is
+ * not a phishing target — the same exemption the host check already makes — and
+ * pinning it would only teach people to set an override they do not need.
+ */
+export function expectedSiwsUris(apiOrigin, env = process.env) {
+    const override = env['POG_SIWS_URI']?.trim();
+    if (override) {
+        try {
+            return [normalizeUri(new URL(override))];
+        }
+        catch {
+            throw new Error(`POG_SIWS_URI is not a URL: ${override}`);
+        }
+    }
+    if (LOOPBACK.has(hostnameOf(apiOrigin)))
+        return null;
+    // The AUTHORITY, verbatim — the API builds `https://${SIWS_DOMAIN}`, port and
+    // all. Reducing it with hostnameOf() made a deployment on
+    // POG_SIWS_DOMAIN=staging.example:8443 expect https://staging.example, so the
+    // exact domain check passed and the exact URI check then refused every single
+    // login. Two checks derived from one value have to derive it the same way.
+    const authority = env['POG_SIWS_DOMAIN']?.trim() || TRUSTED_SITE_HOST;
+    try {
+        return [normalizeUri(new URL(`https://${authority}`))];
+    }
+    catch {
+        throw new Error(`POG_SIWS_DOMAIN is not an authority a URI can be built from: ${authority}. ` +
+            'Set POG_SIWS_URI to the exact URI your deployment signs for.');
+    }
+}
+/**
+ * Compare-ready form: scheme and host lowercased, an empty path and a bare "/"
+ * treated as the same thing. Path, query and fragment keep their case — those
+ * are case-sensitive, and folding them would let two different resources match.
+ */
+function normalizeUri(url) {
+    const path = url.pathname === '/' ? '' : url.pathname.replace(/\/+$/, '');
+    return `${url.protocol}//${url.host.toLowerCase()}${path}${url.search}${url.hash}`;
+}
+/**
+ * The one chain id this client will sign a sign-in for.
+ *
+ * The API binds auth to a single chain (SOLANA_DEVNET_CHAIN_ID today), so this
+ * is an exact match, not a family. Moving the deployment to another chain means
+ * setting POG_SIWS_CHAIN — logins fail closed until then, and the refusal names
+ * both chains so the cause is obvious.
+ */
+export function expectedSiwsChain(env = process.env) {
+    return env['POG_SIWS_CHAIN']?.trim() ?? 'solana:devnet';
+}
+/**
+ * Refuse to sign anything that is not a login to THIS service, for THIS wallet,
+ * with the nonce we just asked for.
+ *
+ * Every field is bound, not sampled. A message we cannot fully parse is a
+ * refusal: there is no safe way to sign text we could not read, and the only
+ * party who benefits from a lenient parser here is whoever served the message.
+ */
+export function assertSiwsMatchesRequest(message, expected, env = process.env) {
+    const hosts = expectedSiwsHosts(expected.origin, env);
+    const fail = (why) => {
+        throw new Error(`Refusing to sign: ${why}. The server at ${expected.origin} returned a sign-in message ` +
+            `that is not a login to ${hosts.join(' or ')} for this wallet. Check POG_API_URL — and ` +
+            'if you are deliberately pointing at a staging or self-hosted deployment, set ' +
+            'POG_SIWS_DOMAIN to the domain it signs people in to.');
+    };
+    // Plaintext to anything but loopback is not a transport detail here.
+    //
+    // An on-path attacker can proxy the nonce request to the real API, hand back
+    // the genuine trusted message — which passes every check below, because it IS
+    // genuine — then take the signature and the sign-in response, and walk away
+    // with a bearer session for the persistent wallet. Validating the message
+    // cannot help when the message is authentic and the channel is not.
+    assertTransportIsSafe(expected.origin);
+    const siws = parseSiws(message);
+    if (siws === null)
+        return fail('the message is not a SIWS sign-in request');
+    if (!hosts.includes(hostnameOf(siws.domain))) {
+        fail(`it signs you in to "${siws.domain}"`);
+    }
+    // And the domain WHOLE, for the same reason as the URI below: the API compares
+    // this field to SIWS_DOMAIN exactly, so `pog.soccer:8443` or
+    // `https://pog.soccer` is an authority it will reject — after the persistent
+    // wallet has signed an authorization naming it. hostnameOf() exists to make
+    // the host check port-insensitive, not to make the field itself loose.
+    const expectedDomains = expectedSiwsDomain(expected.origin, env);
+    if (expectedDomains !== null && siws.domain !== expectedDomains) {
+        fail(`it signs you in to "${String(siws.domain)}", not "${expectedDomains}" — set ` +
+            'POG_SIWS_DOMAIN if that is genuinely what your deployment signs for');
+    }
+    if (siws.address !== expected.walletAddress) {
+        fail(`it names wallet "${siws.address}", not ours`);
+    }
+    if (siws.nonce !== expected.nonce) {
+        fail('the nonce is not the one we requested');
+    }
+    // A signature is scoped to a chain, and the API binds authentication to ONE
+    // chain id. Accepting any solana:* left the door open to a signature that
+    // authorises a different chain context than the one intended.
+    const wantChain = expectedSiwsChain(env);
+    if (siws.chainId !== wantChain) {
+        fail(`it is for chain "${String(siws.chainId)}", not ${wantChain}`);
+    }
+    if (siws.uri === null)
+        return fail('it has no URI');
+    const expectedUris = expectedSiwsUris(expected.origin, env);
+    let uri;
+    try {
+        uri = new URL(siws.uri);
+    }
+    catch {
+        return fail(`its URI is not a URL (${siws.uri})`);
+    }
+    // The exact URI override names its own host, and that is the whole point of
+    // it: a deployment can serve the app at app.example.com while signing for
+    // example.com. Checking the URI's host against the DOMAIN list refused the
+    // very configuration POG_SIWS_URI exists to express — two checks of mine
+    // contradicting each other, with the stricter one winning silently.
+    //
+    // Only this check widens. The API-origin allowlist and the domain comparison
+    // are untouched: an override says where the app lives, not who may serve the
+    // message or what authority it may name.
+    const uriHosts = expectedUris === null ? hosts : [...hosts, ...expectedUris.map((u) => hostnameOf(u))];
+    if (!uriHosts.includes(uri.hostname.toLowerCase())) {
+        fail(`its URI points at ${uri.hostname.toLowerCase()}`);
+    }
+    // The WHOLE URI, not just its host. The API binds this field to one exact
+    // string, so `http://pog.soccer/other-app` is a resource it will reject —
+    // afterwards, with the signature over a different scheme and path already
+    // made by a persistent wallet. Same reason every other field is bound here:
+    // the artifact is the thing not to produce.
+    if (expectedUris !== null && !expectedUris.includes(normalizeUri(uri))) {
+        fail(`its URI is ${siws.uri}, not ${expectedUris.join(' or ')} — set POG_SIWS_URI if that is ` +
+            'genuinely what your deployment signs for');
+    }
+    // Version is part of the signed bytes and decides how a verifier reads them.
+    // The API emits "1" and its validator does not reject anything else, so an
+    // unsupported version would be signed here and interpreted downstream by
+    // whatever rules that version implies.
+    if (siws.version !== '1')
+        fail(`its version is "${String(siws.version)}"`);
+    // Issued At bounds the other end of the window. Without it a message can
+    // claim to have been minted at any time; with a far-future one, `Expiration
+    // Time` stops meaning anything. Signed first, rejected by the API later — so
+    // the wallet has already produced the artifact.
+    if (siws.issuedAt === null)
+        fail('it has no issue time');
+    const issuedAt = Date.parse(siws.issuedAt);
+    if (Number.isNaN(issuedAt))
+        fail(`its issue time is unreadable (${siws.issuedAt})`);
+    if (issuedAt > Date.now() + CLOCK_SKEW_MS)
+        fail('it claims to have been issued in the future');
+    // And a lower bound. Only rejecting the future let a stale message through —
+    // the API refuses it afterwards for an expired nonce, but by then the wallet
+    // has already produced the signature, which is the thing worth not producing.
+    if (issuedAt < Date.now() - NONCE_TTL_MS - CLOCK_SKEW_MS) {
+        fail(`it was issued at ${siws.issuedAt}, too long ago to still be live`);
+    }
+    // NOTE: the statement line is deliberately not bound. For a headless signer
+    // it is not a security boundary the way domain/URI/nonce/chain are — nobody
+    // reads it — and pinning it would couple this client to server wording that
+    // may legitimately change.
+    //
+    // REQUIRED, not "checked if present". The API always emits a ten-minute
+    // expiry; a message without one is a signature with no time bound, and
+    // whoever collected it holds a reusable authorisation forever. Treating
+    // absence as "nothing to check" made omission the easiest way past the check.
+    if (siws.expirationTime === null)
+        fail('it has no expiration');
+    const expiresAt = Date.parse(siws.expirationTime);
+    if (Number.isNaN(expiresAt))
+        fail(`its expiration is unreadable (${siws.expirationTime})`);
+    if (expiresAt <= Date.now())
+        fail('it has already expired');
+    if (expiresAt <= issuedAt)
+        fail('it expires before it was issued');
+    // Upper bound too. Requiring an expiry without capping it still let a
+    // compromised endpoint ask for a signature valid for years — an authorisation
+    // artifact with a lifetime of its own choosing. The real message lives for the
+    // nonce TTL, so anything longer is not this service's.
+    if (expiresAt > issuedAt + NONCE_TTL_MS + CLOCK_SKEW_MS) {
+        fail(`it stays valid until ${siws.expirationTime}, far longer than a sign-in should`);
+    }
+}
+export class PogClient {
+    baseUrl;
+    fetchImpl;
+    timeoutMs;
+    session = null;
+    constructor(baseUrl = process.env['POG_API_URL'] ?? DEFAULT_API_URL, fetchImpl = fetch, 
+    /** Per-request ceiling. Generous: a cup-day bracket is a large response. */
+    timeoutMs = Number(process.env['POG_API_TIMEOUT_MS'] ?? 30_000)) {
+        this.baseUrl = baseUrl;
+        this.fetchImpl = fetchImpl;
+        this.timeoutMs = timeoutMs;
+        this.baseUrl = this.baseUrl.replace(/\/+$/, '');
+    }
+    /**
+     * The active session, or null when there is none or it has expired.
+     *
+     * Expiry is checked on read rather than trusted from when it was issued: this
+     * process can outlive a session, and returning a stale one made `whoami`
+     * report "signed in" while every authenticated call 401'd.
+     */
+    currentSession() {
+        if (this.session === null)
+            return null;
+        const expiresAt = Date.parse(this.session.expiresAt);
+        if (!Number.isNaN(expiresAt) && expiresAt <= Date.now()) {
+            this.session = null;
+            return null;
+        }
+        return this.session;
+    }
+    async request(path, init = {}) {
+        const { auth, headers, ...rest } = init;
+        const merged = {
+            accept: 'application/json',
+            ...(rest.body ? { 'content-type': 'application/json' } : {}),
+            ...(headers ?? {}),
+        };
+        const session = this.currentSession();
+        if (auth && !session) {
+            throw new ApiError(401, path, 'Not signed in (or the session expired) — call login first');
+        }
+        // Send the token on PUBLIC reads too, whenever we hold one.
+        //
+        // The API rate-limits by wallet when a request is authenticated and by IP
+        // when it is not (lib/rate-key.ts). Leaving reads anonymous would put every
+        // agent on one machine back into a single shared IP bucket for exactly the
+        // calls they make most — leaderboard, cup, squad, match. The routes ignore
+        // the header; only the limiter reads it.
+        if (session)
+            merged['authorization'] = `Bearer ${session.sessionId}`;
+        // Bound every request. A server that accepts the connection and then stops
+        // answering — an unhealthy rollout, a half-open path — would otherwise leave
+        // the tool call pending forever, and an agent with no error and no result
+        // cannot continue its loop or report anything useful.
+        const timeout = AbortSignal.timeout(this.timeoutMs);
+        const signal = rest.signal == null
+            ? timeout
+            : // Preserve a caller's own cancellation; whichever fires first wins.
+                AbortSignal.any([rest.signal, timeout]);
+        let res;
+        try {
+            res = await this.fetchImpl(`${this.baseUrl}${path}`, { ...rest, headers: merged, signal });
+        }
+        catch (err) {
+            if (timeout.aborted) {
+                throw new ApiError(504, path, `No response from ${this.baseUrl} within ${String(this.timeoutMs)}ms`);
+            }
+            throw err;
+        }
+        const text = await res.text();
+        let body = null;
+        try {
+            body = text ? JSON.parse(text) : null;
+        }
+        catch {
+            body = text;
+        }
+        if (!res.ok) {
+            // Surface everything the server said, in the order that carries meaning.
+            //
+            // Fastify's schema layer answers `{ error: "Bad Request", message: "body/
+            // players/0 must have required property 'pass'" }` — so preferring `error`
+            // throws away the only useful half and hands the agent something it cannot
+            // act on. The route's own validator instead answers `{ error: "...",
+            // details: [...] }` naming the rule that failed. Keep whichever parts exist.
+            const b = body;
+            const parts = [b?.error, b?.message].filter((p) => typeof p === 'string' && p.length > 0);
+            // Drop the generic HTTP-status echo when a real explanation sits next to it.
+            const meaningful = parts.length > 1 ? parts.filter((p) => p !== res.statusText) : parts;
+            const detail = (meaningful.length ? meaningful.join(' — ') : null) ??
+                (typeof body === 'string' && body ? body : res.statusText);
+            // Keep the machine-readable half. The body's own figure wins over the
+            // header: the playoff cooldown reports the exact instant the next match is
+            // allowed, while `retry-after` only counts down the rate-limit window.
+            const header = (name) => typeof res.headers?.get === 'function' ? res.headers.get(name) : null;
+            const asNumber = (raw) => {
+                if (raw === null)
+                    return undefined;
+                const n = Number(raw);
+                return Number.isFinite(n) ? n : undefined;
+            };
+            const bodySeconds = typeof b?.retryAfterMs === 'number' ? Math.ceil(b.retryAfterMs / 1000) : undefined;
+            const extra = {
+                ...(bodySeconds ?? asNumber(header('retry-after'))) !== undefined
+                    ? { retryAfterSeconds: bodySeconds ?? asNumber(header('retry-after')) }
+                    : {},
+                ...(typeof b?.nextMatchAt === 'string' ? { retryAt: b.nextMatchAt } : {}),
+                ...(asNumber(header('x-ratelimit-remaining')) !== undefined
+                    ? { remaining: asNumber(header('x-ratelimit-remaining')) }
+                    : {}),
+            };
+            throw new ApiError(res.status, path, b?.details?.length ? `${detail}: ${JSON.stringify(b.details)}` : detail, b?.teamId, extra);
+        }
+        return body;
+    }
+    // -------------------------------------------------------------------------
+    // Auth
+    // -------------------------------------------------------------------------
+    /** Run the full SIWS handshake and hold the resulting bearer session. */
+    async login(mnemonic, walletAddress) {
+        // Decide whether this endpoint is one we will sign for BEFORE telling it
+        // which wallet is asking. Both checks run again inside
+        // assertSiwsMatchesRequest — that pass guards the message we were handed,
+        // this one guards the handshake, and an unknown host learns nothing.
+        const origin = new URL(this.baseUrl).origin;
+        assertTransportIsSafe(origin);
+        expectedSiwsHosts(origin);
+        const { nonce } = await this.request(`/api/auth/nonce?wallet=${encodeURIComponent(walletAddress)}`);
+        const { message } = await this.request(`/api/auth/message?wallet=${encodeURIComponent(walletAddress)}&nonce=${encodeURIComponent(nonce)}`);
+        // Never sign server text unread. Fetching the message is right — the server
+        // owns the exact wording — but signing it unconditionally turns this process
+        // into an oracle: point POG_API_URL at a typo'd host or a compromised
+        // staging box and it will hand back a valid, reusable signature over
+        // whatever that host wants, made with the persistent real wallet key.
+        assertSiwsMatchesRequest(message, { walletAddress, nonce, origin });
+        const signed = await this.request('/api/auth/signin', {
+            method: 'POST',
+            body: JSON.stringify({ message, signature: signMessage(mnemonic, message), walletAddress }),
+        });
+        this.session = signed;
+        return signed;
+    }
+    // -------------------------------------------------------------------------
+    // Read
+    // -------------------------------------------------------------------------
+    /**
+     * Liveness. Deliberately /healthz and not /api/ops/status — the ops routes are
+     * operator surface and answer 401 without OPS_API_KEY on any real deployment,
+     * so exposing them here would ship a tool that never works for a player.
+     */
+    health() {
+        return this.request('/healthz');
+    }
+    /** Whether the FA market is open on this deployment (public, ungated). */
+    marketStatus() {
+        return this.request('/api/market/status');
+    }
+    nations() {
+        return this.request('/api/nations');
+    }
+    myTeams() {
+        return this.request('/api/teams', { auth: true });
+    }
+    /**
+     * Everything about this manager in one authenticated call: squads, league
+     * rank, playoff entry and cooldown, finished-match history, next fixture,
+     * honours, career record.
+     *
+     * This is the endpoint that makes the game playable across sessions. Cups run
+     * daily and finish hours after they open, so an agent that only ever looks at
+     * what it did inside one session never sees its own results — and never has a
+     * reason to change the squad. The alternative is six separate calls the agent
+     * has to know to make and stitch together itself.
+     */
+    dashboard() {
+        return this.request('/api/dashboard/me', { auth: true });
+    }
+    /**
+     * A team's finished matches, newest first, up to `limit` (the API caps at 200).
+     *
+     * Lives under /api/playoff/ but is not playoff-only — it lists every completed
+     * match for the team, friendlies included. Needed because the dashboard's own
+     * `teamHistory` is capped at five rows, which is fewer than a single cup day
+     * produces.
+     */
+    teamHistory(teamId, limit) {
+        return this.request(`/api/playoff/${encodeURIComponent(teamId)}/history?limit=${String(limit)}`);
+    }
+    team(teamId) {
+        return this.request(`/api/teams/${encodeURIComponent(teamId)}`);
+    }
+    match(matchId) {
+        return this.request(`/api/matches/${encodeURIComponent(matchId)}`);
+    }
+    /**
+     * Cup SUMMARY only: status, champion, final score, match count. No fixtures —
+     * see `cupBracket` for those.
+     */
+    cup(date) {
+        return this.request(`/api/cups/${encodeURIComponent(date)}`);
+    }
+    /**
+     * The fixtures. A cup date maps to tournament id `wc-${date}`, and the bracket
+     * lives on the tournament, not the cup — /api/cups/:date returns a summary
+     * with a `matchCount` and no matches at all.
+     */
+    cupBracket(date) {
+        return this.request(`/api/tournaments/wc-${encodeURIComponent(date)}/bracket`);
+    }
+    /**
+     * The board's top `limit` rows. The API defaults to 100 and caps at
+     * MAX_LIMIT=500, so a request without an explicit limit silently truncates on
+     * any deployment with more managers than that — and `rows.length` is then the
+     * page size, not the population.
+     */
+    leaderboard(limit = LEADERBOARD_MAX_LIMIT) {
+        return this.request(`/api/leaderboard?limit=${String(limit)}`);
+    }
+    // -------------------------------------------------------------------------
+    // Write
+    // -------------------------------------------------------------------------
+    /**
+     * Play one ranked playoff match. Bodyless POST — the server picks the
+     * opponent from the ladder and creates the caller's ladder entry on first
+     * call, which is how a new squad enters the competitive season at all.
+     *
+     * No body and therefore no content-type header: sending
+     * `application/json` with an empty body is what earns a 415 here.
+     */
+    playPlayoff() {
+        return this.request('/api/playoff/play', { method: 'POST', auth: true });
+    }
+    createTeam(input) {
+        return this.request('/api/teams', { method: 'POST', auth: true, body: JSON.stringify(input) });
+    }
+    updateTeam(teamId, input) {
+        return this.request(`/api/teams/${encodeURIComponent(teamId)}`, {
+            method: 'PUT',
+            auth: true,
+            body: JSON.stringify(input),
+        });
+    }
+    /**
+     * Play a friendly. Team-id form only, on purpose: the server then reads both
+     * squads itself. The inline-squad form exists for engine callers and needs the
+     * engine's attribute names (dori/shoo/defe), which differ from the flat shape
+     * POST /api/teams takes — a trap worth not exposing to an agent.
+     *
+     * Authenticated, and the caller must OWN the home team: a friendly is a
+     * challenge you start with your squad against an arbitrary opponent. Without
+     * that gate anyone could fabricate results onto someone else's public career,
+     * so the route fails closed at 401 when no session is attached.
+     */
+    playFriendly(input) {
+        return this.request('/api/matches/friendly', {
+            method: 'POST',
+            auth: true,
+            body: JSON.stringify(input),
+        });
+    }
+}
+//# sourceMappingURL=client.js.map