Implement Pixabay video provider

Add API wrapper (pixabay.ts) and strategy class (pixabay-provider.ts) following
the Pexels provider pattern. Register in provider factory and asset provider
factories. Update factory tests to expect PixabayProvider instead of throw.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: 45ck

src/visuals/providers/index.ts

@@ -9,14 +9,17 @@
 
 export * from './types.js';
 export { PexelsProvider } from './pexels-provider.js';
+export { PixabayProvider } from './pixabay-provider.js';
 export { MockVideoProvider } from './mock-provider.js';
 export { NanoBananaProvider } from './nanobanana-provider.js';
 export { LocalProvider } from './local-provider.js';
 export { LocalImageProvider } from './local-image-provider.js';
 export { searchPexels, getPexelsVideo } from './pexels.js';
+export { searchPixabay, getPixabayVideo } from './pixabay.js';
 
 import type { VideoProvider, AssetProvider } from './types.js';
 import { PexelsProvider } from './pexels-provider.js';
+import { PixabayProvider } from './pixabay-provider.js';
 import { MockVideoProvider } from './mock-provider.js';
 import { NanoBananaProvider } from './nanobanana-provider.js';
 import { LocalProvider } from './local-provider.js';
@@ -53,8 +56,7 @@ export function createVideoProvider(name: ProviderName): VideoProvider {
     case 'mock':
       return new MockVideoProvider();
     case 'pixabay':
-      // TODO: Implement Pixabay provider
-      throw new Error('Pixabay provider not yet implemented');
+      return new PixabayProvider();
     default:
       throw new Error(`Unknown provider: ${name}`);
   }
@@ -122,9 +124,7 @@ const assetProviderFactories: Record<AssetProviderName, AssetProviderFactory> =
       recursive: config?.visuals?.local?.recursive,
     }),
 
-  pixabay: () => {
-    throw new Error('Pixabay provider not yet implemented');
-  },
+  pixabay: () => adaptVideoProviderToAssetProvider(new PixabayProvider()),
   dalle: () => {
     throw new Error('DALL-E provider not yet implemented');
   },

src/visuals/providers/pixabay-provider.ts

