bbdata-cli 0.2.0 → 0.3.0

package/dist/templates/queries/hitter-raw-bip.ts

@@ -0,0 +1,65 @@
+import { registerTemplate, type QueryTemplate } from './registry.js';
+import type { PitchData } from '../../adapters/types.js';
+
+/**
+ * Raw batted-ball projection — one row per ball in play with hit coordinates.
+ * Powers the spray chart. Filters to pitches where launch_speed is recorded
+ * (i.e., the ball was actually put in play).
+ */
+const template: QueryTemplate = {
+  id: 'hitter-raw-bip',
+  name: 'Hitter Raw Batted Balls',
+  category: 'hitter',
+  description: 'One row per batted ball with hit coordinates, exit velo, and launch angle',
+  preferredSources: ['savant'],
+  requiredParams: ['player'],
+  optionalParams: ['season'],
+  examples: [
+    'bbdata query hitter-raw-bip --player "Aaron Judge" --season 2025 --format json',
+  ],
+
+  buildQuery(params) {
+    return {
+      player_name: params.player,
+      season: params.season ?? new Date().getFullYear(),
+      stat_type: 'batting',
+    };
+  },
+
+  columns() {
+    return [
+      'hc_x',
+      'hc_y',
+      'launch_speed',
+      'launch_angle',
+      'events',
+      'bb_type',
+      'game_date',
+    ];
+  },
+
+  transform(data) {
+    const pitches = data as PitchData[];
+    if (pitches.length === 0) return [];
+
+    return pitches
+      .filter(
+        (p) =>
+          p.launch_speed != null &&
+          p.launch_speed > 0 &&
+          p.hc_x != null &&
+          p.hc_y != null,
+      )
+      .map((p) => ({
+        hc_x: p.hc_x,
+        hc_y: p.hc_y,
+        launch_speed: p.launch_speed,
+        launch_angle: p.launch_angle,
+        events: p.events ?? 'unknown',
+        bb_type: p.bb_type ?? 'unknown',
+        game_date: p.game_date,
+      }));
+  },
+};
+
+registerTemplate(template);

package/dist/templates/queries/hitter-zone-grid.ts

