whoopper 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 car1os
+
+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,176 @@
+# whoopper
+
+The definitive WHOOP API client. Zero runtime dependencies. Full TypeScript types. Every endpoint.
+
+## Install
+
+```bash
+npm install whoopper
+```
+
+Requires Node.js 18+.
+
+## Quick Start
+
+### With OAuth (Official API)
+
+```typescript
+import { WhooopperClient } from 'whoopper';
+
+const client = WhooopperClient.withOAuth({
+  clientId: process.env.WHOOP_CLIENT_ID!,
+  clientSecret: process.env.WHOOP_CLIENT_SECRET!,
+});
+
+await client.authenticate(); // opens browser for OAuth
+
+const profile = await client.user.getProfile();
+console.log(`Hello, ${profile.first_name}!`);
+```
+
+### With Pre-existing Tokens
+
+```typescript
+const client = WhooopperClient.withTokens({
+  official: {
+    accessToken: 'your-access-token',
+    refreshToken: 'your-refresh-token',
+  },
+});
+
+const cycles = await client.cycle.getAll({ start: '2024-01-01' });
+```
+
+## Resources
+
+All official WHOOP API v2 endpoints are supported:
+
+```typescript
+// User
+await client.user.getProfile();
+await client.user.getBodyMeasurement();
+
+// Cycles
+await client.cycle.list({ start: '2024-01-01', end: '2024-02-01' });
+await client.cycle.getById(12345);
+await client.cycle.getRecovery(12345);
+await client.cycle.getSleep(12345);
+
+// Recovery
+await client.recovery.list({ start: '2024-01-01' });
+
+// Sleep
+await client.sleep.list({ start: '2024-01-01' });
+await client.sleep.getById(12345);
+
+// Workouts
+await client.workout.list({ start: '2024-01-01' });
+await client.workout.getById(12345);
+```
+
+## Pagination
+
+Every collection resource supports four pagination strategies:
+
+```typescript
+// Get a single page
+const page = await client.cycle.list({ start: '2024-01-01' });
+
+// Get all records (auto-paginates)
+const all = await client.cycle.getAll({ start: '2024-01-01' });
+
+// Async iterator (memory-efficient)
+for await (const cycle of client.cycle.iterate({ start: '2024-01-01' })) {
+  console.log(cycle.id);
+}
+
+// Page-level iterator
+for await (const page of client.cycle.paginator().iteratePages()) {
+  console.log(`Got ${page.records.length} records`);
+}
+```
+
+## Token Storage
+
+By default, tokens are stored in memory. For persistence across sessions:
+
+```typescript
+import { WhooopperClient, FileTokenStore } from 'whoopper';
+
+const client = WhooopperClient.withOAuth(
+  { clientId: '...', clientSecret: '...' },
+  { tokenStore: new FileTokenStore('./tokens.json') },
+);
+```
+
+`FileTokenStore` writes with `0600` permissions and warns if they're looser.
+
+You can also implement the `TokenStore` interface for custom storage (Redis, database, etc.).
+
+## Utilities
+
+Standalone helpers that work on plain API responses:
+
+```typescript
+import { kJToCalories, msToHours, totalSleepTime, sleepEfficiency } from 'whoopper/utils';
+
+kJToCalories(1000);       // 239
+msToHours(27_000_000);    // 7.5
+
+// Pass a SleepScore from the API
+totalSleepTime(sleep.score);    // total ms of actual sleep
+sleepEfficiency(sleep.score);   // percentage
+```
+
+## Subpath Exports
+
+```typescript
+import { ... } from 'whoopper';         // everything
+import { ... } from 'whoopper/models';   // type interfaces only
+import { ... } from 'whoopper/errors';   // error classes only
+import { ... } from 'whoopper/utils';    // utility functions only
+```
+
+## Error Handling
+
+All errors extend `WhoopError`:
+
+| HTTP Status | Error Class | Notes |
+|-------------|-------------|-------|
+| 400 | `ValidationError` | Bad request parameters |
+| 401 | `TokenExpiredError` | Token needs refresh |
+| 403 | `AuthenticationError` | Insufficient permissions |
+| 404 | `NotFoundError` | Resource doesn't exist |
+| 429 | `RateLimitError` | Has `.retryAfter` (seconds) |
+| 5xx | `ServerError` | Has `.statusCode` |
+
+Retries are automatic for 429 and 5xx (exponential backoff, respects `Retry-After` header, max 5 attempts).
+
+### Optional Result Type
+
+For those who prefer explicit error handling over try/catch:
+
+```typescript
+import { tryCatch } from 'whoopper';
+
+const result = await tryCatch(() => client.user.getProfile());
+if (result.ok) {
+  console.log(result.value.first_name);
+} else {
+  console.error(result.error);
+}
+```
+
+## Configuration
+
+```typescript
+WhooopperClient.withOAuth(config, {
+  tokenStore: new FileTokenStore('./tokens.json'),
+  retry: { maxAttempts: 3, baseDelayMs: 2000 },
+  throttle: { maxConcurrent: 5, minDelayMs: 100 },
+});
+```
+
+## License
+
+MIT

