dda-sdk 0.0.1__py3-none-any.whl

dda_sdk/__init__.py

@@ -0,0 +1,44 @@
+from importlib.metadata import version as _package_version
+
+from dda_sdk.duckdb_connector import DuckDBClient
+from dda_sdk.polars_connector import PolarsClient
+from dda_sdk.schemas import (
+    BaselineSchema,
+    CountriesSchema,
+    CurrenciesSchema,
+    EngagementsPerSkuSchema,
+    EventsSchema,
+    OrganizationsSchema,
+    PortalsSchema,
+    ProductsSchema,
+    SalesPerSkuSchema,
+    SalesSchema,
+    SkusSchema,
+    VisibilitySchema,
+    VisibilityWishlistPerSkuSchema,
+    WishlistActionsSchema,
+    WishlistCohortsSchema,
+)
+
+__version__ = _package_version("dda-sdk")
+
+__all__ = [
+    "__version__",
+    "DuckDBClient",
+    "PolarsClient",
+    "BaselineSchema",
+    "CountriesSchema",
+    "CurrenciesSchema",
+    "EngagementsPerSkuSchema",
+    "EventsSchema",
+    "OrganizationsSchema",
+    "PortalsSchema",
+    "ProductsSchema",
+    "SalesSchema",
+    "SalesPerSkuSchema",
+    "SkusSchema",
+    "VisibilitySchema",
+    "VisibilityWishlistPerSkuSchema",
+    "WishlistActionsSchema",
+    "WishlistCohortsSchema",
+]

dda_sdk/_assets/CLAUDE.md

@@ -0,0 +1,28 @@
+# IndieBI DDA Workspace
+
+> This file is managed by the dda-sdk package and is overwritten on every
+> update. Put your own instructions in `CLAUDE.local.md` instead.
+
+## Data Access (dda_sdk)
+
+For connector setup (credentials, `.env`), see `README.md`.
+For fetching data and generating charts, use the `dda-analytics` skill
+(`.claude/skills/dda-analytics/SKILL.md`).
+
+## Design System
+
+When doing any UI/design/chart/report work, read
+`.claude/skills/indiebi-design-system/SKILL.md` first.
+
+## Your analyses
+
+Create each analysis in its own directory under `projects/`. Updates to the
+SDK never touch `projects/`, `.env`, or `CLAUDE.local.md`.
+
+## Updating
+
+At session start you may be told a new dda-sdk version is available. To
+update, run `uv run dda-update` — it upgrades the package and refreshes the
+managed files (`.claude/skills/`, `docs/`, `CLAUDE.md`, `.claude/settings.json`).
+Your own Claude settings and hooks go in `.claude/settings.local.json`, which
+is never overwritten.

dda_sdk/_assets/docs/assets/logo.svg

@@ -0,0 +1,14 @@
+<svg width="66" height="66" viewBox="0 0 66 66" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect width="66" height="66" fill="url(#paint0_linear_1_4657)"/>
+<path d="M37.7238 32.2868C40.1898 30.6785 41.7115 27.6668 41.7115 24.6956C41.7115 19.6569 37.5044 15.8887 31.7785 15.8887H23.4278V21.3172H31.4349C34.126 21.3172 36.1068 23.0699 36.1068 25.5099C36.1068 28.0364 34.1607 29.9624 31.4349 29.9624H23.4278V21.3172H17.9849V50.1287H32.047C37.9433 50.1287 42.5922 45.9216 42.5922 40.5335C42.5922 36.8693 40.7961 33.7508 37.7238 32.2868ZM31.738 44.6829H23.4278V35.079H31.738C34.7179 35.079 36.8691 37.1378 36.8691 39.9098C36.8691 42.7309 34.7324 44.7551 31.738 44.6829Z" fill="white"/>
+<path d="M17.9849 15.8714H12.5391V21.3172H17.9849V15.8714Z" fill="white"/>
+<path d="M52.2422 15.8858H46.7964V50.1287H52.2422V15.8858Z" fill="white"/>
+<defs>
+<linearGradient id="paint0_linear_1_4657" x1="9.66548" y1="56.3345" x2="56.3345" y2="9.66548" gradientUnits="userSpaceOnUse">
+<stop stop-color="#8468FF"/>
+<stop offset="0.29" stop-color="#8677FF"/>
+<stop offset="0.65" stop-color="#8784FF"/>
+<stop offset="1" stop-color="#8F8FFF"/>
+</linearGradient>
+</defs>
+</svg>

