@jukasdrj/bookstrack-api-client 1.0.1 → 2.1.0

package/CHANGELOG.md

@@ -0,0 +1,163 @@
+# Changelog
+
+All notable changes to the BooksTrack API Client will be documented in this file.
+
+## [2.0.0] - 2025-12-10
+
+### BREAKING CHANGES
+
+- **V3 API Only** - SDK now targets V3 API exclusively
+  - All V1 and V2 endpoints have been removed
+  - Schema regenerated from `/v3/openapi.json`
+  - Update all endpoint paths from `/api/v2/*` to `/v3/*`
+
+### Added
+
+- **Discovery Endpoints** - New V3 discovery routes
+  - `GET /v3/capabilities` - API feature discovery, limits, deprecations
+  - `GET /v3/recommendations/weekly` - Weekly curated book recommendations
+
+### Changed
+
+- **Schema Source** - Now generated from `src/api-v3/openapi-static.json`
+- **Version Bump** - Major version to indicate breaking API changes
+
+### Removed
+
+- All V2 endpoints (sunset March 2026):
+  - `/api/v2/capabilities` → Use `/v3/capabilities`
+  - `/api/v2/recommendations/weekly` → Use `/v3/recommendations/weekly`
+  - `/api/v2/search` → Use `/v3/books/search`
+  - `/api/v2/imports/*` → Use `/v3/jobs/imports/*`
+  - `/api/v2/books/enrich` → Use `/v3/books/enrich`
+
+### Migration Guide (1.x → 2.0)
+
+```typescript
+// Before (V2)
+const response = await client.GET('/api/v2/capabilities')
+const search = await client.GET('/api/v2/search', { params: { query: { q: 'harry potter' } } })
+
+// After (V3)
+const response = await client.GET('/v3/capabilities')
+const search = await client.GET('/v3/books/search', { params: { query: { q: 'harry potter' } } })
+```
+
+## [1.2.0] - 2025-12-03
+
+### Added
+
+- **Shared Response Schemas** - Created `SuccessResponse` and updated `ErrorResponse`
+  - All responses now properly document the `success: boolean` discriminator
+  - Provides foundation for consistent response handling across all endpoints
+
+### Fixed
+
+- **Capabilities Endpoint Decoding** - Added missing `success` field to OpenAPI spec
+  - Fixes iOS error: "The data couldn't be read because it is missing"
+  - OpenAPI spec now matches actual backend response format
+  - SDK auto-generated with correct schema including `success: boolean`
+
+### Known Issues
+
+- **Incomplete Response Schema Migration** - Not all endpoints reference `SuccessResponse` yet
+  - Shared schemas created but full endpoint migration is in progress
+  - Priority endpoints (capabilities, imports, search) are fixed
+  - Complete migration tracked in backend issue tracker
+
+## [1.1.2] - 2025-12-03 (Deprecated - use 1.2.0)
+
+### Fixed
+
+- **Capabilities Endpoint Decoding** - Added missing `success` field to OpenAPI spec
+  - Fixes iOS error: "The data couldn't be read because it is missing"
+  - OpenAPI spec now matches actual backend response format
+  - SDK auto-generated with correct schema including `success: boolean`
+
+## [1.1.1] - 2025-12-03
+
+### Added
+
+- **Job Cancellation Endpoint** - `DELETE /api/v2/jobs/{jobId}/cancel`
+  - Properly documented with Bearer token authentication requirement
+  - SDK now includes typed cancel endpoint with auth headers
+  - Fixes 401 errors when iOS app attempts to cancel completed jobs
+
+### Fixed
+
+- OpenAPI spec now documents cancel endpoint authentication requirements
+- Added `securitySchemes.BearerAuth` for job operation authentication
+
+## [1.1.0] - 2025-12-03
+
+### Added
+
+- **Streaming Utilities** - Helper functions for SSE and WebSocket progress tracking
+  - `createSSEStream()` - Easy SSE connection with typed callbacks
+  - `createWebSocketStream()` - WebSocket wrapper with auth and cancel support
+  - `useSSEStream_Example()` - React hook example for SSE
+  - `useWebSocketStream_Example()` - React hook example for WebSocket
+
+- **Comprehensive Streaming Documentation**
+  - `STREAMING_GUIDE.md` - Complete guide to SSE vs WebSocket architecture
+  - Explains when to use each protocol (SSE for imports, WebSocket for batch ops)
+  - Framework examples for React, Vue, and Svelte
+  - Troubleshooting guide for common issues
+
+### Changed
+
+- Updated README with streaming architecture overview
+- Clarified hybrid SSE/WebSocket approach in documentation
+- Version bump from 1.0.1 → 1.1.0
+
+### Documentation
+
+- Added detailed SSE event types and payload structures
+- Added WebSocket message types and authentication methods
+- Included React hooks examples for both streaming protocols
+- Documented automatic reconnection behavior for SSE
+- Explained bidirectional communication patterns for WebSocket
+
+## [1.0.1] - 2025-11-28
+
+### Initial Release
+
+- Auto-generated TypeScript SDK from OpenAPI specification
+- Full type safety with `openapi-fetch`
+- Support for all V1, V2, and V3 endpoints
+- Basic error handling and circuit breaker error codes
+- ResponseEnvelope format support
+
+## Migration Guide
+
+### From 1.0.1 to 1.1.0
+
+No breaking changes! The 1.1.0 release is backward compatible.
+
+**New Features You Can Use:**
+
+```typescript
+// Before (manual SSE setup)
+const eventSource = new EventSource(sseUrl)
+eventSource.onmessage = (e) => {
+  const data = JSON.parse(e.data)
+  console.log(data.progress)
+}
+
+// After (helper function)
+import { createSSEStream } from '@bookstrack/api-client'
+
+const stream = createSSEStream({
+  sseUrl,
+  onProgress: (event) => console.log(event.progress),
+  onComplete: (event) => console.log('Done!', event.books)
+})
+```
+
+**React Developers:**
+
+Copy the `useSSEStream_Example` or `useWebSocketStream_Example` from `src/streaming.ts` into your React project for typed hooks.
+
+---
+
+**Full Changelog:** https://github.com/yourusername/bendv3/compare/v1.0.1...v1.1.0

