sea-dev 1.0.0

package/README.md

@@ -0,0 +1,129 @@
+# sea.dev monorepo
+
+This is a pnpm monorepo, with a few bits of Python on the side.
+
+## Getting started
+
+Docker needs to be running
+
+You will need Node installed. Then you can install pnpm
+
+```bash
+npm install -g pnpm
+```
+
+Here are some of the main commands you will need:
+
+```bash
+# after adding dependencies
+pnpm install
+
+# run format on _all_ packages
+pnpm run -r fmt
+
+# lint only the main app
+pnpm run --filter @sea/main lint
+
+# fmt, lint, check, test all packages
+pnpm run -r all
+
+# build all dependencies of the apps
+pnpm run --filter "{apps/**}^..." build
+
+# run the main app
+pnpm run --filter @sea/main dev
+
+# or cd apps/main and then
+pnpm run dev
+```
+
+## Monorepo Structure
+
+This is a pnpm workspace monorepo organized into applications and shared libraries.
+
+### Applications (`apps/`)
+
+- **`main`** - Main React web application (TanStack Start)
+- **`api`** - REST API service (Fastify)
+- **`workers`** - Hatchet async workers for background jobs
+- **`conversion-worker`** - Document conversion worker
+- **`posthog-proxy`** - PostHog analytics proxy
+
+### Shared Libraries (`libs/`)
+
+**Core Packages:**
+- **`db`** - Database schema & migrations (Drizzle ORM)
+- **`schemas`** - Zod schemas & TypeScript types for API and database
+- **`dal`** - Data Access Layer (database queries and CRUD operations)
+- **`core`** - Core business logic (data extraction, chat, workflows)
+- **`ai`** - AI/LLM integration (agents, tools, prompts)
+
+**Infrastructure & Utilities:**
+- **`clients`** - External service clients (Azure, GCP, Hatchet)
+- **`cache`** - Caching utilities (Upstash Redis)
+- **`config`** - Shared configuration
+- **`util`** - Utility functions
+- **`validators`** - Validation logic
+
+**UI & Presentation:**
+- **`ui`** - React UI components (shadcn/ui)
+- **`widget`** - Embeddable widget (React)
+- **`widget-ng`** - Angular widget (separate codebase)
+
+**Development:**
+- **`lint`** - Shared ESLint/Prettier configuration
+
+### Package Dependency Flow
+
+```
+┌─────────────┐
+│    apps/    │  Applications consume all libraries
+└──────┬──────┘
+       │
+       ▼
+┌─────────────────────────────────────────┐
+│  @sea/core, @sea/ai (Business Logic)    │
+└──────┬──────────────────────────────────┘
+       │
+       ▼
+┌─────────────────────────────────────────┐
+│  @sea/dal (Data Access Layer)           │
+└──────┬──────────────────────────────────┘
+       │
+       ▼
+┌──────┬──────────────────────────────────┐
+│  @sea/db (Database Schema)              │
+│  @sea/schemas (Types & Validation)      │
+└──────┬──────────────────────────────────┘
+       │
+       ▼
+┌─────────────────────────────────────────┐
+│  @sea/util, @sea/config (Foundation)    │
+└─────────────────────────────────────────┘
+```
+
+**Key Principles:**
+- Schemas and types live in `@sea/schemas`
+- Database definitions live in `@sea/db`
+- Database queries live in `@sea/dal`
+- Business logic lives in `@sea/core` or `@sea/ai`
+- UI components are in `@sea/ui` (reusable) or app-specific folders
+
+> **For AI Assistants:** See [CLAUDE.md](./CLAUDE.md) for detailed development guidelines including package responsibilities, type placement, and coding standards.
+
+See `/apps/main/README.md` for detailed setup and development instructions for the React app.
+
+## Environment Variables
+
+The project requires several environment variables to be set in a `.env` file at the root of the project. Key variables include:
+
+### Required for Core Functionality
+- `DATABASE_URL` - PostgreSQL connection string
+- `BETTER_AUTH_SECRET` - Secret for authentication
+- `OPENAI_API_KEY` - OpenAI API key for LLM features
+
+### Analytics (PostHog)
+- `POSTHOG_URL` - PostHog API host (e.g., `https://app.posthog.com` or `https://eu.posthog.com`)
+- `POSTHOG_KEY` - PostHog project API key
+
+See the main `.env` file for a full list of required variables. The `.env` file is gitignored for security.

package/apps/api/.prettierignore

@@ -0,0 +1,6 @@
+dist
+*.gen.ts
+*.md
+.tanstack
+.nitro
+.output

package/apps/api/.prettierrc.js

@@ -0,0 +1,3 @@
+import config from "@sea/lint/prettier";
+
+export default config;