@@ -0,0 +1,90 @@
+import { registerTemplate, type QueryTemplate } from './registry.js';
+import type { PitchData } from '../../adapters/types.js';
+
+// 3x3 strike zone grid (copied from hitter-hot-cold-zones.ts)
+// row: 0 = high, 2 = low. col: 0 = inside (catcher POV left), 2 = outside.
+const ZONES: { name: string; row: number; col: number; xMin: number; xMax: number; zMin: number; zMax: number }[] = [
+  { name: 'High-In',  row: 0, col: 0, xMin: -0.83, xMax: -0.28, zMin: 2.83, zMax: 3.5  },
+  { name: 'High-Mid', row: 0, col: 1, xMin: -0.28, xMax:  0.28, zMin: 2.83, zMax: 3.5  },
+  { name: 'High-Out', row: 0, col: 2, xMin:  0.28, xMax:  0.83, zMin: 2.83, zMax: 3.5  },
+  { name: 'Mid-In',   row: 1, col: 0, xMin: -0.83, xMax: -0.28, zMin: 2.17, zMax: 2.83 },
+  { name: 'Mid-Mid',  row: 1, col: 1, xMin: -0.28, xMax:  0.28, zMin: 2.17, zMax: 2.83 },
+  { name: 'Mid-Out',  row: 1, col: 2, xMin:  0.28, xMax:  0.83, zMin: 2.17, zMax: 2.83 },
+  { name: 'Low-In',   row: 2, col: 0, xMin: -0.83, xMax: -0.28, zMin: 1.5,  zMax: 2.17 },
+  { name: 'Low-Mid',  row: 2, col: 1, xMin: -0.28, xMax:  0.28, zMin: 1.5,  zMax: 2.17 },
+  { name: 'Low-Out',  row: 2, col: 2, xMin:  0.28, xMax:  0.83, zMin: 1.5,  zMax: 2.17 },
+];
+
+/**
+ * 3x3 zone grid with numeric row/col indices and averaged xwOBA.
+ * Powers the zone-profile heatmap visualization. Unlike hitter-hot-cold-zones
+ * which returns strings for human display, this returns numerics for charting.
+ */
+const template: QueryTemplate = {
+  id: 'hitter-zone-grid',
+  name: 'Hitter Zone Grid (numeric)',
+  category: 'hitter',
+  description: '3x3 strike zone grid with numeric row/col/xwoba for heatmap visualization',
+  preferredSources: ['savant'],
+  requiredParams: ['player'],
+  optionalParams: ['season'],
+  examples: [
+    'bbdata query hitter-zone-grid --player "Shohei Ohtani" --format json',
+  ],
+
+  buildQuery(params) {
+    return {
+      player_name: params.player,
+      season: params.season ?? new Date().getFullYear(),
+      stat_type: 'batting',
+    };
+  },
+
+  columns() {
+    return ['zone', 'row', 'col', 'pitches', 'xwoba'];
+  },
+
+  transform(data) {
+    const pitches = data as PitchData[];
+    if (pitches.length === 0) return [];
+
+    return ZONES.map((z) => {
+      const inZone = pitches.filter(
+        (p) =>
+          p.plate_x >= z.xMin && p.plate_x < z.xMax &&
+          p.plate_z >= z.zMin && p.plate_z < z.zMax,
+      );
+
+      // Compute actual xwOBA across all plate-appearance-ending events in
+      // this zone (not just balls in play). Walks and HBPs use their canonical
+      // wOBA weights; strikeouts contribute zero; batted balls use the
+      // Statcast expected wOBA for that event.
+      const paEnding = inZone.filter((p) => p.events != null);
+      let xwobaSum = 0;
+      for (const p of paEnding) {
+        if (p.events === 'walk') {
+          xwobaSum += 0.69;
+        } else if (p.events === 'hit_by_pitch') {
+          xwobaSum += 0.72;
+        } else if (p.events === 'strikeout') {
+          xwobaSum += 0;
+        } else {
+          // Batted ball: use Statcast estimated wOBA for the contact event
+          xwobaSum += p.estimated_woba ?? 0;
+        }
+      }
+      const xwoba = paEnding.length > 0 ? xwobaSum / paEnding.length : 0;
+
+      return {
+        zone: z.name,
+        row: z.row,
+        col: z.col,
+        pitches: inZone.length,
+        pa: paEnding.length,
+        xwoba: Number(xwoba.toFixed(3)),
+      };
+    });
+  },
+};
+
+registerTemplate(template);

package/dist/templates/queries/index.ts

@@ -1,24 +1,27 @@
-// Import all templates to trigger registration
-import './pitcher-arsenal.js';
-import './pitcher-velocity-trend.js';
-import './pitcher-handedness-splits.js';
-import './hitter-batted-ball.js';
-import './hitter-vs-pitch-type.js';
-import './hitter-hot-cold-zones.js';
-import './matchup-pitcher-vs-hitter.js';
-import './matchup-situational.js';
-import './leaderboard-custom.js';
-import './leaderboard-comparison.js';
-import './trend-rolling-average.js';
-import './trend-year-over-year.js';
-
-export {
-  getTemplate,
-  getAllTemplates,
-  getTemplatesByCategory,
-  listTemplates,
-  type QueryTemplate,
-  type QueryTemplateParams,
-  type QueryResult,
-  type QueryCategory,
-} from './registry.js';
+// Import all templates to trigger registration
+import './pitcher-arsenal.js';
+import './pitcher-velocity-trend.js';
+import './pitcher-handedness-splits.js';
+import './hitter-batted-ball.js';
+import './hitter-vs-pitch-type.js';
+import './hitter-hot-cold-zones.js';
+import './matchup-pitcher-vs-hitter.js';
+import './matchup-situational.js';
+import './leaderboard-custom.js';
+import './leaderboard-comparison.js';
+import './trend-rolling-average.js';
+import './trend-year-over-year.js';
+import './pitcher-raw-pitches.js';
+import './hitter-raw-bip.js';
+import './hitter-zone-grid.js';
+
+export {
+  getTemplate,
+  getAllTemplates,
+  getTemplatesByCategory,
+  listTemplates,
+  type QueryTemplate,
+  type QueryTemplateParams,
+  type QueryResult,
+  type QueryCategory,
+} from './registry.js';

package/dist/templates/queries/pitcher-raw-pitches.ts

