app

type Actor struct {
	Kind        ActorKind
	MemberID    string
	HouseholdID string
	Label       string // "Alex", "Claude Desktop (MCP)", "scheduler"
	Scope       Scope
}

type ActorKind string

type AddDocumentInput struct {
	SubscriptionID string
	ChargeID       string
	Kind           string
	Name           string
	Data           []byte
	DryRun         bool
}

type AgentContext struct {
	Markdown string `json:"markdown" jsonschema:"human-readable briefing of the household, its subscriptions and how Exhale works"`
}

type AttentionList struct {
	Unconfirmed            []ChargeView           `json:"unconfirmed" jsonschema:"charges whose due date passed and that are not marked paid, failed or skipped"`
	ExpiringPaymentMethods []domain.PaymentMethod `json:"expiringPaymentMethods" jsonschema:"payment methods expiring within 45 days"`
	Deadlines              []ChargeView           `` /* 128-byte string literal not displayed */
	// Delivery reports reminders that could not be delivered lately, so a
	// broken channel does not go unnoticed.
	Delivery *DeliveryProblem `json:"delivery,omitempty" jsonschema:"set when reminders failed to be delivered in the last 7 days"`
}

type AuditEntry struct {
	ID         string `json:"id"`
	At         string `json:"at"`
	ActorKind  string `json:"actorKind"`
	ActorLabel string `json:"actor"`
	Action     string `json:"action"`
	Entity     string `json:"entity"`
	EntityID   string `json:"entityId"`
	UndoneBy   string `json:"undoneBy,omitempty"`
}

type AuditLog struct {
	Entries []AuditEntry `json:"entries"`
}

type AuditLogInput struct {
	Limit int `json:"limit,omitempty" query:"limit" jsonschema:"default 50" maximum:"500"`
}

type AuditRef struct {
	ID       string `json:"id"`
	Action   string `json:"action"`
	Entity   string `json:"entity"`
	EntityID string `json:"entityId"`
}

type AuditReport struct {
	Duplicates      []DuplicateGroup     `` /* 128-byte string literal not displayed */
	PriceIncreases  []PriceIncrease      `json:"priceIncreases" jsonschema:"prices that went up in the last 12 months"`
	TrialsEnding    []ChargeView         `json:"trialsEnding" jsonschema:"free trials that turn into a charge within 14 days"`
	CancelDeadlines []ChargeView         `json:"cancelDeadlines" jsonschema:"last days to cancel within 30 days that have no decision yet"`
	Expiring        []ChargeView         `json:"expiring" jsonschema:"manual renewals that expire within 60 days"`
	BigCharges      []ChargeView         `json:"bigCharges" jsonschema:"yearly or rarer charges due within 30 days"`
	CardsExpiring   []CardImpact         `json:"cardsExpiring" jsonschema:"payment methods expiring within 45 days and the subscriptions that use them"`
	Unconfirmed     []ChargeView         `json:"unconfirmed" jsonschema:"charges whose date passed without being confirmed"`
	NotUsed         []UnusedSubscription `json:"notUsed" jsonschema:"subscriptions the member said they no longer use"`
	Findings        int                  `json:"findings" jsonschema:"total number of findings"`
	CheaperPlans    []CheaperPlan        `json:"cheaperPlans" jsonschema:"subscriptions where the member recorded another price (e.g. yearly) that costs less per year"`
}

type Balances struct {
	Month        string          `json:"month"`
	MainCurrency string          `json:"mainCurrency"`
	Members      []MemberBalance `json:"members"`
	Transfers    []Transfer      `json:"transfers" jsonschema:"the fewest payments that settle the month"`
	Charges      []SharedCharge  `json:"charges" jsonschema:"the split charges behind the numbers (paid and still pending this month)"`
}

type BalancesInput struct {
	Month string `json:"month,omitempty" query:"month" jsonschema:"YYYY-MM, default the current month"`
}

type Binding struct {
	Meta
	In, Out reflect.Type
	Invoke  func(s *Service, ctx context.Context, a Actor, raw json.RawMessage) (any, error)
}

type BootstrapInput struct {
	HouseholdName string
	OwnerName     string
	OwnerEmail    string
	Currency      string
	Timezone      string
	Locale        string
}

type Breakdown struct {
	Period      string         `json:"period" enum:"month,year"`
	By          string         `json:"by" enum:"category,payment_method,subscription"`
	Total       money.Money    `json:"total" doc:"in the main currency"`
	Rows        []BreakdownRow `json:"rows" doc:"largest first"`
	Converted   bool           `json:"converted" doc:"other currencies were converted at the latest ECB reference rate"`
	Unconverted []string       `json:"unconverted" doc:"currencies without a known rate, left out"`
}

type BreakdownRow struct {
	Label          string      `json:"label"`
	SubscriptionID string      `json:"subscriptionId,omitempty" doc:"when the breakdown is by subscription"`
	Amount         money.Money `json:"amount"`
	Count          int         `json:"count"`
}

type BulkItem struct {
	ID      string        `json:"id"`
	Name    string        `json:"name"`
	Changes []FieldChange `json:"changes" jsonschema:"empty: nothing changes for this one"`
}

type BulkResult struct {
	Items    []BulkItem `json:"items"`
	Changed  int        `json:"changed" jsonschema:"subscriptions that change"`
	AuditIDs []string   `json:"auditIds" jsonschema:"pass them all to undo (auditIds) to revert the whole change; empty in a dry run"`
	DryRun   bool       `json:"dryRun,omitempty"`
}

type BulkUpdateInput struct {
	IDs             []string `json:"ids" jsonschema:"subscription ids (sub_…), at most 500" minItems:"1" maxItems:"500"`
	Action          string   `` /* 234-byte string literal not displayed */
	CategoryID      *string  `json:"categoryId,omitempty" jsonschema:"with update: the new category; empty string removes it"`
	PaymentMethodID *string  `json:"paymentMethodId,omitempty" jsonschema:"with update: the new payment method; empty string removes it"`
	AddTags         []string `json:"addTags,omitempty" jsonschema:"with update: tags to add to each"`
	RemoveTags      []string `json:"removeTags,omitempty" jsonschema:"with update: tags to remove from each"`
	DryRun          bool     `json:"dryRun,omitempty" jsonschema:"preview what changes for each subscription; nothing is saved"`
}

