@kaiord/garmin-connect 5.0.0 → 7.0.0

package/README.md

@@ -17,22 +17,21 @@ pnpm add @kaiord/garmin-connect
 
 ```typescript
 import { createGarminConnectClient } from "@kaiord/garmin-connect";
-import type { KRD } from "@kaiord/core";
 
-const { auth, service } = createGarminConnectClient();
+const client = createGarminConnectClient();
 
 // Login
-await auth.login("email@example.com", "password");
+await client.auth.login("email@example.com", "password");
 
 // List workouts
-const workouts = await service.list({ limit: 10 });
+const workouts = await client.service.list({ limit: 10 });
 
 // Push a KRD workout to Garmin Connect
-const result = await service.push(krd);
+const result = await client.service.push(krd);
 console.log(`Pushed workout: ${result.name} (id: ${result.id})`);
 ```
 
-### Token Persistence
+### Token Persistence with Auto-Restore
 
 ```typescript
 import {
@@ -40,17 +39,28 @@ import {
   createFileTokenStore,
 } from "@kaiord/garmin-connect";
 
-const tokenStore = createFileTokenStore("./tokens.json");
-const { auth, service } = createGarminConnectClient({ tokenStore });
+const client = createGarminConnectClient({
+  tokenStore: createFileTokenStore("./tokens.json"),
+});
+
+// Auto-restore tokens from store (login not needed if tokens are valid)
+const { restored } = await client.init();
+if (!restored) {
+  await client.auth.login("email@example.com", "password");
+}
+```
+
+### With Retry for Transient Failures
 
-// Login (tokens are saved automatically)
-await auth.login("email@example.com", "password");
+```typescript
+import { createGarminConnectClient } from "@kaiord/garmin-connect";
 
-// On next run, tokens are restored automatically
-// No need to login again if tokens are still valid
+const client = createGarminConnectClient({
+  retry: { maxRetries: 3, baseDelay: 1000, maxDelay: 10000 },
+});
 ```
 
-### Custom Cookie-Aware Fetch
+### Custom Fetch Function
 
 ```typescript
 import {
@@ -58,56 +68,84 @@ import {
   createCookieFetch,
 } from "@kaiord/garmin-connect";
 
-const cookieFetch = createCookieFetch();
-const { auth, service } = createGarminConnectClient({ fetchFn: cookieFetch });
+const client = createGarminConnectClient({
+  fetchFn: createCookieFetch(),
+});
 ```
 
 ## API
 
-### `createGarminConnectClient(options?): { auth, service }`
+### `createGarminConnectClient(options?): GarminConnectClient`
 
 Creates a Garmin Connect client with authentication and workout service.
 
 **Options:**
 
 - `fetchFn` - Custom fetch function (defaults to cookie-aware fetch)
-- `tokenStore` - Token persistence store (defaults to in-memory)
+- `tokenStore` - Token persistence store
+- `logger` - Custom logger
+- `retry` - Retry options: `{ maxRetries?, baseDelay?, maxDelay? }`
 
-### `auth.login(email, password): Promise<void>`
+**Returns:** `{ auth, service, init }`
+
+### `client.init(): Promise<{ restored: boolean }>`
+
+Auto-restores tokens from the token store. Returns `{ restored: true }` if valid tokens were found. Idempotent: no-op if tokens are already in memory.
+
+### `client.auth.login(email, password): Promise<void>`
 
 Authenticates with Garmin Connect via SSO.
 
-### `auth.is_authenticated(): boolean`
+### `client.auth.is_authenticated(): boolean`
 
-Checks if the client has valid authentication tokens.
+Checks if the client has valid (non-expired) authentication tokens.
 
-### `auth.export_tokens(): Promise<TokenData>`
+### `client.auth.export_tokens(): Promise<TokenData>`
 
 Exports current tokens for external storage.
 
-### `auth.restore_tokens(tokens): Promise<void>`
+### `client.auth.restore_tokens(tokens): Promise<void>`
 
 Restores previously exported tokens.
 
-### `service.list(options?): Promise<WorkoutSummary[]>`
+### `client.auth.logout(): Promise<void>`
+
+Clears all tokens from memory and token store.
+
+### `client.service.list(options?): Promise<WorkoutSummary[]>`
 
 Lists workouts from Garmin Connect.
 
-### `service.push(krd): Promise<PushResult>`
+### `client.service.push(krd): Promise<PushResult>`
 
-Pushes a KRD structured workout to Garmin Connect.
+Pushes a KRD-structured workout to Garmin Connect.
+
+### `createFileTokenStore(path?): TokenStore`
+
+Creates a file-based token store. Defaults to `~/.kaiord/garmin-tokens.json`.
+
+### `createMemoryTokenStore(): TokenStore`
+
+Creates an in-memory token store (tokens lost on process exit).
 
 ### `createCookieFetch(): typeof fetch`
 
 Creates a cookie-aware fetch wrapper for SSO authentication flows.
 
-### `createFileTokenStore(path): TokenStore`
+## Migration from v5.x
 
-Creates a file-based token store for persistent authentication.
+```typescript
+// Before (v5.x)
+const { auth, service } = createGarminConnectClient();
+await auth.login(email, password);
 
-### `createMemoryTokenStore(): TokenStore`
+// After (v6.x)
+const client = createGarminConnectClient({ tokenStore });
+const { restored } = await client.init();
+if (!restored) await client.auth.login(email, password);
+```
 
