source

type Challenge struct {
	// Kind: "approve" (in the platform's app), "code" (type the code its
	// app or SMS shows), "qr" (scan Data with the platform's app).
	Kind    string    `json:"kind"`
	Data    string    `json:"data,omitempty"`
	Digits  int       `json:"digits,omitempty"`
	Expires time.Time `json:"expires"`
}

type Choice struct {
	Kind  string `json:"kind"`
	Chain string `json:"chain"`
	Value string `json:"value"`
}

type Config struct {
	Values map[string]string
	HTTP   *http.Client
	// Log, when set, records what the connector does outside a sync (a
	// sign-in), for the run log. Never secrets.
	Log func(format string, args ...any)
	// State is what the connector saved after its last run (cursors, ids
	// already seen...). Opaque to the engine.
	State []byte
}

type Definition struct {
	Kind        string  `json:"kind"`
	Name        string  `json:"name"`
	Category    string  `json:"category"` // "exchange", "broker", "wallet"
	Description string  `json:"description"`
	Fields      []Field `json:"fields"`
	// Setup is shown above the form: how to create a read-only key, etc.
	Setup string `json:"setup,omitempty"`
	// Statement, when set, says how to export the platform's own statement
	// for the connector's Importer (and enables the import in the UI).
	Statement string `json:"statement,omitempty"`
	// Limits says what the platform's API cannot tell, shown where balance
	// corrections are, so the user knows why they exist.
	Limits string `json:"limits,omitempty"`
	// Detect, for a Lines field, recognizes one value (a key, an address)
	// so the UI can say what it is before saving.
	Detect func(value string) (Detected, error) `json:"-"`
	// Preview reads what one value of a list holds now, so the user sees
	// before saving that it is the right account. cfg carries the source's
	// other values (servers, keys).
	Preview func(ctx context.Context, value string, cfg Config) ([]model.Balance, error) `json:"-"`
	// Hidden: kept for sources already set up, not offered for new ones
	// (another kind covers it).
	Hidden bool `json:"hidden,omitempty"`
	// NoTest: the form has no "Test connection" (checking would need the
	// user, like a sign-in to approve).
	NoTest bool `json:"noTest,omitempty"`
	// Modes, when set, are the ways the source can be used (a statement
	// file, a connection...); fields with a Mode belong to one of them.
	Modes []Mode `json:"modes,omitempty"`
	// SealState: the connector's state holds a secret (a session), so the
	// engine stores it encrypted.
	SealState bool `json:"-"`
	// New builds a connector from its settings (secrets decrypted).
	New func(cfg Config) (Source, error) `json:"-"`
}

type Detected struct {
	Kind    string   `json:"kind"` // the chain, for icons: "bitcoin", "evm"…
	Chain   string   `json:"chain"`
	Value   string   `json:"value"`
	Choices []Choice `json:"choices,omitempty"`
}

type Fetch struct {
	Since time.Time
	// Emit records one activity. NativeID must be stable across runs.
	Emit func(model.Activity) error
	// Progress reports what is being fetched, for the run log.
	Progress func(format string, args ...any)
}

type Field struct {
	Name     string `json:"name"`
	Label    string `json:"label"`
	Secret   bool   `json:"secret,omitempty"`   // stored encrypted, never sent back to the UI
	Optional bool   `json:"optional,omitempty"` //
	Help     string `json:"help,omitempty"`
	// Lines: one value per line (a list). A secret list comes back to the
	// UI masked line by line; masked lines sent back keep their stored value.
	Lines bool `json:"lines,omitempty"`
	// Advanced: rarely needed, tucked away in the form.
	Advanced bool `json:"advanced,omitempty"`
	// Hidden: set by the UI itself (a choice made before the form), never
	// shown as a field.
	Hidden bool `json:"hidden,omitempty"`
	// Mode: shown only when the source is used this way (see
	// Definition.Modes); empty for every mode.
	Mode string `json:"mode,omitempty"`
}

type Importer interface {
	// Import parses the file. existing is the source's current history, so
	// the connector can keep API activities that describe the same movement
	// better (transaction hashes, ids, fiat amounts).
	Import(name string, data []byte, existing []model.Activity) (*Statement, error)
}

type Interactive interface {
	Session() Session
	// Login starts a sign-in with one of Session().Methods.
	Login(ctx context.Context, method string) (*Challenge, error)
	// Poll checks on it: a nil challenge means signed in.
	Poll(ctx context.Context) (*Challenge, error)
	// Answer sends the code a "code" challenge asks for.
	Answer(ctx context.Context, code string) (*Challenge, error)
}

type Mode struct {
	ID   string `json:"id"`
	Name string `json:"name"`
	Help string `json:"help,omitempty"`
	Beta bool   `json:"beta,omitempty"`
}

type Offline interface {
	Offline() bool
}

type Session struct {
	// Needed: the source signs in interactively (a session it keeps).
	Needed bool `json:"needed"`
	// Until: when the current session ends (zero: none).
	Until time.Time `json:"until,omitempty"`
	// Methods: how a sign-in can be started ("app", "qr").
	Methods []string `json:"methods,omitempty"`
}

type Source interface {
	// Activities emits the history since f.Since (everything when zero).
	Activities(ctx context.Context, f Fetch) error
	// Balances returns what the platform says is held now.
	Balances(ctx context.Context) ([]model.Balance, error)
	// State returns what to give back in Config.State next time.
	State() []byte
}

type Statement struct {
	From, To time.Time // period covered (inclusive)
	// Accounts: the sub-accounts the file covers (nil: all of them);
	// activities of other sub-accounts in the period stay.
	Accounts   []string
	Activities []model.Activity // the whole history of that period
	Notes      []string         // what the user should know (lines skipped...)
}

type StatementFetcher interface {
	FetchStatement(ctx context.Context, f Fetch) (name string, data []byte, err error)
}

type Tester interface {
	Test(ctx context.Context) error
}