@pinta365/strava 0.0.1

package/esm/src/auth/oauth.js

@@ -0,0 +1,203 @@
+/**
+ * OAuth 2.0 authentication flow for Strava API
+ */
+import { StravaAuthError } from "../errors.js";
+import { formatScopes, parseScopes } from "./scopes.js";
+const OAUTH_BASE_URL = "https://www.strava.com/api/v3/oauth";
+/**
+ * Generate authorization URL
+ */
+export function getAuthorizationUrl(options) {
+    const { clientId, redirectUri, scope, state, approvalPrompt = "auto" } = options;
+    const params = new URLSearchParams({
+        client_id: clientId,
+        redirect_uri: redirectUri,
+        response_type: "code",
+        scope: formatScopes(scope),
+        approval_prompt: approvalPrompt,
+    });
+    if (state) {
+        params.append("state", state);
+    }
+    return `${OAUTH_BASE_URL}/authorize?${params.toString()}`;
+}
+/**
+ * Exchange authorization code for tokens
+ * @param code - Authorization code from OAuth callback
+ * @param clientId - Strava client ID
+ * @param clientSecret - Strava client secret
+ * @param redirectUri - Redirect URI used in authorization (optional)
+ * @returns Token data
+ */
+export async function exchangeCode(code, clientId, clientSecret, redirectUri) {
+    const params = new URLSearchParams({
+        client_id: clientId,
+        client_secret: clientSecret,
+        code,
+        grant_type: "authorization_code",
+    });
+    if (redirectUri) {
+        params.append("redirect_uri", redirectUri);
+    }
+    const response = await fetch(`${OAUTH_BASE_URL}/token`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: params.toString(),
+    });
+    if (!response.ok) {
+        const error = await response.json().catch(() => ({ message: response.statusText }));
+        throw new StravaAuthError(`Failed to exchange code: ${error.message || response.statusText}`, response.status, error);
+    }
+    const data = await response.json();
+    return {
+        accessToken: data.access_token,
+        refreshToken: data.refresh_token,
+        expiresAt: data.expires_at,
+        tokenType: data.token_type,
+        athleteId: data.athlete?.id,
+    };
+}
+/**
+ * Refresh access token using refresh token
+ */
+export async function refreshAccessToken(refreshToken, clientId, clientSecret) {
+    const params = new URLSearchParams({
+        client_id: clientId,
+        client_secret: clientSecret,
+        refresh_token: refreshToken,
+        grant_type: "refresh_token",
+    });
+    const response = await fetch(`${OAUTH_BASE_URL}/token`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: params.toString(),
+    });
+    if (!response.ok) {
+        const error = await response.json().catch(() => ({ message: response.statusText }));
+        throw new StravaAuthError(`Failed to refresh token: ${error.message || response.statusText}`, response.status, error);
+    }
+    const data = await response.json();
+    return {
+        accessToken: data.access_token,
+        refreshToken: data.refresh_token,
+        expiresAt: data.expires_at,
+        tokenType: data.token_type,
+        athleteId: data.athlete?.id,
+    };
+}
+/**
+ * Check if token is expired or about to expire
+ */
+export function isTokenExpired(token, bufferSeconds = 300) {
+    const now = Math.floor(Date.now() / 1000);
+    return token.expiresAt <= (now + bufferSeconds);
+}
+/**
+ * OAuth manager for handling authentication and token refresh
+ */
+export class OAuthManager {
+    constructor(clientId, clientSecret, tokenStore) {
+        Object.defineProperty(this, "tokenStore", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "clientId", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "clientSecret", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.clientId = clientId;
+        this.clientSecret = clientSecret;
+        this.tokenStore = tokenStore;
+    }
+    /**
+     * Get authorization URL
+     */
+    getAuthorizationUrl(options) {
+        return getAuthorizationUrl({
+            ...options,
+            clientId: this.clientId,
+        });
+    }
+    /**
+     * Exchange code and store tokens
+     */
+    async authenticate(code, redirectUri) {
+        const token = await exchangeCode(code, this.clientId, this.clientSecret, redirectUri);
+        await this.tokenStore.set(token);
+        return token;
+    }
+    /**
+     * Get current token, refreshing if needed
+     */
+    async getToken() {
+        const token = await this.tokenStore.get();
+        if (!token) {
+            return null;
+        }
+        // Refresh if expired or about to expire
+        if (isTokenExpired(token)) {
+            try {
+                const newToken = await refreshAccessToken(token.refreshToken, this.clientId, this.clientSecret);
+                const refreshedToken = {
+                    ...newToken,
+                    scope: token.scope,
+                    athleteId: token.athleteId || newToken.athleteId,
+                };
+                await this.tokenStore.set(refreshedToken);
+                return refreshedToken;
+            }
+            catch (error) {
+                await this.tokenStore.clear();
+                throw error;
+            }
+        }
+        return token;
+    }
+    /**
+     * Manually refresh token
+     */
+    async refreshToken() {
+        const token = await this.tokenStore.get();
+        if (!token) {
+            throw new StravaAuthError("No token available to refresh");
+        }
+        const newToken = await refreshAccessToken(token.refreshToken, this.clientId, this.clientSecret);
+        const refreshedToken = {
+            ...newToken,
+            scope: token.scope,
+            athleteId: token.athleteId || newToken.athleteId,
+        };
+        await this.tokenStore.set(refreshedToken);
+        return refreshedToken;
+    }
+    /**
+     * Get current scopes
+     */
+    async getScopes() {
+        const token = await this.tokenStore.get();
+        if (!token || !token.scope) {
+            return [];
+        }
+        return parseScopes(token.scope);
+    }
+    /**
+     * Clear stored tokens
+     */
+    async clearTokens() {
+        await this.tokenStore.clear();
+    }
+}

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

@@ -0,0 +1,52 @@
+/**
+ * OAuth 2.0 scope definitions for Strava API
+ */
+/**
+ * Available OAuth scopes
+ */
+export declare enum StravaScope {
+    Read = "read",
+    ReadAll = "read_all",
+    ProfileReadAll = "profile:read_all",
+    ProfileWrite = "profile:write",
+    ActivityRead = "activity:read",
+    ActivityReadAll = "activity:read_all",
+    ActivityWrite = "activity:write"
+}
+/**
+ * Scope descriptions
+ */
+export declare const SCOPE_DESCRIPTIONS: Record<StravaScope, string>;
+/**
+ * Parse scope string into array
+ * @param scopeString - Comma-separated scope string
+ * @returns Array of scope enums
+ */
+export declare function parseScopes(scopeString: string): StravaScope[];
+/**
+ * Format scopes array into string
+ * @param scopes - Array of scope enums
+ * @returns Comma-separated scope string
+ */
+export declare function formatScopes(scopes: StravaScope[]): string;
+/**
+ * Check if a scope is included in the provided scopes
+ * @param required - Required scope
+ * @param available - Available scopes
+ * @returns True if the required scope is available
+ */
+export declare function hasScope(required: StravaScope, available: StravaScope[]): boolean;
+/**
+ * Check if all required scopes are available
+ * @param required - Required scopes
+ * @param available - Available scopes
+ * @returns True if all required scopes are available
+ */
+export declare function hasAllScopes(required: StravaScope[], available: StravaScope[]): boolean;
+/**
+ * Validate scopes
+ * @param scopes - Scopes to validate
+ * @returns True if all scopes are valid
+ */
+export declare function validateScopes(scopes: StravaScope[]): boolean;
+//# sourceMappingURL=scopes.d.ts.map

package/esm/src/auth/scopes.js

@@ -0,0 +1,71 @@
+/**
+ * OAuth 2.0 scope definitions for Strava API
+ */
+/**
+ * Available OAuth scopes
+ */
+export var StravaScope;
+(function (StravaScope) {
+    StravaScope["Read"] = "read";
+    StravaScope["ReadAll"] = "read_all";
+    StravaScope["ProfileReadAll"] = "profile:read_all";
+    StravaScope["ProfileWrite"] = "profile:write";
+    StravaScope["ActivityRead"] = "activity:read";
+    StravaScope["ActivityReadAll"] = "activity:read_all";
+    StravaScope["ActivityWrite"] = "activity:write";
+})(StravaScope || (StravaScope = {}));
+/**
+ * Scope descriptions
+ */
+export const SCOPE_DESCRIPTIONS = {
+    [StravaScope.Read]: "Read public segments, public routes, public profile data, public posts, public events, club feeds, and leaderboards",
+    [StravaScope.ReadAll]: "Read private routes, private segments, and private events for the user",
+    [StravaScope.ProfileReadAll]: "Read all profile information even if the user has set their profile visibility to Followers or Only You",
+    [StravaScope.ProfileWrite]: "Update the user's weight and Functional Threshold Power (FTP), and access to star or unstar segments on their behalf",
+    [StravaScope.ActivityRead]: "Read the user's activity data for activities that are visible to Everyone and Followers, excluding privacy zone data",
+    [StravaScope.ActivityReadAll]: "The same access as activity:read, plus privacy zone data and access to read the user's activities with visibility set to Only You",
+    [StravaScope.ActivityWrite]: "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",
+};
+/**
+ * Parse scope string into array
+ * @param scopeString - Comma-separated scope string
+ * @returns Array of scope enums
+ */
+export function parseScopes(scopeString) {
+    return scopeString.split(",").map((s) => s.trim()).filter(Boolean);
+}
+/**
+ * Format scopes array into string
+ * @param scopes - Array of scope enums
+ * @returns Comma-separated scope string
+ */
+export function formatScopes(scopes) {
+    return scopes.join(",");
+}
+/**
+ * Check if a scope is included in the provided scopes
+ * @param required - Required scope
+ * @param available - Available scopes
+ * @returns True if the required scope is available
+ */
+export function hasScope(required, available) {
+    return available.includes(required);
+}
+/**
+ * Check if all required scopes are available
+ * @param required - Required scopes
+ * @param available - Available scopes
+ * @returns True if all required scopes are available
+ */
+export function hasAllScopes(required, available) {
+    return required.every((scope) => available.includes(scope));
+}
+/**
+ * Validate scopes
+ * @param scopes - Scopes to validate
+ * @returns True if all scopes are valid
+ */
+export function validateScopes(scopes) {
+    const validScopes = Object.values(StravaScope);
+    return scopes.every((scope) => validScopes.includes(scope));
+}

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

@@ -0,0 +1,57 @@
+/**
+ * Token storage interface and implementations
+ */
+/**
+ * Token data structure
+ */
+export interface TokenData {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+    tokenType: string;
+    scope?: string;
+    athleteId?: number;
+}
+/**
+ * Token storage interface
+ */
+export interface TokenStore {
+    get(): Promise<TokenData | null>;
+    set(token: TokenData): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * In-memory token store (default)
+ */
+export declare class MemoryTokenStore implements TokenStore {
+    private token;
+    get(): Promise<TokenData | null>;
+    set(token: TokenData): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * Browser localStorage token store
+ */
+export declare class LocalStorageTokenStore implements TokenStore {
+    private readonly key;
+    constructor(key?: string);
+    get(): Promise<TokenData | null>;
+    set(token: TokenData): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * File system token store (Node.js/Deno)
+ */
+export declare class FileSystemTokenStore implements TokenStore {
+    private readonly path;
+    constructor(path?: string);
+    get(): Promise<TokenData | null>;
+    set(token: TokenData): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * Get default token store based on runtime environment
+ * @returns TokenStore appropriate for the current runtime (browser, Node.js, Deno, Bun)
+ */
+export declare function getDefaultTokenStore(): TokenStore;
+//# sourceMappingURL=token-store.d.ts.map

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

@@ -0,0 +1,142 @@
+/**
+ * Token storage interface and implementations
+ */
+import { CurrentRuntime, Runtime } from "../../deps/jsr.io/@cross/runtime/1.2.1/mod.js";
+/**
+ * In-memory token store (default)
+ */
+export class MemoryTokenStore {
+    constructor() {
+        Object.defineProperty(this, "token", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+    }
+    get() {
+        return Promise.resolve(this.token);
+    }
+    set(token) {
+        this.token = token;
+        return Promise.resolve();
+    }
+    clear() {
+        this.token = null;
+        return Promise.resolve();
+    }
+}
+/**
+ * Browser localStorage token store
+ */
+export class LocalStorageTokenStore {
+    constructor(key = "strava_tokens") {
+        Object.defineProperty(this, "key", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.key = key;
+    }
+    get() {
+        if (CurrentRuntime !== Runtime.Browser) {
+            throw new Error("LocalStorageTokenStore can only be used in browser environment");
+        }
+        try {
+            const stored = localStorage.getItem(this.key);
+            if (!stored)
+                return Promise.resolve(null);
+            return Promise.resolve(JSON.parse(stored));
+        }
+        catch {
+            return Promise.resolve(null);
+        }
+    }
+    set(token) {
+        if (CurrentRuntime !== Runtime.Browser) {
+            throw new Error("LocalStorageTokenStore can only be used in browser environment");
+        }
+        localStorage.setItem(this.key, JSON.stringify(token));
+        return Promise.resolve();
+    }
+    clear() {
+        if (CurrentRuntime !== Runtime.Browser) {
+            throw new Error("LocalStorageTokenStore can only be used in browser environment");
+        }
+        localStorage.removeItem(this.key);
+        return Promise.resolve();
+    }
+}
+/**
+ * File system token store (Node.js/Deno)
+ */
+export class FileSystemTokenStore {
+    constructor(path = "./.strava-tokens.json") {
+        Object.defineProperty(this, "path", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.path = path;
+    }
+    async get() {
+        try {
+            let content;
+            if (CurrentRuntime === Runtime.Node || CurrentRuntime === Runtime.Bun) {
+                const { readFile } = await import("node:fs/promises");
+                content = await readFile(this.path, "utf-8");
+            }
+            else {
+                // Deno
+                content = await Deno.readTextFile(this.path);
+            }
+            return JSON.parse(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    async set(token) {
+        const content = JSON.stringify(token, null, 2);
+        if (CurrentRuntime === Runtime.Node || CurrentRuntime === Runtime.Bun) {
+            const { writeFile } = await import("node:fs/promises");
+            await writeFile(this.path, content, "utf-8");
+        }
+        else {
+            // Deno
+            await Deno.writeTextFile(this.path, content);
+        }
+    }
+    async clear() {
+        try {
+            if (CurrentRuntime === Runtime.Node || CurrentRuntime === Runtime.Bun) {
+                const { unlink } = await import("node:fs/promises");
+                await unlink(this.path);
+            }
+            else {
+                // Deno
+                await Deno.remove(this.path);
+            }
+        }
+        catch {
+            // File doesn't exist, ignore
+        }
+    }
+}
+/**
+ * Get default token store based on runtime environment
+ * @returns TokenStore appropriate for the current runtime (browser, Node.js, Deno, Bun)
+ */
+export function getDefaultTokenStore() {
+    if (CurrentRuntime === Runtime.Browser) {
+        return new LocalStorageTokenStore();
+    }
+    else if (CurrentRuntime === Runtime.Node || CurrentRuntime === Runtime.Deno || CurrentRuntime === Runtime.Bun) {
+        return new FileSystemTokenStore();
+    }
+    else {
+        return new MemoryTokenStore();
+    }
+}

package/esm/src/client.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Main Strava API client
+ */
+import { type TokenStore } from "./auth/token-store.js";
+import type { RateLimitStrategy, RequestConfig, RetryConfig } from "./types/common.js";
+/**
+ * Client configuration options
+ */
+export interface ClientOptions {
+    clientId: string;
+    clientSecret: string;
+    redirectUri?: string;
+    tokenStore?: TokenStore;
+    baseUrl?: string;
+    timeout?: number;
+    retries?: RetryConfig;
+    rateLimitStrategy?: RateLimitStrategy;
+    deduplicationWindow?: number;
+    normalizeKeys?: boolean;
+    transformDates?: boolean;
+    flattenResponses?: boolean;
+    addComputedFields?: boolean;
+}
+/**
+ * Authentication credentials
+ */
+export interface AuthCredentials {
+    code: string;
+    redirectUri?: string;
+}
+/**
+ * Main Strava API client class
+ */
+export declare class StravaClient {
+    private readonly options;
+    private readonly oauthManager;
+    private readonly rateLimiter;
+    private readonly deduplicator;
+    private _athletes?;
+    private _activities?;
+    private _segments?;
+    private _segmentEfforts?;
+    private _clubs?;
+    private _gears?;
+    private _routes?;
+    private _uploads?;
+    private _streams?;
+    constructor(options: ClientOptions);
+    /**
+     * Authenticate with authorization code
+     */
+    authenticate(credentials: AuthCredentials): Promise<void>;
+    /**
+     * Refresh access token
+     */
+    refreshToken(): Promise<void>;
+    /**
+     * Get authorization URL
+     */
+    getAuthorizationUrl(options: {
+        redirectUri?: string;
+        scope: string[];
+        state?: string;
+        approvalPrompt?: "force" | "auto";
+    }): string;
+    /**
+     * Get current access token (for direct fetch calls)
+     */
+    getAccessToken(): Promise<string>;
+    /**
+     * Low-level request method
+     */
+    request<T>(config: RequestConfig): Promise<T>;
+    get athletes(): AthletesResource;
+    get activities(): ActivitiesResource;
+    get segments(): SegmentsResource;
+    get segmentEfforts(): SegmentEffortsResource;
+    get clubs(): ClubsResource;
+    get gears(): GearsResource;
+    get routes(): RoutesResource;
+    get uploads(): UploadsResource;
+    get streams(): StreamsResource;
+    /**
+     * Clean up resources (stop timers, clear caches)
+     * Call this when you're done with the client to allow the process to exit
+     */
+    destroy(): void;
+}
+import { AthletesResource } from "./resources/athletes.js";
+import { ActivitiesResource } from "./resources/activities.js";
+import { SegmentsResource } from "./resources/segments.js";
+import { SegmentEffortsResource } from "./resources/segment-efforts.js";
+import { ClubsResource } from "./resources/clubs.js";
+import { GearsResource } from "./resources/gears.js";
+import { RoutesResource } from "./resources/routes.js";
+import { UploadsResource } from "./resources/uploads.js";
+import { StreamsResource } from "./resources/streams.js";
+//# sourceMappingURL=client.d.ts.map