gametime-api-client 1.0.0 → 1.1.0

package/README.md

@@ -78,22 +78,56 @@ try {
 }
 ```
 
+### Situations (historical stats + CSV export)
+
+```js
+import { gametime } from 'gametime-api-client';
+import { writeFileSync } from 'fs';
+
+// Austin Reaves, 4th quarter, down 1–15
+const { id } = await gametime.situations.create({
+  sport: 'nba',
+  player: { name: 'Austin Reaves', team: 'LAL' },
+  filters: {
+    nba: {
+      quarter: 4,
+      timeRemainingSeconds: { gte: 0, lte: 720 },
+      scoreDiff: { gte: -15, lte: -1 },
+    },
+  },
+  season: { year: 2025, type: 'REG' },
+});
+
+// Get analysis
+const summary = await gametime.situations.analysis(id, 'nba');
+console.log(summary.analysis.totals, summary.analysis.perStart);
+
+// Export to CSV file
+const csv = await gametime.situations.exportCsv(id, 'nba');
+writeFileSync('austin-reaves-q4-down-1-15.csv', csv);
+```
+
 ## API reference
 
 | Method | Description |
 |--------|-------------|
+| **Live** | |
 | `live.games(sport)` | `'soccer' \| 'nba'` – list in-progress live games |
 | `live.players(sportEventId, sport)` | List players for a game |
 | `live.soccerAnalysis({ sportEventId, focusPlayerId? })` | Soccer prediction analysis |
 | `live.nbaAnalysis({ sportEventId, focusPlayerId?, verbosity? })` | NBA prediction analysis |
 | `live.createSession({ sport, sportEventId, focusPlayerId? })` | Create live WebSocket session |
+| **Situations** | |
+| `situations.create(params)` | Create situation (player + filters + season or game) |
+| `situations.analysis(id, sport)` | Get analysis (totals, perStart, reliability) |
+| `situations.exportCsv(id, sport, { includeSummary? })` | Export stats as CSV string |
 
 ## Types
 
 The client is written in TypeScript and ships with `.d.ts` definitions. Import types for better IDE support:
 
 ```ts
-import type { LiveGame, SoccerAnalysis, NbaAnalysis } from 'gametime-api-client';
+import type { LiveGame, SoccerAnalysis, NbaAnalysis, CreateSituationParams, SituationAnalysis } from 'gametime-api-client';
 ```
 
 ## Links

package/dist/index.d.ts

@@ -1,13 +1,15 @@
 /**
  * Gametime API JavaScript Client
- * Live sports data, player analysis, and predictions for NBA & Soccer.
+ * Live sports data, player analysis, predictions, and historical situations for NBA & Soccer.
  *
  * @example
  * ```js
  * import { createClient } from 'gametime-api-client';
- * const api = createClient({ baseUrl: 'https://gametimeapi.onrender.com' });
+ * const api = createClient();
  * const games = await api.live.games('soccer');
  * const analysis = await api.live.soccerAnalysis({ sportEventId: games[0].sportEventId });
