pigeongov 0.2.0

package/dist/src/types.d.ts

@@ -0,0 +1,362 @@
+export type FilingStatus = "single" | "married_filing_jointly" | "married_filing_separately" | "head_of_household" | "qualifying_surviving_spouse";
+export interface DependentInput {
+    name: string;
+    ssn: string;
+    relationship: string;
+    childTaxCreditEligible: boolean;
+    eitcEligible?: boolean | undefined;
+}
+export interface Address {
+    street1: string;
+    street2?: string | undefined;
+    city: string;
+    state: string;
+    zipCode: string;
+}
+export interface PersonIdentity {
+    firstName: string;
+    lastName: string;
+    ssn: string;
+    address: Address;
+}
+export interface ValidationFlag {
+    field: string;
+    severity: "warning" | "error" | "review";
+    message: string;
+    source?: string | undefined;
+}
+export interface ValidationCheck {
+    id: string;
+    label: string;
+    passed: boolean;
+    severity: "warning" | "error";
+    message: string;
+}
+export interface ReviewSummary {
+    headline: string;
+    notes: string[];
+    flaggedFields: ValidationFlag[];
+}
+export interface W2Document {
+    type: "w2";
+    employerName: string;
+    employerEin?: string | undefined;
+    wages: number;
+    federalWithheld: number;
+    socialSecurityWages?: number | undefined;
+    medicareWages?: number | undefined;
+    employeeName?: string | undefined;
+}
+export interface Form1099NecDocument {
+    type: "1099-nec";
+    payerName: string;
+    nonemployeeCompensation: number;
+    federalWithheld?: number | undefined;
+}
+export interface Form1099IntDocument {
+    type: "1099-int";
+    payerName: string;
+    interestIncome: number;
+    federalWithheld?: number | undefined;
+}
+export interface Form1098Document {
+    type: "1098";
+    lenderName: string;
+    mortgageInterest: number;
+    mortgageInsurancePremiums?: number | undefined;
+    pointsPaid?: number | undefined;
+    outstandingPrincipal?: number | undefined;
+    federalWithheld?: number | undefined;
+}
+export interface Form1095ADocument {
+    type: "1095-a";
+    marketplaceName: string;
+    policyNumber?: string | undefined;
+    monthlyPremiums: number[];
+    monthlySlcsp: number[];
+    monthlyAdvancePtc: number[];
+}
+export interface Form1099DivDocument {
+    type: "1099-div";
+    payerName: string;
+    ordinaryDividends: number;
+    qualifiedDividends: number;
+    totalCapitalGainDistributions?: number | undefined;
+    federalWithheld?: number | undefined;
+}
+export interface Form1099BDocument {
+    type: "1099-b";
+    brokerName: string;
+    proceeds: number;
+    costBasis: number;
+    gainOrLoss?: number | undefined;
+    shortTerm: boolean;
+    federalWithheld?: number | undefined;
+}
+export interface Form1099RDocument {
+    type: "1099-r";
+    payerName: string;
+    grossDistribution: number;
+    taxableAmount: number;
+    distributionCode?: string | undefined;
+    federalWithheld?: number | undefined;
+}
+export interface K1Document {
+    type: "k-1";
+    partnershipName: string;
+    partnershipEin?: string | undefined;
+    ordinaryIncome: number;
+    rentalIncome?: number | undefined;
+    interestIncome?: number | undefined;
+    dividends?: number | undefined;
+    capitalGains?: number | undefined;
+}
+export type ImportedDocument = W2Document | Form1099NecDocument | Form1099IntDocument | Form1098Document | Form1095ADocument | Form1099DivDocument | Form1099BDocument | Form1099RDocument | K1Document;
+export interface TaxBracketBreakdown {
+    rate: number;
+    lowerBound: number;
+    upperBound?: number | undefined;
+    taxableAmount: number;
+    taxAmount: number;
+}
+export type WorkflowDomain = "tax" | "immigration" | "healthcare" | "unemployment" | "business" | "permits" | "education" | "retirement" | "identity" | "benefits" | "veterans" | "legal" | "estate";
+export type WorkflowArtifactFormat = "json" | "pdf" | "checklist" | "summary";
+export interface WorkflowArtifact {
+    kind: string;
+    label: string;
+    format: WorkflowArtifactFormat;
+    path?: string | undefined;
+    content?: unknown;
+}
+export interface WorkflowEvidenceItem {
+    id: string;
+    label: string;
+    required: boolean;
+    status: "provided" | "missing" | "review";
+    notes?: string | undefined;
+    source?: string | undefined;
+}
+export interface WorkflowQuestionOption {
+    label: string;
+    value: string;
+}
+export type WorkflowQuestionFieldType = "text" | "textarea" | "currency" | "number" | "select" | "confirm" | "date";
+export interface WorkflowQuestionField {
+    key: string;
+    label: string;
+    type: WorkflowQuestionFieldType;
+    helpText?: string | undefined;
+    placeholder?: string | undefined;
+    options?: WorkflowQuestionOption[] | undefined;
+}
+export interface WorkflowQuestionSection {
+    id: string;
+    title: string;
+    description?: string | undefined;
+    fields: WorkflowQuestionField[];
+}
+export interface WorkflowDefinitionSummary {
+    id: string;
+    domain: WorkflowDomain;
+    title: string;
+    summary: string;
+    status: "active" | "preview" | "planned";
+    audience: "individual" | "household" | "business";
+    tags: string[];
+    year?: number | undefined;
+    legacyFormId?: string | undefined;
+}
+export interface WorkflowBundle {
+    workflowId: string;
+    domain: WorkflowDomain;
+    title: string;
+    summary: string;
+    year?: number | undefined;
+    legacyFormId?: string | undefined;
+    applicant?: PersonIdentity | undefined;
+    household: Array<{
+        name: string;
+        relationship: string;
+        age?: number | undefined;
+        notes?: string | undefined;
+    }>;
+    evidence: WorkflowEvidenceItem[];
+    answers: Record<string, unknown>;
+    derived: Record<string, unknown>;
+    validation: {
+        checks: ValidationCheck[];
+        flaggedFields: ValidationFlag[];
+    };
+    review: ReviewSummary;
+    outputArtifacts: WorkflowArtifact[];
+    provenance: string[];
+    filledForm?: unknown;
+    calculation?: unknown;
+}
+export interface PigeonGovErrorShape {
+    error: string;
+    message: string;
+    field?: string | undefined;
+    suggestion?: string | undefined;
+    retryable: boolean;
+    docs?: string | undefined;
+    exitCode: number;
+}
+export interface StructuredOutput<T = unknown> {
+    ok: boolean;
+    data?: T | undefined;
+    error?: PigeonGovErrorShape | undefined;
+    exitCode: number;
+}
+export interface HouseholdProfile {
+    id: string;
+    people: PersonRecord[];
+    address: Address;
+    income?: IncomeProfile | undefined;
+    updatedAt: string;
+}
+export interface PersonRecord {
+    id: string;
+    firstName: string;
+    lastName: string;
+    ssn?: string | undefined;
+    dob?: string | undefined;
+    relationship: "self" | "spouse" | "child" | "parent" | "other";
+}
+export interface IncomeProfile {
+    taxYear: number;
+    sources: Array<{
+        label: string;
+        amount: number;
+        type: string;
+    }>;
+    totalGross: number;
+}
+export interface DraftMetadata {
+    id: string;
+    workflowId: string;
+    schemaVersion: string;
+    answers: Record<string, unknown>;
+    completedSections: string[];
+    resumePoint?: string | undefined;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface VaultEntry {
+    id: string;
+    filename: string;
+    mimeType: string;
+    tags: string[];
+    linkedWorkflows: string[];
+    addedAt: string;
+    sizeBytes: number;
+    checksum: string;
+}
+export interface WorkflowDeadline {
+    workflowId: string;
+    label: string;
+    date: string;
+    type: "hard" | "soft";
+    consequence: string;
+    extensionAvailable: boolean;
+}
+export interface WorkflowFee {
+    workflowId: string;
+    label: string;
+    amount: number;
+    currency: "USD";
+    type: "filing" | "biometric" | "expedite" | "optional";
+    waivable: boolean;
+    waiverCriteria?: string | undefined;
+}
+export interface GlossaryEntry {
+    term: string;
+    abbreviation?: string | undefined;
+    domain: WorkflowDomain;
+    definition: string;
+    officialDefinition?: string | undefined;
+    source?: string | undefined;
+    relatedTerms?: string[] | undefined;
+}
+export interface LifeEvent {
+    id: string;
+    label: string;
+    description: string;
+    workflows: LifeEventWorkflow[];
+}
+export interface LifeEventWorkflow {
+    workflowId: string;
+    priority: number;
+    deadline?: string | undefined;
+    dependsOn?: string[] | undefined;
+    notes: string;
+}
+export interface EligibilityResult {
+    workflowId: string;
+    eligible: "likely" | "possible" | "unlikely" | "ineligible";
+    confidence: number;
+    reason: string;
+    nextSteps: string[];
+}
+export interface CapitalGainsInput {
+    transactions: Array<{
+        description: string;
+        dateAcquired: string;
+        dateSold: string;
+        proceeds: number;
+        costBasis: number;
+        shortTerm: boolean;
+    }>;
+}
+export interface DividendDetailInput {
+    ordinaryDividends: number;
+    qualifiedDividends: number;
+    capitalGainDistributions?: number | undefined;
+}
+export interface RentalIncomeInput {
+    propertyAddress: string;
+    grossRent: number;
+    expenses: number;
+    depreciation: number;
+    netIncome: number;
+}
+export interface HsaInput {
+    contributions: number;
+    employerContributions: number;
+    distributions: number;
+    qualifiedMedicalExpenses: number;
+}
+export interface CryptoTransactionInput {
+    exchange: string;
+    asset: string;
+    dateAcquired: string;
+    dateSold: string;
+    proceeds: number;
+    costBasis: number;
+    transactionType: "trade" | "staking" | "lending" | "airdrop" | "mining";
+}
+export interface EquityCompensationInput {
+    type: "rsu" | "iso" | "nso" | "espp";
+    grantDate: string;
+    vestDate?: string | undefined;
+    exerciseDate?: string | undefined;
+    shares: number;
+    fairMarketValue: number;
+    exercisePrice?: number | undefined;
+    salePrice?: number | undefined;
+    saleDate?: string | undefined;
+}
+export interface WorkflowPlugin {
+    name: string;
+    version: string;
+    author?: string | undefined;
+    license?: string | undefined;
+    workflows: Array<{
+        summary: WorkflowDefinitionSummary;
+        inputSchema: unknown;
+        starterData: unknown;
+        sections: WorkflowQuestionSection[];
+        buildBundle: (input: unknown) => WorkflowBundle;
+    }>;
+    glossaryTerms?: GlossaryEntry[] | undefined;
+}

package/dist/src/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":""}

package/dist/src/workflows/deadlines.d.ts

@@ -0,0 +1,13 @@
+import type { WorkflowDeadline } from "../types.js";
+/**
+ * Filter deadlines to those in the future (relative to asOfDate) and sort ascending.
+ */
+export declare function getUpcomingDeadlines(deadlines: WorkflowDeadline[], asOfDate?: Date): WorkflowDeadline[];
+/**
+ * Generate an ICS calendar file string from an array of deadlines.
+ */
+export declare function generateIcs(deadlines: WorkflowDeadline[]): string;
+/**
+ * Hardcoded deadline data for existing workflows.
+ */
+export declare const DEFAULT_DEADLINES: WorkflowDeadline[];

package/dist/src/workflows/deadlines.js

@@ -0,0 +1,88 @@
+/**
+ * Filter deadlines to those in the future (relative to asOfDate) and sort ascending.
+ */
+export function getUpcomingDeadlines(deadlines, asOfDate) {
+    const now = asOfDate ?? new Date();
+    return deadlines
+        .filter((d) => new Date(d.date) > now)
+        .sort((a, b) => new Date(a.date).getTime() - new Date(b.date).getTime());
+}
+/**
+ * Format a Date as an ICS DTSTART value: YYYYMMDDTHHMMSSZ
+ */
+function formatIcsDate(dateStr) {
+    const d = new Date(dateStr);
+    const year = d.getUTCFullYear();
+    const month = String(d.getUTCMonth() + 1).padStart(2, "0");
+    const day = String(d.getUTCDate()).padStart(2, "0");
+    return `${year}${month}${day}T000000Z`;
+}
+/**
+ * Generate an ICS calendar file string from an array of deadlines.
+ */
+export function generateIcs(deadlines) {
+    const events = deadlines
+        .map((d) => `BEGIN:VEVENT\r\nDTSTART:${formatIcsDate(d.date)}\r\nSUMMARY:${d.label}\r\nDESCRIPTION:${d.consequence}\r\nEND:VEVENT`)
+        .join("\r\n");
+    return [
+        "BEGIN:VCALENDAR",
+        "VERSION:2.0",
+        "PRODID:-//PigeonGov//Deadlines//EN",
+        events,
+        "END:VCALENDAR",
+    ].join("\r\n");
+}
+/**
+ * Hardcoded deadline data for existing workflows.
+ */
+export const DEFAULT_DEADLINES = [
+    {
+        workflowId: "tax/1040",
+        label: "Tax filing deadline",
+        date: "2026-04-15",
+        type: "hard",
+        consequence: "Late filing penalty of 5% per month on unpaid taxes",
+        extensionAvailable: true,
+    },
+    {
+        workflowId: "tax/1040",
+        label: "Extension deadline",
+        date: "2026-10-15",
+        type: "hard",
+        consequence: "No further extensions; penalties and interest accrue",
+        extensionAvailable: false,
+    },
+    {
+        workflowId: "immigration/family-visa-intake",
+        label: "Apply as soon as eligible",
+        date: "2099-12-31",
+        type: "soft",
+        consequence: "Processing times increase with backlogs; no fixed statutory deadline",
+        extensionAvailable: false,
+    },
+    {
+        workflowId: "healthcare/aca-enrollment",
+        label: "Open Enrollment start",
+        date: "2026-11-01",
+        type: "hard",
+        consequence: "Cannot enroll in marketplace plan outside open enrollment without a QLE",
+        extensionAvailable: false,
+    },
+    {
+        workflowId: "healthcare/aca-enrollment",
+        label: "Open Enrollment end",
+        date: "2027-01-15",
+        type: "hard",
+        consequence: "Cannot enroll in marketplace plan outside open enrollment without a QLE",
+        extensionAvailable: false,
+    },
+    {
+        workflowId: "unemployment/claim-intake",
+        label: "File within 7 days of last day of work",
+        date: "2026-12-31",
+        type: "soft",
+        consequence: "Benefits may be delayed or reduced if filed late; state-specific rules apply",
+        extensionAvailable: false,
+    },
+];
+//# sourceMappingURL=deadlines.js.map

package/dist/src/workflows/deadlines.js.map

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