Lay the HubSpot and customer-lifecycle foundation

Work in progress from the Codex session, committed so nothing sits undeployed. Verified before committing: typecheck clean across all packages, 139 unit tests and the e2e suite green, migrations apply to an empty Postgres. Adds the HubSpot integration boundary (OAuth, client, contracts, webhook signature verification, sync), a growth route, customer-lifecycle service, Piggy lifecycle tools, a Growth page, and shared lifecycle/hubspot types. Two things are deliberately incomplete and should not be mistaken for finished: `packages/db/src/schema/hubspot.ts` is NOT exported from the schema index, so it is inert — no tables, no migration. That is the correct order (the shape can settle before it becomes a migration), but it does mean the HubSpot routes have no persistence behind them yet. `pnpm-workspace.yaml` and `pnpm-lock.yaml` are left uncommitted on purpose. The workspace file contains a literal unanswered placeholder — "esbuild: set this to true or false" — and this repository installs with npm, which is also what CI runs. Committing a second package manager's lockfile would make the install ambiguous. If the move to pnpm is intended it should be a deliberate change that updates CI and the Dockerfile together. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-13 03:50:18 -07:00
parent d4d7095605
commit 74e37f3e76
20 changed files with 2180 additions and 0 deletions
@@ -0,0 +1,83 @@
+import type { HubSpotObjectType } from '../integrations/hubspot/contracts';
+import { HUBSPOT_OBJECT_TYPES } from '../integrations/hubspot/contracts';
+import { HubSpotOAuthError } from '../integrations/hubspot/oauth';
+import { Hono } from 'hono';
+import { z } from 'zod';
+import { requireCapability } from '../lib/auth';
+import type { ApiEnv } from '../lib/mutation';
+
+const connectionParamSchema = z.string().uuid();
+
+export interface HubSpotConnectionSummary {
+  id: string;
+  portalId: string;
+  displayName: string | null;
+  status: string;
+  grantedScopes: readonly string[];
+  accessTokenExpiresAt: Date;
+  installedAt: Date;
+  lastSyncAt: Date | null;
+  lastError: string | null;
+}
+
+export interface HubSpotRouteService {
+  begin(requestedByUserId: string): Promise<{ authorizationUrl: string }>;
+  complete(code: string, state: string, signal?: AbortSignal): Promise<{ returnPath: string }>;
+  listConnections(): Promise<readonly HubSpotConnectionSummary[]>;
+  enqueueSync(connectionId: string, objectTypes: readonly HubSpotObjectType[], requestedByUserId: string): Promise<{ jobIds: string[] }>;
+}
+
+export function createHubSpotRoutes(service: HubSpotRouteService): Hono<ApiEnv> {
+  const routes = new Hono<ApiEnv>();
+
+  routes.post('/api/integrations/hubspot/oauth/start', async (context) => {
+    const principal = context.get('principal');
+    requireCapability(principal, 'settings:admin');
+    return context.json(await service.begin(principal.userId));
+  });
+
+  routes.get('/api/integrations/hubspot/oauth/callback', async (context) => {
+    const code = context.req.query('code');
+    const state = context.req.query('state');
+    if (!code || !state) {
+      return context.json({ error: 'HubSpot did not return an authorization code and state.' }, 400);
+    }
+    try {
+      const completed = await service.complete(code, state, context.req.raw.signal);
+      return context.redirect(completed.returnPath, 303);
+    } catch (error) {
+      if (error instanceof HubSpotOAuthError) {
+        return context.json({ error: error.message }, 400);
+      }
+      throw error;
+    }
+  });
+
+  routes.get('/api/integrations/hubspot/connections', async (context) => {
+    if (!context.get('principal').scopes.includes('read')) {
+      return context.json({ error: "This credential lacks the 'read' scope." }, 403);
+    }
+    const connections = await service.listConnections();
+    return context.json({
+      connections: connections.map((connection) => ({
+        ...connection,
+        accessTokenExpiresAt: connection.accessTokenExpiresAt.toISOString(),
+        installedAt: connection.installedAt.toISOString(),
+        lastSyncAt: connection.lastSyncAt?.toISOString() ?? null,
+      })),
+    });
+  });
+
+  routes.post('/api/integrations/hubspot/connections/:connectionId/sync', async (context) => {
+    const principal = context.get('principal');
+    requireCapability(principal, 'data:import');
+    const parsedId = connectionParamSchema.safeParse(context.req.param('connectionId'));
+    if (!parsedId.success) return context.json({ error: 'Invalid HubSpot connection ID.' }, 400);
+    return context.json(
+      await service.enqueueSync(parsedId.data, HUBSPOT_OBJECT_TYPES, principal.userId),
+      202,
+    );
+  });
+
+  return routes;
+}