-Creates an in-memory token store (tokens lost on process exit).
+See the [design document](https://github.com/pablo-albaladejo/kaiord/blob/main/openspec/changes/archive/2026-04-03-refactor-garmin-auth/design.md) for the full migration guide.
 
 ## License
 

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import * as _kaiord_core from '@kaiord/core';
-import { WorkoutService, Logger, TokenStore, AuthProvider } from '@kaiord/core';
+import { Logger, WorkoutService, AuthProvider, TokenStore } from '@kaiord/core';
 export { ListOptions, PushResult, TokenData, TokenStore, WorkoutSummary } from '@kaiord/core';
 
+type FetchFn = typeof globalThis.fetch;
 type OAuth1Token = {
     oauth_token: string;
     oauth_token_secret: string;
@@ -14,33 +14,76 @@ type OAuth2Token = {
     refresh_token_expires_in: number;
     expires_at: number;
 };
-type GarminHttpClient = {
-    get: <T>(url: string) => Promise<T>;
-    post: <T>(url: string, body: unknown) => Promise<T>;
-    del: <T>(url: string) => Promise<T>;
-    setTokens: (oauth1: OAuth1Token, oauth2: OAuth2Token) => void;
-    clearTokens: () => void;
-    getOAuth2Token: () => OAuth2Token | undefined;
+
+type RetryOptions = {
+    maxRetries?: number;
+    baseDelay?: number;
+    maxDelay?: number;
+    randomFn?: () => number;
+    logger?: Logger;
 };
 
-type GarminWorkoutClient = Pick<WorkoutService, "push" | "list">;
+type GarminWorkoutClient = WorkoutService;
 
-type GarminAuthProviderOptions = {
+type InitResult = {
+    restored: boolean;
+};
+type GarminConnectClient = {
+    auth: AuthProvider;
+    service: GarminWorkoutClient;
+    init: () => Promise<InitResult>;
+};
+type GarminConnectClientOptions = {
     logger?: Logger;
     tokenStore?: TokenStore;
-    fetchFn?: typeof globalThis.fetch;
+    fetchFn?: FetchFn;
+    retry?: RetryOptions;
 };
-type GarminAuthProviderResult = {
-    auth: AuthProvider;
-    httpClient: GarminHttpClient;
+
+type TokenManager = {
+    getAccessToken: () => string | undefined;
+    getOAuth1Token: () => OAuth1Token | undefined;
+    getOAuth2Token: () => OAuth2Token | undefined;
+    getGeneration: () => number;
+    isAuthenticated: () => boolean;
+    setTokens: (oauth1: OAuth1Token, oauth2: OAuth2Token) => Promise<void>;
+    clearTokens: () => Promise<void>;
+    refresh: () => Promise<void>;
+    init: () => Promise<{
+        restored: boolean;
+    }>;
 };
-declare const createGarminAuthProvider: (options?: GarminAuthProviderOptions) => GarminAuthProviderResult;
+type TokenReader = Pick<TokenManager, "getAccessToken" | "getGeneration" | "refresh" | "isAuthenticated">;
+type RefreshFn = (oauth1: OAuth1Token) => Promise<OAuth2Token>;
 
-type GarminConnectClientOptions = GarminAuthProviderOptions;
-declare const createGarminConnectClient: (options?: GarminConnectClientOptions) => {
-    auth: _kaiord_core.AuthProvider;
-    service: GarminWorkoutClient;
+type GarminAuthProviderOptions = {
+    tokenManager: TokenManager;
+    logger?: Logger;
+    fetchFn?: FetchFn;
 };
+declare const createGarminAuthProvider: (options: GarminAuthProviderOptions) => AuthProvider;
+
+type Options = {
+    refreshFn: RefreshFn;
+    logger: Logger;
+    tokenStore?: TokenStore;
+};
+declare const createTokenManager: (options: Options) => TokenManager;
+
+/**
+ * Create a Garmin Connect client with auth, workout service, and optional token auto-restore.
+ *
+ * @example
+ * ```ts
+ * const client = createGarminConnectClient({
+ *   tokenStore: createFileTokenStore(),
+ *   retry: { maxRetries: 3 },
+ * });
+ * const { restored } = await client.init();
+ * if (!restored) await client.auth.login(email, password);
+ * ```
+ */
+declare const createGarminConnectClient: (options?: GarminConnectClientOptions) => GarminConnectClient;
 
 declare const createCookieFetch: () => typeof globalThis.fetch;
 
@@ -48,4 +91,4 @@ declare const createFileTokenStore: (filePath?: string) => TokenStore;
 
 declare const createMemoryTokenStore: () => TokenStore;
 
-export { type GarminWorkoutClient, createCookieFetch, createFileTokenStore, createGarminAuthProvider, createGarminConnectClient, createMemoryTokenStore };
+export { type GarminConnectClient, type GarminConnectClientOptions, type GarminWorkoutClient, type InitResult, type RetryOptions, type TokenReader, createCookieFetch, createFileTokenStore, createGarminAuthProvider, createGarminConnectClient, createMemoryTokenStore, createTokenManager };