sweatstack-cli 0.5.0__tar.gz → 0.7.0__tar.gz

{sweatstack_cli-0.5.0 → sweatstack_cli-0.7.0}/.claude/settings.local.json

@@ -18,7 +18,8 @@
       "Bash(make help:*)",
       "Bash(tree:*)",
       "Bash(env:*)",
-      "Bash(uv run python:*)"
+      "Bash(uv run python:*)",
+      "Bash(git:*)"
     ]
   }
 }

sweatstack_cli-0.7.0/.claude/skills/sweatstack/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: sweatstack
+description: Builds applications integrating with SweatStack sports data platform. Provides OAuth PKCE authentication, API endpoints, and patterns for single-file HTML web apps. Use when building fitness dashboards, athletic data tools, or apps using SweatStack.
+---
+
+# SweatStack
+
+Sports data platform providing auth, storage, and wearable integrations for developers.
+
+**Base URL:** `https://app.sweatstack.no`
+
+**Default scopes:** `openid profile data:read`
+
+## Reference
+
+**Webapps:** Single-file HTML apps with vanilla JS. See [webapp.md](webapp.md)
+
+**PyScript webapps:** Python data science in the browser (pandas, sklearn, scipy). Trade-offs and template. See [pyscript.md](pyscript.md)
+
+**CLI:** App management and deployment. See [cli.md](cli.md)
+
+**Auth:** OAuth2/PKCE authentication. See [auth.md](auth.md)
+
+**API:** Endpoints and data formats. See [api.md](api.md)

sweatstack_cli-0.7.0/.claude/skills/sweatstack/api.md