@@ -0,0 +1,39 @@
+/**
+ * Pixabay Video Provider - Strategy Implementation
+ *
+ * Wraps the Pixabay API in the VideoProvider interface.
+ */
+
+import type { VideoProvider, VideoSearchOptions, VideoSearchResult } from './types.js';
+import { searchPixabay } from './pixabay.js';
+import { getApiKey } from '../../core/config.js';
+
+/** VideoProvider strategy for the Pixabay stock video API. */
+export class PixabayProvider implements VideoProvider {
+  readonly name = 'pixabay';
+
+  search(options: VideoSearchOptions): Promise<VideoSearchResult[]> {
+    return searchPixabay({
+      query: options.query,
+      perPage: options.perPage ?? 5,
+    }).then((videos) =>
+      videos.map((v) => ({
+        id: String(v.id),
+        url: v.url,
+        thumbnailUrl: v.thumbnailUrl,
+        width: v.width,
+        height: v.height,
+        duration: v.duration,
+      }))
+    );
+  }
+
+  isAvailable(): boolean {
+    try {
+      getApiKey('PIXABAY_API_KEY');
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

src/visuals/providers/pixabay.test.ts

@@ -0,0 +1,182 @@
+/**
+ * @file Unit tests for Pixabay API wrapper
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { searchPixabay, getPixabayVideo, getBestVideoUrl, buildSearchUrl } from './pixabay.js';
+import { RateLimitError, APIError, NotFoundError } from '../../core/errors.js';
+
+const MOCK_HIT = {
+  id: 12345,
+  duration: 15,
+  tags: 'nature, forest, trees',
+  videos: {
+    large: {
+      url: 'https://pixabay.com/large.mp4',
+      width: 1920,
+      height: 1080,
+      size: 5000000,
+      thumbnail: 'https://i.vimeocdn.com/large.jpg',
+    },
+    medium: {
+      url: 'https://pixabay.com/medium.mp4',
+      width: 1280,
+      height: 720,
+      size: 2500000,
+      thumbnail: 'https://i.vimeocdn.com/medium.jpg',
+    },
+    small: {
+      url: 'https://pixabay.com/small.mp4',
+      width: 960,
+      height: 540,
+      size: 1200000,
+      thumbnail: 'https://i.vimeocdn.com/small.jpg',
+    },
+    tiny: {
+      url: 'https://pixabay.com/tiny.mp4',
+      width: 640,
+      height: 360,
+      size: 600000,
+      thumbnail: 'https://i.vimeocdn.com/tiny.jpg',
+    },
+  },
+};
+
+const MOCK_RESPONSE = {
+  total: 100,
+  totalHits: 50,
+  hits: [MOCK_HIT],
+};
+
+function jsonResponse(body: unknown, status = 200, headers: Record<string, string> = {}) {
+  return new Response(JSON.stringify(body), {
+    status,
+    statusText: status === 200 ? 'OK' : 'Error',
+    headers: { 'Content-Type': 'application/json', ...headers },
+  });
+}
+
+describe('pixabay API wrapper', () => {
+  const originalKey = process.env.PIXABAY_API_KEY;
+
+  beforeEach(() => {
+    process.env.PIXABAY_API_KEY = 'test-key';
+  });
+
+  afterEach(() => {
+    process.env.PIXABAY_API_KEY = originalKey;
+    vi.restoreAllMocks();
+  });
+
+  describe('buildSearchUrl', () => {
+    it('builds URL with defaults', () => {
+      const url = buildSearchUrl('mykey', { query: 'nature' });
+      expect(url).toContain('https://pixabay.com/api/videos/');
+      expect(url).toContain('key=mykey');
+      expect(url).toContain('q=nature');
+      expect(url).toContain('safesearch=true');
+      expect(url).toContain('per_page=10');
+      expect(url).toContain('page=1');
+    });
+
+    it('respects custom perPage and page', () => {
+      const url = buildSearchUrl('mykey', { query: 'ocean', perPage: 5, page: 3 });
+      expect(url).toContain('per_page=5');
+      expect(url).toContain('page=3');
+    });
+  });
+
+  describe('getBestVideoUrl', () => {
+    it('prefers medium resolution', () => {
+      const result = getBestVideoUrl(MOCK_HIT);
+      expect(result.url).toBe('https://pixabay.com/medium.mp4');
+      expect(result.width).toBe(1280);
+      expect(result.height).toBe(720);
+    });
+
+    it('falls back to large when medium is missing', () => {
+      const hit = { ...MOCK_HIT, videos: { ...MOCK_HIT.videos, medium: undefined } };
+      const result = getBestVideoUrl(hit);
+      expect(result.url).toBe('https://pixabay.com/large.mp4');
+    });
+
+    it('falls back to small when medium and large are missing', () => {
+      const hit = {
+        ...MOCK_HIT,
+        videos: { ...MOCK_HIT.videos, medium: undefined, large: undefined },
+      };
+      const result = getBestVideoUrl(hit);
+      expect(result.url).toBe('https://pixabay.com/small.mp4');
+    });
+
+    it('falls back to tiny as last resort', () => {
+      const hit = { ...MOCK_HIT, videos: { tiny: MOCK_HIT.videos.tiny } };
+      const result = getBestVideoUrl(hit);
+      expect(result.url).toBe('https://pixabay.com/tiny.mp4');
+    });
+
+    it('throws when no video files available', () => {
+      const hit = { ...MOCK_HIT, videos: {} };
+      expect(() => getBestVideoUrl(hit)).toThrow(/no downloadable files/);
+    });
+  });
+
+  describe('searchPixabay', () => {
+    it('maps response to PixabayVideo array', async () => {
+      vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(jsonResponse(MOCK_RESPONSE));
+
+      const results = await searchPixabay({ query: 'nature' });
+      expect(results).toHaveLength(1);
+      expect(results[0]).toEqual({
+        id: 12345,
+        url: 'https://pixabay.com/medium.mp4',
+        thumbnailUrl: 'https://i.vimeocdn.com/small.jpg',
+        duration: 15,
+        width: 1280,
+        height: 720,
+        tags: 'nature, forest, trees',
+      });
+    });
+
+    it('throws RateLimitError on 429', async () => {
+      vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+        jsonResponse({ error: 'rate limited' }, 429)
+      );
+
+      await expect(searchPixabay({ query: 'test' })).rejects.toThrow(RateLimitError);
+    });
+
+    it('throws APIError on non-OK response', async () => {
+      vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+        jsonResponse({ error: 'bad request' }, 400)
+      );
+
+      await expect(searchPixabay({ query: 'test' })).rejects.toThrow(APIError);
+    });
+  });
+
+  describe('getPixabayVideo', () => {
+    it('returns a single video by ID', async () => {
+      vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(jsonResponse(MOCK_RESPONSE));
+
+      const video = await getPixabayVideo(12345);
+      expect(video.id).toBe(12345);
+      expect(video.url).toBe('https://pixabay.com/medium.mp4');
+    });
+
+    it('throws NotFoundError when no hits', async () => {
+      vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+        jsonResponse({ total: 0, totalHits: 0, hits: [] })
+      );
+
+      await expect(getPixabayVideo(99999)).rejects.toThrow(NotFoundError);
+    });
+
+    it('throws RateLimitError on 429', async () => {
+      vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+        jsonResponse({ error: 'rate limited' }, 429)
+      );
+
+      await expect(getPixabayVideo(12345)).rejects.toThrow(RateLimitError);
+    });
+  });
+});