football-docs 0.4.0 → 0.5.1

package/README.md

@@ -1,10 +1,10 @@
 # football-docs
 
-Searchable football data provider documentation for AI coding agents. Like [Context7](https://context7.com) for football data.
+Searchable football data provider and tooling documentation for AI coding agents. Like [Context7](https://context7.com) for football data.
 
-**Who it's for:** Developers and analysts who use AI coding tools (Claude Code, Cursor, VS Code Copilot, Windsurf) to work with football data. Works with any tool that supports MCP.
+**Who it's for:** Developers and analysts who use AI coding tools (Claude Code, Cursor, VS Code Copilot) to work with football data. Works with any tool that supports MCP.
 
-**What it does:** Gives your AI agent a searchable index of documentation for 15 football data providers — event types, qualifier IDs, coordinate systems, API endpoints, data models, identity surfaces, and cross-provider comparisons. Your agent looks up the real docs instead of guessing from training data.
+**What it does:** Gives your AI agent a searchable index of documentation for 15 football data providers and tools — event types, qualifier IDs, coordinate systems, API endpoints, data models, identity surfaces, and cross-provider comparisons for the data providers (StatsBomb, Opta, Wyscout, Impect, SkillCorner, and more), plus the open-source libraries people build with (kloppy, mplsoccer, socceraction, soccerdata, and more). Your agent looks up the real docs instead of guessing from training data.
 
 **Why not just let the AI figure it out?** LLMs get football data specifics wrong constantly — Opta qualifier IDs, StatsBomb coordinate ranges, API endpoint URLs, library method signatures. These are mutable facts that change across versions. football-docs gives the agent verified, sourced documentation with provenance tracking so you know where every answer came from.
 
@@ -58,21 +58,6 @@ Add to `.vscode/mcp.json`:
 }
 ```
 
-### Windsurf
-
-Add to `~/.codeium/windsurf/mcp_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "football-docs": {
-      "command": "npx",
-      "args": ["-y", "football-docs"]
-    }
-  }
-}
-```
-
 ### Claude Desktop
 
 Add to `claude_desktop_config.json`:
@@ -111,23 +96,23 @@ Add to `claude_desktop_config.json`:
 
 | Provider | Chunks | Categories |
 |----------|--------|------------|
-| StatsBomb | 150 | event-types, data-model, coordinate-system, api-access, xg-model, identity-surfaces |
+| StatsBomb | 231 | event-types, data-model, coordinate-system, api-access, api-endpoints, xg-model, iq-metrics, player/team stats, player-mapping, identity-surfaces |
+| Wyscout | 157 | event-types, data-model, coordinate-system, api-access, api-endpoints, glossary, identity-surfaces |
 | kloppy | 100 | data-model, usage, provider-mapping |
 | SportMonks | 78 | event-types, data-model, api-access, identity-surfaces |
 | databallpy | 63 | data-model, overview, usage |
 | mplsoccer | 62 | overview, pitch-types, visualizations |
-| Wyscout | 68 | event-types, data-model, coordinate-system, api-access, identity-surfaces |
+| Impect | 58 | api-access, api-endpoints, data-model, event-types, coordinate-system, concepts, identity-surfaces |
+| SkillCorner | 51 | api-access, api-endpoints, data-model, physical-data, coordinate-system, concepts, identity-surfaces |
 | Free sources | 45 | overview, fbref, understat |
 | soccerdata | 40 | overview, data-sources, usage |
 | Opta | 36 | event-types, qualifiers, coordinate-system, api-access, identity-surfaces |
 | socceraction | 26 | SPADL format, VAEP, Expected Threat |
 | FotMob | 7 | identity-surfaces |
-| Impect | 7 | identity-surfaces |
-| SkillCorner | 7 | identity-surfaces |
 | Soccerdonna | 7 | identity-surfaces |
 | Transfermarkt | 7 | identity-surfaces |
 
-**703 searchable chunks** across 15 providers.
+**968 searchable chunks** across 15 providers and tools.
 
 ## Contributing
 
@@ -139,17 +124,6 @@ Contributions are welcome from everyone. There are three ways to help:
 
 **You don't need to be an expert.** See **[CONTRIBUTING.md](CONTRIBUTING.md)** for the full guide.
 
-### What we especially need
-
-| Provider | Priority | Source material to start from |
-|----------|----------|-------------------------------|
-| FPL (Fantasy Premier League) | High | [FPL APIs Explained](https://www.oliverlooney.com/blogs/FPL-APIs-Explained) |
-| API-Football (RapidAPI) | High | [API-Football docs](https://www.api-football.com/documentation-v3) |
-| Football-data.org | Medium | [Football-data.org docs](https://www.football-data.org/documentation/api) |
-| TheSportsDB | Medium | [TheSportsDB API](https://www.thesportsdb.com/api.php) |
-| WhoScored | Medium | Based on Opta F24, community-documented |
-| Sofascore | Medium | Unofficial API, community-documented |
-
 ## For maintainers
 
 ### Crawl pipeline

package/dist/ingest.js

@@ -18,7 +18,7 @@
  *   npm run ingest                    # ingest all providers
  *   npm run ingest -- --provider opta # ingest one provider
  */
-import { existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { basename, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import Database from "better-sqlite3";
@@ -184,7 +184,10 @@ function main() {
         }
         const providers = readdirSync(DOCS_DIR).filter((d) => {
             const full = resolve(DOCS_DIR, d);
-            return existsSync(full) && readdirSync(full).some((f) => f.endsWith(".md"));
+            // Skip non-directory entries (e.g. macOS .DS_Store) so listing can't throw ENOTDIR.
+            return (existsSync(full) &&
+                statSync(full).isDirectory() &&
+                readdirSync(full).some((f) => f.endsWith(".md")));
         });
         let total = 0;
         for (const provider of providers) {

package/docs/impect/api-access.md

@@ -0,0 +1,78 @@
+---
+source_url: https://api.impect.com
+source_type: crawled
+upstream_version: Customer API v5.0
+crawled_at: 2026-06-03
+---
+
+# Impect API Access
+
+## Overview
+
+Impect is a **commercial football data provider** known for its *Packing* and *pxT* (packing expected threat) metrics, KPI/score framework and detailed set-piece data. Access is via the **Impect Customer API (v5)**, a REST/JSON API. This document is sourced from the v5 OpenAPI spec (`specs/impect/impect_openapi_docs.yml`).
+
+- Base URL: `https://api.impect.com`
+- Swagger: `https://api.impect.com/v3/api-docs/CustomerAPI`
+- All endpoints are `GET` and namespaced under `/v5/customerapi/...`.
+- Endpoint inventory: [api-endpoints.md](api-endpoints.md) · data model: [data-model.md](data-model.md) · metrics: [concepts.md](concepts.md).
+
+## Authentication
+
+**Bearer token** obtained via Keycloak (`https://login.impect.com/`). Pass it as `Authorization: Bearer <token>`. Every endpoint is protected by `hasRole('API')`.
+
+The official **`impectPy`** Python client handles the token exchange — get a token from your username/password, then pass it to each call:
+
+```python
+import impectPy as ip
+
+token = ip.getAccessToken(username="you@club.com", password="...")
+iterations = ip.getIterations(token=token)
+events = ip.getEvents(matches=[match_id], token=token)
+```
+
+(There is also an R client, `impectR`.) If calling the REST API directly, exchange credentials for a token at the Keycloak token endpoint, then send `Authorization: Bearer <token>` on each request.
+
+## Rate limiting
+
+**10 requests per second per user.** `impectPy` implements client-side token-bucket throttling to stay under it. The API also returns `RateLimit-Policy` and `RateLimit-Remaining` headers; on a `429`, wait for the `Retry-After` header duration before retrying.
+
+## Request correlation
+
+Every endpoint accepts an optional **`X-Request-ID`** header (ideally a UUID) to correlate client and server logs when raising support issues.
+
+## Response envelope
+
+All responses share an envelope:
+
+```json
+{
+  "data": [ /* the payload — usually a List<...Dto> */ ],
+  "status": 200,
+  "message": null
+}
+```
+
+`data` holds the typed payload; `status` mirrors the HTTP status; `message` carries error/info text. Errors use `ErrorResponseObject`.
+
+## Core concepts (how the API is organised)
+
+| Term | Meaning |
+|---|---|
+| **Iteration** | A season × competition instance (e.g. "Premier League 2024/25"). The primary unit for aggregated data. `iterationId` keys most master-data and iteration-level endpoints. |
+| **Match** | A single game, keyed by `matchId`. The unit for event-level data, KPIs, scores and set-pieces. |
+| **Squad** | A team (club or national team), keyed by `squadId`. |
+| **KPI** | A countable/valued key performance indicator computed per event/player/squad. See [concepts.md](concepts.md). |
+| **Score** | A 0–100-style standardised rating derived from KPIs, at player/squad/profile level. |
+| **Profile** | A weighted bundle of KPIs/scores defining a player archetype, position-scoped. |
+
+## Update & delete feeds
+
+For keeping a local mirror in sync, the API exposes incremental **update** and **delete** feeds per entity type. Both take a required **`since`** query param (ISO 8601 timestamp) and return only records changed/deleted after it. See the Update Feed / Delete Feed sections of [api-endpoints.md](api-endpoints.md).
+
+## Cross-provider IDs
+
+Master-data objects (iterations, players, squads, matches, coaches, stadiums) carry an **`idMappings`** field — provider name → array of that provider's IDs — so you can bridge Impect entities to other providers directly. See [identity-surfaces.md](identity-surfaces.md).
+
+## SkillCorner integration
+
+Impect aligns its events to **SkillCorner** tracking frames. `GET /v5/customerapi/matches/{matchId}/skillcorner-frame-mappings` returns frame ↔ event-index mappings (with an `isMatched` flag), letting you join Impect event data to SkillCorner tracking. See [skillcorner](../skillcorner/api-access.md).

