@timesheet/sdk 1.0.2 → 1.0.4

package/CHANGELOG.md

@@ -6,6 +6,36 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [1.0.4] - 2026-01-04
+
+### Added
+- OAuth 2.1 Discovery support (RFC 8414):
+  - `OAuthDiscovery` class for endpoint discovery from `/.well-known/oauth-authorization-server`
+  - Support for Protected Resource Metadata (RFC 9728)
+  - Support for OpenID Connect Discovery (`/.well-known/openid-configuration`)
+  - Discovery result caching with configurable TTL
+  - `discoverOAuth()` convenience function for quick discovery
+  - Custom `authorizationEndpoint` and `tokenEndpoint` options in OAuth21Auth methods
+
+## [1.0.3] - 2026-01-04
+
+### Added
+- OAuth 2.1 authentication support with PKCE (Proof Key for Code Exchange)
+- New `OAuth21Auth` class for OAuth 2.1 authorization code flow
+- PKCE utilities: `generatePkceCodePair()`, `generateCodeVerifier()`, `generateCodeChallenge()`
+- Support for public clients (optional client secret with PKCE)
+- Resource indicators support (RFC 8707)
+- Reports API integration (`reports.timesheet.io`) with full model support:
+  - `DocumentReportResource` - Document PDF/XML generation
+  - `TaskReportResource` - Task report generation
+  - `ExpenseReportResource` - Expense report generation
+  - `NoteReportResource` - Note report generation
+  - `ExportResource` - Excel/CSV/PDF exports with templates and custom fields
+- Complete TypeScript models for reports: `DocumentReport`, `TaskReportItem`, `ExpenseReportItem`, `NoteReportItem`
+- Export template management (CRUD operations)
+- Custom export field management
+- Comprehensive unit tests for Reports API
+
 ## [1.0.2] - 2025-10-25
 
 ### Added
@@ -70,7 +100,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Removed complex mocking in favor of simple validation tests
 - Updated GitHub Actions to use non-deprecated action versions
 
-[Unreleased]: https://github.com/timesheetIO/timesheet-typescript/compare/v1.0.2...HEAD
+[Unreleased]: https://github.com/timesheetIO/timesheet-typescript/compare/v1.0.4...HEAD
+[1.0.4]: https://github.com/timesheetIO/timesheet-typescript/compare/v1.0.3...v1.0.4
+[1.0.3]: https://github.com/timesheetIO/timesheet-typescript/compare/v1.0.2...v1.0.3
 [1.0.2]: https://github.com/timesheetIO/timesheet-typescript/compare/v1.0.1...v1.0.2
 [1.0.1]: https://github.com/timesheetIO/timesheet-typescript/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/timesheetIO/timesheet-typescript/releases/tag/v1.0.0 

package/README.md

