@pinta365/strava 0.0.1 → 0.0.3

package/LICENSE

@@ -1,21 +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.
+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

@@ -16,18 +16,42 @@ A cross-runtime TypeScript client for the Strava API v3. Works on Deno, Node.js
 
 ### Deno
 
-```typescript
-import { StravaClient } from "https://deno.land/x/strava/mod.ts";
+```bash
+deno add jsr:@pinta365/strava
 ```
 
-### Node.js / Bun
+### Node.js
+
+#### Using npm
 
 ```bash
 npm install @pinta365/strava
 ```
 
-```typescript
-import { StravaClient } from "@pinta365/strava";
+#### Using JSR (recommended)
+
+```bash
+npx jsr add @pinta365/strava
+```
+
+#### Using pnpm
+
+```bash
+pnpm i jsr:@pinta365/strava
+```
+
+### Bun
+
+#### Using JSR (recommended)
+
+```bash
+bunx jsr add @pinta365/strava
+```
+
+#### Using npm
+
+```bash
+bun add @pinta365/strava
 ```
 
 ## Quick Start

package/esm/src/auth/oauth.d.ts

@@ -38,25 +38,39 @@ export declare class OAuthManager {
     private tokenStore;
     private clientId;
     private clientSecret;
+    /**
+     * Create a new OAuth manager
+     * @param clientId - Strava client ID
+     * @param clientSecret - Strava client secret
+     * @param tokenStore - Token storage implementation
+     */
     constructor(clientId: string, clientSecret: string, tokenStore: TokenStore);
     /**
      * Get authorization URL
+     * @param options - Authorization URL options
+     * @returns Authorization URL to redirect user to
      */
     getAuthorizationUrl(options: Omit<AuthorizationUrlOptions, "clientId">): string;
     /**
      * Exchange code and store tokens
+     * @param code - Authorization code from OAuth callback
+     * @param redirectUri - Redirect URI used in authorization (optional)
+     * @returns Token data
      */
     authenticate(code: string, redirectUri?: string): Promise<TokenData>;
     /**
      * Get current token, refreshing if needed
+     * @returns Token data or null if not authenticated
      */
     getToken(): Promise<TokenData | null>;
     /**
      * Manually refresh token
+     * @returns New token data
      */
     refreshToken(): Promise<TokenData>;
     /**
      * Get current scopes
+     * @returns Array of current OAuth scopes
      */
     getScopes(): Promise<StravaScope[]>;
     /**

package/esm/src/auth/oauth.js

@@ -100,6 +100,12 @@ export function isTokenExpired(token, bufferSeconds = 300) {
  * OAuth manager for handling authentication and token refresh
  */
 export class OAuthManager {
+    /**
+     * Create a new OAuth manager
+     * @param clientId - Strava client ID
+     * @param clientSecret - Strava client secret
+     * @param tokenStore - Token storage implementation
+     */
     constructor(clientId, clientSecret, tokenStore) {
         Object.defineProperty(this, "tokenStore", {
             enumerable: true,
@@ -125,6 +131,8 @@ export class OAuthManager {
     }
     /**
      * Get authorization URL
+     * @param options - Authorization URL options
+     * @returns Authorization URL to redirect user to
      */
     getAuthorizationUrl(options) {
         return getAuthorizationUrl({
@@ -134,6 +142,9 @@ export class OAuthManager {
     }
     /**
      * Exchange code and store tokens
+     * @param code - Authorization code from OAuth callback
+     * @param redirectUri - Redirect URI used in authorization (optional)
+     * @returns Token data
      */
     async authenticate(code, redirectUri) {
         const token = await exchangeCode(code, this.clientId, this.clientSecret, redirectUri);
@@ -142,6 +153,7 @@ export class OAuthManager {
     }
     /**
      * Get current token, refreshing if needed
+     * @returns Token data or null if not authenticated
      */
     async getToken() {
         const token = await this.tokenStore.get();
@@ -169,6 +181,7 @@ export class OAuthManager {
     }
     /**
      * Manually refresh token
+     * @returns New token data
      */
     async refreshToken() {
         const token = await this.tokenStore.get();
@@ -186,6 +199,7 @@ export class OAuthManager {
     }
     /**
      * Get current scopes
+     * @returns Array of current OAuth scopes
      */
     async getScopes() {
         const token = await this.tokenStore.get();

package/esm/src/auth/token-store.d.ts

@@ -16,8 +16,19 @@ export interface TokenData {
  * Token storage interface
  */
 export interface TokenStore {
+    /**
+     * Get stored token data
+     * @returns Token data or null if not found
+     */
     get(): Promise<TokenData | null>;
+    /**
+     * Store token data
+     * @param token - Token data to store
+     */
     set(token: TokenData): Promise<void>;
+    /**
+     * Clear stored token data
+     */
     clear(): Promise<void>;
 }
 /**
@@ -25,8 +36,19 @@ export interface TokenStore {
  */
 export declare class MemoryTokenStore implements TokenStore {
     private token;
+    /**
+     * Get stored token data
+     * @returns Token data or null if not found
+     */
     get(): Promise<TokenData | null>;
+    /**
+     * Store token data
+     * @param token - Token data to store
+     */
     set(token: TokenData): Promise<void>;
+    /**
+     * Clear stored token data
+     */
     clear(): Promise<void>;
 }
 /**
@@ -34,9 +56,23 @@ export declare class MemoryTokenStore implements TokenStore {
  */
 export declare class LocalStorageTokenStore implements TokenStore {
     private readonly key;
+    /**
+     * @param key - localStorage key to use (default: "strava_tokens")
+     */
     constructor(key?: string);
+    /**
+     * Get stored token data
+     * @returns Token data or null if not found
+     */
     get(): Promise<TokenData | null>;
+    /**
+     * Store token data
+     * @param token - Token data to store
+     */
     set(token: TokenData): Promise<void>;
+    /**
+     * Clear stored token data
+     */
     clear(): Promise<void>;
 }
 /**
@@ -44,9 +80,23 @@ export declare class LocalStorageTokenStore implements TokenStore {
  */
 export declare class FileSystemTokenStore implements TokenStore {
     private readonly path;
+    /**
+     * @param path - File path to store tokens (default: "./.strava-tokens.json")
+     */
     constructor(path?: string);
+    /**
+     * Get stored token data
+     * @returns Token data or null if not found
+     */
     get(): Promise<TokenData | null>;
+    /**
+     * Store token data
+     * @param token - Token data to store
+     */
     set(token: TokenData): Promise<void>;
+    /**
+     * Clear stored token data
+     */
     clear(): Promise<void>;
 }
 /**

package/esm/src/auth/token-store.js

@@ -14,13 +14,24 @@ export class MemoryTokenStore {
             value: null
         });
     }
+    /**
+     * Get stored token data
+     * @returns Token data or null if not found
+     */
     get() {
         return Promise.resolve(this.token);
     }
+    /**
+     * Store token data
+     * @param token - Token data to store
+     */
     set(token) {
         this.token = token;
         return Promise.resolve();
     }
+    /**
+     * Clear stored token data
+     */
     clear() {
         this.token = null;
         return Promise.resolve();
@@ -30,6 +41,9 @@ export class MemoryTokenStore {
  * Browser localStorage token store
  */
 export class LocalStorageTokenStore {
+    /**
+     * @param key - localStorage key to use (default: "strava_tokens")
+     */
     constructor(key = "strava_tokens") {
         Object.defineProperty(this, "key", {
             enumerable: true,
@@ -39,6 +53,10 @@ export class LocalStorageTokenStore {
         });
         this.key = key;
     }
+    /**
+     * Get stored token data
+     * @returns Token data or null if not found
+     */
     get() {
         if (CurrentRuntime !== Runtime.Browser) {
             throw new Error("LocalStorageTokenStore can only be used in browser environment");
@@ -53,6 +71,10 @@ export class LocalStorageTokenStore {
             return Promise.resolve(null);
         }
     }
+    /**
+     * Store token data
+     * @param token - Token data to store
+     */
     set(token) {
         if (CurrentRuntime !== Runtime.Browser) {
             throw new Error("LocalStorageTokenStore can only be used in browser environment");
@@ -60,6 +82,9 @@ export class LocalStorageTokenStore {
         localStorage.setItem(this.key, JSON.stringify(token));
         return Promise.resolve();
     }
+    /**
+     * Clear stored token data
+     */
     clear() {
         if (CurrentRuntime !== Runtime.Browser) {
             throw new Error("LocalStorageTokenStore can only be used in browser environment");
@@ -72,6 +97,9 @@ export class LocalStorageTokenStore {
  * File system token store (Node.js/Deno)
  */
 export class FileSystemTokenStore {
+    /**
+     * @param path - File path to store tokens (default: "./.strava-tokens.json")
+     */
     constructor(path = "./.strava-tokens.json") {
         Object.defineProperty(this, "path", {
             enumerable: true,
@@ -81,6 +109,10 @@ export class FileSystemTokenStore {
         });
         this.path = path;
     }
+    /**
+     * Get stored token data
+     * @returns Token data or null if not found
+     */
     async get() {
         try {
             let content;
@@ -98,6 +130,10 @@ export class FileSystemTokenStore {
             return null;
         }
     }
+    /**
+     * Store token data
+     * @param token - Token data to store
+     */
     async set(token) {
         const content = JSON.stringify(token, null, 2);
         if (CurrentRuntime === Runtime.Node || CurrentRuntime === Runtime.Bun) {
@@ -109,6 +145,9 @@ export class FileSystemTokenStore {
             await Deno.writeTextFile(this.path, content);
         }
     }
+    /**
+     * Clear stored token data
+     */
     async clear() {
         try {
             if (CurrentRuntime === Runtime.Node || CurrentRuntime === Runtime.Bun) {

package/esm/src/client.d.ts

@@ -7,25 +7,40 @@ import type { RateLimitStrategy, RequestConfig, RetryConfig } from "./types/comm
  * Client configuration options
  */
 export interface ClientOptions {
+    /** Strava client ID */
     clientId: string;
+    /** Strava client secret */
     clientSecret: string;
+    /** OAuth redirect URI */
     redirectUri?: string;
+    /** Token storage implementation (default: auto-detected based on runtime) */
     tokenStore?: TokenStore;
+    /** Base URL for API requests (default: "https://www.strava.com/api/v3") */
     baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
     timeout?: number;
+    /** Retry configuration */
     retries?: RetryConfig;
+    /** Rate limit handling strategy (default: "queue") */
     rateLimitStrategy?: RateLimitStrategy;
+    /** Request deduplication window in milliseconds (default: 5000) */
     deduplicationWindow?: number;
+    /** Normalize snake_case keys to camelCase (default: true) */
     normalizeKeys?: boolean;
+    /** Transform ISO date strings to Date objects (default: true) */
     transformDates?: boolean;
+    /** Flatten nested response structures (default: true) */
     flattenResponses?: boolean;
+    /** Add computed fields (pace, duration, etc.) (default: true) */
     addComputedFields?: boolean;
 }
 /**
  * Authentication credentials
  */
 export interface AuthCredentials {
+    /** Authorization code from OAuth callback */
     code: string;
+    /** Redirect URI used in authorization (optional, uses client default if not provided) */
     redirectUri?: string;
 }
 /**
@@ -45,9 +60,14 @@ export declare class StravaClient {
     private _routes?;
     private _uploads?;
     private _streams?;
+    /**
+     * Create a new Strava API client
+     * @param options - Client configuration options
+     */
     constructor(options: ClientOptions);
     /**
      * Authenticate with authorization code
+     * @param credentials - Authentication credentials
      */
     authenticate(credentials: AuthCredentials): Promise<void>;
     /**
@@ -55,7 +75,13 @@ export declare class StravaClient {
      */
     refreshToken(): Promise<void>;
     /**
-     * Get authorization URL
+     * Get authorization URL for OAuth flow
+     * @param options - Authorization URL options
+     * @param options.redirectUri - Redirect URI (optional, uses client default if not provided)
+     * @param options.scope - OAuth scopes to request
+     * @param options.state - Optional state parameter for CSRF protection
+     * @param options.approvalPrompt - Approval prompt behavior (default: "auto")
+     * @returns Authorization URL to redirect user to
      */
     getAuthorizationUrl(options: {
         redirectUri?: string;
@@ -65,20 +91,51 @@ export declare class StravaClient {
     }): string;
     /**
      * Get current access token (for direct fetch calls)
+     * @returns Current access token
+     * @throws Error if not authenticated
      */
     getAccessToken(): Promise<string>;
     /**
      * Low-level request method
+     * @param config - Request configuration
+     * @returns Response data
      */
     request<T>(config: RequestConfig): Promise<T>;
+    /**
+     * Athletes resource
+     */
     get athletes(): AthletesResource;
+    /**
+     * Activities resource
+     */
     get activities(): ActivitiesResource;
+    /**
+     * Segments resource
+     */
     get segments(): SegmentsResource;
+    /**
+     * Segment efforts resource
+     */
     get segmentEfforts(): SegmentEffortsResource;
+    /**
+     * Clubs resource
+     */
     get clubs(): ClubsResource;
+    /**
+     * Gears resource
+     */
     get gears(): GearsResource;
+    /**
+     * Routes resource
+     */
     get routes(): RoutesResource;
+    /**
+     * Uploads resource
+     */
     get uploads(): UploadsResource;
+    /**
+     * Streams resource
+     */
     get streams(): StreamsResource;
     /**
      * Clean up resources (stop timers, clear caches)

package/esm/src/client.js

@@ -10,6 +10,10 @@ import { getDefaultTokenStore } from "./auth/token-store.js";
  * Main Strava API client class
  */
 export class StravaClient {
+    /**
+     * Create a new Strava API client
+     * @param options - Client configuration options
+     */
     constructor(options) {
         Object.defineProperty(this, "options", {
             enumerable: true,
@@ -110,6 +114,7 @@ export class StravaClient {
     }
     /**
      * Authenticate with authorization code
+     * @param credentials - Authentication credentials
      */
     async authenticate(credentials) {
         await this.oauthManager.authenticate(credentials.code, credentials.redirectUri || this.options.redirectUri);
@@ -121,7 +126,13 @@ export class StravaClient {
         await this.oauthManager.refreshToken();
     }
     /**
-     * Get authorization URL
+     * Get authorization URL for OAuth flow
+     * @param options - Authorization URL options
+     * @param options.redirectUri - Redirect URI (optional, uses client default if not provided)
+     * @param options.scope - OAuth scopes to request
+     * @param options.state - Optional state parameter for CSRF protection
+     * @param options.approvalPrompt - Approval prompt behavior (default: "auto")
+     * @returns Authorization URL to redirect user to
      */
     getAuthorizationUrl(options) {
         return this.oauthManager.getAuthorizationUrl({
@@ -133,6 +144,8 @@ export class StravaClient {
     }
     /**
      * Get current access token (for direct fetch calls)
+     * @returns Current access token
+     * @throws Error if not authenticated
      */
     async getAccessToken() {
         const token = await this.oauthManager.getToken();
@@ -143,6 +156,8 @@ export class StravaClient {
     }
     /**
      * Low-level request method
+     * @param config - Request configuration
+     * @returns Response data
      */
     async request(config) {
         const token = await this.oauthManager.getToken();
@@ -162,54 +177,81 @@ export class StravaClient {
             addComputedFields: this.options.addComputedFields,
         });
     }
+    /**
+     * Athletes resource
+     */
     get athletes() {
         if (!this._athletes) {
             this._athletes = new AthletesResource(this);
         }
         return this._athletes;
     }
+    /**
+     * Activities resource
+     */
     get activities() {
         if (!this._activities) {
             this._activities = new ActivitiesResource(this);
         }
         return this._activities;
     }
+    /**
+     * Segments resource
+     */
     get segments() {
         if (!this._segments) {
             this._segments = new SegmentsResource(this);
         }
         return this._segments;
     }
+    /**
+     * Segment efforts resource
+     */
     get segmentEfforts() {
         if (!this._segmentEfforts) {
             this._segmentEfforts = new SegmentEffortsResource(this);
         }
         return this._segmentEfforts;
     }
+    /**
+     * Clubs resource
+     */
     get clubs() {
         if (!this._clubs) {
             this._clubs = new ClubsResource(this);
         }
         return this._clubs;
     }
+    /**
+     * Gears resource
+     */
     get gears() {
         if (!this._gears) {
             this._gears = new GearsResource(this);
         }
         return this._gears;
     }
+    /**
+     * Routes resource
+     */
     get routes() {
         if (!this._routes) {
             this._routes = new RoutesResource(this);
         }
         return this._routes;
     }
+    /**
+     * Uploads resource
+     */
     get uploads() {
         if (!this._uploads) {
             this._uploads = new UploadsResource(this);
         }
         return this._uploads;
     }
+    /**
+     * Streams resource
+     */
     get streams() {
         if (!this._streams) {
             this._streams = new StreamsResource(this);

package/esm/src/utils/pagination.d.ts

@@ -14,18 +14,21 @@ export declare class PaginatedIterator<T> {
     constructor(fetchPage: (page: number, perPage: number) => Promise<T[]>, perPage?: number);
     /**
      * Get next page
+     * @returns True if a page was fetched, false if no more pages
      */
     next(): Promise<boolean>;
     /**
      * Get current page items
+     * @returns Array of items from the current page
      */
     get current(): T[];
     /**
      * Check if there are more pages
+     * @returns True if there are more pages available
      */
     get hasMorePages(): boolean;
     /**
-     * Reset iterator
+     * Reset iterator to start from the first page
      */
     reset(): void;
 }

package/esm/src/utils/pagination.js

@@ -39,6 +39,7 @@ export class PaginatedIterator {
     }
     /**
      * Get next page
+     * @returns True if a page was fetched, false if no more pages
      */
     async next() {
         if (!this.hasMore) {
@@ -54,18 +55,20 @@ export class PaginatedIterator {
     }
     /**
      * Get current page items
+     * @returns Array of items from the current page
      */
     get current() {
         return this.currentItems;
     }
     /**
      * Check if there are more pages
+     * @returns True if there are more pages available
      */
     get hasMorePages() {
         return this.hasMore;
     }
     /**
-     * Reset iterator
+     * Reset iterator to start from the first page
      */
     reset() {
         this.currentPage = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pinta365/strava",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "A library for interacting with the Strava API.",
   "keywords": [
     "strava",

package/script/src/auth/oauth.d.ts

@@ -38,25 +38,39 @@ export declare class OAuthManager {
     private tokenStore;
     private clientId;
     private clientSecret;
+    /**
+     * Create a new OAuth manager
+     * @param clientId - Strava client ID
+     * @param clientSecret - Strava client secret
+     * @param tokenStore - Token storage implementation
+     */
     constructor(clientId: string, clientSecret: string, tokenStore: TokenStore);
     /**
      * Get authorization URL
+     * @param options - Authorization URL options
+     * @returns Authorization URL to redirect user to
      */
     getAuthorizationUrl(options: Omit<AuthorizationUrlOptions, "clientId">): string;
     /**
      * Exchange code and store tokens
+     * @param code - Authorization code from OAuth callback
+     * @param redirectUri - Redirect URI used in authorization (optional)
+     * @returns Token data
      */
     authenticate(code: string, redirectUri?: string): Promise<TokenData>;
     /**
      * Get current token, refreshing if needed
+     * @returns Token data or null if not authenticated
      */
     getToken(): Promise<TokenData | null>;
     /**
      * Manually refresh token
+     * @returns New token data
      */
     refreshToken(): Promise<TokenData>;
     /**
      * Get current scopes
+     * @returns Array of current OAuth scopes
      */
     getScopes(): Promise<StravaScope[]>;
     /**

package/script/src/auth/oauth.js

@@ -107,6 +107,12 @@ function isTokenExpired(token, bufferSeconds = 300) {
  * OAuth manager for handling authentication and token refresh
  */
 class OAuthManager {
+    /**
+     * Create a new OAuth manager
+     * @param clientId - Strava client ID
+     * @param clientSecret - Strava client secret
+     * @param tokenStore - Token storage implementation
+     */
     constructor(clientId, clientSecret, tokenStore) {
         Object.defineProperty(this, "tokenStore", {
             enumerable: true,
@@ -132,6 +138,8 @@ class OAuthManager {
     }
     /**
      * Get authorization URL
+     * @param options - Authorization URL options
+     * @returns Authorization URL to redirect user to
      */
     getAuthorizationUrl(options) {
         return getAuthorizationUrl({
@@ -141,6 +149,9 @@ class OAuthManager {
     }
     /**
      * Exchange code and store tokens
+     * @param code - Authorization code from OAuth callback
+     * @param redirectUri - Redirect URI used in authorization (optional)
+     * @returns Token data
      */
     async authenticate(code, redirectUri) {
         const token = await exchangeCode(code, this.clientId, this.clientSecret, redirectUri);
@@ -149,6 +160,7 @@ class OAuthManager {
     }
     /**
      * Get current token, refreshing if needed
+     * @returns Token data or null if not authenticated
      */
     async getToken() {
         const token = await this.tokenStore.get();
@@ -176,6 +188,7 @@ class OAuthManager {
     }
     /**
      * Manually refresh token
+     * @returns New token data
      */
     async refreshToken() {
         const token = await this.tokenStore.get();
@@ -193,6 +206,7 @@ class OAuthManager {
     }
     /**
      * Get current scopes
+     * @returns Array of current OAuth scopes
      */
     async getScopes() {
         const token = await this.tokenStore.get();

package/script/src/auth/token-store.d.ts

@@ -16,8 +16,19 @@ export interface TokenData {
  * Token storage interface
  */
 export interface TokenStore {
+    /**
+     * Get stored token data
+     * @returns Token data or null if not found
+     */
     get(): Promise<TokenData | null>;
+    /**
+     * Store token data
+     * @param token - Token data to store
+     */
     set(token: TokenData): Promise<void>;
+    /**
+     * Clear stored token data
+     */
     clear(): Promise<void>;
 }
 /**
@@ -25,8 +36,19 @@ export interface TokenStore {
  */
 export declare class MemoryTokenStore implements TokenStore {
     private token;
+    /**
+     * Get stored token data
+     * @returns Token data or null if not found
+     */
     get(): Promise<TokenData | null>;
+    /**
+     * Store token data
+     * @param token - Token data to store
+     */
     set(token: TokenData): Promise<void>;
+    /**
+     * Clear stored token data
+     */
     clear(): Promise<void>;
 }
 /**
@@ -34,9 +56,23 @@ export declare class MemoryTokenStore implements TokenStore {
  */
 export declare class LocalStorageTokenStore implements TokenStore {
     private readonly key;
+    /**
+     * @param key - localStorage key to use (default: "strava_tokens")
+     */
     constructor(key?: string);
+    /**
+     * Get stored token data
+     * @returns Token data or null if not found
+     */
     get(): Promise<TokenData | null>;
+    /**
+     * Store token data
+     * @param token - Token data to store
+     */
     set(token: TokenData): Promise<void>;
+    /**
+     * Clear stored token data
+     */
     clear(): Promise<void>;
 }
 /**
@@ -44,9 +80,23 @@ export declare class LocalStorageTokenStore implements TokenStore {
  */
 export declare class FileSystemTokenStore implements TokenStore {
     private readonly path;
+    /**
+     * @param path - File path to store tokens (default: "./.strava-tokens.json")
+     */
     constructor(path?: string);
+    /**
+     * Get stored token data
+     * @returns Token data or null if not found
+     */
     get(): Promise<TokenData | null>;
+    /**
+     * Store token data
+     * @param token - Token data to store
+     */
     set(token: TokenData): Promise<void>;
+    /**
+     * Clear stored token data
+     */
     clear(): Promise<void>;
 }
 /**

package/script/src/auth/token-store.js

@@ -51,13 +51,24 @@ class MemoryTokenStore {
             value: null
         });
     }
+    /**
+     * Get stored token data
+     * @returns Token data or null if not found
+     */
     get() {
         return Promise.resolve(this.token);
     }
+    /**
+     * Store token data
+     * @param token - Token data to store
+     */
     set(token) {
         this.token = token;
         return Promise.resolve();
     }
+    /**
+     * Clear stored token data
+     */
     clear() {
         this.token = null;
         return Promise.resolve();
@@ -68,6 +79,9 @@ exports.MemoryTokenStore = MemoryTokenStore;
  * Browser localStorage token store
  */
 class LocalStorageTokenStore {
+    /**
+     * @param key - localStorage key to use (default: "strava_tokens")
+     */
     constructor(key = "strava_tokens") {
         Object.defineProperty(this, "key", {
             enumerable: true,
@@ -77,6 +91,10 @@ class LocalStorageTokenStore {
         });
         this.key = key;
     }
+    /**
+     * Get stored token data
+     * @returns Token data or null if not found
+     */
     get() {
         if (mod_js_1.CurrentRuntime !== mod_js_1.Runtime.Browser) {
             throw new Error("LocalStorageTokenStore can only be used in browser environment");
@@ -91,6 +109,10 @@ class LocalStorageTokenStore {
             return Promise.resolve(null);
         }
     }
+    /**
+     * Store token data
+     * @param token - Token data to store
+     */
     set(token) {
         if (mod_js_1.CurrentRuntime !== mod_js_1.Runtime.Browser) {
             throw new Error("LocalStorageTokenStore can only be used in browser environment");
@@ -98,6 +120,9 @@ class LocalStorageTokenStore {
         localStorage.setItem(this.key, JSON.stringify(token));
         return Promise.resolve();
     }
+    /**
+     * Clear stored token data
+     */
     clear() {
         if (mod_js_1.CurrentRuntime !== mod_js_1.Runtime.Browser) {
             throw new Error("LocalStorageTokenStore can only be used in browser environment");
@@ -111,6 +136,9 @@ exports.LocalStorageTokenStore = LocalStorageTokenStore;
  * File system token store (Node.js/Deno)
  */
 class FileSystemTokenStore {
+    /**
+     * @param path - File path to store tokens (default: "./.strava-tokens.json")
+     */
     constructor(path = "./.strava-tokens.json") {
         Object.defineProperty(this, "path", {
             enumerable: true,
@@ -120,6 +148,10 @@ class FileSystemTokenStore {
         });
         this.path = path;
     }
+    /**
+     * Get stored token data
+     * @returns Token data or null if not found
+     */
     async get() {
         try {
             let content;
@@ -137,6 +169,10 @@ class FileSystemTokenStore {
             return null;
         }
     }
+    /**
+     * Store token data
+     * @param token - Token data to store
+     */
     async set(token) {
         const content = JSON.stringify(token, null, 2);
         if (mod_js_1.CurrentRuntime === mod_js_1.Runtime.Node || mod_js_1.CurrentRuntime === mod_js_1.Runtime.Bun) {
@@ -148,6 +184,9 @@ class FileSystemTokenStore {
             await Deno.writeTextFile(this.path, content);
         }
     }
+    /**
+     * Clear stored token data
+     */
     async clear() {
         try {
             if (mod_js_1.CurrentRuntime === mod_js_1.Runtime.Node || mod_js_1.CurrentRuntime === mod_js_1.Runtime.Bun) {

package/script/src/client.d.ts

@@ -7,25 +7,40 @@ import type { RateLimitStrategy, RequestConfig, RetryConfig } from "./types/comm
  * Client configuration options
  */
 export interface ClientOptions {
+    /** Strava client ID */
     clientId: string;
+    /** Strava client secret */
     clientSecret: string;
+    /** OAuth redirect URI */
     redirectUri?: string;
+    /** Token storage implementation (default: auto-detected based on runtime) */
     tokenStore?: TokenStore;
+    /** Base URL for API requests (default: "https://www.strava.com/api/v3") */
     baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
     timeout?: number;
+    /** Retry configuration */
     retries?: RetryConfig;
+    /** Rate limit handling strategy (default: "queue") */
     rateLimitStrategy?: RateLimitStrategy;
+    /** Request deduplication window in milliseconds (default: 5000) */
     deduplicationWindow?: number;
+    /** Normalize snake_case keys to camelCase (default: true) */
     normalizeKeys?: boolean;
+    /** Transform ISO date strings to Date objects (default: true) */
     transformDates?: boolean;
+    /** Flatten nested response structures (default: true) */
     flattenResponses?: boolean;
+    /** Add computed fields (pace, duration, etc.) (default: true) */
     addComputedFields?: boolean;
 }
 /**
  * Authentication credentials
  */
 export interface AuthCredentials {
+    /** Authorization code from OAuth callback */
     code: string;
+    /** Redirect URI used in authorization (optional, uses client default if not provided) */
     redirectUri?: string;
 }
 /**
@@ -45,9 +60,14 @@ export declare class StravaClient {
     private _routes?;
     private _uploads?;
     private _streams?;
+    /**
+     * Create a new Strava API client
+     * @param options - Client configuration options
+     */
     constructor(options: ClientOptions);
     /**
      * Authenticate with authorization code
+     * @param credentials - Authentication credentials
      */
     authenticate(credentials: AuthCredentials): Promise<void>;
     /**
@@ -55,7 +75,13 @@ export declare class StravaClient {
      */
     refreshToken(): Promise<void>;
     /**
-     * Get authorization URL
+     * Get authorization URL for OAuth flow
+     * @param options - Authorization URL options
+     * @param options.redirectUri - Redirect URI (optional, uses client default if not provided)
+     * @param options.scope - OAuth scopes to request
+     * @param options.state - Optional state parameter for CSRF protection
+     * @param options.approvalPrompt - Approval prompt behavior (default: "auto")
+     * @returns Authorization URL to redirect user to
      */
     getAuthorizationUrl(options: {
         redirectUri?: string;
@@ -65,20 +91,51 @@ export declare class StravaClient {
     }): string;
     /**
      * Get current access token (for direct fetch calls)
+     * @returns Current access token
+     * @throws Error if not authenticated
      */
     getAccessToken(): Promise<string>;
     /**
      * Low-level request method
+     * @param config - Request configuration
+     * @returns Response data
      */
     request<T>(config: RequestConfig): Promise<T>;
+    /**
+     * Athletes resource
+     */
     get athletes(): AthletesResource;
+    /**
+     * Activities resource
+     */
     get activities(): ActivitiesResource;
+    /**
+     * Segments resource
+     */
     get segments(): SegmentsResource;
+    /**
+     * Segment efforts resource
+     */
     get segmentEfforts(): SegmentEffortsResource;
+    /**
+     * Clubs resource
+     */
     get clubs(): ClubsResource;
+    /**
+     * Gears resource
+     */
     get gears(): GearsResource;
+    /**
+     * Routes resource
+     */
     get routes(): RoutesResource;
+    /**
+     * Uploads resource
+     */
     get uploads(): UploadsResource;
+    /**
+     * Streams resource
+     */
     get streams(): StreamsResource;
     /**
      * Clean up resources (stop timers, clear caches)

package/script/src/client.js

@@ -13,6 +13,10 @@ const token_store_js_1 = require("./auth/token-store.js");
  * Main Strava API client class
  */
 class StravaClient {
+    /**
+     * Create a new Strava API client
+     * @param options - Client configuration options
+     */
     constructor(options) {
         Object.defineProperty(this, "options", {
             enumerable: true,
@@ -113,6 +117,7 @@ class StravaClient {
     }
     /**
      * Authenticate with authorization code
+     * @param credentials - Authentication credentials
      */
     async authenticate(credentials) {
         await this.oauthManager.authenticate(credentials.code, credentials.redirectUri || this.options.redirectUri);
@@ -124,7 +129,13 @@ class StravaClient {
         await this.oauthManager.refreshToken();
     }
     /**
-     * Get authorization URL
+     * Get authorization URL for OAuth flow
+     * @param options - Authorization URL options
+     * @param options.redirectUri - Redirect URI (optional, uses client default if not provided)
+     * @param options.scope - OAuth scopes to request
+     * @param options.state - Optional state parameter for CSRF protection
+     * @param options.approvalPrompt - Approval prompt behavior (default: "auto")
+     * @returns Authorization URL to redirect user to
      */
     getAuthorizationUrl(options) {
         return this.oauthManager.getAuthorizationUrl({
@@ -136,6 +147,8 @@ class StravaClient {
     }
     /**
      * Get current access token (for direct fetch calls)
+     * @returns Current access token
+     * @throws Error if not authenticated
      */
     async getAccessToken() {
         const token = await this.oauthManager.getToken();
@@ -146,6 +159,8 @@ class StravaClient {
     }
     /**
      * Low-level request method
+     * @param config - Request configuration
+     * @returns Response data
      */
     async request(config) {
         const token = await this.oauthManager.getToken();
@@ -165,54 +180,81 @@ class StravaClient {
             addComputedFields: this.options.addComputedFields,
         });
     }
+    /**
+     * Athletes resource
+     */
     get athletes() {
         if (!this._athletes) {
             this._athletes = new athletes_js_1.AthletesResource(this);
         }
         return this._athletes;
     }
+    /**
+     * Activities resource
+     */
     get activities() {
         if (!this._activities) {
             this._activities = new activities_js_1.ActivitiesResource(this);
         }
         return this._activities;
     }
+    /**
+     * Segments resource
+     */
     get segments() {
         if (!this._segments) {
             this._segments = new segments_js_1.SegmentsResource(this);
         }
         return this._segments;
     }
+    /**
+     * Segment efforts resource
+     */
     get segmentEfforts() {
         if (!this._segmentEfforts) {
             this._segmentEfforts = new segment_efforts_js_1.SegmentEffortsResource(this);
         }
         return this._segmentEfforts;
     }
+    /**
+     * Clubs resource
+     */
     get clubs() {
         if (!this._clubs) {
             this._clubs = new clubs_js_1.ClubsResource(this);
         }
         return this._clubs;
     }
+    /**
+     * Gears resource
+     */
     get gears() {
         if (!this._gears) {
             this._gears = new gears_js_1.GearsResource(this);
         }
         return this._gears;
     }
+    /**
+     * Routes resource
+     */
     get routes() {
         if (!this._routes) {
             this._routes = new routes_js_1.RoutesResource(this);
         }
         return this._routes;
     }
+    /**
+     * Uploads resource
+     */
     get uploads() {
         if (!this._uploads) {
             this._uploads = new uploads_js_1.UploadsResource(this);
         }
         return this._uploads;
     }
+    /**
+     * Streams resource
+     */
     get streams() {
         if (!this._streams) {
             this._streams = new streams_js_1.StreamsResource(this);

package/script/src/utils/pagination.d.ts

@@ -14,18 +14,21 @@ export declare class PaginatedIterator<T> {
     constructor(fetchPage: (page: number, perPage: number) => Promise<T[]>, perPage?: number);
     /**
      * Get next page
+     * @returns True if a page was fetched, false if no more pages
      */
     next(): Promise<boolean>;
     /**
      * Get current page items
+     * @returns Array of items from the current page
      */
     get current(): T[];
     /**
      * Check if there are more pages
+     * @returns True if there are more pages available
      */
     get hasMorePages(): boolean;
     /**
-     * Reset iterator
+     * Reset iterator to start from the first page
      */
     reset(): void;
 }

package/script/src/utils/pagination.js

@@ -44,6 +44,7 @@ class PaginatedIterator {
     }
     /**
      * Get next page
+     * @returns True if a page was fetched, false if no more pages
      */
     async next() {
         if (!this.hasMore) {
@@ -59,18 +60,20 @@ class PaginatedIterator {
     }
     /**
      * Get current page items
+     * @returns Array of items from the current page
      */
     get current() {
         return this.currentItems;
     }
     /**
      * Check if there are more pages
+     * @returns True if there are more pages available
      */
     get hasMorePages() {
         return this.hasMore;
     }
     /**
-     * Reset iterator
+     * Reset iterator to start from the first page
      */
     reset() {
         this.currentPage = 1;