@pinta365/strava 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pinta <https://github.com/Pinta365>
+
+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.

package/README.md

@@ -0,0 +1,390 @@
+# @pinta365/strava
+
+A cross-runtime TypeScript client for the Strava API v3. Works on Deno, Node.js (18+), Bun, and browsers.
+
+## Features
+
+- ✅ **Type-safe**: Full TypeScript support with generated types from Swagger specification
+- ✅ **Cross-runtime**: Works on Deno, Node.js, Bun, and browsers
+- ✅ **OAuth 2.0**: Complete authentication flow with automatic token refresh
+- ✅ **Rate limiting**: Built-in rate limit handling and queue management
+- ✅ **Request optimization**: Automatic request deduplication and retry logic
+- ✅ **Opinionated helpers**: Key normalization (snake_case → camelCase), date transformations, response flattening, computed fields
+- ✅ **Pagination**: Auto-pagination iterators for easy data fetching
+
+## Installation
+
+### Deno
+
+```typescript
+import { StravaClient } from "https://deno.land/x/strava/mod.ts";
+```
+
+### Node.js / Bun
+
+```bash
+npm install @pinta365/strava
+```
+
+```typescript
+import { StravaClient } from "@pinta365/strava";
+```
+
+## Quick Start
+
+### 1. Generate Types (First Time)
+
+Before using the library, generate TypeScript types from the Strava API specification:
+
+```bash
+deno task generate:types
+```
+
+### 2. Create Client
+
+```typescript
+import { StravaClient } from "@pinta365/strava";
+
+const client = new StravaClient({
+    clientId: "your-client-id",
+    clientSecret: "your-client-secret",
+    redirectUri: "https://yourapp.com/callback",
+});
+```
+
+### 3. Authenticate
+
+```typescript
+// Get authorization URL
+const authUrl = client.getAuthorizationUrl({
+    scope: ["activity:read_all", "profile:read_all"],
+    state: "optional-csrf-token",
+});
+
+// Redirect user to authUrl
+// After user authorizes, Strava redirects to your redirectUri with a code
+
+// Exchange code for tokens
+await client.authenticate({
+    code: "authorization-code-from-redirect",
+});
+```
+
+### 4. Use the API
+
+```typescript
+// Get authenticated athlete
+const athlete = await client.athletes.get();
+
+// Get activity by ID
+const activity = await client.activities.getById(123456);
+
+// Analyze activity with comprehensive data (zones, laps, best efforts, analysis)
+const analysis = await client.activities.analyze(123456, {
+    includeStreams: false, // Optional: include stream data
+});
+
+// Get athlete stats with recent activities and gear
+const profile = await client.athletes.getStatsWithActivities(athleteId, {
+    recentActivitiesLimit: 10,
+    includeGear: true,
+});
+
+// List activities with auto-pagination
+for await (const activity of client.activities.listAll()) {
+    console.log(activity.name);
+}
+
+// Get activity with all details
+const details = await client.activities.getWithDetails(123456);
+// Returns: activity + laps + zones + comments + kudoers
+
+// Get activity streams
+const streams = await client.streams.getForActivity(123456, {
+    types: ["time", "distance", "latlng", "altitude", "heartrate"],
+});
+
+// Clean up resources when done (important for long-running processes)
+client.destroy();
+```
+
+## Configuration
+
+### Client Options
+
+```typescript
+const client = new StravaClient({
+    clientId: "your-client-id",
+    clientSecret: "your-client-secret",
+    redirectUri: "https://yourapp.com/callback",
+
+    // Token storage (auto-detected by default)
+    tokenStore: new FileSystemTokenStore("./tokens.json"),
+
+    // HTTP options
+    baseUrl: "https://www.strava.com/api/v3",
+    timeout: 30000,
+
+    // Retry configuration
+    retries: {
+        maxAttempts: 3,
+        initialDelay: 1000,
+        maxDelay: 10000,
+        backoffFactor: 2,
+    },
+
+    // Rate limit strategy
+    rateLimitStrategy: "queue", // 'queue' | 'throw' | 'wait'
+
+    // Request deduplication
+    deduplicationWindow: 5000, // milliseconds
+
+    // Response transformations
+    normalizeKeys: true, // Convert snake_case to camelCase (default: true)
+    transformDates: true, // Convert ISO strings to Date objects (default: true)
+    flattenResponses: true, // Flatten nested structures (default: true)
+    addComputedFields: true, // Add computed properties (see below) (default: true)
+});
+```
+
+### Token Storage
+
+The library automatically selects an appropriate token store based on the runtime:
+
+- **Browser**: `LocalStorageTokenStore`
+- **Node.js/Deno**: `FileSystemTokenStore`
+- **Other**: `MemoryTokenStore`
+
+You can also provide a custom token store:
+
+```typescript
+import { TokenData, TokenStore } from "@pinta365/strava";
+
+class CustomTokenStore implements TokenStore {
+    async get(): Promise<TokenData | null> {
+        // Load from your storage
+    }
+
+    async set(token: TokenData): Promise<void> {
+        // Save to your storage
+    }
+
+    async clear(): Promise<void> {
+        // Clear from your storage
+    }
+}
+
+const client = new StravaClient({
+    clientId: "...",
+    clientSecret: "...",
+    tokenStore: new CustomTokenStore(),
+});
+```
+
+## Response Transformations
+
+The library applies opinionated transformations to API responses by default. These can be controlled via client options:
+
+### Key Normalization (`normalizeKeys`)
+
+Converts snake_case keys from the API to camelCase for JavaScript/TypeScript conventions:
+
+```typescript
+// API returns: { start_date_local: "...", athlete_id: 123 }
+// Library returns: { startDateLocal: "...", athleteId: 123 }
+```
+
+### Date Transformation (`transformDates`)
+
+Converts ISO date strings to JavaScript `Date` objects:
+
+```typescript
+// API returns: { startDateLocal: "2024-01-15T10:30:00Z" }
+// Library returns: { startDateLocal: Date("2024-01-15T10:30:00Z") }
+```
+
+### Response Flattening (`flattenResponses`)
+
+Flattens nested objects to the top level for easier access:
+
+```typescript
+// API returns: { athlete: { id: 123, firstname: "John" } }
+// Library returns: { athlete: { id: 123, firstname: "John" }, athleteId: 123, athleteFirstname: "John" }
+```
+
+### Computed Fields (`addComputedFields`)
+
+Adds computed properties to activity objects for convenience:
+
+#### For All Activities:
+
+- **`averageSpeed`** (number, m/s): `distance / movingTime`
+- **`averageSpeedKmh`** (number, km/h): `(distance / 1000) / (movingTime / 3600)`
+- **`duration`** (object):
+  - `seconds`: Raw time in seconds
+  - `minutes`: `Math.floor(time / 60)`
+  - `hours`: `Math.floor(time / 3600)`
+  - `formatted`: Human-readable string (e.g., "1:23:45" or "23:45")
+
+#### For Run Activities Only:
+
+- **`pace`** (string): Formatted as "min:sec/km" (e.g., "5:30/km")
+
+Example:
+
+```typescript
+const activity = await client.activities.getById(123456);
+
+// Computed fields available:
+console.log(activity.averageSpeed); // 3.5 (m/s)
+console.log(activity.averageSpeedKmh); // 12.6 (km/h)
+console.log(activity.pace); // "5:30/km" (if it's a Run)
+console.log(activity.duration.formatted); // "1:23:45"
+console.log(activity.duration.hours); // 1
+```
+
+## Cleanup
+
+When you're done with the client (especially in long-running processes or scripts), call `destroy()` to clean up resources and allow the process to
+exit:
+
+```typescript
+// After all API calls are complete
+client.destroy();
+```
+
+This clears internal timers and caches, which is important for scripts that should exit automatically.
+
+## Resources
+
+The client provides resource namespaces for different API endpoints:
+
+- `client.athletes` - Athlete information and stats
+- `client.activities` - Activity CRUD and operations
+- `client.segments` - Segment information and exploration
+- `client.segmentEfforts` - Segment effort data
+- `client.clubs` - Club information and members
+- `client.gears` - Gear information
+- `client.routes` - Route information and downloads
+- `client.uploads` - Activity file uploads
+- `client.streams` - Activity, segment, and route streams
+
+### Opinionated Helpers
+
+The library provides opinionated helper methods that combine multiple API calls for convenience:
+
+#### Activity Analysis
+
+Analyze an activity with comprehensive data including zones, laps, best efforts, and computed insights:
+
+```typescript
+const analysis = await client.activities.analyze(activityId, {
+    includeStreams: false, // Optional: include stream data (may require premium)
+    streamTypes: ["heartrate", "watts", "cadence"], // Optional: specific stream types
+});
+
+// Analysis includes:
+// - Full activity details
+// - Zones (power/heart rate)
+// - Laps
+// - Best efforts (segment efforts)
+// - Optional streams
+// - Computed analysis:
+//   - hasPowerData: boolean
+//   - hasHeartRateData: boolean
+//   - totalLaps: number
+//   - bestEffortCount: number
+//   - averageLapTime: number (seconds)
+//   - averageLapDistance: number (meters)
+```
+
+#### Activity Details
+
+Get activity with all related data (laps, zones, comments, kudoers):
+
+```typescript
+const details = await client.activities.getWithDetails(activityId);
+// Returns: activity + laps + zones + comments + kudoers
+```
+
+#### Athlete Profile with Stats
+
+Get comprehensive athlete profile including stats, recent activities, and gear:
+
+```typescript
+const profile = await client.athletes.getStatsWithActivities(athleteId, {
+    recentActivitiesLimit: 10, // Number of recent activities to fetch
+    includeGear: true, // Include detailed gear information (bikes + shoes)
+});
+
+// Profile includes:
+// - Full athlete details
+// - Activity stats (totals, PRs, etc.)
+// - Recent activities array
+// - Gear details (optional)
+```
+
+## Error Handling
+
+The library provides custom error classes:
+
+```typescript
+import { StravaAuthError, StravaError, StravaNotFoundError, StravaRateLimitError, StravaServerError, StravaValidationError } from "@pinta365/strava";
+
+try {
+    const activity = await client.activities.getById(123);
+} catch (error) {
+    if (error instanceof StravaNotFoundError) {
+        console.log("Activity not found");
+    } else if (error instanceof StravaRateLimitError) {
+        console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);
+    } else if (error instanceof StravaAuthError) {
+        console.log("Authentication failed");
+    }
+}
+```
+
+## OAuth Scopes
+
+Available scopes:
+
+- `read` - Read public segments, public routes, public profile data, public posts, public events, club feeds, and leaderboards
+- `read_all` - Read private routes, private segments, and private events for the user
+- `profile:read_all` - Read all profile information even if the user has set their profile visibility to Followers or Only You
+- `profile:write` - Update the user's weight and Functional Threshold Power (FTP), and access to star or unstar segments on their behalf
+- `activity:read` - Read the user's activity data for activities that are visible to Everyone and Followers, excluding privacy zone data
+- `activity:read_all` - The same access as `activity:read`, plus privacy zone data and access to read the user's activities with visibility set to
+  Only You
+- `activity:write` - Access to create manual activities and uploads, and access to edit any activities that are visible to the app, based on activity
+  read access level
+
+## Development
+
+### Generate Types
+
+```bash
+deno task generate:types
+```
+
+### Run Tests
+
+```bash
+deno test -A
+```
+
+### Format and Lint
+
+```bash
+deno fmt
+deno lint
+```
+
+### Pre-push Validation
+
+```bash
+deno task prepush
+```
+
+## License
+
+MIT