package/docs/impect/api-endpoints.md

@@ -0,0 +1,97 @@
+---
+source_url: https://api.impect.com
+source_type: crawled
+upstream_version: Customer API v5.0
+crawled_at: 2026-06-03
+---
+
+# Impect API Endpoints (Customer API v5)
+
+44 `GET` endpoints under base `https://api.impect.com`, all prefixed `/v5/customerapi/`. Paths below omit that prefix. All require `Authorization: Bearer <token>` (see [api-access.md](api-access.md)); responses use the `{data, status, message}` envelope. Common path params: `{iterationId}`, `{matchId}`, `{squadId}`, `{positions}` (comma-separated `Position` values).
+
+## Master Data
+
+| Endpoint | Returns |
+|---|---|
+| `GET /countries` | All countries |
+| `GET /iterations` | All iterations (season × competition) |
+| `GET /iterations/{iterationId}/matches` | Matches in an iteration |
+| `GET /iterations/{iterationId}/squads` | Squads in an iteration |
+| `GET /iterations/{iterationId}/players` | Players in an iteration |
+| `GET /iterations/{iterationId}/coaches` | Coaches in an iteration |
+| `GET /iterations/{iterationId}/stadiums` | Stadiums in an iteration |
+| `GET /matches/{matchId}` | Match line-ups, formations & substitutions (`data` is a `MatchDto`, wrapped in `ResponseObject_MatchInfoDto`) |
+
+## Match Level Data
+
+| Endpoint | Returns |
+|---|---|
+| `GET /matches/{matchId}/events` | Full event feed (`EventDto`) — packing zones, lanes, pxT, phases |
+| `GET /matches/{matchId}/event-kpis` | Per-event KPI values (`ScoringDto`: position, playerId, eventId, kpiId, value) |
+| `GET /matches/{matchId}/player-kpis` | Per-player KPI sums for the match |
+| `GET /matches/{matchId}/squad-kpis` | Per-squad KPI sums for the match |
+| `GET /matches/{matchId}/player-scores` | Per-player standardised scores |
+| `GET /matches/{matchId}/positions/{positions}/player-scores` | Per-player scores for given positions |
+| `GET /matches/{matchId}/squad-scores` | Per-squad scores |
+| `GET /matches/{matchId}/set-pieces` | Set-piece sub-phases (`SetPieceDto`) |
+| `GET /matches/{matchId}/skillcorner-frame-mappings` | SkillCorner frame ↔ event-index mappings |
+
+## Iteration Level Data (aggregates)
+
+| Endpoint | Returns |
+|---|---|
+| `GET /iterations/{iterationId}/squad-kpis` | Squad average KPIs across the iteration |
+| `GET /iterations/{iterationId}/squad-scores` | Squad scores across the iteration |
+| `GET /iterations/{iterationId}/squads/{squadId}/player-kpis` | Player average KPIs (one squad) |
+| `GET /iterations/{iterationId}/squads/{squadId}/player-scores` | Player scores (one squad) |
+| `GET /iterations/{iterationId}/squads/{squadId}/positions/{positions}/player-scores` | Player scores by position |
+| `GET /iterations/{iterationId}/squads/{squadId}/positions/{positions}/player-profile-scores` | Player profile scores by position |
+
+## Definitions
+
+| Endpoint | Returns |
+|---|---|
+| `GET /kpis` | All KPI definitions |
+| `GET /kpis/event` | Event-level KPI definitions |
+| `GET /player-scores` | All player score definitions (`ScoreDto`: id, name, details{label, definition, meaning}, inverted) |
+| `GET /squad-scores` | All squad score definitions |
+| `GET /player-profiles` | All profile definitions (`ProfileDto`: name, weighted factors, positions) |
+
+Definitions endpoints accept an optional **`language`** query param for translated labels/definitions.
+
+## Squad Ratings & Predictions
+
+| Endpoint | Returns |
+|---|---|
+| `GET /iterations/{iterationId}/squads/ratings` | Squad ratings over the iteration (`SquadRatingsForIterationDto` → dated entries) |
+| `GET /iterations/{iterationId}/predictions/model-coefficients` | Prediction model coefficients |
+
+## Update Feed (incremental sync)
+
+All take a required **`since`** (ISO 8601) query param; return records changed after it.
+
+| Endpoint | Entity |
+|---|---|
+| `GET /update/iterations` | Iterations |
+| `GET /update/matches` | Matches |
+| `GET /update/matchdata` | Match data (events/KPIs/scores recalculated) |
+| `GET /update/squads` | Squads |
+| `GET /update/players` | Players |
+| `GET /update/coaches` | Coaches |
+| `GET /update/stadiums` | Stadiums |
+| `GET /update/skillcorner-frame-mappings` | SkillCorner frame mappings |
+
+## Delete Feed (incremental sync)
+
+All take a required **`since`** (ISO 8601) query param; return `DeletedDto` records (with `DeleteType` = `DELETED` or `MERGED`).
+
+| Endpoint | Entity |
+|---|---|
+| `GET /delete/iterations` | Iterations |
+| `GET /delete/matches` | Matches |
+| `GET /delete/squads` | Squads |
+| `GET /delete/players` | Players |
+| `GET /delete/coaches` | Coaches |
+| `GET /delete/stadiums` | Stadiums |
+
+Note: a `MERGED` delete means the entity was merged into another (follow up via the update feed to find the survivor).

