source

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
	// 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"`
	// 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"`
}

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 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)
	Activities []model.Activity // the whole history of that period
	Notes      []string         // what the user should know (lines skipped...)
}

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