books

type Account struct {
	Number string      `json:"number"`
	Name   string      `json:"name"`
	Type   AccountType `json:"type"`
	Party  PartyType   `json:"party,omitempty"`
}

type AccountType string

type AskRequest struct {
	// Question is the plain-language question about the org's books, e.g. "what is my
	// MRR?". Longer than 2000 characters is truncated, never refused.
	Question string `json:"question"`
	// From is the RFC3339 start of the metric window. Empty means all time, treated as a
	// single reporting period (see monthsBetween).
	From string `json:"from,omitempty"`
	// To is the RFC3339 end of the metric window. Empty means up to now.
	To string `json:"to,omitempty"`
}

type AskResponse struct {
	// Answer is one or two sentences answering the question, every number in it taken
	// from Figures.
	Answer string `json:"answer"`
	// Figures are the grounded numbers the answer states, each already formatted.
	Figures []Figure `json:"figures"`
	// Followups are sharper questions to ask next, chosen from the same intent.
	Followups []string `json:"followups"`
	// Sources name the books reports the figures were computed from — "pnl",
	// "position", "trial".
	Sources []string `json:"sources"`
}

type BalanceLine struct {
	Account string      `json:"account,omitempty"`
	Name    string      `json:"name"`
	Type    AccountType `json:"type,omitempty"`
	Amount  int64       `json:"amount"` // cents, display sign
}

type BalanceSheet struct {
	AsOf             string        `json:"asOf,omitempty"`
	Assets           []BalanceLine `json:"assets"`
	Liabilities      []BalanceLine `json:"liabilities"`
	Equity           []BalanceLine `json:"equity"`
	TotalAssets      int64         `json:"totalAssets"`
	TotalLiabilities int64         `json:"totalLiabilities"`
	TotalEquity      int64         `json:"totalEquity"`
	Balanced         bool          `json:"balanced"` // TotalAssets == TotalLiabilities + TotalEquity
}

type BankQuestion struct {
	Connector  string `json:"connector"`
	ExternalID string `json:"externalId"`
	Prompt     string `json:"prompt"`
	Status     string `json:"status"`
	CreatedAt  string `json:"createdAt"`
}

type BankResult struct {
	Status         string `json:"status"`
	VoucherPosted  bool   `json:"voucherPosted"`
	QuestionRaised bool   `json:"questionRaised"`
	Skipped        bool   `json:"skipped"` // already processed (idempotent no-op)
}

type BankTally struct {
	Ingested   int `json:"ingested"`   // transactions seen
	Posted     int `json:"posted"`     // vouchers newly posted (outflow + reconciled)
	Reconciled int `json:"reconciled"` // inflows cleared against Square-clearing
	Questions  int `json:"questions"`  // unmatched inflows that raised a question
	Transfers  int `json:"transfers"`  // own-account moves recorded (no P&L)
	Skipped    int `json:"skipped"`    // already-processed idempotent no-ops
}

type BankTxn struct {
	Connector   string    `json:"connector"`
	ExternalID  string    `json:"externalId"`
	PostedAt    string    `json:"postedAt"` // RFC3339 posting time, ledger-comparable
	AmountCents int64     `json:"amountCents"`
	Currency    string    `json:"currency"`
	Description string    `json:"description"`
	Merchant    string    `json:"merchant"`
	Direction   Direction `json:"direction"`
}

type BankTxnRow struct {
	Connector      string    `json:"connector"`
	ExternalID     string    `json:"externalId"`
	PostedAt       string    `json:"postedAt"`
	AmountCents    int64     `json:"amountCents"`
	Currency       string    `json:"currency"`
	Direction      Direction `json:"direction"`
	Description    string    `json:"description,omitempty"`
	Merchant       string    `json:"merchant,omitempty"`
	MatchedVoucher string    `json:"matchedVoucher,omitempty"`
	Status         string    `json:"status"`
}