package/esm/_dnt.shims.d.ts

@@ -0,0 +1,2 @@
+export declare const dntGlobalThis: Omit<typeof globalThis, never>;
+//# sourceMappingURL=_dnt.shims.d.ts.map

package/esm/_dnt.shims.js

@@ -0,0 +1,57 @@
+const dntGlobals = {};
+export const dntGlobalThis = createMergeProxy(globalThis, dntGlobals);
+function createMergeProxy(baseObj, extObj) {
+    return new Proxy(baseObj, {
+        get(_target, prop, _receiver) {
+            if (prop in extObj) {
+                return extObj[prop];
+            }
+            else {
+                return baseObj[prop];
+            }
+        },
+        set(_target, prop, value) {
+            if (prop in extObj) {
+                delete extObj[prop];
+            }
+            baseObj[prop] = value;
+            return true;
+        },
+        deleteProperty(_target, prop) {
+            let success = false;
+            if (prop in extObj) {
+                delete extObj[prop];
+                success = true;
+            }
+            if (prop in baseObj) {
+                delete baseObj[prop];
+                success = true;
+            }
+            return success;
+        },
+        ownKeys(_target) {
+            const baseKeys = Reflect.ownKeys(baseObj);
+            const extKeys = Reflect.ownKeys(extObj);
+            const extKeysSet = new Set(extKeys);
+            return [...baseKeys.filter((k) => !extKeysSet.has(k)), ...extKeys];
+        },
+        defineProperty(_target, prop, desc) {
+            if (prop in extObj) {
+                delete extObj[prop];
+            }
+            Reflect.defineProperty(baseObj, prop, desc);
+            return true;
+        },
+        getOwnPropertyDescriptor(_target, prop) {
+            if (prop in extObj) {
+                return Reflect.getOwnPropertyDescriptor(extObj, prop);
+            }
+            else {
+                return Reflect.getOwnPropertyDescriptor(baseObj, prop);
+            }
+        },
+        has(_target, prop) {
+            return prop in extObj || prop in baseObj;
+        },
+    });
+}