package/docs/impect/concepts.md

@@ -0,0 +1,58 @@
+---
+source_url: https://api.impect.com
+source_type: crawled
+upstream_version: Customer API v5.0
+crawled_at: 2026-06-03
+---
+
+# Impect Concepts: Packing, pxT, KPIs, Scores
+
+Impect's analytics are built on a few signature concepts. The API exposes them as fields and as queryable definitions; the framing below is grounded in the v5 schema (exact field names in [data-model.md](data-model.md)). For canonical formulas, consult the Definitions endpoints (which return each KPI/score's `label`, `definition`, `meaning`) and Impect's own glossary.
+
+## Packing
+
+**Packing** counts the opponents a pass or dribble *bypasses* (outplays) — i.e. how many defenders are taken out of the game by moving the ball past them. In the event model this surfaces as `PassDto.opponents` (opponents bypassed) together with the start/end `packingZone`. Bypassing defenders closer to goal is worth more, which is why the longitudinal `PackingZone` bands (`FIRST_THIRD` → `BOX`) matter. Impect popularised Packing as an alternative to possession/pass-count metrics.
+
+## pxT — packing expected threat
+
+**pxT** assigns a *threat value* to ball progression rather than just counting bypassed opponents. On each pass, `PassDto.pxT` is `{team, opponent}`:
+
+- **`team`** — expected threat added *for* the attacking team by the action.
+- **`opponent`** — expected threat conceded *to* the opponent (the risk/cost component, e.g. if the ball is lost).
+
+Net value is the team gain weighed against the opponent risk. pxT is Impect's possession-value layer over the Packing/zone framework.
+
+## KPIs
+
+A **KPI** is a single valued metric computed at event, player or squad level. In data, a KPI value is `{kpiId, value}` (`KpiDto`); at event level it is `{position, playerId, eventId, kpiId, value}` (`ScoringDto`). Resolve `kpiId` to its meaning via:
+
+- `GET /kpis` — all KPI definitions
+- `GET /kpis/event` — event-level KPI definitions
+
+Each definition (`KpiDetailsDto`) carries `label`, `definition`, `meaning`, an optional `parentKpi`, a `context`, and an `inverted` flag (true where a lower raw value is better). Pass `language` for translated text.
+
+## Scores
+
+A **score** is a standardised rating derived from KPIs (so different metrics are comparable on a common scale; `inverted` marks lower-is-better inputs). Scores are exposed at several granularities:
+
+| Level | Endpoints |
+|---|---|
+| Player (match) | `/matches/{matchId}/player-scores`, `.../positions/{positions}/player-scores` |
+| Player (iteration avg) | `/iterations/{id}/squads/{squadId}/player-scores`, `.../positions/{positions}/player-scores` |
+| Squad | `/matches/{matchId}/squad-scores`, `/iterations/{id}/squad-scores` |
+| Profile | `/iterations/{id}/squads/{squadId}/positions/{positions}/player-profile-scores` |
+
+Definitions: `GET /player-scores`, `GET /squad-scores` (`ScoreDto = {id, name, details{label, definition, meaning}, inverted}`).
+
+## Profiles
+
+A **profile** (`ProfileDto`) is a weighted bundle defining a player archetype, scoped to positions: `{name, factors:[{name, type(KPI|SCORE), weight, inverted}], positions:[{name}]}`. Profile scores rate how well a player fits an archetype in given positions. Definitions: `GET /player-profiles`.
+
+## Squad ratings & predictions
+
+- **Squad ratings** — a time series of squad strength across an iteration (`GET /iterations/{id}/squads/ratings` → dated `{squadId, value}` entries).
+- **Prediction model coefficients** — the coefficients behind Impect's match-outcome predictions (`GET /iterations/{id}/predictions/model-coefficients`).
+
+## Set-piece sub-phases
+
+Impect breaks each set-piece into ordered **sub-phases** (delivery → first touch → second touch …), each with its own end zone, delivery type, touch players/outcomes and aggregates. This makes set-pieces analysable as structured sequences rather than single events. See `SetPieceDto` in [data-model.md](data-model.md).