package/apps/api/dotenvx-safe.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+ENV_VARS=$(dotenvx run -- env)
+DATABASE_URL=$(echo "$ENV_VARS" | grep "DATABASE_URL=" | cut -d'=' -f2-)
+
+if [[ "$DATABASE_URL" != *"localhost"* ]]; then
+  echo "DATABASE_URL does not contain 'localhost'. Aborting."
+  exit 1
+fi
+
+exec dotenvx run -- "$@"

package/apps/api/eslint.config.mjs

@@ -0,0 +1,3 @@
+import config from "@sea/lint/eslint";
+
+export default config;

package/apps/api/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@sea/api",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "dotenvx run -- tsx watch src/index.ts | pino-pretty",
+    "build": "vite build",
+    "start": "node dist/index.js",
+    "fmt": "prettier --log-level warn --write .",
+    "lint": "eslint src/",
+    "check": "tsc --noEmit",
+    "test": "IS_TEST=true vitest run",
+    "ci:fmt": "prettier --check .",
+    "ci:lint": "pnpm run lint",
+    "ci:check": "pnpm run check",
+    "all": "pnpm run fmt && pnpm run lint && pnpm run check && pnpm run test"
+  },
+  "dependencies": {
+    "@ai-sdk/openai": "^3.0.1",
+    "@azure/storage-blob": "^12.27.0",
+    "@fastify/cors": "^11.1.0",
+    "@fastify/multipart": "^9.0.3",
+    "@fastify/swagger": "^9.5.1",
+    "@hatchet-dev/typescript-sdk": "^1.9.2",
+    "@posthog/ai": "catalog:",
+    "@scalar/fastify-api-reference": "^1.32.10",
+    "@sea/clients": "workspace:*",
+    "@sea/config": "workspace:*",
+    "@sea/core": "workspace:*",
+    "@sea/db": "workspace:*",
+    "@sea/ai": "workspace:*",
+    "ai": "^6.0.3",
+    "date-fns": "^4.1.0",
+    "drizzle-orm": "^0.43.1",
+    "fastify": "^5.4.0",
+    "fastify-favicon": "^5.0.0",
+    "fastify-type-provider-zod": "^5.0.2",
+    "nanoid": "^5.1.5",
+    "posthog-node": "catalog:",
+    "tsx": "^4.0.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@dotenvx/dotenvx": "^1.42.0",
+    "@sea/dal": "workspace:*",
+    "@sea/lint": "workspace:*",
+    "@sea/schemas": "workspace:*",
+    "@sea/util": "workspace:*",
+    "@types/node": "^22.13.10",
+    "pino-pretty": "^13.0.0",
+    "vite": "^7.1.2",
+    "vitest": "^3.0.8"
+  },
+  "engines": {
+    "node": ">=22.0.0 <23.0.0",
+    "pnpm": ">=10.13.0 <11.0.0"
+  }
+}

package/apps/api/src/clients/posthog.ts

@@ -0,0 +1,25 @@
+import { PostHog } from "posthog-node";
+
+const key = process.env.POSTHOG_KEY;
+const host = process.env.POSTHOG_URL;
+
+export const posthog =
+  key && host ? new PostHog(key, { host, flushAt: 20, flushInterval: 10000 }) : null;
+
+type CaptureArgs = {
+  event: string;
+  distinctId: string;
+  properties?: Record<string, unknown>;
+  groups?: Record<string, string>;
+};
+
+export function captureEvent({ event, distinctId, properties, groups }: CaptureArgs) {
+  if (!posthog) return;
+  try {
+    // Fire-and-forget; do not await PostHog network/flush work
+    void posthog.capture({ event, distinctId, properties, groups });
+  } catch (error) {
+    // PostHog instrumentation should never affect request handling
+    console.error("posthog capture failed", error);
+  }
+}

package/apps/api/src/dal/submission.ts

@@ -0,0 +1,59 @@
+import { db, schema } from "@sea/db";
+import type { Member } from "@sea/db/types";
+import { and, eq, gt, isNull } from "drizzle-orm";
+
+export async function getSubmission({
+  member,
+  submissionId,
+}: {
+  member: Member;
+  submissionId: string;
+}) {
+  const submission = await db.query.submission.findFirst({
+    where: and(
+      eq(schema.submission.id, submissionId),
+      eq(schema.submission.organizationId, member.organizationId),
+      eq(schema.submission.type, "extraction"),
+      isNull(schema.submission.deletedAt),
+    ),
+    with: {
+      extractions: {
+        with: {
+          document: true,
+        },
+      },
+    },
+  });
+
+  return submission;
+}
+
+export async function getSubmissionsForForm({
+  member,
+  formId,
+  afterDate,
+}: {
+  member: Member;
+  formId: string;
+  afterDate: Date;
+}) {
+  const submissions = await db.query.submission.findMany({
+    where: and(
+      eq(schema.submission.organizationId, member.organizationId),
+      eq(schema.submission.formId, formId),
+      eq(schema.submission.type, "extraction"),
+      gt(schema.submission.createdAt, afterDate),
+      isNull(schema.submission.deletedAt),
+    ),
+    with: {
+      extractions: {
+        with: {
+          document: true,
+        },
+      },
+    },
+    orderBy: [schema.submission.createdAt],
+  });
+
+  return submissions;
+}