package/esm/deps/jsr.io/@cross/runtime/1.2.1/mod.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Enum of supported Runtimes.
+ * @enum {string}
+ */
+export declare enum Runtime {
+    Deno = "deno",
+    Bun = "bun",
+    Node = "node",
+    Browser = "browser",
+    Tauri = "tauri",
+    Workerd = "workerd",
+    Netlify = "netlify",
+    EdgeLight = "edgelight",
+    Fastly = "fastly",
+    Unsupported = "unsupported"
+}
+/**
+ * Enum of supported Operating Systems.
+ * @enum {string}
+ */
+export declare enum OperatingSystem {
+    Windows = "windows",
+    macOS = "macos",
+    Linux = "linux",
+    Android = "android",
+    Unix = "unix",
+    iOS = "ios",
+    Unsupported = "unsupported"
+}
+/**
+ * Enum of supported Products.
+ * @enum {string}
+ */
+export declare enum Product {
+    Deno = "deno",
+    Bun = "bun",
+    Node = "node",
+    Tauri = "tauri",
+    Workerd = "workerd",
+    Netlify = "netlify",
+    EdgeLight = "edgelight",
+    Fastly = "fastly",
+    Firefox = "firefox",
+    Safari = "safari",
+    Chrome = "chrome",
+    Edge = "edge",
+    Opera = "opera",
+    Brave = "brave",
+    Unsupported = "unsupported"
+}
+/**
+ * Enum of common CPU architectures.
+ * @enum {string}
+ */
+export declare enum Architecture {
+    x86 = "x86",
+    x64 = "x86_64",
+    arm = "arm",
+    arm64 = "arm64",
+    Unsupported = "unsupported"
+}
+/**
+ * Dynamically determines the current runtime environment.
+ */
+export declare function getCurrentRuntime(): Runtime;
+/**
+ * Dynamically determines the current operating system.
+ */
+export declare function getCurrentOS(): OperatingSystem;
+/**
+ * Determine operating system from user agent string, if possible
+ */
+export declare function getOSFromUserAgent(userAgent: string): OperatingSystem;
+/**
+ * Dynamically determines the current browser and its version (if applicable).
+ */
+export declare function getCurrentProduct(): Product;
+/**
+ * Determines the product from a user agent string, if possible
+ */
+export declare function getProductFromUserAgent(userAgent: string): Product;
+/**
+ * Dynamically determines the version of the current product/runtime
+ * @returns {string} A string containing the detected version, or undefined if the product is not supported.
+ */
+export declare function getCurrentVersion(): string | undefined;
+/**
+ * Determines the product version from a user agent string, if possible
+ */
+export declare function getVersionFromUserAgent(userAgent: string): string | undefined;
+/**
+ * Attempts to determine the current CPU architecture of the runtime's environment.
+ */
+export declare function getCurrentArchitecture(): Architecture;
+/**
+ * Logs current system information to the console.
+ *
+ * @param {boolean} [useTable=false] - If true, formats the output as a table.
+ */
+export declare function dumpSystemInfo(useTable?: boolean): void;
+/**
+ * Gets the current system information as a formatted JSON string.
+ * @returns {string}
+ */
+export declare function getSystemInfo(): string;
+/**
+ * Static variable containing the current runtime.
+ */
+export declare const CurrentRuntime: Runtime;
+/**
+ * Static variable containing the current product.
+ */
+export declare const CurrentProduct: Product;
+/**
+ * Static variable containing the current product/runtime version.
+ */
+export declare const CurrentVersion: string | undefined;
+/**
+ * Static variable containing the current operating system.
+ */
+export declare const CurrentOS: OperatingSystem | undefined;
+/**
+ * Static variable containing the current operating system.
+ */
+export declare const CurrentArchitecture: Architecture | undefined;
+//# sourceMappingURL=mod.d.ts.map