financial-graph-shared 1.0.0

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "financial-graph-shared",
+  "version": "1.0.0",
+  "description": "Shared types, schema, and utilities for financial-graph",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./types": "./dist/types/types.js",
+    "./schema": "./dist/types/schema.js",
+    "./validation": "./dist/types/validation.js",
+    "./composite-keys": "./dist/types/composite-keys.js",
+    "./ids": "./dist/types/ids.js",
+    "./db": {
+      "types": "./dist/db/index.d.ts",
+      "default": "./dist/db/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "clean": "rm -rf dist",
+    "test": "bun run build && bun test tests/",
+    "test:watch": "bun test --watch tests/",
+    "test:only": "bun test tests/",
+    "schema:push": "bunx instant-cli@latest push schema"
+  },
+  "keywords": ["types", "schema", "instantdb"],
+  "author": "",
+  "license": "ISC",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "dependencies": {
+    "@instantdb/core": "^0.22.96",
+    "fast-check": "^4.5.3",
+    "uuid": "^13.0.0",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.5",
+    "@types/node": "^25.0.3",
+    "@types/uuid": "^11.0.0",
+    "typescript": "^5.9.3"
+  },
+  "files": [
+    "dist",
+    "types"
+  ]
+}

package/types/ids.ts

@@ -0,0 +1,249 @@
+/**
+ * Deterministic ID Generation for InstantDB
+ *
+ * Benefits:
+ * - Deterministic: Same input always produces the same UUID
+ * - Idempotent: Upserts with identical data update the same record
+ * - No redundancy: No need for separate composite_key column
+ * - Compatible: UUID v5 format works with InstantDB's ID requirements
+ */
+
+import { v5 as uuidv5 } from 'uuid';
+import { 
+  CompanyType, 
+  type CompanyIdentity,
+  PublicCompanySchema,
+  IssuerCompanySchema,
+  PrivateCompanySchema,
+  UnknownCompanySchema,
+  AccessionNumberString,
+  ParentOfParamsSchema,
+  SubsidiaryEnrichmentParamsSchema,
+  BusinessSegmentParamsSchema,
+  BrandParamsSchema,
+  OwnsParamsSchema,
+} from './types';
+
+/**
+ * Namespace UUIDs for each entity type.
+ * These are used with UUID v5 to generate deterministic IDs.
+ * Each namespace ensures IDs are unique within their entity type.
+ */
+export const NAMESPACES = {
+  /** Namespace for company entity IDs */
+  COMPANY: '6ba7b810-9dad-11d1-80b4-00c04fd430c8',
+  /** Namespace for filing entity IDs */
+  FILING: '6ba7b811-9dad-11d1-80b4-00c04fd430c8',
+  /** Namespace for parent_of relationship IDs */
+  PARENT_OF: '6ba7b812-9dad-11d1-80b4-00c04fd430c8',
+  /** Namespace for subsidiary_enrichment entity IDs */
+  SUBSIDIARY_ENRICHMENT: '6ba7b813-9dad-11d1-80b4-00c04fd430c8',
+  /** Namespace for business_segment entity IDs */
+  BUSINESS_SEGMENT: '6ba7b814-9dad-11d1-80b4-00c04fd430c8',
+  /** Namespace for brand entity IDs */
+  BRAND: '6ba7b815-9dad-11d1-80b4-00c04fd430c8',
+  /** Namespace for owns relationship IDs */
+  OWNS: '6ba7b816-9dad-11d1-80b4-00c04fd430c8',
+  /** Namespace for company_info entity IDs */
+  COMPANY_INFO: '6ba7b817-9dad-11d1-80b4-00c04fd430c8',
+} as const;
+
+export type NamespaceKey = keyof typeof NAMESPACES;
+
+// ============================================================================
+// COMPANY ID GENERATION
+// ============================================================================
+
+/**
+ * Company data required for ID generation
+ */
+export interface CompanyIdInput {
+  type: number;
+  name?: string;
+  jurisdiction_raw?: string;
+  identity?: CompanyIdentity;
+}
+
+/**
+ * Generate a deterministic UUID v5 ID for a company.
+ * @param company - Company data with type and required fields
+ * @returns UUID v5 string
+ */
+export function generateCompanyId(company: CompanyIdInput): string {
+  switch (company.type) {
+    case CompanyType.PUBLIC: {
+      const validated = PublicCompanySchema.parse(company);
+      return uuidv5(`${company.type}:${validated.identity.primaryCIK}`, NAMESPACES.COMPANY);
+    }
+
+    case CompanyType.ISSUER: {
+      const validated = IssuerCompanySchema.parse(company);
+      return uuidv5(`${company.type}:${validated.identity.primaryCIK}`, NAMESPACES.COMPANY);
+    }
+
+    case CompanyType.PRIVATE: {
+      const validated = PrivateCompanySchema.parse(company);
+      const normalizedName = validated.name.trim().toLowerCase();
+      const normalizedJurisdiction = validated.jurisdiction_raw.trim().toLowerCase();
+      return uuidv5(`${company.type}:${normalizedName}:${normalizedJurisdiction}`, NAMESPACES.COMPANY);
+    }
+
+    default: {
+      const validated = UnknownCompanySchema.parse(company);
+      const normalizedName = validated.name.trim().toLowerCase();
+      const normalizedJurisdiction = validated.jurisdiction_raw?.trim().toLowerCase() || '';
+      const compositeString = normalizedJurisdiction
+        ? `${company.type}:${normalizedName}:${normalizedJurisdiction}`
+        : `${company.type}:${normalizedName}`;
+      return uuidv5(compositeString, NAMESPACES.COMPANY);
+    }
+  }
+}
+
+// ============================================================================
+// FILING ID GENERATION
+// ============================================================================
+
+/**
+ * Generate a deterministic UUID v5 ID for a filing.
+ * 
+ * @param accessionNumber - SEC accession number (e.g., "0001193125-24-123456" or "0001193125241234567")
+ * @returns UUID v5 string
+ * @throws ZodError if accession number is invalid
+ * 
+ * @example
+ * generateFilingId("0001193125-24-123456") // Returns UUID v5
+ * generateFilingId("0001193125241234567")  // Returns same UUID v5 (normalized)
+ */
+export function generateFilingId(accessionNumber: string): string {
+  const normalized = AccessionNumberString.parse(accessionNumber);
+  return uuidv5(normalized, NAMESPACES.FILING);
+}
+
+// ============================================================================
+// RELATIONSHIP ENTITY ID GENERATION
+// ============================================================================
+
+/**
+ * Generate a deterministic UUID v5 ID for a parent_of relationship.
+ * 
+ * @param parentId - UUID of the parent company
+ * @param subsidiaryId - UUID of the subsidiary company
+ * @returns UUID v5 string
+ * @throws ZodError if parentId or subsidiaryId is empty
+ * 
+ * @example
+ * generateParentOfId("parent-uuid", "subsidiary-uuid")
+ */
+export function generateParentOfId(
+  parentId: string,
+  subsidiaryId: string
+): string {
+  ParentOfParamsSchema.parse({ parentId, subsidiaryId });
+  const compositeString = `${parentId}:${subsidiaryId}`;
+  return uuidv5(compositeString, NAMESPACES.PARENT_OF);
+}
+
+/**
+ * Generate a deterministic UUID v5 ID for a subsidiary_enrichment.
+ * 
+ * @param companyId - UUID of the company
+ * @param filingId - UUID of the filing
+ * @returns UUID v5 string
+ * @throws ZodError if companyId or filingId is empty
+ * 
+ * @example
+ * generateSubsidiaryEnrichmentId("company-uuid", "filing-uuid")
+ */
+export function generateSubsidiaryEnrichmentId(
+  companyId: string,
+  filingId: string
+): string {
+  SubsidiaryEnrichmentParamsSchema.parse({ companyId, filingId });
+  const compositeString = `${companyId}:${filingId}`;
+  return uuidv5(compositeString, NAMESPACES.SUBSIDIARY_ENRICHMENT);
+}
+
+/**
+ * Generate a deterministic UUID v5 ID for an owns relationship.
+ * 
+ * @param companyId - UUID of the owning company
+ * @param brandId - UUID of the brand
+ * @returns UUID v5 string
+ * @throws ZodError if companyId or brandId is empty
+ * 
+ * @example
+ * generateOwnsId("company-uuid", "brand-uuid")
+ */
+export function generateOwnsId(
+  companyId: string,
+  brandId: string
+): string {
+  OwnsParamsSchema.parse({ companyId, brandId });
+  const compositeString = `${companyId}:${brandId}`;
+  return uuidv5(compositeString, NAMESPACES.OWNS);
+}
+
+/**
+ * Generate a deterministic UUID v5 ID for a business_segment.
+ * 
+ * @param companyId - UUID of the company
+ * @param segmentName - Name of the business segment
+ * @param fiscalYear - Fiscal year (integer)
+ * @param fiscalQuarter - Fiscal quarter (1-4) or null for annual
+ * @returns UUID v5 string
+ * @throws ZodError if required fields are invalid
+ * 
+ * @example
+ * generateBusinessSegmentId("company-uuid", "Cloud Services", 2024, 1)
+ * generateBusinessSegmentId("company-uuid", "Cloud Services", 2024, null) // Annual
+ */
+export function generateBusinessSegmentId(
+  companyId: string,
+  segmentName: string,
+  fiscalYear: number,
+  fiscalQuarter: number | null
+): string {
+  BusinessSegmentParamsSchema.parse({ companyId, segmentName, fiscalYear, fiscalQuarter });
+  const normalizedName = segmentName.trim().toLowerCase();
+  const quarter = fiscalQuarter !== null ? fiscalQuarter.toString() : 'null';
+  const compositeString = `${companyId}:${normalizedName}:${fiscalYear}:${quarter}`;
+  return uuidv5(compositeString, NAMESPACES.BUSINESS_SEGMENT);
+}
+
+/**
+ * Generate a deterministic UUID v5 ID for a brand.
+ * 
+ * @param companyId - UUID of the owning company
+ * @param name - Name of the brand
+ * @returns UUID v5 string
+ * @throws ZodError if companyId or name is empty
+ * 
+ * @example
+ * generateBrandId("company-uuid", "iPhone")
+ */
+export function generateBrandId(
+  companyId: string,
+  name: string
+): string {
+  BrandParamsSchema.parse({ companyId, name });
+  const normalizedName = name.trim().toLowerCase();
+  const compositeString = `${companyId}:${normalizedName}`;
+  return uuidv5(compositeString, NAMESPACES.BRAND);
+}
+
+/**
+ * Generate a deterministic UUID v5 ID for company_info.
+ * 
+ * @param companyId - UUID of the company
+ * @returns UUID v5 string
+ * 
+ * @example
+ * generateCompanyInfoId("company-uuid")
+ */
+export function generateCompanyInfoId(companyId: string): string {
+  if (!companyId || companyId.trim().length === 0) {
+    throw new Error("companyId is required for company_info ID generation");
+  }
+  return uuidv5(companyId, NAMESPACES.COMPANY_INFO);
+}