type CalendarEvent struct {
	Date           engine.Date `json:"date"`
	Kind           string      `` /* 158-byte string literal not displayed */
	Title          string      `json:"title"`
	SubscriptionID string      `json:"subscriptionId"`
	Subscription   string      `json:"subscription"`
	Amount         money.Money `json:"amount"`
	ChargeID       string      `json:"chargeId,omitempty" jsonschema:"empty for dates projected from the schedule beyond the next few months"`
	Status         string      `json:"status,omitempty" jsonschema:"charge status; projected dates are pending"`
	Projected      bool        `json:"projected" jsonschema:"computed from the schedule; the charge does not exist yet"`
}

type CalendarInput struct {
	From string `json:"from,omitempty" query:"from" jsonschema:"first day, YYYY-MM-DD (default today)"`
	To   string `json:"to,omitempty" query:"to" jsonschema:"last day, YYYY-MM-DD (default one year after from; at most three years)"`
}

type CalendarView struct {
	From   engine.Date     `json:"from"`
	To     engine.Date     `json:"to"`
	Events []CalendarEvent `json:"events"`
}

type CardImpact struct {
	PaymentMethod domain.PaymentMethod `json:"paymentMethod"`
	Subscriptions []SubscriptionRef    `json:"subscriptions" jsonschema:"active subscriptions that will fail when it expires"`
}

type CardNotice struct {
	PaymentMethod domain.PaymentMethod
	DaysLeft      int
	Subscriptions []SubscriptionView
	// Others are the payment methods they can move to.
	Others []domain.PaymentMethod
}

type CategoryOut struct {
	Category domain.Category `json:"category"`
}

type CategorySpend struct {
	Category string      `json:"category"`
	Monthly  money.Money `json:"monthly" jsonschema:"in the main currency"`
	Count    int         `json:"count"`
}

type ChangeChargeAmountInput struct {
	ChargeID string `json:"chargeId"`
	Amount   string `json:"amount" jsonschema:"new amount as a decimal string, in the subscription currency"`
	Scope    string `` /* 164-byte string literal not displayed */
	DryRun   bool   `json:"dryRun,omitempty"`
}

type ChangeChargeDateInput struct {
	ChargeID string `json:"chargeId" jsonschema:"charge id (chg_…)"`
	NewDate  string `json:"newDate" jsonschema:"new due date, YYYY-MM-DD"`
	Scope    string `` /* 149-byte string literal not displayed */
	DryRun   bool   `json:"dryRun,omitempty"`
}

type ChargeList struct {
	From    engine.Date  `json:"from"`
	To      engine.Date  `json:"to"`
	Charges []ChargeView `json:"charges"`
}

type ChargeMatch struct {
	Charge      ChargeView    `json:"charge"`
	Transaction StatementLine `json:"transaction"`
	Paid        money.Money   `json:"paid" jsonschema:"what the transaction took"`
	Action      string        `` /* 196-byte string literal not displayed */
	// PriceChange is set when the bank took another amount in the same
	// currency: ask whether it is the new price.
	PriceChange *PriceChangeHint `` /* 194-byte string literal not displayed */
}

type ChargeResult struct {
	Charge       ChargeView       `json:"charge"`
	Subscription SubscriptionView `json:"subscription"`
	AuditID      string           `json:"auditId,omitempty" jsonschema:"pass to undo to revert this change"`
	DryRun       bool             `json:"dryRun,omitempty"`
	// PriceChange is set when a charge was paid at a different amount than
	// expected, in the same currency: probably a new price.
	PriceChange *PriceChangeHint `` /* 175-byte string literal not displayed */
}

type ChargeView struct {
	domain.Charge
	SubscriptionName string `json:"subscriptionName"`
	PaymentMethod    string `json:"paymentMethod,omitempty"`
	Delayed          bool   `json:"delayed" jsonschema:"true when the charge was moved from its scheduled date"`
	DaysUntil        int    `json:"daysUntil" jsonschema:"days from today to the due date (negative if overdue)"`
	// Kind tells what this date means to the member.
	Kind         string      `` /* 190-byte string literal not displayed */
	CancelBy     engine.Date `json:"cancelBy,omitzero" jsonschema:"last day to cancel before this charge, when the subscription has a notice period"`
	CancelPassed bool        `json:"cancelPassed" jsonschema:"the last day to cancel before this charge has passed: it will renew"`
	Logo         string      `json:"logo,omitempty" jsonschema:"path of the subscription's uploaded logo, if any"`
}

type CheaperPlan struct {
	Subscription SubscriptionRef `json:"subscription"`
	Other        domain.AltPrice `json:"other" jsonschema:"the other price and the period it covers"`
	PlanSwitch
}

type CreateCategoryInput struct {
	Name   string `json:"name"`
	Color  string `json:"color,omitempty" jsonschema:"hex color, e.g. #7c6cff"`
	DryRun bool   `json:"dryRun,omitempty"`
}

type CreateSubscriptionInput struct {
	Name            string `json:"name" jsonschema:"service name, e.g. Netflix Premium" minLength:"1" maxLength:"120"`
	Price           string `json:"price" jsonschema:"price per charge as a decimal string, e.g. 12.99"`
	Currency        string `json:"currency" jsonschema:"ISO 4217 code, e.g. EUR"`
	Interval        int    `json:"interval,omitempty" jsonschema:"number of units between charges, default 1" minimum:"1"`
	Unit            string `json:"unit,omitempty" jsonschema:"day, week, month (default) or year" enum:"day,week,month,year"`
	FirstCharge     string `` /* 126-byte string literal not displayed */
	DayRule         string `` /* 470-byte string literal not displayed */
	WeekendShift    string `` /* 343-byte string literal not displayed */
	CategoryID      string `json:"categoryId,omitempty"`
	PaymentMethodID string `json:"paymentMethodId,omitempty"`
	PayerID         string `json:"payerId,omitempty" jsonschema:"member who pays; defaults to the caller"`
	Private         bool   `json:"private,omitempty" jsonschema:"only visible to its creator and payer"`
	URL             string `json:"url,omitempty"`
	Notes           string `json:"notes,omitempty"`
	AutoConfirm     bool   `json:"autoConfirm,omitempty" jsonschema:"mark each charge paid automatically on its due date"`
	ReminderDays    []int  `json:"reminderDays,omitempty" jsonschema:"days before each charge to remind, default [3, 0]"`
	EndDate         string `json:"endDate,omitempty" jsonschema:"last possible charge date, YYYY-MM-DD"`
	Status          string `` /* 210-byte string literal not displayed */
	TermsInput
	ExtrasInput
	DryRun bool `json:"dryRun,omitempty" jsonschema:"preview the result without saving"`
}