package/apps/api/src/errors.ts

@@ -0,0 +1,55 @@
+import type { FastifyError } from "fastify";
+
+type HttpErrorParams = {
+  code: string;
+  statusCode: number;
+  message: string;
+  cause?: Error;
+};
+
+export class HttpClientError extends Error implements FastifyError {
+  readonly code: string;
+  readonly statusCode: number;
+  readonly message: string;
+  readonly cause?: Error;
+
+  constructor({ code, statusCode, message, cause }: HttpErrorParams) {
+    super(message, { cause });
+    this.code = code;
+    this.statusCode = statusCode;
+    this.message = message;
+  }
+}
+
+export class UnauthorizedError extends HttpClientError {
+  constructor(message: string, code: string = "UNAUTHORIZED", cause?: Error) {
+    super({
+      code,
+      statusCode: 401,
+      message: `Unauthorized: ${message}`,
+      cause,
+    });
+  }
+}
+
+export class NotFoundError extends HttpClientError {
+  constructor(message: string, cause?: Error) {
+    super({
+      code: "NOT_FOUND",
+      statusCode: 404,
+      message: `Not Found: ${message}`,
+      cause,
+    });
+  }
+}
+
+export class ServerError extends HttpClientError {
+  constructor(message: string, cause?: Error) {
+    super({
+      code: "SERVER_ERROR",
+      statusCode: 500,
+      message,
+      cause,
+    });
+  }
+}

package/apps/api/src/index.ts

@@ -0,0 +1,21 @@
+import { getApiConfig } from "./lib/config";
+import { createServer } from "./server";
+
+const config = getApiConfig();
+const { port } = config;
+
+const start = async () => {
+  const server = await createServer();
+  try {
+    const host = process.env.HOST || "127.0.0.1";
+
+    await server.listen({ port, host });
+    console.log(`Server listening on ${host}:${port}`);
+    console.log(`Scalar at http://${host}:${port}/docs`);
+  } catch (err) {
+    server.log.error(err);
+    process.exit(1);
+  }
+};
+
+start();

package/apps/api/src/lib/channel.ts

@@ -0,0 +1,28 @@
+import type { FastifyRequest } from "fastify";
+
+export const SEA_CHANNEL_HEADER = "x-sea-channel" as const;
+
+export const ALLOWED_CHANNELS = ["api", "web", "embedded"] as const;
+
+export type Channel = (typeof ALLOWED_CHANNELS)[number];
+
+const allowedChannelSet = new Set<string>(ALLOWED_CHANNELS);
+
+const MAX_UNKNOWN_CHANNEL_WARNINGS = 100;
+let unknownChannelWarningCount = 0;
+
+export function getChannel(request: FastifyRequest): Channel {
+  const raw = request.headers[SEA_CHANNEL_HEADER] as string | undefined;
+  if (!raw) return "api";
+
+  const normalized = raw.toLowerCase();
+  if (!allowedChannelSet.has(normalized)) {
+    if (unknownChannelWarningCount < MAX_UNKNOWN_CHANNEL_WARNINGS) {
+      unknownChannelWarningCount += 1;
+      console.warn("Unknown x-sea-channel header value", { raw, normalized });
+    }
+    return "api";
+  }
+
+  return normalized as Channel;
+}

package/apps/api/src/lib/config.ts

@@ -0,0 +1,9 @@
+import { type Config, ConfigFactory } from "@sea/config";
+
+export type ApiConfig = Config & {
+  port: number;
+};
+
+export function getApiConfig() {
+  return { ...ConfigFactory.getConfig(), port: 10000 };
+}

package/apps/api/src/lib/fmt.test.ts

@@ -0,0 +1,9 @@
+import { describe, expect, it } from "vitest";
+import { capitalize } from "./fmt";
+
+describe("capitalize", () => {
+  it("should capitalize a sentence", async () => {
+    const res = capitalize("this is a sentence");
+    expect(res).toEqual("This Is A Sentence");
+  });
+});

package/apps/api/src/lib/fmt.ts

