feat(types): nested refs + TeamRef metadata (0.3.0 / 0.3.1) (#7)

## Summary

Two related additions to the type model, both additive and non-breaking:

**0.3.0 — nested refs**
- New types: `TeamRef`, `SportRef`, `EntityRef`, `Team`
- Existing odds + opportunity rows extend with optional `home`, `away`,
`sport_ref`, `league_ref`, `market_ref`, `sportsbook_ref`
- `ArbitrageLeg` gains `sportsbook_ref`; `ClosingOddsLine` gains
`market_ref` + `sportsbook_ref`
- Reference rows (`Sport`, `League`, `Sportsbook`, `Market`) gain
`numerical_id`; `Team` adds `abbreviation` + `numerical_id`

**0.3.1 — TeamRef metadata**
- `TeamRef` and the `Team` reference shape gain optional `logo`, `city`,
`mascot`, `conference`, `division`. ~93% coverage on `logo`, similar on
the rest. All five default to `None`.

## Plus a public-release cleanup pass

- Add MIT `LICENSE` and `SECURITY.md`
- Untrack `tests/` and add to `.gitignore` (kept locally for dev); CI
gate is now lint + typecheck across the 3.10–3.13 matrix
- Tighten sdist via `[tool.hatch.build.targets.sdist]` so `.github/`
workflows no longer ship to PyPI sdist
- Update author email to `hello@sharpapi.io`
- Misc internal-comment cleanup

## Compatibility

No existing field renamed, retyped, or removed. Code on 0.2.x continues
to work.

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Mlaz-code

.github/workflows/publish.yml

@@ -10,13 +10,11 @@ on:
   workflow_dispatch:
 
 jobs:
-  # Re-run the full test matrix on the tagged commit before publish.
-  # Mirrors test.yml so a tagged release gets the same coverage as
-  # a push/PR. Previously publish.yml ran zero tests — a broken SDK
-  # could reach PyPI, and PyPI versions are immutable (only super-
-  # ceded). needs: test below gates the publish job on every matrix
-  # entry passing.
-  test:
+  # Mirrors test.yml on the tagged commit: lint + typecheck across the
+  # support matrix before publish. PyPI versions are immutable, so any
+  # gate we can apply pre-upload is cheaper than publishing a broken
+  # release. needs: gate below blocks publish on every matrix entry.
+  gate:
     runs-on: ubuntu-latest
     strategy:
       matrix:
@@ -31,7 +29,7 @@ jobs:
 
       - name: Install dependencies
         run: |
-          pip install -e ".[test,pandas]"
+          pip install -e ".[pandas]"
           pip install ruff pyright
 
       - name: Ruff check
@@ -40,11 +38,8 @@ jobs:
       - name: Pyright
         run: pyright
 
-      - name: Run tests
-        run: pytest -v
-
   publish:
-    needs: test
+    needs: gate
     runs-on: ubuntu-latest
     permissions:
       id-token: write

.github/workflows/test.yml

@@ -22,19 +22,11 @@ jobs:
 
       - name: Install dependencies
         run: |
-          pip install -e ".[test,pandas]"
+          pip install -e ".[pandas]"
           pip install ruff pyright
 
       - name: Ruff check
-        # [tool.ruff] config is already in pyproject.toml — rules E, F,
-        # I, UP. This step enforces them; before today they were only
-        # suggestions.
         run: ruff check
 
       - name: Pyright
-        # Same story — [tool.pyright] was set to standard mode in
-        # pyproject.toml but never invoked in CI.
         run: pyright
-
-      - name: Run tests
-        run: pytest -v

.gitignore

@@ -10,3 +10,9 @@ build/
 .ruff_cache/
 *.egg
 .mypy_cache/
+.coverage
+htmlcov/
+.claude/
+.DS_Store
+tests/
+.benchmarks/

CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to the `sharpapi` Python SDK are documented here.
+
+## 0.3.1 — 2026-05-06
+
+### Added — TeamRef metadata
+
+`TeamRef` now exposes five additional optional fields:
+
+- `logo` — full CDN URL. ~93% of teams are populated.
+- `city` — e.g. `"Arizona"` for the Diamondbacks.
+- `mascot` — e.g. `"Diamondbacks"`.
+- `conference` — e.g. `"NL"`, `"AFC"`, `"Western"`.
+- `division` — e.g. `"West Division"`, `"NL East"`, `"Pacific Division"`.
+
+All five default to `None` and are additive — existing 0.3.0 code keeps
+working unchanged.
+
+## 0.3.0 — 2026-05-06
+
+### Added — nested refs
+
+Every odds row, opportunity row, and reference-list row may now carry
+optional structured reference objects alongside the existing flat fields.
+All new fields are **optional and additive** — clients on older API
+versions (or talking to older API servers) see `None` and behave
+identically.
+
+New models:
+
+- `TeamRef` — `id`, `numerical_id`, `name`, `abbreviation` (latter only on
+  team-sport competitors)
+- `SportRef` — `id`, `name`, `numerical_id`
+- `EntityRef` — `id`, `label`, `numerical_id` (used for league / market /
+  sportsbook refs)
+
+New optional fields:
+
+- `OddsLine`, `EVOpportunity`, `ArbitrageOpportunity`, `MiddleOpportunity`,
+  `LowHoldOpportunity` — all gain `home`, `away`, `sport_ref`, `league_ref`,
+  `market_ref`, `sportsbook_ref` (legs / opps without a single book skip
+  `sportsbook_ref`).
+- `ArbitrageLeg` — gains `sportsbook_ref`.
+- `ClosingOddsLine` — gains `market_ref`, `sportsbook_ref`.
+- `ClosingSnapshot` — gains `home`, `away`, `sport_ref`, `league_ref`.
+- `Sport`, `League`, `Sportsbook`, `Market` — gain `numerical_id`.
+- `Event` — gains `home`, `away`, `sport_ref`, `league_ref`.
+
+New reference model:
+
+- `Team` — for the `/teams` reference endpoint, includes optional
+  `abbreviation` and `numerical_id`.
+
+### Backward compatibility
+
+No existing field was renamed, retyped, or removed. Code that does not
+reference the new attributes continues to work without changes.

LICENSE

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

SECURITY.md

@@ -0,0 +1,25 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you believe you have found a security vulnerability in this SDK or in
+the SharpAPI service, please report it privately to:
+
+**hello@sharpapi.io** (subject line: `[SECURITY] <short summary>`)
+
+Please do not open a public GitHub issue for security reports.
+
+We will acknowledge receipt within 72 hours and aim to provide a status
+update within 7 days. If the issue is confirmed, we will work with you on
+disclosure timing.
+
+## Scope
+
+In scope:
+- This SDK package and its published artifact on PyPI
+- The SharpAPI HTTP and WebSocket APIs (`api.sharpapi.io`, `ws.sharpapi.io`)
+
+Out of scope:
+- Findings in third-party dependencies (please report those upstream)
+- Denial of service via brute-force or volumetric attacks against the API
+- Issues that require physical access to a user's device

pyproject.toml

@@ -4,12 +4,12 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sharpapi"
-version = "0.2.6"
+version = "0.3.1"
 description = "Official Python SDK for the SharpAPI real-time sports betting odds API"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10"
-authors = [{ name = "SharpAPI", email = "support@sharpapi.io" }]
+authors = [{ name = "SharpAPI", email = "hello@sharpapi.io" }]
 keywords = ["sports-betting", "odds", "arbitrage", "ev", "api", "real-time", "pinnacle"]
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -41,6 +41,25 @@ Changelog = "https://github.com/Sharp-API/sharpapi-python/releases"
 [tool.hatch.build.targets.wheel]
 packages = ["src/sharpapi"]
 
+# Explicit sdist whitelist. Hatchling's default sdist would otherwise
+# include everything not gitignored (CI workflows, dependabot config,
+# .gitignore itself), all of which would land on PyPI on every release.
+# Keep this in sync with what we actually want users who do
+# `pip install --no-binary :all: sharpapi` to receive.
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/sharpapi",
+  "README.md",
+  "LICENSE",
+  "CHANGELOG.md",
+  "SECURITY.md",
+  "pyproject.toml",
+]
+exclude = [
+  ".gitignore",
+  ".github",
+]
+
 [tool.ruff]
 target-version = "py310"
 line-length = 100

