fix(analytics): track CardView events on direct card route

The GET /api/u/card/:cardId endpoint fetched card data without recording
a CardView, bypassing analytics entirely for share-link access.

- publicService.getCardById now accepts viewerId and request params and
  creates a CardView when an authenticated non-owner requests the card
- The /card/:cardId route handler performs soft JWT verification (same
  pattern as /:username and /:username/card/:cardId) to extract viewerId
- Source defaults to link for direct card access, consistent with the
  profile view path; callers may override via ?source= query param
- Owner self-views are excluded to match the existing tracking contract

Closes #495

Author: Ridanshi

apps/backend/src/__tests__/public.test.ts

@@ -39,7 +39,9 @@ const mockPrisma = {
   followLog: {
     findMany: vi.fn().mockResolvedValue([]),
   },
-  card: {} as any,
+  card: {
+    findUnique: vi.fn(),
+  },
 };
 
 // ── Redis mock ────────────────────────────────────────────────────────────────
@@ -464,3 +466,147 @@ describe('GET /api/public/:username/qr-session', () => {
     );
   });
 });
+
+// ─── Direct card view tracking (Issue #495) ───────────────────────────────────
+
+const mockCard = {
+  id: 'card-abc',
+  title: 'My Dev Card',
+  user: {
+    id: 'user-123',
+    username: 'testuser',
+    displayName: 'Test User',
+    bio: null,
+    avatarUrl: null,
+    accentColor: '#ffffff',
+  },
+  cardLinks: [],
+};
+
+describe('GET /api/public/card/:cardId — direct card view tracking', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockRedis.get.mockResolvedValue(null);
+    mockRedis.set.mockResolvedValue('OK');
+    mockPrisma.cardView.create.mockReturnValue({ catch: vi.fn() });
+    mockPrisma.card.findUnique.mockResolvedValue(mockCard);
+  });
+
+  it('returns 200 with correct card shape', async () => {
+    const app = await buildApp();
+    const res = await app.inject({
+      method: 'GET',
+      url: '/api/public/card/card-abc',
+    });
+
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.id).toBe('card-abc');
+    expect(body.title).toBe('My Dev Card');
+    expect(body.owner.username).toBe('testuser');
+    expect(Array.isArray(body.links)).toBe(true);
+  });
+
+  it('returns 404 when card does not exist', async () => {
+    mockPrisma.card.findUnique.mockResolvedValue(null);
+
+    const app = await buildApp();
+    const res = await app.inject({
+      method: 'GET',
+      url: '/api/public/card/nonexistent',
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json().error).toBe('Card not found');
+  });
+
+  it('records CardView when authenticated viewer requests card', async () => {
+    const app = await buildApp();
+
+    // Sign a JWT for a different user (viewer-456 ≠ owner user-123)
+    const token = app.jwt.sign({ id: 'viewer-456' });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: '/api/public/card/card-abc',
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(mockPrisma.cardView.create).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({
+          ownerId: 'user-123',
+          cardId: 'card-abc',
+          viewerId: 'viewer-456',
+        }),
+      }),
+    );
+  });
+
+  it('does not record CardView for anonymous (unauthenticated) request', async () => {
+    const app = await buildApp();
+
+    const res = await app.inject({
+      method: 'GET',
+      url: '/api/public/card/card-abc',
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(mockPrisma.cardView.create).not.toHaveBeenCalled();
+  });
+
+  it('does not record CardView when viewer is the card owner', async () => {
+    const app = await buildApp();
+
+    // Sign JWT as the owner (user-123 === card.user.id)
+    const token = app.jwt.sign({ id: 'user-123' });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: '/api/public/card/card-abc',
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(mockPrisma.cardView.create).not.toHaveBeenCalled();
+  });
+
+  it('uses "link" as default source for direct card views', async () => {
+    const app = await buildApp();
+    const token = app.jwt.sign({ id: 'viewer-456' });
+
+    await app.inject({
+      method: 'GET',
+      url: '/api/public/card/card-abc',
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    expect(mockPrisma.cardView.create).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({
+          source: 'link',
+        }),
+      }),
+    );
+  });
+
+  it('records CardView with custom source query param when provided', async () => {
+    const app = await buildApp();
+    const token = app.jwt.sign({ id: 'viewer-456' });
+
+    await app.inject({
+      method: 'GET',
+      url: '/api/public/card/card-abc?source=web',
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    expect(mockPrisma.cardView.create).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({
+          source: 'web',
+        }),
+      }),
+    );
+  });
+});

apps/backend/src/routes/public.ts

@@ -75,8 +75,18 @@ export async function publicRoutes(app: FastifyInstance): Promise<void> {
   }, async (request: FastifyRequest<{ Params: { cardId: string } }>, reply: FastifyReply) => {
     const { cardId } = request.params;
 
+    let viewerId: string | null = null;
+    try {
+      if (request.headers.authorization) {
+        const decoded = (await request.jwtVerify()) as { id?: string };
+        viewerId = decoded?.id ?? null;
+      }
+    } catch {
+      // ignored
+    }
+
     try {
-      const card = await publicService.getCardById(app, cardId);
+      const card = await publicService.getCardById(app, cardId, viewerId, request);
       if (!card) {
         return reply.status(404).send({ error: 'Card not found' });
       }

apps/backend/src/services/publicService.ts

@@ -47,8 +47,14 @@ export async function getPublicProfile(app: FastifyInstance, username: string, v
   return { cached: false, data: response, cacheKey }
 }
 
-export async function getCardById(app: FastifyInstance, cardId: string) {
+export async function getCardById(app: FastifyInstance, cardId: string, viewerId: string | null, request: any) {
   const card = await app.prisma.card.findUnique({ where: { id: cardId }, include: { user: true, cardLinks: { include: { platformLink: true }, orderBy: { displayOrder: 'asc' } } } })
+  if (!card) { return null }
+
+  if (viewerId && viewerId !== card.user.id) {
+    app.prisma.cardView.create({ data: { ownerId: card.user.id, cardId: card.id, viewerId, viewerIp: request.ip || null, viewerAgent: request.headers['user-agent'] || null, source: request.query?.source || 'link' } }).catch((error: unknown) => app.log.error(`Failed to log view: ${getErrorMessage(error)}`))
+  }
+
   return card
 }