@profullstack/coinpay 0.8.0 → 0.10.0

package/src/finances-reports.d.ts

@@ -0,0 +1,243 @@
+import type { CoinPayClient } from './client.js';
+
+export type ProviderCoverage = 'unknown' | 'partial' | 'available_window_fetched';
+export type ReconciliationStatus = 'not_attempted' | 'unavailable' | 'mismatch' | 'user_reconciled';
+export type ReportFormat = 'pdf' | 'html' | 'csv' | 'json';
+export type ReportStatus = 'queued' | 'generating' | 'ready' | 'failed' | 'superseded' | 'deleted';
+export type JobStatus = 'queued' | 'running' | 'waiting_for_budget' | 'partial' | 'failed' | 'completed' | 'cancelled';
+export type JobKind = 'backfill' | 'refresh' | 'scheduled_sync' | 'report';
+
+/** Thrown by every call here when the server answers with its structured error body. */
+export interface FinanceApiError extends Error {
+  code?: string;
+  status?: number;
+  retryable?: boolean;
+  jobId?: string;
+  reportId?: string;
+  retryAfter?: string | null;
+}
+
+export interface FinanceJob {
+  id: string;
+  kind: JobKind;
+  connectionId: string | null;
+  status: JobStatus;
+  params: Record<string, unknown>;
+  progress: Record<string, unknown>;
+  result: Record<string, unknown> | null;
+  errorCode: string | null;
+  errorMessage: string | null;
+  attempts: number;
+  nextAttemptAt: string | null;
+  cancelRequested: boolean;
+  createdAt: string;
+  startedAt: string | null;
+  finishedAt: string | null;
+  updatedAt: string;
+}
+
+export interface FinanceReportPeriod {
+  kind: 'month' | 'quarter' | 'custom';
+  selector: string;
+  label: string;
+  timezone: string;
+  start: string;
+  end: string;
+  effectiveEnd: string;
+  periodToDate: boolean;
+  cutoff: string;
+}
+
+export interface FinanceReportTotals {
+  currency: string;
+  credits: string;
+  debits: string;
+  net: string;
+  rows: number;
+}
+
+export interface FinanceReport {
+  id: string;
+  revision: number;
+  supersedesReportId: string | null;
+  supersededByReportId: string | null;
+  jobId: string | null;
+  period: FinanceReportPeriod;
+  scope: 'all' | 'business' | 'personal';
+  accountIds: string[];
+  includeHidden: boolean;
+  includePending: boolean;
+  strict: boolean;
+  status: ReportStatus;
+  local_export_complete: boolean | null;
+  provider_coverage: ProviderCoverage | null;
+  reconciliation_status: ReconciliationStatus;
+  datasetHash: string | null;
+  rowCount: number | null;
+  pendingCount: number | null;
+  totals: FinanceReportTotals[] | null;
+  warnings: string[];
+  rendererVersion: string | null;
+  errorCode: string | null;
+  errorMessage: string | null;
+  artifacts: Array<{ format: ReportFormat; bytes: number; sha256: string }>;
+  createdAt: string;
+  generatedAt: string | null;
+  notice: string;
+}
+
+export interface BinaryResponse {
+  bytes: Uint8Array;
+  contentType: string;
+  filename: string | null;
+  sha256: string | null;
+  headers: Record<string, string>;
+}
+
+export interface FinanceStatement {
+  id: string;
+  accountId: string;
+  institutionLabel: string | null;
+  label: string;
+  cycle: 'monthly' | 'quarterly' | 'custom';
+  periodStart: string;
+  periodEnd: string;
+  timezone: string;
+  notes: string | null;
+  originalFilename: string | null;
+  contentType: string;
+  bytes: number;
+  sha256: string;
+  scanState: 'quarantined' | 'clean' | 'rejected';
+  scanReason: string | null;
+  provenance: string;
+  verified: false;
+  reconciliation: FinanceReconciliation | null;
+  createdAt: string;
+}
+
+export interface FinanceReconciliation {
+  id: string;
+  statementId: string;
+  reportId: string;
+  accountId: string;
+  currency: string;
+  entered: { opening: string; closing: string; credits: string | null; debits: string | null };
+  signConvention: 'as_stated' | 'liability_positive';
+  normalized: { opening: string; closing: string };
+  expectedClosing: string;
+  difference: string;
+  state: 'matched' | 'mismatch' | 'unavailable' | 'user_reconciled' | 'invalidated';
+  acknowledged: boolean;
+  datasetHash: string | null;
+  version: number;
+  createdAt: string;
+  invalidatedAt: string | null;
+  bankVerified: false;
+}
+
+export interface AccountCoverage {
+  accountId: string;
+  name: string | null;
+  org_name: string | null;
+  currency: string | null;
+  coverage: ProviderCoverage;
+  fraction: number;
+  gaps: Array<{ start: string; end: string }>;
+  warnings: string[];
+  capped: boolean;
+  rowsRejected: number;
+}
+
+export interface PeriodSelection {
+  period?: string;
+  from?: string;
+  to?: string;
+  timezone?: string;
+}
+
+export function connectSimpleFin(
+  client: CoinPayClient,
+  options: { setupToken: string; label?: string; protocolVersion?: 1 | 2; idempotencyKey?: string },
+): Promise<{ connection: Record<string, unknown>; replayed?: boolean }>;
+export function disconnectFinanceConnection(client: CoinPayClient, connectionId: string): Promise<{ connection: Record<string, unknown>; note: string }>;
+export function describeFinanceConnection(
+  client: CoinPayClient,
+  connectionId: string,
+): Promise<{ connection: Record<string, unknown>; deletionWouldRemove: { accounts: number; transactions: number; statements: number; reports: number } }>;
+export function deleteFinanceConnection(client: CoinPayClient, connectionId: string, options: { confirm: true }): Promise<{ success: boolean; removed: Record<string, number> }>;
+export function setFinanceSyncConsent(client: CoinPayClient, connectionId: string, dailySync: boolean): Promise<{ connection: Record<string, unknown> }>;
+
+export function createBackfillJob(
+  client: CoinPayClient,
+  options: PeriodSelection & { connectionId?: string; idempotencyKey?: string },
+): Promise<{ jobs: FinanceJob[]; job: FinanceJob; timezone?: { timezone: string; source: 'request' | 'saved' } }>;
+export function createRefreshJob(client: CoinPayClient, options: { connectionId: string; days?: number; idempotencyKey?: string }): Promise<{ jobs: FinanceJob[]; job: FinanceJob }>;
+export function getFinanceJob(client: CoinPayClient, jobId: string): Promise<FinanceJob>;
+export function listFinanceJobs(client: CoinPayClient, options?: { limit?: number; connectionId?: string }): Promise<FinanceJob[]>;
+export function cancelFinanceJob(client: CoinPayClient, jobId: string): Promise<FinanceJob>;
+export function waitForFinanceJob(
+  client: CoinPayClient,
+  jobId: string,
+  options?: { intervalMs?: number; timeoutMs?: number; onProgress?: (job: FinanceJob) => void; sleep?: (ms: number) => Promise<void> },
+): Promise<FinanceJob>;
+
+export function getFinanceCoverage(
+  client: CoinPayClient,
+  options: PeriodSelection & { accountIds?: string[]; includeHidden?: boolean },
+): Promise<{ period: FinanceReportPeriod; provider_coverage: ProviderCoverage; accounts: AccountCoverage[] }>;
+
+export function createFinanceReport(
+  client: CoinPayClient,
+  options: PeriodSelection & {
+    accountIds?: string[];
+    scope?: 'all' | 'business' | 'personal';
+    includeHidden?: boolean;
+    includePendingAppendix?: boolean;
+    formats?: ReportFormat[];
+    strict?: boolean;
+    idempotencyKey?: string;
+  },
+): Promise<{ report: FinanceReport; job: FinanceJob }>;
+export function listFinanceReports(client: CoinPayClient, options?: { limit?: number; offset?: number }): Promise<{ reports: FinanceReport[]; total: number }>;
+export function getFinanceReport(client: CoinPayClient, reportId: string): Promise<{ report: FinanceReport; job: FinanceJob | null }>;
+export function deleteFinanceReport(client: CoinPayClient, reportId: string): Promise<{ success: boolean; note: string }>;
+export function waitForFinanceReport(
+  client: CoinPayClient,
+  reportId: string,
+  options?: { intervalMs?: number; timeoutMs?: number; onProgress?: (data: { report: FinanceReport; job: FinanceJob | null }) => void; sleep?: (ms: number) => Promise<void> },
+): Promise<{ report: FinanceReport; job: FinanceJob | null }>;
+export function downloadFinanceReport(client: CoinPayClient, reportId: string, options?: { format?: ReportFormat }): Promise<BinaryResponse>;
+
+export function importFinanceStatement(
+  client: CoinPayClient,
+  options: PeriodSelection & {
+    file: Uint8Array | Blob;
+    filename?: string;
+    accountId: string;
+    institutionLabel?: string;
+    cycle?: 'monthly' | 'quarterly' | 'custom';
+    notes?: string;
+  },
+): Promise<{ statement: FinanceStatement; duplicateOf: string | null; note: string }>;
+export function listFinanceStatements(
+  client: CoinPayClient,
+  options?: PeriodSelection & { accountId?: string; limit?: number },
+): Promise<FinanceStatement[]>;
+export function getFinanceStatement(client: CoinPayClient, statementId: string): Promise<{ statement: FinanceStatement; reconciliations: FinanceReconciliation[] }>;
+export function downloadFinanceStatement(client: CoinPayClient, statementId: string): Promise<BinaryResponse>;
+export function deleteFinanceStatement(client: CoinPayClient, statementId: string): Promise<{ success: boolean; note: string }>;
+export function reconcileFinanceStatement(
+  client: CoinPayClient,
+  statementId: string,
+  options: {
+    reportId: string;
+    opening: string;
+    closing: string;
+    credits?: string;
+    debits?: string;
+    currency: string;
+    signConvention?: 'as_stated' | 'liability_positive';
+    acknowledge?: boolean;
+  },
+): Promise<FinanceReconciliation>;