src/sharpapi/__init__.py

@@ -38,6 +38,7 @@
     ArbitrageOpportunity,
     ClosingOddsLine,
     ClosingSnapshot,
+    EntityRef,
     Event,
     EVOpportunity,
     GameState,
@@ -53,11 +54,14 @@
     RateLimitInfo,
     ResponseMeta,
     Sport,
+    SportRef,
     Sportsbook,
+    Team,
+    TeamRef,
 )
 from .streaming import EventStream
 
-__version__ = "0.2.6"
+__version__ = "0.3.1"
 
 __all__ = [
     # Clients
@@ -71,6 +75,7 @@
     "ArbitrageOpportunity",
     "ClosingOddsLine",
     "ClosingSnapshot",
+    "EntityRef",
     "EVOpportunity",
     "Event",
     "GameState",
@@ -86,7 +91,10 @@
     "RateLimitInfo",
     "ResponseMeta",
     "Sport",
+    "SportRef",
     "Sportsbook",
+    "Team",
+    "TeamRef",
     # Streaming
     "EventStream",
     # Exceptions

src/sharpapi/exceptions.py

@@ -1,8 +1,7 @@
 """SharpAPI exceptions and canonical error-code registry.
 
-The error codes here mirror ``pkg/errcodes/errcodes.go`` in sharp-api-go, which
-is the single source of truth for every code the API emits. Keep this file in
-sync when new codes are added upstream.
+The codes here mirror the canonical set the SharpAPI server emits.
+Keep this file in sync when new codes are added upstream.
 """
 
 from __future__ import annotations
@@ -65,9 +64,10 @@ class StreamError(SharpAPIError):
 # =============================================================================
 # Canonical error-code registry
 #
-# Mirrors sharp-api-go/pkg/errcodes/errcodes.go. When upstream adds a new code,
-# add it here too and update the matching description. Each code maps to the
-# Python exception class that ``handle_errors`` (in ``_base.py``) raises for it.
+# Mirrors the canonical SharpAPI server error-code set. When upstream adds
+# a new code, add it here too and update the matching description. Each
+# code maps to the Python exception class that ``handle_errors`` (in
+# ``_base.py``) raises for it.
 # =============================================================================
 
 # HTTP error codes — emitted via REST handlers (httputil.WriteJSONError).
@@ -174,10 +174,10 @@ class StreamError(SharpAPIError):
     UPSTREAM_ERROR: SharpAPIError,
 }
 
-# Deprecated aliases. ``bad_request`` and ``invalid_request`` were both collapsed
-# into ``validation_error`` in sharp-api-go. Kept here so that older API
-# responses (or user code still checking these strings) resolve correctly.
-# TODO: remove after 2026-10.
+# Deprecated aliases. ``bad_request`` and ``invalid_request`` were both
+# collapsed into ``validation_error`` server-side. Kept here so that older
+# API responses (or user code still checking these strings) resolve
+# correctly. Will be removed after 2026-10.
 DEPRECATED_CODE_ALIASES: dict[str, str] = {
     "bad_request": VALIDATION_ERROR,
     "invalid_request": VALIDATION_ERROR,