@@ -0,0 +1,62 @@
+import { registerTemplate, type QueryTemplate } from './registry.js';
+import type { PitchData } from '../../adapters/types.js';
+
+/**
+ * Raw pitch-level projection — one row per pitch, coordinate columns preserved.
+ * Powers the pitch-movement visualization (pfx_x, pfx_z scatter).
+ * Unlike pitcher-arsenal this does NOT aggregate; viz builders need per-pitch points.
+ */
+const template: QueryTemplate = {
+  id: 'pitcher-raw-pitches',
+  name: 'Pitcher Raw Pitches',
+  category: 'pitcher',
+  description: 'One row per pitch with coordinate columns for visualization (movement, location)',
+  preferredSources: ['savant'],
+  requiredParams: ['player'],
+  optionalParams: ['season', 'pitchType'],
+  examples: [
+    'bbdata query pitcher-raw-pitches --player "Corbin Burnes" --season 2025 --format json',
+  ],
+
+  buildQuery(params) {
+    return {
+      player_name: params.player,
+      season: params.season ?? new Date().getFullYear(),
+      stat_type: 'pitching',
+      pitch_type: params.pitchType ? [params.pitchType] : undefined,
+    };
+  },
+
+  columns() {
+    return [
+      'pitch_type',
+      'release_speed',
+      'release_spin_rate',
+      'pfx_x',
+      'pfx_z',
+      'plate_x',
+      'plate_z',
+      'game_date',
+    ];
+  },
+
+  transform(data) {
+    const pitches = data as PitchData[];
+    if (pitches.length === 0) return [];
+
+    return pitches
+      .filter((p) => p.pitch_type)
+      .map((p) => ({
+        pitch_type: p.pitch_type,
+        release_speed: p.release_speed,
+        release_spin_rate: p.release_spin_rate,
+        pfx_x: p.pfx_x,
+        pfx_z: p.pfx_z,
+        plate_x: p.plate_x,
+        plate_z: p.plate_z,
+        game_date: p.game_date,
+      }));
+  },
+};
+
+registerTemplate(template);

package/dist/templates/queries/trend-rolling-average.ts

