@1ly/mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 1ly.store
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,330 @@
+# @1ly/mcp-server
+
+MCP server for [1ly.store](https://1ly.store) — Discover and pay for APIs with AI agents.
+
+## What is this?
+
+This MCP server enables AI agents (Claude, GPT, Cursor, etc.) to:
+
+1. **Search** for APIs and services on 1ly.store
+2. **Get details** about pricing, reviews, and usage
+3. **Call APIs** with automatic crypto payments (x402 protocol)
+4. **Leave reviews** after purchases
+5. **Create and manage API links** (Developer Mode + API key)
+
+## Quick Start (1 minute)
+
+Pick **one** of the following and paste it into your terminal.
+
+### Solana (mainnet)
+
+```bash
+ONELY_WALLET_TYPE=solana \
+ONELY_WALLET_KEY="$HOME/1ly-agent-wallet.json" \
+npx @1ly/mcp-server
+```
+
+### Base (mainnet)
+
+```bash
+ONELY_WALLET_TYPE=evm \
+ONELY_WALLET_KEY="$HOME/.1ly-base-private-key" \
+npx @1ly/mcp-server
+```
+
+Optional safety limits:
+
+```bash
+ONELY_BUDGET_PER_CALL=1.00
+ONELY_BUDGET_DAILY=50.00
+```
+
+### Developer Mode (create/manage API links)
+
+```bash
+ONELY_API_KEY="1ly_live_..." \
+npx @1ly/mcp-server
+```
+
+## Get an API Key (Developer Mode)
+
+1. Sign in to 1ly store: `https://1ly.store`
+2. Open **Settings** (profile dropdown → Settings)
+3. Enable **Developer Mode**
+4. Open **Developer Settings** and click **Create API Key**
+5. Copy the key (shown once)
+
+Keys look like:
+```
+1ly_live_xxxxxxxx...
+```
+
+## How API keys are used
+
+- **For MCP tools**: set `ONELY_API_KEY` in your MCP config or environment.  
+  The MCP server attaches it as `Authorization: Bearer <key>` automatically.
+- **For direct API calls**: include the header yourself:
+
+```http
+Authorization: Bearer 1ly_live_...
+```
+
+## Install (Claude Desktop)
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "1ly": {
+      "command": "npx",
+      "args": ["@1ly/mcp-server"],
+      "env": {
+        "ONELY_WALLET_TYPE": "solana",
+        "ONELY_WALLET_KEY": "/path/to/solana-wallet.json",
+        "ONELY_BUDGET_PER_CALL": "1.00",
+        "ONELY_BUDGET_DAILY": "50.00"
+      }
+    }
+  }
+}
+```
+
+### Developer Mode (API key only)
+
+```json
+{
+  "mcpServers": {
+    "1ly": {
+      "command": "npx",
+      "args": ["@1ly/mcp-server"],
+      "env": {
+        "ONELY_API_KEY": "1ly_live_..."
+      }
+    }
+  }
+}
+```
+
+## Install (Cursor)
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "servers": {
+    "1ly": {
+      "command": "npx @1ly/mcp-server",
+      "env": {
+        "ONELY_WALLET_TYPE": "solana",
+        "ONELY_WALLET_KEY": "/path/to/solana-wallet.json",
+        "ONELY_BUDGET_PER_CALL": "1.00",
+        "ONELY_BUDGET_DAILY": "50.00"
+      }
+    }
+  }
+}
+```
+
+### Developer Mode (API key only)
+
+```json
+{
+  "servers": {
+    "1ly": {
+      "command": "npx @1ly/mcp-server",
+      "env": {
+        "ONELY_API_KEY": "1ly_live_..."
+      }
+    }
+  }
+}
+```
+
+## Verify it works (recommended)
+
+Run a quick self-test:
+
+```bash
+ONELY_WALLET_TYPE=solana \
+ONELY_WALLET_KEY="$HOME/1ly-agent-wallet.json" \
+npx @1ly/mcp-server --self-test
+```
+
+## What agents can do
+
+Typical flow:
+
+1. `1ly_search` → find an API
+2. `1ly_get_details` → confirm price + supported networks
+3. `1ly_call` → auto‑pay with x402 v2 and return the API response
+4. `1ly_review` → optional review using the `_1ly` metadata
+5. `1ly_create_link` → create a paid or free API link (Developer Mode)
+
+## Tools
+
+### `1ly_search`
+
+Search for APIs by keyword.
+
+```typescript
+// Input
+{ query: "weather api", type: "api", maxPrice: 0.10 }
+
+// Output
+{
+  results: [
+    {
+      title: "Real-time Weather",
+      endpoint: "/api/link/joe/weather",
+      price: 0.01,
+      stats: { buyers: 150, rating: 95 }
+    }
+  ]
+}
+```
+
+### `1ly_get_details`
+
+Get full details about an API.
+
+```typescript
+// Input
+{ endpoint: "joe/weather" }
+
+// Output
+{
+  title: "Real-time Weather",
+  description: "Global weather data with forecasts",
+  price: 0.01,
+  reviews: [...],
+  paymentInfo: { networks: ["solana", "base"] }
+}
+```
+
+### `1ly_call`
+
+Call an API with automatic payment.
+
+```typescript
+// Input
+{ endpoint: "joe/weather", body: { city: "NYC" } }
+
+// Output
+{
+  data: { temp: 72, conditions: "sunny" },
+  _1ly: { purchaseId: "...", reviewToken: "..." }
+}
+```
+
+### `1ly_review`
+
+Leave a review after purchase.
+
+```typescript
+// Input
+{ purchaseId: "...", reviewToken: "...", positive: true, comment: "Fast and accurate!" }
+
+// Output
+{ success: true, reviewId: "..." }
+```
+
+### `1ly_create_link`
+
+Create an API link (paid or free). Requires `ONELY_API_KEY`.
+
+```typescript
+// Input
+{
+  title: "Premium Trading Signals",
+  url: "https://example.com/signals",
+  price: "10.00",
+  description: "Daily crypto signals"
+}
+```
+
+### `1ly_list_links`
+
+List API links for the store. Requires `ONELY_API_KEY`.
+
+### `1ly_update_link`
+
+Update an API link by id. Requires `ONELY_API_KEY`.
+
+### `1ly_delete_link`
+
+Delete an API link by id. Requires `ONELY_API_KEY`.
+
+### `1ly_get_stats`
+
+Fetch store or link stats. Requires `ONELY_API_KEY`.
+
+## Configuration
+
+| Environment Variable | Required | Description |
+|---------------------|----------|-------------|
+| `ONELY_WALLET_TYPE` | Yes | `solana` or `evm` |
+| `ONELY_WALLET_KEY` | Yes | Private key or path to keyfile |
+| `ONELY_BUDGET_PER_CALL` | No | Max USD per call (default: 1.00) |
+| `ONELY_BUDGET_DAILY` | No | Daily USD limit (default: 50.00) |
+| `ONELY_NETWORK` | No | Preferred network (default: solana) |
+| `ONELY_API_KEY` | No | Developer Mode API key for link management |
+
+## Wallet Setup
+
+### Solana
+
+Create a wallet keypair:
+
+```bash
+solana-keygen new -o ~/1ly-agent-wallet.json
+```
+
+Fund it with USDC on Solana mainnet.
+
+### EVM (Base)
+
+Create an EVM wallet (Base-compatible) and provide its **private key** via `ONELY_WALLET_KEY`.
+
+- **Option A (recommended)**: export your private key from your wallet (e.g. MetaMask/Rabby) and save it to a local file (one line, with or without `0x` prefix).
+- **Option B**: set the private key directly as an env var (not recommended for shared machines).
+
+Examples:
+
+```bash
+# from a file
+export ONELY_WALLET_TYPE=evm
+export ONELY_WALLET_KEY="$HOME/.1ly-base-private-key"
+
+# or inline (starts with 0x...)
+export ONELY_WALLET_TYPE=evm
+export ONELY_WALLET_KEY="0xYOUR_PRIVATE_KEY"
+```
+
+## Devnet / testnets (coming soon)
+
+We plan to offer an official devnet/testnet endpoint so you can try 1ly with test USDC before mainnet. For now, production usage requires mainnet USDC.
+
+## Troubleshooting
+
+- **Missing wallet**: Set `ONELY_WALLET_TYPE` and `ONELY_WALLET_KEY`.
+- **Missing API key**: Set `ONELY_API_KEY` to use link management tools.
+- **402 errors on first call**: Expected — `1ly_call` handles payment automatically.
+- **Insufficient funds**: Fund your wallet with USDC on the selected network.
+- **Review failed**: Ensure you pass the exact `purchaseId` + `reviewToken` returned by `1ly_call`.
+
+## Security
+
+- **Wallet keys stay local** — Never sent to 1ly servers
+- **Budget limits** — Prevent runaway spending
+- **Open source** — Audit the code yourself
+
+## Links
+
+- [1ly.store](https://1ly.store) — Marketplace
+- [Documentation](https://docs.1ly.store)
+- [x402 Protocol](https://x402.org)
+
+## License
+
+MIT

package/dist/budget.d.ts

@@ -0,0 +1,7 @@
+import type { Config } from "./config.js";
+/**
+ * Enforces daily budget by reading/modifying a small JSON file on disk.
+ * Throws if this call would exceed the configured daily limit.
+ */
+export declare function checkAndRecordDailySpend(config: Config, priceUsd: number): void;
+//# sourceMappingURL=budget.d.ts.map

package/dist/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../src/budget.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAmD1C;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAuB/E"}

package/dist/budget.js

@@ -0,0 +1,64 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkAndRecordDailySpend = checkAndRecordDailySpend;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+function getBudgetStatePath() {
+    const envPath = process.env.ONELY_BUDGET_STATE_FILE;
+    if (envPath && envPath.trim().length > 0) {
+        return envPath;
+    }
+    return path_1.default.join(os_1.default.homedir(), ".1ly-mcp-budget.json");
+}
+function loadBudgetState() {
+    const filePath = getBudgetStatePath();
+    try {
+        if (!fs_1.default.existsSync(filePath)) {
+            return { date: new Date().toISOString().slice(0, 10), spentToday: 0 };
+        }
+        const raw = fs_1.default.readFileSync(filePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        const today = new Date().toISOString().slice(0, 10);
+        // Reset if date changed or data invalid
+        if (!parsed.date || typeof parsed.spentToday !== "number" || parsed.date !== today) {
+            return { date: today, spentToday: 0 };
+        }
+        return parsed;
+    }
+    catch {
+        // On any error, fall back to fresh state
+        return { date: new Date().toISOString().slice(0, 10), spentToday: 0 };
+    }
+}
+function saveBudgetState(state) {
+    const filePath = getBudgetStatePath();
+    try {
+        fs_1.default.writeFileSync(filePath, JSON.stringify(state, null, 2), { encoding: "utf-8" });
+    }
+    catch {
+        // If we cannot persist, we still allow the call; fail-open is safer for UX
+    }
+}
+/**
+ * Enforces daily budget by reading/modifying a small JSON file on disk.
+ * Throws if this call would exceed the configured daily limit.
+ */
+function checkAndRecordDailySpend(config, priceUsd) {
+    const today = new Date().toISOString().slice(0, 10);
+    const state = loadBudgetState();
+    const current = state.date === today ? state.spentToday : 0;
+    const next = current + priceUsd;
+    if (next > config.budgets.daily) {
+        throw new Error(`Price $${priceUsd.toFixed(4)} would exceed daily budget of $${config.budgets.daily} (already spent: $${current.toFixed(4)})`);
+    }
+    const updated = {
+        date: today,
+        spentToday: next,
+    };
+    saveBudgetState(updated);
+}
+//# sourceMappingURL=budget.js.map

package/dist/budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../src/budget.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+export declare const ConfigSchema: z.ZodObject<{
+    apiBase: z.ZodDefault<z.ZodString>;
+    wallet: z.ZodNullable<z.ZodOptional<z.ZodObject<{
+        type: z.ZodEnum<["solana", "evm"]>;
+        key: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "solana" | "evm";
+        key: string;
+    }, {
+        type: "solana" | "evm";
+        key: string;
+    }>>>;
+    budgets: z.ZodObject<{
+        perCall: z.ZodDefault<z.ZodNumber>;
+        daily: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        perCall: number;
+        daily: number;
+    }, {
+        perCall?: number | undefined;
+        daily?: number | undefined;
+    }>;
+    network: z.ZodDefault<z.ZodEnum<["solana", "base"]>>;
+    apiKey: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    apiBase: string;
+    budgets: {
+        perCall: number;
+        daily: number;
+    };
+    network: "solana" | "base";
+    wallet?: {
+        type: "solana" | "evm";
+        key: string;
+    } | null | undefined;
+    apiKey?: string | null | undefined;
+}, {
+    budgets: {
+        perCall?: number | undefined;
+        daily?: number | undefined;
+    };
+    apiBase?: string | undefined;
+    wallet?: {
+        type: "solana" | "evm";
+        key: string;
+    } | null | undefined;
+    network?: "solana" | "base" | undefined;
+    apiKey?: string | null | undefined;
+}>;
+export type Config = z.infer<typeof ConfigSchema>;
+export declare function loadConfig(): Config;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAevB,CAAC;AAEH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAElD,wBAAgB,UAAU,IAAI,MAAM,CAenC"}

package/dist/config.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigSchema = void 0;
+exports.loadConfig = loadConfig;
+const zod_1 = require("zod");
+exports.ConfigSchema = zod_1.z.object({
+    apiBase: zod_1.z.string().url().default("https://1ly.store"),
+    wallet: zod_1.z
+        .object({
+        type: zod_1.z.enum(["solana", "evm"]),
+        key: zod_1.z.string(),
+    })
+        .optional()
+        .nullable(),
+    budgets: zod_1.z.object({
+        perCall: zod_1.z.number().positive().default(1.0),
+        daily: zod_1.z.number().positive().default(50.0),
+    }),
+    network: zod_1.z.enum(["solana", "base"]).default("solana"),
+    apiKey: zod_1.z.string().optional().nullable(),
+});
+function loadConfig() {
+    const walletType = process.env.ONELY_WALLET_TYPE;
+    const walletKey = process.env.ONELY_WALLET_KEY;
+    const apiKey = process.env.ONELY_API_KEY || null;
+    return exports.ConfigSchema.parse({
+        apiBase: "https://1ly.store",
+        wallet: walletType && walletKey ? { type: walletType, key: walletKey } : null,
+        budgets: {
+            perCall: parseFloat(process.env.ONELY_BUDGET_PER_CALL || "1.0"),
+            daily: parseFloat(process.env.ONELY_BUDGET_DAILY || "50.0"),
+        },
+        network: process.env.ONELY_NETWORK || "solana",
+        apiKey,
+    });
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":";;;AAqBA,gCAeC;AApCD,6BAAwB;AAEX,QAAA,YAAY,GAAG,OAAC,CAAC,MAAM,CAAC;IACnC,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,mBAAmB,CAAC;IACtD,MAAM,EAAE,OAAC;SACN,MAAM,CAAC;QACN,IAAI,EAAE,OAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QAC/B,GAAG,EAAE,OAAC,CAAC,MAAM,EAAE;KAChB,CAAC;SACD,QAAQ,EAAE;SACV,QAAQ,EAAE;IACb,OAAO,EAAE,OAAC,CAAC,MAAM,CAAC;QAChB,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC;QAC3C,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;KAC3C,CAAC;IACF,OAAO,EAAE,OAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IACrD,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CACzC,CAAC,CAAC;AAIH,SAAgB,UAAU;IACxB,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;IACjD,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;IAC/C,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,IAAI,CAAC;IAEjD,OAAO,oBAAY,CAAC,KAAK,CAAC;QACxB,OAAO,EAAE,mBAAmB;QAC5B,MAAM,EAAE,UAAU,IAAI,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,IAAI;QAC7E,OAAO,EAAE;YACP,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,qBAAqB,IAAI,KAAK,CAAC;YAC/D,KAAK,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,MAAM,CAAC;SAC5D;QACD,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,QAAQ;QAC9C,MAAM;KACP,CAAC,CAAC;AACL,CAAC"}

package/dist/http.d.ts

@@ -0,0 +1,26 @@
+export interface FetchOptions extends RequestInit {
+    /** Override timeout in milliseconds (default: 15000) */
+    timeoutMs?: number;
+    /** Number of retry attempts for transient errors (default: 2) */
+    retries?: number;
+    /** Delay between retries in milliseconds (default: 500) */
+    retryDelayMs?: number;
+}
+export declare class HttpError extends Error {
+    readonly status?: number | undefined;
+    readonly url?: string | undefined;
+    readonly bodySnippet?: string | undefined;
+    constructor(message: string, status?: number | undefined, url?: string | undefined, bodySnippet?: string | undefined);
+}
+/**
+ * fetchWithTimeout wraps the global fetch with:
+ * - per-request timeout using AbortController
+ * - basic retry logic for network/timeout errors
+ */
+export declare function fetchWithTimeout(url: string, options?: FetchOptions): Promise<Response>;
+/**
+ * Helper to throw a rich HttpError when response.ok is false.
+ * Reads a small snippet of the body (if any) for easier debugging.
+ */
+export declare function assertOk(response: Response, contextMessage: string): Promise<void>;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,YAAa,SAAQ,WAAW;IAC/C,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,SAAU,SAAQ,KAAK;aAGhB,MAAM,CAAC,EAAE,MAAM;aACf,GAAG,CAAC,EAAE,MAAM;aACZ,WAAW,CAAC,EAAE,MAAM;gBAHpC,OAAO,EAAE,MAAM,EACC,MAAM,CAAC,EAAE,MAAM,YAAA,EACf,GAAG,CAAC,EAAE,MAAM,YAAA,EACZ,WAAW,CAAC,EAAE,MAAM,YAAA;CAKvC;AAMD;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,QAAQ,CAAC,CA4CnB;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,QAAQ,EAClB,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAqBf"}

package/dist/http.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpError = void 0;
+exports.fetchWithTimeout = fetchWithTimeout;
+exports.assertOk = assertOk;
+const DEFAULT_TIMEOUT_MS = 15_000;
+const DEFAULT_RETRIES = 2;
+const DEFAULT_RETRY_DELAY_MS = 500;
+class HttpError extends Error {
+    status;
+    url;
+    bodySnippet;
+    constructor(message, status, url, bodySnippet) {
+        super(message);
+        this.status = status;
+        this.url = url;
+        this.bodySnippet = bodySnippet;
+        this.name = "HttpError";
+    }
+}
+exports.HttpError = HttpError;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * fetchWithTimeout wraps the global fetch with:
+ * - per-request timeout using AbortController
+ * - basic retry logic for network/timeout errors
+ */
+async function fetchWithTimeout(url, options = {}) {
+    const { timeoutMs = DEFAULT_TIMEOUT_MS, retries = DEFAULT_RETRIES, retryDelayMs = DEFAULT_RETRY_DELAY_MS, ...fetchOptions } = options;
+    let lastError;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await fetch(url, {
+                ...fetchOptions,
+                signal: controller.signal,
+            });
+            clearTimeout(timeout);
+            return response;
+        }
+        catch (error) {
+            clearTimeout(timeout);
+            lastError = error;
+            // If this was the last attempt, rethrow
+            if (attempt === retries) {
+                throw new Error(`Request to ${url} failed after ${retries + 1} attempt(s): ${error instanceof Error ? error.message : String(error)}`);
+            }
+            // Otherwise wait and retry
+            await sleep(retryDelayMs);
+        }
+    }
+    // Should be unreachable, but TypeScript needs a return/throw
+    throw lastError instanceof Error
+        ? lastError
+        : new Error(`Request to ${url} failed for unknown reasons`);
+}
+/**
+ * Helper to throw a rich HttpError when response.ok is false.
+ * Reads a small snippet of the body (if any) for easier debugging.
+ */
+async function assertOk(response, contextMessage) {
+    if (response.ok)
+        return;
+    let bodySnippet;
+    try {
+        const text = await response.text();
+        bodySnippet = text.slice(0, 500);
+    }
+    catch {
+        // Ignore body read errors
+    }
+    const url = response.url;
+    const messageParts = [
+        contextMessage,
+        `status=${response.status}`,
+        response.statusText && `statusText=${response.statusText}`,
+        url && `url=${url}`,
+        bodySnippet && `body=${bodySnippet}`,
+    ].filter(Boolean);
+    throw new HttpError(messageParts.join(" | "), response.status, url, bodySnippet);
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}