@jukasdrj/bookstrack-api-client 1.0.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/CHANGELOG.md +163 -0
  2. package/README.md +47 -21
  3. package/STREAMING_GUIDE.md +508 -0
  4. package/dist/index.d.ts +1 -0
  5. package/dist/index.d.ts.map +1 -1
  6. package/dist/index.js +2 -0
  7. package/dist/schema.d.ts +344 -1033
  8. package/dist/schema.d.ts.map +1 -1
  9. package/dist/streaming.d.ts +153 -0
  10. package/dist/streaming.d.ts.map +1 -0
  11. package/dist/streaming.js +279 -0
  12. package/package.json +7 -5
package/dist/schema.d.ts CHANGED
@@ -3,7 +3,7 @@
3
3
  * Do not make direct changes to the file.
4
4
  */
5
5
  export interface paths {
6
- "/health": {
6
+ "/v3/capabilities": {
7
7
  parameters: {
8
8
  query?: never;
9
9
  header?: never;
@@ -11,80 +11,10 @@ export interface paths {
11
11
  cookie?: never;
12
12
  };
13
13
  /**
14
- * Health check endpoint
15
- * @description Simple health check that returns worker status.
16
- *
17
- * Returns basic worker information for monitoring purposes:
18
- * - **status**: Health status indicator (always "ok" when responding)
19
- * - **worker**: Worker service name
20
- * - **version**: API version
21
- * - **router**: Router framework type
22
- *
23
- * **Example:** `GET /health`
24
- *
25
- * This endpoint is publicly accessible and requires no authentication.
26
- * Use it for:
27
- * - Monitoring and uptime checks
28
- * - Load balancer health gates
29
- * - CI/CD pipeline verification
14
+ * Get API capabilities
15
+ * @description Returns API feature availability, limits, and deprecation notices. Clients should call this on app startup.
30
16
  */
31
- get: {
32
- parameters: {
33
- query?: never;
34
- header?: never;
35
- path?: never;
36
- cookie?: never;
37
- };
38
- requestBody?: never;
39
- responses: {
40
- /** @description Health check successful */
41
- 200: {
42
- headers: {
43
- [name: string]: unknown;
44
- };
45
- content: {
46
- /**
47
- * @example {
48
- * "data": {
49
- * "status": "ok",
50
- * "worker": "api-worker",
51
- * "version": "2.1.0",
52
- * "router": "hono"
53
- * },
54
- * "metadata": {
55
- * "timestamp": "2025-11-28T12:00:00.000Z"
56
- * }
57
- * }
58
- */
59
- "application/json": {
60
- data: {
61
- /**
62
- * @description Health status indicator
63
- * @enum {string}
64
- */
65
- status: "ok";
66
- /** @description Worker service name */
67
- worker: string;
68
- /** @description API version */
69
- version: string;
70
- /**
71
- * @description Router framework
72
- * @enum {string}
73
- */
74
- router: "hono";
75
- };
76
- metadata?: {
77
- /**
78
- * Format: date-time
79
- * @description ISO 8601 timestamp
80
- */
81
- timestamp: string;
82
- };
83
- };
84
- };
85
- };
86
- };
87
- };
17
+ get: operations["getCapabilities"];
88
18
  put?: never;
89
19
  post?: never;
90
20
  delete?: never;
@@ -93,7 +23,7 @@ export interface paths {
93
23
  patch?: never;
94
24
  trace?: never;
95
25
  };
96
- "/v1/search/isbn": {
26
+ "/v3/recommendations/weekly": {
97
27
  parameters: {
98
28
  query?: never;
99
29
  header?: never;
@@ -101,506 +31,10 @@ export interface paths {
101
31
  cookie?: never;
102
32
  };
103
33
  /**
104
- * Search for a book by ISBN
105
- * @description Search for a book by ISBN-10 or ISBN-13 (digits only, no hyphens).
106
- *
107
- * Returns comprehensive book data including:
108
- * - Works: Abstract creative works (title, description, subjects)
109
- * - Editions: Physical/digital editions (publisher, publication date, format)
110
- * - Authors: Author biographical data (name, gender, cultural region)
111
- *
112
- * **Example:** `GET /v1/search/isbn?isbn=9780439708180`
113
- *
114
- * **Multi-Provider Orchestration:**
115
- * 1. BookRepository (KV/D1 cache) - fastest
116
- * 2. Google Books API - primary source
117
- * 3. OpenLibrary API - fallback #1
118
- * 4. ISBNdb API - fallback #2
119
- *
120
- * **Cache TTL:** 24 hours (KV), permanent (D1)
121
- *
122
- * **Rate Limits:**
123
- * - 100 requests/minute per IP
124
- * - 1000 requests/hour per IP
125
- *
126
- * **Circuit Breaker Protection:**
127
- * All external providers are protected by circuit breakers.
128
- * If a provider's circuit is OPEN, the request fails fast with `CIRCUIT_OPEN` error.
34
+ * Get weekly book recommendations
35
+ * @description Returns global weekly book recommendations. Non-personalized curated picks generated every Sunday at midnight UTC.
129
36
  */
130
- get: {
131
- parameters: {
132
- query: {
133
- /** @description ISBN-10 or ISBN-13 (digits only, no hyphens) */
134
- isbn: string;
135
- };
136
- header?: never;
137
- path?: never;
138
- cookie?: never;
139
- };
140
- requestBody?: never;
141
- responses: {
142
- /** @description Book found successfully */
143
- 200: {
144
- headers: {
145
- [name: string]: unknown;
146
- };
147
- content: {
148
- /**
149
- * @example {
150
- * "data": {
151
- * "works": [
152
- * {
153
- * "title": "Harry Potter and the Philosopher's Stone",
154
- * "subjectTags": [
155
- * "magic",
156
- * "wizards",
157
- * "fantasy"
158
- * ],
159
- * "firstPublicationYear": 1997,
160
- * "description": "Harry Potter has never even heard of Hogwarts...",
161
- * "coverImageURL": "https://covers.openlibrary.org/b/id/12345-L.jpg",
162
- * "primaryProvider": "google_books",
163
- * "goodreadsWorkIDs": [
164
- * "OL82563W"
165
- * ],
166
- * "amazonASINs": [
167
- * "B0192CTMYG"
168
- * ],
169
- * "librarythingIDs": [],
170
- * "googleBooksVolumeIDs": [
171
- * "wrOQLV6xB-wC"
172
- * ],
173
- * "isbndbQuality": 95,
174
- * "reviewStatus": "verified",
175
- * "synthetic": false
176
- * }
177
- * ],
178
- * "editions": [
179
- * {
180
- * "isbns": [
181
- * "9780439708180",
182
- * "0439708184"
183
- * ],
184
- * "title": "Harry Potter and the Philosopher's Stone",
185
- * "publisher": "Scholastic Inc.",
186
- * "publicationDate": "1999-09-01",
187
- * "pageCount": 309,
188
- * "format": "paperback",
189
- * "coverImageURL": "https://covers.openlibrary.org/b/isbn/9780439708180-L.jpg",
190
- * "primaryProvider": "google_books",
191
- * "amazonASINs": [
192
- * "0439708184"
193
- * ],
194
- * "googleBooksVolumeIDs": [
195
- * "wrOQLV6xB-wC"
196
- * ],
197
- * "librarythingIDs": [],
198
- * "isbndbQuality": 95
199
- * }
200
- * ],
201
- * "authors": [
202
- * {
203
- * "name": "J.K. Rowling",
204
- * "gender": "female",
205
- * "culturalRegion": "europe",
206
- * "nationality": "British",
207
- * "birthYear": 1965,
208
- * "openLibraryID": "OL23919A",
209
- * "bookCount": 42
210
- * }
211
- * ],
212
- * "resultCount": 1
213
- * },
214
- * "metadata": {
215
- * "timestamp": "2025-11-28T12:00:00.000Z",
216
- * "processingTime": 145,
217
- * "provider": "google_books",
218
- * "cached": true
219
- * }
220
- * }
221
- */
222
- "application/json": {
223
- data: {
224
- works: {
225
- title: string;
226
- subjectTags: string[];
227
- originalLanguage?: string;
228
- firstPublicationYear?: number;
229
- description?: string;
230
- /** Format: uri */
231
- coverImageURL?: string;
232
- synthetic?: boolean;
233
- /** @enum {string} */
234
- primaryProvider?: "google_books" | "open_library" | "isbndb" | "kv_cache";
235
- contributors?: ("google_books" | "open_library" | "isbndb" | "kv_cache")[];
236
- openLibraryID?: string;
237
- openLibraryWorkID?: string;
238
- isbndbID?: string;
239
- googleBooksVolumeID?: string;
240
- goodreadsID?: string;
241
- goodreadsWorkIDs: string[];
242
- amazonASINs: string[];
243
- librarythingIDs: string[];
244
- googleBooksVolumeIDs: string[];
245
- /** Format: date-time */
246
- lastISBNDBSync?: string;
247
- isbndbQuality: number;
248
- /** @enum {string} */
249
- reviewStatus: "unverified" | "verified" | "rejected" | "flagged";
250
- originalImagePath?: string;
251
- boundingBox?: {
252
- x: number;
253
- y: number;
254
- width: number;
255
- height: number;
256
- };
257
- }[];
258
- editions: {
259
- isbn?: string;
260
- isbns: string[];
261
- title?: string;
262
- publisher?: string;
263
- publicationDate?: string;
264
- pageCount?: number;
265
- /** @enum {string} */
266
- format: "hardcover" | "paperback" | "ebook" | "audiobook" | "mass_market" | "board_book" | "unknown";
267
- /** Format: uri */
268
- coverImageURL?: string;
269
- editionTitle?: string;
270
- editionDescription?: string;
271
- language?: string;
272
- /** @enum {string} */
273
- primaryProvider?: "google_books" | "open_library" | "isbndb" | "kv_cache";
274
- contributors?: ("google_books" | "open_library" | "isbndb" | "kv_cache")[];
275
- openLibraryID?: string;
276
- openLibraryEditionID?: string;
277
- isbndbID?: string;
278
- googleBooksVolumeID?: string;
279
- goodreadsID?: string;
280
- amazonASINs: string[];
281
- googleBooksVolumeIDs: string[];
282
- librarythingIDs: string[];
283
- /** Format: date-time */
284
- lastISBNDBSync?: string;
285
- isbndbQuality: number;
286
- }[];
287
- authors: {
288
- name: string;
289
- /** @enum {string} */
290
- gender: "male" | "female" | "non_binary" | "unknown";
291
- /** @enum {string} */
292
- culturalRegion?: "north_america" | "latin_america" | "europe" | "asia" | "africa" | "middle_east" | "oceania" | "unknown";
293
- nationality?: string;
294
- birthYear?: number;
295
- deathYear?: number;
296
- openLibraryID?: string;
297
- isbndbID?: string;
298
- googleBooksID?: string;
299
- goodreadsID?: string;
300
- bookCount?: number;
301
- }[];
302
- resultCount: number;
303
- };
304
- metadata?: {
305
- /** Format: date-time */
306
- timestamp: string;
307
- processingTime?: number;
308
- /** @enum {string} */
309
- provider?: "google_books" | "open_library" | "isbndb" | "kv_cache" | "d1_database" | "none";
310
- cached?: boolean;
311
- };
312
- };
313
- };
314
- };
315
- /** @description Invalid ISBN format */
316
- 400: {
317
- headers: {
318
- [name: string]: unknown;
319
- };
320
- content: {
321
- /**
322
- * @example {
323
- * "data": null,
324
- * "metadata": {
325
- * "timestamp": "2025-11-28T12:00:00.000Z"
326
- * },
327
- * "error": {
328
- * "code": "INVALID_ISBN",
329
- * "message": "Invalid ISBN format. Must be valid ISBN-10 or ISBN-13",
330
- * "details": {
331
- * "isbn": "invalid-isbn"
332
- * }
333
- * }
334
- * }
335
- */
336
- "application/json": {
337
- data: unknown;
338
- metadata?: {
339
- /** Format: date-time */
340
- timestamp: string;
341
- cached?: boolean;
342
- /** @enum {string} */
343
- source?: "google_books" | "open_library" | "isbndb" | "kv_cache" | "d1_database" | "vectorize";
344
- };
345
- error: {
346
- /** @enum {string} */
347
- code: "NOT_FOUND" | "INVALID_REQUEST" | "INVALID_ISBN" | "INVALID_QUERY" | "MISSING_PARAMETER" | "UNAUTHORIZED" | "FORBIDDEN" | "INTERNAL_ERROR" | "API_ERROR" | "NETWORK_ERROR" | "RATE_LIMIT_EXCEEDED" | "CIRCUIT_OPEN" | "PROVIDER_ERROR" | "TIMEOUT";
348
- message: string;
349
- details?: {
350
- [key: string]: unknown;
351
- };
352
- retryable?: boolean;
353
- retryAfterMs?: number;
354
- provider?: string;
355
- };
356
- };
357
- };
358
- };
359
- /** @description Book not found */
360
- 404: {
361
- headers: {
362
- [name: string]: unknown;
363
- };
364
- content: {
365
- /**
366
- * @example {
367
- * "data": {
368
- * "works": [],
369
- * "editions": [],
370
- * "authors": [],
371
- * "resultCount": 0
372
- * },
373
- * "metadata": {
374
- * "timestamp": "2025-11-28T12:00:00.000Z",
375
- * "processingTime": 523,
376
- * "provider": "none",
377
- * "cached": false
378
- * }
379
- * }
380
- */
381
- "application/json": {
382
- data: {
383
- works: {
384
- title: string;
385
- subjectTags: string[];
386
- originalLanguage?: string;
387
- firstPublicationYear?: number;
388
- description?: string;
389
- /** Format: uri */
390
- coverImageURL?: string;
391
- synthetic?: boolean;
392
- /** @enum {string} */
393
- primaryProvider?: "google_books" | "open_library" | "isbndb" | "kv_cache";
394
- contributors?: ("google_books" | "open_library" | "isbndb" | "kv_cache")[];
395
- openLibraryID?: string;
396
- openLibraryWorkID?: string;
397
- isbndbID?: string;
398
- googleBooksVolumeID?: string;
399
- goodreadsID?: string;
400
- goodreadsWorkIDs: string[];
401
- amazonASINs: string[];
402
- librarythingIDs: string[];
403
- googleBooksVolumeIDs: string[];
404
- /** Format: date-time */
405
- lastISBNDBSync?: string;
406
- isbndbQuality: number;
407
- /** @enum {string} */
408
- reviewStatus: "unverified" | "verified" | "rejected" | "flagged";
409
- originalImagePath?: string;
410
- boundingBox?: {
411
- x: number;
412
- y: number;
413
- width: number;
414
- height: number;
415
- };
416
- }[];
417
- editions: {
418
- isbn?: string;
419
- isbns: string[];
420
- title?: string;
421
- publisher?: string;
422
- publicationDate?: string;
423
- pageCount?: number;
424
- /** @enum {string} */
425
- format: "hardcover" | "paperback" | "ebook" | "audiobook" | "mass_market" | "board_book" | "unknown";
426
- /** Format: uri */
427
- coverImageURL?: string;
428
- editionTitle?: string;
429
- editionDescription?: string;
430
- language?: string;
431
- /** @enum {string} */
432
- primaryProvider?: "google_books" | "open_library" | "isbndb" | "kv_cache";
433
- contributors?: ("google_books" | "open_library" | "isbndb" | "kv_cache")[];
434
- openLibraryID?: string;
435
- openLibraryEditionID?: string;
436
- isbndbID?: string;
437
- googleBooksVolumeID?: string;
438
- goodreadsID?: string;
439
- amazonASINs: string[];
440
- googleBooksVolumeIDs: string[];
441
- librarythingIDs: string[];
442
- /** Format: date-time */
443
- lastISBNDBSync?: string;
444
- isbndbQuality: number;
445
- }[];
446
- authors: {
447
- name: string;
448
- /** @enum {string} */
449
- gender: "male" | "female" | "non_binary" | "unknown";
450
- /** @enum {string} */
451
- culturalRegion?: "north_america" | "latin_america" | "europe" | "asia" | "africa" | "middle_east" | "oceania" | "unknown";
452
- nationality?: string;
453
- birthYear?: number;
454
- deathYear?: number;
455
- openLibraryID?: string;
456
- isbndbID?: string;
457
- googleBooksID?: string;
458
- goodreadsID?: string;
459
- bookCount?: number;
460
- }[];
461
- resultCount: number;
462
- };
463
- metadata?: {
464
- /** Format: date-time */
465
- timestamp: string;
466
- processingTime?: number;
467
- /** @enum {string} */
468
- provider?: "google_books" | "open_library" | "isbndb" | "kv_cache" | "d1_database" | "none";
469
- cached?: boolean;
470
- };
471
- };
472
- };
473
- };
474
- /** @description Rate limit exceeded */
475
- 429: {
476
- headers: {
477
- [name: string]: unknown;
478
- };
479
- content: {
480
- /**
481
- * @example {
482
- * "data": null,
483
- * "metadata": {
484
- * "timestamp": "2025-11-28T12:00:00.000Z"
485
- * },
486
- * "error": {
487
- * "code": "RATE_LIMIT_EXCEEDED",
488
- * "message": "Rate limit exceeded. Maximum 100 requests per minute.",
489
- * "retryable": true,
490
- * "retryAfterMs": 60000
491
- * }
492
- * }
493
- */
494
- "application/json": {
495
- data: unknown;
496
- metadata?: {
497
- /** Format: date-time */
498
- timestamp: string;
499
- cached?: boolean;
500
- /** @enum {string} */
501
- source?: "google_books" | "open_library" | "isbndb" | "kv_cache" | "d1_database" | "vectorize";
502
- };
503
- error: {
504
- /** @enum {string} */
505
- code: "NOT_FOUND" | "INVALID_REQUEST" | "INVALID_ISBN" | "INVALID_QUERY" | "MISSING_PARAMETER" | "UNAUTHORIZED" | "FORBIDDEN" | "INTERNAL_ERROR" | "API_ERROR" | "NETWORK_ERROR" | "RATE_LIMIT_EXCEEDED" | "CIRCUIT_OPEN" | "PROVIDER_ERROR" | "TIMEOUT";
506
- message: string;
507
- details?: {
508
- [key: string]: unknown;
509
- };
510
- retryable?: boolean;
511
- retryAfterMs?: number;
512
- provider?: string;
513
- };
514
- };
515
- };
516
- };
517
- /** @description Internal server error */
518
- 500: {
519
- headers: {
520
- [name: string]: unknown;
521
- };
522
- content: {
523
- /**
524
- * @example {
525
- * "data": null,
526
- * "metadata": {
527
- * "timestamp": "2025-11-28T12:00:00.000Z"
528
- * },
529
- * "error": {
530
- * "code": "INTERNAL_ERROR",
531
- * "message": "An unexpected error occurred while processing the request"
532
- * }
533
- * }
534
- */
535
- "application/json": {
536
- data: unknown;
537
- metadata?: {
538
- /** Format: date-time */
539
- timestamp: string;
540
- cached?: boolean;
541
- /** @enum {string} */
542
- source?: "google_books" | "open_library" | "isbndb" | "kv_cache" | "d1_database" | "vectorize";
543
- };
544
- error: {
545
- /** @enum {string} */
546
- code: "NOT_FOUND" | "INVALID_REQUEST" | "INVALID_ISBN" | "INVALID_QUERY" | "MISSING_PARAMETER" | "UNAUTHORIZED" | "FORBIDDEN" | "INTERNAL_ERROR" | "API_ERROR" | "NETWORK_ERROR" | "RATE_LIMIT_EXCEEDED" | "CIRCUIT_OPEN" | "PROVIDER_ERROR" | "TIMEOUT";
547
- message: string;
548
- details?: {
549
- [key: string]: unknown;
550
- };
551
- retryable?: boolean;
552
- retryAfterMs?: number;
553
- provider?: string;
554
- };
555
- };
556
- };
557
- };
558
- /** @description Circuit breaker open - provider unavailable */
559
- 503: {
560
- headers: {
561
- [name: string]: unknown;
562
- };
563
- content: {
564
- /**
565
- * @example {
566
- * "data": null,
567
- * "metadata": {
568
- * "timestamp": "2025-11-28T12:00:00.000Z"
569
- * },
570
- * "error": {
571
- * "code": "CIRCUIT_OPEN",
572
- * "message": "Provider google-books circuit breaker is open. Service temporarily unavailable.",
573
- * "provider": "google-books",
574
- * "retryable": true,
575
- * "retryAfterMs": 45000
576
- * }
577
- * }
578
- */
579
- "application/json": {
580
- data: unknown;
581
- metadata?: {
582
- /** Format: date-time */
583
- timestamp: string;
584
- cached?: boolean;
585
- /** @enum {string} */
586
- source?: "google_books" | "open_library" | "isbndb" | "kv_cache" | "d1_database" | "vectorize";
587
- };
588
- error: {
589
- /** @enum {string} */
590
- code: "NOT_FOUND" | "INVALID_REQUEST" | "INVALID_ISBN" | "INVALID_QUERY" | "MISSING_PARAMETER" | "UNAUTHORIZED" | "FORBIDDEN" | "INTERNAL_ERROR" | "API_ERROR" | "NETWORK_ERROR" | "RATE_LIMIT_EXCEEDED" | "CIRCUIT_OPEN" | "PROVIDER_ERROR" | "TIMEOUT";
591
- message: string;
592
- details?: {
593
- [key: string]: unknown;
594
- };
595
- retryable?: boolean;
596
- retryAfterMs?: number;
597
- provider?: string;
598
- };
599
- };
600
- };
601
- };
602
- };
603
- };
37
+ get: operations["getWeeklyRecommendations"];
604
38
  put?: never;
605
39
  post?: never;
606
40
  delete?: never;
@@ -609,7 +43,7 @@ export interface paths {
609
43
  patch?: never;
610
44
  trace?: never;
611
45
  };
612
- "/v1/search/title": {
46
+ "/v3/books/search": {
613
47
  parameters: {
614
48
  query?: never;
615
49
  header?: never;
@@ -617,369 +51,10 @@ export interface paths {
617
51
  cookie?: never;
618
52
  };
619
53
  /**
620
- * Search for books by title
621
- * @description Search for books by title using multi-provider orchestration.
622
- *
623
- * Returns up to 20 results by default, each including:
624
- * - Works: Abstract creative works (title, description, subjects)
625
- * - Editions: Physical/digital editions (publisher, publication date, format)
626
- * - Authors: Author biographical data (name, gender, cultural region)
627
- *
628
- * **Example:** `GET /v1/search/title?q=harry%20potter&limit=10`
629
- *
630
- * **Multi-Provider Orchestration:**
631
- * 1. OpenLibrary API - primary source for title searches
632
- * 2. Author enrichment from Wikidata (cultural diversity data)
633
- * 3. No caching (freshness important for search results)
634
- *
635
- * **Query Parameters:**
636
- * - `q` (required): Search query string (1-200 characters)
637
- * - `limit` (optional): Maximum number of results (1-100, default: 20)
638
- *
639
- * **Rate Limits:**
640
- * - 100 requests/minute per IP
641
- * - 1000 requests/hour per IP
642
- *
643
- * **Author Enrichment:**
644
- * All author results are enriched with cultural and biographical data from Wikidata.
54
+ * Search books
55
+ * @description Unified search supporting multiple modes: text, semantic, similar
645
56
  */
646
- get: {
647
- parameters: {
648
- query: {
649
- /** @description Book title search query */
650
- q: string;
651
- /** @description Maximum number of results (1-100, default: 20) */
652
- limit?: string;
653
- };
654
- header?: never;
655
- path?: never;
656
- cookie?: never;
657
- };
658
- requestBody?: never;
659
- responses: {
660
- /** @description Books found successfully (may be empty if no matches) */
661
- 200: {
662
- headers: {
663
- [name: string]: unknown;
664
- };
665
- content: {
666
- /**
667
- * @example {
668
- * "data": {
669
- * "works": [
670
- * {
671
- * "title": "Harry Potter and the Philosopher's Stone",
672
- * "subjectTags": [
673
- * "magic",
674
- * "wizards",
675
- * "fantasy",
676
- * "adventure"
677
- * ],
678
- * "firstPublicationYear": 1997,
679
- * "description": "Harry Potter has never even heard of Hogwarts...",
680
- * "coverImageURL": "https://covers.openlibrary.org/b/id/12345-L.jpg",
681
- * "primaryProvider": "open_library",
682
- * "goodreadsWorkIDs": [
683
- * "OL82563W"
684
- * ],
685
- * "amazonASINs": [
686
- * "B0192CTMYG"
687
- * ],
688
- * "librarythingIDs": [],
689
- * "googleBooksVolumeIDs": [],
690
- * "isbndbQuality": 85,
691
- * "reviewStatus": "verified",
692
- * "synthetic": false
693
- * },
694
- * {
695
- * "title": "Harry Potter and the Chamber of Secrets",
696
- * "subjectTags": [
697
- * "magic",
698
- * "wizards",
699
- * "fantasy"
700
- * ],
701
- * "firstPublicationYear": 1998,
702
- * "description": "The summer after his first year at Hogwarts...",
703
- * "coverImageURL": "https://covers.openlibrary.org/b/id/12346-L.jpg",
704
- * "primaryProvider": "open_library",
705
- * "goodreadsWorkIDs": [
706
- * "OL82563W"
707
- * ],
708
- * "amazonASINs": [
709
- * "B0192CTNYH"
710
- * ],
711
- * "librarythingIDs": [],
712
- * "googleBooksVolumeIDs": [],
713
- * "isbndbQuality": 85,
714
- * "reviewStatus": "verified",
715
- * "synthetic": false
716
- * }
717
- * ],
718
- * "editions": [
719
- * {
720
- * "isbns": [
721
- * "9780439708180",
722
- * "0439708184"
723
- * ],
724
- * "title": "Harry Potter and the Philosopher's Stone",
725
- * "publisher": "Scholastic Inc.",
726
- * "publicationDate": "1999-09-01",
727
- * "pageCount": 309,
728
- * "format": "paperback",
729
- * "coverImageURL": "https://covers.openlibrary.org/b/isbn/9780439708180-L.jpg",
730
- * "primaryProvider": "open_library",
731
- * "amazonASINs": [
732
- * "0439708184"
733
- * ],
734
- * "googleBooksVolumeIDs": [],
735
- * "librarythingIDs": [],
736
- * "isbndbQuality": 85
737
- * }
738
- * ],
739
- * "authors": [
740
- * {
741
- * "name": "J.K. Rowling",
742
- * "gender": "female",
743
- * "culturalRegion": "europe",
744
- * "nationality": "British",
745
- * "birthYear": 1965,
746
- * "openLibraryID": "OL23919A",
747
- * "bookCount": 42
748
- * }
749
- * ],
750
- * "resultCount": 2
751
- * },
752
- * "metadata": {
753
- * "timestamp": "2025-11-28T12:00:00.000Z",
754
- * "processingTime": 1205,
755
- * "provider": "open_library",
756
- * "cached": false
757
- * }
758
- * }
759
- */
760
- "application/json": {
761
- data: {
762
- works: {
763
- title: string;
764
- subjectTags: string[];
765
- originalLanguage?: string;
766
- firstPublicationYear?: number;
767
- description?: string;
768
- /** Format: uri */
769
- coverImageURL?: string;
770
- synthetic?: boolean;
771
- /** @enum {string} */
772
- primaryProvider?: "google_books" | "open_library" | "isbndb" | "kv_cache";
773
- contributors?: ("google_books" | "open_library" | "isbndb" | "kv_cache")[];
774
- openLibraryID?: string;
775
- openLibraryWorkID?: string;
776
- isbndbID?: string;
777
- googleBooksVolumeID?: string;
778
- goodreadsID?: string;
779
- goodreadsWorkIDs: string[];
780
- amazonASINs: string[];
781
- librarythingIDs: string[];
782
- googleBooksVolumeIDs: string[];
783
- /** Format: date-time */
784
- lastISBNDBSync?: string;
785
- isbndbQuality: number;
786
- /** @enum {string} */
787
- reviewStatus: "unverified" | "verified" | "rejected" | "flagged";
788
- originalImagePath?: string;
789
- boundingBox?: {
790
- x: number;
791
- y: number;
792
- width: number;
793
- height: number;
794
- };
795
- }[];
796
- editions: {
797
- isbn?: string;
798
- isbns: string[];
799
- title?: string;
800
- publisher?: string;
801
- publicationDate?: string;
802
- pageCount?: number;
803
- /** @enum {string} */
804
- format: "hardcover" | "paperback" | "ebook" | "audiobook" | "mass_market" | "board_book" | "unknown";
805
- /** Format: uri */
806
- coverImageURL?: string;
807
- editionTitle?: string;
808
- editionDescription?: string;
809
- language?: string;
810
- /** @enum {string} */
811
- primaryProvider?: "google_books" | "open_library" | "isbndb" | "kv_cache";
812
- contributors?: ("google_books" | "open_library" | "isbndb" | "kv_cache")[];
813
- openLibraryID?: string;
814
- openLibraryEditionID?: string;
815
- isbndbID?: string;
816
- googleBooksVolumeID?: string;
817
- goodreadsID?: string;
818
- amazonASINs: string[];
819
- googleBooksVolumeIDs: string[];
820
- librarythingIDs: string[];
821
- /** Format: date-time */
822
- lastISBNDBSync?: string;
823
- isbndbQuality: number;
824
- }[];
825
- authors: {
826
- name: string;
827
- /** @enum {string} */
828
- gender: "male" | "female" | "non_binary" | "unknown";
829
- /** @enum {string} */
830
- culturalRegion?: "north_america" | "latin_america" | "europe" | "asia" | "africa" | "middle_east" | "oceania" | "unknown";
831
- nationality?: string;
832
- birthYear?: number;
833
- deathYear?: number;
834
- openLibraryID?: string;
835
- isbndbID?: string;
836
- googleBooksID?: string;
837
- goodreadsID?: string;
838
- bookCount?: number;
839
- }[];
840
- resultCount: number;
841
- };
842
- metadata?: {
843
- /** Format: date-time */
844
- timestamp: string;
845
- processingTime?: number;
846
- /** @enum {string} */
847
- provider?: "google_books" | "open_library" | "isbndb" | "kv_cache" | "d1_database" | "none";
848
- cached?: boolean;
849
- };
850
- };
851
- };
852
- };
853
- /** @description Invalid query parameters */
854
- 400: {
855
- headers: {
856
- [name: string]: unknown;
857
- };
858
- content: {
859
- /**
860
- * @example {
861
- * "data": null,
862
- * "metadata": {
863
- * "timestamp": "2025-11-28T12:00:00.000Z"
864
- * },
865
- * "error": {
866
- * "code": "INVALID_QUERY",
867
- * "message": "Search query is required and must be 1-200 characters",
868
- * "details": {
869
- * "parameter": "q"
870
- * }
871
- * }
872
- * }
873
- */
874
- "application/json": {
875
- data: unknown;
876
- metadata?: {
877
- /** Format: date-time */
878
- timestamp: string;
879
- cached?: boolean;
880
- /** @enum {string} */
881
- source?: "google_books" | "open_library" | "isbndb" | "kv_cache" | "d1_database" | "vectorize";
882
- };
883
- error: {
884
- /** @enum {string} */
885
- code: "NOT_FOUND" | "INVALID_REQUEST" | "INVALID_ISBN" | "INVALID_QUERY" | "MISSING_PARAMETER" | "UNAUTHORIZED" | "FORBIDDEN" | "INTERNAL_ERROR" | "API_ERROR" | "NETWORK_ERROR" | "RATE_LIMIT_EXCEEDED" | "CIRCUIT_OPEN" | "PROVIDER_ERROR" | "TIMEOUT";
886
- message: string;
887
- details?: {
888
- [key: string]: unknown;
889
- };
890
- retryable?: boolean;
891
- retryAfterMs?: number;
892
- provider?: string;
893
- };
894
- };
895
- };
896
- };
897
- /** @description Rate limit exceeded */
898
- 429: {
899
- headers: {
900
- [name: string]: unknown;
901
- };
902
- content: {
903
- /**
904
- * @example {
905
- * "data": null,
906
- * "metadata": {
907
- * "timestamp": "2025-11-28T12:00:00.000Z"
908
- * },
909
- * "error": {
910
- * "code": "RATE_LIMIT_EXCEEDED",
911
- * "message": "Rate limit exceeded. Maximum 100 requests per minute.",
912
- * "retryable": true,
913
- * "retryAfterMs": 60000
914
- * }
915
- * }
916
- */
917
- "application/json": {
918
- data: unknown;
919
- metadata?: {
920
- /** Format: date-time */
921
- timestamp: string;
922
- cached?: boolean;
923
- /** @enum {string} */
924
- source?: "google_books" | "open_library" | "isbndb" | "kv_cache" | "d1_database" | "vectorize";
925
- };
926
- error: {
927
- /** @enum {string} */
928
- code: "NOT_FOUND" | "INVALID_REQUEST" | "INVALID_ISBN" | "INVALID_QUERY" | "MISSING_PARAMETER" | "UNAUTHORIZED" | "FORBIDDEN" | "INTERNAL_ERROR" | "API_ERROR" | "NETWORK_ERROR" | "RATE_LIMIT_EXCEEDED" | "CIRCUIT_OPEN" | "PROVIDER_ERROR" | "TIMEOUT";
929
- message: string;
930
- details?: {
931
- [key: string]: unknown;
932
- };
933
- retryable?: boolean;
934
- retryAfterMs?: number;
935
- provider?: string;
936
- };
937
- };
938
- };
939
- };
940
- /** @description Internal server error */
941
- 500: {
942
- headers: {
943
- [name: string]: unknown;
944
- };
945
- content: {
946
- /**
947
- * @example {
948
- * "data": null,
949
- * "metadata": {
950
- * "timestamp": "2025-11-28T12:00:00.000Z"
951
- * },
952
- * "error": {
953
- * "code": "INTERNAL_ERROR",
954
- * "message": "An unexpected error occurred while processing the request"
955
- * }
956
- * }
957
- */
958
- "application/json": {
959
- data: unknown;
960
- metadata?: {
961
- /** Format: date-time */
962
- timestamp: string;
963
- cached?: boolean;
964
- /** @enum {string} */
965
- source?: "google_books" | "open_library" | "isbndb" | "kv_cache" | "d1_database" | "vectorize";
966
- };
967
- error: {
968
- /** @enum {string} */
969
- code: "NOT_FOUND" | "INVALID_REQUEST" | "INVALID_ISBN" | "INVALID_QUERY" | "MISSING_PARAMETER" | "UNAUTHORIZED" | "FORBIDDEN" | "INTERNAL_ERROR" | "API_ERROR" | "NETWORK_ERROR" | "RATE_LIMIT_EXCEEDED" | "CIRCUIT_OPEN" | "PROVIDER_ERROR" | "TIMEOUT";
970
- message: string;
971
- details?: {
972
- [key: string]: unknown;
973
- };
974
- retryable?: boolean;
975
- retryAfterMs?: number;
976
- provider?: string;
977
- };
978
- };
979
- };
980
- };
981
- };
982
- };
57
+ get: operations["searchBooks"];
983
58
  put?: never;
984
59
  post?: never;
985
60
  delete?: never;
@@ -988,106 +63,15 @@ export interface paths {
988
63
  patch?: never;
989
64
  trace?: never;
990
65
  };
991
- "/api/v2/capabilities": {
66
+ "/v3/books/{isbn}": {
992
67
  parameters: {
993
68
  query?: never;
994
69
  header?: never;
995
70
  path?: never;
996
71
  cookie?: never;
997
72
  };
998
- /**
999
- * Get API capabilities and feature availability
1000
- * @description Returns comprehensive feature availability and configuration.
1001
- * Clients should call this on app startup to discover available features.
1002
- *
1003
- * **Use Cases:**
1004
- * - Feature discovery (check which endpoints are available)
1005
- * - Version compatibility (check API version)
1006
- * - Rate limit awareness (know limits before hitting them)
1007
- * - Deprecation notices (prepare for sunset endpoints)
1008
- */
1009
- get: {
1010
- parameters: {
1011
- query?: never;
1012
- header?: never;
1013
- path?: never;
1014
- cookie?: never;
1015
- };
1016
- requestBody?: never;
1017
- responses: {
1018
- /** @description API capabilities retrieved successfully */
1019
- 200: {
1020
- headers: {
1021
- [name: string]: unknown;
1022
- };
1023
- content: {
1024
- "application/json": {
1025
- data: {
1026
- apiVersion: string;
1027
- features: {
1028
- name: string;
1029
- enabled: boolean;
1030
- version: string;
1031
- endpoints: string[];
1032
- rateLimit?: {
1033
- requests: number;
1034
- windowMs: number;
1035
- };
1036
- notes?: string;
1037
- }[];
1038
- limits: {
1039
- maxBatchSize: number;
1040
- maxCsvRows: number;
1041
- maxImageSizeMb: number;
1042
- maxConcurrentJobs: number;
1043
- };
1044
- deprecations: {
1045
- endpoint: string;
1046
- sunsetDate: string;
1047
- replacement: string;
1048
- }[];
1049
- };
1050
- metadata?: {
1051
- /** Format: date-time */
1052
- timestamp: string;
1053
- cached?: boolean;
1054
- /** @enum {string} */
1055
- source?: "google_books" | "open_library" | "isbndb" | "kv_cache" | "d1_database" | "vectorize";
1056
- };
1057
- };
1058
- };
1059
- };
1060
- /** @description Internal server error */
1061
- 500: {
1062
- headers: {
1063
- [name: string]: unknown;
1064
- };
1065
- content: {
1066
- "application/json": {
1067
- data: unknown;
1068
- metadata?: {
1069
- /** Format: date-time */
1070
- timestamp: string;
1071
- cached?: boolean;
1072
- /** @enum {string} */
1073
- source?: "google_books" | "open_library" | "isbndb" | "kv_cache" | "d1_database" | "vectorize";
1074
- };
1075
- error: {
1076
- /** @enum {string} */
1077
- code: "NOT_FOUND" | "INVALID_REQUEST" | "INVALID_ISBN" | "INVALID_QUERY" | "MISSING_PARAMETER" | "UNAUTHORIZED" | "FORBIDDEN" | "INTERNAL_ERROR" | "API_ERROR" | "NETWORK_ERROR" | "RATE_LIMIT_EXCEEDED" | "CIRCUIT_OPEN" | "PROVIDER_ERROR" | "TIMEOUT";
1078
- message: string;
1079
- details?: {
1080
- [key: string]: unknown;
1081
- };
1082
- retryable?: boolean;
1083
- retryAfterMs?: number;
1084
- provider?: string;
1085
- };
1086
- };
1087
- };
1088
- };
1089
- };
1090
- };
73
+ /** Get book by ISBN */
74
+ get: operations["getBookByISBN"];
1091
75
  put?: never;
1092
76
  post?: never;
1093
77
  delete?: never;
@@ -1096,10 +80,176 @@ export interface paths {
1096
80
  patch?: never;
1097
81
  trace?: never;
1098
82
  };
83
+ "/v3/books/enrich": {
84
+ parameters: {
85
+ query?: never;
86
+ header?: never;
87
+ path?: never;
88
+ cookie?: never;
89
+ };
90
+ get?: never;
91
+ put?: never;
92
+ /** Enrich books with metadata */
93
+ post: operations["enrichBooks"];
94
+ delete?: never;
95
+ options?: never;
96
+ head?: never;
97
+ patch?: never;
98
+ trace?: never;
99
+ };
1099
100
  }
1100
101
  export type webhooks = Record<string, never>;
1101
102
  export interface components {
1102
- schemas: never;
103
+ schemas: {
104
+ SearchResponse: {
105
+ success: boolean;
106
+ data: {
107
+ books?: components["schemas"]["Book"][];
108
+ total?: number;
109
+ };
110
+ metadata: components["schemas"]["ResponseMetadata"];
111
+ };
112
+ BookResponse: {
113
+ success: boolean;
114
+ data: components["schemas"]["Book"];
115
+ metadata: components["schemas"]["ResponseMetadata"];
116
+ };
117
+ EnrichRequest: {
118
+ isbns: string[];
119
+ /** @default false */
120
+ includeEmbedding: boolean;
121
+ };
122
+ EnrichResponse: {
123
+ success: boolean;
124
+ data: {
125
+ books?: components["schemas"]["Book"][];
126
+ found?: number;
127
+ requested?: number;
128
+ };
129
+ metadata: components["schemas"]["ResponseMetadata"];
130
+ };
131
+ Book: {
132
+ /** @description 13-digit ISBN (example: 9780439708180) */
133
+ isbn: string;
134
+ /** @description 10-digit ISBN if available (example: 0439708184) */
135
+ isbn10?: string;
136
+ /** @description Book title */
137
+ title: string;
138
+ /** @description Book subtitle */
139
+ subtitle?: string;
140
+ /** @description List of author names */
141
+ authors: string[];
142
+ /** @description Publisher name */
143
+ publisher?: string;
144
+ /** @description Publication date (ISO 8601 or partial format) */
145
+ publishedDate?: string;
146
+ /** @description Book description/synopsis */
147
+ description?: string;
148
+ /** @description Number of pages */
149
+ pageCount?: number;
150
+ /** @description Book categories/genres */
151
+ categories?: string[];
152
+ /** @description ISO 639-1 language code (e.g., "en") */
153
+ language?: string;
154
+ /**
155
+ * Format: uri
156
+ * @description Cover image URL
157
+ */
158
+ coverUrl?: string;
159
+ /**
160
+ * Format: uri
161
+ * @description Thumbnail image URL
162
+ */
163
+ thumbnailUrl?: string;
164
+ /** @description OpenLibrary work key (e.g., OL82563W) */
165
+ workKey?: string;
166
+ /** @description OpenLibrary edition key (e.g., OL7353617M) */
167
+ editionKey?: string;
168
+ /**
169
+ * @description Data source provider
170
+ * @enum {string}
171
+ */
172
+ provider: "alexandria" | "google_books" | "open_library" | "isbndb";
173
+ /** @description Data quality score 0-100 */
174
+ quality: number;
175
+ };
176
+ ErrorResponse: {
177
+ /** @enum {boolean} */
178
+ success: false;
179
+ error: {
180
+ code: string;
181
+ message: string;
182
+ retryable?: boolean;
183
+ };
184
+ };
185
+ ResponseMetadata: {
186
+ /** Format: date-time */
187
+ timestamp: string;
188
+ requestId?: string;
189
+ cached?: boolean;
190
+ /** @description Request processing time in milliseconds */
191
+ processingTime?: number;
192
+ };
193
+ /** @description API capabilities (iOS-compatible flat format) */
194
+ CapabilitiesResponse: {
195
+ features: components["schemas"]["CapabilitiesFeatures"];
196
+ limits: components["schemas"]["CapabilitiesLimits"];
197
+ /** @description API version */
198
+ version: string;
199
+ };
200
+ CapabilitiesFeatures: {
201
+ /** @description Semantic search enabled */
202
+ semantic_search: boolean;
203
+ /** @description Similar books search enabled */
204
+ similar_books: boolean;
205
+ /** @description Weekly recommendations enabled */
206
+ weekly_recommendations: boolean;
207
+ /** @description SSE streaming enabled */
208
+ sse_streaming: boolean;
209
+ /** @description Batch enrichment enabled */
210
+ batch_enrichment: boolean;
211
+ /** @description CSV import enabled */
212
+ csv_import: boolean;
213
+ };
214
+ CapabilitiesLimits: {
215
+ /** @description Semantic search requests per minute */
216
+ semantic_search_rpm: number;
217
+ /** @description Text search requests per minute */
218
+ text_search_rpm: number;
219
+ /** @description Maximum rows in CSV import */
220
+ csv_max_rows: number;
221
+ /** @description Maximum photos in batch scan */
222
+ batch_max_photos: number;
223
+ };
224
+ RecommendationsResponse: {
225
+ success: boolean;
226
+ data: {
227
+ /** @description Week start date (ISO 8601) */
228
+ weekOf: string;
229
+ recommendations: components["schemas"]["Recommendation"][];
230
+ /** @description Number of recommendations returned */
231
+ count: number;
232
+ /** @description Total recommendations available */
233
+ totalAvailable: number;
234
+ };
235
+ metadata: components["schemas"]["ResponseMetadata"];
236
+ };
237
+ Recommendation: {
238
+ /** @description Book ISBN */
239
+ isbn: string;
240
+ /** @description Book title */
241
+ title: string;
242
+ /** @description Primary author */
243
+ author: string;
244
+ /**
245
+ * Format: uri
246
+ * @description Cover image URL
247
+ */
248
+ coverUrl?: string;
249
+ /** @description Why this book is recommended */
250
+ reason: string;
251
+ };
252
+ };
1103
253
  responses: never;
1104
254
  parameters: never;
1105
255
  requestBodies: never;
@@ -1107,5 +257,166 @@ export interface components {
1107
257
  pathItems: never;
1108
258
  }
1109
259
  export type $defs = Record<string, never>;
1110
- export type operations = Record<string, never>;
260
+ export interface operations {
261
+ getCapabilities: {
262
+ parameters: {
263
+ query?: never;
264
+ header?: never;
265
+ path?: never;
266
+ cookie?: never;
267
+ };
268
+ requestBody?: never;
269
+ responses: {
270
+ /** @description API capabilities */
271
+ 200: {
272
+ headers: {
273
+ [name: string]: unknown;
274
+ };
275
+ content: {
276
+ "application/json": components["schemas"]["CapabilitiesResponse"];
277
+ };
278
+ };
279
+ /** @description Server error */
280
+ 500: {
281
+ headers: {
282
+ [name: string]: unknown;
283
+ };
284
+ content: {
285
+ "application/problem+json": components["schemas"]["ErrorResponse"];
286
+ };
287
+ };
288
+ };
289
+ };
290
+ getWeeklyRecommendations: {
291
+ parameters: {
292
+ query?: {
293
+ /** @description Number of recommendations (1-20) */
294
+ limit?: number;
295
+ };
296
+ header?: never;
297
+ path?: never;
298
+ cookie?: never;
299
+ };
300
+ requestBody?: never;
301
+ responses: {
302
+ /** @description Weekly recommendations */
303
+ 200: {
304
+ headers: {
305
+ [name: string]: unknown;
306
+ };
307
+ content: {
308
+ "application/json": components["schemas"]["RecommendationsResponse"];
309
+ };
310
+ };
311
+ /** @description No recommendations available */
312
+ 404: {
313
+ headers: {
314
+ [name: string]: unknown;
315
+ };
316
+ content: {
317
+ "application/problem+json": components["schemas"]["ErrorResponse"];
318
+ };
319
+ };
320
+ /** @description Server error */
321
+ 500: {
322
+ headers: {
323
+ [name: string]: unknown;
324
+ };
325
+ content: {
326
+ "application/problem+json": components["schemas"]["ErrorResponse"];
327
+ };
328
+ };
329
+ };
330
+ };
331
+ searchBooks: {
332
+ parameters: {
333
+ query: {
334
+ /** @description Search query */
335
+ q: string;
336
+ mode?: "text" | "semantic" | "similar";
337
+ page?: number;
338
+ limit?: number;
339
+ };
340
+ header?: never;
341
+ path?: never;
342
+ cookie?: never;
343
+ };
344
+ requestBody?: never;
345
+ responses: {
346
+ /** @description Search results */
347
+ 200: {
348
+ headers: {
349
+ [name: string]: unknown;
350
+ };
351
+ content: {
352
+ "application/json": components["schemas"]["SearchResponse"];
353
+ };
354
+ };
355
+ /** @description Invalid request */
356
+ 400: {
357
+ headers: {
358
+ [name: string]: unknown;
359
+ };
360
+ content: {
361
+ "application/problem+json": components["schemas"]["ErrorResponse"];
362
+ };
363
+ };
364
+ };
365
+ };
366
+ getBookByISBN: {
367
+ parameters: {
368
+ query?: never;
369
+ header?: never;
370
+ path: {
371
+ isbn: string;
372
+ };
373
+ cookie?: never;
374
+ };
375
+ requestBody?: never;
376
+ responses: {
377
+ /** @description Book details */
378
+ 200: {
379
+ headers: {
380
+ [name: string]: unknown;
381
+ };
382
+ content: {
383
+ "application/json": components["schemas"]["BookResponse"];
384
+ };
385
+ };
386
+ /** @description Book not found */
387
+ 404: {
388
+ headers: {
389
+ [name: string]: unknown;
390
+ };
391
+ content: {
392
+ "application/problem+json": components["schemas"]["ErrorResponse"];
393
+ };
394
+ };
395
+ };
396
+ };
397
+ enrichBooks: {
398
+ parameters: {
399
+ query?: never;
400
+ header?: never;
401
+ path?: never;
402
+ cookie?: never;
403
+ };
404
+ requestBody: {
405
+ content: {
406
+ "application/json": components["schemas"]["EnrichRequest"];
407
+ };
408
+ };
409
+ responses: {
410
+ /** @description Enriched books */
411
+ 200: {
412
+ headers: {
413
+ [name: string]: unknown;
414
+ };
415
+ content: {
416
+ "application/json": components["schemas"]["EnrichResponse"];
417
+ };
418
+ };
419
+ };
420
+ };
421
+ }
1111
422
  //# sourceMappingURL=schema.d.ts.map