@pinta365/strava 0.0.1

package/esm/src/http/rate-limiter.js

@@ -0,0 +1,168 @@
+/**
+ * Rate limit tracking and queue management
+ */
+/**
+ * Rate limiter for Strava API
+ */
+export class RateLimiter {
+    constructor(strategy = "queue") {
+        Object.defineProperty(this, "shortTermLimit", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 600
+        });
+        Object.defineProperty(this, "shortTermWindow", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 15 * 60 * 1000
+        });
+        Object.defineProperty(this, "dailyLimit", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 30000
+        });
+        Object.defineProperty(this, "dailyWindow", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 24 * 60 * 60 * 1000
+        });
+        Object.defineProperty(this, "shortTermRequests", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "dailyRequests", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "queue", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "strategy", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.strategy = strategy;
+    }
+    /**
+     * Update rate limit info from response headers
+     */
+    updateFromHeaders(headers) {
+        const shortTermLimit = headers.get("X-RateLimit-Limit");
+        const shortTermUsage = headers.get("X-RateLimit-Usage");
+        const dailyLimit = headers.get("X-RateLimit-Limit-Daily");
+        const dailyUsage = headers.get("X-RateLimit-Usage-Daily");
+        if (shortTermLimit) {
+            this.shortTermLimit = parseInt(shortTermLimit, 10);
+        }
+        if (shortTermUsage) {
+            const parts = shortTermUsage.split(",");
+            if (parts.length >= 1) {
+                const current = parseInt(parts[0], 10);
+                this.recordRequest("shortTerm", current);
+            }
+        }
+        if (dailyLimit) {
+            this.dailyLimit = parseInt(dailyLimit, 10);
+        }
+        if (dailyUsage) {
+            const parts = dailyUsage.split(",");
+            if (parts.length >= 1) {
+                const current = parseInt(parts[0], 10);
+                this.recordRequest("daily", current);
+            }
+        }
+    }
+    /**
+     * Record a request timestamp
+     */
+    recordRequest(type, _currentUsage) {
+        const now = Date.now();
+        const window = type === "shortTerm" ? this.shortTermWindow : this.dailyWindow;
+        const requests = type === "shortTerm" ? this.shortTermRequests : this.dailyRequests;
+        const cutoff = now - window;
+        while (requests.length > 0 && requests[0] < cutoff) {
+            requests.shift();
+        }
+        requests.push(now);
+    }
+    /**
+     * Get current rate limit info
+     */
+    getRateLimitInfo() {
+        const now = Date.now();
+        const shortTermCutoff = now - this.shortTermWindow;
+        this.shortTermRequests = this.shortTermRequests.filter((t) => t >= shortTermCutoff);
+        const dailyCutoff = now - this.dailyWindow;
+        this.dailyRequests = this.dailyRequests.filter((t) => t >= dailyCutoff);
+        return {
+            shortTermLimit: this.shortTermLimit,
+            shortTermUsage: this.shortTermRequests.length,
+            dailyLimit: this.dailyLimit,
+            dailyUsage: this.dailyRequests.length,
+        };
+    }
+    /**
+     * Check if we can make a request
+     */
+    canMakeRequest() {
+        const info = this.getRateLimitInfo();
+        return (info.shortTermUsage ?? 0) < (info.shortTermLimit ?? 600) &&
+            (info.dailyUsage ?? 0) < (info.dailyLimit ?? 30000);
+    }
+    /**
+     * Wait until we can make a request
+     */
+    async waitForAvailability() {
+        if (this.canMakeRequest()) {
+            return;
+        }
+        if (this.strategy === "throw") {
+            const info = this.getRateLimitInfo();
+            throw new Error(`Rate limit exceeded. Short-term: ${info.shortTermUsage}/${info.shortTermLimit}, ` +
+                `Daily: ${info.dailyUsage}/${info.dailyLimit}`);
+        }
+        if (this.strategy === "wait") {
+            while (!this.canMakeRequest()) {
+                await new Promise((resolve) => setTimeout(resolve, 1000));
+            }
+            return;
+        }
+        return new Promise((resolve, reject) => {
+            this.queue.push({
+                resolve,
+                reject,
+                timestamp: Date.now(),
+            });
+        });
+    }
+    /**
+     * Process queued requests
+     */
+    processQueue() {
+        while (this.queue.length > 0 && this.canMakeRequest()) {
+            const request = this.queue.shift();
+            if (request) {
+                request.resolve(undefined);
+            }
+        }
+    }
+    /**
+     * Set rate limit strategy
+     */
+    setStrategy(strategy) {
+        this.strategy = strategy;
+    }
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Core HTTP request handler
+ */
+import type { RateLimiter } from "./rate-limiter.js";
+import type { RequestDeduplicator } from "./deduplication.js";
+import type { RequestConfig, RetryConfig } from "../types/common.js";
+interface RequestOptions {
+    baseUrl?: string;
+    timeout?: number;
+    accessToken?: string;
+    rateLimiter?: RateLimiter;
+    deduplicator?: RequestDeduplicator;
+    retryConfig?: RetryConfig;
+    normalizeKeys?: boolean;
+    transformDates?: boolean;
+    flattenResponses?: boolean;
+    addComputedFields?: boolean;
+}
+/**
+ * Make HTTP request with retry, rate limiting, and error handling
+ */
+export declare function request<T>(config: RequestConfig, options?: RequestOptions): Promise<T>;
+export {};
+//# sourceMappingURL=request.d.ts.map

package/esm/src/http/request.js

@@ -0,0 +1,158 @@
+/**
+ * Core HTTP request handler
+ */
+import { StravaAuthError, StravaError, StravaNotFoundError, StravaRateLimitError, StravaServerError, StravaValidationError } from "../errors.js";
+import { withRetry } from "./retry.js";
+import { applyTransformations } from "../utils/transformers.js";
+const DEFAULT_BASE_URL = "https://www.strava.com/api/v3";
+const DEFAULT_TIMEOUT = 30000;
+/**
+ * Extract rate limit info from response headers
+ */
+function extractRateLimitInfo(headers) {
+    const shortTermLimit = headers.get("X-RateLimit-Limit");
+    const shortTermUsage = headers.get("X-RateLimit-Usage");
+    const dailyLimit = headers.get("X-RateLimit-Limit-Daily");
+    const dailyUsage = headers.get("X-RateLimit-Usage-Daily");
+    const info = {};
+    if (shortTermLimit) {
+        info.shortTermLimit = parseInt(shortTermLimit, 10);
+    }
+    if (shortTermUsage) {
+        const parts = shortTermUsage.split(",");
+        if (parts.length >= 1) {
+            info.shortTermUsage = parseInt(parts[0], 10);
+        }
+    }
+    if (dailyLimit) {
+        info.dailyLimit = parseInt(dailyLimit, 10);
+    }
+    if (dailyUsage) {
+        const parts = dailyUsage.split(",");
+        if (parts.length >= 1) {
+            info.dailyUsage = parseInt(parts[0], 10);
+        }
+    }
+    return info;
+}
+/**
+ * Build query string from query parameters
+ */
+function buildQueryString(query) {
+    if (!query)
+        return "";
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value !== undefined && value !== null) {
+            params.append(key, String(value));
+        }
+    }
+    const queryString = params.toString();
+    return queryString ? `?${queryString}` : "";
+}
+/**
+ * Create error from response
+ */
+async function createErrorFromResponse(response) {
+    const statusCode = response.status;
+    let errorData;
+    try {
+        errorData = await response.json();
+    }
+    catch {
+        errorData = await response.text().catch(() => undefined);
+    }
+    const message = typeof errorData === "object" && errorData !== null && "message" in errorData
+        ? String(errorData.message)
+        : `HTTP ${statusCode}: ${response.statusText}`;
+    const rateLimitInfo = extractRateLimitInfo(response.headers);
+    const retryAfter = response.headers.get("Retry-After");
+    switch (statusCode) {
+        case 401:
+        case 403:
+            return new StravaAuthError(message, statusCode, errorData);
+        case 404:
+            return new StravaNotFoundError(message, statusCode, errorData);
+        case 422: {
+            const errors = typeof errorData === "object" && errorData !== null && "errors" in errorData
+                ? errorData.errors
+                : undefined;
+            return new StravaValidationError(message, statusCode, errorData, errors);
+        }
+        case 429:
+            return new StravaRateLimitError(message, statusCode, errorData, retryAfter ? parseInt(retryAfter, 10) : undefined, rateLimitInfo.shortTermLimit, rateLimitInfo.shortTermUsage);
+        case 500:
+        case 502:
+        case 503:
+        case 504:
+            return new StravaServerError(message, statusCode, errorData);
+        default:
+            return new StravaError(message, statusCode, errorData);
+    }
+}
+/**
+ * Make HTTP request with retry, rate limiting, and error handling
+ */
+export function request(config, options = {}) {
+    const { baseUrl = DEFAULT_BASE_URL, timeout = DEFAULT_TIMEOUT, accessToken, rateLimiter, deduplicator, retryConfig, normalizeKeys = true, transformDates = false, flattenResponses = false, addComputedFields = false, } = options;
+    const queryString = buildQueryString(config.query);
+    const url = `${baseUrl}${config.path}${queryString}`;
+    const headers = {
+        "Content-Type": "application/json",
+        ...config.headers,
+    };
+    if (accessToken) {
+        headers["Authorization"] = `Bearer ${accessToken}`;
+    }
+    const makeRequest = async () => {
+        if (rateLimiter) {
+            await rateLimiter.waitForAvailability();
+        }
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+        try {
+            const response = await fetch(url, {
+                method: config.method,
+                headers,
+                body: config.body ? JSON.stringify(config.body) : undefined,
+                signal: controller.signal,
+            });
+            if (rateLimiter) {
+                rateLimiter.updateFromHeaders(response.headers);
+                rateLimiter.processQueue();
+            }
+            if (!response.ok) {
+                throw await createErrorFromResponse(response);
+            }
+            const rawData = await response.json();
+            const transformedData = applyTransformations(rawData, normalizeKeys, transformDates, flattenResponses, addComputedFields);
+            return transformedData;
+        }
+        catch (error) {
+            if (error instanceof StravaError) {
+                throw error;
+            }
+            if (error instanceof Error && error.name === "AbortError") {
+                throw new StravaError(`Request timeout after ${timeout}ms`, undefined, error);
+            }
+            throw new StravaError(error instanceof Error ? error.message : "Unknown error", undefined, error);
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    };
+    if (deduplicator) {
+        return deduplicator.getOrCreate(config.method, config.path, config.query, config.body, () => withRetry(makeRequest, retryConfig, (error) => {
+            if (error instanceof StravaRateLimitError && error.retryAfter) {
+                return error.retryAfter;
+            }
+            return undefined;
+        }));
+    }
+    return withRetry(makeRequest, retryConfig, (error) => {
+        if (error instanceof StravaRateLimitError && error.retryAfter) {
+            return error.retryAfter;
+        }
+        return undefined;
+    });
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Retry logic with exponential backoff
+ */
+import type { RetryConfig } from "../types/common.js";
+/**
+ * Execute a function with retry logic
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, config?: RetryConfig, getRetryAfter?: (error: unknown) => number | undefined): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/esm/src/http/retry.js

@@ -0,0 +1,61 @@
+/**
+ * Retry logic with exponential backoff
+ */
+const DEFAULT_RETRY_CONFIG = {
+    maxAttempts: 3,
+    initialDelay: 1000,
+    maxDelay: 10000,
+    backoffFactor: 2,
+    retryableStatusCodes: [429, 500, 502, 503, 504],
+};
+/**
+ * Calculate delay for retry attempt
+ */
+function calculateDelay(attempt, config, retryAfter) {
+    if (retryAfter !== undefined) {
+        return Math.min(retryAfter * 1000, config.maxDelay);
+    }
+    const delay = config.initialDelay * Math.pow(config.backoffFactor, attempt - 1);
+    return Math.min(delay, config.maxDelay);
+}
+/**
+ * Sleep for specified milliseconds
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Check if error/status code is retryable
+ */
+function isRetryable(statusCode, config) {
+    if (statusCode === undefined) {
+        return true;
+    }
+    return config.retryableStatusCodes.includes(statusCode);
+}
+/**
+ * Execute a function with retry logic
+ */
+export async function withRetry(fn, config, getRetryAfter) {
+    const retryConfig = { ...DEFAULT_RETRY_CONFIG, ...config };
+    let lastError;
+    for (let attempt = 1; attempt <= retryConfig.maxAttempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt >= retryConfig.maxAttempts) {
+                break;
+            }
+            const statusCode = error && typeof error === "object" && "statusCode" in error ? error.statusCode : undefined;
+            if (!isRetryable(statusCode, retryConfig)) {
+                throw error;
+            }
+            const retryAfter = getRetryAfter ? getRetryAfter(error) : undefined;
+            const delay = calculateDelay(attempt, retryConfig, retryAfter);
+            await sleep(delay);
+        }
+    }
+    throw lastError;
+}

package/esm/src/resources/activities.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Activities resource
+ */
+import type { StravaClient } from "../client.js";
+import type { ActivityZone, Comment, DetailedActivity, DetailedSegmentEffort, Lap, StreamSet, SummaryActivity, SummaryAthlete } from "../types/api.js";
+import type { StreamType } from "./streams.js";
+/**
+ * Options for listing activities
+ */
+export interface ListActivitiesOptions {
+    /** Unix timestamp for activities before this time */
+    before?: number;
+    /** Unix timestamp for activities after this time */
+    after?: number;
+    /** Page number (default: 1) */
+    page?: number;
+    /** Number of items per page (default: 30, max: 200) */
+    perPage?: number;
+}
+/**
+ * Data for creating a new activity
+ */
+export interface CreateActivityData {
+    /** Activity name */
+    name: string;
+    /** Activity type (e.g., "Run", "Ride") */
+    type: string;
+    /** Start date in ISO 8601 format */
+    startDateLocal: string;
+    /** Elapsed time in seconds */
+    elapsedTime: number;
+    /** Activity description */
+    description?: string;
+    /** Distance in meters */
+    distance?: number;
+    /** Whether activity was done on trainer */
+    trainer?: boolean;
+    /** Whether activity is a commute */
+    commute?: boolean;
+}
+/**
+ * Data for updating an existing activity
+ */
+export interface UpdateActivityData {
+    /** Activity name */
+    name?: string;
+    /** Activity type (e.g., "Run", "Ride") */
+    type?: string;
+    /** Sport type */
+    sportType?: string;
+    /** Start date in ISO 8601 format */
+    startDateLocal?: string;
+    /** Elapsed time in seconds */
+    elapsedTime?: number;
+    /** Activity description */
+    description?: string;
+    /** Distance in meters */
+    distance?: number;
+    /** Whether activity was done on trainer */
+    trainer?: boolean;
+    /** Whether activity is a commute */
+    commute?: boolean;
+    /** Gear ID */
+    gearId?: string;
+}
+/**
+ * Resource for interacting with Strava activities
+ */
+export declare class ActivitiesResource {
+    private client;
+    constructor(client: StravaClient);
+    /**
+     * Get activity by ID
+     */
+    getById(id: number): Promise<DetailedActivity>;
+    /**
+     * List athlete activities
+     */
+    list(options?: ListActivitiesOptions): Promise<SummaryActivity[]>;
+    /**
+     * List all activities (auto-pagination)
+     */
+    listAll(options?: Omit<ListActivitiesOptions, "page">): AsyncGenerator<SummaryActivity, void, unknown>;
+    /**
+     * Create activity
+     */
+    create(data: CreateActivityData): Promise<DetailedActivity>;
+    /**
+     * Update activity
+     */
+    update(id: number, data: UpdateActivityData): Promise<DetailedActivity>;
+    /**
+     * Delete activity
+     */
+    delete(id: number): Promise<void>;
+    /**
+     * Get activity with details (combines activity + laps + zones + comments + kudoers)
+     */
+    getWithDetails(id: number): Promise<DetailedActivity & {
+        laps: Lap[];
+        zones: ActivityZone[];
+        comments: Comment[];
+        kudoers: SummaryAthlete[];
+    }>;
+    /**
+     * Get activity laps
+     */
+    getLaps(id: number): Promise<Lap[]>;
+    /**
+     * Get activity zones
+     */
+    getZones(id: number): Promise<ActivityZone[]>;
+    /**
+     * Get activity comments
+     */
+    getComments(id: number, options?: {
+        page?: number;
+        perPage?: number;
+    }): Promise<Comment[]>;
+    /**
+     * Get activity kudoers
+     */
+    getKudoers(id: number, options?: {
+        page?: number;
+        perPage?: number;
+    }): Promise<SummaryAthlete[]>;
+    /**
+     * Analyze activity with comprehensive data
+     * Combines activity, zones, laps, best efforts (segments), and optionally streams
+     */
+    analyze(id: number, options?: {
+        includeStreams?: boolean;
+        streamTypes?: StreamType[];
+    }): Promise<DetailedActivity & {
+        zones: ActivityZone[];
+        laps: Lap[];
+        bestEfforts: DetailedSegmentEffort[];
+        streams?: StreamSet;
+        analysis: {
+            hasPowerData: boolean;
+            hasHeartRateData: boolean;
+            totalLaps: number;
+            bestEffortCount: number;
+            averageLapTime?: number;
+            averageLapDistance?: number;
+        };
+    }>;
+}
+//# sourceMappingURL=activities.d.ts.map