@@ -0,0 +1,170 @@
+# SweatStack API Reference
+
+## Contents
+
+- [Endpoints](#endpoints)
+- [Choosing the Right Endpoint](#choosing-the-right-endpoint)
+- [Data Fetching Patterns](#data-fetching-patterns)
+- [Parquet Responses](#parquet-responses)
+- [Metrics Parameter](#metrics-parameter)
+- [Available Metrics](#available-metrics)
+- [GPS Data](#gps-data)
+- [Sports](#sports)
+- [Authentication](#authentication)
+
+---
+
+**Base URL:** `https://app.sweatstack.no`
+
+**OpenAPI spec:** https://app.sweatstack.no/openapi.json
+
+**IMPORTANT: Before making any API call, fetch the OpenAPI spec to verify:**
+- Valid enum values (e.g. sports use hierarchical format like `walking.hiking`, not `hiking`)
+- Required vs optional parameters
+- Response schemas — look up the specific schema (e.g., `ActivityRead`) before accessing fields
+
+Never guess field names or enum values. The spec is the source of truth.
+
+## Common Gotchas
+
+**Activity timestamps:** Use `start` (UTC) or `start_local` (user's local time). Not `start_time`, `started_at`, or `timestamp`.
+
+**Key activity fields:** `id`, `start`, `start_local`, `sport`, `duration`, `name`, `description`
+
+**Date parameters:** Use `YYYY-MM-DD` format. Most endpoints reject timestamps.
+
+**Parameter naming:** Longitudinal endpoints use `sports` (plural), activity list uses `sport` (singular).
+
+## Endpoints
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/api/v1/activities/` | GET | List activities (filter: sport, tags, start, end) |
+| `/api/v1/activities/{id}` | GET | Get activity details |
+| `/api/v1/activities/{id}/data` | GET | Timeseries data (returns Parquet) |
+| `/api/v1/activities/latest` | GET | Most recent activity |
+| `/api/v1/activities/upload` | POST | Upload .fit files (max 10) |
+| `/api/v1/profile/tags/` | GET | User-defined tags |
+| `/api/v1/profile/sports/` | GET | Available sports hierarchy |
+| `/api/v1/activities/longitudinal-data` | GET | Timeseries data across activities. Allows extensive filtering on sports and metrics. (returns Parquet) |
+| `/api/v1/activities/longitudinal-mean-max` | GET | Historical mean-max (returns Parquet) |
+| `/api/v1/oauth/userinfo` | GET | Current user info |
+
+**Critical**: Never guess request paramaters or body schemas. Use the openapi.json when not sure.
+
+## Choosing the Right Endpoint
+
+**Multi-activity analysis** (trends, distributions, comparisons): Use `/activities/longitudinal-data` — one request for all matching activities.
+
+**Single activity** (detail view, route map): Use `/activities/{id}/data`.
+
+## Data Fetching Patterns
+
+**Time window comparisons:** Fetch the larger window once, filter client-side. Avoid multiple requests for overlapping or adjacent ranges.
+
+**Bulk activity data:** Need data from many activities? Use `/activities/longitudinal-data` with filters instead of looping through `/activities/{id}/data` — one request vs N.
+
+**Per-activity stats:** Longitudinal endpoints return raw samples with `activity_id`. Use DuckDB to aggregate: `GROUP BY activity_id`.
+
+## Parquet Responses
+
+Data endpoints return **Parquet files (snappy-compressed)**. Your Parquet library must support snappy codec.
+
+**Browser apps:** Use DuckDB-WASM (recommended - full codec support, reliable CDN).
+
+**Other environments:** Any Parquet library with snappy support.
+
+### DuckDB-WASM Setup (browser)
+
+```javascript
+import * as duckdb from 'https://cdn.jsdelivr.net/npm/@duckdb/duckdb-wasm@1.28.0/+esm';
+
+const JSDELIVR_BUNDLES = duckdb.getJsDelivrBundles();
+const bundle = await duckdb.selectBundle(JSDELIVR_BUNDLES);
+const worker_url = URL.createObjectURL(
+    new Blob([`importScripts("${bundle.mainWorker}");`], { type: 'text/javascript' })
+);
+const worker = new Worker(worker_url);
+const logger = new duckdb.ConsoleLogger();
+const db = new duckdb.AsyncDuckDB(logger, worker);
+await db.instantiate(bundle.mainModule, bundle.pthreadWorker);
+URL.revokeObjectURL(worker_url);
+```
+
+### Parsing Parquet
+
+```javascript
+async function parseParquet(arrayBuffer) {
+    const uint8 = new Uint8Array(arrayBuffer);
+    await db.registerFileBuffer('data.parquet', uint8);
+    const conn = await db.connect();
+    const result = await conn.query('SELECT * FROM "data.parquet"');
+
+    const data = {};
+    for (const field of result.schema.fields) {
+        data[field.name] = result.getChild(field.name).toArray();
+    }
+    await conn.close();
+    return data;
+}
+
+// Usage
+const response = await fetch(`${API_BASE}/activities/${id}/data?metrics=altitude&metrics=distance`, {
+    headers: { 'Authorization': `Bearer ${token}` }
+});
+const data = await parseParquet(await response.arrayBuffer());
+// data = { altitude: [...], distance: [...] }
+```
+
+**Note:** DuckDB-WASM is ~10MB but reliable. Other browser libraries (parquet-wasm, hyparquet) have codec or CDN issues.
+
+## Metrics Parameter
+
+Pass multiple times for multiple metrics:
+
+```
+?metrics=altitude&metrics=distance    ✓
+?metrics=altitude,distance            ✗
+```
+
+## Available Metrics
+
+duration, power, speed, heart_rate, cadence, altitude, latitude, longitude, temperature, core_temperature, smo2, distance, lactate, RPE
+
+## GPS Data
+
+Filter invalid coordinates:
+
+```javascript
+function isValidGPS(lat, lon) {
+    if (!Number.isFinite(lat) || !Number.isFinite(lon)) return false;
+    if (lat < -90 || lat > 90) return false;
+    if (lon < -180 || lon > 180) return false;
+
+    const EPSILON = 1e-6;
+    if (Math.abs(lat) < EPSILON && Math.abs(lon) < EPSILON) return false;
+
+    return true;
+}
+```
+
+Catches NaN (from null values), Null Island (0, 0), and garbage floats.
+
+## Sports
+
+**Formatting sport values for display:**
+
+```javascript
+function formatSport(sport) {
+    const parts = sport.split(".");
+    const base = parts[0].replace(/_/g, " ");
+    if (parts.length === 1) return base;
+    const rest = parts.slice(1).join(" ").replace(/_/g, " ");
+    return `${base} (${rest})`;
+}
+// "cycling.mountain" → "cycling (mountain)"
+```
+
+## Authentication
+
+All endpoints require `Authorization: Bearer TOKEN` header.

sweatstack_cli-0.7.0/.claude/skills/sweatstack/auth.md

@@ -0,0 +1,136 @@
+# OAuth2/OpenID Authentication
+
+## Contents
+
+- [Endpoints](#endpoints)
+- [Scopes](#scopes)
+- [PKCE Flow](#pkce-flow-public-clients)
+- [Authorization Code Flow](#authorization-code-flow-private-clients)
+- [Token Exchange](#token-exchange)
+- [Refresh Tokens](#refresh-tokens)
+- [API Authentication](#api-authentication)
+
+---
+
+## Endpoints
+
+| Endpoint | URL |
+|----------|-----|
+| Authorization | `https://app.sweatstack.no/oauth/authorize` |
+| Token | `https://app.sweatstack.no/api/v1/oauth/token` |
+
+## Scopes
+
+| Scope | Purpose |
+|-------|---------|
+| `openid` | OpenID Connect (currently unused by SweatStack) |
+| `profile` | Access to profile information |
+| `data:read` | Read access to user data |
+| `data:write` | Write and delete access (no read) |
+| `offline_access` | Refresh token for public clients |
+
+**Default:** `openid profile data:read`
+
+## PKCE Flow (Public Clients)
+
+For browser apps, mobile apps, and other public clients without a client secret.
+
+### 1. Generate PKCE pair
+
+- Code verifier: random string (43-128 chars)
+- Code challenge: base64url(SHA-256(verifier))
+
+### 2. Redirect to authorize
+
+```
+https://app.sweatstack.no/oauth/authorize?
+  client_id=CLIENT_ID&
+  redirect_uri=REDIRECT_URI&
+  response_type=code&
+  scope=openid%20profile%20data:read&
+  code_challenge=CHALLENGE&
+  code_challenge_method=S256&
+  prompt=none
+```
+
+**Critical:** Include `prompt=none` to avoid double consent screens.
+
+### 3. Exchange code for token
+
+```
+POST https://app.sweatstack.no/api/v1/oauth/token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=authorization_code&
+code=AUTH_CODE&
+redirect_uri=REDIRECT_URI&
+client_id=CLIENT_ID&
+code_verifier=VERIFIER
+```
+
+## Authorization Code Flow (Private Clients)
+
+For server-side apps with a client secret.
+
+### 1. Redirect to authorize
+
+```
+https://app.sweatstack.no/oauth/authorize?
+  client_id=CLIENT_ID&
+  redirect_uri=REDIRECT_URI&
+  response_type=code&
+  scope=openid%20profile%20data:read&
+  prompt=none
+```
+
+### 2. Exchange code for token
+
+```
+POST https://app.sweatstack.no/api/v1/oauth/token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=authorization_code&
+code=AUTH_CODE&
+redirect_uri=REDIRECT_URI&
+client_id=CLIENT_ID&
+client_secret=CLIENT_SECRET
+```
+
+## Token Exchange
+
+**Response:**
+```json
+{
+  "access_token": "...",
+  "token_type": "Bearer",
+  "expires_in": 3600,
+  "refresh_token": "...",
+  "scope": "openid profile data:read"
+}
+```
+
+- `refresh_token` included automatically for private clients
+- Public clients must request `offline_access` scope
+
+## Refresh Tokens
+
+Exchange a refresh token for a new access token:
+
+```
+POST https://app.sweatstack.no/api/v1/oauth/token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=refresh_token&
+refresh_token=REFRESH_TOKEN&
+client_id=CLIENT_ID
+```
+
+For private clients, include `client_secret`.
+
+## API Authentication
+
+All API requests require the Authorization header:
+
+```
+Authorization: Bearer ACCESS_TOKEN
+```

sweatstack_cli-0.7.0/.claude/skills/sweatstack/cli.md

@@ -0,0 +1,70 @@
+# SweatStack CLI
+
+Command-line tool for authentication, app management, and static deployments.
+
+## Installation
+
+**macOS/Linux:**
+```bash
+curl -LsSf sweatstack.no/install-cli | sh
+```
+
+**Windows:**
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm sweatstack.no/install-cli-windows | iex"
+```
+
+Verify with `sweatstack --version`. Alternative: `uv pip install sweatstack-cli`
+
+## Authentication
+
+```bash
+sweatstack login     # Opens browser for OAuth2, stores credentials locally
+sweatstack logout    # Remove stored credentials
+sweatstack status    # Show auth status and token details
+```
+
+Always `sweatstack status` to check if the user is authenticated.
+
+## Create Applications
+
+```bash
+sweatstack app create "My App"
+```
+
+**Options:**
+
+| Flag | Purpose |
+|------|---------|
+| `--page myapp` | Associate with a SweatStack Page (auto-configures redirect URI) |
+| `--secret` | Generate client secret for confidential clients |
+| `--env` | Write credentials to `.env` file |
+| `--env-file PATH` | Write credentials to specific file |
+| `--json` | Output as JSON for scripting |
+
+**Full example:**
+```bash
+sweatstack app create "My Streamlit App" --page my-streamlit-app --secret --env-file .env.local
+```
+
+Creates a private application. Public apps require the web dashboard. Page slugs can be rejected if unavailable.
+
+## Deploy Static Sites
+
+```bash
+sweatstack page deploy myapp ./dist
+```
+
+Uploads files to `https://myapp.sweatstack.pages.dev`.
+
+**Constraints:**
+- Pages must be pre-created via dashboard: https://app.sweatstack.no/settings/api
+- 10MB limit per app
+
+## Help
+
+```bash
+sweatstack --help
+sweatstack app --help
+sweatstack app create --help
+```

sweatstack_cli-0.7.0/.claude/skills/sweatstack/pyscript.md

@@ -0,0 +1,33 @@
+# PyScript Web Apps
+
+Use when the user needs Python data science libraries (pandas, numpy, scikit-learn, scipy, matplotlib) in the browser. No backend — static deployment.
+
+## Trade-offs vs Vanilla JS Webapp
+
+| | PyScript | Vanilla JS ([webapp.md](webapp.md)) |
+|---|---|---|
+| **Best for** | Data analysis, ML, statistical computing | Dashboards, visualizations, simple data display |
+| **Libraries** | Full Python ecosystem via Pyodide | Browser JS only |
+| **Cold start** | 10-20s (loading Pyodide + packages) | Instant |
+| **Computation** | Client-side Python (slower than native) | Client-side JS (fast) |
+
+Confirm with user before choosing PyScript — the cold start is significant.
+
+## Template
+
+**Repo:** https://github.com/sweatstack/sweatstack-pyscript-template
+
+Clone the template to start. The README covers setup, the ctx API, parameter patterns, examples, and deployment.
+
+## Workflow
+
+1. Clone the template repo
+2. Register an OAuth app with `sweatstack auth register`
+3. Set Client ID in `index.html`
+4. Write analysis logic in `main.py`
+5. Deploy with `sweatstack apps deploy`
+
+## Key Constraints
+
+- **Only edit `main.py` and `index.html`.** Do not generate or modify `app.js`, `worker.py`, `runtime.py`, CSS, or `mini-coi.js` — these are framework files maintained by the template.
+- The template includes 4 working examples (`examples/`) — use these as reference for different patterns (single activity, multi-parameter, ML pipelines).

sweatstack_cli-0.7.0/.claude/skills/sweatstack/webapp.md

@@ -0,0 +1,138 @@
+# Building Single-File Web Apps
+
+## Contents
+
+- [Tech Stack](#tech-stack)
+- [Output Location](#output-location)
+- [Quality Bar](#quality-bar)
+- [Prerequisites](#prerequisites)
+- [Authentication](#authentication)
+- [HTML Structure](#html-structure)
+- [Default Styling](#default-styling)
+- [SweatStack Branding](#sweatstack-branding)
+- [After Generation](#after-generation)
+- [Reference Apps](#reference-apps)
+
+---
+
+## Tech Stack
+
+- Single HTML file with inline `<style>` and `<script>`
+- Vanilla JS only (no React, no build step)
+- CDN dependencies when needed (e.g., html2canvas for sharing)
+- localStorage for access token and user preferences
+- DuckDB-WASM for Parquet parsing (supports full SQL for analytics)
+
+## Output Location
+
+Place generated files in `public/index.html`. Creates a deployment-ready structure.
+
+## Quality Bar
+
+UI can be minimal - focus on functionality. Auth and API error handling must be solid: handle 401s, show clear error states, never fail silently.
+
+## Prerequisites
+
+Requires a **Client ID** from a SweatStack application.
+
+**If user provides a client_id:** Use it directly, skip app creation.
+
+**Otherwise, create an app with the SweatStack CLI:**
+1. Derive app name from the task (e.g., "heart rate analyzer" → "Heart Rate Analyzer")
+2. Generate page slug from app name: lowercase, spaces to hyphens (e.g., "heart-rate-analyzer")
+3. Create the app with the sweatstack cli
+4. If slug is rejected, prompt user for alternative
+
+Prompt user for app name only if it cannot be reasonably inferred from the task.
+
+## Authentication
+
+Browser apps use PKCE flow (public client, no client secret).
+
+**Critical:** Always include `prompt=none` in auth redirects to avoid double consent screens.
+
+**Token storage:** Use localStorage. Store `access_token` and expiry timestamp.
+
+**On page load:** No token → show login. Expired token → silent re-auth with `prompt=none`.
+
+**On 401:** Silent re-auth with `prompt=none`.
+
+**Constants to define:**
+```javascript
+const CLIENT_ID = '...';
+const REDIRECT_URI = window.location.origin + window.location.pathname; // Works for localhost and production
+const AUTH_URL = 'https://app.sweatstack.no/oauth/authorize';
+const TOKEN_URL = 'https://app.sweatstack.no/api/v1/oauth/token';
+const API_BASE = 'https://app.sweatstack.no/api/v1';
+```
+
+## HTML Structure
+
+- Auth container (login button): shown when no token
+- App container (main UI): shown after authentication
+
+## Default Styling
+
+Use only when user doesn't specify styling preferences.
+
+**Aesthetic direction:** Minimal and clean. Think scientific paper, not dashboard.
+
+**Layout:**
+- Centered container, `max-width: 48rem`
+- Visual elements fill container width
+- Full-width only for apps that are primarily visual (e.g., mapping app)
+
+**Styling:**
+- Clear heading hierarchy with generous whitespace
+- Light background, dark text
+- Everything flows vertically — no sidebars, no cards, no visual clutter
+
+**Typography:** System fonts are acceptable for minimal aesthetic. If choosing a web font, make it intentional — one distinctive font, not generic defaults like Inter or Roboto.
+
+**What to avoid:** Generic "AI slop" — purple gradients, card-heavy layouts, excessive shadows, decorative elements that add no meaning. Minimalism requires precision in spacing and typography, not decoration.
+
+## SweatStack Branding
+
+**Login page content:**
+- Brief explanation of what the app does
+- Text explaining the app uses SweatStack to access sports data (e.g., "This app connects to SweatStack to access your workout data")
+
+**Login button** (Norwegian flag red):
+
+```html
+<button onclick="startAuth()" style="
+    background: #EF2B2D;
+    color: white;
+    border: none;
+    padding: 0.75rem 1.5rem;
+    font-size: 1rem;
+    border-radius: 4px;
+    cursor: pointer;
+">Connect with SweatStack</button>
+```
+
+**Logout button:** Top right of main content area (not viewport). Clears sessionStorage and returns to login view.
+
+**Footer** (always present):
+
+```html
+<footer style="color: #666; font-size: 0.875rem; text-align: center; margin-top: 3rem;">
+    Powered by <a href="https://sweatstack.no" style="color: #666;">SweatStack</a> ·
+    Built with <a href="https://github.com/sweatStack/sweatstack-skills" style="color: #666;">Skills</a>
+</footer>
+```
+
+## After Generation
+
+**Preview locally:** Suggest user start a local file server in the `public/` directory.
+
+**Next steps to mention:**
+- **Deploy to the web:** `sweatstack page deploy <slug> ./public`
+- **Make available to other users:** Add privacy policy and app description at `https://app.sweatstack.no/applications/{APP_ID}`
+
+## Reference Apps
+
+Study these for patterns:
+
+- **graph.sweatstack.no** - Activity contribution graph
+- **zones.sweatstack.no** - Training zone calculator