@@ -0,0 +1,62 @@
+import { format, formatISO } from "date-fns";
+
+export function formatFullDate(date: Date) {
+  return format(date, "EEE, d MMM yyyy");
+}
+
+export function formatShortDate(date: Date) {
+  return format(date, "d MMM");
+}
+
+export function formatDay(date: Date) {
+  return format(date, "EEEE"); // Example: Thursday
+}
+
+export function formatMonthYear(date: Date) {
+  return format(date, "MMM yyyy");
+}
+
+export function formatMonthOnly(date: Date) {
+  return format(date, "MMMM");
+}
+
+export function formatISODate(date: Date) {
+  return formatISO(date, { representation: "date" });
+}
+
+export function formatISODateTime(date: Date) {
+  return formatISO(date);
+}
+
+export function formatFullDateTime(date: Date) {
+  return format(date, "EEE, d MMM yyyy 'at' h:mm a");
+}
+
+export function formatTime(time: string | null): string {
+  if (!time) {
+    return "";
+  }
+  return time.slice(0, 5);
+}
+
+export function capitalize(text: string): string {
+  const res = text
+    .split(" ")
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(" ");
+  return res;
+}
+
+export function formatUrl(url: string): string {
+  const trimmedUrl = url.trim();
+  if (trimmedUrl.includes("mailto:")) {
+    return trimmedUrl;
+  }
+  if (/^https?:\/\//i.test(trimmedUrl)) {
+    return trimmedUrl;
+  }
+  if (url.startsWith("/")) {
+    return trimmedUrl;
+  }
+  return `https://${trimmedUrl}`;
+}

package/apps/api/src/lib/invariant.ts

@@ -0,0 +1,23 @@
+import { ServerError } from "@/errors";
+
+const prefix: string = "Invariant failed";
+
+export function hasValue(value: unknown): boolean {
+  if (typeof value === "undefined" || value === null) {
+    return false;
+  }
+  return true;
+}
+
+export function invariant(
+  condition: unknown,
+  message?: string | (() => string),
+): asserts condition {
+  // Note we're using our own definition of truthy...
+  if (condition === true || hasValue(condition)) {
+    return;
+  }
+  const provided: string | undefined = typeof message === "function" ? message() : message;
+  const value: string = provided ? `${prefix}: ${provided}` : prefix;
+  throw new ServerError(value);
+}

package/apps/api/src/middleware/auth.ts

@@ -0,0 +1,66 @@
+import type { Result } from "@/types/result";
+import type { MemberHydrated } from "@sea/dal/member";
+import { db, schema } from "@sea/db";
+import crypto from "crypto";
+import { and, eq, isNull } from "drizzle-orm";
+
+function hashKey(key: string): string {
+  const hash = crypto.createHash("sha256").update(key, "utf8").digest("hex");
+  return hash;
+}
+
+export type AuthResult = { member: MemberHydrated; apiKeyId: string };
+
+export async function authenticateApiKey(
+  authorization: string | undefined,
+): Promise<Result<AuthResult>> {
+  if (!authorization) {
+    return {
+      ok: false,
+      message: "Missing Authorization header",
+      code: "MISSING_AUTH_HEADER",
+    };
+  }
+
+  const [scheme, token] = authorization.split(" ");
+
+  if (scheme !== "Bearer" || !token) {
+    return {
+      ok: false,
+      message: "Invalid Authorization header format. Expected: Bearer <token>",
+      code: "INVALID_AUTH_HEADER",
+    };
+  }
+
+  const keyHash = hashKey(token);
+  const apiKey = await db.query.apiKey.findFirst({
+    where: and(eq(schema.apiKey.keyHash, keyHash), isNull(schema.apiKey.deletedAt)),
+    with: {
+      member: {
+        with: {
+          user: true,
+          organization: true,
+        },
+      },
+    },
+  });
+
+  if (!apiKey) {
+    return {
+      ok: false,
+      message: "Invalid API key",
+      code: "INVALID_API_KEY",
+    };
+  }
+
+  if (apiKey.expiresAt && apiKey.expiresAt < new Date()) {
+    return {
+      ok: false,
+      message: "API key has expired",
+      code: "EXPIRED_API_KEY",
+    };
+  }
+
+  const { member } = apiKey;
+  return { ok: true, data: { member, apiKeyId: apiKey.id } };
+}

package/apps/api/src/routes/index.ts

@@ -0,0 +1,20 @@
+import { UnauthorizedError } from "@/errors";
+import { authenticateApiKey } from "@/middleware/auth";
+import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+import type { ZodTypeProvider } from "fastify-type-provider-zod";
+import { v2Router } from "./v2";
+
+export const router = async <App extends FastifyInstance>(app: App) =>
+  app
+    .addHook("preHandler", async (request: FastifyRequest, _reply: FastifyReply) => {
+      const authorization = request.headers.authorization;
+      const result = await authenticateApiKey(authorization);
+      if (!result.ok) {
+        const { message, code } = result;
+        throw new UnauthorizedError(message, code);
+      }
+      request.member = result.data.member;
+      request.apiKeyId = result.data.apiKeyId;
+    })
+    .withTypeProvider<ZodTypeProvider>()
+    .register(v2Router, { prefix: "/v2" });