type DecideRenewalInput struct {
	ChargeID string `json:"chargeId"`
	Decision string `json:"decision" jsonschema:"keep: stop asking before the last day to cancel; undecided: ask again" enum:"keep,undecided"`
	DryRun   bool   `json:"dryRun,omitempty"`
}

type DeleteCategoryInput struct {
	ID     string `json:"id" jsonschema:"category id (cat_…)"`
	DryRun bool   `json:"dryRun,omitempty"`
}

type DeleteDocumentInput struct {
	ID     string `json:"id" jsonschema:"document id (doc_…)"`
	DryRun bool   `json:"dryRun,omitempty"`
}

type DeletePaymentMethodInput struct {
	ID     string `json:"id" jsonschema:"payment method to delete (pm_…)"`
	MoveTo string `json:"moveTo,omitempty" jsonschema:"payment method that takes over its subscriptions; empty leaves them without one"`
	DryRun bool   `json:"dryRun,omitempty"`
}

type DeleteResult struct {
	Deleted string `json:"deleted"`
	AuditID string `json:"auditId" jsonschema:"pass to undo to restore"`
}

type DeleteSubscriptionInput struct {
	ID     string `json:"id"`
	DryRun bool   `json:"dryRun,omitempty"`
}

type DeleteTagInput struct {
	Tag    string `json:"tag" jsonschema:"the tag to remove (case does not matter)"`
	DryRun bool   `json:"dryRun,omitempty"`
}

type DeliveryProblem struct {
	Failed    int    `json:"failed" jsonschema:"reminders not delivered in the last 7 days"`
	NoChannel int    `json:"noChannel" jsonschema:"of those, how many had nowhere to go (no chat or channel linked)"`
	LastError string `json:"lastError,omitempty" jsonschema:"most recent delivery error"`
}

type DismissDuplicateInput struct {
	Key    string `json:"key" jsonschema:"key of the duplicate group, from audit"`
	DryRun bool   `json:"dryRun,omitempty"`
}

type DismissResult struct {
	Key    string `json:"key"`
	DryRun bool   `json:"dryRun,omitempty"`
}

type Document struct {
	ID             string    `json:"id"`
	SubscriptionID string    `json:"subscriptionId"`
	ChargeID       string    `json:"chargeId,omitempty" jsonschema:"the charge this invoice or receipt belongs to, if any"`
	Kind           string    `` /* 144-byte string literal not displayed */
	Name           string    `json:"name" jsonschema:"file name as uploaded"`
	MediaType      string    `json:"mediaType" jsonschema:"application/pdf, image/png, image/jpeg or image/webp"`
	Size           int64     `json:"size" jsonschema:"bytes"`
	SHA256         string    `json:"sha256"`
	CreatedAt      time.Time `json:"createdAt"`
	CreatedBy      string    `json:"createdBy" jsonschema:"who attached it"`
	// URL is where the content is downloaded, with the caller's credentials.
	URL string `json:"url" jsonschema:"path to download the file, under this Exhale's address"`
	// Path is the file inside a full export archive; empty elsewhere.
	Path string `json:"path,omitempty"`
}

type DocumentList struct {
	Documents []Document `json:"documents"`
}

type DocumentResult struct {
	Document Document `json:"document"`
	AuditID  string   `json:"auditId,omitempty" jsonschema:"pass to undo to revert"`
}

type DuplicateGroup struct {
	Key           string            `json:"key" jsonschema:"stable id of the group; pass it to dismiss_duplicate when paying twice is on purpose"`
	Service       string            `json:"service"`
	Subscriptions []SubscriptionRef `json:"subscriptions"`
}

type DuplicateNotice struct {
	Group DuplicateGroup
	// Subscriptions in the same order as Group.Subscriptions.
	Subscriptions []SubscriptionView
}

type ExportData struct {
	Format         string                 `json:"format" jsonschema:"always exhale/1"`
	ExportedAt     time.Time              `json:"exportedAt"`
	Household      domain.Household       `json:"household"`
	Members        []domain.Member        `json:"members"`
	Categories     []domain.Category      `json:"categories"`
	PaymentMethods []domain.PaymentMethod `json:"paymentMethods"`
	Subscriptions  []ExportedSubscription `json:"subscriptions"`
}

type ExportedSubscription struct {
	SubscriptionView
	Charges []domain.Charge `json:"charges"`
	// Files are its uploaded logo and documents, without their content:
	// the full export archive and the backups carry the content (ADR 0027).
	Files []Document `json:"files"`
}

type ExtrasInput struct {
	Tags     []string `json:"tags,omitempty" jsonschema:"free labels, many per subscription, e.g. work or family. Totals stay by category"`
	AltPrice string   `` /* 225-byte string literal not displayed */
	AltUnit  string   `json:"altUnit,omitempty" jsonschema:"the period altPrice covers: month or year (default: year)" enum:"month,year"`
}

type ExtrasUpdate struct {
	Tags     []string `json:"tags,omitempty" jsonschema:"replaces every tag; an empty list removes them all"`
	AltPrice *string  `` /* 164-byte string literal not displayed */
	AltUnit  *string  `json:"altUnit,omitempty" jsonschema:"the period altPrice covers: month or year" enum:"month,year"`
}

type FieldChange struct {
	Field string `json:"field" jsonschema:"category, paymentMethod, tags, status or deleted" enum:"category,paymentMethod,tags,status,deleted"`
	From  string `json:"from"`
	To    string `json:"to"`
}

