financial-graph-shared 1.0.0

package/dist/types/types.d.ts

@@ -0,0 +1,321 @@
+/**
+ * Shared Database Types & Validation
+ *
+ * InstantDB handles: type checking, required/optional, unique constraints
+ * We handle: business logic validation that InstantDB can't express
+ *
+ * Types vs Interfaces:
+ * - `type` aliases are direct re-exports from InstantDB (InstaQLEntity)
+ * - `interface` adds proper typing for enum/JSON fields that InstantDB types as number/any
+ * - Code should use the interfaces (Company, ParentOfEdge) not the raw types
+ */
+import { z } from "zod";
+import type { InstaQLEntity } from "@instantdb/core";
+import type schema from "../instant.schema";
+export declare const CompanyType: {
+    readonly PUBLIC: 1;
+    readonly PRIVATE: 2;
+    readonly ISSUER: 3;
+    readonly UNKNOWN: 4;
+    readonly TRUST: 5;
+};
+export type CompanyTypeValue = (typeof CompanyType)[keyof typeof CompanyType];
+export declare const ParentOfSource: {
+    readonly MA_EVENT: 1;
+    readonly SPINOFF: 2;
+    readonly IPO: 3;
+    readonly MANUAL: 4;
+    readonly SEC_FILING: 5;
+};
+export type ParentOfSourceValue = (typeof ParentOfSource)[keyof typeof ParentOfSource];
+type CompanyRaw = InstaQLEntity<typeof schema, "company">;
+type ParentOfEdgeRaw = InstaQLEntity<typeof schema, "parent_of">;
+export type Filing = InstaQLEntity<typeof schema, "filing">;
+export type FilingAttachments = Record<string, string>;
+export type SubsidiaryEnrichment = InstaQLEntity<typeof schema, "subsidiary_enrichment">;
+export type Audit = InstaQLEntity<typeof schema, "audit">;
+/** JSON structure for company.identity field */
+export interface CompanyIdentity {
+    primaryCIK?: string;
+    ciks?: string;
+    tickers?: string;
+    exchanges?: string;
+    sp500?: boolean;
+    lei?: string;
+    duns?: string;
+    entityType?: string;
+    sic?: string;
+    sicDescription?: string;
+    ein?: string;
+    category?: string;
+    ownerOrg?: string;
+}
+/** Company with properly typed `type` (enum) and `identity` (JSON) */
+export interface Company extends Omit<CompanyRaw, "type" | "identity"> {
+    type: CompanyTypeValue;
+    identity?: CompanyIdentity;
+}
+/** ParentOfEdge with properly typed `source` (enum) */
+export interface ParentOfEdge extends Omit<ParentOfEdgeRaw, "source"> {
+    source: ParentOfSourceValue;
+}
+/** JSON structure for audit.fields_changed array items */
+export interface FieldChange {
+    field: string;
+    old_value: unknown;
+    new_value: unknown;
+}
+/** Audit with properly typed `fields_changed` (JSON array) */
+export interface AuditWithChanges extends Omit<Audit, "fields_changed"> {
+    fields_changed: FieldChange[];
+}
+export declare const NonEmptyString: z.ZodString;
+export declare const IntNumber: z.ZodNumber;
+/** CIK: 1-10 digit numeric string, normalized to 10 digits with leading zeros */
+export declare const CIKString: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+/**
+ * Accession Number: SEC filing identifier
+ * Format: XXXXXXXXXX-XX-XXXXXX (with dashes) or XXXXXXXXXXXXXXXXXX (without)
+ * Normalized by removing dashes
+ */
+export declare const AccessionNumberString: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+/** Jurisdiction: rejects numbers/percentages (common parsing errors) */
+export declare const JurisdictionString: z.ZodString;
+/** PUBLIC company: requires name, identity required */
+export declare const PublicCompanySchema: z.ZodObject<{
+    type: z.ZodLiteral<1>;
+    name: z.ZodString;
+    identity: z.ZodObject<{
+        primaryCIK: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+        ciks: z.ZodOptional<z.ZodString>;
+        tickers: z.ZodOptional<z.ZodString>;
+        exchanges: z.ZodOptional<z.ZodString>;
+        sp500: z.ZodOptional<z.ZodBoolean>;
+        lei: z.ZodOptional<z.ZodString>;
+        duns: z.ZodOptional<z.ZodString>;
+        entityType: z.ZodOptional<z.ZodString>;
+        sic: z.ZodOptional<z.ZodString>;
+        sicDescription: z.ZodOptional<z.ZodString>;
+        ein: z.ZodOptional<z.ZodString>;
+        category: z.ZodOptional<z.ZodString>;
+        ownerOrg: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    jurisdiction_raw: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** PRIVATE company: requires name + jurisdiction, identity optional */
+export declare const PrivateCompanySchema: z.ZodObject<{
+    type: z.ZodLiteral<2>;
+    name: z.ZodString;
+    jurisdiction_raw: z.ZodString;
+    identity: z.ZodOptional<z.ZodObject<{
+        primaryCIK: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+        ciks: z.ZodOptional<z.ZodString>;
+        tickers: z.ZodOptional<z.ZodString>;
+        exchanges: z.ZodOptional<z.ZodString>;
+        sp500: z.ZodOptional<z.ZodBoolean>;
+        lei: z.ZodOptional<z.ZodString>;
+        duns: z.ZodOptional<z.ZodString>;
+        entityType: z.ZodOptional<z.ZodString>;
+        sic: z.ZodOptional<z.ZodString>;
+        sicDescription: z.ZodOptional<z.ZodString>;
+        ein: z.ZodOptional<z.ZodString>;
+        category: z.ZodOptional<z.ZodString>;
+        ownerOrg: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** ISSUER company: requires name, identity required */
+export declare const IssuerCompanySchema: z.ZodObject<{
+    type: z.ZodLiteral<3>;
+    name: z.ZodString;
+    identity: z.ZodObject<{
+        primaryCIK: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+        ciks: z.ZodOptional<z.ZodString>;
+        tickers: z.ZodOptional<z.ZodString>;
+        exchanges: z.ZodOptional<z.ZodString>;
+        sp500: z.ZodOptional<z.ZodBoolean>;
+        lei: z.ZodOptional<z.ZodString>;
+        duns: z.ZodOptional<z.ZodString>;
+        entityType: z.ZodOptional<z.ZodString>;
+        sic: z.ZodOptional<z.ZodString>;
+        sicDescription: z.ZodOptional<z.ZodString>;
+        ein: z.ZodOptional<z.ZodString>;
+        category: z.ZodOptional<z.ZodString>;
+        ownerOrg: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    jurisdiction_raw: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** UNKNOWN company: requires name, jurisdiction optional, identity optional */
+export declare const UnknownCompanySchema: z.ZodObject<{
+    type: z.ZodLiteral<4>;
+    name: z.ZodString;
+    jurisdiction_raw: z.ZodOptional<z.ZodString>;
+    identity: z.ZodOptional<z.ZodObject<{
+        primaryCIK: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+        ciks: z.ZodOptional<z.ZodString>;
+        tickers: z.ZodOptional<z.ZodString>;
+        exchanges: z.ZodOptional<z.ZodString>;
+        sp500: z.ZodOptional<z.ZodBoolean>;
+        lei: z.ZodOptional<z.ZodString>;
+        duns: z.ZodOptional<z.ZodString>;
+        entityType: z.ZodOptional<z.ZodString>;
+        sic: z.ZodOptional<z.ZodString>;
+        sicDescription: z.ZodOptional<z.ZodString>;
+        ein: z.ZodOptional<z.ZodString>;
+        category: z.ZodOptional<z.ZodString>;
+        ownerOrg: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** TRUST company: requires name, identity optional */
+export declare const TrustCompanySchema: z.ZodObject<{
+    type: z.ZodLiteral<5>;
+    name: z.ZodString;
+    jurisdiction_raw: z.ZodOptional<z.ZodString>;
+    identity: z.ZodOptional<z.ZodObject<{
+        primaryCIK: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+        ciks: z.ZodOptional<z.ZodString>;
+        tickers: z.ZodOptional<z.ZodString>;
+        exchanges: z.ZodOptional<z.ZodString>;
+        sp500: z.ZodOptional<z.ZodBoolean>;
+        lei: z.ZodOptional<z.ZodString>;
+        duns: z.ZodOptional<z.ZodString>;
+        entityType: z.ZodOptional<z.ZodString>;
+        sic: z.ZodOptional<z.ZodString>;
+        sicDescription: z.ZodOptional<z.ZodString>;
+        ein: z.ZodOptional<z.ZodString>;
+        category: z.ZodOptional<z.ZodString>;
+        ownerOrg: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Company validation by type */
+export declare const CompanySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<1>;
+    name: z.ZodString;
+    identity: z.ZodObject<{
+        primaryCIK: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+        ciks: z.ZodOptional<z.ZodString>;
+        tickers: z.ZodOptional<z.ZodString>;
+        exchanges: z.ZodOptional<z.ZodString>;
+        sp500: z.ZodOptional<z.ZodBoolean>;
+        lei: z.ZodOptional<z.ZodString>;
+        duns: z.ZodOptional<z.ZodString>;
+        entityType: z.ZodOptional<z.ZodString>;
+        sic: z.ZodOptional<z.ZodString>;
+        sicDescription: z.ZodOptional<z.ZodString>;
+        ein: z.ZodOptional<z.ZodString>;
+        category: z.ZodOptional<z.ZodString>;
+        ownerOrg: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    jurisdiction_raw: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<2>;
+    name: z.ZodString;
+    jurisdiction_raw: z.ZodString;
+    identity: z.ZodOptional<z.ZodObject<{
+        primaryCIK: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+        ciks: z.ZodOptional<z.ZodString>;
+        tickers: z.ZodOptional<z.ZodString>;
+        exchanges: z.ZodOptional<z.ZodString>;
+        sp500: z.ZodOptional<z.ZodBoolean>;
+        lei: z.ZodOptional<z.ZodString>;
+        duns: z.ZodOptional<z.ZodString>;
+        entityType: z.ZodOptional<z.ZodString>;
+        sic: z.ZodOptional<z.ZodString>;
+        sicDescription: z.ZodOptional<z.ZodString>;
+        ein: z.ZodOptional<z.ZodString>;
+        category: z.ZodOptional<z.ZodString>;
+        ownerOrg: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<3>;
+    name: z.ZodString;
+    identity: z.ZodObject<{
+        primaryCIK: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+        ciks: z.ZodOptional<z.ZodString>;
+        tickers: z.ZodOptional<z.ZodString>;
+        exchanges: z.ZodOptional<z.ZodString>;
+        sp500: z.ZodOptional<z.ZodBoolean>;
+        lei: z.ZodOptional<z.ZodString>;
+        duns: z.ZodOptional<z.ZodString>;
+        entityType: z.ZodOptional<z.ZodString>;
+        sic: z.ZodOptional<z.ZodString>;
+        sicDescription: z.ZodOptional<z.ZodString>;
+        ein: z.ZodOptional<z.ZodString>;
+        category: z.ZodOptional<z.ZodString>;
+        ownerOrg: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    jurisdiction_raw: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<4>;
+    name: z.ZodString;
+    jurisdiction_raw: z.ZodOptional<z.ZodString>;
+    identity: z.ZodOptional<z.ZodObject<{
+        primaryCIK: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+        ciks: z.ZodOptional<z.ZodString>;
+        tickers: z.ZodOptional<z.ZodString>;
+        exchanges: z.ZodOptional<z.ZodString>;
+        sp500: z.ZodOptional<z.ZodBoolean>;
+        lei: z.ZodOptional<z.ZodString>;
+        duns: z.ZodOptional<z.ZodString>;
+        entityType: z.ZodOptional<z.ZodString>;
+        sic: z.ZodOptional<z.ZodString>;
+        sicDescription: z.ZodOptional<z.ZodString>;
+        ein: z.ZodOptional<z.ZodString>;
+        category: z.ZodOptional<z.ZodString>;
+        ownerOrg: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<5>;
+    name: z.ZodString;
+    jurisdiction_raw: z.ZodOptional<z.ZodString>;
+    identity: z.ZodOptional<z.ZodObject<{
+        primaryCIK: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+        ciks: z.ZodOptional<z.ZodString>;
+        tickers: z.ZodOptional<z.ZodString>;
+        exchanges: z.ZodOptional<z.ZodString>;
+        sp500: z.ZodOptional<z.ZodBoolean>;
+        lei: z.ZodOptional<z.ZodString>;
+        duns: z.ZodOptional<z.ZodString>;
+        entityType: z.ZodOptional<z.ZodString>;
+        sic: z.ZodOptional<z.ZodString>;
+        sicDescription: z.ZodOptional<z.ZodString>;
+        ein: z.ZodOptional<z.ZodString>;
+        category: z.ZodOptional<z.ZodString>;
+        ownerOrg: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>], "type">;
+export declare const ParentOfParamsSchema: z.ZodObject<{
+    parentId: z.ZodString;
+    subsidiaryId: z.ZodString;
+    establishedDate: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const SubsidiaryEnrichmentParamsSchema: z.ZodObject<{
+    companyId: z.ZodString;
+    filingId: z.ZodString;
+}, z.core.$strip>;
+export declare const BusinessSegmentParamsSchema: z.ZodObject<{
+    companyId: z.ZodString;
+    segmentName: z.ZodString;
+    fiscalYear: z.ZodNumber;
+    fiscalQuarter: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const BrandParamsSchema: z.ZodObject<{
+    companyId: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strip>;
+export declare const OwnsParamsSchema: z.ZodObject<{
+    companyId: z.ZodString;
+    brandId: z.ZodString;
+}, z.core.$strip>;
+export declare function isPublicCompany(company: Company): boolean;
+export declare function isPrivateCompany(company: Company): boolean;
+export declare function isFromSecFiling(edge: ParentOfEdge): boolean;
+export declare function validate<T>(schema: z.ZodSchema<T>, data: unknown, schemaName?: string): T;
+export declare function safeValidate<T>(schema: z.ZodSchema<T>, data: unknown): {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: z.ZodError;
+};
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../types/types.ts"],"names":[],"mappings":"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"}

package/dist/types/types.js

@@ -0,0 +1,180 @@
+/**
+ * Shared Database Types & Validation
+ *
+ * InstantDB handles: type checking, required/optional, unique constraints
+ * We handle: business logic validation that InstantDB can't express
+ *
+ * Types vs Interfaces:
+ * - `type` aliases are direct re-exports from InstantDB (InstaQLEntity)
+ * - `interface` adds proper typing for enum/JSON fields that InstantDB types as number/any
+ * - Code should use the interfaces (Company, ParentOfEdge) not the raw types
+ */
+import { z } from "zod";
+// ============================================================================
+// ENUMS
+// ============================================================================
+export const CompanyType = {
+    PUBLIC: 1,
+    PRIVATE: 2,
+    ISSUER: 3,
+    UNKNOWN: 4,
+    TRUST: 5,
+};
+export const ParentOfSource = {
+    MA_EVENT: 1,
+    SPINOFF: 2,
+    IPO: 3,
+    MANUAL: 4,
+    SEC_FILING: 5,
+};
+// ============================================================================
+// FIELD VALIDATORS (business logic InstantDB can't express)
+// ============================================================================
+export const NonEmptyString = z.string().min(1);
+export const IntNumber = z.number().int();
+/** CIK: 1-10 digit numeric string, normalized to 10 digits with leading zeros */
+export const CIKString = z
+    .string()
+    .regex(/^\d{1,10}$/, "CIK must be 1-10 digits")
+    .transform((val) => val.trim().padStart(10, "0"));
+/**
+ * Accession Number: SEC filing identifier
+ * Format: XXXXXXXXXX-XX-XXXXXX (with dashes) or XXXXXXXXXXXXXXXXXX (without)
+ * Normalized by removing dashes
+ */
+export const AccessionNumberString = z
+    .string()
+    .min(1, "Accession number is required")
+    .transform((val) => val.replace(/-/g, ""));
+/** Jurisdiction: rejects numbers/percentages (common parsing errors) */
+export const JurisdictionString = z.string().refine((val) => {
+    const trimmed = val.trim();
+    if (/^\d+(\.\d+)?$/.test(trimmed))
+        return false;
+    if (/^\d+(\.\d+)?%$/.test(trimmed))
+        return false;
+    return true;
+}, { message: "Jurisdiction cannot be a number or percentage" });
+// ============================================================================
+// COMPANY VALIDATION (type-specific rules)
+// ============================================================================
+const CompanyIdentitySchema = z.object({
+    primaryCIK: CIKString.optional(),
+    ciks: z.string().optional(),
+    tickers: z.string().optional(),
+    exchanges: z.string().optional(),
+    sp500: z.boolean().optional(),
+    lei: z.string().length(20).optional(),
+    duns: z.string().length(9).optional(),
+    entityType: z.string().optional(),
+    sic: z.string().optional(),
+    sicDescription: z.string().optional(),
+    ein: z.string().optional(),
+    category: z.string().optional(),
+    ownerOrg: z.string().optional(),
+});
+/** PUBLIC company: requires name, identity required */
+export const PublicCompanySchema = z.object({
+    type: z.literal(CompanyType.PUBLIC),
+    name: NonEmptyString,
+    identity: CompanyIdentitySchema,
+    jurisdiction_raw: z.string().optional(),
+});
+/** PRIVATE company: requires name + jurisdiction, identity optional */
+export const PrivateCompanySchema = z.object({
+    type: z.literal(CompanyType.PRIVATE),
+    name: NonEmptyString,
+    jurisdiction_raw: JurisdictionString,
+    identity: CompanyIdentitySchema.optional(),
+});
+/** ISSUER company: requires name, identity required */
+export const IssuerCompanySchema = z.object({
+    type: z.literal(CompanyType.ISSUER),
+    name: NonEmptyString,
+    identity: CompanyIdentitySchema,
+    jurisdiction_raw: z.string().optional(),
+});
+/** UNKNOWN company: requires name, jurisdiction optional, identity optional */
+export const UnknownCompanySchema = z.object({
+    type: z.literal(CompanyType.UNKNOWN),
+    name: NonEmptyString,
+    jurisdiction_raw: JurisdictionString.optional(),
+    identity: CompanyIdentitySchema.optional(),
+});
+/** TRUST company: requires name, identity optional */
+export const TrustCompanySchema = z.object({
+    type: z.literal(CompanyType.TRUST),
+    name: NonEmptyString,
+    jurisdiction_raw: z.string().optional(),
+    identity: CompanyIdentitySchema.optional(),
+});
+/** Company validation by type */
+export const CompanySchema = z.discriminatedUnion("type", [
+    PublicCompanySchema,
+    PrivateCompanySchema,
+    IssuerCompanySchema,
+    UnknownCompanySchema,
+    TrustCompanySchema,
+]);
+// ============================================================================
+// ID GENERATION PARAMS (for composite key generation)
+// ============================================================================
+export const ParentOfParamsSchema = z.object({
+    parentId: NonEmptyString,
+    subsidiaryId: NonEmptyString,
+    establishedDate: NonEmptyString.optional(),
+});
+export const SubsidiaryEnrichmentParamsSchema = z.object({
+    companyId: NonEmptyString,
+    filingId: NonEmptyString,
+});
+export const BusinessSegmentParamsSchema = z.object({
+    companyId: NonEmptyString,
+    segmentName: NonEmptyString,
+    fiscalYear: IntNumber,
+    fiscalQuarter: IntNumber.nullable(),
+});
+export const BrandParamsSchema = z.object({
+    companyId: NonEmptyString,
+    name: NonEmptyString,
+});
+export const OwnsParamsSchema = z.object({
+    companyId: NonEmptyString,
+    brandId: NonEmptyString,
+});
+// ============================================================================
+// TYPE GUARDS
+// ============================================================================
+export function isPublicCompany(company) {
+    return (company.type === CompanyType.PUBLIC || company.type === CompanyType.ISSUER);
+}
+export function isPrivateCompany(company) {
+    return company.type === CompanyType.PRIVATE;
+}
+export function isFromSecFiling(edge) {
+    return edge.source === ParentOfSource.SEC_FILING;
+}
+// ============================================================================
+// VALIDATION HELPERS
+// ============================================================================
+export function validate(schema, data, schemaName) {
+    try {
+        return schema.parse(data);
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            const errors = error.issues
+                .map((e) => `${e.path.join(".")}: ${e.message}`)
+                .join(", ");
+            throw new Error(`Validation failed${schemaName ? ` for ${schemaName}` : ""}: ${errors}`);
+        }
+        throw error;
+    }
+}
+export function safeValidate(schema, data) {
+    const result = schema.safeParse(data);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    return { success: false, error: result.error };
+}

package/dist/types/validation.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Validation Re-exports (backward compatibility)
+ *
+ * For new code, import directly from "./types"
+ */
+export { NonEmptyString, IntNumber, CIKString, JurisdictionString, CompanySchema, PublicCompanySchema, PrivateCompanySchema, IssuerCompanySchema, UnknownCompanySchema, AccessionNumberString, ParentOfParamsSchema, SubsidiaryEnrichmentParamsSchema, BusinessSegmentParamsSchema, BrandParamsSchema, OwnsParamsSchema, validate, safeValidate, } from "./types";
+//# sourceMappingURL=validation.d.ts.map

package/dist/types/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../types/validation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAEL,cAAc,EACd,SAAS,EACT,SAAS,EACT,kBAAkB,EAGlB,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EAGpB,qBAAqB,EACrB,oBAAoB,EACpB,gCAAgC,EAChC,2BAA2B,EAC3B,iBAAiB,EACjB,gBAAgB,EAGhB,QAAQ,EACR,YAAY,GACb,MAAM,SAAS,CAAC"}

package/dist/types/validation.js

@@ -0,0 +1,14 @@
+/**
+ * Validation Re-exports (backward compatibility)
+ *
+ * For new code, import directly from "./types"
+ */
+export { 
+// Field validators
+NonEmptyString, IntNumber, CIKString, JurisdictionString, 
+// Company validation (type-specific rules)
+CompanySchema, PublicCompanySchema, PrivateCompanySchema, IssuerCompanySchema, UnknownCompanySchema, 
+// ID generation params
+AccessionNumberString, ParentOfParamsSchema, SubsidiaryEnrichmentParamsSchema, BusinessSegmentParamsSchema, BrandParamsSchema, OwnsParamsSchema, 
+// Helpers
+validate, safeValidate, } from "./types";

package/dist/utils/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Shared Utilities
+ */
+export * from "./logger-interface";
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,oBAAoB,CAAC"}

package/dist/utils/index.js

@@ -0,0 +1,4 @@
+/**
+ * Shared Utilities
+ */
+export * from "./logger-interface";

package/dist/utils/logger-interface.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Shared Logger Interface
+ *
+ * Common interface for logging across frontend and backend.
+ * Implementations differ (browser vs Node.js) but API is consistent.
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export interface LogMetadata {
+    [key: string]: any;
+}
+export interface Logger {
+    debug(message: string, meta?: LogMetadata): void;
+    info(message: string, meta?: LogMetadata): void;
+    warn(message: string, meta?: LogMetadata): void;
+    error(message: string, meta?: LogMetadata): void;
+}
+export interface LoggerFactory {
+    createLogger(context: string): Logger;
+}
+/**
+ * Failed Record Utilities
+ *
+ * Convention for saving failed records during ingestion/processing.
+ * Failed records are separate from logs and stored in a structured format.
+ */
+export interface FailedRecord<T = any> {
+    timestamp: string;
+    context: string;
+    identifier: string | number;
+    data: T;
+    error: {
+        message: string;
+        stack?: string;
+        code?: string;
+    };
+}
+export interface FailedRecordOptions {
+    /** Base directory for failed records (e.g., 'financial-graph/backend/logs/failed-records') */
+    baseDir: string;
+    /** Context/module name (e.g., 'ticker-ingestion', 'subsidiary-parser') */
+    context: string;
+    /** Optional date for organizing by date (defaults to today) */
+    date?: Date;
+}
+/**
+ * Generate a standardized path for failed records
+ *
+ * Convention: {baseDir}/{context}/{YYYY-MM-DD}/failed-{context}-{timestamp}.json
+ *
+ * Example: logs/failed-records/ticker-ingestion/2026-01-12/failed-ticker-ingestion-20260112-143022.json
+ */
+export declare function getFailedRecordPath(options: FailedRecordOptions): string;
+/**
+ * Create a failed record object
+ */
+export declare function createFailedRecord<T>(context: string, identifier: string | number, data: T, error: Error | string): FailedRecord<T>;
+//# sourceMappingURL=logger-interface.d.ts.map

package/dist/utils/logger-interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger-interface.d.ts","sourceRoot":"","sources":["../../utils/logger-interface.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D,MAAM,WAAW,WAAW;IAC1B,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACjD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAChD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAChD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;CAClD;AAED,MAAM,WAAW,aAAa;IAC5B,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;CACvC;AAED;;;;;GAKG;AAEH,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,GAAG;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,IAAI,EAAE,CAAC,CAAC;IACR,KAAK,EAAE;QACL,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAED,MAAM,WAAW,mBAAmB;IAClC,8FAA8F;IAC9F,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,IAAI,CAAC,EAAE,IAAI,CAAC;CACb;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAMxE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GAAG,MAAM,EAC3B,IAAI,EAAE,CAAC,EACP,KAAK,EAAE,KAAK,GAAG,MAAM,GACpB,YAAY,CAAC,CAAC,CAAC,CAgBjB"}

package/dist/utils/logger-interface.js

@@ -0,0 +1,38 @@
+/**
+ * Shared Logger Interface
+ *
+ * Common interface for logging across frontend and backend.
+ * Implementations differ (browser vs Node.js) but API is consistent.
+ */
+/**
+ * Generate a standardized path for failed records
+ *
+ * Convention: {baseDir}/{context}/{YYYY-MM-DD}/failed-{context}-{timestamp}.json
+ *
+ * Example: logs/failed-records/ticker-ingestion/2026-01-12/failed-ticker-ingestion-20260112-143022.json
+ */
+export function getFailedRecordPath(options) {
+    const date = options.date || new Date();
+    const dateStr = date.toISOString().split("T")[0]; // YYYY-MM-DD
+    const timestamp = date.toISOString().replace(/[:.]/g, "-").split("T").join("-").slice(0, -5); // YYYY-MM-DD-HHmmss
+    return `${options.baseDir}/${options.context}/${dateStr}/failed-${options.context}-${timestamp}.json`;
+}
+/**
+ * Create a failed record object
+ */
+export function createFailedRecord(context, identifier, data, error) {
+    const errorObj = typeof error === "string"
+        ? { message: error }
+        : {
+            message: error.message,
+            stack: error.stack,
+            code: error.code,
+        };
+    return {
+        timestamp: new Date().toISOString(),
+        context,
+        identifier,
+        data,
+        error: errorObj,
+    };
+}