dda_sdk/_assets/docs/data-freshness.md

@@ -0,0 +1,5 @@
+# Data Freshness
+
+Data is scraped once per day. The `portals` table includes a `latest_date` column showing the most recent date for which data has been received for each portal/platform/region combination - use it to check how current your data is before running an analysis.
+
+If you need more frequent scrapes, contact your IndieBI consultant.

dda_sdk/_assets/docs/getting-started.md

@@ -0,0 +1,36 @@
+# Getting Started
+
+## Download
+
+[Download dda-sdk.zip](https://dda-sdk-f2dee2.gitlab.io/dda-sdk.zip).
+
+## Prerequisites
+
+- [Python 3.12+](https://www.python.org/downloads/)
+- [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python package manager)
+- Access credentials from your IndieBI account (user ID and SAS token)
+
+## Setup
+
+Install dependencies by running in the project root:
+
+```bash
+uv sync
+```
+
+This installs everything the SDK needs. You only need to do this once (and again after any SDK update).
+
+## Configuration
+
+Create a `.env` file in your project root (you can copy existing `.env.example` file and substitute your credentials):
+
+```env
+USER_ID=your-user-id
+SAS_TOKEN=your-sas-token
+```
+
+## Next steps
+
+- [Use with Claude](use-with-claude.md) - prompt Claude to generate charts and analysis from your game data, no code required
+- [Write your own queries](querying-data.md) - connect directly via Python and build custom pipelines
+- [Tables & schema reference](schema-reference.md) - available tables and their column definitions

dda_sdk/_assets/docs/index.md

@@ -0,0 +1,27 @@
+# DDA SDK
+
+The DDA (Direct Data Access) SDK gives you direct access to IndieBI's data - sales, engagements, promotions, and more - from a single Python interface.
+
+Pull data from Steam, Nintendo, PlayStation, and other platforms without touching raw files or wrangling API tokens.
+
+## Why DDA v2 is a step change
+
+DDA v2 is built on the [Delta Lake](https://delta.io/) open table standard - the same format used by Databricks, Metabase, DuckDB, and many other tools your team may already use. That means you're not locked into a proprietary format: your data works wherever Delta tables work.
+
+A few things that make this a meaningful upgrade:
+
+- **One set of credentials, all your data** - whether you're a studio with a single title or a publisher managing dozens of partners, you access everything through a single connection. No juggling multiple logins or data exports.
+- **Connect the tools you already use** - because the data lives in an open format, you can point Databricks, Metabase, DuckDB UI, or your own notebooks directly at it without any extra wrangling.
+- **Always-fresh data, no interruptions** - in v1, a data refresh could cut off a download mid-flight. That's gone: reads and refreshes now happen independently, so your queries always complete cleanly.
+- **All your platforms, one dataset** - Steam, PlayStation, Nintendo, and more are merged into a single unified table. No more downloading separate exports and stitching them together; cross-platform comparisons and rollups just work.
+- **Fits into your existing workflow** - because it's an SDK, you can embed it in notebooks, scheduled pipelines, or BI tools rather than logging into a portal and clicking export. Your data, on your terms.
+
+## What's inside
+
+- **DuckDB connector** - low-latency queries against Delta Lake tables on Azure
+- **Polars connector** - lazy evaluation for large date ranges
+- **Typed schemas** - Pandera-validated DataFrames so you know exactly what columns you're working with
+
+## Quick links
+
+- [Getting Started](getting-started.md)

dda_sdk/_assets/docs/portal-support.md

@@ -0,0 +1,55 @@
+# Portal Support
+
+The SDK ingests data from the storefronts listed below. What data is available per portal depends on what each storefront exposes through its reporting API - not every portal provides the same metrics.
+
+To see the exact portal/platform/region combinations active in your account, query the [`portals`](schema-reference.md#portals) table:
+
+```python
+from dda_sdk import DuckDBClient, PortalsSchema
+
+with DuckDBClient() as client:
+    portals = client.query(PortalsSchema, "SELECT * FROM portals")
+
+print(portals.select(["portal", "platform", "region", "latest_date"]))
+```
+
+---
+
+## Supported portals
+
+| Platform | Data sources |
+|---|---|
+| Steam | Sales, Discounts, Store impressions, Wishlists, Wishlist balance |
+| Nintendo | Sales, Discounts, Wishlists |
+| PlayStation | Sales, GameHub sales, Wishlist actions |
+| Epic Games Store | Sales |
+| Microsoft | Sales |
+| GOG | Sales |
+| Humble | Sales |
+| Meta Quest | Sales |
+| Meta Rift | Sales |
+| Google | Sales |
+| Apple App Store | Sales |
+
+---
+
+## Discount data
+
+Promotional event data - discount depth, event name, start/end dates, and performance metrics — is available via the [`events`](schema-reference.md#events) table.
+
+| Portal | Method | Accuracy |
+|---|---|---|
+| Steam | Scraped directly | High |
+| Nintendo | Scraped directly | High |
+| Other Portals | Detected from revenue changes | Lower — may miss shallow or short discounts |
+
+**Scraped** portals provide exact discount depth and named events (e.g. `"Steam Summer Sale 2026"`). **Detected** portals infer a discount period from drops in revenue, so the timing and depth may be approximate, the event name is created, not reflecting what is set on the backend.
+
+Events populate the following columns in `events` table:
+
+- `event_name` - human-readable name of the sale (e.g. `"Steam Summer Sale 2026"`)
+- `discount` - discount depth as a 0–1 float (`0.40` = 40% off)
+- `date_from` / `date_to` - event window
+- `click_through_rate`, `conversion_rate`, `sales_uplift_score` - performance metrics (may be null if the portal does not report the underlying traffic data)
+
+See [schema reference → events](schema-reference.md#events) for the full column list.

dda_sdk/_assets/docs/querying-data.md

@@ -0,0 +1,85 @@
+# Querying Data
+
+## Interactive UI
+
+The quickest way to explore your data is the DuckDB web UI. It connects to your storage, registers all available tables, and opens a local SQL editor in the browser — no Python required beyond the initial launch.
+
+```bash
+uv run duckdb-ui
+```
+
+Opens `http://localhost:4213`. All tables are available immediately as views. Press Enter in the terminal to stop the server.
+
+---
+
+The SDK also exposes two clients for querying data programmatically. You can create a python file in `/projects` folder (see `/projects/explore.py` as example).
+
+## DuckDBClient
+
+Run SQL against your data and get back a validated Polars DataFrame. The best choice for straightforward queries.
+
+```python
+from dda_sdk import DuckDBClient, SalesPerSkuSchema
+
+with DuckDBClient() as client:
+    df = client.query(
+        SalesPerSkuSchema,
+        """
+        SELECT *
+        FROM sales_per_sku
+        WHERE date >= '2026-01-01'
+          AND date <= '2026-01-31'
+        """,
+    )
+
+print(df["gross_sales"].sum())
+```
+
+The schema class passed to `query()` validates the result - if a column is missing or has the wrong type, you get an error immediately rather than a silent wrong answer downstream.
+
+## PolarsClient
+
+Returns a `LazyFrame` - nothing is fetched until you call `.collect()`. Better for large date ranges or when you want to chain multiple transformations before pulling data.
+
+```python
+from dda_sdk import PolarsClient, SalesPerSkuSchema
+import polars as pl
+
+with PolarsClient() as client:
+    df = (
+        client.scan_table(SalesPerSkuSchema)
+        .filter(pl.col("date").is_between(pl.date(2026, 1, 1), pl.date(2026, 3, 31)))
+        .filter(pl.col("portal_platform_region").str.starts_with("Steam"))
+        .group_by(pl.col("date").dt.truncate("1mo"))
+        .agg(pl.col("gross_sales").sum())
+        .sort("date")
+        .collect()
+    )
+```
+
+You can also use SQL with `PolarsClient`:
+
+```python
+with PolarsClient() as client:
+    df = client.query(
+        "SELECT * FROM sales_per_sku WHERE date >= '2026-01-01'"
+    ).collect()
+```
+
+## Passing credentials explicitly
+
+Both clients read `USER_ID` and `SAS_TOKEN` from your `.env` by default. You can also pass them directly via `Config`:
+
+```python
+from dda_sdk.config import Config
+
+cfg = Config(user_id="u-xxxxx", sas_token="<your-sas-token>")
+
+with DuckDBClient(cfg) as client:
+    ...
+
+with PolarsClient(cfg) as client:
+    ...
+```
+
+This is useful when running against a different storage account or when credentials come from a secret manager rather than a `.env` file.