type GetSubscriptionInput struct {
	ID string `json:"id" path:"id" jsonschema:"subscription id (sub_…)"`
}

type HouseholdInfo struct {
	Household      domain.Household       `json:"household"`
	Members        []domain.Member        `json:"members"`
	Categories     []domain.Category      `json:"categories"`
	PaymentMethods []domain.PaymentMethod `json:"paymentMethods"`
	Today          engine.Date            `json:"today" jsonschema:"today's date in the household time zone"`
	Tags           []TagCount             `json:"tags" jsonschema:"every tag in use, with how many subscriptions carry it"`
}

type ImportInput struct {
	Items           []ImportItem `json:"items"`
	AllowDuplicates bool         `` /* 131-byte string literal not displayed */
	DryRun          bool         `json:"dryRun,omitempty" jsonschema:"preview: nothing is saved. Show the result to the user, then call again without it"`
}

type ImportItem struct {
	Name          string   `json:"name"`
	Price         string   `json:"price" jsonschema:"decimal string, e.g. 12.99"`
	Currency      string   `json:"currency,omitempty" jsonschema:"ISO 4217 code; default: the household's display currency"`
	Interval      int      `json:"interval,omitempty" jsonschema:"units between charges, default 1"`
	Unit          string   `json:"unit,omitempty" jsonschema:"day, week, month (default) or year" enum:"day,week,month,year"`
	NextCharge    string   `json:"nextCharge,omitempty" jsonschema:"next (or first) charge, YYYY-MM-DD. For an ended subscription: when it started"`
	DayRule       string   `` /* 240-byte string literal not displayed */
	WeekendShift  string   `` /* 202-byte string literal not displayed */
	StartedOn     string   `json:"startedOn,omitempty" jsonschema:"when the member first subscribed, YYYY-MM-DD"`
	EndDate       string   `json:"endDate,omitempty" jsonschema:"last day, for subscriptions that ended, YYYY-MM-DD"`
	Status        string   `json:"status,omitempty" jsonschema:"active (default), paused or cancelled" enum:"active,paused,cancelled"`
	Category      string   `json:"category,omitempty" jsonschema:"category name; created if it does not exist"`
	PaymentMethod string   `json:"paymentMethod,omitempty" jsonschema:"payment method name; created if it does not exist"`
	Payer         string   `json:"payer,omitempty" jsonschema:"member name; default: the caller"`
	URL           string   `json:"url,omitempty"`
	Notes         string   `json:"notes,omitempty"`
	CancelURL     string   `json:"cancelUrl,omitempty"`
	Account       string   `json:"account,omitempty"`
	Renewal       string   `json:"renewal,omitempty" jsonschema:"auto (default) or manual" enum:"auto,manual"`
	NoticeDays    int      `json:"noticeDays,omitempty"`
	TrialEndsOn   string   `json:"trialEndsOn,omitempty"`
	ReminderDays  []int    `json:"reminderDays,omitempty" jsonschema:"days before each charge to remind; default [3, 0]"`
	AutoConfirm   bool     `json:"autoConfirm,omitempty"`
	Tags          []string `json:"tags,omitempty" jsonschema:"free labels"`
	AltPrice      string   `json:"altPrice,omitempty" jsonschema:"another price the provider offers, decimal string, e.g. 99.00"`
	AltUnit       string   `json:"altUnit,omitempty" jsonschema:"the period altPrice covers: month or year" enum:"month,year"`
	// Remark is a note from whoever prepared the item (a file parser or an
	// agent) for the person reviewing it. It is not saved.
	Remark string `json:"remark,omitempty" jsonschema:"note for the person reviewing the import; not saved"`
}

type ImportOutcome struct {
	Name    string `json:"name"`
	Action  string `json:"action" jsonschema:"create, duplicate (skipped) or error (skipped)" enum:"create,duplicate,error"`
	ID      string `json:"id,omitempty" jsonschema:"new subscription id; not saved in a dry run"`
	Message string `json:"message,omitempty"`
}

type ImportResult struct {
	Created           int             `json:"created"`
	Duplicates        int             `json:"duplicates"`
	Errors            int             `json:"errors"`
	Items             []ImportOutcome `json:"items"`
	NewCategories     []string        `json:"newCategories" jsonschema:"categories created along the way"`
	NewPaymentMethods []string        `json:"newPaymentMethods" jsonschema:"payment methods created along the way"`
	DryRun            bool            `json:"dryRun,omitempty"`
}

type KeepAwake struct {

	// MaxSleep bounds every wait, so a change made by another process
	// (exhale mcp) or a clock jump is noticed.
	MaxSleep time.Duration
	// RetryAfter is how long a refused hold waits before it is tried again
	// with the same setting.
	RetryAfter time.Duration
	// contains filtered or unexported fields
}

type KeepAwakeInfo struct {
	KeepAwakeSetting
	Timezone string          `json:"timezone" jsonschema:"the time zone of from and to (the household's)"`
	Status   KeepAwakeStatus `json:"status"`
}

type KeepAwakeSetting struct {
	Mode string `` /* 153-byte string literal not displayed */
	From string `json:"from" jsonschema:"start of the hours, HH:MM in the household time zone"`
	To   string `json:"to" jsonschema:"end of the hours, HH:MM in the household time zone; earlier than from for hours that cross midnight"`
	// The system is kept awake; the display may still sleep unless this is set.
	KeepDisplayOn bool `json:"keepDisplayOn" jsonschema:"also keep the display on (default false: only the system stays awake)"`
}

type KeepAwakeStatus struct {
	State string `` /* 271-byte string literal not displayed */
	// Why it is unavailable.
	Reason string `` /* 163-byte string literal not displayed */
	Error  string `json:"error,omitempty" jsonschema:"what the system said, in its words"`
}

type ListChargesInput struct {
	From string `json:"from,omitempty" query:"from" jsonschema:"first due date, YYYY-MM-DD (default today)"`
	To   string `json:"to,omitempty" query:"to" jsonschema:"last due date, YYYY-MM-DD (default from + 30 days)"`
}

