puntersedge 0.1.0

package/README.md

@@ -0,0 +1,67 @@
+# puntersedge
+
+Official Node.js / TypeScript client for the [PuntersEdge Australian Sports Odds API](https://puntersedge.online/api-platform).
+
+## Install
+
+```bash
+npm install puntersedge
+```
+
+## Quick start
+
+```typescript
+import PuntersEdgeClient from "puntersedge";
+
+const client = new PuntersEdgeClient({ apiKey: "YOUR_API_KEY" });
+
+// List sports
+const sports = await client.sports();
+
+// NRL head-to-head odds
+const nrl = await client.odds("nrl", "h2h");
+
+// Best odds across bookmakers (with arb detection)
+const best = await client.bestOdds("afl");
+
+// Next 5 horse races
+const races = await client.nextToGo(5, "horse");
+
+// Check your credit usage
+const usage = await client.usage();
+```
+
+## API key
+
+[Get a free API key](https://puntersedge.online/api-platform) — no credit card required.
+
+## Errors
+
+```typescript
+import { AuthError, RateLimitError, NotFoundError, ServerError } 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 */ }
+}
+```
+
+## Supported sports
+
+AFL, NRL, NBA, Tennis ATP/WTA, EPL, A-League, Super Rugby, Big Bash, Test Cricket
+
+## Links
+
+- [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/)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,117 @@
+/**
+ * PuntersEdge Node.js SDK
+ * Official client for the Australian Sports Odds API
+ * https://puntersedge.online/api-platform
+ */
+export interface Sport {
+    key: string;
+    title: string;
+    group: string;
+    active: boolean;
+}
+export interface Outcome {
+    name: string;
+    price: number;
+}
+export interface Market {
+    key: string;
+    outcomes: Outcome[];
+}
+export interface Bookmaker {
+    key: string;
+    title: string;
+    markets: Market[];
+}
+export interface Event {
+    id: string;
+    home_team: string;
+    away_team: string;
+    commence_time: string;
+    bookmakers: Bookmaker[];
+}
+export interface OddsResponse {
+    sport_key: string;
+    events: Event[];
+    fetched_at?: string;
+    data_age_seconds?: number;
+    stale?: boolean;
+}
+export interface BestOddsEvent {
+    id: string;
+    home_team: string;
+    away_team: string;
+    best_odds: Record<string, {
+        price: number;
+        bookmaker: string;
+    }>;
+    arb_opportunity: boolean;
+    arb_margin: number;
+}
+export interface BestOddsResponse {
+    sport_key: string;
+    events: BestOddsEvent[];
+}
+export interface Runner {
+    name: string;
+    number?: number;
+    prices: Record<string, number>;
+}
+export interface Race {
+    id: string;
+    name: string;
+    venue: string;
+    category: string;
+    start_time: string;
+    runners: Runner[];
+}
+export interface RacingResponse {
+    races: Race[];
+}
+export interface Usage {
+    plan: string;
+    credits_limit: number;
+    credits_used: number;
+    credits_remaining: number;
+    reset_date: string;
+    usage_by_endpoint?: Record<string, number>;
+    recent_activity?: Array<{
+        endpoint: string;
+        timestamp: string;
+        credits: number;
+    }>;
+}
+export interface PuntersEdgeOptions {
+    apiKey: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+}
+export declare class AuthError extends Error {
+    constructor(message: string);
+}
+export declare class RateLimitError extends Error {
+    constructor(message: string);
+}
+export declare class NotFoundError extends Error {
+    constructor(message: string);
+}
+export declare class ServerError extends Error {
+    constructor(message: string);
+}
+export declare class PuntersEdgeClient {
+    private apiKey;
+    private baseUrl;
+    private timeoutMs;
+    constructor(options: PuntersEdgeOptions);
+    private url;
+    /** List all active sports */
+    sports(): Promise<Sport[]>;
+    /** Get odds for a sport. markets = "h2h" | "spreads" | "totals" (comma-separated) */
+    odds(sportKey: string, markets?: string, bookmakers?: string): Promise<OddsResponse>;
+    /** Best available price per selection + arb detection */
+    bestOdds(sportKey: string): Promise<BestOddsResponse>;
+    /** Next-to-go racing. categories = "horse" | "greyhound" | "harness" */
+    nextToGo(numRaces?: number, categories?: string): Promise<RacingResponse>;
+    /** Current credit usage */
+    usage(): Promise<Usage>;
+}
+export default PuntersEdgeClient;

package/dist/index.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * PuntersEdge Node.js SDK
+ * Official client for the Australian Sports Odds API
+ * https://puntersedge.online/api-platform
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PuntersEdgeClient = exports.ServerError = exports.NotFoundError = exports.RateLimitError = exports.AuthError = void 0;
+const BASE_URL = "https://puntersedge.online";
+class AuthError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AuthError";
+    }
+}
+exports.AuthError = AuthError;
+class RateLimitError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RateLimitError";
+    }
+}
+exports.RateLimitError = RateLimitError;
+class NotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NotFoundError";
+    }
+}
+exports.NotFoundError = NotFoundError;
+class ServerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ServerError";
+    }
+}
+exports.ServerError = ServerError;
+async function request(url, apiKey, timeoutMs = 10000) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(url, {
+            headers: { "X-API-Key": apiKey },
+            signal: controller.signal,
+        });
+        const body = await res.json();
+        if (res.status === 401)
+            throw new AuthError(body.detail || "Unauthorized");
+        if (res.status === 402)
+            throw new RateLimitError(body.detail || "Insufficient credits");
+        if (res.status === 404)
+            throw new NotFoundError(body.detail || "Not found");
+        if (!res.ok)
+            throw new ServerError(`HTTP ${res.status}: ${body.detail || "Unknown error"}`);
+        return body;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+class PuntersEdgeClient {
+    constructor(options) {
+        var _a, _b;
+        this.apiKey = options.apiKey;
+        this.baseUrl = (_a = options.baseUrl) !== null && _a !== void 0 ? _a : BASE_URL;
+        this.timeoutMs = (_b = options.timeoutMs) !== null && _b !== void 0 ? _b : 10000;
+    }
+    url(path) {
+        return `${this.baseUrl}${path}`;
+    }
+    /** List all active sports */
+    async sports() {
+        return request(this.url("/api/v1/sports"), this.apiKey, this.timeoutMs);
+    }
+    /** Get odds for a sport. markets = "h2h" | "spreads" | "totals" (comma-separated) */
+    async odds(sportKey, markets = "h2h", bookmakers) {
+        const params = new URLSearchParams({ markets });
+        if (bookmakers)
+            params.set("bookmakers", bookmakers);
+        return request(this.url(`/api/v1/sports/${sportKey}/odds?${params}`), this.apiKey, this.timeoutMs);
+    }
+    /** Best available price per selection + arb detection */
+    async bestOdds(sportKey) {
+        return request(this.url(`/api/v1/best-odds/${sportKey}`), this.apiKey, this.timeoutMs);
+    }
+    /** Next-to-go racing. categories = "horse" | "greyhound" | "harness" */
+    async nextToGo(numRaces = 5, categories) {
+        const params = new URLSearchParams({ num_races: String(numRaces) });
+        if (categories)
+            params.set("categories", categories);
+        return request(this.url(`/api/v1/racing/next-to-go?${params}`), this.apiKey, this.timeoutMs);
+    }
+    /** Current credit usage */
+    async usage() {
+        return request(this.url("/api/v1/usage"), this.apiKey, this.timeoutMs);
+    }
+}
+exports.PuntersEdgeClient = PuntersEdgeClient;
+exports.default = PuntersEdgeClient;

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "puntersedge",
+  "version": "0.1.0",
+  "description": "Official Node.js client for the PuntersEdge Australian Sports Odds API",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "sports-odds",
+    "betting",
+    "australia",
+    "afl",
+    "nrl",
+    "api",
+    "puntersedge"
+  ],
+  "author": "PuntersEdge",
+  "license": "MIT",
+  "homepage": "https://puntersedge.online/api-platform",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/puntersedge/node-sdk"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,209 @@
+/**
+ * PuntersEdge Node.js SDK
+ * Official client for the Australian Sports Odds API
+ * https://puntersedge.online/api-platform
+ */
+
+const BASE_URL = "https://puntersedge.online";
+
+export interface Sport {
+  key: string;
+  title: string;
+  group: string;
+  active: boolean;
+}
+
+export interface Outcome {
+  name: string;
+  price: number;
+}
+
+export interface Market {
+  key: string;
+  outcomes: Outcome[];
+}
+
+export interface Bookmaker {
+  key: string;
+  title: string;
+  markets: Market[];
+}
+
+export interface Event {
+  id: string;
+  home_team: string;
+  away_team: string;
+  commence_time: string;
+  bookmakers: Bookmaker[];
+}
+
+export interface OddsResponse {
+  sport_key: string;
+  events: Event[];
+  fetched_at?: string;
+  data_age_seconds?: number;
+  stale?: boolean;
+}
+
+export interface BestOddsEvent {
+  id: string;
+  home_team: string;
+  away_team: string;
+  best_odds: Record<string, { price: number; bookmaker: string }>;
+  arb_opportunity: boolean;
+  arb_margin: number;
+}
+
+export interface BestOddsResponse {
+  sport_key: string;
+  events: BestOddsEvent[];
+}
+
+export interface Runner {
+  name: string;
+  number?: number;
+  prices: Record<string, number>;
+}
+
+export interface Race {
+  id: string;
+  name: string;
+  venue: string;
+  category: string;
+  start_time: string;
+  runners: Runner[];
+}
+
+export interface RacingResponse {
+  races: Race[];
+}
+
+export interface Usage {
+  plan: string;
+  credits_limit: number;
+  credits_used: number;
+  credits_remaining: number;
+  reset_date: string;
+  usage_by_endpoint?: Record<string, number>;
+  recent_activity?: Array<{ endpoint: string; timestamp: string; credits: number }>;
+}
+
+export interface PuntersEdgeOptions {
+  apiKey: string;
+  baseUrl?: string;
+  timeoutMs?: number;
+}
+
+export class AuthError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "AuthError";
+  }
+}
+
+export class RateLimitError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "RateLimitError";
+  }
+}
+
+export class NotFoundError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "NotFoundError";
+  }
+}
+
+export class ServerError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ServerError";
+  }
+}
+
+async function request<T>(
+  url: string,
+  apiKey: string,
+  timeoutMs = 10000
+): Promise<T> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const res = await fetch(url, {
+      headers: { "X-API-Key": apiKey },
+      signal: controller.signal,
+    });
+
+    const body = await res.json() as { detail?: string } & T;
+
+    if (res.status === 401) throw new AuthError((body as {detail?: string}).detail || "Unauthorized");
+    if (res.status === 402) throw new RateLimitError((body as {detail?: string}).detail || "Insufficient credits");
+    if (res.status === 404) throw new NotFoundError((body as {detail?: string}).detail || "Not found");
+    if (!res.ok) throw new ServerError(`HTTP ${res.status}: ${(body as {detail?: string}).detail || "Unknown error"}`);
+
+    return body;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export class PuntersEdgeClient {
+  private apiKey: string;
+  private baseUrl: string;
+  private timeoutMs: number;
+
+  constructor(options: PuntersEdgeOptions) {
+    this.apiKey = options.apiKey;
+    this.baseUrl = options.baseUrl ?? BASE_URL;
+    this.timeoutMs = options.timeoutMs ?? 10000;
+  }
+
+  private url(path: string): string {
+    return `${this.baseUrl}${path}`;
+  }
+
+  /** List all active sports */
+  async sports(): Promise<Sport[]> {
+    return request<Sport[]>(this.url("/api/v1/sports"), this.apiKey, this.timeoutMs);
+  }
+
+  /** Get odds for a sport. markets = "h2h" | "spreads" | "totals" (comma-separated) */
+  async odds(sportKey: string, markets = "h2h", bookmakers?: string): Promise<OddsResponse> {
+    const params = new URLSearchParams({ markets });
+    if (bookmakers) params.set("bookmakers", bookmakers);
+    return request<OddsResponse>(
+      this.url(`/api/v1/sports/${sportKey}/odds?${params}`),
+      this.apiKey,
+      this.timeoutMs
+    );
+  }
+
+  /** Best available price per selection + arb detection */
+  async bestOdds(sportKey: string): Promise<BestOddsResponse> {
+    return request<BestOddsResponse>(
+      this.url(`/api/v1/best-odds/${sportKey}`),
+      this.apiKey,
+      this.timeoutMs
+    );
+  }
+
+  /** Next-to-go racing. categories = "horse" | "greyhound" | "harness" */
+  async nextToGo(numRaces = 5, categories?: string): Promise<RacingResponse> {
+    const params = new URLSearchParams({ num_races: String(numRaces) });
+    if (categories) params.set("categories", categories);
+    return request<RacingResponse>(
+      this.url(`/api/v1/racing/next-to-go?${params}`),
+      this.apiKey,
+      this.timeoutMs
+    );
+  }
+
+  /** Current credit usage */
+  async usage(): Promise<Usage> {
+    return request<Usage>(this.url("/api/v1/usage"), this.apiKey, this.timeoutMs);
+  }
+}
+
+export default PuntersEdgeClient;