@pinta365/strava 0.0.1

package/esm/src/client.js

@@ -0,0 +1,235 @@
+/**
+ * Main Strava API client
+ */
+import { request } from "./http/request.js";
+import { RateLimiter } from "./http/rate-limiter.js";
+import { RequestDeduplicator } from "./http/deduplication.js";
+import { OAuthManager } from "./auth/oauth.js";
+import { getDefaultTokenStore } from "./auth/token-store.js";
+/**
+ * Main Strava API client class
+ */
+export class StravaClient {
+    constructor(options) {
+        Object.defineProperty(this, "options", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "oauthManager", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "rateLimiter", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "deduplicator", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_athletes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_activities", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_segments", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_segmentEfforts", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_clubs", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_gears", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_routes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_uploads", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_streams", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.options = {
+            baseUrl: options.baseUrl || "https://www.strava.com/api/v3",
+            timeout: options.timeout || 30000,
+            retries: options.retries || {},
+            rateLimitStrategy: options.rateLimitStrategy || "queue",
+            deduplicationWindow: options.deduplicationWindow || 5000,
+            normalizeKeys: options.normalizeKeys ?? true,
+            transformDates: options.transformDates ?? true,
+            flattenResponses: options.flattenResponses ?? true,
+            addComputedFields: options.addComputedFields ?? true,
+            tokenStore: options.tokenStore || getDefaultTokenStore(),
+            redirectUri: options.redirectUri,
+            clientId: options.clientId,
+            clientSecret: options.clientSecret,
+        };
+        this.oauthManager = new OAuthManager(this.options.clientId, this.options.clientSecret, this.options.tokenStore);
+        this.rateLimiter = new RateLimiter(this.options.rateLimitStrategy);
+        this.deduplicator = new RequestDeduplicator(this.options.deduplicationWindow);
+    }
+    /**
+     * Authenticate with authorization code
+     */
+    async authenticate(credentials) {
+        await this.oauthManager.authenticate(credentials.code, credentials.redirectUri || this.options.redirectUri);
+    }
+    /**
+     * Refresh access token
+     */
+    async refreshToken() {
+        await this.oauthManager.refreshToken();
+    }
+    /**
+     * Get authorization URL
+     */
+    getAuthorizationUrl(options) {
+        return this.oauthManager.getAuthorizationUrl({
+            redirectUri: options.redirectUri || this.options.redirectUri || "",
+            scope: options.scope,
+            state: options.state,
+            approvalPrompt: options.approvalPrompt,
+        });
+    }
+    /**
+     * Get current access token (for direct fetch calls)
+     */
+    async getAccessToken() {
+        const token = await this.oauthManager.getToken();
+        if (!token) {
+            throw new Error("Not authenticated. Call authenticate() first.");
+        }
+        return token.accessToken;
+    }
+    /**
+     * Low-level request method
+     */
+    async request(config) {
+        const token = await this.oauthManager.getToken();
+        if (!token) {
+            throw new Error("Not authenticated. Call authenticate() first.");
+        }
+        return request(config, {
+            baseUrl: this.options.baseUrl,
+            timeout: this.options.timeout,
+            accessToken: token.accessToken,
+            rateLimiter: this.rateLimiter,
+            deduplicator: this.deduplicator,
+            retryConfig: this.options.retries,
+            normalizeKeys: this.options.normalizeKeys,
+            transformDates: this.options.transformDates,
+            flattenResponses: this.options.flattenResponses,
+            addComputedFields: this.options.addComputedFields,
+        });
+    }
+    get athletes() {
+        if (!this._athletes) {
+            this._athletes = new AthletesResource(this);
+        }
+        return this._athletes;
+    }
+    get activities() {
+        if (!this._activities) {
+            this._activities = new ActivitiesResource(this);
+        }
+        return this._activities;
+    }
+    get segments() {
+        if (!this._segments) {
+            this._segments = new SegmentsResource(this);
+        }
+        return this._segments;
+    }
+    get segmentEfforts() {
+        if (!this._segmentEfforts) {
+            this._segmentEfforts = new SegmentEffortsResource(this);
+        }
+        return this._segmentEfforts;
+    }
+    get clubs() {
+        if (!this._clubs) {
+            this._clubs = new ClubsResource(this);
+        }
+        return this._clubs;
+    }
+    get gears() {
+        if (!this._gears) {
+            this._gears = new GearsResource(this);
+        }
+        return this._gears;
+    }
+    get routes() {
+        if (!this._routes) {
+            this._routes = new RoutesResource(this);
+        }
+        return this._routes;
+    }
+    get uploads() {
+        if (!this._uploads) {
+            this._uploads = new UploadsResource(this);
+        }
+        return this._uploads;
+    }
+    get streams() {
+        if (!this._streams) {
+            this._streams = new StreamsResource(this);
+        }
+        return this._streams;
+    }
+    /**
+     * Clean up resources (stop timers, clear caches)
+     * Call this when you're done with the client to allow the process to exit
+     */
+    destroy() {
+        this.deduplicator.destroy();
+    }
+}
+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";