type ListDocumentsInput struct {
	ID string `json:"id" path:"id" jsonschema:"subscription id (sub_…)"`
}

type ListSubscriptionsInput struct {
	Status string `json:"status,omitempty" query:"status" jsonschema:"active, paused or cancelled; empty for all"`
	Query  string `json:"query,omitempty" query:"query" jsonschema:"case-insensitive search in the name, notes, account, category and tags"`
	Tag    string `json:"tag,omitempty" query:"tag" jsonschema:"only subscriptions with this tag (case-insensitive)"`
}

type LogoResult struct {
	SubscriptionID string `json:"subscriptionId"`
	Logo           string `json:"logo,omitempty" jsonschema:"path of the logo now shown; empty: the bundled brand mark or the monogram"`
	AuditID        string `json:"auditId,omitempty" jsonschema:"pass to undo to revert"`
}

type MatchStatementInput struct {
	Transactions []StatementLine `json:"transactions" jsonschema:"the payments of the statement"`
	From         string          `json:"from,omitempty" jsonschema:"first day the statement covers, YYYY-MM-DD (default: the first transaction)"`
	To           string          `json:"to,omitempty" jsonschema:"last day the statement covers, YYYY-MM-DD (default: the last transaction)"`
}

type MemberBalance struct {
	MemberID string      `json:"memberId"`
	Name     string      `json:"name"`
	Paid     money.Money `json:"paid" jsonschema:"what this member's payment methods paid for shared subscriptions"`
	Share    money.Money `json:"share" jsonschema:"what this member should carry"`
	Net      money.Money `json:"net" jsonschema:"paid minus share: positive is owed money, negative owes money"`
}

type Meta struct {
	Name        string // tool name, snake_case
	Title       string
	Description string
	Write       bool // changes data; needs write scope
	Destructive bool // deletes or cancels; agents need confirmation
	Idempotent  bool // repeating the call has no further effect
	Method      string
	Path        string // REST path under /api/v1
	Tag         string
}

type MethodSpend struct {
	PaymentMethod string      `json:"paymentMethod"`
	Monthly       money.Money `json:"monthly" jsonschema:"in the main currency"`
	Count         int         `json:"count"`
}

type MonthSpend struct {
	Month    string      `json:"month" jsonschema:"YYYY-MM"`
	Paid     money.Money `json:"paid" jsonschema:"charges marked paid that month, in the display currency"`
	Expected money.Money `` /* 127-byte string literal not displayed */
	Count    int         `json:"count" jsonschema:"paid plus expected charges"`
}

type Op[In, Out any] struct {
	Meta
	Run func(s *Service, ctx context.Context, a Actor, in In) (Out, error)
}

type OutboxItem struct {
	ID       string
	Kind     string
	ChargeID string
	MemberID string
	DueAt    time.Time
	Attempts int
	// Ref is what an item that is not about a charge is about: a payment
	// method (KindCardExpiry) or a duplicate group (KindDuplicate).
	Ref string
	// Personal is set for an item one member asked for (a snooze): it goes
	// to them only, never to a shared team channel.
	Personal bool
}

type PaidTotals struct {
	Count int         `json:"count" jsonschema:"charges marked paid"`
	Total money.Money `json:"total" jsonschema:"sum of paid charges, in the subscription currency"`
	Since engine.Date `json:"since,omitzero" jsonschema:"date of the first paid charge"`
}

type PaydayOutlook struct {
	Payday  engine.Date  `json:"payday" jsonschema:"next payday"`
	Due     money.Money  `json:"due" jsonschema:"total of the charges due before it, in the display currency"`
	Charges []ChargeView `json:"charges"`
}

type PaymentMethodOut struct {
	PaymentMethod domain.PaymentMethod `json:"paymentMethod"`
}

type PlanSwitch struct {
	Current money.Money `json:"currentYearly" jsonschema:"what the current plan costs per year"`
	Other   money.Money `json:"otherYearly" jsonschema:"what the other price costs per year"`
	// Saving is positive when switching saves money, negative when the
	// current plan is already the cheaper one.
	Saving money.Money `` /* 155-byte string literal not displayed */
}

type PreviewScheduleInput struct {
	Interval     int    `json:"interval" minimum:"1"`
	Unit         string `json:"unit" enum:"day,week,month,year"`
	FirstCharge  string `json:"firstCharge" jsonschema:"YYYY-MM-DD"`
	DayRule      string `` /* 470-byte string literal not displayed */
	WeekendShift string `` /* 343-byte string literal not displayed */
	Count        int    `json:"count,omitempty" jsonschema:"how many dates, default 12" maximum:"60"`
}

type PriceChangeHint struct {
	Expected    money.Money `json:"expected"`
	Charged     money.Money `json:"charged"`
	Change      string      `json:"changePercent"`
	YearlyDelta money.Money `json:"yearlyDelta" jsonschema:"difference per year if this is the new price, in the subscription currency"`
}

type PriceIncrease struct {
	Subscription SubscriptionRef `json:"subscription"`
	From         money.Money     `json:"from"`
	To           money.Money     `json:"to"`
	Since        engine.Date     `json:"since"`
	Change       string          `json:"changePercent"`
	YearlyDelta  money.Money     `json:"yearlyDelta" jsonschema:"extra cost per year at the new price, in the subscription currency"`
}

type PricePoint struct {
	From      engine.Date `json:"from" jsonschema:"first charge at this price"`
	Price     money.Money `json:"price"`
	Change    string      `json:"changePercent,omitempty" jsonschema:"change against the previous price, e.g. +14.3"`
	Scheduled bool        `json:"scheduled,omitempty" jsonschema:"a change announced in advance that has not arrived yet"`
}

type ReassignPaymentMethodInput struct {
	FromID string `json:"fromId" jsonschema:"payment method the subscriptions use now (pm_…)"`
	ToID   string `json:"toId,omitempty" jsonschema:"payment method to move them to; empty leaves them without one"`
	DryRun bool   `json:"dryRun,omitempty"`
}

type ReassignResult struct {
	Moved   int    `json:"moved" jsonschema:"subscriptions that changed payment method"`
	Deleted string `json:"deleted,omitempty" jsonschema:"payment method that was deleted, if any"`
}