package/dist/auth/auth-server.d.ts

@@ -0,0 +1,15 @@
+interface AuthServerResult {
+    port: number;
+    waitForCode: () => Promise<{
+        code: string;
+        state: string;
+    }>;
+    waitForTokens: () => Promise<{
+        accessToken: string;
+        expiresIn: number;
+    }>;
+    close: () => void;
+}
+export declare function startAuthServer(): Promise<AuthServerResult>;
+export {};
+//# sourceMappingURL=auth-server.d.ts.map

package/dist/auth/auth-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-server.d.ts","sourceRoot":"","sources":["../../src/auth/auth-server.ts"],"names":[],"mappings":"AAEA,UAAU,gBAAgB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5D,aAAa,EAAE,MAAM,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACzE,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AA2DD,wBAAgB,eAAe,IAAI,OAAO,CAAC,gBAAgB,CAAC,CA4E3D"}

package/dist/auth/auth-server.js

@@ -0,0 +1,127 @@
+import { createServer } from 'node:http';
+const SUCCESS_HTML = `<!DOCTYPE html>
+<html><head><title>Authentication Successful</title></head>
+<body style="font-family:system-ui;display:flex;justify-content:center;align-items:center;height:100vh;margin:0;background:#0a0a0a;color:#fff">
+<div style="text-align:center">
+<h1 style="color:#00d1b2">Authentication Successful</h1>
+<p>You can close this tab and return to the terminal.</p>
+</div></body></html>`;
+const LOGIN_HTML = `<!DOCTYPE html>
+<html><head><title>WHOOP Login</title></head>
+<body style="font-family:system-ui;display:flex;justify-content:center;align-items:center;height:100vh;margin:0;background:#0a0a0a;color:#fff">
+<div style="max-width:400px;width:100%;padding:2rem">
+<h1 style="color:#00d1b2;text-align:center">WHOOP Login</h1>
+<p style="color:#999;text-align:center;font-size:0.9rem">Your password stays in this browser — it is never sent to the library.</p>
+<form id="loginForm" style="display:flex;flex-direction:column;gap:1rem">
+<input name="email" type="email" placeholder="Email" required style="padding:0.75rem;border:1px solid #333;border-radius:8px;background:#1a1a1a;color:#fff;font-size:1rem">
+<input name="password" type="password" placeholder="Password" required style="padding:0.75rem;border:1px solid #333;border-radius:8px;background:#1a1a1a;color:#fff;font-size:1rem">
+<button type="submit" style="padding:0.75rem;border:none;border-radius:8px;background:#00d1b2;color:#000;font-size:1rem;font-weight:bold;cursor:pointer">Log In</button>
+<div id="error" style="color:#ff6b6b;text-align:center;display:none"></div>
+</form>
+</div>
+<script>
+const COGNITO_URL = 'https://api.prod.whoop.com/auth-service/v3/whoop';
+document.getElementById('loginForm').addEventListener('submit', async (e) => {
+  e.preventDefault();
+  const form = e.target;
+  const errorEl = document.getElementById('error');
+  errorEl.style.display = 'none';
+  try {
+    const resp = await fetch(COGNITO_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        username: form.email.value,
+        password: form.password.value,
+        grant_type: 'password',
+        issueRefresh: false,
+      }),
+    });
+    if (!resp.ok) throw new Error('Login failed: ' + resp.status);
+    const data = await resp.json();
+    await fetch('/token-callback', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        access_token: data.access_token,
+        expires_in: data.expires_in || 3600,
+      }),
+    });
+    document.body.innerHTML = \`${SUCCESS_HTML.replace(/`/g, '\\`').replace(/<\/?html>|<\/?head>|<\/?body>|<title>.*?<\/title>/g, '').trim()}\`;
+  } catch (err) {
+    errorEl.textContent = err.message;
+    errorEl.style.display = 'block';
+  }
+});
+</script></body></html>`;
+export function startAuthServer() {
+    return new Promise((resolve, reject) => {
+        let codeResolve = null;
+        let tokenResolve = null;
+        const server = createServer((req, res) => {
+            const url = new URL(req.url ?? '/', `http://localhost`);
+            if (req.method === 'GET' && url.pathname === '/callback') {
+                const code = url.searchParams.get('code');
+                const state = url.searchParams.get('state');
+                if (code && state && codeResolve) {
+                    res.writeHead(200, { 'Content-Type': 'text/html' });
+                    res.end(SUCCESS_HTML);
+                    codeResolve({ code, state });
+                }
+                else {
+                    res.writeHead(400, { 'Content-Type': 'text/plain' });
+                    res.end('Missing code or state parameter');
+                }
+                return;
+            }
+            if (req.method === 'GET' && url.pathname === '/login') {
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                res.end(LOGIN_HTML);
+                return;
+            }
+            if (req.method === 'POST' && url.pathname === '/token-callback') {
+                let body = '';
+                req.on('data', (chunk) => { body += chunk.toString(); });
+                req.on('end', () => {
+                    try {
+                        const data = JSON.parse(body);
+                        res.writeHead(200, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ ok: true }));
+                        if (tokenResolve) {
+                            tokenResolve({
+                                accessToken: data.access_token,
+                                expiresIn: data.expires_in,
+                            });
+                        }
+                    }
+                    catch {
+                        res.writeHead(400, { 'Content-Type': 'text/plain' });
+                        res.end('Invalid JSON');
+                    }
+                });
+                return;
+            }
+            res.writeHead(404, { 'Content-Type': 'text/plain' });
+            res.end('Not found');
+        });
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            if (!address || typeof address === 'string') {
+                reject(new Error('Failed to start auth server'));
+                return;
+            }
+            resolve({
+                port: address.port,
+                waitForCode: () => new Promise(res => {
+                    codeResolve = res;
+                }),
+                waitForTokens: () => new Promise(res => {
+                    tokenResolve = res;
+                }),
+                close: () => server.close(),
+            });
+        });
+        server.on('error', reject);
+    });
+}
+//# sourceMappingURL=auth-server.js.map