@@ -12,7 +12,7 @@ The official TypeScript SDK for the [Timesheet API](https://timesheet.io), provi
 
 - ✅ **Type-Safe** - Full TypeScript support with comprehensive types
 - ✅ **Modern Architecture** - Promise-based with async/await support
-- ✅ **Authentication** - Built-in API Key and OAuth2 support
+- ✅ **Authentication** - Built-in API Key, OAuth2, and OAuth 2.1 (PKCE) with automatic discovery (RFC 8414)
 - ✅ **Error Handling** - Typed exceptions for better error management
 - ✅ **Pagination** - Automatic pagination with async iterators
 - ✅ **Retry Logic** - Configurable retry with exponential backoff
@@ -89,6 +89,137 @@ const client = new TimesheetClient({
 });
 ```
 
+### OAuth 2.1 Authentication (with PKCE)
+
+OAuth 2.1 is the recommended authentication method for new applications. It requires PKCE (Proof Key for Code Exchange) for enhanced security.
+
+```typescript
+import { OAuth21Auth, generatePkceCodePair } from '@timesheet/sdk';
+
+// Step 1: Generate PKCE code pair
+const pkce = generatePkceCodePair();
+// Store pkce.codeVerifier securely (e.g., in session storage)
+
+// Step 2: Build authorization URL and redirect user
+const authUrl = OAuth21Auth.buildAuthorizationUrl({
+  clientId: 'your-client-id',
+  redirectUri: 'https://your-app.com/callback',
+  codeChallenge: pkce.codeChallenge,
+  codeChallengeMethod: pkce.codeChallengeMethod,
+  state: 'random-csrf-state', // Optional but recommended
+  scope: 'read write',        // Optional
+});
+
+// Redirect user to authUrl...
+
+// Step 3: After user authorizes, exchange code for tokens
+const auth = await OAuth21Auth.fromAuthorizationCode({
+  clientId: 'your-client-id',
+  clientSecret: 'your-client-secret', // Optional for public clients
+  authorizationCode: codeFromCallback,
+  redirectUri: 'https://your-app.com/callback',
+  codeVerifier: pkce.codeVerifier,
+});
+
+// Step 4: Use with TimesheetClient
+const client = new TimesheetClient({
+  authentication: auth
+});
+```
+
+#### OAuth 2.1 with Endpoint Discovery (RFC 8414)
+
+The SDK supports automatic endpoint discovery from `/.well-known/oauth-authorization-server`, allowing you to dynamically configure OAuth endpoints:
+
+```typescript
+import { OAuth21Auth, OAuthDiscovery, generatePkceCodePair } from '@timesheet/sdk';
+
+// Step 1: Discover OAuth endpoints
+const discovery = new OAuthDiscovery();
+const metadata = await discovery.discover('https://api.timesheet.io');
+
+console.log('Authorization endpoint:', metadata.authorizationServer.authorization_endpoint);
+console.log('Token endpoint:', metadata.authorizationServer.token_endpoint);
+console.log('Supported scopes:', metadata.authorizationServer.scopes_supported);
+
+// Step 2: Generate PKCE and build authorization URL using discovered endpoints
+const pkce = generatePkceCodePair();
+
+const authUrl = OAuth21Auth.buildAuthorizationUrl({
+  clientId: 'your-client-id',
+  redirectUri: 'https://your-app.com/callback',
+  codeChallenge: pkce.codeChallenge,
+  codeChallengeMethod: pkce.codeChallengeMethod,
+  scope: 'read write',
+  state: 'random-csrf-state',
+  authorizationEndpoint: metadata.authorizationServer.authorization_endpoint,
+});
+
+// Store pkce.codeVerifier and token endpoint securely, then redirect user
+sessionStorage.setItem('pkce_verifier', pkce.codeVerifier);
+sessionStorage.setItem('token_endpoint', metadata.authorizationServer.token_endpoint);
+
+// Step 3: After callback, exchange code using discovered token endpoint
+const auth = await OAuth21Auth.fromAuthorizationCode({
+  clientId: 'your-client-id',
+  authorizationCode: codeFromCallback,
+  redirectUri: 'https://your-app.com/callback',
+  codeVerifier: sessionStorage.getItem('pkce_verifier'),
+  tokenEndpoint: sessionStorage.getItem('token_endpoint'),
+});
+
+const client = new TimesheetClient({
+  authentication: auth
+});
+```
+
+The `OAuthDiscovery` class provides caching and additional discovery options:
+
+```typescript
+import { OAuthDiscovery, discoverOAuth } from '@timesheet/sdk';
+
+// Using convenience function (uses shared cached instance)
+const result = await discoverOAuth('https://api.timesheet.io');
+
+// Using class with custom options
+const discovery = new OAuthDiscovery({
+  cacheTtl: 3600000,           // Cache for 1 hour (default)
+  timeout: 10000,              // Request timeout in ms
+  fetchOpenIdConfig: true,      // Also fetch OpenID Connect config
+  fetchProtectedResource: true, // Also fetch protected resource metadata (RFC 9728)
+});
+
+const metadata = await discovery.discover('https://api.timesheet.io');
+
+// Check cache status
+if (discovery.isCached('https://api.timesheet.io')) {
+  console.log('Using cached metadata');
+}
+
+// Clear cache when needed
+discovery.clearCache();
+```
+
+#### Using OAuth 2.1 with existing tokens
+
+```typescript
+import { OAuth21Auth } from '@timesheet/sdk';
+
+// With just an access token
+const auth = new OAuth21Auth('your-access-token');
+
+// With refresh token for automatic token refresh
+const auth = new OAuth21Auth({
+  clientId: 'your-client-id',
+  clientSecret: 'your-client-secret', // Optional for public clients
+  refreshToken: 'your-refresh-token',
+});
+
+const client = new TimesheetClient({
+  authentication: auth
+});
+```
+
 ## Resources
 
 All API resources are available through the client: