@pinta365/strava 0.0.1

package/script/mod.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * @pinta365/strava - TypeScript client for Strava API v3
+ *
+ * A cross-runtime (Deno, Node.js, Bun, Browser) library for interacting with the Strava API.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateRange = exports.validatePositiveInteger = exports.validatePagination = exports.validateNonNegativeInteger = exports.validateNonEmptyString = exports.validateDate = exports.transformDates = exports.flattenResponses = exports.applyTransformations = exports.addComputedFields = exports.PaginatedIterator = exports.listAll = exports.buildPaginationQuery = exports.StreamsResource = exports.UploadsResource = exports.RoutesResource = exports.GearsResource = exports.ClubsResource = exports.SegmentEffortsResource = exports.SegmentsResource = exports.ActivitiesResource = exports.AthletesResource = exports.MemoryTokenStore = exports.LocalStorageTokenStore = exports.getDefaultTokenStore = exports.FileSystemTokenStore = exports.validateScopes = exports.StravaScope = exports.parseScopes = exports.hasScope = exports.hasAllScopes = exports.formatScopes = exports.refreshAccessToken = exports.OAuthManager = exports.getAuthorizationUrl = exports.exchangeCode = exports.StravaValidationError = exports.StravaServerError = exports.StravaRateLimitError = exports.StravaNotFoundError = exports.StravaError = exports.StravaAuthError = exports.StravaClient = void 0;
+// Main client
+var client_js_1 = require("./src/client.js");
+Object.defineProperty(exports, "StravaClient", { enumerable: true, get: function () { return client_js_1.StravaClient; } });
+// Error classes
+var errors_js_1 = require("./src/errors.js");
+Object.defineProperty(exports, "StravaAuthError", { enumerable: true, get: function () { return errors_js_1.StravaAuthError; } });
+Object.defineProperty(exports, "StravaError", { enumerable: true, get: function () { return errors_js_1.StravaError; } });
+Object.defineProperty(exports, "StravaNotFoundError", { enumerable: true, get: function () { return errors_js_1.StravaNotFoundError; } });
+Object.defineProperty(exports, "StravaRateLimitError", { enumerable: true, get: function () { return errors_js_1.StravaRateLimitError; } });
+Object.defineProperty(exports, "StravaServerError", { enumerable: true, get: function () { return errors_js_1.StravaServerError; } });
+Object.defineProperty(exports, "StravaValidationError", { enumerable: true, get: function () { return errors_js_1.StravaValidationError; } });
+// Auth
+var oauth_js_1 = require("./src/auth/oauth.js");
+Object.defineProperty(exports, "exchangeCode", { enumerable: true, get: function () { return oauth_js_1.exchangeCode; } });
+Object.defineProperty(exports, "getAuthorizationUrl", { enumerable: true, get: function () { return oauth_js_1.getAuthorizationUrl; } });
+Object.defineProperty(exports, "OAuthManager", { enumerable: true, get: function () { return oauth_js_1.OAuthManager; } });
+Object.defineProperty(exports, "refreshAccessToken", { enumerable: true, get: function () { return oauth_js_1.refreshAccessToken; } });
+var scopes_js_1 = require("./src/auth/scopes.js");
+Object.defineProperty(exports, "formatScopes", { enumerable: true, get: function () { return scopes_js_1.formatScopes; } });
+Object.defineProperty(exports, "hasAllScopes", { enumerable: true, get: function () { return scopes_js_1.hasAllScopes; } });
+Object.defineProperty(exports, "hasScope", { enumerable: true, get: function () { return scopes_js_1.hasScope; } });
+Object.defineProperty(exports, "parseScopes", { enumerable: true, get: function () { return scopes_js_1.parseScopes; } });
+Object.defineProperty(exports, "StravaScope", { enumerable: true, get: function () { return scopes_js_1.StravaScope; } });
+Object.defineProperty(exports, "validateScopes", { enumerable: true, get: function () { return scopes_js_1.validateScopes; } });
+var token_store_js_1 = require("./src/auth/token-store.js");
+Object.defineProperty(exports, "FileSystemTokenStore", { enumerable: true, get: function () { return token_store_js_1.FileSystemTokenStore; } });
+Object.defineProperty(exports, "getDefaultTokenStore", { enumerable: true, get: function () { return token_store_js_1.getDefaultTokenStore; } });
+Object.defineProperty(exports, "LocalStorageTokenStore", { enumerable: true, get: function () { return token_store_js_1.LocalStorageTokenStore; } });
+Object.defineProperty(exports, "MemoryTokenStore", { enumerable: true, get: function () { return token_store_js_1.MemoryTokenStore; } });
+// Resources (for advanced usage)
+var athletes_js_1 = require("./src/resources/athletes.js");
+Object.defineProperty(exports, "AthletesResource", { enumerable: true, get: function () { return athletes_js_1.AthletesResource; } });
+var activities_js_1 = require("./src/resources/activities.js");
+Object.defineProperty(exports, "ActivitiesResource", { enumerable: true, get: function () { return activities_js_1.ActivitiesResource; } });
+var segments_js_1 = require("./src/resources/segments.js");
+Object.defineProperty(exports, "SegmentsResource", { enumerable: true, get: function () { return segments_js_1.SegmentsResource; } });
+var segment_efforts_js_1 = require("./src/resources/segment-efforts.js");
+Object.defineProperty(exports, "SegmentEffortsResource", { enumerable: true, get: function () { return segment_efforts_js_1.SegmentEffortsResource; } });
+var clubs_js_1 = require("./src/resources/clubs.js");
+Object.defineProperty(exports, "ClubsResource", { enumerable: true, get: function () { return clubs_js_1.ClubsResource; } });
+var gears_js_1 = require("./src/resources/gears.js");
+Object.defineProperty(exports, "GearsResource", { enumerable: true, get: function () { return gears_js_1.GearsResource; } });
+var routes_js_1 = require("./src/resources/routes.js");
+Object.defineProperty(exports, "RoutesResource", { enumerable: true, get: function () { return routes_js_1.RoutesResource; } });
+var uploads_js_1 = require("./src/resources/uploads.js");
+Object.defineProperty(exports, "UploadsResource", { enumerable: true, get: function () { return uploads_js_1.UploadsResource; } });
+var streams_js_1 = require("./src/resources/streams.js");
+Object.defineProperty(exports, "StreamsResource", { enumerable: true, get: function () { return streams_js_1.StreamsResource; } });
+// Utilities
+var pagination_js_1 = require("./src/utils/pagination.js");
+Object.defineProperty(exports, "buildPaginationQuery", { enumerable: true, get: function () { return pagination_js_1.buildPaginationQuery; } });
+Object.defineProperty(exports, "listAll", { enumerable: true, get: function () { return pagination_js_1.listAll; } });
+Object.defineProperty(exports, "PaginatedIterator", { enumerable: true, get: function () { return pagination_js_1.PaginatedIterator; } });
+var transformers_js_1 = require("./src/utils/transformers.js");
+Object.defineProperty(exports, "addComputedFields", { enumerable: true, get: function () { return transformers_js_1.addComputedFields; } });
+Object.defineProperty(exports, "applyTransformations", { enumerable: true, get: function () { return transformers_js_1.applyTransformations; } });
+Object.defineProperty(exports, "flattenResponses", { enumerable: true, get: function () { return transformers_js_1.flattenResponses; } });
+Object.defineProperty(exports, "transformDates", { enumerable: true, get: function () { return transformers_js_1.transformDates; } });
+var validators_js_1 = require("./src/utils/validators.js");
+Object.defineProperty(exports, "validateDate", { enumerable: true, get: function () { return validators_js_1.validateDate; } });
+Object.defineProperty(exports, "validateNonEmptyString", { enumerable: true, get: function () { return validators_js_1.validateNonEmptyString; } });
+Object.defineProperty(exports, "validateNonNegativeInteger", { enumerable: true, get: function () { return validators_js_1.validateNonNegativeInteger; } });
+Object.defineProperty(exports, "validatePagination", { enumerable: true, get: function () { return validators_js_1.validatePagination; } });
+Object.defineProperty(exports, "validatePositiveInteger", { enumerable: true, get: function () { return validators_js_1.validatePositiveInteger; } });
+Object.defineProperty(exports, "validateRange", { enumerable: true, get: function () { return validators_js_1.validateRange; } });