package/dist/auth/auth-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-server.js","sourceRoot":"","sources":["../../src/auth/auth-server.ts"],"names":[],"mappings":"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"}

package/dist/auth/oauth-provider.d.ts

@@ -0,0 +1,17 @@
+import type { OAuthConfig } from './types.js';
+import { TokenInfo } from './token-info.js';
+import type { TokenStore } from './token-store.js';
+export declare class OAuthProvider {
+    private readonly config;
+    private readonly store;
+    private tokenInfo;
+    constructor(config: OAuthConfig, store: TokenStore);
+    authenticate(): Promise<TokenInfo>;
+    getAccessToken(): Promise<string>;
+    setTokenInfo(tokenInfo: TokenInfo): void;
+    private browserAuth;
+    private exchangeCode;
+    private refresh;
+    revoke(): Promise<void>;
+}
+//# sourceMappingURL=oauth-provider.d.ts.map

package/dist/auth/oauth-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-provider.d.ts","sourceRoot":"","sources":["../../src/auth/oauth-provider.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAiB,MAAM,YAAY,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAiBnD,qBAAa,aAAa;IAItB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAJxB,OAAO,CAAC,SAAS,CAA0B;gBAGxB,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,UAAU;IAG9B,YAAY,IAAI,OAAO,CAAC,SAAS,CAAC;IAqBlC,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAgBvC,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;YAI1B,WAAW;YAwCX,YAAY;YA2BZ,OAAO;IAyBf,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAI9B"}

package/dist/auth/oauth-provider.js