package/esm/src/errors.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Custom error classes for Strava API interactions
+ */
+/**
+ * Base error class for all Strava API errors
+ */
+export declare class StravaError extends Error {
+    statusCode?: number;
+    response?: unknown;
+    constructor(message: string, statusCode?: number, response?: unknown);
+}
+/**
+ * Authentication-related errors (401, invalid credentials, token expired)
+ */
+export declare class StravaAuthError extends StravaError {
+    constructor(message: string, statusCode?: number, response?: unknown);
+}
+/**
+ * Rate limit errors (429)
+ */
+export declare class StravaRateLimitError extends StravaError {
+    retryAfter?: number;
+    limit?: number;
+    usage?: number;
+    constructor(message: string, statusCode?: number, response?: unknown, retryAfter?: number, limit?: number, usage?: number);
+}
+/**
+ * Resource not found errors (404)
+ */
+export declare class StravaNotFoundError extends StravaError {
+    constructor(message: string, statusCode?: number, response?: unknown);
+}
+/**
+ * Validation errors (422)
+ */
+export declare class StravaValidationError extends StravaError {
+    errors?: Array<{
+        field: string;
+        message: string;
+    }>;
+    constructor(message: string, statusCode?: number, response?: unknown, errors?: Array<{
+        field: string;
+        message: string;
+    }>);
+}
+/**
+ * Server errors (5xx)
+ */
+export declare class StravaServerError extends StravaError {
+    constructor(message: string, statusCode?: number, response?: unknown);
+}
+//# sourceMappingURL=errors.d.ts.map

package/esm/src/errors.js