package/script/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

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

@@ -0,0 +1,68 @@
+/**
+ * OAuth 2.0 authentication flow for Strava API
+ */
+import type { TokenData, TokenStore } from "./token-store.js";
+import { type StravaScope } from "./scopes.js";
+interface AuthorizationUrlOptions {
+    clientId: string;
+    redirectUri: string;
+    scope: StravaScope[];
+    state?: string;
+    approvalPrompt?: "force" | "auto";
+}
+/**
+ * Generate authorization URL
+ */
+export declare function getAuthorizationUrl(options: AuthorizationUrlOptions): string;
+/**
+ * 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 declare function exchangeCode(code: string, clientId: string, clientSecret: string, redirectUri?: string): Promise<TokenData>;
+/**
+ * Refresh access token using refresh token
+ */
+export declare function refreshAccessToken(refreshToken: string, clientId: string, clientSecret: string): Promise<TokenData>;
+/**
+ * Check if token is expired or about to expire
+ */
+export declare function isTokenExpired(token: TokenData, bufferSeconds?: number): boolean;
+/**
+ * OAuth manager for handling authentication and token refresh
+ */
+export declare class OAuthManager {
+    private tokenStore;
+    private clientId;
+    private clientSecret;
+    constructor(clientId: string, clientSecret: string, tokenStore: TokenStore);
+    /**
+     * Get authorization URL
+     */
+    getAuthorizationUrl(options: Omit<AuthorizationUrlOptions, "clientId">): string;
+    /**
+     * Exchange code and store tokens
+     */
+    authenticate(code: string, redirectUri?: string): Promise<TokenData>;
+    /**
+     * Get current token, refreshing if needed
+     */
+    getToken(): Promise<TokenData | null>;
+    /**
+     * Manually refresh token
+     */
+    refreshToken(): Promise<TokenData>;
+    /**
+     * Get current scopes
+     */
+    getScopes(): Promise<StravaScope[]>;
+    /**
+     * Clear stored tokens
+     */
+    clearTokens(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=oauth.d.ts.map

package/script/src/auth/oauth.js

@@ -0,0 +1,211 @@
+"use strict";
+/**
+ * OAuth 2.0 authentication flow for Strava API
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OAuthManager = void 0;
+exports.getAuthorizationUrl = getAuthorizationUrl;
+exports.exchangeCode = exchangeCode;
+exports.refreshAccessToken = refreshAccessToken;
+exports.isTokenExpired = isTokenExpired;
+const errors_js_1 = require("../errors.js");
+const scopes_js_1 = require("./scopes.js");
+const OAUTH_BASE_URL = "https://www.strava.com/api/v3/oauth";
+/**
+ * Generate authorization URL
+ */
+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: (0, scopes_js_1.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
+ */
+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 errors_js_1.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
+ */
+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 errors_js_1.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
+ */
+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
+ */
+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 errors_js_1.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 (0, scopes_js_1.parseScopes)(token.scope);
+    }
+    /**
+     * Clear stored tokens
+     */
+    async clearTokens() {
+        await this.tokenStore.clear();
+    }
+}
+exports.OAuthManager = OAuthManager;

package/script/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/script/src/auth/scopes.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * OAuth 2.0 scope definitions for Strava API
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCOPE_DESCRIPTIONS = exports.StravaScope = void 0;
+exports.parseScopes = parseScopes;
+exports.formatScopes = formatScopes;
+exports.hasScope = hasScope;
+exports.hasAllScopes = hasAllScopes;
+exports.validateScopes = validateScopes;
+/**
+ * Available OAuth scopes
+ */
+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 || (exports.StravaScope = StravaScope = {}));
+/**
+ * Scope descriptions
+ */
+exports.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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+function validateScopes(scopes) {
+    const validScopes = Object.values(StravaScope);
+    return scopes.every((scope) => validScopes.includes(scope));
+}

package/script/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