type ReminderEntry struct {
	ID             string      `json:"id"`
	Kind           string      `json:"kind" jsonschema:"reminder (before a charge), decision (before the last day to cancel) or confirm (was it charged?)"`
	Status         string      `json:"status" jsonschema:"pending, sent, failed or cancelled" enum:"pending,sent,failed,cancelled"`
	DueAt          time.Time   `json:"dueAt" jsonschema:"when it is or was meant to go out"`
	SentAt         *time.Time  `json:"sentAt,omitempty"`
	Attempts       int         `json:"attempts"`
	Error          string      `json:"error,omitempty" jsonschema:"last delivery error"`
	SubscriptionID string      `json:"subscriptionId"`
	Subscription   string      `json:"subscription"`
	ChargeDate     engine.Date `json:"chargeDate"`
	To             string      `json:"to,omitempty" jsonschema:"member it is for"`
	Explanation    string      `json:"explanation" jsonschema:"what happened, in plain words"`
}

type ReminderLog struct {
	Entries []ReminderEntry `json:"entries"`
}

type ReminderLogInput struct {
	Limit int `json:"limit,omitempty" query:"limit" jsonschema:"how many entries, newest first (default 100)" maximum:"500"`
}

type RemoveLogoInput struct {
	ID     string `json:"id" jsonschema:"subscription id (sub_…)"`
	DryRun bool   `json:"dryRun,omitempty"`
}

type RenameTagInput struct {
	Tag    string `json:"tag" jsonschema:"the tag to rename (case does not matter)"`
	To     string `json:"to" jsonschema:"the new name; if a subscription already has it, the two merge"`
	DryRun bool   `json:"dryRun,omitempty"`
}

type SavePaymentMethodInput struct {
	ID        string `json:"id,omitempty" jsonschema:"existing payment method id (pm_…) to update; empty to create"`
	Name      string `json:"name" jsonschema:"e.g. Revolut, Visa, PayPal"`
	Kind      string `json:"kind" enum:"card,bank,paypal,other"`
	Last4     string `json:"last4,omitempty" jsonschema:"last four digits" maxLength:"4"`
	ExpiresOn string `json:"expiresOn,omitempty" jsonschema:"last valid day, YYYY-MM-DD (for cards: last day of the expiry month)"`
	OwnerID   string `json:"ownerId,omitempty"`
	DryRun    bool   `json:"dryRun,omitempty"`
}

type SchedulePreview struct {
	Dates []engine.Date `json:"dates"`
}

type Scope string

type Service struct {
	// contains filtered or unexported fields
}

type SetChargeStatusInput struct {
	ChargeID      string `json:"chargeId"`
	Status        string `json:"status" jsonschema:"paid, failed, skipped, or pending to reopen" enum:"paid,failed,skipped,pending"`
	ChargedAmount string `json:"chargedAmount,omitempty" jsonschema:"what the bank actually took, decimal string (optional)"`
	ChargedIn     string `json:"chargedCurrency,omitempty" jsonschema:"currency of chargedAmount, e.g. EUR when a USD service is paid from a EUR card"`
	Note          string `json:"note,omitempty"`
	DryRun        bool   `json:"dryRun,omitempty"`
}

type SetKeepAwakeInput struct {
	Mode          *string `` /* 163-byte string literal not displayed */
	From          *string `json:"from,omitempty" jsonschema:"start of the hours, HH:MM in the household time zone"`
	To            *string `` /* 126-byte string literal not displayed */
	KeepDisplayOn *bool   `json:"keepDisplayOn,omitempty" jsonschema:"also keep the display on; false lets it sleep while the system stays awake"`
	DryRun        bool    `json:"dryRun,omitempty"`
}

type SetLogoInput struct {
	ID     string
	Data   []byte
	DryRun bool
}

type SetSubscriptionStatusInput struct {
	ID     string `json:"id"`
	Action string `` /* 128-byte string literal not displayed */
	DryRun bool   `json:"dryRun,omitempty"`
}

type SharedCharge struct {
	Subscription string      `json:"subscription"`
	Date         engine.Date `json:"date"`
	Amount       money.Money `json:"amount" jsonschema:"in the display currency"`
	PaidBy       string      `json:"paidBy"`
	Status       string      `json:"status"`
}

type SnoozeInput struct {
	ChargeID string `json:"chargeId"`
	Kind     string `` /* 200-byte string literal not displayed */
	Days     int    `json:"days" jsonschema:"bring it back in this many days, at the reminder time (1: tomorrow)" minimum:"1" maximum:"30"`
	DryRun   bool   `json:"dryRun,omitempty"`
}

type SnoozeResult struct {
	ChargeID string      `json:"chargeId"`
	Kind     string      `json:"kind"`
	On       engine.Date `json:"on" jsonschema:"the day it comes back"`
	At       time.Time   `json:"at" jsonschema:"when it comes back"`
	Clamped  bool        `` /* 130-byte string literal not displayed */
	Planned  bool        `json:"alreadyPlanned" jsonschema:"a message about this charge was already planned that day, so no second one is added"`
	DryRun   bool        `json:"dryRun,omitempty"`
}

type SpendingHistory struct {
	MainCurrency   string              `json:"mainCurrency"`
	Months         []MonthSpend        `json:"months" jsonschema:"oldest first; past months show what was paid, future months what is expected"`
	BySubscription []SubscriptionSpend `json:"bySubscription" jsonschema:"lifetime paid per subscription, largest first"`
	TotalPaid      money.Money         `json:"totalPaid" jsonschema:"everything marked paid in the months shown"`
	HeaviestMonth  string              `json:"heaviestMonth,omitempty" jsonschema:"upcoming month with the most to pay, YYYY-MM"`
	Unconverted    []string            `json:"unconverted" jsonschema:"currencies without a known rate, left out"`
}

type SpendingHistoryInput struct {
	Months int `json:"months,omitempty" query:"months" jsonschema:"months to look back and ahead, default 12" minimum:"1" maximum:"60"`
}

