@verbatims/sdk 1.5.0 → 1.6.1

package/src/resources/__tests__/resources.test.ts

@@ -6,6 +6,7 @@ import { ReferencesResource } from '../references'
 import { TagsResource } from '../tags'
 import { CollectionsResource } from '../collections'
 import { SearchResource } from '../search'
+import { ThemesResource } from '../themes'
 
 function mockResponse(data: unknown, status = 200) {
   return new Response(JSON.stringify(data), {
@@ -338,6 +339,205 @@ describe('CollectionsResource', () => {
   })
 })
 
+describe('ThemesResource', () => {
+  let fetchFn: ReturnType<typeof vi.fn>
+  let themes: ThemesResource
+
+  beforeEach(() => {
+    const mock = createMockClient()
+    fetchFn = mock.fetchFn
+    themes = new ThemesResource(mock.client)
+  })
+
+  it('getActive calls GET /themes/active', async () => {
+    fetchFn.mockResolvedValue(mockResponse({
+      success: true,
+      data: { id: 1, slug: 'summer', name: 'Summer', description: null, language: 'en', isActive: true, isDefault: false, scheduledStart: null, scheduledEnd: null, priority: 0, config: null, createdAt: '2024-01-01', updatedAt: '2024-01-01', filters_count: 0 },
+    }))
+
+    const result = await themes.getActive({ language: 'en' })
+    const [url] = fetchFn.mock.calls[0]
+    expect(url).toContain('/themes/active')
+    const parsed = new URL(url, 'http://localhost')
+    expect(parsed.searchParams.get('language')).toBe('en')
+    expect(result.data?.slug).toBe('summer')
+  })
+
+  it('getFeed calls GET /themes/:slug/feed', async () => {
+    fetchFn.mockResolvedValue(mockResponse({
+      success: true,
+      data: { theme: { id: 1, slug: 'summer', name: 'Summer', description: null, language: 'en', isActive: true, isDefault: false, scheduledStart: null, scheduledEnd: null, priority: 0, config: null, createdAt: '2024-01-01', updatedAt: '2024-01-01', filters_count: 0 }, quotes: [], authors: [], references: [], total: 0 },
+    }))
+
+    await themes.getFeed('summer', { language: 'fr' })
+    const [url] = fetchFn.mock.calls[0]
+    expect(url).toContain('/themes/summer/feed')
+    const parsed = new URL(url, 'http://localhost')
+    expect(parsed.searchParams.get('language')).toBe('fr')
+  })
+
+  it('list calls GET /themes with params', async () => {
+    fetchFn.mockResolvedValue(mockResponse({
+      success: true,
+      data: [{ id: 1, slug: 'summer', name: 'Summer', description: null, language: 'en', isActive: true, isDefault: false, scheduledStart: null, scheduledEnd: null, priority: 0, config: null, createdAt: '2024-01-01', updatedAt: '2024-01-01', filters_count: 0 }],
+      pagination: { page: 1, limit: 10, total: 1, totalPages: 1, hasMore: false },
+    }))
+
+    const result = await themes.list({ search: 'summer' })
+    const [url] = fetchFn.mock.calls[0]
+    expect(url).toContain('/themes')
+    const parsed = new URL(url, 'http://localhost')
+    expect(parsed.searchParams.get('search')).toBe('summer')
+    expect(result.data).toHaveLength(1)
+  })
+
+  it('paginate yields themes across pages', async () => {
+    fetchFn
+      .mockResolvedValueOnce(mockResponse({
+        success: true,
+        data: [{ id: 1, slug: 'a', name: 'A', description: null, language: null, isActive: false, isDefault: false, scheduledStart: null, scheduledEnd: null, priority: 0, config: null, createdAt: '2024-01-01', updatedAt: '2024-01-01', filters_count: 0 }],
+        pagination: { page: 1, limit: 1, total: 2, totalPages: 2, hasMore: true },
+      }))
+      .mockResolvedValueOnce(mockResponse({
+        success: true,
+        data: [{ id: 2, slug: 'b', name: 'B', description: null, language: null, isActive: false, isDefault: false, scheduledStart: null, scheduledEnd: null, priority: 0, config: null, createdAt: '2024-01-01', updatedAt: '2024-01-01', filters_count: 0 }],
+        pagination: { page: 2, limit: 1, total: 2, totalPages: 2, hasMore: false },
+      }))
+
+    const results = []
+    for await (const item of themes.paginate()) {
+      results.push(item)
+    }
+    expect(results).toHaveLength(2)
+  })
+
+  it('get calls GET /themes/:id', async () => {
+    fetchFn.mockResolvedValue(mockResponse({
+      success: true,
+      data: { id: 5, slug: 'test', name: 'Test', description: null, language: null, isActive: false, isDefault: false, scheduledStart: null, scheduledEnd: null, priority: 0, config: null, createdAt: '2024-01-01', updatedAt: '2024-01-01', filters_count: 0, filters: [], translations: [] },
+    }))
+
+    await themes.get(5)
+    const [url] = fetchFn.mock.calls[0]
+    expect(url).toContain('/themes/5')
+  })
+
+  it('create calls POST /themes', async () => {
+    fetchFn.mockResolvedValue(mockResponse({
+      success: true,
+      data: { id: 1, slug: 'new-theme', name: 'New Theme', description: null, language: 'en', isActive: false, isDefault: false, scheduledStart: null, scheduledEnd: null, priority: 0, config: null, createdAt: '2024-01-01', updatedAt: '2024-01-01', filters_count: 0 },
+    }))
+
+    await themes.create({ slug: 'new-theme', name: 'New Theme', language: 'en' })
+    const [, opts] = fetchFn.mock.calls[0]
+    expect(opts.method).toBe('POST')
+    expect(JSON.parse(opts.body).slug).toBe('new-theme')
+  })
+
+  it('update calls PUT /themes/:id', async () => {
+    fetchFn.mockResolvedValue(mockResponse({
+      success: true,
+      data: { id: 1, slug: 'updated', name: 'Updated', description: null, language: 'en', isActive: false, isDefault: false, scheduledStart: null, scheduledEnd: null, priority: 5, config: null, createdAt: '2024-01-01', updatedAt: '2024-01-01', filters_count: 0 },
+    }))
+
+    await themes.update(1, { priority: 5 })
+    const [, opts] = fetchFn.mock.calls[0]
+    expect(opts.method).toBe('PUT')
+  })
+
+  it('delete calls DELETE /themes/:id', async () => {
+    fetchFn.mockResolvedValue(mockResponse({ success: true }))
+    await themes.delete(1)
+    const [url, opts] = fetchFn.mock.calls[0]
+    expect(url).toContain('/themes/1')
+    expect(opts.method).toBe('DELETE')
+  })
+
+  it('activate calls PUT /themes/:id/activate', async () => {
+    fetchFn.mockResolvedValue(mockResponse({
+      success: true,
+      data: { id: 1, slug: 'test', name: 'Test', description: null, language: null, isActive: true, isDefault: false, scheduledStart: null, scheduledEnd: null, priority: 0, config: null, createdAt: '2024-01-01', updatedAt: '2024-01-01', filters_count: 0 },
+    }))
+
+    await themes.activate(1, true)
+    const [, opts] = fetchFn.mock.calls[0]
+    expect(opts.method).toBe('PUT')
+    expect(JSON.parse(opts.body)).toEqual({ is_active: true })
+  })
+
+  it('addFilter calls POST /themes/:id/filters', async () => {
+    fetchFn.mockResolvedValue(mockResponse({
+      success: true,
+      data: { id: 10, themeId: 1, type: 'keyword', value: 'test', matchMode: 'any' },
+    }))
+
+    await themes.addFilter(1, { type: 'keyword', value: 'test' })
+    const [, opts] = fetchFn.mock.calls[0]
+    expect(opts.method).toBe('POST')
+    expect(JSON.parse(opts.body)).toEqual({ type: 'keyword', value: 'test' })
+  })
+
+  it('removeFilter calls DELETE /themes/:id/filters/:fid', async () => {
+    fetchFn.mockResolvedValue(mockResponse({ success: true }))
+    await themes.removeFilter(1, 5)
+    const [url, opts] = fetchFn.mock.calls[0]
+    expect(url).toContain('/themes/1/filters/5')
+    expect(opts.method).toBe('DELETE')
+  })
+
+  it('filterSuggestions calls GET /themes/filter-suggestions', async () => {
+    fetchFn.mockResolvedValue(mockResponse({
+      success: true,
+      data: [{ label: 'Test Tag', value: 'test' }],
+    }))
+
+    await themes.filterSuggestions({ q: 'test', type: 'tag_name' })
+    const [url] = fetchFn.mock.calls[0]
+    expect(url).toContain('/themes/filter-suggestions')
+    const parsed = new URL(url, 'http://localhost')
+    expect(parsed.searchParams.get('q')).toBe('test')
+    expect(parsed.searchParams.get('type')).toBe('tag_name')
+  })
+
+  it('filterRecommendations calls POST /themes/filter-recommendations', async () => {
+    fetchFn.mockResolvedValue(mockResponse({
+      success: true,
+      data: [{ type: 'tag', value: 'wisdom', label: 'Wisdom' }],
+    }))
+
+    await themes.filterRecommendations({ name: 'Summer', filters: [{ type: 'keyword', value: 'sun' }] })
+    const [, opts] = fetchFn.mock.calls[0]
+    expect(opts.method).toBe('POST')
+    expect(JSON.parse(opts.body).name).toBe('Summer')
+  })
+
+  it('suggestName calls POST /themes/suggest-name', async () => {
+    fetchFn.mockResolvedValue(mockResponse({
+      success: true,
+      data: { name: 'Summer Vibes', slug: 'summer-vibes', description: 'A summer theme' },
+    }))
+
+    await themes.suggestName('summer')
+    const [, opts] = fetchFn.mock.calls[0]
+    expect(opts.method).toBe('POST')
+    expect(JSON.parse(opts.body).name).toBe('summer')
+  })
+
+  it('suggestions calls GET /themes/suggestions', async () => {
+    fetchFn.mockResolvedValue(mockResponse({
+      success: true,
+      data: [{ type: 'tag', name: 'Summer', slug: 'summer', description: 'Summer theme', color_primary: '#FF0000', color_secondary: '#00FF00', filters: [{ type: 'keyword', value: 'summer', match_mode: 'any' }] }],
+    }))
+
+    await themes.suggestions({ ai: true, tags: 'summer,beach' })
+    const [url] = fetchFn.mock.calls[0]
+    expect(url).toContain('/themes/suggestions')
+    const parsed = new URL(url, 'http://localhost')
+    expect(parsed.searchParams.get('ai')).toBe('true')
+    expect(parsed.searchParams.get('tags')).toBe('summer,beach')
+  })
+})
+
 describe('SearchResource', () => {
   let fetchFn: ReturnType<typeof vi.fn>
   let search: SearchResource

package/src/resources/index.ts

@@ -4,3 +4,4 @@ export { ReferencesResource } from './references'
 export { TagsResource } from './tags'
 export { CollectionsResource } from './collections'
 export { SearchResource } from './search'
+export { ThemesResource } from './themes'

package/src/resources/themes.ts

@@ -0,0 +1,214 @@
+import { z } from 'zod/v4'
+import type { VerbatimsClient } from '../client'
+import { apiResponseSchema } from '../types'
+import { paginate } from '../pagination'
+import type {
+  Theme,
+  ThemeFilter,
+  ThemeSuggestion,
+  ThemeFeed,
+  ThemeWithDetails,
+  ListThemesParams,
+  CreateThemeData,
+  UpdateThemeData,
+  AddFilterData,
+  FilterSuggestion,
+  FilterRecommendationsData,
+  FilterRecommendation,
+  ThemeNameSuggestion,
+  ThemeSuggestionItem,
+  ActiveThemeParams,
+  FeedParams,
+  ThemeSuggestionsQuery,
+} from '../types'
+
+const themeSchema = z.object({
+  id: z.number(),
+  slug: z.string(),
+  name: z.string(),
+  description: z.string().nullable(),
+  language: z.string().nullable(),
+  isActive: z.boolean(),
+  isDefault: z.boolean(),
+  scheduledStart: z.string().nullable(),
+  scheduledEnd: z.string().nullable(),
+  priority: z.number(),
+  config: z.record(z.string(), z.unknown()).nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  filters_count: z.number(),
+  pending_suggestions_count: z.number().optional(),
+})
+
+const themeListResponseSchema = apiResponseSchema(z.array(themeSchema))
+const themeSingleResponseSchema = apiResponseSchema(themeSchema)
+
+const themeFilterSchema = z.object({
+  id: z.number(),
+  themeId: z.number(),
+  type: z.string(),
+  value: z.string(),
+  matchMode: z.enum(['any', 'all']),
+})
+
+const themeSuggestionSchema = z.object({
+  id: z.number(),
+  themeId: z.number(),
+  enrichmentJobId: z.number().nullable(),
+  type: z.enum(['tag', 'author', 'reference']),
+  suggestedValue: z.string(),
+  context: z.string().nullable(),
+  status: z.enum(['pending', 'accepted', 'rejected']),
+  createdBy: z.number().nullable(),
+  reviewedBy: z.number().nullable(),
+  reviewedAt: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+})
+
+const themeFeedSchema = z.object({
+  theme: themeSchema,
+  quotes: z.array(z.object({
+    id: z.number(),
+    name: z.string(),
+    language: z.string(),
+    created_at: z.string(),
+    views_count: z.number(),
+    likes_count: z.number(),
+    updated_at: z.string(),
+    author: z.object({ id: z.number(), name: z.string() }).optional(),
+    reference: z.object({ id: z.number(), name: z.string() }).optional(),
+  })),
+  authors: z.array(z.object({
+    id: z.number(),
+    name: z.string(),
+    job: z.string(),
+    description: z.string(),
+    image_url: z.string(),
+    likes_count: z.number(),
+  })),
+  references: z.array(z.object({
+    id: z.number(),
+    name: z.string(),
+    description: z.string(),
+    primary_type: z.string(),
+    image_url: z.string(),
+    likes_count: z.number(),
+  })),
+  total: z.number(),
+})
+
+type ThemeItem = z.infer<typeof themeSchema>
+
+export class ThemesResource {
+  constructor(private client: VerbatimsClient) {}
+
+  async getActive(params?: ActiveThemeParams) {
+    return this.client.get('/themes/active', { params: params as Record<string, unknown> }, apiResponseSchema(themeSchema.nullable()))
+  }
+
+  async getFeed(slug: string, params?: FeedParams) {
+    return this.client.get(`/themes/${slug}/feed`, { params: params as Record<string, unknown> }, apiResponseSchema(themeFeedSchema.nullable()))
+  }
+
+  async list(params?: ListThemesParams) {
+    return this.client.get('/themes', { params: params as Record<string, unknown> }, themeListResponseSchema)
+  }
+
+  paginate(params?: ListThemesParams): AsyncGenerator<ThemeItem> {
+    return paginate<ThemeItem>((page) =>
+      this.list({ ...params, page }).then(r => ({
+        data: r.data,
+        pagination: r.pagination,
+      }))
+    )
+  }
+
+  async get(id: number) {
+    return this.client.get(`/themes/${id}`, {}, apiResponseSchema(themeSchema.and(z.object({
+      filters: z.array(themeFilterSchema),
+      translations: z.array(z.object({
+        id: z.number(),
+        themeId: z.number(),
+        language: z.string(),
+        name: z.string(),
+        description: z.string().nullable(),
+      })),
+    }))))
+  }
+
+  async create(data: CreateThemeData) {
+    return this.client.post('/themes', data, {}, themeSingleResponseSchema)
+  }
+
+  async update(id: number, data: UpdateThemeData) {
+    return this.client.put(`/themes/${id}`, data, {}, themeSingleResponseSchema)
+  }
+
+  async delete(id: number) {
+    return this.client.delete(`/themes/${id}`, {}, apiResponseSchema(z.undefined()))
+  }
+
+  async activate(id: number, isActive: boolean) {
+    return this.client.put(`/themes/${id}/activate`, { is_active: isActive }, {}, themeSingleResponseSchema)
+  }
+
+  async setDefault(id: number, isDefault: boolean) {
+    return this.client.put(`/themes/${id}/default`, { is_default: isDefault }, {}, themeSingleResponseSchema)
+  }
+
+  async addFilter(id: number, data: AddFilterData) {
+    return this.client.post(`/themes/${id}/filters`, data, {}, apiResponseSchema(themeFilterSchema))
+  }
+
+  async removeFilter(id: number, filterId: number) {
+    return this.client.delete(`/themes/${id}/filters/${filterId}`, {}, apiResponseSchema(z.undefined()))
+  }
+
+  async listSuggestions(id: number) {
+    return this.client.get(`/themes/${id}/suggestions`, {}, apiResponseSchema(z.array(themeSuggestionSchema)))
+  }
+
+  async reviewSuggestion(id: number, suggestionId: number, action: 'accepted' | 'rejected') {
+    return this.client.put(`/themes/${id}/suggestions/${suggestionId}`, { action }, {}, apiResponseSchema(themeSuggestionSchema))
+  }
+
+  async filterSuggestions(params: { q: string; type: string }) {
+    return this.client.get('/themes/filter-suggestions', { params: params as Record<string, unknown> }, apiResponseSchema(z.array(z.object({
+      label: z.string(),
+      value: z.string(),
+    }))))
+  }
+
+  async filterRecommendations(data: FilterRecommendationsData) {
+    return this.client.post('/themes/filter-recommendations', data, {}, apiResponseSchema(z.array(z.object({
+      type: z.string(),
+      value: z.string(),
+      label: z.string(),
+    }))))
+  }
+
+  async suggestName(name: string) {
+    return this.client.post('/themes/suggest-name', { name }, {}, apiResponseSchema(z.object({
+      name: z.string(),
+      slug: z.string(),
+      description: z.string(),
+    })))
+  }
+
+  async suggestions(params?: ThemeSuggestionsQuery) {
+    return this.client.get('/themes/suggestions', { params: params as Record<string, unknown> }, apiResponseSchema(z.array(z.object({
+      type: z.enum(['tag', 'author', 'reference']),
+      name: z.string(),
+      slug: z.string(),
+      description: z.string(),
+      color_primary: z.string(),
+      color_secondary: z.string(),
+      filters: z.array(z.object({
+        type: z.string(),
+        value: z.string(),
+        match_mode: z.literal('any'),
+      })),
+    }))))
+  }
+}

package/src/types.ts

@@ -235,3 +235,186 @@ export interface CreateCollectionData {
   description?: string | null
   is_public?: boolean
 }
+
+// --- Theme types ---
+
+export interface Theme {
+  id: number
+  slug: string
+  name: string
+  description: string | null
+  language: string | null
+  isActive: boolean
+  isDefault: boolean
+  scheduledStart: string | null
+  scheduledEnd: string | null
+  priority: number
+  config: Record<string, unknown> | null
+  createdAt: string
+  updatedAt: string
+  filters_count: number
+  pending_suggestions_count?: number
+}
+
+export interface ThemeFilter {
+  id: number
+  themeId: number
+  type: string
+  value: string
+  matchMode: 'any' | 'all'
+}
+
+export interface ThemeTranslation {
+  id: number
+  themeId: number
+  language: string
+  name: string
+  description: string | null
+}
+
+export interface ThemeSuggestion {
+  id: number
+  themeId: number
+  enrichmentJobId: number | null
+  type: 'tag' | 'author' | 'reference'
+  suggestedValue: string
+  context: string | null
+  status: 'pending' | 'accepted' | 'rejected'
+  createdBy: number | null
+  reviewedBy: number | null
+  reviewedAt: string | null
+  createdAt: string
+  updatedAt: string
+}
+
+export interface ThemeFeedQuote {
+  id: number
+  name: string
+  language: string
+  created_at: string
+  views_count: number
+  likes_count: number
+  updated_at: string
+  author?: { id: number; name: string }
+  reference?: { id: number; name: string }
+}
+
+export interface ThemeFeedAuthor {
+  id: number
+  name: string
+  job: string
+  description: string
+  image_url: string
+  likes_count: number
+}
+
+export interface ThemeFeedReference {
+  id: number
+  name: string
+  description: string
+  primary_type: string
+  image_url: string
+  likes_count: number
+}
+
+export interface ThemeFeed {
+  theme: Theme
+  quotes: ThemeFeedQuote[]
+  authors: ThemeFeedAuthor[]
+  references: ThemeFeedReference[]
+  total: number
+}
+
+export interface ThemeWithDetails extends Theme {
+  filters: ThemeFilter[]
+  translations: ThemeTranslation[]
+}
+
+export interface ListThemesParams {
+  page?: number
+  limit?: number
+  search?: string
+  sort_by?: 'priority' | 'name' | 'slug'
+  sort_order?: 'asc' | 'desc'
+}
+
+export interface CreateThemeData {
+  slug: string
+  name: string
+  description?: string | null
+  language?: string | null
+  translations?: Array<{ language: string; name: string; description?: string | null }>
+  is_active?: boolean
+  is_default?: boolean
+  priority?: number
+  scheduled_start?: string | null
+  scheduled_end?: string | null
+  config?: Record<string, unknown> | null
+}
+
+export interface UpdateThemeData {
+  slug?: string
+  name?: string
+  description?: string | null
+  language?: string | null
+  is_active?: boolean
+  is_default?: boolean
+  priority?: number
+  scheduled_start?: string | null
+  scheduled_end?: string | null
+  config?: Record<string, unknown> | string | null
+  translations?: Array<{ language: string; name: string; description?: string | null }>
+}
+
+export interface AddFilterData {
+  type: string
+  value: string
+  match_mode?: 'any' | 'all'
+}
+
+export interface FilterSuggestion {
+  label: string
+  value: string
+}
+
+export interface FilterRecommendationsData {
+  name?: string
+  filters?: Array<{ type: string; value: string }>
+}
+
+export interface FilterRecommendation {
+  type: string
+  value: string
+  label: string
+}
+
+export interface ThemeNameSuggestion {
+  name: string
+  slug: string
+  description: string
+}
+
+export interface ThemeSuggestionItem {
+  type: 'tag' | 'author' | 'reference'
+  name: string
+  slug: string
+  description: string
+  color_primary: string
+  color_secondary: string
+  filters: Array<{ type: string; value: string; match_mode: 'any' }>
+}
+
+export interface ActiveThemeParams {
+  language?: string
+  theme?: string
+}
+
+export interface FeedParams {
+  language?: string
+}
+
+export interface ThemeSuggestionsQuery {
+  ai?: boolean
+  tags?: string
+  language?: string
+}