feat(sdk): persist last-click attribution on in-app events (SIT-237) (#27)

onamfc · web-flow · commit 24dff3e2f4e1 · 2026-06-08T12:35:42.000-07:00
* feat(sdk): persist last-click attribution on in-app events

Attribute in-app events (screen views + custom events) to the deep link that
drove them, not just the original install link — the basis for re-engagement
and down-funnel reporting (SIT-237).

- in_app_events: add nullable attributed_link_id / attributed_click_id /
  attributed_at / session_id via idempotent startup ALTERs, plus indexes for
  per-link conversion aggregation and per-session screen-flow lookups.
- POST /api/sdk/v1/event accepts and stores the SDK attribution stamp
  (attributedLinkId/attributedClickId/linkOpenedAt/sessionId). Optional and
  backward compatible: older clients omit them; a stale/unknown attributed
  link falls back to a no-link insert so events are never lost.
- Route tests: stamp persistence, backward compat, FK fallback, 404.

Cloud inherits both schema and ingestion via @linkforty/core (initializeDatabase
+ sdkRoutes). Per-workspace windows and windowed aggregation are cloud-side.

* fix(sdk): scope the in-app-event FK fallback to the attributed-link FK only

Address PR review on the last-click attribution insert:
- Narrow the 23503 catch to the attributed_link_id FK (via insertError.constraint).
  A non-link 23503 — e.g. install_id's FK lost to a concurrent install delete —
  now rethrows as a real error instead of being mislabeled "attributed_link_id
  not found" and then re-failing the fallback (which still carries install_id)
  with an uncaught 500.
- Comment the intentional orphaned-click case (fallback keeps attributed_click_id
  with a null link; null link is correct for SIT-261 link-keyed aggregation) and
  the keep-in-sync requirement of the duplicated fallback INSERT.
- Make idx_in_app_events_session a partial index (WHERE session_id IS NOT NULL):
  session_id is null for the legacy/organic majority and screen-flow lookups
  always filter non-null. Done before first creation to avoid a later DROP+CREATE.

Adds a test for the non-link FK rethrow path; FK-fallback test now mocks the
link constraint name. 130 tests green, tsc clean.
diff --git a/src/lib/database.ts b/src/lib/database.ts
@@ -370,6 +370,30 @@ export async function initializeDatabase(options: DatabaseOptions = {}) {
       END $$;
     `);
 
+    // Last-click attribution columns on in_app_events (SIT-237).
+    // Events (screen views + custom events) are attributed to the deep link that
+    // drove them, not just the original install link. The SDK stamps each event
+    // with the active link, when it opened, and the app-open session; the window
+    // (organic vs attributed) is applied at query time. Nullable + backward
+    // compatible: legacy/organic rows stay null and fall back to the install link.
+    await client.query(`
+      DO $$
+      BEGIN
+        IF NOT EXISTS (SELECT 1 FROM information_schema.columns WHERE table_name='in_app_events' AND column_name='attributed_link_id') THEN
+          ALTER TABLE in_app_events ADD COLUMN attributed_link_id UUID REFERENCES links(id) ON DELETE SET NULL;
+        END IF;
+        IF NOT EXISTS (SELECT 1 FROM information_schema.columns WHERE table_name='in_app_events' AND column_name='attributed_click_id') THEN
+          ALTER TABLE in_app_events ADD COLUMN attributed_click_id UUID;
+        END IF;
+        IF NOT EXISTS (SELECT 1 FROM information_schema.columns WHERE table_name='in_app_events' AND column_name='attributed_at') THEN
+          ALTER TABLE in_app_events ADD COLUMN attributed_at TIMESTAMP;
+        END IF;
+        IF NOT EXISTS (SELECT 1 FROM information_schema.columns WHERE table_name='in_app_events' AND column_name='session_id') THEN
+          ALTER TABLE in_app_events ADD COLUMN session_id UUID;
+        END IF;
+      END $$;
+    `);
+
     // Create indexes for performance
     await client.query('CREATE UNIQUE INDEX IF NOT EXISTS idx_links_short_code ON links(short_code)');
     await client.query('CREATE INDEX IF NOT EXISTS idx_links_user_id ON links(user_id)');
@@ -398,6 +422,11 @@ export async function initializeDatabase(options: DatabaseOptions = {}) {
     await client.query('CREATE INDEX IF NOT EXISTS idx_in_app_events_install_id ON in_app_events(install_id)');
     await client.query('CREATE INDEX IF NOT EXISTS idx_in_app_events_name ON in_app_events(event_name)');
     await client.query('CREATE INDEX IF NOT EXISTS idx_in_app_events_timestamp ON in_app_events(event_timestamp DESC)');
+    // Attribution lookups: per-link conversion aggregation + per-session screen flow
+    await client.query('CREATE INDEX IF NOT EXISTS idx_in_app_events_attributed_link ON in_app_events(attributed_link_id, event_timestamp DESC)');
+    // Partial: session_id is null for legacy/organic in-app events (the majority);
+    // per-session screen-flow lookups always filter `session_id IS NOT NULL`.
+    await client.query('CREATE INDEX IF NOT EXISTS idx_in_app_events_session ON in_app_events(session_id) WHERE session_id IS NOT NULL');
 
     // Add deep_link_parameters column for custom deep link parameters
     await client.query(`
diff --git a/src/routes/sdk.event.test.ts b/src/routes/sdk.event.test.ts
@@ -0,0 +1,148 @@
+import { describe, it, expect, beforeEach, vi, type Mock } from 'vitest';
+
+// Mock the database singleton so the route runs without a real Postgres.
+vi.mock('../lib/database.js', () => ({
+  db: { query: vi.fn() },
+}));
+
+import Fastify, { type FastifyInstance } from 'fastify';
+import { db } from '../lib/database.js';
+import { sdkRoutes } from './sdk.js';
+
+const mockQuery = db.query as unknown as Mock;
+
+const INSTALL_ID = '11111111-1111-4111-8111-111111111111';
+const LINK_ID = '22222222-2222-4222-8222-222222222222';
+const SESSION_ID = '33333333-3333-4333-8333-333333333333';
+const CLICK_ID = '44444444-4444-4444-8444-444444444444';
+const EVENT_ID = '55555555-5555-4555-8555-555555555555';
+
+async function buildApp(): Promise<FastifyInstance> {
+  const app = Fastify();
+  await app.register(sdkRoutes);
+  await app.ready();
+  return app;
+}
+
+const EVENT_TS = '2026-06-05T10:05:00.000Z';
+const LINK_OPENED_AT = '2026-06-05T10:00:00.000Z';
+
+const stampedEvent = {
+  installId: INSTALL_ID,
+  eventName: 'add_to_cart',
+  eventData: { sku: 'abc' },
+  timestamp: EVENT_TS,
+  attributedLinkId: LINK_ID,
+  attributedClickId: CLICK_ID,
+  linkOpenedAt: LINK_OPENED_AT,
+  sessionId: SESSION_ID,
+};
+
+describe('POST /api/sdk/v1/event — last-click attribution stamp', () => {
+  beforeEach(() => {
+    mockQuery.mockReset();
+  });
+
+  it('persists the attribution stamp on the in_app_events row', async () => {
+    // 1) install lookup (link_id null so the webhook block is skipped)
+    mockQuery.mockResolvedValueOnce({ rows: [{ id: INSTALL_ID, link_id: null }] });
+    // 2) the event INSERT
+    mockQuery.mockResolvedValueOnce({ rows: [{ id: EVENT_ID }] });
+
+    const app = await buildApp();
+    const res = await app.inject({ method: 'POST', url: '/api/sdk/v1/event', payload: stampedEvent });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toMatchObject({ eventId: EVENT_ID, acknowledged: true });
+
+    const insertCall = mockQuery.mock.calls[1];
+    expect(insertCall[0]).toMatch(/INSERT INTO in_app_events/);
+    expect(insertCall[0]).toMatch(/attributed_link_id/);
+    // params: install, name, dataJson, ts, link, click, openedAt, session
+    expect(insertCall[1]).toEqual([
+      INSTALL_ID,
+      'add_to_cart',
+      JSON.stringify({ sku: 'abc' }),
+      EVENT_TS,
+      LINK_ID,
+      CLICK_ID,
+      LINK_OPENED_AT,
+      SESSION_ID,
+    ]);
+
+    await app.close();
+  });
+
+  it('stays backward compatible: an event with no stamp stores null attribution + a sessionId-less row', async () => {
+    mockQuery.mockResolvedValueOnce({ rows: [{ id: INSTALL_ID, link_id: null }] });
+    mockQuery.mockResolvedValueOnce({ rows: [{ id: EVENT_ID }] });
+
+    const app = await buildApp();
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/sdk/v1/event',
+      payload: { installId: INSTALL_ID, eventName: 'signup' },
+    });
+
+    expect(res.statusCode).toBe(200);
+    const params = mockQuery.mock.calls[1][1];
+    expect(params[4]).toBeNull(); // attributed_link_id
+    expect(params[5]).toBeNull(); // attributed_click_id
+    expect(params[6]).toBeNull(); // attributed_at
+    expect(params[7]).toBeNull(); // session_id
+    await app.close();
+  });
+
+  it('never loses an event when the attributed link is stale: falls back to no-link insert on FK violation', async () => {
+    mockQuery.mockResolvedValueOnce({ rows: [{ id: INSTALL_ID, link_id: null }] });
+    // first INSERT rejects with the attributed_link_id FK violation
+    mockQuery.mockRejectedValueOnce(Object.assign(new Error('FK violation'), { code: '23503', constraint: 'in_app_events_attributed_link_id_fkey' }));
+    // fallback INSERT (without attributed_link_id) succeeds
+    mockQuery.mockResolvedValueOnce({ rows: [{ id: EVENT_ID }] });
+
+    const app = await buildApp();
+    const res = await app.inject({ method: 'POST', url: '/api/sdk/v1/event', payload: stampedEvent });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toMatchObject({ eventId: EVENT_ID, acknowledged: true });
+
+    // the fallback INSERT omits attributed_link_id but keeps click/session
+    const fallbackCall = mockQuery.mock.calls[2];
+    expect(fallbackCall[0]).not.toMatch(/attributed_link_id/);
+    expect(fallbackCall[1]).toEqual([
+      INSTALL_ID,
+      'add_to_cart',
+      JSON.stringify({ sku: 'abc' }),
+      EVENT_TS,
+      CLICK_ID,
+      LINK_OPENED_AT,
+      SESSION_ID,
+    ]);
+
+    await app.close();
+  });
+
+  it('rethrows a non-link FK violation (e.g. install deleted mid-request) instead of mislabeling it as a link problem', async () => {
+    mockQuery.mockResolvedValueOnce({ rows: [{ id: INSTALL_ID, link_id: null }] });
+    // install_id's FK lost to a concurrent install delete — a 23503 that is NOT the link FK
+    mockQuery.mockRejectedValueOnce(Object.assign(new Error('FK violation'), { code: '23503', constraint: 'in_app_events_install_id_fkey' }));
+
+    const app = await buildApp();
+    const res = await app.inject({ method: 'POST', url: '/api/sdk/v1/event', payload: stampedEvent });
+
+    // Surfaces as a real error; no misleading no-link fallback insert is attempted.
+    expect(res.statusCode).toBe(500);
+    expect(mockQuery.mock.calls.length).toBe(2); // install lookup + the failed insert only
+    await app.close();
+  });
+
+  it('returns 404 when the install does not exist', async () => {
+    mockQuery.mockResolvedValueOnce({ rows: [] });
+
+    const app = await buildApp();
+    const res = await app.inject({ method: 'POST', url: '/api/sdk/v1/event', payload: stampedEvent });
+
+    expect(res.statusCode).toBe(404);
+    await app.close();
+  });
+});
diff --git a/src/routes/sdk.ts b/src/routes/sdk.ts
@@ -210,6 +210,12 @@ export async function sdkRoutes(fastify: FastifyInstance) {
    * - eventData: Optional JSON data associated with the event
    * - timestamp: Optional event timestamp (defaults to now)
    *
+   * Last-click attribution stamp (SIT-237, all optional / backward compatible):
+   * - attributedLinkId: UUID of the deep link currently credited (last-click)
+   * - attributedClickId: UUID of the originating click, when known
+   * - linkOpenedAt: ISO timestamp of when that deep link opened the app
+   * - sessionId: UUID identifying the app-open session (for screen-flow grouping)
+   *
    * Response:
    * - eventId: UUID of the tracked event
    * - acknowledged: Boolean confirmation
@@ -220,6 +226,10 @@ export async function sdkRoutes(fastify: FastifyInstance) {
       eventName: z.string(),
       eventData: z.record(z.any()).optional(),
       timestamp: z.string().datetime().optional(),
+      attributedLinkId: z.string().uuid().optional(),
+      attributedClickId: z.string().uuid().optional(),
+      linkOpenedAt: z.string().datetime().optional(),
+      sessionId: z.string().uuid().optional(),
     });
 
     const body = schema.parse(request.body);