type SpendingSummary struct {
	MainCurrency string        `json:"mainCurrency"`
	Monthly      []money.Money `json:"monthlyByCurrency" jsonschema:"active subscriptions normalized per month, one entry per currency"`
	Yearly       []money.Money `json:"yearlyByCurrency"`
	// MonthlyTotal and YearlyTotal are in the main currency, converting other
	// currencies at the latest ECB reference rate (see RatesDate).
	MonthlyTotal money.Money       `json:"monthlyTotal"`
	YearlyTotal  money.Money       `json:"yearlyTotal"`
	Converted    bool              `json:"converted" jsonschema:"true when other currencies were converted into the main currency"`
	Unconverted  []string          `json:"unconverted" jsonschema:"currencies without a known rate, left out of the totals"`
	Rates        map[string]string `json:"rates" jsonschema:"units of the main currency per 1 unit of each currency"`
	RatesDate    string            `json:"ratesDate,omitempty" jsonschema:"ECB reference date of the rates used"`
	ByCategory   []CategorySpend   `json:"byCategory" jsonschema:"monthly spend per category, in the main currency"`
	ByMethod     []MethodSpend     `json:"byPaymentMethod" jsonschema:"monthly spend per payment method, in the main currency"`
	Active       int               `json:"activeSubscriptions"`
	NextCharges  []ChargeView      `json:"next7Days"`
	// SetAside is the monthly equivalent of everything that is not billed
	// monthly: what to put away each month so yearly bills do not surprise.
	SetAside money.Money `` /* 183-byte string literal not displayed */
	// BeforePayday is set when the household has a payday.
	BeforePayday *PaydayOutlook `json:"beforePayday,omitempty" jsonschema:"what is due before the next payday, when the household has one"`
	// Stopped is what cancelling saved: "you stopped paying X per year".
	Stopped StoppedSpend `` /* 249-byte string literal not displayed */
}

type StatementLine struct {
	Date        string `json:"date" jsonschema:"when the money left, YYYY-MM-DD"`
	Description string `json:"description" jsonschema:"the text the bank shows, e.g. NETFLIX.COM 866-579-7172"`
	Amount      string `` /* 129-byte string literal not displayed */
	Currency    string `json:"currency,omitempty" jsonschema:"ISO 4217 code; default: the household's currency"`
}

type StatementMatch struct {
	From    engine.Date   `json:"from"`
	To      engine.Date   `json:"to"`
	Matches []ChargeMatch `json:"matches" jsonschema:"expected charges found in the statement, by due date"`
	// Missing are open charges due in the period that no transaction
	// matches.
	Missing   []ChargeView `` /* 220-byte string literal not displayed */
	Unmatched int          `json:"unmatched" jsonschema:"transactions that match no expected charge"`
}

type StoppedSpend struct {
	Yearly        money.Money           `json:"yearly" jsonschema:"what the cancelled subscriptions would cost per year at their last price, in the display currency"`
	Count         int                   `json:"count"`
	Subscriptions []StoppedSubscription `json:"subscriptions" jsonschema:"most recently ended first"`
}

type StoppedSubscription struct {
	ID     string      `json:"id"`
	Name   string      `json:"name"`
	Yearly money.Money `json:"yearly" jsonschema:"per year at its last price, in the subscription currency"`
	// YearlyMain is Yearly converted into the display currency.
	YearlyMain money.Money `json:"yearlyMain" jsonschema:"per year, in the display currency"`
	Until      engine.Date `json:"until,omitzero" jsonschema:"last day of service"`
}

type SubscriptionDetail struct {
	Subscription SubscriptionView `json:"subscription"`
	Upcoming     []ChargeView     `json:"upcoming"`
	History      []ChargeView     `json:"history"`
	PriceHistory []PricePoint     `json:"priceHistory" jsonschema:"every price it has had, oldest first, from the charge ledger; a scheduled change comes last"`
	Paid         PaidTotals       `json:"paid" jsonschema:"what it has really cost so far"`
}

type SubscriptionList struct {
	Subscriptions []SubscriptionView `json:"subscriptions"`
}

type SubscriptionRef struct {
	ID      string      `json:"id"`
	Name    string      `json:"name"`
	Payer   string      `json:"payer,omitempty"`
	Monthly money.Money `json:"monthly" jsonschema:"in the subscription currency"`
}

type SubscriptionSpend struct {
	ID    string      `json:"id"`
	Name  string      `json:"name"`
	Paid  money.Money `json:"paid" jsonschema:"sum of paid charges, in the display currency"`
	Count int         `json:"count"`
	Since engine.Date `json:"since,omitzero"`
}

type SubscriptionView struct {
	domain.Subscription
	Cadence        string      `json:"cadence" jsonschema:"human description of the billing cycle, e.g. every 1 month"`
	NextCharge     engine.Date `json:"nextCharge,omitzero" jsonschema:"next charge date (YYYY-MM-DD), empty if none"`
	MonthlyCost    money.Money `json:"monthlyCost" jsonschema:"price normalized to one month, in the subscription currency"`
	CategoryName   string      `json:"categoryName,omitempty"`
	PaymentMethod  string      `json:"paymentMethod,omitempty" jsonschema:"payment method label, e.g. Revolut ••0937"`
	PayerName      string      `json:"payerName,omitempty"`
	CancelledUntil engine.Date `json:"serviceUntil,omitzero" jsonschema:"for cancelled subscriptions: last day of service"`
	YearlyCost     money.Money `json:"yearlyCost" jsonschema:"price normalized to one year, in the subscription currency"`
	InTrial        bool        `json:"inTrial" jsonschema:"the free trial is still running; the next charge is the first paid one"`
	CancelBy       engine.Date `` /* 155-byte string literal not displayed */
	Expires        bool        `json:"expires" jsonschema:"manual renewal: the next charge date is when it expires unless renewed"`
	AskUsage       bool        `` /* 127-byte string literal not displayed */
	// PlanSwitch is set only when the member recorded another price (altPrice).
	PlanSwitch *PlanSwitch `` /* 146-byte string literal not displayed */
	// Billing rules (weekday of the month, weekend shift).
	BillingDay    string      `` /* 206-byte string literal not displayed */
	NextScheduled engine.Date `` /* 156-byte string literal not displayed */
	Logo          string      `json:"logo,omitempty" jsonschema:"path of a logo someone uploaded for it; empty: the bundled brand mark or the initials"`
}