type BookRequest struct {
	// ScanID is the scanned document's file hash, as GET /v1/books/inbox and the scan
	// draft report it. It is the idempotency key: re-booking the same scan writes nothing.
	ScanID string `json:"scanId"`
	// Voucher is the reviewed voucher to post. Its source is FORCED to (scan, scanId)
	// server-side, so it can never be booked under another source's key.
	Voucher Voucher `json:"voucher"`
	// Override books this bill even when one of the SAME economic identity
	// (vendor, total, issue date) already posted — the explicit human confirmation that a
	// same-looking bill is a genuine second spend, not the same receipt re-scanned.
	Override bool `json:"override,omitempty"`
}

type BookResponse struct {
	// ScanID echoes the scan that was booked.
	ScanID string `json:"scanId"`
	// Posted is true when this call wrote the voucher, false when the same scan had
	// already booked and nothing was written.
	Posted bool `json:"posted"`
}

type Connector interface {
	Name() string
	Fetch(ctx context.Context, org, cursor string) (txns []BankTxn, nextCursor string, err error)
}

type Direction string

type Extracted struct {
	Merchant   string     `json:"merchant"`
	IssuedAt   string     `json:"issuedAt"` // YYYY-MM-DD
	TotalCents int64      `json:"totalCents"`
	TaxCents   int64      `json:"taxCents"`
	Currency   string     `json:"currency"`
	Category   string     `json:"category"` // proposed slug (software|cloud|office|…)
	LineItems  []LineItem `json:"lineItems,omitempty"`
	Note       string     `json:"note,omitempty"`
}

type Figure struct {
	// Label names the metric, e.g. "MRR" or "Runway".
	Label string `json:"label"`
	// Value is the figure already formatted through books' own money formatter, so a
	// consumer never re-derives it.
	Value string `json:"value"`
	// Period is the window the figure covers, e.g. "2026-07" or "all-time".
	Period string `json:"period,omitempty"`
}

type FinancialPackage struct {
	Org          string       `json:"org"`
	From         string       `json:"from,omitempty"`
	To           string       `json:"to,omitempty"`
	GeneratedAt  string       `json:"generatedAt"`
	TrialBalance TrialBalance `json:"trialBalance"`
	PnL          PnL          `json:"pnl"`
	BalanceSheet BalanceSheet `json:"balanceSheet"`
	GL           []GLRow      `json:"gl"`
}

type GLRow struct {
	ID         int64  `json:"id"`
	PostingAt  string `json:"postingAt"`
	Account    string `json:"account"`
	Debit      int64  `json:"debit"`
	Credit     int64  `json:"credit"`
	Against    string `json:"against,omitempty"`
	SourceKind string `json:"sourceKind"`
	SourceID   string `json:"sourceId"`
	Remarks    string `json:"remarks,omitempty"`
}

type Importer interface {
	Parse(data []byte) ([]BankTxn, error)
}

type InboxItem struct {
	ID         string     `json:"id"` // the file hash (== a scan's ScanID)
	Filename   string     `json:"filename,omitempty"`
	Status     string     `json:"status"`
	CreatedAt  string     `json:"createdAt"`
	Extracted  *Extracted `json:"extracted,omitempty"`
	Vendor     string     `json:"vendor,omitempty"`
	Category   string     `json:"category,omitempty"`
	Confidence string     `json:"confidence,omitempty"`
}

type Leg struct {
	// Account is the chart-of-accounts number this side posts to, e.g. "5300".
	Account string `json:"account"`
	// Debit is the leg's debit in exact cents. Set this or Credit, not both.
	Debit int64 `json:"debit"`
	// Credit is the leg's credit in exact cents. Set this or Debit, not both.
	Credit int64 `json:"credit"`
}

type LineItem struct {
	Description string `json:"description"`
	AmountCents int64  `json:"amountCents"`
}