@@ -239,19 +249,66 @@ export async function sdkRoutes(fastify: FastifyInstance) {
 
       const install = installCheck.rows[0];
       const eventTimestamp = body.timestamp || new Date().toISOString();
+      const eventDataJson = JSON.stringify(body.eventData || {});
 
-      // Insert event into in_app_events table
-      const eventResult = await db.query(
-        `INSERT INTO in_app_events (install_id, event_name, event_data, event_timestamp)
-         VALUES ($1, $2, $3, $4)
-         RETURNING id`,
-        [
-          body.installId,
-          body.eventName,
-          JSON.stringify(body.eventData || {}),
-          eventTimestamp,
-        ]
-      );
+      // Insert event with the last-click attribution stamp. The attributing link
+      // may differ from the install link (re-engagement) or be absent (organic).
+      let eventResult;
+      try {
+        eventResult = await db.query(
+          `INSERT INTO in_app_events
+             (install_id, event_name, event_data, event_timestamp,
+              attributed_link_id, attributed_click_id, attributed_at, session_id)
+           VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+           RETURNING id`,
+          [
+            body.installId,
+            body.eventName,
+            eventDataJson,
+            eventTimestamp,
+            body.attributedLinkId ?? null,
+            body.attributedClickId ?? null,
+            body.linkOpenedAt ?? null,
+            body.sessionId ?? null,
+          ]
+        );
+      } catch (insertError: any) {
+        // Only a stale/unknown *attributed link* FK is recoverable here: record
+        // the event without link attribution rather than losing it. Any other
+        // 23503 — e.g. install_id's FK lost to a concurrent install delete — is a
+        // real error that must surface, not be mislabeled as a link problem.
+        const isLinkFk =
+          insertError?.code === '23503' &&
+          String(insertError?.constraint ?? '').includes('attributed_link_id');
+        if (isLinkFk) {
+          fastify.log.warn(
+            `attributed_link_id ${body.attributedLinkId} not found; storing event without link attribution`
+          );
+          // Keep this column list in sync with the primary INSERT above (it just
+          // omits attributed_link_id). attributed_click_id is intentionally kept
+          // without a link: the orphaned-click case is expected, and a null
+          // attributed_link_id is the correct value for link-keyed aggregation
+          // (the SIT-261 consumer must not read it as a data bug).
+          eventResult = await db.query(
+            `INSERT INTO in_app_events
+               (install_id, event_name, event_data, event_timestamp,
+                attributed_click_id, attributed_at, session_id)
+             VALUES ($1, $2, $3, $4, $5, $6, $7)
+             RETURNING id`,
+            [
+              body.installId,
+              body.eventName,
+              eventDataJson,
+              eventTimestamp,
+              body.attributedClickId ?? null,
+              body.linkOpenedAt ?? null,
+              body.sessionId ?? null,
+            ]
+          );
+        } else {
+          throw insertError;
+        }
+      }
 
       const eventId = eventResult.rows[0].id;
 