type TagCount struct {
	Name          string `json:"name"`
	Subscriptions int    `json:"subscriptions"`
}

type TermsInput struct {
	StartedOn   string         `json:"startedOn,omitempty" jsonschema:"when the member first subscribed, YYYY-MM-DD. History only: it creates no charges"`
	TrialEndsOn string         `` /* 146-byte string literal not displayed */
	NoticeDays  int            `` /* 176-byte string literal not displayed */
	Renewal     string         `` /* 189-byte string literal not displayed */
	CancelURL   string         `json:"cancelUrl,omitempty" jsonschema:"page where it is cancelled or managed, https://…"`
	Account     string         `json:"account,omitempty" jsonschema:"login or email the subscription lives under"`
	Shares      []domain.Share `json:"shares,omitempty" jsonschema:"how members split the cost, by relative weight; empty: the payer carries it all"`
}

type Transfer struct {
	From   string      `json:"from" jsonschema:"member id who pays"`
	To     string      `json:"to" jsonschema:"member id who receives"`
	Amount money.Money `json:"amount"`
	Text   string      `json:"text" jsonschema:"e.g. Ana pays Alex 12.50 EUR"`
}

type UndoInput struct {
	AuditID string `json:"auditId,omitempty" jsonschema:"id returned by a write (aud_…)"`
	// AuditIDs revert several changes together, e.g. every change of a bulk
	// edit: all of them or none.
	AuditIDs []string `` /* 134-byte string literal not displayed */
	DryRun   bool     `json:"dryRun,omitempty"`
}

type UndoResult struct {
	Restored string `json:"restored" jsonschema:"entity id that was restored"`
	AuditID  string `json:"auditId"`
	// Undone counts the changes reverted (more than one with auditIds).
	Undone int `json:"undone"`
}

type UnusedSubscription struct {
	Subscription SubscriptionRef `json:"subscription"`
	Yearly       money.Money     `json:"yearly" jsonschema:"what it costs per year, in the subscription currency"`
	AnsweredOn   engine.Date     `json:"answeredOn"`
}

type UpdateCategoryInput struct {
	ID     string  `json:"id" jsonschema:"category id (cat_…)"`
	Name   *string `json:"name,omitempty"`
	Color  *string `json:"color,omitempty" jsonschema:"hex color, e.g. #7c6cff"`
	DryRun bool    `json:"dryRun,omitempty"`
}

type UpdateHouseholdInput struct {
	Name         *string `json:"name,omitempty" maxLength:"60"`
	Currency     *string `json:"currency,omitempty" jsonschema:"display currency (ISO 4217): totals are converted into it"`
	Timezone     *string `json:"timezone,omitempty" jsonschema:"IANA time zone, e.g. Europe/Madrid"`
	Locale       *string `` /* 140-byte string literal not displayed */
	ReminderTime *string `` /* 141-byte string literal not displayed */
	Payday       *int    `` /* 186-byte string literal not displayed */
	// Repeat until handled: how often an unanswered "was it charged?" comes back.
	ConfirmTimes     *int `` /* 221-byte string literal not displayed */
	ConfirmEveryDays *int `json:"confirmEveryDays,omitempty" jsonschema:"days between two of those questions" minimum:"1" maximum:"30"`
	DryRun           bool `json:"dryRun,omitempty"`
}

type UpdateSubscriptionInput struct {
	ID              string  `json:"id" jsonschema:"subscription id (sub_…)"`
	Name            *string `json:"name,omitempty"`
	Price           *string `json:"price,omitempty" jsonschema:"new price from the next open charge on, decimal string"`
	CategoryID      *string `json:"categoryId,omitempty"`
	PaymentMethodID *string `json:"paymentMethodId,omitempty" jsonschema:"applies to this and following charges"`
	PayerID         *string `json:"payerId,omitempty"`
	Private         *bool   `json:"private,omitempty"`
	URL             *string `json:"url,omitempty"`
	Notes           *string `json:"notes,omitempty"`
	AutoConfirm     *bool   `json:"autoConfirm,omitempty"`
	ReminderDays    []int   `json:"reminderDays,omitempty"`
	ReminderHour    *int    `json:"reminderHour,omitempty" jsonschema:"local hour of day for reminders (0-23)"`
	Interval        *int    `json:"interval,omitempty" jsonschema:"new number of units between charges, from the next charge on" minimum:"1"`
	Unit            *string `json:"unit,omitempty" jsonschema:"new billing unit, from the next charge on" enum:"day,week,month,year"`
	NextCharge      *string `` /* 162-byte string literal not displayed */
	DayRule         *string `` /* 470-byte string literal not displayed */
	WeekendShift    *string `` /* 343-byte string literal not displayed */
	EndDate         *string `` /* 126-byte string literal not displayed */
	PriceFrom       *string `` /* 170-byte string literal not displayed */
	StartedOn       *string `json:"startedOn,omitempty" jsonschema:"when the member first subscribed, YYYY-MM-DD; empty string clears it"`
	TrialEndsOn     *string `` /* 129-byte string literal not displayed */
	NoticeDays      *int    `json:"noticeDays,omitempty" jsonschema:"days of notice required to cancel before a renewal; 0 removes it"`
	Renewal         *string `json:"renewal,omitempty" jsonschema:"auto or manual (expires unless renewed)" enum:"auto,manual"`
	CancelURL       *string `json:"cancelUrl,omitempty" jsonschema:"page where it is cancelled or managed"`
	Account         *string `json:"account,omitempty" jsonschema:"login or email the subscription lives under"`
	// Shares replace the cost split; an empty list gives the cost back to the payer.
	Shares []domain.Share `json:"shares,omitempty" jsonschema:"how members split the cost, by relative weight"`
	Using  *bool          `json:"using,omitempty" jsonschema:"the member's answer to 'still using this?'"`
	ExtrasUpdate
	DryRun bool `json:"dryRun,omitempty"`
}