@@ -0,0 +1,139 @@
+import { randomBytes } from 'node:crypto';
+import { TokenInfo } from './token-info.js';
+import { AuthenticationError, RefreshTokenError } from '../errors/auth.js';
+import { startAuthServer } from './auth-server.js';
+const AUTH_URL = 'https://api.prod.whoop.com/oauth/oauth2/auth';
+const TOKEN_URL = 'https://api.prod.whoop.com/oauth/oauth2/token';
+const STORE_KEY = 'official';
+const DEFAULT_SCOPES = [
+    'read:recovery',
+    'read:cycles',
+    'read:sleep',
+    'read:workout',
+    'read:profile',
+    'read:body_measurement',
+];
+export class OAuthProvider {
+    config;
+    store;
+    tokenInfo = null;
+    constructor(config, store) {
+        this.config = config;
+        this.store = store;
+    }
+    async authenticate() {
+        // Try loading from store first
+        const stored = await this.store.load(STORE_KEY);
+        if (stored && !stored.isExpired) {
+            this.tokenInfo = stored;
+            return stored;
+        }
+        // Try refresh if we have a refresh token
+        if (stored?.refreshToken) {
+            try {
+                return await this.refresh(stored.refreshToken);
+            }
+            catch {
+                // Refresh failed, fall through to full auth
+            }
+        }
+        // Full browser-based OAuth flow
+        return this.browserAuth();
+    }
+    async getAccessToken() {
+        if (!this.tokenInfo) {
+            throw new AuthenticationError('Not authenticated. Call authenticate() first.');
+        }
+        if (this.tokenInfo.isExpired) {
+            if (this.tokenInfo.refreshToken) {
+                this.tokenInfo = await this.refresh(this.tokenInfo.refreshToken);
+            }
+            else {
+                throw new AuthenticationError('Token expired and no refresh token available.');
+            }
+        }
+        return this.tokenInfo.accessToken;
+    }
+    setTokenInfo(tokenInfo) {
+        this.tokenInfo = tokenInfo;
+    }
+    async browserAuth() {
+        const state = randomBytes(16).toString('hex');
+        const scopes = this.config.scopes ?? DEFAULT_SCOPES;
+        const { port, waitForCode, close } = await startAuthServer();
+        const redirectUri = this.config.redirectUri ?? `http://localhost:${port}/callback`;
+        const authUrl = new URL(AUTH_URL);
+        authUrl.searchParams.set('client_id', this.config.clientId);
+        authUrl.searchParams.set('redirect_uri', redirectUri);
+        authUrl.searchParams.set('response_type', 'code');
+        authUrl.searchParams.set('scope', scopes.join(' '));
+        authUrl.searchParams.set('state', state);
+        // Open browser
+        const { exec } = await import('node:child_process');
+        const openCmd = process.platform === 'darwin'
+            ? 'open'
+            : process.platform === 'win32'
+                ? 'start'
+                : 'xdg-open';
+        exec(`${openCmd} "${authUrl.toString()}"`);
+        try {
+            const { code, state: returnedState } = await waitForCode();
+            if (returnedState !== state) {
+                throw new AuthenticationError('OAuth state mismatch');
+            }
+            const tokenInfo = await this.exchangeCode(code, redirectUri);
+            this.tokenInfo = tokenInfo;
+            await this.store.save(STORE_KEY, tokenInfo);
+            return tokenInfo;
+        }
+        finally {
+            close();
+        }
+    }
+    async exchangeCode(code, redirectUri) {
+        const body = new URLSearchParams({
+            grant_type: 'authorization_code',
+            code,
+            redirect_uri: redirectUri,
+            client_id: this.config.clientId,
+            client_secret: this.config.clientSecret,
+        });
+        const response = await fetch(TOKEN_URL, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: body.toString(),
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new AuthenticationError(`Token exchange failed: ${error}`);
+        }
+        const tokenResponse = (await response.json());
+        return TokenInfo.fromTokenResponse(tokenResponse);
+    }
+    async refresh(refreshToken) {
+        const body = new URLSearchParams({
+            grant_type: 'refresh_token',
+            refresh_token: refreshToken,
+            client_id: this.config.clientId,
+            client_secret: this.config.clientSecret,
+        });
+        const response = await fetch(TOKEN_URL, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: body.toString(),
+        });
+        if (!response.ok) {
+            throw new RefreshTokenError(`Token refresh failed: ${response.status}`);
+        }
+        const tokenResponse = (await response.json());
+        const tokenInfo = TokenInfo.fromTokenResponse(tokenResponse);
+        this.tokenInfo = tokenInfo;
+        await this.store.save(STORE_KEY, tokenInfo);
+        return tokenInfo;
+    }
+    async revoke() {
+        await this.store.clear(STORE_KEY);
+        this.tokenInfo = null;
+    }
+}
+//# sourceMappingURL=oauth-provider.js.map

package/dist/auth/oauth-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-provider.js","sourceRoot":"","sources":["../../src/auth/oauth-provider.ts"],"names":[],"mappings":"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"}

package/dist/auth/token-info.d.ts

@@ -0,0 +1,21 @@
+export interface TokenInfoData {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt: number;
+}
+export declare class TokenInfo {
+    readonly accessToken: string;
+    readonly refreshToken: string | undefined;
+    readonly expiresAt: number;
+    constructor(data: TokenInfoData);
+    static fromTokenResponse(response: {
+        access_token: string;
+        refresh_token?: string;
+        expires_in: number;
+    }): TokenInfo;
+    get isExpired(): boolean;
+    get timeUntilExpiry(): number;
+    toJSON(): TokenInfoData;
+    static fromJSON(data: TokenInfoData): TokenInfo;
+}
+//# sourceMappingURL=token-info.d.ts.map

package/dist/auth/token-info.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-info.d.ts","sourceRoot":"","sources":["../../src/auth/token-info.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,SAAS;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,IAAI,EAAE,aAAa;IAM/B,MAAM,CAAC,iBAAiB,CAAC,QAAQ,EAAE;QACjC,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,UAAU,EAAE,MAAM,CAAC;KACpB,GAAG,SAAS;IAQb,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED,MAAM,IAAI,aAAa;IAQvB,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS;CAGhD"}

package/dist/auth/token-info.js

@@ -0,0 +1,35 @@
+const EXPIRY_BUFFER_MS = 60_000;
+export class TokenInfo {
+    accessToken;
+    refreshToken;
+    expiresAt;
+    constructor(data) {
+        this.accessToken = data.accessToken;
+        this.refreshToken = data.refreshToken;
+        this.expiresAt = data.expiresAt;
+    }
+    static fromTokenResponse(response) {
+        return new TokenInfo({
+            accessToken: response.access_token,
+            refreshToken: response.refresh_token,
+            expiresAt: Date.now() + response.expires_in * 1000,
+        });
+    }
+    get isExpired() {
+        return Date.now() >= this.expiresAt - EXPIRY_BUFFER_MS;
+    }
+    get timeUntilExpiry() {
+        return Math.max(0, this.expiresAt - Date.now());
+    }
+    toJSON() {
+        return {
+            accessToken: this.accessToken,
+            refreshToken: this.refreshToken,
+            expiresAt: this.expiresAt,
+        };
+    }
+    static fromJSON(data) {
+        return new TokenInfo(data);
+    }
+}
+//# sourceMappingURL=token-info.js.map

package/dist/auth/token-info.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-info.js","sourceRoot":"","sources":["../../src/auth/token-info.ts"],"names":[],"mappings":"AAAA,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAQhC,MAAM,OAAO,SAAS;IACX,WAAW,CAAS;IACpB,YAAY,CAAqB;IACjC,SAAS,CAAS;IAE3B,YAAY,IAAmB;QAC7B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACpC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;QACtC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;IAClC,CAAC;IAED,MAAM,CAAC,iBAAiB,CAAC,QAIxB;QACC,OAAO,IAAI,SAAS,CAAC;YACnB,WAAW,EAAE,QAAQ,CAAC,YAAY;YAClC,YAAY,EAAE,QAAQ,CAAC,aAAa;YACpC,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC,UAAU,GAAG,IAAI;SACnD,CAAC,CAAC;IACL,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,SAAS,GAAG,gBAAgB,CAAC;IACzD,CAAC;IAED,IAAI,eAAe;QACjB,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAClD,CAAC;IAED,MAAM;QACJ,OAAO;YACL,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,SAAS,EAAE,IAAI,CAAC,SAAS;SAC1B,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,QAAQ,CAAC,IAAmB;QACjC,OAAO,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;CACF"}

package/dist/auth/token-store.d.ts

@@ -0,0 +1,21 @@
+import { TokenInfo } from './token-info.js';
+export interface TokenStore {
+    load(key: string): Promise<TokenInfo | null>;
+    save(key: string, token: TokenInfo): Promise<void>;
+    clear(key: string): Promise<void>;
+}
+export declare class MemoryTokenStore implements TokenStore {
+    private tokens;
+    load(key: string): Promise<TokenInfo | null>;
+    save(key: string, token: TokenInfo): Promise<void>;
+    clear(key: string): Promise<void>;
+}
+export declare class FileTokenStore implements TokenStore {
+    private readonly filePath;
+    constructor(filePath: string);
+    load(key: string): Promise<TokenInfo | null>;
+    save(key: string, token: TokenInfo): Promise<void>;
+    clear(key: string): Promise<void>;
+    private checkPermissions;
+}
+//# sourceMappingURL=token-store.d.ts.map

package/dist/auth/token-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-store.d.ts","sourceRoot":"","sources":["../../src/auth/token-store.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAsB,MAAM,iBAAiB,CAAC;AAEhE,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAC7C,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnC;AAED,qBAAa,gBAAiB,YAAW,UAAU;IACjD,OAAO,CAAC,MAAM,CAAgC;IAExC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAI5C,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGxC;AAED,qBAAa,cAAe,YAAW,UAAU;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,MAAM;IAEvC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAgB5C,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAalD,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAWzB,gBAAgB;CAc/B"}