package/types/instant.schema.future.js

@@ -0,0 +1,55 @@
+"use strict";
+// Future schema additions - M&A tracking entities
+// These are not yet implemented but defined for future use
+// To use: merge these entities into instant.schema.ts when ready
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.futureEntities = void 0;
+const core_1 = require("@instantdb/core");
+// === M&A Event Tracking ===
+// Track mergers, acquisitions, spinoffs, and divestitures
+exports.futureEntities = {
+    ma_events: core_1.i.entity({
+        acquirer_id: core_1.i.string().indexed(),
+        announced_date: core_1.i.string().optional(),
+        created_at: core_1.i.string(),
+        deal_value: core_1.i.number().optional(),
+        deal_value_currency: core_1.i.string(),
+        effective_date: core_1.i.string().indexed(),
+        event_type: core_1.i.string().indexed(), // "acquisition" | "merger" | "spinoff" | "divestiture"
+        status: core_1.i.string().indexed(), // "pending" | "completed" | "terminated"
+        target_id: core_1.i.string().indexed(),
+        updated_at: core_1.i.string(),
+    }),
+    // Edge: Acquirer acquired Target
+    acquired: core_1.i.entity({
+        created_at: core_1.i.string(),
+        from_company_id: core_1.i.string().indexed(), // Acquirer
+        ma_event_id: core_1.i.string().indexed(),
+        to_company_id: core_1.i.string().indexed(), // Target
+    }),
+    // Edge: Target was acquired by Acquirer (reverse)
+    was_acquired_by: core_1.i.entity({
+        created_at: core_1.i.string(),
+        from_company_id: core_1.i.string().indexed(), // Target
+        ma_event_id: core_1.i.string().indexed(),
+        to_company_id: core_1.i.string().indexed(), // Acquirer
+    }),
+    // Temporal snapshots of company state
+    company_snapshots: core_1.i.entity({
+        aliases: core_1.i.any(),
+        change_reason: core_1.i.string().indexed(), // "ma_event" | "spinoff" | "ipo" | "delisting" | "name_change"
+        company_id: core_1.i.string().indexed(),
+        created_at: core_1.i.string(),
+        identity: core_1.i.any(),
+        ma_event_id: core_1.i.string().indexed().optional(),
+        name: core_1.i.string(),
+        type: core_1.i.string(),
+        valid_from: core_1.i.string().indexed(),
+        valid_to: core_1.i.string().indexed().optional(),
+    }),
+};
+// Usage example:
+// 1. Copy entities above into instant.schema.ts entities section
+// 2. Implement M&A ingestion pipeline
+// 3. Create repo functions for M&A operations
+// 4. Update frontend to display M&A events