package/src/finances-reports.js

@@ -0,0 +1,257 @@
+/**
+ * Finance reports, sync jobs, coverage and the statement library.
+ *
+ * Every function takes a `CoinPayClient` authenticated with a merchant
+ * session. Nothing here computes a total: the server freezes each report's
+ * rows and sums them exactly, and these calls fetch what it produced. A
+ * download returns bytes, never a JSON-wrapped blob.
+ */
+
+function query(params) {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined || value === null || value === '') continue;
+    if (Array.isArray(value)) {
+      for (const v of value) search.append(key, String(v));
+    } else {
+      search.set(key, String(value));
+    }
+  }
+  const s = search.toString();
+  return s ? `?${s}` : '';
+}
+
+function headersWith(idempotencyKey) {
+  return idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {};
+}
+
+/** Surface the server's structured error `{ error: { code, message } }` as an Error with `.code`. */
+async function call(client, endpoint, options = {}) {
+  try {
+    return await client.request(endpoint, options);
+  } catch (err) {
+    const body = err && err.response && err.response.error;
+    if (body && typeof body === 'object') {
+      const wrapped = new Error(body.message || err.message);
+      wrapped.code = body.code;
+      wrapped.status = err.status;
+      wrapped.retryable = body.retryable === true;
+      wrapped.jobId = body.jobId;
+      wrapped.reportId = body.reportId;
+      wrapped.retryAfter = body.retryAfter;
+      wrapped.response = err.response;
+      throw wrapped;
+    }
+    if (err && err.response && typeof err.response.code === 'string' && !err.code) err.code = err.response.code;
+    throw err;
+  }
+}
+
+// ── Connections ──
+
+/**
+ * Claim a SimpleFIN setup token. The token is single-use; the server checks
+ * everything it can before spending it and says plainly when the outcome is
+ * unknown (`err.code === 'claim_outcome_unknown'`).
+ */
+export async function connectSimpleFin(client, { setupToken, label, protocolVersion, idempotencyKey } = {}) {
+  if (!setupToken || !String(setupToken).trim()) throw new Error('A setup token is required');
+  return call(client, '/finances/connections', {
+    method: 'POST',
+    headers: headersWith(idempotencyKey),
+    body: JSON.stringify({ setupToken: String(setupToken).trim(), label, protocolVersion }),
+  });
+}
+
+/** Stop future syncs and remove the credential; history is kept. */
+export async function disconnectFinanceConnection(client, connectionId) {
+  return call(client, `/finances/connections/${encodeURIComponent(connectionId)}/disconnect`, { method: 'POST', body: '{}' });
+}
+
+/** What deleting a connection would remove. */
+export async function describeFinanceConnection(client, connectionId) {
+  return call(client, `/finances/connections/${encodeURIComponent(connectionId)}`);
+}
+
+/** Delete a connection and everything under it. `confirm` must be true. */
+export async function deleteFinanceConnection(client, connectionId, { confirm = false } = {}) {
+  if (!confirm) throw new Error('Deleting a connection removes its account data; pass { confirm: true }');
+  return call(client, `/finances/connections/${encodeURIComponent(connectionId)}?confirm=yes`, {
+    method: 'DELETE',
+    headers: { 'X-Confirm-Delete': 'yes' },
+  });
+}
+
+/** Opt a connection in or out of a once-daily background sync. */
+export async function setFinanceSyncConsent(client, connectionId, dailySync) {
+  return call(client, `/finances/connections/${encodeURIComponent(connectionId)}/consent`, {
+    method: 'POST',
+    body: JSON.stringify({ dailySync: dailySync === true }),
+  });
+}
+
+// ── Jobs ──
+
+/** Queue a period backfill (`{ period: '2026-Q2' }` or `{ from, to }`). Answers 202 with the job(s). */
+export async function createBackfillJob(client, { connectionId, period, from, to, timezone, idempotencyKey } = {}) {
+  return call(client, '/finances/sync-jobs', {
+    method: 'POST',
+    headers: headersWith(idempotencyKey),
+    body: JSON.stringify({ kind: 'backfill', connectionId, period, from, to, timezone }),
+  });
+}
+
+/** Queue a background rolling refresh of one connection. */
+export async function createRefreshJob(client, { connectionId, days, idempotencyKey } = {}) {
+  return call(client, '/finances/sync-jobs', {
+    method: 'POST',
+    headers: headersWith(idempotencyKey),
+    body: JSON.stringify({ kind: 'refresh', connectionId, days }),
+  });
+}
+
+export async function getFinanceJob(client, jobId) {
+  const data = await call(client, `/finances/jobs/${encodeURIComponent(jobId)}`);
+  return data.job;
+}
+
+export async function listFinanceJobs(client, { limit, connectionId } = {}) {
+  const data = await call(client, `/finances/jobs${query({ limit, connection: connectionId })}`);
+  return data.jobs || [];
+}
+
+export async function cancelFinanceJob(client, jobId) {
+  const data = await call(client, `/finances/jobs/${encodeURIComponent(jobId)}/cancel`, { method: 'POST', body: '{}' });
+  return data.job;
+}
+
+const TERMINAL_JOB = new Set(['completed', 'failed', 'cancelled', 'partial']);
+
+/**
+ * Poll a job until it reaches a terminal state or `waiting_for_budget`
+ * (which can take hours to clear and is reported, not waited out).
+ */
+export async function waitForFinanceJob(client, jobId, { intervalMs = 3000, timeoutMs = 30 * 60 * 1000, onProgress, sleep } = {}) {
+  const started = Date.now();
+  const pause = sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  for (;;) {
+    const job = await getFinanceJob(client, jobId);
+    if (onProgress) onProgress(job);
+    if (TERMINAL_JOB.has(job.status) || job.status === 'waiting_for_budget') return job;
+    if (Date.now() - started > timeoutMs) return job;
+    await pause(intervalMs);
+  }
+}
+
+// ── Coverage ──
+
+export async function getFinanceCoverage(client, { period, from, to, timezone, accountIds, includeHidden } = {}) {
+  return call(client, `/finances/coverage${query({ period, from, to, timezone, account: accountIds, hidden: includeHidden ? 1 : undefined })}`);
+}
+
+// ── Reports ──
+
+/**
+ * Create an immutable report revision. Answers 202 with `{ report, job }`;
+ * use `waitForFinanceReport` to block until it is ready.
+ */
+export async function createFinanceReport(client, {
+  period, from, to, timezone, accountIds, scope, includeHidden, includePendingAppendix, formats, strict, idempotencyKey,
+} = {}) {
+  return call(client, '/finances/reports', {
+    method: 'POST',
+    headers: headersWith(idempotencyKey),
+    body: JSON.stringify({ period, from, to, timezone, accountIds, scope, includeHidden, includePendingAppendix, formats, strict }),
+  });
+}
+
+export async function listFinanceReports(client, { limit, offset } = {}) {
+  return call(client, `/finances/reports${query({ limit, offset })}`);
+}
+
+export async function getFinanceReport(client, reportId) {
+  return call(client, `/finances/reports/${encodeURIComponent(reportId)}`);
+}
+
+export async function deleteFinanceReport(client, reportId) {
+  return call(client, `/finances/reports/${encodeURIComponent(reportId)}`, { method: 'DELETE' });
+}
+
+const TERMINAL_REPORT = new Set(['ready', 'failed', 'superseded', 'deleted']);
+
+export async function waitForFinanceReport(client, reportId, { intervalMs = 3000, timeoutMs = 30 * 60 * 1000, onProgress, sleep } = {}) {
+  const started = Date.now();
+  const pause = sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  for (;;) {
+    const data = await getFinanceReport(client, reportId);
+    if (onProgress) onProgress(data);
+    if (TERMINAL_REPORT.has(data.report.status)) return data;
+    if (data.job && data.job.status === 'waiting_for_budget') return data;
+    if (Date.now() - started > timeoutMs) return data;
+    await pause(intervalMs);
+  }
+}
+
+/**
+ * Download one format of a ready report. Resolves to
+ * `{ bytes: Uint8Array, contentType, filename, sha256, headers }`.
+ */
+export async function downloadFinanceReport(client, reportId, { format = 'pdf' } = {}) {
+  return client.requestBinary(`/finances/reports/${encodeURIComponent(reportId)}/download${query({ format })}`);
+}
+
+// ── Statements ──
+
+/**
+ * Import an original PDF. `file` is a Uint8Array/Buffer/Blob of the bytes;
+ * nothing is read out of it into the ledger.
+ */
+export async function importFinanceStatement(client, {
+  file, filename = 'statement.pdf', accountId, period, from, to, timezone, institutionLabel, cycle, notes,
+} = {}) {
+  if (!file) throw new Error('A PDF file is required');
+  if (!accountId) throw new Error('accountId is required');
+  const form = new FormData();
+  const blob = file instanceof Blob ? file : new Blob([file], { type: 'application/pdf' });
+  form.append('file', blob, filename);
+  form.append('accountId', accountId);
+  if (period) form.append('period', period);
+  if (from) form.append('from', from);
+  if (to) form.append('to', to);
+  if (timezone) form.append('timezone', timezone);
+  if (institutionLabel) form.append('institutionLabel', institutionLabel);
+  if (cycle) form.append('cycle', cycle);
+  if (notes) form.append('notes', notes);
+  return client.requestForm('/finances/statements', form);
+}
+
+export async function listFinanceStatements(client, { accountId, period, from, to, timezone, limit } = {}) {
+  const data = await call(client, `/finances/statements${query({ account: accountId, period, from, to, timezone, limit })}`);
+  return data.statements || [];
+}
+
+export async function getFinanceStatement(client, statementId) {
+  return call(client, `/finances/statements/${encodeURIComponent(statementId)}`);
+}
+
+export async function downloadFinanceStatement(client, statementId) {
+  return client.requestBinary(`/finances/statements/${encodeURIComponent(statementId)}/download`);
+}
+
+export async function deleteFinanceStatement(client, statementId) {
+  return call(client, `/finances/statements/${encodeURIComponent(statementId)}`, { method: 'DELETE' });
+}
+
+/**
+ * Enter a statement's balances and check them against one report revision.
+ * Amounts are decimal strings in the account currency.
+ */
+export async function reconcileFinanceStatement(client, statementId, {
+  reportId, opening, closing, credits, debits, currency, signConvention, acknowledge,
+} = {}) {
+  const data = await call(client, `/finances/statements/${encodeURIComponent(statementId)}/reconciliations`, {
+    method: 'POST',
+    body: JSON.stringify({ reportId, opening, closing, credits, debits, currency, signConvention, acknowledge }),
+  });
+  return data.reconciliation;
+}