+ * const { id } = await api.situations.create({ player: {...}, filters: {...}, season: {...} });
+ * const csv = await api.situations.exportCsv(id, 'nba');
  * ```
  */
 export interface ClientOptions {
@@ -122,12 +124,91 @@ export interface NbaAnalysis {
     };
     narration?: Record<string, unknown>;
 }
+/** Situation create filters */
+export interface SituationFiltersNba {
+    nba: {
+        quarter: 1 | 2 | 3 | 4;
+        timeRemainingSeconds: {
+            gte: number;
+            lte: number;
+        };
+        scoreDiff: {
+            gte: number;
+            lte: number;
+        };
+    };
+}
+export interface SituationFiltersSoccer {
+    soccer: {
+        half: 1 | 2;
+        minuteRange: {
+            gte: number;
+            lte: number;
+        };
+        scoreState: "leading" | "drawing" | "trailing";
+        goalDiffRange?: {
+            gte: number;
+            lte: number;
+        };
+    };
+}
+export interface CreateSituationParams {
+    sport?: "nba" | "soccer";
+    player: {
+        name: string;
+        id?: string;
+        team?: string;
+    };
+    filters: SituationFiltersNba | SituationFiltersSoccer;
+    limits?: {
+        maxGames?: number;
+        minStarts?: number;
+        maxStartsPerGame?: number;
+    };
+    game?: {
+        id: string;
+    };
+    season?: {
+        year: number;
+        type: "REG" | "PST" | "PRE";
+    };
+}
+export interface CreateSituationResponse {
+    id: string;
+    gamesScanned: number;
+    gamesUsed: number;
+}
+export interface SituationAnalysis {
+    id: string;
+    status: "ready" | "failed";
+    analysis: {
+        gamesScanned: number;
+        gamesUsed: number;
+        startsMatched: number;
+        reliabilityGrade: "A" | "B" | "C" | "D";
+        totals: Record<string, number>;
+        perStart: Record<string, number>;
+    };
+}
+/** Situations: create, analysis, CSV export */
+export interface SituationsApi {
+    /** Create a situation (provide either game or season, not both) */
+    create(params: CreateSituationParams): Promise<CreateSituationResponse>;
+    /** Get analysis for a situation */
+    analysis(id: string, sport: "nba" | "soccer"): Promise<SituationAnalysis>;
+    /** Export situation stats as CSV string */
+    exportCsv(id: string, sport: "nba" | "soccer", options?: {
+        includeSummary?: boolean;
+    }): Promise<string>;
+}
 /** Create a Gametime API client */
 export declare function createClient(options?: ClientOptions): {
     live: LiveApi;
+    situations: SituationsApi;
 };
 /** Pre-built client using default hosted API URL */
 export declare const gametime: {
     live: LiveApi;
+    situations: SituationsApi;
 };
 export { ApiError };

package/dist/index.js

@@ -1,13 +1,15 @@
 /**
  * Gametime API JavaScript Client
- * Live sports data, player analysis, and predictions for NBA & Soccer.
+ * Live sports data, player analysis, predictions, and historical situations for NBA & Soccer.
  *
  * @example
  * ```js
  * import { createClient } from 'gametime-api-client';
- * const api = createClient({ baseUrl: 'https://gametimeapi.onrender.com' });
+ * const api = createClient();
  * const games = await api.live.games('soccer');
  * const analysis = await api.live.soccerAnalysis({ sportEventId: games[0].sportEventId });
+ * const { id } = await api.situations.create({ player: {...}, filters: {...}, season: {...} });
+ * const csv = await api.situations.exportCsv(id, 'nba');
  * ```
  */
 const DEFAULT_BASE = "https://gametimeapi.onrender.com";
@@ -36,6 +38,16 @@ async function request(baseUrl, path, init) {
 function get(baseUrl, path) {
     return request(baseUrl, path, { method: "GET" });
 }
+async function getText(baseUrl, path) {
+    const url = `${baseUrl.replace(/\/$/, "")}${path}`;
+    const res = await fetch(url);
+    if (!res.ok) {
+        const body = await res.json().catch(() => ({}));
+        const err = body?.error ?? body;
+        throw new ApiError(err?.message ?? body?.message ?? res.statusText, err?.code, res.status, err?.details);
+    }
+    return res.text();
+}
 function post(baseUrl, path, body) {
     return request(baseUrl, path, {
         method: "POST",
@@ -63,7 +75,21 @@ export function createClient(options = {}) {
             return post(baseUrl, "/v1/live/sessions", params);
         },
     };
-    return { live };
+    const situations = {
+        create(params) {
+            return post(baseUrl, "/v1/situations", params);
+        },
+        analysis(id, sport) {
+            return get(baseUrl, `/v1/situations/${encodeURIComponent(id)}/analysis?sport=${sport}`);
+        },
+        exportCsv(id, sport, options) {
+            const q = new URLSearchParams({ sport });
+            if (options?.includeSummary !== undefined)
+                q.set("includeSummary", String(options.includeSummary));
+            return getText(baseUrl, `/v1/situations/${encodeURIComponent(id)}/export.csv?${q}`);
+        },
+    };
+    return { live, situations };
 }
 /** Pre-built client using default hosted API URL */
 export const gametime = createClient();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gametime-api-client",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "JavaScript client for Gametime API - live sports data, player analysis, and predictions",
   "type": "module",
   "main": "dist/index.js",