package/types/instant.schema.future.ts

@@ -0,0 +1,59 @@
+// Future schema additions - M&A tracking entities
+// These are not yet implemented but defined for future use
+// To use: merge these entities into instant.schema.ts when ready
+
+import { i } from "@instantdb/core";
+
+// === M&A Event Tracking ===
+// Track mergers, acquisitions, spinoffs, and divestitures
+
+export const futureEntities = {
+  ma_events: i.entity({
+    acquirer_id: i.string().indexed(),
+    announced_date: i.string().optional(),
+    created_at: i.string(),
+    deal_value: i.number().optional(),
+    deal_value_currency: i.string(),
+    effective_date: i.string().indexed(),
+    event_type: i.string().indexed(), // "acquisition" | "merger" | "spinoff" | "divestiture"
+    status: i.string().indexed(), // "pending" | "completed" | "terminated"
+    target_id: i.string().indexed(),
+    updated_at: i.string(),
+  }),
+
+  // Edge: Acquirer acquired Target
+  acquired: i.entity({
+    created_at: i.string(),
+    from_company_id: i.string().indexed(), // Acquirer
+    ma_event_id: i.string().indexed(),
+    to_company_id: i.string().indexed(), // Target
+  }),
+
+  // Edge: Target was acquired by Acquirer (reverse)
+  was_acquired_by: i.entity({
+    created_at: i.string(),
+    from_company_id: i.string().indexed(), // Target
+    ma_event_id: i.string().indexed(),
+    to_company_id: i.string().indexed(), // Acquirer
+  }),
+
+  // Temporal snapshots of company state
+  company_snapshots: i.entity({
+    aliases: i.any(),
+    change_reason: i.string().indexed(), // "ma_event" | "spinoff" | "ipo" | "delisting" | "name_change"
+    company_id: i.string().indexed(),
+    created_at: i.string(),
+    identity: i.any(),
+    ma_event_id: i.string().indexed().optional(),
+    name: i.string(),
+    type: i.string(),
+    valid_from: i.string().indexed(),
+    valid_to: i.string().indexed().optional(),
+  }),
+};
+
+// Usage example:
+// 1. Copy entities above into instant.schema.ts entities section
+// 2. Implement M&A ingestion pipeline
+// 3. Create repo functions for M&A operations
+// 4. Update frontend to display M&A events