puntersedge 0.1.0 → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PuntersEdge
+
+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

@@ -1,67 +1,319 @@
 # puntersedge
 
-Official Node.js / TypeScript client for the [PuntersEdge Australian Sports Odds API](https://puntersedge.online/api-platform).
-
-## Install
+Official TypeScript/JavaScript client for the [PuntersEdge Odds API](https://puntersedge.online/api)
+— Australian and New Zealand racing (thoroughbred, greyhound, harness) and Australian sports odds
+from 14 Australian bookmakers, with settled results, form, a permanent market-movement archive and
+signed webhooks.
 
 ```bash
 npm install puntersedge
 ```
 
-## Quick start
+```ts
+import { PuntersEdge } from "puntersedge";
+
+const pe = new PuntersEdge({ apiKey: process.env.PUNTERSEDGE_API_KEY });
+
+for (const race of await pe.racing.nextToGo({ numRaces: 5, categories: "horse" })) {
+  const best = race.runners
+    .flatMap(r => r.bookmakers.map(b => ({ runner: r.name, book: b.key, price: b.win_price })))
+    .filter(q => q.price)
+    .sort((a, b) => b.price! - a.price!)[0];
+
+  console.log(`${race.venue} R${race.race_number}  best: ${best?.runner} @ ${best?.price} (${best?.book})`);
+}
+
+console.log(`${pe.credits?.remaining} credits left`);
+```
 
-```typescript
-import PuntersEdgeClient from "puntersedge";
+- **No dependencies.** Standard `fetch` only.
+- **Runs anywhere.** Node 18+, Deno, Bun, Cloudflare Workers, Vercel Edge, browsers. ESM and CommonJS.
+- **Fully typed.** Every response type is generated from the live OpenAPI document, so the types
+  cannot quietly drift from the server.
+- **Errors are typed.** A 402 is not a 429 is not a 422, and each carries what you need to act on it.
 
-const client = new PuntersEdgeClient({ apiKey: "YOUR_API_KEY" });
+## Get a key
 
-// List sports
-const sports = await client.sports();
+1. Sign up at <https://puntersedge.online/api>. Free tier, no card: 1,500 credits/month, 30 requests/minute.
+2. Click the verification link. The key is shown on screen and emailed to you.
+3. `export PUNTERSEDGE_API_KEY=...`
 
-// NRL head-to-head odds
-const nrl = await client.odds("nrl", "h2h");
+You can explore without a key at all — see [the sandbox](#the-sandbox-no-key-needed).
 
-// Best odds across bookmakers (with arb detection)
-const best = await client.bestOdds("afl");
+## Racing is not a sport key
 
-// Next 5 horse races
-const races = await client.nextToGo(5, "horse");
+The single most common first mistake. There is no `sport_key` of `"horse-racing"`.
 
-// Check your credit usage
-const usage = await client.usage();
+```ts
+await pe.sports.odds("horse-racing");     // ✗ 422
+await pe.racing.nextToGo();               // ✓
 ```
 
-## API key
+Racing and sports are separate endpoint families because they are separate shapes: a race has
+runners, barriers, a venue and a jump time; a fixture has two teams and a market. They are grouped
+the same way here.
+
+| | |
+|---|---|
+| `pe.racing.*` | thoroughbred, greyhound, harness — AU and NZ |
+| `pe.sports.*` | AFL, NRL, NBA, and the rest, by sport key |
+| `pe.arb.*` | cross-book comparison and arbitrage scanning |
+| `pe.account.*` | usage, key metadata, rotation, billing |
+| `pe.webhooks.*` | push delivery instead of polling |
+| `pe.health.*` | per-connector freshness, public uptime |
+| `pe.demo.*` | the sandbox: real prices, truncated, no key |
+
+## Credits, read for free
+
+The API bills per successful request and reports the running balance on **every** response. The
+client parses those headers, so checking your balance never costs a call.
+
+```ts
+await pe.racing.nextToGo();
+
+pe.credits?.cost;        // 2
+pe.credits?.remaining;   // 1088   — or the string "unlimited"
+pe.credits?.pctUsed;     // 27.5
+pe.credits?.warning;     // "approaching-limit", once you cross the threshold
+```
+
+Prefer this to polling `/v1/usage`: the response you just made already answered the question.
+
+For a callback on every billed call — to feed a gauge, or to log:
+
+```ts
+const pe = new PuntersEdge({
+  apiKey: KEY,
+  onCredits: c => { if (c.warning) console.warn(`${c.remaining} credits left`); },
+});
+```
+
+### What a call costs
+
+| Endpoints | Credits |
+|---|---|
+| `/v1/usage`, `/v1/billing/portal`, the sandbox, `/v1/uptime` | 0 |
+| `sports.list`, `racing.events`, `racing.venues`, `racing.trackConditions`, coverage endpoints | 1 |
+| `sports.odds` | **1 per market requested** |
+| `racing.nextToGo`, `racing.results`, `racing.changes`, `racing.acceptances`, jockey/trainer stats, `arb.bestPrices` | 2 |
+| `racing.bestOdds`, `racing.movers`, form endpoints, `sports.bestOdds`, `arb.sports`, `arb.lines` | 3 |
+| `racing.priceHistory`, `racing.closingLines`, `racing.pricePaths`, sports history and movements | 5 |
+| `racing.closingLinesCsv`, `racing.pricePathsCsv` | **20** |
 
-[Get a free API key](https://puntersedge.online/api-platform) — no credit card required.
+A malformed request — an unknown sport key, an unrecognised bookmaker, a bad date — is refused
+**before** billing, so a 422 is free.
 
 ## Errors
 
-```typescript
-import { AuthError, RateLimitError, NotFoundError, ServerError } from "puntersedge";
+```ts
+import {
+  PuntersEdgeError, AuthError, CreditsExhaustedError,
+  RateLimitError, ValidationError, NotFoundError, ServerError, NetworkError,
+} from "puntersedge";
 
 try {
-  const data = await client.odds("afl");
-} catch (e) {
-  if (e instanceof AuthError) { /* invalid key */ }
-  if (e instanceof RateLimitError) { /* out of credits */ }
-  if (e instanceof NotFoundError) { /* sport not found */ }
-  if (e instanceof ServerError) { /* 5xx */ }
+  await pe.racing.movers({ direction: "firming" });
+} catch (err) {
+  if (err instanceof RateLimitError) {
+    // The server told you how long to wait. Wait, then repeat the identical call.
+    await new Promise(r => setTimeout(r, (err.retryAfter ?? 60) * 1000));
+  } else if (err instanceof CreditsExhaustedError) {
+    // Not a rate limit — backing off will not clear it.
+    console.error(`Out of credits. ${err.upgrade?.plan} gives ${err.upgrade?.credits}/mo: ${err.upgrade?.url}`);
+    if (err.upgrade?.covers === "partial") {
+      console.error("…and that is still below your measured need. Email hello@puntersedge.online.");
+    }
+  } else if (err instanceof ValidationError) {
+    // Deterministic: retrying will fail identically forever.
+    for (const f of err.fields) console.error(f.loc.join("."), f.msg);
+  } else if (err instanceof PuntersEdgeError) {
+    console.error(err.status, err.problem?.type, err.message);
+  }
 }
 ```
 
-## Supported sports
+Every error carries the RFC 7807 body the API returned, so `err.problem.type` is a stable URI you
+can switch on, documented at [puntersedge.online/developers/errors](https://puntersedge.online/developers/errors).
+
+### Nothing is retried for you
+
+Deliberately. Odds are time-sensitive: a transparent retry inside the client can hand you a price
+recorded before a move you would have acted on, and it can double a billed call without telling
+you. Retry at the layer that knows whether a stale answer is acceptable.
+
+```ts
+async function withRetry<T>(call: () => Promise<T>, attempts = 3): Promise<T> {
+  for (let i = 0; ; i++) {
+    try {
+      return await call();
+    } catch (err) {
+      const retryable = err instanceof RateLimitError || err instanceof ServerError;
+      if (!retryable || i >= attempts - 1) throw err;
+      const wait = err instanceof RateLimitError
+        ? (err.retryAfter ?? 60) * 1000
+        : 2 ** i * 1000;
+      await new Promise(r => setTimeout(r, wait));
+    }
+  }
+}
+```
+
+Note what is missing from that list: `CreditsExhaustedError` and `ValidationError` are never
+retried, because neither will ever succeed on a second attempt.
+
+## Polling a live board
+
+Do not loop `nextToGo`. It re-downloads every race every time and bills 2 credits for the
+privilege. `changes` returns only what moved since a timestamp, and hands back the cursor for the
+next call.
+
+```ts
+let since = new Date(Date.now() - 60_000).toISOString();
+
+setInterval(async () => {
+  const batch = await pe.racing.changes({ since, categories: ["horse", "greyhound"] });
+  for (const race of batch.races ?? []) applyUpdate(race);
+  since = batch.server_time;          // the cursor for the next poll
+}, 15_000);
+```
+
+`server_time` is deliberately set back 30 seconds from the server clock so an in-flight write is
+never skipped. That makes the feed **at-least-once**: you will occasionally see a race twice, so
+`applyUpdate` must be idempotent.
+
+For anything slower than a few seconds, a [webhook](#webhooks) is cheaper still.
+
+## Freshness
+
+A stalled scraper does not return an error — it keeps serving its last value, which is exactly what
+a live price looks like. Every quote carries its own age:
+
+```ts
+const quotes = race.runners[0].bookmakers.filter(b => !b.stale && (b.age_seconds ?? 0) < 120);
+```
+
+And `pe.health.connectors()` reports `last_ok` per bookmaker, which is how you tell a quiet market
+from a broken feed.
+
+## Webhooks
+
+Creating a subscription needs the Standard plan or above.
+
+```ts
+const hook = await pe.webhooks.create({
+  url: "https://example.com/pe-hook",
+  events: ["race.odds_open"],
+});
+console.log(hook.secret);   // shown once — store it
+```
+
+Every delivery is signed. Verify against the **raw body**, before anything parses it:
+
+```ts
+import express from "express";
+import { verifyWebhookSignature } from "puntersedge";
+
+app.post("/pe-hook", express.raw({ type: "application/json" }), async (req, res) => {
+  const ok = await verifyWebhookSignature({
+    body: req.body,                                    // a Buffer, unparsed
+    signature: req.header("X-Webhook-Signature"),
+    secret: process.env.PUNTERSEDGE_WEBHOOK_SECRET!,
+  });
+  if (!ok) return res.sendStatus(401);
+
+  res.sendStatus(200);                                 // ack fast
+  queue.push(JSON.parse(req.body.toString("utf8")));    // work later
+});
+```
+
+> `JSON.stringify(req.body)` will never match. The API signs a canonical serialisation — keys
+> sorted, no whitespace — and your framework's re-serialisation differs. Hash the bytes you
+> received.
+
+When nothing arrives, `pe.webhooks.deliveries(id)` shows the attempts and the response codes your
+endpoint returned.
+
+## The sandbox, no key needed
+
+Real prices, truncated to 3 races, 5 runners and 3 bookmakers. 0 credits, no signup — so the
+example in *your* README stays runnable by someone who has not signed up yet.
+
+```ts
+const pe = new PuntersEdge();                 // no key
+const { races } = await pe.demo.nextToGo();
+```
+
+## Bulk history
+
+The archive endpoints stream CSV in a stable column order, which is the format a modeller actually
+wants:
+
+```ts
+const csv = await pe.racing.closingLinesCsv({ date: "2026-09-01", category: "horse" });
+await writeFile("closing-lines.csv", csv);
+```
+
+**CSV costs 20 credits, not 5.** These two endpoints are the only ones on the API whose price
+depends on the format you ask for, and the reason is size: the server caps a CSV pull at 50,000
+rows against 5,000 for a JSON page, so one call can return ten times the data for four times the
+price. If you are paging a small window, ask for JSON.
+
+## Runtime notes
+
+**Timeouts and cancellation.** 30 seconds by default; override per client or per call, and pass
+your own `AbortSignal` whenever you have one.
+
+```ts
+await pe.racing.nextToGo({ timeoutMs: 5_000, signal: req.signal });
+```
+
+**Connection reuse matters more than anything you can tune server-side.** Measured against this
+API: a cold TLS handshake costs 137ms against 40.5ms on a reused connection. Node's global fetch
+agent pools by default — so reuse one `PuntersEdge` instance for the life of your process rather
+than constructing one per request.
+
+**Compression.** Responses are JSON and compress about 9x. Node, Deno and Bun request gzip
+automatically. If you supply your own `fetch`, make sure it does too.
+
+**Endpoints newer than this package.** `pe.raw()` reaches anything:
+
+```ts
+const { data, credits, headers } = await pe.raw("GET", "/v1/racing/something-new", { limit: 5 });
+```
+
+## CommonJS
+
+```js
+const { PuntersEdge } = require("puntersedge");
+```
+
+## Contributing
+
+```bash
+npm install
+npm run types:generate     # regenerate src/types.generated.ts from the live schema
+npm run typecheck
+npm run build
+npm test                   # unit + contract tests, offline
+PUNTERSEDGE_API_KEY=... node --test test/live.test.mjs
+```
 
-AFL, NRL, NBA, Tennis ATP/WTA, EPL, A-League, Super Rugby, Big Bash, Test Cricket
+`test/contract.test.mjs` checks every call this client can make against the API's own OpenAPI
+document — every path template must exist and every query parameter must be one the server
+declares. That is the test that catches the failure mode a stubbed unit test cannot: a mis-mapped
+parameter name that the server silently ignores while returning a cheerful 200.
 
-## Links
+## Also available
 
-- [API documentation](https://puntersedge.online/api/examples)
-- [Coverage](https://puntersedge.online/api/coverage)
-- [Pricing](https://puntersedge.online/api/pricing)
-- [Status](https://puntersedge.online/status)
-- [Python SDK](https://pypi.org/project/puntersedge/)
+- **Python** — [`puntersedge`](https://pypi.org/project/puntersedge/) on PyPI, same design.
+- **MCP server** — [`puntersedge-mcp`](https://pypi.org/project/puntersedge-mcp/), for Claude,
+  Cursor and other agent hosts. See [/developers/mcp-server](https://puntersedge.online/developers/mcp-server).
+- **Examples** — [puntersedge-examples](https://github.com/puntersedge/puntersedge-examples):
+  runnable scripts, starters, n8n workflows and a Google Sheets connector.
+- **Postman** — import <https://api.puntersedge.online/postman.json>.
 
-## License
+## Licence
 
-MIT
+MIT. Data licensing is separate: internal use is included on every plan, showing prices to end
+users needs attribution on Plus and above, and redistribution needs Platform. See
+[the terms](https://puntersedge.online/terms).