package/docs/impect/coordinate-system.md

@@ -0,0 +1,49 @@
+---
+source_url: https://api.impect.com
+source_type: crawled
+upstream_version: Customer API v5.0
+crawled_at: 2026-06-03
+---
+
+# Impect Coordinate System & Spatial Zones
+
+Impect locates events with both **continuous coordinates** and a set of **categorical zone descriptors**. The categorical descriptors (packing zone, lane, pitch position) are central to Impect's analytics and are attached to the start and end of every event.
+
+## Coordinates
+
+Each `EventPositionDto` carries two coordinate pairs (`CoordinateDto = {x, y}`):
+
+- **`coordinates`** — raw pitch coordinates.
+- **`adjCoordinates`** — **direction-adjusted** coordinates, normalised so a squad's attacking direction is consistent regardless of which way it physically plays. Use these to compare/aggregate across halves and teams without flipping.
+
+The OpenAPI spec types `x`/`y` as numbers but does not pin the numeric range, so treat the scale as provider-defined and prefer the categorical zones below for portable logic; use `adjCoordinates` for any direction-sensitive computation. Shots also expose a goal-plane aim point via `ShotDto.targetPoint = {y, z}` and the goalkeeper position/`divePoint`.
+
+## Packing zone (`PackingZone`)
+
+Longitudinal bands up the pitch, used in Packing/pxT metrics:
+
+`GKR` → `FIRST_THIRD` → `SECOND_THIRD` → `FINAL_THIRD` → `BOX`
+
+(`GKR` = goalkeeper/restart zone behind the first third; `BOX` = opponent penalty area.)
+
+## Lane (`Lane`)
+
+Lateral channels across the pitch (the half-space framework):
+
+`LEFT_WING` · `LEFT_HALF_SPACE` · `CENTER` · `RIGHT_HALF_SPACE` · `RIGHT_WING`
+
+## Pitch position (`PitchPosition`)
+
+Coarse thirds-by-box location:
+
+`OWN_BOX` · `OWN_HALF` · `OPPONENT_HALF` · `OPPONENT_BOX`
+
+## Set-piece end zones (`EndZone`)
+
+Target zones used in set-piece sub-phases (corners, free-kicks, goal-kicks, throw-ins, second deliveries):
+
+`FAR_LEFT`, `FAR_RIGHT`, `NEAR_POST`, `FAR_POST`, `OPPOSITE_SIDE_1`, `OPPOSITE_SIDE_2`, `SAME_SIDE_1`, `SAME_SIDE_2`, `SIX_YARD_BOX`, `INSIDE_OWN_BOX`, `INSIDE_OPPONENT_BOX`, `OUTSIDE_BOX`, `LEFT_GOAL_KICK_ZONE`, `RIGHT_GOAL_KICK_ZONE`, `CENTER`
+
+## Putting it together
+
+A single event therefore carries, at both `start` and `end`: continuous `coordinates` + `adjCoordinates`, plus the `packingZone` (longitudinal band), `lane` (lateral channel) and `pitchPosition` (coarse box/half). The packing zone and lane together give a grid Impect uses to define line-breaking passes and the threat models in [concepts.md](concepts.md).