@@ -0,0 +1,102 @@
+/**
+ * Custom error classes for Strava API interactions
+ */
+/**
+ * Base error class for all Strava API errors
+ */
+export class StravaError extends Error {
+    constructor(message, statusCode, response) {
+        super(message);
+        Object.defineProperty(this, "statusCode", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "response", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.name = "StravaError";
+        this.statusCode = statusCode;
+        this.response = response;
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, StravaError);
+        }
+    }
+}
+/**
+ * Authentication-related errors (401, invalid credentials, token expired)
+ */
+export class StravaAuthError extends StravaError {
+    constructor(message, statusCode, response) {
+        super(message, statusCode, response);
+        this.name = "StravaAuthError";
+    }
+}
+/**
+ * Rate limit errors (429)
+ */
+export class StravaRateLimitError extends StravaError {
+    constructor(message, statusCode, response, retryAfter, limit, usage) {
+        super(message, statusCode, response);
+        Object.defineProperty(this, "retryAfter", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "limit", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "usage", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.name = "StravaRateLimitError";
+        this.retryAfter = retryAfter;
+        this.limit = limit;
+        this.usage = usage;
+    }
+}
+/**
+ * Resource not found errors (404)
+ */
+export class StravaNotFoundError extends StravaError {
+    constructor(message, statusCode, response) {
+        super(message, statusCode, response);
+        this.name = "StravaNotFoundError";
+    }
+}
+/**
+ * Validation errors (422)
+ */
+export class StravaValidationError extends StravaError {
+    constructor(message, statusCode, response, errors) {
+        super(message, statusCode, response);
+        Object.defineProperty(this, "errors", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.name = "StravaValidationError";
+        this.errors = errors;
+    }
+}
+/**
+ * Server errors (5xx)
+ */
+export class StravaServerError extends StravaError {
+    constructor(message, statusCode, response) {
+        super(message, statusCode, response);
+        this.name = "StravaServerError";
+    }
+}

package/esm/src/http/deduplication.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Request deduplication to prevent duplicate requests within a time window
+ */
+/**
+ * Request deduplication cache
+ */
+export declare class RequestDeduplicator {
+    private cache;
+    private cleanupInterval;
+    private readonly windowMs;
+    constructor(windowMs?: number);
+    /**
+     * Generate cache key from request details
+     */
+    private generateKey;
+    /**
+     * Get or create a request promise
+     */
+    getOrCreate<T>(method: string, path: string, query: Record<string, unknown> | undefined, body: unknown, factory: () => Promise<T>): Promise<T>;
+    /**
+     * Clear expired entries
+     */
+    private cleanup;
+    /**
+     * Start periodic cleanup
+     */
+    private startCleanup;
+    /**
+     * Stop cleanup and clear cache
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=deduplication.d.ts.map

package/esm/src/http/deduplication.js

@@ -0,0 +1,96 @@
+/**
+ * Request deduplication to prevent duplicate requests within a time window
+ */
+/**
+ * Request deduplication cache
+ */
+export class RequestDeduplicator {
+    constructor(windowMs = 5000) {
+        Object.defineProperty(this, "cache", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "cleanupInterval", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "windowMs", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.windowMs = windowMs;
+        this.startCleanup();
+    }
+    /**
+     * Generate cache key from request details
+     */
+    generateKey(method, path, query, body) {
+        const parts = [method, path];
+        if (query) {
+            const sortedQuery = Object.keys(query)
+                .sort()
+                .map((key) => `${key}=${String(query[key])}`)
+                .join("&");
+            parts.push(sortedQuery);
+        }
+        if (body) {
+            try {
+                const bodyHash = JSON.stringify(body);
+                parts.push(bodyHash);
+            }
+            catch {
+                parts.push(String(body));
+            }
+        }
+        return parts.join("|");
+    }
+    /**
+     * Get or create a request promise
+     */
+    getOrCreate(method, path, query, body, factory) {
+        const key = this.generateKey(method, path, query, body);
+        const now = Date.now();
+        const cached = this.cache.get(key);
+        if (cached && (now - cached.timestamp) < this.windowMs) {
+            return cached.promise;
+        }
+        const promise = factory();
+        this.cache.set(key, { promise, timestamp: now });
+        return promise;
+    }
+    /**
+     * Clear expired entries
+     */
+    cleanup() {
+        const now = Date.now();
+        for (const [key, entry] of this.cache.entries()) {
+            if (now - entry.timestamp >= this.windowMs) {
+                this.cache.delete(key);
+            }
+        }
+    }
+    /**
+     * Start periodic cleanup
+     */
+    startCleanup() {
+        this.cleanupInterval = setInterval(() => {
+            this.cleanup();
+        }, this.windowMs);
+    }
+    /**
+     * Stop cleanup and clear cache
+     */
+    destroy() {
+        if (this.cleanupInterval !== null) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+        this.cache.clear();
+    }
+}

package/esm/src/http/rate-limiter.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Rate limit tracking and queue management
+ */
+import type { RateLimitInfo, RateLimitStrategy } from "../types/common.js";
+/**
+ * Rate limiter for Strava API
+ */
+export declare class RateLimiter {
+    private shortTermLimit;
+    private shortTermWindow;
+    private dailyLimit;
+    private dailyWindow;
+    private shortTermRequests;
+    private dailyRequests;
+    private queue;
+    private strategy;
+    constructor(strategy?: RateLimitStrategy);
+    /**
+     * Update rate limit info from response headers
+     */
+    updateFromHeaders(headers: Headers): void;
+    /**
+     * Record a request timestamp
+     */
+    private recordRequest;
+    /**
+     * Get current rate limit info
+     */
+    getRateLimitInfo(): RateLimitInfo;
+    /**
+     * Check if we can make a request
+     */
+    canMakeRequest(): boolean;
+    /**
+     * Wait until we can make a request
+     */
+    waitForAvailability(): Promise<void>;
+    /**
+     * Process queued requests
+     */
+    processQueue(): void;
+    /**
+     * Set rate limit strategy
+     */
+    setStrategy(strategy: RateLimitStrategy): void;
+}
+//# sourceMappingURL=rate-limiter.d.ts.map