kmcom-nuxt-layers 2.5.1 → 2.6.2

package/layers/metadata/providers/comicvine/server/utils/metadata-comicvine/provider.ts

@@ -1,26 +1,43 @@
 import type { MetadataProvider } from '#layers/metadata/shared/types'
 
+// Matches CJK, Hangul, Arabic, Hebrew, Thai, Devanagari, Cyrillic, etc.
+const NON_LATIN_RE = /[Ͱ-ϿЀ-ӿ؀-ۿऀ-ॿ　-鿿가-힯豈-﫿]/
+
+function isEnglish(title: string): boolean {
+  return !NON_LATIN_RE.test(title)
+}
+
 export const comicVineProvider: MetadataProvider = {
   id: 'comicvine',
   label: 'Comic Vine',
-  mediaTypes: ['comic', 'graphic-novel', 'collected-edition'],
+  mediaTypes: ['comic', 'comic-series'],
 
-  // fallow-ignore-next-line complexity
   async search({ query, mediaType, limit = 10 }) {
-    const resourceType = mediaType === 'collected-edition' || mediaType === 'graphic-novel' ? 'volume' : 'issue'
-
-    if (resourceType === 'volume') {
+    if (mediaType === 'comic-series') {
       const res = await searchComicVineVolumes(query, limit)
-      return (Array.isArray(res.results) ? res.results : []).map(normaliseComicVineVolume)
+      return (Array.isArray(res.results) ? res.results : [])
+        .filter((v) => isEnglish(v.name))
+        .map(normaliseComicVineVolume)
+    }
+
+    if (mediaType === 'comic') {
+      const res = await searchComicVineIssues(query, limit)
+      return (Array.isArray(res.results) ? res.results : [])
+        .filter((i) => isEnglish(i.name ?? i.volume?.name ?? ''))
+        .map(normaliseComicVineIssue)
     }
 
+    // All — split limit between issues and series
     const [issueRes, volumeRes] = await Promise.all([
       searchComicVineIssues(query, Math.ceil(limit / 2)),
       searchComicVineVolumes(query, Math.floor(limit / 2)),
     ])
-
-    const issues = (Array.isArray(issueRes.results) ? issueRes.results : []).map(normaliseComicVineIssue)
-    const volumes = (Array.isArray(volumeRes.results) ? volumeRes.results : []).map(normaliseComicVineVolume)
+    const issues = (Array.isArray(issueRes.results) ? issueRes.results : [])
+      .filter((i) => isEnglish(i.name ?? i.volume?.name ?? ''))
+      .map(normaliseComicVineIssue)
+    const volumes = (Array.isArray(volumeRes.results) ? volumeRes.results : [])
+      .filter((v) => isEnglish(v.name))
+      .map(normaliseComicVineVolume)
     return [...issues, ...volumes]
   },
 

package/layers/metadata/providers/comicvine/server/utils/metadata-comicvine/types.ts

@@ -29,6 +29,7 @@ export type ComicVineVolume = {
   description: string | null
   deck: string | null
   start_year: string | null
+  count_of_issues: number | null
   site_detail_url: string
   image: { original_url: string; medium_url: string } | null
   publisher: { id: number; name: string } | null

package/layers/metadata/providers/comicvine/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../../apps/playground/tsconfig.json",
+  "extends": "../../../../apps/playground/tsconfig.json",
   "compilerOptions": {
     "strict": true
   },

package/layers/metadata/providers/google-books/nuxt.config.ts

@@ -24,7 +24,7 @@ export default defineNuxtConfig({
 })
 
 declare module '@nuxt/schema' {
-  interface RuntimeConfig {
+  type RuntimeConfig = {
     metadataGoogleBooks: {
       apiKey: string
     }

package/layers/metadata/providers/google-books/server/utils/metadata-google-books/client.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest'
+
+import { googleBooksCoverUrl, googleBooksMediaType } from './client'
+
+describe('googleBooksMediaType', () => {
+  it('classifies manga from categories', () => {
+    expect(googleBooksMediaType(['Comics & Graphic Novels / Manga'])).toBe('manga')
+  })
+
+  it('classifies comic as graphic-novel', () => {
+    expect(googleBooksMediaType(['Comics & Graphic Novels / Comic'])).toBe('graphic-novel')
+  })
+
+  it('classifies "graphic novel" as graphic-novel', () => {
+    expect(googleBooksMediaType(['Fiction / Graphic Novel'])).toBe('graphic-novel')
+  })
+
+  it('is case-insensitive', () => {
+    expect(googleBooksMediaType(['MANGA'])).toBe('manga')
+    expect(googleBooksMediaType(['COMIC'])).toBe('graphic-novel')
+  })
+
+  it('defaults to book for unrelated categories', () => {
+    expect(googleBooksMediaType(['Fiction / Thriller'])).toBe('book')
+  })
+
+  it('defaults to book when categories is undefined', () => {
+    expect(googleBooksMediaType(undefined)).toBe('book')
+  })
+
+  it('defaults to book when categories is empty', () => {
+    expect(googleBooksMediaType([])).toBe('book')
+  })
+
+  it('prefers manga over comic when both are present', () => {
+    expect(googleBooksMediaType(['Manga / Comic'])).toBe('manga')
+  })
+})
+
+describe('googleBooksCoverUrl', () => {
+  it('upgrades http to https', () => {
+    const url = googleBooksCoverUrl('http://books.google.com/books/content?id=abc&zoom=1')
+    expect(url.startsWith('https://')).toBe(true)
+  })
+
+  it('rewrites zoom=N to zoom=3', () => {
+    const url = googleBooksCoverUrl('https://books.google.com/books/content?id=abc&zoom=1')
+    expect(url).toContain('&zoom=3')
+    expect(url).not.toContain('&zoom=1')
+  })
+
+  it('strips &edge=curl', () => {
+    const url = googleBooksCoverUrl(
+      'https://books.google.com/books/content?id=abc&zoom=1&edge=curl'
+    )
+    expect(url).not.toContain('edge=curl')
+  })
+
+  it('appends &fife=w{width} using the default width of 800', () => {
+    const url = googleBooksCoverUrl('https://books.google.com/books/content?id=abc&zoom=1')
+    expect(url.endsWith('&fife=w800')).toBe(true)
+  })
+
+  it('appends &fife=w{width} using a custom width', () => {
+    const url = googleBooksCoverUrl('https://books.google.com/books/content?id=abc&zoom=1', 200)
+    expect(url.endsWith('&fife=w200')).toBe(true)
+  })
+
+  it('applies all transformations together', () => {
+    const url = googleBooksCoverUrl(
+      'http://books.google.com/books/content?id=abc&zoom=5&edge=curl',
+      400
+    )
+    expect(url).toBe('https://books.google.com/books/content?id=abc&zoom=3&fife=w400')
+  })
+})

package/layers/metadata/providers/google-books/server/utils/metadata-google-books/client.ts

@@ -2,12 +2,30 @@ import type { GoogleBooksSearchResponse, GoogleBooksVolume } from './types'
 
 const BASE = 'https://www.googleapis.com/books/v1'
 
+export function googleBooksMediaType(categories?: string[]): import('#layers/metadata/shared/types').MetadataMediaType {
+  const joined = (categories ?? []).join(' ').toLowerCase()
+  if (joined.includes('manga')) return 'manga'
+  if (joined.includes('comic') || joined.includes('graphic novel')) return 'graphic-novel'
+  return 'book'
+}
+
+export function googleBooksCoverUrl(url: string, width = 800): string {
+  return url
+    .replace('http://', 'https://')
+    .replace(/&zoom=\d+/, '&zoom=3')
+    .replace('&edge=curl', '')
+    + `&fife=w${width}`
+}
+
 function getApiKey(): string | undefined {
   return useRuntimeConfig().metadataGoogleBooks?.apiKey || undefined
 }
 
-export async function searchGoogleBooks(query: string, limit = 10): Promise<GoogleBooksSearchResponse> {
-  const params: Record<string, string> = { q: query, maxResults: String(limit) }
+export async function searchGoogleBooks(
+  query: string,
+  limit = 10
+): Promise<GoogleBooksSearchResponse> {
+  const params: Record<string, string> = { q: query, maxResults: String(limit), langRestrict: 'en' }
   const apiKey = getApiKey()
   if (apiKey) params.key = apiKey
 

package/layers/metadata/providers/google-books/server/utils/metadata-google-books/normalise.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { googleBooksCoverUrl, googleBooksMediaType } from './client'
+import { normaliseGoogleBooksVolume } from './normalise'
+import type { GoogleBooksVolume } from './types'
+
+// normalise.ts calls googleBooksMediaType()/googleBooksCoverUrl() as Nitro auto-imports;
+// stub them with the real (pure, string-building) implementations from client.ts.
+vi.stubGlobal('googleBooksMediaType', googleBooksMediaType)
+vi.stubGlobal('googleBooksCoverUrl', googleBooksCoverUrl)
+
+function baseVolume(overrides: Partial<GoogleBooksVolume['volumeInfo']> = {}): GoogleBooksVolume {
+  return {
+    id: 'abc123',
+    selfLink: 'https://www.googleapis.com/books/v1/volumes/abc123',
+    volumeInfo: {
+      title: 'Watchmen',
+      ...overrides,
+    },
+  }
+}
+
+describe('normaliseGoogleBooksVolume', () => {
+  it('prefers extraLarge over all other image sizes', () => {
+    const record = normaliseGoogleBooksVolume(
+      baseVolume({
+        imageLinks: {
+          smallThumbnail: 's.jpg',
+          thumbnail: 't.jpg',
+          small: 'sm.jpg',
+          medium: 'm.jpg',
+          large: 'l.jpg',
+          extraLarge: 'xl.jpg',
+        },
+      })
+    )
+    expect(record.coverUrl).toBe(googleBooksCoverUrl('xl.jpg'))
+  })
+
+  it('falls back to large when extraLarge is absent', () => {
+    const record = normaliseGoogleBooksVolume(
+      baseVolume({ imageLinks: { large: 'l.jpg', medium: 'm.jpg' } })
+    )
+    expect(record.coverUrl).toBe(googleBooksCoverUrl('l.jpg'))
+  })
+
+  it('falls back to medium when extraLarge/large are absent', () => {
+    const record = normaliseGoogleBooksVolume(
+      baseVolume({ imageLinks: { medium: 'm.jpg', small: 'sm.jpg' } })
+    )
+    expect(record.coverUrl).toBe(googleBooksCoverUrl('m.jpg'))
+  })
+
+  it('falls back to small when extraLarge/large/medium are absent', () => {
+    const record = normaliseGoogleBooksVolume(
+      baseVolume({ imageLinks: { small: 'sm.jpg', thumbnail: 't.jpg' } })
+    )
+    expect(record.coverUrl).toBe(googleBooksCoverUrl('sm.jpg'))
+  })
+
+  it('falls back to thumbnail when larger sizes are absent', () => {
+    const record = normaliseGoogleBooksVolume(
+      baseVolume({ imageLinks: { thumbnail: 't.jpg', smallThumbnail: 's.jpg' } })
+    )
+    expect(record.coverUrl).toBe(googleBooksCoverUrl('t.jpg'))
+  })
+
+  it('falls back to smallThumbnail as the last resort', () => {
+    const record = normaliseGoogleBooksVolume(
+      baseVolume({ imageLinks: { smallThumbnail: 's.jpg' } })
+    )
+    expect(record.coverUrl).toBe(googleBooksCoverUrl('s.jpg'))
+  })
+
+  it('leaves coverUrl undefined when imageLinks is absent', () => {
+    expect(normaliseGoogleBooksVolume(baseVolume()).coverUrl).toBeUndefined()
+  })
+
+  it('extracts isbn10/isbn13 from industryIdentifiers', () => {
+    const record = normaliseGoogleBooksVolume(
+      baseVolume({
+        industryIdentifiers: [
+          { type: 'ISBN_10', identifier: '0930289232' },
+          { type: 'ISBN_13', identifier: '9780930289232' },
+        ],
+      })
+    )
+    expect(record.identifiers).toMatchObject({
+      isbn10: '0930289232',
+      isbn13: '9780930289232',
+    })
+  })
+
+  it('leaves isbn10/isbn13 undefined when industryIdentifiers is absent', () => {
+    const record = normaliseGoogleBooksVolume(baseVolume())
+    expect(record.identifiers?.isbn10).toBeUndefined()
+    expect(record.identifiers?.isbn13).toBeUndefined()
+  })
+
+  it('always sets identifiers.googleBooksId to the volume id', () => {
+    const record = normaliseGoogleBooksVolume(baseVolume())
+    expect(record.identifiers?.googleBooksId).toBe('abc123')
+  })
+
+  it('classifies mediaType via googleBooksMediaType(categories)', () => {
+    const manga = normaliseGoogleBooksVolume(baseVolume({ categories: ['Manga'] }))
+    expect(manga.mediaType).toBe('manga')
+
+    const book = normaliseGoogleBooksVolume(baseVolume({ categories: ['Fiction'] }))
+    expect(book.mediaType).toBe('book')
+  })
+
+  it('maps authors to creators with the author role', () => {
+    const record = normaliseGoogleBooksVolume(baseVolume({ authors: ['Alan Moore'] }))
+    expect(record.creators).toEqual([{ name: 'Alan Moore', role: 'author' }])
+  })
+
+  it('leaves creators undefined when authors is absent', () => {
+    expect(normaliseGoogleBooksVolume(baseVolume()).creators).toBeUndefined()
+  })
+
+  it('prefers canonicalVolumeLink over infoLink for sourceUrl', () => {
+    const record = normaliseGoogleBooksVolume(
+      baseVolume({ canonicalVolumeLink: 'canonical.url', infoLink: 'info.url' })
+    )
+    expect(record.sourceUrl).toBe('canonical.url')
+  })
+
+  it('falls back to infoLink when canonicalVolumeLink is absent', () => {
+    const record = normaliseGoogleBooksVolume(baseVolume({ infoLink: 'info.url' }))
+    expect(record.sourceUrl).toBe('info.url')
+  })
+
+  it('stamps lastSyncedAt as a string', () => {
+    expect(normaliseGoogleBooksVolume(baseVolume()).lastSyncedAt).toEqual(expect.any(String))
+  })
+
+  it('sets id and provider fields from the volume id', () => {
+    const record = normaliseGoogleBooksVolume(baseVolume())
+    expect(record.id).toBe('google-books:volume:abc123')
+    expect(record.provider).toBe('google-books')
+    expect(record.providerId).toBe('abc123')
+  })
+})

package/layers/metadata/providers/google-books/server/utils/metadata-google-books/normalise.ts

@@ -1,4 +1,5 @@
-import type { MetadataRecord, MetadataCreator } from '#layers/metadata/shared/types'
+import type { MetadataCreator, MetadataRecord } from '#layers/metadata/shared/types'
+
 import type { GoogleBooksVolume } from './types'
 
 // fallow-ignore-next-line complexity
@@ -13,26 +14,34 @@ export function normaliseGoogleBooksVolume(volume: GoogleBooksVolume): MetadataR
   const isbn10 = volumeInfo.industryIdentifiers?.find((i) => i.type === 'ISBN_10')?.identifier
   const isbn13 = volumeInfo.industryIdentifiers?.find((i) => i.type === 'ISBN_13')?.identifier
 
-  const cover = volumeInfo.imageLinks?.thumbnail ?? volumeInfo.imageLinks?.smallThumbnail
+  const rawCover =
+    volumeInfo.imageLinks?.extraLarge ??
+    volumeInfo.imageLinks?.large ??
+    volumeInfo.imageLinks?.medium ??
+    volumeInfo.imageLinks?.small ??
+    volumeInfo.imageLinks?.thumbnail ??
+    volumeInfo.imageLinks?.smallThumbnail
+
+  const sourceUrl = volumeInfo.canonicalVolumeLink ?? volumeInfo.infoLink
 
   return {
     id: `google-books:volume:${volume.id}`,
     provider: 'google-books',
     providerId: volume.id,
-    mediaType: 'book',
+    mediaType: googleBooksMediaType(volumeInfo.categories),
     title: volumeInfo.title,
-    subtitle: volumeInfo.subtitle,
-    description: volumeInfo.description,
-    creators: creators.length ? creators : undefined,
-    publisher: volumeInfo.publisher,
-    publishedAt: volumeInfo.publishedDate,
-    coverUrl: cover ? cover.replace('http://', 'https://') : undefined,
+    ...(volumeInfo.subtitle && { subtitle: volumeInfo.subtitle }),
+    ...(volumeInfo.description && { description: volumeInfo.description }),
+    ...(creators.length && { creators }),
+    ...(volumeInfo.publisher && { publisher: volumeInfo.publisher }),
+    ...(volumeInfo.publishedDate && { publishedAt: volumeInfo.publishedDate }),
+    ...(rawCover && { coverUrl: googleBooksCoverUrl(rawCover) }),
     identifiers: {
-      isbn10,
-      isbn13,
+      ...(isbn10 && { isbn10 }),
+      ...(isbn13 && { isbn13 }),
       googleBooksId: volume.id,
     },
-    sourceUrl: volumeInfo.canonicalVolumeLink ?? volumeInfo.infoLink,
+    ...(sourceUrl && { sourceUrl }),
     raw: volume,
     lastSyncedAt: new Date().toISOString(),
   }

package/layers/metadata/providers/google-books/server/utils/metadata-google-books/provider.ts

@@ -3,11 +3,18 @@ import type { MetadataProvider } from '#layers/metadata/shared/types'
 export const googleBooksProvider: MetadataProvider = {
   id: 'google-books',
   label: 'Google Books',
-  mediaTypes: ['book', 'graphic-novel', 'collected-edition'],
+  mediaTypes: ['book', 'graphic-novel', 'manga'],
 
-  async search({ query, limit = 10 }) {
-    const res = await searchGoogleBooks(query, limit)
-    return (res.items ?? []).map(normaliseGoogleBooksVolume)
+  async search({ query, mediaType, limit = 10 }) {
+    const subjectHints: Record<string, string> = {
+      'graphic-novel': '+subject:"Comics & Graphic Novels"',
+      'manga': '+subject:manga',
+      'book': '+-subject:"Comics & Graphic Novels"+-subject:manga',
+    }
+    const q = query + (mediaType ? (subjectHints[mediaType] ?? '') : '')
+    const res = await searchGoogleBooks(q, limit)
+    const records = (res.items ?? []).map(normaliseGoogleBooksVolume)
+    return mediaType ? records.filter((r) => r.mediaType === mediaType) : records
   },
 
   async lookup({ providerId }) {

package/layers/metadata/providers/google-books/server/utils/metadata-google-books/types.ts

@@ -7,7 +7,15 @@ export type GoogleBooksVolumeInfo = {
   description?: string
   industryIdentifiers?: Array<{ type: 'ISBN_10' | 'ISBN_13' | string; identifier: string }>
   pageCount?: number
-  imageLinks?: { thumbnail?: string; smallThumbnail?: string }
+  imageLinks?: {
+    smallThumbnail?: string
+    thumbnail?: string
+    small?: string
+    medium?: string
+    large?: string
+    extraLarge?: string
+  }
+  categories?: string[]
   previewLink?: string
   infoLink?: string
   canonicalVolumeLink?: string

package/layers/metadata/providers/google-books/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../../apps/playground/tsconfig.json",
+  "extends": "../../../../apps/playground/tsconfig.json",
   "compilerOptions": {
     "strict": true
   },

package/layers/metadata/providers/openlibrary/server/utils/metadata-openlibrary/client.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest'
+
+import { openLibraryCoverUrl } from './client'
+
+describe('openLibraryCoverUrl', () => {
+  it('builds the covers.openlibrary.org URL shape', () => {
+    expect(openLibraryCoverUrl(12345)).toBe('https://covers.openlibrary.org/b/id/12345-L.jpg')
+  })
+
+  it('defaults to size L when no size is given', () => {
+    expect(openLibraryCoverUrl(1)).toBe('https://covers.openlibrary.org/b/id/1-L.jpg')
+  })
+
+  it('supports the S size', () => {
+    expect(openLibraryCoverUrl(1, 'S')).toBe('https://covers.openlibrary.org/b/id/1-S.jpg')
+  })
+
+  it('supports the M size', () => {
+    expect(openLibraryCoverUrl(1, 'M')).toBe('https://covers.openlibrary.org/b/id/1-M.jpg')
+  })
+
+  it('supports the L size explicitly', () => {
+    expect(openLibraryCoverUrl(1, 'L')).toBe('https://covers.openlibrary.org/b/id/1-L.jpg')
+  })
+})

package/layers/metadata/providers/openlibrary/server/utils/metadata-openlibrary/client.ts

@@ -1,14 +1,23 @@
-import type { OpenLibrarySearchResponse, OpenLibraryWork, OpenLibraryEdition } from './types'
+import type { OpenLibraryEdition, OpenLibrarySearchResponse, OpenLibraryWork } from './types'
 
 const BASE = 'https://openlibrary.org'
 
-export function openLibraryCoverUrl(coverId: number, size: 'S' | 'M' | 'L' = 'M'): string {
+export function openLibraryCoverUrl(coverId: number, size: 'S' | 'M' | 'L' = 'L'): string {
   return `https://covers.openlibrary.org/b/id/${coverId}-${size}.jpg`
 }
 
-export async function searchOpenLibrary(query: string, limit = 10): Promise<OpenLibrarySearchResponse> {
+export async function searchOpenLibrary(
+  query: string,
+  limit = 10
+): Promise<OpenLibrarySearchResponse> {
   return $fetch<OpenLibrarySearchResponse>(`${BASE}/search.json`, {
-    query: { q: query, limit, fields: 'key,title,subtitle,author_name,author_key,publisher,first_publish_year,isbn,cover_i,number_of_pages_median' },
+    timeout: 10000,
+    query: {
+      q: query,
+      limit,
+      fields:
+        'key,title,subtitle,author_name,author_key,publisher,first_publish_year,isbn,cover_i,number_of_pages_median',
+    },
   })
 }
 
@@ -23,8 +32,7 @@ export async function lookupOpenLibraryEdition(editionId: string): Promise<OpenL
 export async function lookupByIsbn(isbn: string): Promise<OpenLibraryEdition | null> {
   try {
     return await $fetch<OpenLibraryEdition>(`${BASE}/isbn/${isbn}.json`)
-  }
-  catch {
+  } catch {
     return null
   }
 }

package/layers/metadata/providers/openlibrary/server/utils/metadata-openlibrary/normalise.test.ts

@@ -0,0 +1,142 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { openLibraryCoverUrl } from './client'
+import {
+  normaliseOpenLibraryEdition,
+  normaliseOpenLibrarySearchDoc,
+  normaliseOpenLibraryWork,
+} from './normalise'
+import type { OpenLibraryEdition, OpenLibrarySearchDoc, OpenLibraryWork } from './types'
+
+// normalise.ts calls openLibraryCoverUrl() as a Nitro auto-import; stub it with the real
+// implementation from client.ts since that function is pure (no $fetch/config involved).
+vi.stubGlobal('openLibraryCoverUrl', openLibraryCoverUrl)
+
+function baseSearchDoc(overrides: Partial<OpenLibrarySearchDoc> = {}): OpenLibrarySearchDoc {
+  return {
+    key: '/works/OL82563W',
+    title: 'Watchmen',
+    ...overrides,
+  }
+}
+
+function baseWork(overrides: Partial<OpenLibraryWork> = {}): OpenLibraryWork {
+  return {
+    key: '/works/OL82563W',
+    title: 'Watchmen',
+    ...overrides,
+  }
+}
+
+function baseEdition(overrides: Partial<OpenLibraryEdition> = {}): OpenLibraryEdition {
+  return {
+    key: '/books/OL456M',
+    title: 'Watchmen',
+    ...overrides,
+  }
+}
+
+describe('normaliseOpenLibrarySearchDoc', () => {
+  it('strips /works/ from the key to derive the id', () => {
+    const record = normaliseOpenLibrarySearchDoc(baseSearchDoc({ key: '/works/OL82563W' }))
+    expect(record.providerId).toBe('OL82563W')
+    expect(record.id).toBe('openlibrary:work:OL82563W')
+  })
+
+  it('splits isbn[] into isbn10/isbn13 by length', () => {
+    const record = normaliseOpenLibrarySearchDoc(
+      baseSearchDoc({ isbn: ['0930289232', '9780930289232'] })
+    )
+    expect(record.identifiers).toMatchObject({ isbn10: '0930289232', isbn13: '9780930289232' })
+  })
+
+  it('leaves isbn10/isbn13 undefined when isbn is absent', () => {
+    const record = normaliseOpenLibrarySearchDoc(baseSearchDoc())
+    expect(record.identifiers?.isbn10).toBeUndefined()
+    expect(record.identifiers?.isbn13).toBeUndefined()
+  })
+
+  it('maps author_name/author_key pairs into creators, stripping /authors/', () => {
+    const record = normaliseOpenLibrarySearchDoc(
+      baseSearchDoc({ author_name: ['Alan Moore'], author_key: ['/authors/OL123A'] })
+    )
+    expect(record.creators).toEqual([{ name: 'Alan Moore', role: 'author', providerId: 'OL123A' }])
+  })
+
+  it('leaves creators undefined when there are no authors', () => {
+    expect(normaliseOpenLibrarySearchDoc(baseSearchDoc()).creators).toBeUndefined()
+  })
+
+  it('builds coverUrl from cover_i using openLibraryCoverUrl', () => {
+    const record = normaliseOpenLibrarySearchDoc(baseSearchDoc({ cover_i: 12345 }))
+    expect(record.coverUrl).toBe(openLibraryCoverUrl(12345))
+  })
+
+  it('leaves coverUrl undefined when cover_i is absent', () => {
+    expect(normaliseOpenLibrarySearchDoc(baseSearchDoc()).coverUrl).toBeUndefined()
+  })
+
+  it('stamps lastSyncedAt as a string', () => {
+    expect(normaliseOpenLibrarySearchDoc(baseSearchDoc()).lastSyncedAt).toEqual(expect.any(String))
+  })
+})
+
+describe('normaliseOpenLibraryWork', () => {
+  it('strips /works/ from the key to derive the id', () => {
+    const record = normaliseOpenLibraryWork(baseWork({ key: '/works/OL82563W' }))
+    expect(record.providerId).toBe('OL82563W')
+    expect(record.id).toBe('openlibrary:work:OL82563W')
+  })
+
+  it('uses the description string directly when it is a string', () => {
+    const record = normaliseOpenLibraryWork(baseWork({ description: 'Plain text description' }))
+    expect(record.description).toBe('Plain text description')
+  })
+
+  it('extracts description.value when description is an object', () => {
+    const record = normaliseOpenLibraryWork(
+      baseWork({ description: { value: 'Wrapped description' } })
+    )
+    expect(record.description).toBe('Wrapped description')
+  })
+
+  it('leaves description undefined when absent', () => {
+    expect(normaliseOpenLibraryWork(baseWork()).description).toBeUndefined()
+  })
+
+  it('builds coverUrl from covers[0]', () => {
+    const record = normaliseOpenLibraryWork(baseWork({ covers: [777, 888] }))
+    expect(record.coverUrl).toBe(openLibraryCoverUrl(777))
+  })
+})
+
+describe('normaliseOpenLibraryEdition', () => {
+  it('strips /books/ from the key to derive the id', () => {
+    const record = normaliseOpenLibraryEdition(baseEdition({ key: '/books/OL456M' }))
+    expect(record.providerId).toBe('OL456M')
+    expect(record.id).toBe('openlibrary:edition:OL456M')
+  })
+
+  it('reads isbn10/isbn13 from the first entries of isbn_10/isbn_13', () => {
+    const record = normaliseOpenLibraryEdition(
+      baseEdition({ isbn_10: ['0930289232'], isbn_13: ['9780930289232', '9999999999999'] })
+    )
+    expect(record.identifiers).toMatchObject({ isbn10: '0930289232', isbn13: '9780930289232' })
+  })
+
+  it('leaves isbn10/isbn13 undefined when absent', () => {
+    const record = normaliseOpenLibraryEdition(baseEdition())
+    expect(record.identifiers?.isbn10).toBeUndefined()
+    expect(record.identifiers?.isbn13).toBeUndefined()
+  })
+
+  it('builds coverUrl from covers[0]', () => {
+    const record = normaliseOpenLibraryEdition(baseEdition({ covers: [111] }))
+    expect(record.coverUrl).toBe(openLibraryCoverUrl(111))
+  })
+
+  it('takes publisher from publishers[0]', () => {
+    const record = normaliseOpenLibraryEdition(baseEdition({ publishers: ['DC Comics', 'Vertigo'] }))
+    expect(record.publisher).toBe('DC Comics')
+  })
+})