package/docs/impect/data-model.md

@@ -0,0 +1,123 @@
+---
+source_url: https://api.impect.com
+source_type: crawled
+upstream_version: Customer API v5.0
+crawled_at: 2026-06-03
+---
+
+# Impect Data Model
+
+Payload structures returned by the Customer API v5, from the OpenAPI spec. Every response is wrapped in `{data, status, message}` (see [api-access.md](api-access.md)). For the spatial/categorical enums see [coordinate-system.md](coordinate-system.md) and [event-types.md](event-types.md); for KPI/score semantics see [concepts.md](concepts.md).
+
+## Event (`EventDto`)
+
+`GET /matches/{matchId}/events` returns a list of `EventDto`. Each event is heavily annotated with Impect's spatial framework (packing zone, lane, pitch position) and metric payloads.
+
+| Field | Type | Notes |
+|---|---|---|
+| `index` | integer | Event order within the match |
+| `id` | integer | Event id |
+| `sequenceIndex` | integer | Index within the possession sequence |
+| `gameTime` | `GameTimeDto` | `{gameTime (mm:ss), gameTimeInSec}` |
+| `periodId` | integer | Match period |
+| `squadId` | integer | Acting squad |
+| `player` | `EventPlayerDto` | `{id, position, positionSide}` |
+| `actionType` | `ActionType` | SHOT, PASS, DRIBBLE, TACKLE, INTERCEPTION, CLEARANCE, CROSS, FOUL, OFFSIDE |
+| `action` | `Action` | LOW_PASS, HIGH_PASS, GROUND_DUEL, AIR_DUEL, SHOT, CROSS, CLEARANCE, INTERCEPTION, TACKLE, FOUL, OFFSIDE |
+| `result` | `EventResult` | SUCCESS / FAIL |
+| `phase` | `Phase` | SECOND_BALL, BUILD_UP, COUNTER_ATTACK, SET_PIECE |
+| `pressure` | number | Pressure on the acting player |
+| `distanceToOpponent` | `DistanceToOpponent` | LESS_THAN_ONE_METER, ONE_TO_THREE_METERS, MORE_THAN_THREE_METERS |
+| `start` / `end` | `EventPositionDto` | Location + zone/lane/pitch-position at start and end (see below) |
+| `opponent` | `EventOpponentPositionDto` | Nearest opponent's `coordinates` / `adjCoordinates` |
+| `formation` | `FormationsDto` | `{team, opponent}` formation strings |
+| `pass` | `PassDto` | Present for passes (see below) |
+| `shot` | `ShotDto` | Present for shots |
+| `dribble` | `DribbleDto` | `{distance, type, result, playerId}` |
+| `duel` | `DuelDto` | `{duelType, playerId}` |
+| `setPiece` | `EventSetPieceDto` | `{id, subPhaseId, mainEvent}` — links event to a set-piece sub-phase |
+| `inferredSetPiece` | boolean | Set-piece inferred rather than tagged |
+| `pressingPlayerId` | integer | |
+| `fouledPlayerId` | integer | |
+
+### `EventPositionDto` (start / end)
+
+| Field | Type | Notes |
+|---|---|---|
+| `coordinates` | `CoordinateDto` | `{x, y}` raw pitch coordinates |
+| `adjCoordinates` | `CoordinateDto` | Direction-adjusted coordinates (attack normalised one way) |
+| `packingZone` | `PackingZone` | GKR, FIRST_THIRD, SECOND_THIRD, FINAL_THIRD, BOX |
+| `pitchPosition` | `PitchPosition` | OWN_BOX, OWN_HALF, OPPONENT_HALF, OPPONENT_BOX |
+| `lane` | `Lane` | LEFT_WING, LEFT_HALF_SPACE, CENTER, RIGHT_HALF_SPACE, RIGHT_WING |
+
+### `PassDto`
+
+| Field | Type | Notes |
+|---|---|---|
+| `distance` | number | |
+| `angle` | number | |
+| `distanceToGoal` | number | |
+| `duration` | number | |
+| `opponents` | integer | Opponents bypassed (packing count) |
+| `receiver` | `PassReceiverDto` | `{playerId, type}` — `type` = TEAMMATE / OPPONENT |
+| `currentAttackingSquadId` | integer | |
+| `bodyPart` | `BodyPart` | FOOT / HEAD / OTHER (+ `bodyPartExtended` string) |
+| `previousPassHeight` | `PassHeight` | LOW / MEDIUM / HIGH |
+| `pxT` | `PxTDto` | `{team, opponent}` — packing expected threat added for/against (see [concepts.md](concepts.md)) |
+
+### `ShotDto`
+
+| Field | Type | Notes |
+|---|---|---|
+| `distance` | number | |
+| `angle` | number | |
+| `targetPoint` | `TargetPointDto` | `{y, z}` — aim point in the goal plane |
+| `gk` | `ShotGoalkeeperDto` | `{coordinates, adjCoordinates, divePoint, woodwork}` — `woodwork` = LEFT_POST / RIGHT_POST / CROSSBAR |
+
+## KPIs and scoring
+
+KPIs are valued metrics referenced by `kpiId`; their human definitions come from the Definitions endpoints.
+
+| Schema | Shape | From |
+|---|---|---|
+| `KpiDto` | `{kpiId, value}` | player/squad/iteration KPI endpoints |
+| `ScoringDto` | `{position, playerId, eventId, kpiId, value}` | `GET /matches/{matchId}/event-kpis` |
+| `KpiDetailsDto` | `{id, name, details, parentKpi, context, inverted}` | KPI definitions |
+| `KpiBasicDetailsDto` | `{label, definition, meaning}` | nested in definitions/scores |
+
+`ScoreDto` (score definitions): `{id, name, details:{label, definition, meaning}, inverted}`. Player/squad scores are standardised ratings derived from KPIs (player-scores, squad-scores, profile-scores endpoints). `ProfileDto`: `{name, factors:[{name, type(KPI|SCORE), weight, inverted}], positions:[{name}]}`.
+
+## Set-pieces (`SetPieceDto`)
+
+Impect models set-pieces as a sequence of **sub-phases**:
+
+| Field | Type | Notes |
+|---|---|---|
+| `id`, `matchId`, `squadId` | integer | |
+| `startTime`/`endTime` (+ `*InSec`) | string/number | |
+| `phaseIndex` | integer | |
+| `setPieceCategory` / `adjSetPieceCategory` | `SetPieceCategory` | FREE_KICK, CORNER, GOAL_KICK, THROW_IN, PENALTY |
+| `setPieceExecutionType` | `SetPieceExecutionType` | DIRECT / INDIRECT |
+| `setPieceSubPhase` | `[SetPieceSubPhaseDto]` | per-category end zones (`cornerEndZone`, `freeKickEndZone`, …), delivery types, first/second-touch players & outcomes, `passReceiverId`, `ballTrajectory`, `aggregates` |
+
+End zones use the `EndZone` enum (NEAR_POST, FAR_POST, SIX_YARD_BOX, etc. — see [coordinate-system.md](coordinate-system.md)).
+
+## Squad ratings & predictions
+
+- `GET /iterations/{iterationId}/squads/ratings` → `SquadRatingsForIterationDto` = `{iterationId, squadRatingsEntries:[SquadRatingsForDateDto]}`; each dated entry holds `SquadRatingDto` = `{squadId, value}`. Ratings are a time series across the iteration.
+- `GET /iterations/{iterationId}/predictions/model-coefficients` → model coefficients (`ModelCoefficientDto`) used in Impect's match-prediction model.
+
+## Master data
+
+| Schema | Key fields |
+|---|---|
+| `IterationDto` | `id`, `season`, `competition{name, id, type, countryId, gender}`, `dataVersion`, `lastChangeTimestamp`, `idMappings` |
+| `MatchDto` (single match, from `GET /matches/{matchId}`) | `id`, `dateTime`, `lastCalculationDate`, `iterationId`, `stadiumId`, `squadHome`/`squadAway` (`MatchSquadInfoDto`: `id` (squadId), players, startingPositions, substitutions, startingFormation, formations, coachId). **No `idMappings`.** |
+| `MatchInfoDto` (list item, from `GET /iterations/{id}/matches`) | `iterationId`, `id`, `homeSquadId`, `awaySquadId`, `scheduledDate`, `lastCalculationDate`, `matchDay`, `available`, `idMappings` |
+| `PlayerDto` | `id`, `firstname`, `lastname`, `commonname`, `birthdate`, `birthplace`, `leg` (LEFT/RIGHT/BOTH), `countryIds`, `gender`, `currentSquadId`, `idMappings` |
+| `SquadDto` | `id`, `name`, `countryId`, `type` (NATIONAL_TEAM/CLUB), `gender`, `imageUrl`, `idMappings`, `access` |
+| `CoachDto` (has `idMappings`) / `StadiumDto` (has `idMappings`) / `CountryDetailDto` | reference data |
+
+> Note: `GET /matches/{matchId}` is wrapped in `ResponseObject_MatchInfoDto`, but its `data` payload is actually a **`MatchDto`** (with nested line-ups). The flat `MatchInfoDto` — the one that carries `idMappings` — is what the `/iterations/{id}/matches` list returns.
+
+`idMappings` (`IdMappingDto`) is an **array of `{external provider name → string[]}` maps** and is present on `IterationDto`, `SquadDto`, `PlayerDto`, `MatchInfoDto`, `CoachDto` and `StadiumDto` — see [identity-surfaces.md](identity-surfaces.md).

package/docs/impect/event-types.md

@@ -0,0 +1,73 @@
+---
+source_url: https://api.impect.com
+source_type: crawled
+upstream_version: Customer API v5.0
+crawled_at: 2026-06-03
+---
+
+# Impect Event Types & Enums
+
+Impect's `EventDto` does not use a free-form type string — it uses a small set of controlled enums. The two that classify an event are **`actionType`** (the broad category) and **`action`** (the specific action). These are the exact enum values from the v5 spec. See [data-model.md](data-model.md) for the full event payload.
+
+## `actionType` (9)
+
+The broad event category:
+
+`SHOT`, `PASS`, `DRIBBLE`, `TACKLE`, `INTERCEPTION`, `CLEARANCE`, `CROSS`, `FOUL`, `OFFSIDE`
+
+## `action` (11)
+
+The specific action (note passes split by height, and duels are first-class):
+
+`LOW_PASS`, `HIGH_PASS`, `GROUND_DUEL`, `AIR_DUEL`, `SHOT`, `CROSS`, `CLEARANCE`, `INTERCEPTION`, `TACKLE`, `FOUL`, `OFFSIDE`
+
+## `result`
+
+`SUCCESS`, `FAIL`
+
+## `phase` — possession phase
+
+`SECOND_BALL`, `BUILD_UP`, `COUNTER_ATTACK`, `SET_PIECE`
+
+## Contextual enums
+
+| Enum | Values |
+|---|---|
+| `BodyPart` | `FOOT`, `HEAD`, `OTHER` |
+| `PassHeight` | `LOW`, `MEDIUM`, `HIGH` |
+| `ReceiverType` | `TEAMMATE`, `OPPONENT` |
+| `DuelType` | `GROUND_DUEL`, `AIR_DUEL` |
+| `DribbleType` | `ONE_VS_ONE`, `ONE_VS_MANY` |
+| `DribbleResult` | `WINNER`, `LOSER` |
+| `DistanceToOpponent` | `LESS_THAN_ONE_METER`, `ONE_TO_THREE_METERS`, `MORE_THAN_THREE_METERS` |
+| `Woodwork` | `LEFT_POST`, `RIGHT_POST`, `CROSSBAR` |
+| `Leg` | `LEFT`, `RIGHT`, `BOTH` |
+
+## Position enums
+
+| Enum | Values |
+|---|---|
+| `Position` | `BANK` (bench), `GOALKEEPER`, `LEFT_BACK`, `RIGHT_BACK`, `CENTER_BACK`, `LEFT_MIDFIELD`, `RIGHT_MIDFIELD`, `CENTER_MIDFIELD`, `LEFT_WING`, `RIGHT_WING`, `CENTER_FORWARD` |
+| `PositionSide` | `LEFT`, `RIGHT`, `CENTER` |
+
+`{positions}` path params (e.g. on player-scores endpoints) take a comma-separated list of `Position` values.
+
+## Set-piece enums
+
+| Enum | Values |
+|---|---|
+| `SetPieceCategory` | `FREE_KICK`, `CORNER`, `GOAL_KICK`, `THROW_IN`, `PENALTY` |
+| `SetPieceExecutionType` | `DIRECT`, `INDIRECT` |
+
+## Other enums
+
+| Enum | Values |
+|---|---|
+| `Gender` | `MALE`, `FEMALE` |
+| `SquadType` | `NATIONAL_TEAM`, `CLUB` |
+| `SubstitutionType` | `SUB_ON`, `SUB_OFF`, `TACTICAL_CHANGE` |
+| `DeleteType` | `DELETED`, `MERGED` |
+| `DataVersion` | `V1` |
+| `ProfileFactorType` | `KPI`, `SCORE` |
+
+Spatial enums (`PackingZone`, `Lane`, `PitchPosition`, `EndZone`) are documented in [coordinate-system.md](coordinate-system.md).

package/docs/impect/identity-surfaces.md

@@ -1,15 +1,40 @@
 ---
-source_type: curated
-source_url: null
-upstream_version: null
-crawled_at: null
+source_type: crawled
+source_url: https://api.impect.com
+upstream_version: Customer API v5.0
+crawled_at: 2026-06-03
 ---
 
 # Impect Identity Surfaces
 
-Impect is primarily useful as a commercial match and event data provider. Public
-documentation for identity surfaces is limited, so this page records cautious
-curated guidance for entity-resolution work that has legitimate data access.
+Impect is primarily useful as a commercial match and event data provider. The
+sections below combine **spec-confirmed** identity facts from the Customer API v5
+with cautious curated guidance for entity-resolution work that has legitimate
+data access.
+
+## ID Mappings (confirmed, v5 API)
+
+The v5 API exposes a first-class **`idMappings`** field on master-data objects —
+`IterationDto`, `SquadDto`, `PlayerDto`, `MatchInfoDto`, `CoachDto` and
+`StadiumDto` all carry it (i.e. nearly every entity except the nested single-match
+`MatchDto`). `IdMappingDto` is:
+
+> "ID mappings to external systems. Keys are provider names, values are arrays of
+> string identifiers." — i.e. each entry is a `map<providerName, string[]>`, and
+> the field is an array of such maps.
+
+This means Impect entities can be bridged to other providers **directly from the
+feed**, without inference — read `idMappings` on the iteration/squad/player/match/
+coach/stadium and match the external IDs to your register. An entity may map to
+multiple IDs per provider (hence arrays). Note matches expose `idMappings` on the
+flat list item (`MatchInfoDto`, from `GET /iterations/{id}/matches`), not on the
+single-match `MatchDto` from `GET /matches/{matchId}`. Impect also aligns events
+to **SkillCorner** frames via `GET /matches/{matchId}/skillcorner-frame-mappings`,
+a separate frame↔event bridge (not part of `idMappings`).
+
+Entity keys themselves are integer `id` fields: `iterationId`, `matchId`,
+`squadId`, player `id`, `coachId`, `stadiumId`, `countryId`. Iterations are the
+season×competition unit (`{season, competition{...}}`).
 
 ## Access Surface