feat(search): resolve AT Protocol handles in search (#85)

* feat(search): add AT Protocol handle resolution fallback

When the local DB returns no results for a search query, try to resolve
the query as an AT Protocol handle via the Bluesky public API. Results
from the DB get `claimed: true`; network-resolved profiles that aren't
already in DB results are appended with `claimed: false`. Short queries
without dots also try {query}.bsky.social. Resolution failures are
silently swallowed so DB results always return.

* style: fix Prettier formatting

src/routes/search.ts

···
 import type { FastifyInstance } from 'fastify';
 import type { Database } from '../db/index.js';
 import { sql } from 'drizzle-orm';
+import { resolveHandleFromNetwork } from '../services/handle-resolver.js';
+import { logger } from '../logger.js';
 
 export function registerSearchRoutes(app: FastifyInstance, db: Database) {
   app.get('/api/search/profiles', async (request, reply) => {
···
       LIMIT ${limitNum} OFFSET ${offsetNum}
     `);
 
-    return {
-      profiles: results.rows.map((row) => {
-        const r = row as Record<string, unknown>;
-        const profile: Record<string, unknown> = {
-          did: r.did,
-          handle: r.handle,
-          headline: r.headline,
-          about: r.about,
-        };
-        if (r.displayName != null) profile.displayName = r.displayName;
-        if (r.avatarUrl != null) profile.avatar = r.avatarUrl;
-        if (r.currentRole != null) profile.currentRole = r.currentRole;
-        if (r.currentCompany != null) profile.currentCompany = r.currentCompany;
-        return profile;
-      }),
-    };
+    const dbProfiles = results.rows.map((row) => {
+      const r = row as Record<string, unknown>;
+      const profile: Record<string, unknown> = {
+        did: r.did,
+        handle: r.handle,
+        headline: r.headline,
+        about: r.about,
+        claimed: true,
+      };
+      if (r.displayName != null) profile.displayName = r.displayName;
+      if (r.avatarUrl != null) profile.avatar = r.avatarUrl;
+      if (r.currentRole != null) profile.currentRole = r.currentRole;
+      if (r.currentCompany != null) profile.currentCompany = r.currentCompany;
+      return profile;
+    });
+
+    // Try AT Protocol handle resolution as fallback
+    try {
+      const resolved = await resolveHandleFromNetwork(q.trim());
+      if (resolved) {
+        const alreadyInResults = dbProfiles.some((p) => p.did === resolved.did);
+        if (!alreadyInResults) {
+          const networkProfile: Record<string, unknown> = {
+            did: resolved.did,
+            handle: resolved.handle,
+            about: resolved.about,
+            claimed: false,
+          };
+          if (resolved.displayName != null) networkProfile.displayName = resolved.displayName;
+          if (resolved.avatar != null) networkProfile.avatar = resolved.avatar;
+          dbProfiles.push(networkProfile);
+        }
+      }
+    } catch (err) {
+      logger.debug({ err, query: q }, 'Handle resolution fallback failed');
+    }
+
+    return { profiles: dbProfiles };
   });
 }

src/services/handle-resolver.ts

···
+import { isValidHandle } from '@atproto/syntax';
+import { Agent } from '@atproto/api';
+import { logger } from '../logger.js';
+
+export interface ResolvedProfile {
+  did: string;
+  handle: string;
+  displayName: string | undefined;
+  avatar: string | undefined;
+  about: string | undefined;
+}
+
+const SIMPLE_HANDLE_RE = /^[a-zA-Z0-9-]+$/;
+const publicAgent = new Agent('https://public.api.bsky.app');
+
+export async function resolveHandleFromNetwork(query: string): Promise<ResolvedProfile | null> {
+  const candidates: string[] = [];
+
+  if (isValidHandle(query)) {
+    candidates.push(query);
+  }
+
+  // If no dots and looks like a simple username, also try .bsky.social
+  if (SIMPLE_HANDLE_RE.test(query) && !query.includes('.')) {
+    const bskySocial = `${query}.bsky.social`;
+    if (isValidHandle(bskySocial) && !candidates.includes(bskySocial)) {
+      candidates.push(bskySocial);
+    }
+  }
+
+  for (const handle of candidates) {
+    try {
+      const response = await publicAgent.getProfile(
+        { actor: handle },
+        { signal: AbortSignal.timeout(3000) },
+      );
+      return {
+        did: response.data.did,
+        handle: response.data.handle,
+        displayName: response.data.displayName || undefined,
+        avatar: response.data.avatar || undefined,
+        about: response.data.description || undefined,
+      };
+    } catch (err) {
+      logger.debug({ handle, err }, 'Handle resolution failed');
+    }
+  }
+
+  return null;
+}

tests/routes/search.test.ts

···
-import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { describe, it, expect, beforeAll, afterAll, vi, beforeEach } from 'vitest';
 import { buildServer } from '../../src/server.js';
 import { createDb } from '../../src/db/index.js';
 import { profiles, positions } from '../../src/db/schema/index.js';
···
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import type { FastifyInstance } from 'fastify';
+
+vi.mock('../../src/services/handle-resolver.js', () => ({
+  resolveHandleFromNetwork: vi.fn().mockResolvedValue(null),
+}));
 
 describe('Search API', () => {
   let app: FastifyInstance;
···
     for (const profile of body.profiles) {
       expect(profile.rank).toBeUndefined();
     }
+  });
+
+  it('DB results include claimed: true', async () => {
+    const res = await app.inject({ method: 'GET', url: '/api/search/profiles?q=TypeScript' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.profiles.length).toBeGreaterThanOrEqual(1);
+    for (const profile of body.profiles) {
+      expect(profile.claimed).toBe(true);
+    }
+  });
+
+  describe('AT Protocol handle resolution fallback', () => {
+    let handleResolverMock: typeof import('../../src/services/handle-resolver.js');
+
+    beforeEach(async () => {
+      handleResolverMock = await import('../../src/services/handle-resolver.js');
+      vi.mocked(handleResolverMock.resolveHandleFromNetwork).mockReset();
+      vi.mocked(handleResolverMock.resolveHandleFromNetwork).mockResolvedValue(null);
+    });
+
+    it('resolves AT Protocol handle when DB has no results and returns claimed: false', async () => {
+      vi.mocked(handleResolverMock.resolveHandleFromNetwork).mockResolvedValue({
+        did: 'did:plc:network-resolved',
+        handle: 'networkuser.bsky.social',
+        displayName: 'Network User',
+        avatar: 'https://cdn.bsky.app/img/avatar/network.jpg',
+        about: 'Found via network',
+      });
+
+      const res = await app.inject({
+        method: 'GET',
+        url: '/api/search/profiles?q=networkuser.bsky.social',
+      });
+      expect(res.statusCode).toBe(200);
+      const body = res.json();
+      expect(body.profiles.length).toBe(1);
+      const profile = body.profiles[0];
+      expect(profile.did).toBe('did:plc:network-resolved');
+      expect(profile.handle).toBe('networkuser.bsky.social');
+      expect(profile.displayName).toBe('Network User');
+      expect(profile.avatar).toBe('https://cdn.bsky.app/img/avatar/network.jpg');
+      expect(profile.about).toBe('Found via network');
+      expect(profile.claimed).toBe(false);
+    });
+
+    it('returns empty when handle resolution also fails', async () => {
+      vi.mocked(handleResolverMock.resolveHandleFromNetwork).mockResolvedValue(null);
+
+      const res = await app.inject({
+        method: 'GET',
+        url: '/api/search/profiles?q=doesnotexist.bsky.social',
+      });
+      expect(res.statusCode).toBe(200);
+      expect(res.json().profiles).toHaveLength(0);
+    });
+
+    it('short queries without dots get .bsky.social appended via resolver', async () => {
+      vi.mocked(handleResolverMock.resolveHandleFromNetwork).mockResolvedValue({
+        did: 'did:plc:short-handle',
+        handle: 'shortname.bsky.social',
+        displayName: 'Short Name',
+        avatar: undefined,
+        about: undefined,
+      });
+
+      const res = await app.inject({
+        method: 'GET',
+        url: '/api/search/profiles?q=shortname',
+      });
+      expect(res.statusCode).toBe(200);
+      const body = res.json();
+      // The resolver was called with the query; it handles .bsky.social appending internally
+      expect(vi.mocked(handleResolverMock.resolveHandleFromNetwork)).toHaveBeenCalledWith(
+        'shortname',
+      );
+      const profile = body.profiles.find((p: { did: string }) => p.did === 'did:plc:short-handle');
+      expect(profile).toBeDefined();
+      expect(profile.claimed).toBe(false);
+    });
+
+    it('does not duplicate when handle resolves to DID already in DB', async () => {
+      vi.mocked(handleResolverMock.resolveHandleFromNetwork).mockResolvedValue({
+        did: 'did:plc:search-test',
+        handle: 'searchtest.bsky.social',
+        displayName: 'Alice Wonderland',
+        avatar: 'https://cdn.bsky.app/img/avatar/did:plc:search-test/test.jpg',
+        about: 'Building distributed systems',
+      });
+
+      const res = await app.inject({
+        method: 'GET',
+        url: '/api/search/profiles?q=TypeScript',
+      });
+      expect(res.statusCode).toBe(200);
+      const body = res.json();
+      const aliceResults = body.profiles.filter(
+        (p: { did: string }) => p.did === 'did:plc:search-test',
+      );
+      expect(aliceResults).toHaveLength(1);
+      expect(aliceResults[0].claimed).toBe(true);
+    });
+
+    it('silently returns DB results when resolution throws', async () => {
+      vi.mocked(handleResolverMock.resolveHandleFromNetwork).mockRejectedValue(
+        new Error('Network error'),
+      );
+
+      const res = await app.inject({
+        method: 'GET',
+        url: '/api/search/profiles?q=TypeScript',
+      });
+      expect(res.statusCode).toBe(200);
+      const body = res.json();
+      expect(body.profiles.length).toBeGreaterThanOrEqual(1);
+    });
   });
 });