package/README.md

@@ -1,9 +1,15 @@
 # @bookstrack/api-client
 
-**Official TypeScript SDK for BooksTrack API**
+[![npm version](https://img.shields.io/npm/v/@jukasdrj/bookstrack-api-client.svg)](https://www.npmjs.com/package/@jukasdrj/bookstrack-api-client)
+[![npm downloads](https://img.shields.io/npm/dm/@jukasdrj/bookstrack-api-client.svg)](https://www.npmjs.com/package/@jukasdrj/bookstrack-api-client)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Official TypeScript SDK for BooksTrack V3 API**
 
 Auto-generated from OpenAPI specification using `openapi-typescript` + `openapi-fetch`.
 
+> **Version 2.0** - V3 API only. V1/V2 endpoints have been sunset.
+
 ## Features
 
 - **Type-Safe** - Full TypeScript support with auto-generated types
@@ -16,13 +22,19 @@ Auto-generated from OpenAPI specification using `openapi-typescript` + `openapi-
 ## Installation
 
 ```bash
-npm install @bookstrack/api-client
+npm install @jukasdrj/bookstrack-api-client
 ```
 
-**Note:** This package is published to GitHub Packages. Ensure your `.npmrc` is configured:
+Or with yarn:
 
+```bash
+yarn add @jukasdrj/bookstrack-api-client
 ```
-@bookstrack:registry=https://npm.pkg.github.com
+
+Or with pnpm:
+
+```bash
+pnpm add @jukasdrj/bookstrack-api-client
 ```
 
 ---
@@ -32,22 +44,31 @@ npm install @bookstrack/api-client
 ### Basic Usage
 
 ```typescript
-import { createBooksTrackClient } from '@bookstrack/api-client'
+import { createBooksTrackClient } from '@jukasdrj/bookstrack-api-client'
 
 const client = createBooksTrackClient({
   baseUrl: 'https://api.oooefam.net'
 })
 
-// Search by ISBN
-const { data, error } = await client.GET('/v1/search/isbn', {
-  params: { query: { isbn: '9780439708180' } }
+// Get API capabilities (call on app startup)
+const { data: caps } = await client.GET('/v3/capabilities')
+console.log('API Version:', caps.data.apiVersion)
+
+// Search books by title
+const { data, error } = await client.GET('/v3/books/search', {
+  params: { query: { q: 'harry potter' } }
 })
 
 if (error) {
   console.error('API Error:', error)
 } else {
-  console.log('Book:', data.data)
+  console.log('Books:', data.data.books)
 }
+
+// Get book by ISBN
+const { data: book } = await client.GET('/v3/books/{isbn}', {
+  params: { path: { isbn: '9780439708180' } }
+})
 ```
 
 ### Advanced Usage
@@ -63,42 +84,57 @@ const client = createBooksTrackClient({
 })
 ```
 
-#### POST Requests (Batch Enrichment)
+#### POST Requests (Book Enrichment)
 
 ```typescript
-const { data, error } = await client.POST('/v1/enrich/batch', {
+const { data, error } = await client.POST('/v3/books/enrich', {
   body: {
-    workIds: ['OL123W', 'OL456W'],
-    force: false
+    isbns: ['9780439708180', '9780316769488'],
+    includeEmbedding: false
   }
 })
 
 if (error) {
   console.error('Failed to enrich:', error)
 } else {
-  console.log('Job ID:', data.data.jobId)
+  console.log('Enriched:', data.data.books)
 }
 ```
 
-#### WebSocket Progress Tracking
+#### Progress Streaming (SSE vs WebSocket)
+
+BooksTrack uses **two streaming protocols** depending on the use case:
+
+- **SSE** for CSV imports (one-way, auto-reconnect)
+- **WebSocket** for batch enrichment (bidirectional, cancel support)
 
+**SSE Example (CSV Import):**
 ```typescript
-// Start batch job
-const { data: job } = await client.POST('/v1/enrich/batch', {
-  body: { workIds: [...] }
-})
+const { data } = await client.POST('/api/v2/imports', { body: formData })
+const { sseUrl } = data.data
 
-const jobId = job.data.jobId
+const eventSource = new EventSource(sseUrl)
+eventSource.addEventListener('progress', (e) => {
+  const update = JSON.parse(e.data)
+  console.log(`Progress: ${update.progress * 100}%`)
+})
+```
 
-// Connect to WebSocket
-const ws = new WebSocket(`wss://api.oooefam.net/ws/progress?jobId=${jobId}`)
+**WebSocket Example (Batch Enrichment):**
+```typescript
+const { data } = await client.POST('/v1/enrichment/batch', {
+  body: { books: [...], jobId: crypto.randomUUID() }
+})
 
+const ws = new WebSocket(data.data.websocketUrl, [data.data.authToken])
 ws.onmessage = (event) => {
-  const progress = JSON.parse(event.data)
-  console.log(`Progress: ${progress.progress * 100}%`)
+  const message = JSON.parse(event.data)
+  console.log(`Progress: ${message.progress * 100}%`)
 }
 ```
 
+📖 **See [STREAMING_GUIDE.md](./STREAMING_GUIDE.md) for complete SSE/WebSocket documentation**
+
 #### Polling Job Status (Fallback)
 
 ```typescript
@@ -242,7 +278,7 @@ npm publish
 
 ```typescript
 import { useQuery } from '@tanstack/react-query'
-import { client } from '@bookstrack/api-client'
+import { client } from '@jukasdrj/bookstrack-api-client'
 
 function BookSearch({ isbn }: { isbn: string }) {
   const { data, error, isLoading } = useQuery({
@@ -267,7 +303,7 @@ function BookSearch({ isbn }: { isbn: string }) {
 
 ```typescript
 import { ref } from 'vue'
-import { client } from '@bookstrack/api-client'
+import { client } from '@jukasdrj/bookstrack-api-client'
 
 export function useBookSearch(isbn: string) {
   const book = ref(null)
@@ -296,7 +332,7 @@ export function useBookSearch(isbn: string) {
 
 ```typescript
 import { writable } from 'svelte/store'
-import { client } from '@bookstrack/api-client'
+import { client } from '@jukasdrj/bookstrack-api-client'
 
 export function createBookStore() {
   const { subscribe, set, update } = writable({
@@ -339,7 +375,7 @@ const book = await res.json()
 ### After (SDK)
 
 ```typescript
-import { client } from '@bookstrack/api-client'
+import { client } from '@jukasdrj/bookstrack-api-client'
 
 const { data } = await client.GET('/v1/search/isbn', {
   params: { query: { isbn: '123' } }
@@ -359,7 +395,7 @@ const book = data.data
 ## Support
 
 - **Documentation:** https://github.com/yourusername/bendv3/tree/main/docs
-- **API Contract:** https://github.com/yourusername/bendv3/blob/main/docs/API_CONTRACT.md
+- **API Contract:** https://github.com/yourusername/bendv3/blob/main/docs/openapi.yaml
 - **Issues:** https://github.com/yourusername/bendv3/issues
 
 ---