@torqlab/strava-api 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TORQ Lab
+
+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

@@ -0,0 +1,167 @@
+# @torqlab/strava-api
+
+TypeScript client for the Strava API with automatic rate limiting, retry handling, and comprehensive type safety.
+
+This package provides a robust interface to the Strava API, handling OAuth authentication, automatic token refresh, intelligent rate limiting, and retry logic. Built with TypeScript for complete type safety and designed for production use.
+
+## Install
+
+Published to NPM.
+
+```bash
+npm i @torqlab/strava-api
+```
+
+Or with Bun:
+
+```bash
+bun add @torqlab/strava-api
+```
+
+## Quick start
+
+```ts
+import { fetchActivity, fetchActivities, getAuthUrl, exchangeToken } from '@torqlab/strava-api';
+import type { StravaApiConfig, StravaActivity } from '@torqlab/strava-api';
+
+// OAuth flow - get authorization URL
+const authUrl = getAuthUrl({
+  clientId: 'your-client-id',
+  redirectUri: 'http://localhost:3000/callback',
+  scope: 'read,activity:read_all',
+});
+
+console.log(`Visit: ${authUrl}`);
+
+// Exchange authorization code for tokens
+const tokens = await exchangeToken({
+  clientId: 'your-client-id',
+  clientSecret: 'your-client-secret',
+  code: 'authorization-code-from-callback',
+});
+
+// Configure API client
+const config: StravaApiConfig = {
+  accessToken: tokens.access_token,
+  refreshToken: tokens.refresh_token,
+  clientId: 'your-client-id',
+  clientSecret: 'your-client-secret',
+};
+
+// Fetch a single activity
+const activity: StravaActivity = await fetchActivity(config, 12345678);
+
+console.log(`Activity: ${activity.name}`);
+console.log(`Distance: ${activity.distance}m`);
+console.log(`Moving time: ${activity.moving_time}s`);
+
+// Fetch multiple activities
+const activities: StravaActivity[] = await fetchActivities(config, {
+  per_page: 10,
+  page: 1,
+});
+
+console.log(`Found ${activities.length} activities`);
+```
+
+## Features
+
+- **Type Safety**: Full TypeScript support with comprehensive type definitions
+- **OAuth 2.0**: Complete OAuth flow with authorization URL generation and token exchange
+- **Automatic Token Refresh**: Handles expired access tokens automatically
+- **Rate Limiting**: Intelligent rate limit handling with exponential backoff
+- **Retry Logic**: Automatic retry for transient failures
+- **Error Handling**: Comprehensive error types and messages
+- **Validation**: Input validation for activity IDs and configuration
+- **Zero Dependencies**: No external runtime dependencies
+
+## API Reference
+
+### Authentication
+
+#### `getAuthUrl(params)`
+
+Generate OAuth authorization URL.
+
+```ts
+const authUrl = getAuthUrl({
+  clientId: 'your-client-id',
+  redirectUri: 'http://localhost:3000/callback',
+  scope: 'read,activity:read_all', // Optional, defaults to 'read'
+  state: 'random-state-string', // Optional
+});
+```
+
+#### `exchangeToken(params)`
+
+Exchange authorization code for access tokens.
+
+```ts
+const tokens = await exchangeToken({
+  clientId: 'your-client-id',
+  clientSecret: 'your-client-secret',
+  code: 'authorization-code',
+});
+```
+
+### Activities
+
+#### `fetchActivity(config, activityId)`
+
+Fetch a single activity by ID.
+
+```ts
+const activity = await fetchActivity(config, 12345678);
+```
+
+#### `fetchActivities(config, params?)`
+
+Fetch multiple activities with optional pagination.
+
+```ts
+const activities = await fetchActivities(config, {
+  per_page: 30,
+  page: 1,
+  before: 1640995200, // Unix timestamp
+  after: 1609459200, // Unix timestamp
+});
+```
+
+### Configuration
+
+The `StravaApiConfig` interface supports:
+
+- `accessToken`: OAuth2 access token (required)
+- `refreshToken`: OAuth2 refresh token for automatic renewal
+- `clientId`: OAuth2 client ID for token refresh
+- `clientSecret`: OAuth2 client secret for token refresh
+- `guardrails`: Optional validation callback for activities
+
+## Error Handling
+
+The package provides comprehensive error handling with typed error codes:
+
+```ts
+import { fetchActivity } from '@torqlab/strava-api';
+import type { StravaApiError } from '@torqlab/strava-api';
+
+try {
+  const activity = await fetchActivity(config, activityId);
+} catch (error) {
+  if (error.code === 'RATE_LIMITED') {
+    console.log('Rate limited, retry after delay');
+  } else if (error.code === 'UNAUTHORIZED') {
+    console.log('Token expired, refresh needed');
+  } else if (error.code === 'NOT_FOUND') {
+    console.log('Activity not found');
+  }
+}
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Issues and pull requests are welcome on [GitHub](https://github.com/torqlab/strava-api).

package/dist/client/client.d.ts

@@ -0,0 +1,34 @@
+import type { StravaApiConfig } from '../types';
+/**
+ * Fetches activities list from the Strava API.
+ *
+ * Makes an authenticated HTTP GET request to the Strava API to retrieve
+ * a list of activities for the authenticated athlete. Handles various HTTP
+ * error responses and maps them to appropriate `StravaApiError` codes.
+ *
+ * @template T - The expected return type of the API response (e.g. `StravaActivity`).
+ * @param {string} url - The API endpoint URL.
+ * @param {StravaApiConfig} config - Strava API configuration with access token and optional base URL.
+ * @returns {Promise<T>} Promise resolving to the raw Strava API response data array.
+ * @throws {Error} Throws an error with `StravaApiError` structure for various failure scenarios:
+ *   - 'NETWORK_ERROR' (retryable): Network connection failure.
+ *   - 'UNAUTHORIZED' (not retryable): Invalid or expired token (401).
+ *   - 'FORBIDDEN' (not retryable): Insufficient permissions (403).
+ *   - 'RATE_LIMITED' (retryable): Rate limit exceeded (429).
+ *   - 'SERVER_ERROR' (retryable): Strava API server error (5xx).
+ *   - 'MALFORMED_RESPONSE' (not retryable): Invalid JSON response or not an array.
+ *   - And others...
+ *
+ * @see {@link https://developers.strava.com/docs/reference/#api-Activities-getLoggedInAthleteActivities | Strava Get Activities API}
+ *
+ * @example
+ * ```typescript
+ * const activities = await client<StravaActivity[]>(
+ *  STRAVA_API_ENDPOINTS.ACTIVITIES,
+ *  { accessToken: 'abc123' },
+ * );
+ * ```
+ */
+declare const client: <T>(url: string, config: StravaApiConfig) => Promise<T>;
+export default client;
+//# sourceMappingURL=client.d.ts.map

package/dist/client/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../client/client.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAwBhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,QAAA,MAAM,MAAM,GAAU,CAAC,EAAE,KAAK,MAAM,EAAE,QAAQ,eAAe,KAAG,OAAO,CAAC,CAAC,CAMxE,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/client/create-error/create-error.d.ts

@@ -0,0 +1,13 @@
+import type { StravaApiErrorCode } from '../../types';
+/**
+ * Creates an `StravaApiError` wrapped in an `Error` object.
+ * @param {StravaApiErrorCode} code - Error code from `StravaApiErrorCode` union type.
+ * @param {string} message - User-friendly error message.
+ * @param {boolean} [retryable=false] - Whether the error is retryable (default: false).
+ * @param {Response} [response] - Optional fetch `Response` object to include in the error for additional context (e.g. rate limit headers).
+ * @returns {Error} Error object with JSON-stringified `StravaApiError` in message.
+ * @internal
+ */
+declare const createError: (code: StravaApiErrorCode, message: string, retryable?: boolean, response?: Response) => Error;
+export default createError;
+//# sourceMappingURL=create-error.d.ts.map

package/dist/client/create-error/create-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-error.d.ts","sourceRoot":"","sources":["../../../client/create-error/create-error.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtE;;;;;;;;GAQG;AACH,QAAA,MAAM,WAAW,GACf,MAAM,kBAAkB,EACxB,SAAS,MAAM,EACf,YAAW,OAAe,EAC1B,WAAW,QAAQ,KAClB,KAkBF,CAAC;AAEF,eAAe,WAAW,CAAC"}

package/dist/client/create-error/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './create-error';
+//# sourceMappingURL=index.d.ts.map

package/dist/client/create-error/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../client/create-error/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/client/get-auth-headers/get-auth-headers.d.ts

@@ -0,0 +1,22 @@
+import { StravaApiConfig } from '../../types';
+/**
+ * Builds HTTP headers for Strava API authentication.
+ *
+ * Creates the Authorization header using OAuth2 Bearer token format as required
+ * by the Strava API. The header format follows RFC 6750 Bearer Token Usage.
+ *
+ * @param {StravaApiConfig} config - Strava API configuration containing the access token.
+ * @returns {HeadersInit} Headers object with Authorization header set to "Bearer {token}".
+ *
+ * @see {@link https://developers.strava.com/docs/authentication/ | Strava API Authentication}
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc6750 | RFC 6750: Bearer Token Usage}
+ *
+ * @example
+ * ```typescript
+ * const headers = getAuthHeaders({ accessToken: 'abc123' });
+ * // Returns: { Authorization: 'Bearer abc123' }
+ * ```
+ */
+declare const getAuthHeaders: (config: StravaApiConfig) => HeadersInit;
+export default getAuthHeaders;
+//# sourceMappingURL=get-auth-headers.d.ts.map

package/dist/client/get-auth-headers/get-auth-headers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-auth-headers.d.ts","sourceRoot":"","sources":["../../../client/get-auth-headers/get-auth-headers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;;;;;;;;;;;GAiBG;AACH,QAAA,MAAM,cAAc,GAAI,QAAQ,eAAe,KAAG,WAMjD,CAAC;AAEF,eAAe,cAAc,CAAC"}

package/dist/client/get-auth-headers/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './get-auth-headers';
+//# sourceMappingURL=index.d.ts.map

package/dist/client/get-auth-headers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../client/get-auth-headers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/client/handle-fetch-error/handle-fetch-error.d.ts

@@ -0,0 +1,19 @@
+import { StravaApiConfig } from '../../types';
+/**
+ * Handles errors from API fetch, including rate limits and unauthorized errors.
+ *
+ * For rate limit errors, it waits for the appropriate duration before retrying.
+ * For unauthorized errors, it attempts to refresh the token if possible and retry.
+ * For other errors, it rethrows them to be handled by the retry logic.
+ *
+ * @template T - The expected return type of the API fetch function.
+ * @param {Function} fn - The API fetch function to execute during error handling.
+ * @param {StravaApiConfig} config - Strava API configuration.
+ * @param {unknown} error - The error object thrown from the API fetch attempt.
+ * @returns {Promise<T>} Promise resolving to the expected return type if retry is successful.
+ * @throws {Error} Throws the original error if it's not a rate limit or unauthorized error, or if retries are exhausted.
+ * @internal
+ */
+declare const handleFetchError: <T>(fn: (config: StravaApiConfig) => Promise<T>, config: StravaApiConfig, error: unknown) => Promise<T>;
+export default handleFetchError;
+//# sourceMappingURL=handle-fetch-error.d.ts.map

package/dist/client/handle-fetch-error/handle-fetch-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle-fetch-error.d.ts","sourceRoot":"","sources":["../../../client/handle-fetch-error/handle-fetch-error.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAA8B,MAAM,aAAa,CAAC;AAK1E;;;;;;;;;;;;;;GAcG;AACH,QAAA,MAAM,gBAAgB,GAAU,CAAC,EAC/B,IAAI,CAAC,MAAM,EAAE,eAAe,KAAK,OAAO,CAAC,CAAC,CAAC,EAC3C,QAAQ,eAAe,EACvB,OAAO,OAAO,KACb,OAAO,CAAC,CAAC,CAwCX,CAAC;AAEF,eAAe,gBAAgB,CAAC"}

package/dist/client/handle-fetch-error/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './handle-fetch-error';
+//# sourceMappingURL=index.d.ts.map

package/dist/client/handle-fetch-error/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../client/handle-fetch-error/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/client/handle-rate-limit/constants.d.ts

@@ -0,0 +1,3 @@
+export declare const DEFAULT_WAIT_MS: number;
+export declare const WINDOW_MS: number;
+//# sourceMappingURL=constants.d.ts.map

package/dist/client/handle-rate-limit/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../client/handle-rate-limit/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,eAAe,QAAY,CAAC;AAEzC,eAAO,MAAM,SAAS,QAAiB,CAAC"}

package/dist/client/handle-rate-limit/handle-rate-limit.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Handles rate limit responses from Strava API by waiting appropriately.
+ *
+ * Parses rate limit headers from HTTP response and waits for the appropriate
+ * duration before allowing retry. Prioritizes `Retry-After` header if present,
+ * otherwise uses rate limit usage headers to calculate wait time. Falls back
+ * to default 60-second wait if no rate limit information is available.
+ *
+ * Rate limit headers parsed:
+ * - `Retry-After`: Seconds to wait (highest priority)
+ * - `X-RateLimit-Limit`: Maximum requests per window
+ * - `X-RateLimit-Usage`: Current request count
+ *
+ * If usage >= limit, waits for full 15-minute window.
+ *
+ * @param {Response} response - HTTP Response object containing rate limit headers.
+ * @returns {Promise<void>} Promise that resolves after waiting for the calculated duration.
+ *
+ * @see {@link https://developers.strava.com/docs/rate-limits/ | Strava API Rate Limits}
+ *
+ * @example
+ * ```typescript
+ * const response = new Response('Rate Limited', {
+ *   status: 429,
+ *   headers: { 'Retry-After': '5' }
+ * });
+ * await handleRateLimit(response); // Waits 5 seconds
+ * ```
+ */
+declare const handleRateLimit: (response: Response) => Promise<void>;
+export default handleRateLimit;
+//# sourceMappingURL=handle-rate-limit.d.ts.map

package/dist/client/handle-rate-limit/handle-rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle-rate-limit.d.ts","sourceRoot":"","sources":["../../../client/handle-rate-limit/handle-rate-limit.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,QAAA,MAAM,eAAe,GAAU,UAAU,QAAQ,KAAG,OAAO,CAAC,IAAI,CAkC/D,CAAC;AAEF,eAAe,eAAe,CAAC"}

package/dist/client/handle-rate-limit/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './handle-rate-limit';
+//# sourceMappingURL=index.d.ts.map

package/dist/client/handle-rate-limit/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../client/handle-rate-limit/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/client/handle-retry/handle-retry.d.ts

@@ -0,0 +1,30 @@
+import { Input } from './types';
+/**
+ * Implements retry logic with exponential backoff for async operations.
+ *
+ * Executes a function with automatic retries on failure. Uses exponential backoff
+ * strategy (doubling delay on each retry) up to a maximum delay. Only retries
+ * errors marked as retryable (`ActivityError.retryable === true`). Non-retryable
+ * errors are immediately thrown without retry attempts.
+ *
+ * @template T - The return type of the function being retried.
+ * @param {Input<T>} params - Parameters for the retry logic.
+ * @param {RetryFunction<T>} params.fn - Async function to execute and retry on failure.
+ * @param {number} params.maxRetries - Maximum number of retry attempts before giving up.
+ * @param {number} [params.initialBackoffMs=STRAVA_API_INITIAL_BACKOFF_MS] - Initial backoff delay in milliseconds (default is 1000ms).
+ * @returns {Promise<T>} Promise resolving to the function's return value on success.
+ * @throws {Error} Throws the last error encountered if all retries are exhausted.
+ *
+ * @example
+ * ```typescript
+ * const result = await handleRetry(
+ *   () => fetchFromApi('123456', config),
+ *   3, // max 3 retries
+ *   1000 // start with 1 second delay
+ * );
+ * // Retry delays: 1s, 2s, 4s (capped at MAX_BACKOFF_MS)
+ * ```
+ */
+declare const handleRetry: <T>({ fn, maxRetries, initialBackoffMs, }: Input<T>) => Promise<T>;
+export default handleRetry;
+//# sourceMappingURL=handle-retry.d.ts.map

package/dist/client/handle-retry/handle-retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle-retry.d.ts","sourceRoot":"","sources":["../../../client/handle-retry/handle-retry.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAiB,MAAM,SAAS,CAAC;AAuE/C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,QAAA,MAAM,WAAW,GAAU,CAAC,EAAE,uCAI3B,KAAK,CAAC,CAAC,CAAC,KAAG,OAAO,CAAC,CAAC,CAAkE,CAAC;AAE1F,eAAe,WAAW,CAAC"}

package/dist/client/handle-retry/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './handle-retry';
+//# sourceMappingURL=index.d.ts.map

package/dist/client/handle-retry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../client/handle-retry/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/client/handle-retry/types.d.ts

@@ -0,0 +1,7 @@
+export type RetryFunction<T> = () => Promise<T>;
+export interface Input<T> {
+    fn: RetryFunction<T>;
+    maxRetries: number;
+    initialBackoffMs?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/client/handle-retry/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../client/handle-retry/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;AAEhD,MAAM,WAAW,KAAK,CAAC,CAAC;IACtB,EAAE,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B"}

package/dist/client/index.d.ts

@@ -0,0 +1,4 @@
+export { default } from './client';
+export { default as createError } from './create-error';
+export { default as handleRetry } from './handle-retry';
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/client/parse-error/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './parse-error';
+//# sourceMappingURL=index.d.ts.map

package/dist/client/parse-error/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../client/parse-error/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC"}

package/dist/client/parse-error/parse-error.d.ts

@@ -0,0 +1,14 @@
+import type { StravaApiError } from '../../types';
+/**
+ * Parses an `Error` object to extract `StravaApiError` if present.
+ *
+ * Attempts to parse the error message as JSON to extract structured `StravaApiError`.
+ * Returns `null` if parsing fails or error doesn't contain `StravaApiError` structure.
+ *
+ * @param {Error} error - Error object potentially containing `StravaApiError` in message.
+ * @returns {StravaApiError | null} `StravaApiError` if successfully parsed, `null` otherwise.
+ * @internal
+ */
+declare const parseError: (error: unknown) => StravaApiError | null;
+export default parseError;
+//# sourceMappingURL=parse-error.d.ts.map

package/dist/client/parse-error/parse-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-error.d.ts","sourceRoot":"","sources":["../../../client/parse-error/parse-error.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;;;;;GASG;AACH,QAAA,MAAM,UAAU,GAAI,OAAO,OAAO,KAAG,cAAc,GAAG,IAMrD,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/client/parse-error-code/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './parse-error-code';
+//# sourceMappingURL=index.d.ts.map

package/dist/client/parse-error-code/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../client/parse-error-code/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/client/parse-error-code/parse-error-code.d.ts

@@ -0,0 +1,12 @@
+import type { StravaApiErrorCode } from '../../types';
+/**
+ * Parses error code from an Error object.
+ * Attempts to parse the error message as JSON to extract structured `StravaApiError`.
+ * Returns `null` if parsing fails or error doesn't contain `StravaApiError` structure.
+ * @param {Error} error - Error object potentially containing `StravaApiError` in message.
+ * @returns {StravaApiErrorCode | null} `StravaApiErrorCode` if successfully parsed, `null` otherwise.
+ * @internal
+ */
+declare const parseErrorCode: (error: unknown) => StravaApiErrorCode | null;
+export default parseErrorCode;
+//# sourceMappingURL=parse-error-code.d.ts.map

package/dist/client/parse-error-code/parse-error-code.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-error-code.d.ts","sourceRoot":"","sources":["../../../client/parse-error-code/parse-error-code.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGtD;;;;;;;GAOG;AACH,QAAA,MAAM,cAAc,GAAI,OAAO,OAAO,KAAG,kBAAkB,GAAG,IAQ7D,CAAC;AAEF,eAAe,cAAc,CAAC"}

package/dist/client/parse-response/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './parse-response';
+//# sourceMappingURL=index.d.ts.map

package/dist/client/parse-response/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../client/parse-response/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/client/parse-response/parse-response.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Parses Strava API response.
+ * Handles various HTTP error responses and maps them to appropriate `StravaApiError` codes.
+ * @template T - The expected return type of the parsed API response (e.g. `StravaActivity`).
+ * @param {Response} response - The fetch `Response` object from the API request.
+ * @returns {Promise<T>} Promise resolving to the raw Strava API response.
+ * @throws {Error} Throws an error with `StravaApiError` structure for various failure scenarios:
+ *   - 'NETWORK_ERROR' (retryable): Network connection failure.
+ *   - 'UNAUTHORIZED' (not retryable): Invalid or expired token (401).
+ *   - 'FORBIDDEN' (not retryable): Insufficient permissions (403).
+ *   - 'RATE_LIMITED' (retryable): Rate limit exceeded (429).
+ *   - 'SERVER_ERROR' (retryable): Strava API server error (5xx).
+ *   - 'MALFORMED_RESPONSE' (not retryable): Invalid JSON response or empty response.
+ *   - And others...
+ *
+ * @see {@link https://developers.strava.com/docs/reference/ | Strava API}
+ *
+ * @example
+ * ```typescript
+ * const response = await fetch('https://www.strava.com/api/v3/athlete/activities', {
+ *   headers: {
+ *     Authorization: 'Bearer abc123',
+ *   },
+ * });
+ * const data = await parseResponse(response);
+ * ```
+ */
+declare const parseResponse: <T>(response: Response) => Promise<T>;
+export default parseResponse;
+//# sourceMappingURL=parse-response.d.ts.map

package/dist/client/parse-response/parse-response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-response.d.ts","sourceRoot":"","sources":["../../../client/parse-response/parse-response.ts"],"names":[],"mappings":"AAgCA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,QAAA,MAAM,aAAa,GAAU,CAAC,EAAE,UAAU,QAAQ,KAAG,OAAO,CAAC,CAAC,CA4B7D,CAAC;AAEF,eAAe,aAAa,CAAC"}

package/dist/constants.d.ts

@@ -0,0 +1,35 @@
+export declare const STRAVA_API_INITIAL_BACKOFF_MS = 1000;
+export declare const STRAVA_API_MAX_BACKOFF_MS = 16000;
+export declare const STRAVA_API_MAX_RETRIES = 3;
+export declare const STRAVA_AUTH_DEFAULT_SCOPE = "activity:read";
+export declare const STRAVA_OAUTH_BASE_URL = "https://www.strava.com/oauth";
+export declare const STRAVA_API_BASE_URL = "https://www.strava.com/api/v3";
+export declare const STRAVA_API_ENDPOINTS: {
+    TOKEN: string;
+    AUTH: string;
+    ACTIVITIES: string;
+    /**
+     * Requires `/:id` for a specific activity.
+     */
+    ACTIVITY: string;
+};
+export declare const STRAVA_API_ERROR_CODES: {
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    readonly FORBIDDEN: "FORBIDDEN";
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly SERVER_ERROR: "SERVER_ERROR";
+    readonly MALFORMED_RESPONSE: "MALFORMED_RESPONSE";
+    readonly INVALID_ID: "INVALID_ID";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly VALIDATION_FAILED: "VALIDATION_FAILED";
+    readonly INVALID_CONFIG: "INVALID_CONFIG";
+    readonly INVALID_CODE: "INVALID_CODE";
+};
+export declare const STRAVA_API_STATUS_CODES: {
+    readonly UNAUTHORIZED: 401;
+    readonly FORBIDDEN: 403;
+    readonly RATE_LIMITED: 429;
+    readonly SERVER_ERROR: 500;
+};
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,6BAA6B,OAAO,CAAC;AAElD,eAAO,MAAM,yBAAyB,QAAQ,CAAC;AAE/C,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC,eAAO,MAAM,yBAAyB,kBAAkB,CAAC;AAEzD,eAAO,MAAM,qBAAqB,iCAAiC,CAAC;AAEpE,eAAO,MAAM,mBAAmB,kCAAkC,CAAC;AAEnE,eAAO,MAAM,oBAAoB;;;;IAK/B;;OAEG;;CAEJ,CAAC;AAEF,eAAO,MAAM,sBAAsB;;;;;;;;;;;;CAYzB,CAAC;AAEX,eAAO,MAAM,uBAAuB;;;;;CAK1B,CAAC"}

package/dist/exchange-token/exchange-token.d.ts

@@ -0,0 +1,36 @@
+import { StravaAuthConfig, StravaAuthTokenResponse } from '../types';
+/**
+ * Exchanges an authorization code for OAuth2 access and refresh tokens.
+ *
+ * After a user authorizes the application via the authorization URL, Strava
+ * redirects to the redirect URI with an authorization code. This function
+ * exchanges that code for access and refresh tokens that can be used to make
+ * API requests.
+ *
+ * @param {string} authorizationCode - Authorization code received from Strava redirect.
+ * @param {StravaAuthConfig} config - OAuth2 configuration including client ID, secret, and redirect URI.
+ * @returns {Promise<StravaTokenResponse>} Promise resolving to token response containing access token, refresh token, and expiration info.
+ *
+ * @throws {Error} Throws an error with StravaAuthError structure for various failure scenarios:
+ *   - 'INVALID_CONFIG' (not retryable): Missing required configuration.
+ *   - 'INVALID_CODE' (not retryable): Authorization code is missing or invalid.
+ *   - 'NETWORK_ERROR' (retryable): Network connection failure.
+ *   - 'UNAUTHORIZED' (not retryable): Invalid client credentials or authorization code.
+ *   - 'MALFORMED_RESPONSE' (not retryable): Invalid JSON response or missing required fields.
+ *   - And others...
+ *
+ * @see {@link https://developers.strava.com/docs/authentication/#tokenexchange | Strava Token Exchange}
+ *
+ * @example
+ * ```typescript
+ * const tokens = await exchangeToken('authorization-code-123', {
+ *   clientId: '12345',
+ *   clientSecret: 'secret',
+ *   redirectUri: 'http://localhost'
+ * });
+ * // Returns: { access_token: '...', refresh_token: '...', expires_at: 1234567890, ... }
+ * ```
+ */
+declare const exchangeToken: (authorizationCode: string, config: StravaAuthConfig) => Promise<StravaAuthTokenResponse | null>;
+export default exchangeToken;
+//# sourceMappingURL=exchange-token.d.ts.map

package/dist/exchange-token/exchange-token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exchange-token.d.ts","sourceRoot":"","sources":["../../exchange-token/exchange-token.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAwCrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,QAAA,MAAM,aAAa,GACjB,mBAAmB,MAAM,EACzB,QAAQ,gBAAgB,KACvB,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAmCxC,CAAC;AAEF,eAAe,aAAa,CAAC"}

package/dist/exchange-token/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './exchange-token';
+//# sourceMappingURL=index.d.ts.map

package/dist/exchange-token/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../exchange-token/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC"}