@profullstack/coinpay 0.13.0 → 0.15.0

package/src/statements-fetch.d.ts

@@ -14,6 +14,52 @@ export interface Institution {
   name: string;
   url: string | null;
   accounts: FetcherAccount[];
+  /** 'tax' for an agency (FTB, IRS), 'brokerage' for a brokerage with no linked account (Webull); absent for a bank. */
+  kind?: 'tax' | 'brokerage';
+}
+
+export interface TaxSource {
+  key: string;
+  kind: 'tax';
+  name: string;
+  login: string;
+  lockoutMinutes: number;
+  cloudWarning?: string;
+}
+
+export interface BrokerageSource {
+  key: string;
+  kind: 'brokerage';
+  name: string;
+  login: string;
+  statements?: string;
+}
+
+export interface BrokerageDocumentInfo {
+  category: 'statement' | 'tax';
+  docType: 'form' | null;
+  taxYear: number | null;
+  periodLabel: string;
+  title: string;
+}
+
+export interface ThrottleLimits {
+  windowMs: number;
+  perWindow: number;
+  perDay: number;
+  defaultLockoutMinutes: number;
+  marginMinutes: number;
+}
+
+export type ThrottleVerdict = { ok: true } | { ok: false; reason: 'locked' | 'daily_limit' | 'window_limit'; retryAt: string; message: string };
+
+export interface TaxDocumentInfo {
+  docType: 'transcript' | 'notice' | 'letter' | 'form' | 'return' | 'other';
+  code: string | null;
+  taxYear: number | null;
+  noticeDate: string | null;
+  periodLabel: string;
+  title: string;
 }
 
 export interface Period {
@@ -55,7 +101,7 @@ export interface Download {
   key: string | null;
 }
 
-export type PageStatus = 'ok' | 'login_needed' | 'no_statements';
+export type PageStatus = 'ok' | 'login_needed' | 'no_statements' | 'locked';
 
 export function lastFour(name: string): string | null;
 export function slug(value: string): string;
@@ -63,6 +109,37 @@ export function institutionKey(domain: string | null | undefined, name: string |
 export function groupInstitutions(accounts: ReadonlyArray<{ id: string; name: string; org_name?: string | null; org_domain?: string | null; is_hidden?: boolean }>): Institution[];
 export function pickInstitution(institutions: readonly Institution[], name: string): Institution;
 export const DRIVERS: ReadonlyArray<{ key: string; login: string; statements?: string }>;
+export const HOST_KEYS: ReadonlyArray<[RegExp, string]>;
+export const TAX_SOURCES: readonly TaxSource[];
+export function taxSource(key: string): TaxSource | null;
+export const BROKERAGE_SOURCES: readonly BrokerageSource[];
+export function brokerageSource(key: string): BrokerageSource | null;
+export function isBrokerageSource(institution: { key: string; kind?: string; accounts?: readonly unknown[] } | null | undefined): boolean;
+export function sourceMode(institution: { key: string; kind?: string; accounts?: readonly unknown[] }): 'statements' | 'tax' | 'documents';
+export function standaloneSources(): Institution[];
+export function withStandaloneSources(institutions: readonly Institution[]): Institution[];
+export function isTaxSource(institution: { key: string; kind?: string; accounts?: readonly unknown[] } | null | undefined): boolean;
+export function keepCandidate(mode: 'statements' | 'tax' | 'documents', label: string, context: string, href: string | null): boolean;
+export function collectScript(mode?: 'statements' | 'tax' | 'documents'): string;
+export const COLLECT_TAX: string;
+export const OPEN_TAX_DOCS: string;
+export const COLLECT_DOCS: string;
+export const OPEN_DOCUMENTS: string;
+export const PAGE_TEXT: string;
+export function classifyTaxDocument(download: { label?: string; context?: string; suggestedName?: string }, fetchedAt?: Date): TaxDocumentInfo;
+export function keepTaxDocument(options: Record<string, unknown>): Promise<Record<string, unknown>>;
+export function classifyBrokerageDocument(download: { label?: string; context?: string; suggestedName?: string }, fetchedAt?: Date): BrokerageDocumentInfo;
+export function keepBrokerageDocument(options: Record<string, unknown>): Promise<Record<string, unknown>>;
+export const TAX_THROTTLE: ThrottleLimits;
+export function evaluateThrottle(source: { attempts?: ReadonlyArray<string | { at: string }>; lockedUntil?: string | null; lockReason?: string | null }, now?: Date, limits?: ThrottleLimits): ThrottleVerdict;
+export function detectLockout(text: string | null | undefined): { minutes: number | null } | null;
+export function lockoutUntil(found: { minutes: number | null } | null, now?: Date, limits?: ThrottleLimits, defaultMinutes?: number): string;
+export function throttlePath(home: string): string;
+export function loadThrottle(home: string): { sources: Record<string, { attempts: Array<{ at: string; kind: string }>; lockedUntil: string | null; lockReason: string | null }> };
+export function saveThrottle(ledger: unknown, home: string): void;
+export function checkLocalThrottle(home: string, key: string, now?: Date, limits?: ThrottleLimits): ThrottleVerdict;
+export function takeLocalAttempt(home: string, key: string, kind: string, now?: Date, limits?: ThrottleLimits): ThrottleVerdict;
+export function recordLocalLockout(home: string, key: string, until: string, reason?: string): unknown;
 export function startUrls(institution: { key: string; url: string | null }, learnt?: string | null): { login: string | null; fetch: string | null };
 export function isSignInUrl(url: string): boolean;
 export function findDates(source: string | null | undefined): { date: string; precise: boolean }[];
@@ -106,10 +183,13 @@ export function fetchInstitution(
     renderMs?: number;
     onFile: (download: Download) => Promise<void> | void;
     log?: (line: string) => void;
+    mode?: 'statements' | 'tax' | 'documents';
+    watchLockout?: boolean;
+    pauseMs?: number;
   },
-): Promise<{ status: PageStatus; url: string; candidates: number; silent: string[] }>;
-export function loginWindow(browser: Browser, url: string): Promise<string | null>;
-export function assistWindow(browser: Browser, options: { start: string; onFile: (download: Download) => Promise<void> | void }): Promise<number>;
+): Promise<{ status: PageStatus; url: string; candidates: number; silent: string[]; lockout?: { minutes: number | null } }>;
+export function loginWindow(browser: Browser, url: string, options?: { onPageText?: (text: string) => unknown }): Promise<string | null>;
+export function assistWindow(browser: Browser, options: { start: string; onFile: (download: Download) => Promise<void> | void; onPageText?: (text: string) => unknown }): Promise<number>;
 export function loadLocal(home?: string): { institutions: Record<string, Record<string, unknown>>; entries: Record<string, unknown>[] };
 export function saveLocal(state: unknown, home?: string): void;
 export function archive(home: string, institution: Institution, account: FetcherAccount | null, period: Period | null, suggestedName: string, bytes: Uint8Array): string;
@@ -119,5 +199,6 @@ export function clientApi(client: unknown): Promise<{
   listAccounts(): Promise<unknown[]>;
   importStatement(options: Record<string, unknown>): Promise<unknown>;
   reportRun(run: Record<string, unknown>): Promise<unknown>;
+  fileDocument(options: Record<string, unknown>): Promise<{ document?: { id: string }; duplicate?: boolean }>;
 }>;
 export function retryImports(options: Record<string, unknown>): Promise<{ imported: number; skipped: number; failed: number }>;