@@ -22,7 +22,7 @@ const template: QueryTemplate = {
   },
 
   columns() {
-    return ['Window', 'Games', 'AVG', 'SLG', 'K %', 'Avg EV', 'Hard Hit %'];
+    return ['Window', 'Window End', 'Games', 'AVG', 'SLG', 'K %', 'Avg EV', 'Hard Hit %'];
   },
 
   transform(data) {
@@ -41,7 +41,16 @@ const template: QueryTemplate = {
     const windowSize = 15;
 
     if (dates.length < windowSize) {
-      return [{ Window: 'Insufficient data', Games: dates.length, AVG: '—', SLG: '—', 'K %': '—', 'Avg EV': '—', 'Hard Hit %': '—' }];
+      return [{
+        Window: 'Insufficient data',
+        'Window End': '',
+        Games: dates.length,
+        AVG: '—',
+        SLG: '—',
+        'K %': '—',
+        'Avg EV': '—',
+        'Hard Hit %': '—',
+      }];
     }
 
     // Calculate rolling windows
@@ -68,8 +77,11 @@ const template: QueryTemplate = {
         : null;
       const hardHit = batted.filter((p) => p.launch_speed! >= 95).length;
 
+      const windowEnd = windowDates[windowDates.length - 1]!;
+
       results.push({
-        Window: `${windowDates[0]} → ${windowDates[windowDates.length - 1]}`,
+        Window: `${windowDates[0]} → ${windowEnd}`,
+        'Window End': windowEnd,
         Games: windowDates.length,
         AVG: pas.length > 0 ? (hits.length / pas.length).toFixed(3) : '—',
         SLG: pas.length > 0 ? (totalBases / pas.length).toFixed(3) : '—',

package/dist/templates/reports/advance-sp.hbs

@@ -1,60 +1,66 @@
-# Advance Report: {{player}} (SP)
-
-**Season:** {{season}} | **For:** {{audience}} | **Generated:** {{date}}
-
----
-
-## Recent Form
-
-*Last 5 starts — to be populated with game log data*
-
-## Pitch Mix & Sequencing
-
-{{#if data.pitcher-arsenal}}
-### Arsenal Overview
-
-| Pitch | Usage | Velo | Spin | Whiff % |
-|-------|-------|------|------|---------|
-{{#each data.pitcher-arsenal}}
-| {{this.[Pitch Type]}} | {{this.[Usage %]}} | {{this.[Avg Velo]}} | {{this.[Avg Spin]}} | {{this.[Whiff %]}} |
-{{/each}}
-
-### By Count (to be populated)
-- **Ahead in count:** Primary pitch selection
-- **Behind in count:** Go-to pitch
-- **Two-strike:** Put-away pitch
-{{else}}
-*Arsenal data not available*
-{{/if}}
-
-## Times Through the Order
-
-*3rd time adjustment, velocity drop patterns — to be analyzed from pitch-level data*
-
-## Platoon Vulnerabilities
-
-{{#if data.pitcher-handedness-splits}}
-| Split | PA | AVG | SLG | K % | BB % |
-|-------|-----|-----|-----|-----|------|
-{{#each data.pitcher-handedness-splits}}
-| {{this.vs}} | {{this.PA}} | {{this.AVG}} | {{this.SLG}} | {{this.[K %]}} | {{this.[BB %]}} |
-{{/each}}
-{{else}}
-*Splits data not available*
-{{/if}}
-
-## How to Attack
-
-### Early in Game (1st time through)
-- *To be filled: patient approach? aggressive?*
-
-### Late in Game (3rd+ time through)
-- *To be filled: exploit fatigue patterns?*
-
-### Key Weaknesses
-- *To be filled by evaluator*
-
----
-
-*Generated by bbdata CLI · Data sources: {{sources}}*
-*This is a 1-page advance report designed for in-game use.*
+# Advance Report: {{player}} (SP)
+
+**Season:** {{season}} | **For:** {{audience}} | **Generated:** {{date}}
+
+---
+
+## Recent Form
+
+*Last 5 starts — to be populated with game log data*
+
+## Pitch Mix & Sequencing
+
+{{#if data.pitcher-arsenal}}
+### Arsenal Overview
+
+| Pitch | Usage | Velo | Spin | Whiff % |
+|-------|-------|------|------|---------|
+{{#each data.pitcher-arsenal}}
+| {{this.[Pitch Type]}} | {{this.[Usage %]}} | {{this.[Avg Velo]}} | {{this.[Avg Spin]}} | {{this.[Whiff %]}} |
+{{/each}}
+
+### By Count (to be populated)
+- **Ahead in count:** Primary pitch selection
+- **Behind in count:** Go-to pitch
+- **Two-strike:** Put-away pitch
+{{else}}
+*Arsenal data not available*
+{{/if}}
+
+{{#if graphs.movementChart}}
+### Pitch Movement Profile
+
+{{{svgOrEmpty graphs.movementChart}}}
+{{/if}}
+
+## Times Through the Order
+
+*3rd time adjustment, velocity drop patterns — to be analyzed from pitch-level data*
+
+## Platoon Vulnerabilities
+
+{{#if data.pitcher-handedness-splits}}
+| Split | PA | AVG | SLG | K % | BB % |
+|-------|-----|-----|-----|-----|------|
+{{#each data.pitcher-handedness-splits}}
+| {{this.vs}} | {{this.PA}} | {{this.AVG}} | {{this.SLG}} | {{this.[K %]}} | {{this.[BB %]}} |
+{{/each}}
+{{else}}
+*Splits data not available*
+{{/if}}
+
+## How to Attack
+
+### Early in Game (1st time through)
+- *To be filled: patient approach? aggressive?*
+
+### Late in Game (3rd+ time through)
+- *To be filled: exploit fatigue patterns?*
+
+### Key Weaknesses
+- *To be filled by evaluator*
+
+---
+
+*Generated by bbdata CLI · Data sources: {{sources}}*
+*This is a 1-page advance report designed for in-game use.*

package/dist/templates/reports/pro-hitter-eval.hbs

@@ -1,65 +1,77 @@
-# Pro Hitter Evaluation: {{player}}
-
-**Season:** {{season}} | **Audience:** {{audience}} | **Generated:** {{date}}
-
----
-
-## Batted Ball Profile
-
-{{#if data.hitter-batted-ball}}
-| Metric | Value |
-|--------|-------|
-{{#each data.hitter-batted-ball}}
-| {{this.Metric}} | {{this.Value}} |
-{{/each}}
-{{else}}
-*Batted ball data not available*
-{{/if}}
-
-## Approach & Discipline
-
-{{#if data.hitter-vs-pitch-type}}
-| Pitch Type | Seen | Swing % | Whiff % | Foul % | In Play | Avg EV | SLG |
-|------------|------|---------|---------|--------|---------|--------|-----|
-{{#each data.hitter-vs-pitch-type}}
-| {{this.[Pitch Type]}} | {{this.Seen}} | {{this.[Swing %]}} | {{this.[Whiff %]}} | {{this.[Foul %]}} | {{this.[In Play]}} | {{this.[Avg EV]}} | {{this.SLG}} |
-{{/each}}
-{{else}}
-*Pitch type breakdown not available*
-{{/if}}
-
-## Hot/Cold Zones
-
-{{#if data.hitter-hot-cold-zones}}
-| Zone | Pitches | Swings | Whiff % | AVG | SLG |
-|------|---------|--------|---------|-----|-----|
-{{#each data.hitter-hot-cold-zones}}
-| {{this.Zone}} | {{this.Pitches}} | {{this.Swings}} | {{this.[Whiff %]}} | {{this.AVG}} | {{this.SLG}} |
-{{/each}}
-{{else}}
-*Zone data not available*
-{{/if}}
-
-## Splits Analysis
-
-*To be populated: vs LHP/RHP, home/away*
-
-## Trend Analysis
-
-*To be populated: rolling average trends*
-
-## Risk Assessment
-
-*To be filled by evaluator: injury history, age curve, contract implications*
-
-## Comparable Player
-
-*To be filled by evaluator: statistical comp*
-
-## Role Projection
-
-*To be filled by evaluator: lineup position, expected production, Acquire / Pass / Monitor*
-
----
-
-*Generated by bbdata CLI · Data sources: {{sources}}*
+# Pro Hitter Evaluation: {{player}}
+
+**Season:** {{season}} | **Audience:** {{audience}} | **Generated:** {{date}}
+
+---
+
+## Batted Ball Profile
+
+{{#if data.hitter-batted-ball}}
+| Metric | Value |
+|--------|-------|
+{{#each data.hitter-batted-ball}}
+| {{this.Metric}} | {{this.Value}} |
+{{/each}}
+{{else}}
+*Batted ball data not available*
+{{/if}}
+
+{{#if graphs.sprayChart}}
+### Spray Chart
+
+{{{svgOrEmpty graphs.sprayChart}}}
+{{/if}}
+
+## Approach & Discipline
+
+{{#if data.hitter-vs-pitch-type}}
+| Pitch Type | Seen | Swing % | Whiff % | Foul % | In Play | Avg EV | SLG |
+|------------|------|---------|---------|--------|---------|--------|-----|
+{{#each data.hitter-vs-pitch-type}}
+| {{this.[Pitch Type]}} | {{this.Seen}} | {{this.[Swing %]}} | {{this.[Whiff %]}} | {{this.[Foul %]}} | {{this.[In Play]}} | {{this.[Avg EV]}} | {{this.SLG}} |
+{{/each}}
+{{else}}
+*Pitch type breakdown not available*
+{{/if}}
+
+## Hot/Cold Zones
+
+{{#if data.hitter-hot-cold-zones}}
+| Zone | Pitches | Swings | Whiff % | AVG | SLG |
+|------|---------|--------|---------|-----|-----|
+{{#each data.hitter-hot-cold-zones}}
+| {{this.Zone}} | {{this.Pitches}} | {{this.Swings}} | {{this.[Whiff %]}} | {{this.AVG}} | {{this.SLG}} |
+{{/each}}
+{{else}}
+*Zone data not available*
+{{/if}}
+
+{{#if graphs.zoneChart}}
+### Zone Heatmap
+
+{{{svgOrEmpty graphs.zoneChart}}}
+{{/if}}
+
+## Splits Analysis
+
+*To be populated: vs LHP/RHP, home/away*
+
+## Trend Analysis
+
+*To be populated: rolling average trends*
+
+## Risk Assessment
+
+*To be filled by evaluator: injury history, age curve, contract implications*
+
+## Comparable Player
+
+*To be filled by evaluator: statistical comp*
+
+## Role Projection
+
+*To be filled by evaluator: lineup position, expected production, Acquire / Pass / Monitor*
+
+---
+
+*Generated by bbdata CLI · Data sources: {{sources}}*