type Metrics struct {
	From            string `json:"from,omitempty"`
	To              string `json:"to,omitempty"`
	Period          string `json:"period"`          // human label, e.g. "2026-07" or "all-time"
	Months          int    `json:"months"`          // window length used to normalize MRR / burn
	MRR             int64  `json:"mrr"`             // recurring revenue (4100) per month
	ARR             int64  `json:"arr"`             // MRR * 12
	Revenue         int64  `json:"revenue"`         // recognized revenue (all Income roots) over the period
	COGS            int64  `json:"cogs"`            // cost of goods (5000) over the period
	Burn            int64  `json:"burn"`            // total expense (all Expense roots) over the period
	GrossProfit     int64  `json:"grossProfit"`     // Revenue − COGS
	GrossMarginBps  int64  `json:"grossMarginBps"`  // GrossProfit / Revenue in basis points (7000 = 70%)
	NetIncome       int64  `json:"netIncome"`       // Revenue − Burn
	Cash            int64  `json:"cash"`            // Bank (1000) + Square clearing (1010) as of `to`
	DeferredRevenue int64  `json:"deferredRevenue"` // Customer Wallet (2000) liability as of `to`
	MonthlyBurn     int64  `json:"monthlyBurn"`     // net cash burned per month (>0 ⇒ losing cash)
	RunwayMonths    int64  `json:"runwayMonths"`    // Cash / MonthlyBurn; -1 = infinite (not burning)
}

type MetricsResponse struct {
	// From is the RFC3339 start of the reporting window, exclusive; absent for all time.
	From string `json:"from,omitempty"`
	// To is the RFC3339 end of the reporting window, inclusive; absent for up to now.
	To string `json:"to,omitempty"`
	// Period is the human window label, e.g. "2026-07" or "all-time".
	Period string `json:"period"`
	// Months is the window length in whole months used to normalize MRR and burn.
	Months int `json:"months"`
	// MRR is monthly recurring revenue in cents.
	MRR int64 `json:"mrr"`
	// ARR is annualized recurring revenue in cents (MRR × 12).
	ARR int64 `json:"arr"`
	// Revenue is recognized revenue in cents over the period.
	Revenue int64 `json:"revenue"`
	// COGS is cost of goods sold in cents over the period.
	COGS int64 `json:"cogs"`
	// Burn is total expense in cents over the period.
	Burn int64 `json:"burn"`
	// GrossProfit is Revenue − COGS, in cents.
	GrossProfit int64 `json:"grossProfit"`
	// GrossMarginBps is GrossProfit / Revenue in basis points (7000 = 70%).
	GrossMarginBps int64 `json:"grossMarginBps"`
	// NetIncome is Revenue − Burn, in cents.
	NetIncome int64 `json:"netIncome"`
	// Cash is the bank + processor-clearing balance in cents as of To.
	Cash int64 `json:"cash"`
	// DeferredRevenue is the customer-wallet liability in cents as of To.
	DeferredRevenue int64 `json:"deferredRevenue"`
	// MonthlyBurn is net cash burned per month in cents; 0 when not losing cash.
	MonthlyBurn int64 `json:"monthlyBurn"`
	// RunwayMonths is Cash / MonthlyBurn; -1 means infinite (the org is not burning).
	RunwayMonths int64 `json:"runwayMonths"`
	// Figures is the same snapshot rendered through books' one money formatter.
	Figures []Figure `json:"figures"`
}

type PartyType string

type PnL struct {
	From         string    `json:"from,omitempty"`
	To           string    `json:"to,omitempty"`
	Income       []PnLLine `json:"income"`
	Expense      []PnLLine `json:"expense"`
	TotalIncome  int64     `json:"totalIncome"`
	TotalExpense int64     `json:"totalExpense"`
	NetIncome    int64     `json:"netIncome"` // TotalIncome − TotalExpense
}

type PnLLine struct {
	Account string      `json:"account"`
	Name    string      `json:"name"`
	Type    AccountType `json:"type"`
	Amount  int64       `json:"amount"` // cents, display sign (income & expense both positive when normal)
}

