sea-dev 1.0.0

package/libs/dal/src/defaults-types.ts

@@ -0,0 +1,23 @@
+import type { UseCase as DbUseCase, FormFieldType } from "@sea/db/schema";
+
+export type DenormField = { name: string; type: FormFieldType; hint?: string; order: number };
+export type DenormGroup = {
+  name: string;
+  hint?: string;
+  order: number;
+  multi?: boolean;
+  fields?: DenormField[];
+};
+export type DenormForm = { name: string; hint: string; groups?: DenormGroup[] };
+export type DenormWorkflow = { name: string; slug: string; hint: string; forms?: DenormForm[] };
+
+export const defaultDeals = [
+  {
+    name: "Test Deal",
+  },
+] as const;
+
+export const unnamedField = "<Unnamed field>";
+
+// NOTE: This type must stay in sync with `UseCase` in `@sea/db/schema`.
+export type UseCase = DbUseCase | null;

package/libs/dal/src/defaults.ts

@@ -0,0 +1,550 @@
+export { defaultDeals, unnamedField } from "./defaults-types";
+export type { DenormField, DenormForm, DenormWorkflow, UseCase } from "./defaults-types";
+
+import { defaultWorkflows as consumerLendingUkWorkflows } from "./defaults-consumer-lending-uk";
+import { defaultWorkflows as consumerLendingUsWorkflows } from "./defaults-consumer-lending-us";
+import { defaultWorkflows as privateCreditWorkflows } from "./defaults-private-credit";
+import { defaultWorkflows as privateEquityWorkflows } from "./defaults-private-equity";
+import { defaultWorkflows as smbLendingUsWorkflows } from "./defaults-smb-lending-us";
+import { defaultWorkflows as smeLendingUkWorkflows } from "./defaults-sme-lending-uk";
+import { defaultWorkflows as smeLendingUkExpressWorkflows } from "./defaults-sme-lending-uk-express";
+import type { DenormWorkflow, UseCase } from "./defaults-types";
+
+/**
+ * ================================================================================================
+ * DEFAULT WORKFLOW STRUCTURE GUIDE
+ * ================================================================================================
+ *
+ * This guide explains how to structure workflow templates for document extraction and data capture.
+ * The templates define what data to extract from documents and how to organize it.
+ *
+ * ================================================================================================
+ * CORE CONCEPTS
+ * ================================================================================================
+ *
+ * 1. WORKFLOW - Top level container (e.g., "Origination", "Underwriting", "Monitoring")
+ *    - Represents a business process stage
+ *    - Contains multiple FORMS
+ *
+ * 2. FORM - Document type or data category (e.g., "Bank Statement", "Income Statement")
+ *    - Represents a specific document or data collection point
+ *    - Contains multiple GROUPS
+ *
+ * 3. GROUP - Logical section within a form (e.g., "Account Information", "Transactions")
+ *    - Organizes related fields together
+ *    - Can be marked as `multi: true` to allow multiple instances (collections)
+ *    - Contains multiple FIELDS
+ *
+ * 4. FIELD - Individual data point (e.g., "BankName", "Revenue", "TransactionDate")
+ *    - Has a type: "string", "money", "number", "date", "string-long"
+ *    - Should always have a descriptive hint
+ *
+ * ================================================================================================
+ * MULTI-PERIOD DATA BEST PRACTICES
+ * ================================================================================================
+ *
+ * When capturing financial data or time-series information, use the MULTI-GROUP pattern:
+ *
+ * ✅ CORRECT PATTERN - Separate static info from repeating periods:
+ *
+ * Form: "Income Statement"
+ *   Group: "Company Information" (order: 0, multi: false)
+ *     - CompanyName
+ *     - CompaniesHouseNumber
+ *   Group: "Financial Periods" (order: 1, multi: true)  ← Multiple periods
+ *     - FinancialPeriodEnd
+ *     - Revenue
+ *     - Expenses
+ *     - Net Income
+ *
+ * ❌ INCORRECT PATTERN - Don't capture only one period:
+ *
+ * Form: "Income Statement"
+ *   Group: "Financial Data" (order: 0)
+ *     - FinancialPeriodEnd  ← Only captures ONE period
+ *     - Revenue
+ *     - Expenses
+ *
+ * WHY? Multi-period capture enables:
+ * - Trend analysis (compare Q1 vs Q2 vs Q3)
+ * - Growth calculations
+ * - Anomaly detection
+ * - Better underwriting decisions
+ *
+ * USE MULTI-GROUP FOR:
+ * ✓ Financial statements (P&L, Balance Sheet, Cash Flow) - capture multiple quarters/years
+ * ✓ Bank statements - capture multiple statement periods
+ * ✓ Transactions - capture all transactions within a statement
+ * ✓ Directors/Officers - capture all directors in a company
+ * ✓ Invoices (Debtors/Creditors ledger) - capture all outstanding invoices
+ * ✓ CCJs/Legal judgements - capture all judgements
+ * ✓ Covenants - capture all covenant tests
+ * ✓ Any time you might have MORE THAN ONE instance of the same data structure
+ *
+ * ================================================================================================
+ * HINT GUIDELINES
+ * ================================================================================================
+ *
+ * EVERY field should have a hint. Good hints:
+ *
+ * 1. EXPLAIN WHAT TO EXTRACT
+ *    ✅ "Total sales revenue for the period (UK term: Turnover)"
+ *    ❌ "Revenue"
+ *
+ * 2. PROVIDE EXAMPLES WHERE HELPFUL
+ *    ✅ "UK bank sort code (e.g., 12-34-56)"
+ *    ✅ "Period covered (e.g., January 2024, Q1 2024, YTD 2024)"
+ *    ❌ "Sort code"
+ *
+ * 3. CLARIFY REGIONAL/DOMAIN TERMINOLOGY
+ *    ✅ "Accounts Payable (UK term: Creditors)"
+ *    ✅ "Inventory (UK term: Stock)"
+ *    ❌ "AP"
+ *
+ * 4. EXPLAIN CALCULATIONS OR RELATIONSHIPS
+ *    ✅ "Gross Profit = Revenue - Cost of Sales"
+ *    ✅ "Leave blank if this is a deposit (not a withdrawal)"
+ *    ❌ "Gross profit"
+ *
+ * 5. PROVIDE BUSINESS CONTEXT FOR METRICS
+ *    ✅ "Cash Conversion Cycle (CCC) - measures days between paying suppliers and collecting from customers. Lower is better."
+ *    ❌ "CCC"
+ *
+ * ================================================================================================
+ * FIELD NAMING CONVENTIONS
+ * ================================================================================================
+ *
+ * - Use PascalCase for field names: "CompanyName", "DateOfBirth", "TotalRevenue"
+ * - Be descriptive but concise: "StatementPeriodStart" not "Start"
+ * - Use standard terminology: "Revenue" not "Sales" (unless region-specific like UK "Turnover")
+ * - Be consistent across forms: if you use "CompaniesHouseNumber" in one form, use it everywhere
+ *
+ * ================================================================================================
+ * ORDERING
+ * ================================================================================================
+ *
+ * - Groups should be ordered logically: static info first, then collections
+ *   Example: "Company Information" (order: 0), then "Financial Periods" (order: 1)
+ *
+ * - Fields should be ordered by importance and logical flow:
+ *   Example in a Bank Statement:
+ *   1. BankName
+ *   2. AccountNumber
+ *   3. StatementPeriodStart
+ *   4. StatementPeriodEnd
+ *   5. OpeningBalance
+ *   6. ClosingBalance
+ *
+ * ================================================================================================
+ * EXAMPLE - SIMPLE DEFAULT WORKFLOW
+ * ================================================================================================
+ *
+ * The workflow below demonstrates these principles with two common forms:
+ * 1. Income Statement - showing multi-period financial data capture
+ * 2. Bank Statement - showing both static account info and repeating transactions
+ */
+
+// Simple default workflow for when useCase is null (skip case)
+const simpleDefaultWorkflows: DenormWorkflow[] = [
+  {
+    // WORKFLOW LEVEL
+    name: "Origination",
+    slug: "origination",
+    hint: "Extract applicant details, loan amounts, business information, contact data",
+    forms: [
+      // FORM 1: Income Statement
+      // Demonstrates: Multi-period financial data capture pattern
+      {
+        name: "Income Statement",
+        hint: "Capture income statement results across reporting periods for financial imports",
+        groups: [
+          // GROUP 1: Static company information (captured once)
+          {
+            name: "General Information",
+            order: 0,
+            // Note: multi is NOT set here - we only need company info once
+            fields: [
+              {
+                name: "CompanyName",
+                type: "string",
+                hint: "Name of the company for which the financials are reported.",
+                order: 0,
+              },
+            ],
+          },
+          // GROUP 2: Financial periods (can capture multiple periods for trend analysis)
+          {
+            name: "Income Statement",
+            order: 1,
+            multi: true, // ← IMPORTANT: Allows capturing multiple financial periods (Q1, Q2, Q3, etc.)
+            fields: [
+              {
+                name: "FinancialPeriod",
+                type: "date",
+                hint: "The relevant financial period end date. Provide the date in UTC (YYYY-MM-DD).",
+                order: 0,
+              },
+              {
+                name: "Revenue",
+                type: "money",
+                hint: "Total income generated from normal business operations. Often referred to as total sales, total income, or turnover.",
+                order: 1,
+              },
+              {
+                name: "COGS",
+                type: "money",
+                hint: "Direct costs of producing goods sold; includes materials and labor. Also called cost of sales.",
+                order: 2,
+              },
+              {
+                name: "Gross Profit",
+                type: "money",
+                hint: "Derived as Revenue − COGS (cost of goods sold). If Revenue and COGS are provided, this can be left blank.",
+                order: 3,
+              },
+              {
+                name: "SG&A",
+                type: "money",
+                hint: "Overhead and operating expenses not tied to production. Can be referred to as overheads, SG&A or Selling, General and Administrative expenses.",
+                order: 4,
+              },
+              {
+                name: "EBIT",
+                type: "money",
+                hint: "Earnings before interest and taxes. Often called operating profit. If not provided, it can be approximated as (Revenue - COGS - SG&A) or (Gross Profit - SG&A).",
+                order: 5,
+              },
+              {
+                name: "EBITDA",
+                type: "money",
+                hint: "Earnings before interest, taxes, depreciation, and amortisation. This shows a company's profitability before non-cash and financing costs. If the value isn't given explicitly, this can be calculated by taking EBIT and adding depreciation and amortisation.",
+                order: 6,
+              },
+              {
+                name: "Net Income",
+                type: "money",
+                hint: "Total profit of the company after all expenses and taxes have been deducted from revenue. Also known as net profit, net earnings, or net result.",
+                order: 7,
+              },
+            ],
+          },
+        ],
+      },
+      // FORM 2: Bank Statement
+      // Demonstrates: Two-level collection pattern (account info + transactions)
+      {
+        name: "Bank Statement",
+        hint: "Extract account balances, transactions, deposits, withdrawals, and cash flow patterns",
+        groups: [
+          // GROUP 1: Static account information (captured once per statement)
+          {
+            name: "Bank Statement",
+            order: 0,
+            // Note: In a more advanced implementation, this could be split into:
+            // - "Account Information" (order: 0, multi: false) for BankName, AccountNumber, etc.
+            // - "Statement Periods" (order: 1, multi: true) for period-specific data
+            // See defaults-sme-lending-uk.ts for an example of this pattern
+            fields: [
+              {
+                name: "BankName",
+                type: "string",
+                order: 0,
+              },
+              {
+                name: "AccountNumber",
+                type: "string",
+                order: 1,
+              },
+              {
+                name: "AccountType",
+                type: "string",
+                order: 2,
+              },
+              {
+                name: "AccountHolderName",
+                type: "string",
+                order: 3,
+              },
+              {
+                name: "StatementPeriodStart",
+                type: "date",
+                order: 4,
+              },
+              {
+                name: "StatementPeriodEnd",
+                type: "date",
+                order: 5,
+              },
+              {
+                name: "OpeningBalance",
+                type: "money",
+                order: 6,
+              },
+              {
+                name: "ClosingBalance",
+                type: "money",
+                order: 7,
+              },
+              {
+                name: "IBAN",
+                type: "string",
+                order: 8,
+              },
+              {
+                name: "Currency",
+                type: "string",
+                order: 9,
+              },
+              {
+                name: "SortCode",
+                type: "string",
+                order: 10,
+              },
+            ],
+          },
+          // GROUP 2: Transactions (can have many transactions per statement)
+          {
+            name: "Transactions",
+            multi: true, // ← IMPORTANT: Each bank statement has multiple transactions
+            order: 1,
+            fields: [
+              {
+                name: "Date",
+                type: "date",
+                order: 0,
+              },
+              {
+                name: "Description",
+                type: "string",
+                order: 1,
+              },
+              {
+                name: "DepositAmount",
+                type: "money",
+                order: 2,
+              },
+              {
+                name: "WithdrawalAmount",
+                type: "money",
+                order: 3,
+              },
+              {
+                name: "Balance",
+                type: "money",
+                order: 4,
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  },
+];
+
+// Legacy export for backward compatibility - returns simple default workflows
+export const defaultWorkflows: DenormWorkflow[] = simpleDefaultWorkflows;
+
+// Get workflows for a specific use case
+export function getWorkflowsForUseCase(useCase: UseCase | null): DenormWorkflow[] {
+  if (!useCase) {
+    return simpleDefaultWorkflows;
+  }
+
+  switch (useCase) {
+    case "sme_lending_uk":
+      return smeLendingUkWorkflows;
+    case "sme_lending_uk_express":
+      return smeLendingUkExpressWorkflows;
+    case "smb_lending_us":
+      return smbLendingUsWorkflows;
+    case "consumer_lending_uk":
+      return consumerLendingUkWorkflows;
+    case "consumer_lending_us":
+      return consumerLendingUsWorkflows;
+    case "private_equity":
+      return privateEquityWorkflows;
+    case "private_credit":
+      return privateCreditWorkflows;
+    default:
+      return simpleDefaultWorkflows;
+  }
+}
+
+// Form mapping for use cases (updated to match new structure without lending-ratios)
+export type UseCaseFormMap = {
+  [key in Exclude<UseCase, null>]?: {
+    [workflowSlug: string]: string[];
+  };
+};
+
+export const useCaseFormMap: UseCaseFormMap = {
+  sme_lending_uk: {
+    origination: [
+      "Investment Memo",
+      "UK P&L",
+      "UK Balance Sheet",
+      "Bank Statement",
+      "Directors & Officers",
+      "Debtors Ledger",
+      "Creditors Ledger",
+      "Cash Flow Statement",
+    ],
+    underwriting: [
+      "UK P&L",
+      "UK Balance Sheet",
+      "Cash Flow Statement",
+      "Debtors Ledger",
+      "Creditors Ledger",
+      "UK Credit Check",
+      "Security & Collateral",
+      "Cash Conversion Ratios",
+    ],
+    monitoring: [
+      "Investment Memo",
+      "Bank Statement",
+      "Directors & Officers",
+      "Covenant Compliance",
+    ],
+  },
+  smb_lending_us: {
+    origination: ["Investment Memo", "Bank Statement", "Principal Owners"],
+    underwriting: [
+      "Income Statement",
+      "Balance Sheet",
+      "Tax Returns",
+      "Credit Bureau",
+      "UCC Filings & Business Registration",
+      "Security & Collateral",
+      "Cash Conversion Ratios",
+    ],
+    monitoring: ["Investment Memo", "Bank Statement", "Principal Owners", "Covenant Compliance"],
+  },
+  consumer_lending_uk: {
+    origination: [
+      "Credit Application",
+      "Personal Financial Statement",
+      "Employment Verification",
+      "Bank Statement",
+    ],
+    underwriting: ["Personal Credit Report", "Security & Collateral"],
+    monitoring: [],
+  },
+  consumer_lending_us: {
+    origination: [
+      "Credit Application",
+      "Personal Financial Statement",
+      "Employment Verification",
+      "Bank Statement",
+    ],
+    underwriting: ["Personal Credit Report", "Security & Collateral"],
+    monitoring: [],
+  },
+  private_equity: {
+    origination: [
+      "Investment Memo",
+      "Income Statement",
+      "Balance Sheet",
+      "Cash Flow Statement",
+      "Sponsor Information",
+    ],
+    monitoring: ["Covenant Compliance"],
+  },
+  private_credit: {
+    origination: [
+      "Investment Memo",
+      "Income Statement",
+      "Balance Sheet",
+      "Cash Flow Statement",
+      "Sponsor Information",
+      "Intercreditor Agreement",
+      "Security & Collateral",
+    ],
+    monitoring: ["Covenant Compliance"],
+  },
+};
+
+// Clone a DenormWorkflow by deeply copying its nested collections (forms → groups → fields).
+// Top-level properties like name/slug/hint are primitives and are safe to spread.
+// If DenormWorkflow gains additional reference-type properties in future, update this helper.
+function cloneWorkflow(workflow: DenormWorkflow): DenormWorkflow {
+  return {
+    ...workflow,
+    forms: workflow.forms?.map((form) => ({
+      ...form,
+      groups: form.groups?.map((group) => ({
+        ...group,
+        fields: group.fields?.map((field) => ({ ...field })),
+      })),
+    })),
+  };
+}
+
+// Filter forms based on use case
+export function filterFormsForUseCase(workflow: DenormWorkflow, useCase: UseCase): DenormWorkflow {
+  if (!useCase) {
+    return workflow;
+  }
+
+  const formMap = useCaseFormMap[useCase];
+  if (!formMap || !workflow.slug) {
+    return workflow;
+  }
+
+  const allowedForms = formMap[workflow.slug];
+  if (!allowedForms) {
+    // If no mapping exists for this workflow slug, return all forms
+    return workflow;
+  }
+
+  // Deep clone to avoid mutating the original
+  const filteredWorkflow = cloneWorkflow(workflow);
+
+  if (filteredWorkflow.forms) {
+    filteredWorkflow.forms = filteredWorkflow.forms.filter((form) =>
+      allowedForms.includes(form.name),
+    );
+  }
+
+  return filteredWorkflow;
+}
+
+// Field customization functions
+export function customizeFieldsForUseCase(
+  workflow: DenormWorkflow,
+  useCase: UseCase,
+): DenormWorkflow {
+  if (!useCase) {
+    return workflow;
+  }
+
+  // Deep clone to avoid mutating the original
+  const customizedWorkflow = cloneWorkflow(workflow);
+
+  if (useCase === "sme_lending_uk" && customizedWorkflow.slug === "origination") {
+    const investmentMemoForm = customizedWorkflow.forms?.find((f) => f.name === "Investment Memo");
+    const borrowerGroup = investmentMemoForm?.groups?.find((g) => g.name === "Borrower Profile");
+    if (borrowerGroup?.fields) {
+      borrowerGroup.fields.push({
+        name: "Companies House Number",
+        type: "string",
+        hint: "Company registration number",
+        order: borrowerGroup.fields.length,
+      });
+    }
+  }
+
+  if (useCase === "smb_lending_us" && customizedWorkflow.slug === "origination") {
+    const investmentMemoForm = customizedWorkflow.forms?.find((f) => f.name === "Investment Memo");
+    const borrowerGroup = investmentMemoForm?.groups?.find((g) => g.name === "Borrower Profile");
+    if (borrowerGroup?.fields) {
+      borrowerGroup.fields.push({
+        name: "EIN",
+        type: "string",
+        hint: "Employer Identification Number",
+        order: borrowerGroup.fields.length,
+      });
+    }
+  }
+
+  return customizedWorkflow;
+}

package/libs/dal/src/document.test.ts

@@ -0,0 +1,70 @@
+import { resetTestDb } from "@/_tests/mock-db"; // Must always be the first import
+
+import { db, schema } from "@sea/db";
+import type { Member } from "@sea/db/types";
+import { beforeEach, describe, expect, it } from "vitest";
+import { getDocument } from "./document";
+
+describe("dbtest: getDocument", () => {
+  beforeEach(async () => {
+    await resetTestDb();
+  });
+
+  it("prevents access to documents from other organizations", async () => {
+    // Create two organizations
+    const [org1, org2] = await db
+      .insert(schema.organization)
+      .values([{ name: "Org 1" }, { name: "Org 2" }])
+      .returning();
+
+    // Create deals for both organizations
+    const [deal1, deal2] = await db
+      .insert(schema.deal)
+      .values([
+        { organizationId: org1!.id, name: "Deal 1 - Org 1" },
+        { organizationId: org2!.id, name: "Deal 1 - Org 2" },
+      ])
+      .returning();
+
+    // Create documents for both workflows
+    const [document1, document2] = await db
+      .insert(schema.document)
+      .values([
+        {
+          dealId: deal1!.id,
+          name: "Document 1",
+          contentType: "application/pdf",
+          blobKey: "key1",
+          blobUrl: "https://example.com/doc1.pdf",
+          blobUrlExpiry: new Date(Date.now() + 3600000), // 1 hour from now
+        },
+        {
+          dealId: deal2!.id,
+          name: "Document 2",
+          contentType: "application/pdf",
+          blobKey: "key2",
+          blobUrl: "https://example.com/doc2.pdf",
+          blobUrlExpiry: new Date(Date.now() + 3600000), // 1 hour from now
+        },
+      ])
+      .returning();
+
+    // Create member for org1
+    const member: Member = {
+      id: "member-1",
+      organizationId: org1!.id,
+      userId: "user-1",
+      role: "member",
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    };
+
+    // Should be able to access document from same organization
+    const result = await getDocument({ member, documentId: document1!.id });
+    expect(result.id).toBe(document1!.id);
+    expect(result.name).toBe("Document 1");
+
+    // Should NOT be able to access document from different organization
+    await expect(getDocument({ member, documentId: document2!.id })).rejects.toThrow();
+  });
+});