type Question struct {
	ID       string `json:"id"`     // the source transaction id it concerns
	Kind     string `json:"kind"`   // outlier|reversal|roundoff|uncosted|overdrawn
	Text     string `json:"text"`   // the specific question to ask the founder
	Amount   string `json:"amount"` // formatted figure ($…)
	Account  string `json:"account,omitempty"`
	PostedAt string `json:"postedAt,omitempty"`
}

type QuestionsResponse struct {
	Questions []Question `json:"questions"`
}

type Rule struct {
	// Pattern is the merchant substring the rule matches on, case-insensitively. It is
	// also the key an upsert writes by.
	Pattern string `json:"pattern"`
	// Category is the COA expense account a matching bill books to. An upsert normalizes
	// a slug ("cloud") to its account number.
	Category string `json:"category"` // COA account number
	// Priority breaks ties: when several patterns match, the highest wins.
	Priority int `json:"priority"`
}

type ScanDraft struct {
	ScanID     string     `json:"scanId"` // file hash — the (scan, id) idempotency key
	Extracted  Extracted  `json:"extracted"`
	Vendor     string     `json:"vendor"`
	Category   string     `json:"category"`   // resolved COA expense account number
	Confidence string     `json:"confidence"` // auto | low
	Voucher    Voucher    `json:"voucher"`    // PROPOSED — not yet posted
	Balanced   bool       `json:"balanced"`   // Σdebit == Σcredit (always true when built)
	Questions  []Question `json:"questions,omitempty"`
}

type TellerLink struct {
	ApplicationID string `json:"applicationId"`
	Environment   string `json:"environment"`
}

type TrialBalance struct {
	From        string            `json:"from,omitempty"`
	To          string            `json:"to,omitempty"`
	Rows        []TrialBalanceRow `json:"rows"`
	TotalDebit  int64             `json:"totalDebit"`
	TotalCredit int64             `json:"totalCredit"`
	Balanced    bool              `json:"balanced"`
}

type TrialBalanceRow struct {
	Account       string      `json:"account"`
	Name          string      `json:"name"`
	Type          AccountType `json:"type"`
	OpeningDebit  int64       `json:"openingDebit"`
	OpeningCredit int64       `json:"openingCredit"`
	Debit         int64       `json:"debit"`  // period movement
	Credit        int64       `json:"credit"` // period movement
	ClosingDebit  int64       `json:"closingDebit"`
	ClosingCredit int64       `json:"closingCredit"`
}

type Txn struct {
	Date         string `json:"date"`
	Description  string `json:"description"`
	Vendor       string `json:"vendor,omitempty"`
	Category     string `json:"category"` // COA account number of the P&L line
	CategoryName string `json:"categoryName,omitempty"`
	Source       string `json:"source"` // source_kind: bank_txn | scan | commerce_txn
	AmountCents  int64  `json:"amountCents"`
	VoucherID    int64  `json:"voucherId"`
}

type VendorRow struct {
	// Canonical is the vendor's one true name, and the key an upsert writes by.
	Canonical string `json:"canonical"`
	// Aliases are the other spellings a receipt may print the vendor under; a scan
	// matching any of them resolves to this vendor.
	Aliases []string `json:"aliases,omitempty"`
	// DefaultCategory is the COA expense account new bills from this vendor book to.
	// An upsert normalizes a slug ("software") to its account number.
	DefaultCategory string `json:"defaultCategory,omitempty"` // COA account number
}

type Voucher struct {
	// SourceKind is the idempotency namespace naming what booked this, e.g. "scan".
	SourceKind string `json:"sourceKind"`
	// SourceID is the source event's own id within that namespace. Together with
	// SourceKind it is the key that makes a repeat posting a no-op.
	SourceID string `json:"sourceId"`
	// PostingAt is the RFC3339 instant the event posts at — the time every statement
	// window filters on.
	PostingAt string `json:"postingAt"`
	// Description is the human line for the event, e.g. the vendor a bill came from.
	Description string `json:"description"`
	// Legs are the sides of the posting. They must balance: Σdebit == Σcredit, give or
	// take the 2¢ round-off allowance.
	Legs []Leg `json:"legs"`
}