store

Documentation

Overview

Package store provides bitwave's workspace-aware storage implementations.

The local store persists a workspace as a directory of plain-text files:

• accounts.ledger
• prices.ledger
• <name>.journal (one or more)

Each .journal file maps 1:1 to a Journal (id = filename stem, name = id title-cased). Entries are tagged with their journal during parse so SetEntryStatus can rewrite the correct file.

Package store provides bitwave's workspace-aware storage interface plus its local file-backed and cloud (the cloud ledger HTTP) implementations.

bitwave adds a per-call journal id everywhere a write happens, so a workspace with multiple journals can be driven from the same CLI surface.

Index

• Constants
• Variables
• type Cloud
  • func NewCloud(baseURL, orgId, workspaceId string, tokenResolver func() (string, error)) *Cloud
  • func (c *Cloud) AddAccount(ctx context.Context, a model.Account) error
  • func (c *Cloud) AddEntry(ctx context.Context, journalId string, e model.Entry) (string, error)
  • func (c *Cloud) AddPrice(ctx context.Context, p model.Price) error
  • func (c *Cloud) EnsureJournal(ctx context.Context, journalId string) error
  • func (c *Cloud) Import(ctx context.Context, journalId string, p *model.Project) error
  • func (c *Cloud) Journals(ctx context.Context) ([]string, error)
  • func (c *Cloud) Project(ctx context.Context) (*model.Project, error)
  • func (c *Cloud) SetEntryStatus(ctx context.Context, entryID string, status model.Status, ...) error
• type LocalWorkspace
  • func InitLocal(dir, name, baseCurrency string) (*LocalWorkspace, error)
  • func OpenLocal(dir string) (*LocalWorkspace, error)
  • func (s *LocalWorkspace) AddAccount(ctx context.Context, a model.Account) error
  • func (s *LocalWorkspace) AddEntry(ctx context.Context, journalId string, e model.Entry) (string, error)
  • func (s *LocalWorkspace) AddEntryToJournal(ctx context.Context, journalId string, e model.Entry) (string, error)
  • func (s *LocalWorkspace) AddPrice(ctx context.Context, p model.Price) error
  • func (s *LocalWorkspace) AppendRaw(ctx context.Context, journalId string, p *model.Project) error
  • func (s *LocalWorkspace) EnsureJournal(ctx context.Context, id string) error
  • func (s *LocalWorkspace) Import(ctx context.Context, journalId string, p *model.Project) error
  • func (s *LocalWorkspace) JournalIds() ([]string, error)
  • func (s *LocalWorkspace) Journals(ctx context.Context) ([]string, error)
  • func (s *LocalWorkspace) ParseJournalEntries(id string) ([]model.Entry, error)
  • func (s *LocalWorkspace) Project(ctx context.Context) (*model.Project, error)
  • func (s *LocalWorkspace) ResolveJournal(ctx context.Context, explicit string) (string, error)
  • func (s *LocalWorkspace) SetEntryStatus(ctx context.Context, entryID string, status model.Status, ...) error
• type Store

Constants

const (
	AccountsFile = "accounts.ledger"
	PricesFile   = "prices.ledger"
	JournalExt   = ".journal"
)

Filenames within a workspace directory.

const DefaultJournal = "default"

DefaultJournal is the journal id used when no journal is specified and none exists yet.

Variables

var ErrAmbiguousJournal = errors.New("multiple journals in workspace; pass --journal to disambiguate")

ErrAmbiguousJournal is returned by ResolveJournal when the workspace has multiple .journal files and no explicit journal was passed.

Types

type Cloud

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

Cloud is the cloud-backed implementation of Store. It uses gl-svc's current workspace-scoped /v1 surface. Do not route cloud operations through the accounting SDK's legacy /api/v1/orgs/{org}/ledger/workspaces surface: the gateway no longer registers those item routes.

func NewCloud

func NewCloud(baseURL, orgId, workspaceId string, tokenResolver func() (string, error)) *Cloud

NewCloud builds a bitwave cloud store.

func (*Cloud) AddAccount

func (c *Cloud) AddAccount(ctx context.Context, a model.Account) error

func (*Cloud) AddEntry

func (c *Cloud) AddEntry(ctx context.Context, journalId string, e model.Entry) (string, error)

func (*Cloud) AddPrice

func (c *Cloud) AddPrice(ctx context.Context, p model.Price) error

func (*Cloud) EnsureJournal

func (c *Cloud) EnsureJournal(ctx context.Context, journalId string) error

func (*Cloud) Import

func (c *Cloud) Import(ctx context.Context, journalId string, p *model.Project) error

func (*Cloud) Journals

func (c *Cloud) Journals(ctx context.Context) ([]string, error)

func (*Cloud) Project

func (c *Cloud) Project(ctx context.Context) (*model.Project, error)

func (*Cloud) SetEntryStatus

func (c *Cloud) SetEntryStatus(ctx context.Context, entryID string, status model.Status, postingAccount string) error

type LocalWorkspace

type LocalWorkspace struct {
	Dir string
	Cfg *config.Config
}

LocalWorkspace reads/writes a bitwave workspace as plain-text files.

func InitLocal

func InitLocal(dir, name, baseCurrency string) (*LocalWorkspace, error)

InitLocal scaffolds an empty local workspace at dir. Refuses to clobber an existing .bitwave.toml.

func OpenLocal

func OpenLocal(dir string) (*LocalWorkspace, error)

OpenLocal opens an existing local workspace at dir. Returns config.ErrNotAWorkspace if the dir has no .bitwave.toml.

func (*LocalWorkspace) AddAccount

func (s *LocalWorkspace) AddAccount(ctx context.Context, a model.Account) error

AddAccount appends to accounts.ledger.

func (*LocalWorkspace) AddEntry

func (s *LocalWorkspace) AddEntry(ctx context.Context, journalId string, e model.Entry) (string, error)

AddEntry satisfies the Store interface; delegates to AddEntryToJournal.

func (*LocalWorkspace) AddEntryToJournal

func (s *LocalWorkspace) AddEntryToJournal(ctx context.Context, journalId string, e model.Entry) (string, error)

AddEntryToJournal appends e to <journalId>.journal. The synthetic id for the entry is returned so the caller can pass it back to SetEntryStatus.

func (*LocalWorkspace) AddPrice

func (s *LocalWorkspace) AddPrice(ctx context.Context, p model.Price) error

AddPrice appends to prices.ledger.

func (*LocalWorkspace) AppendRaw

func (s *LocalWorkspace) AppendRaw(ctx context.Context, journalId string, p *model.Project) error

AppendRaw imports a parsed project into journalId, appending accounts and prices to their canonical files.

func (*LocalWorkspace) EnsureJournal

func (s *LocalWorkspace) EnsureJournal(ctx context.Context, id string) error

EnsureJournal creates an empty <id>.journal file if it doesn't exist.

func (*LocalWorkspace) Import

func (s *LocalWorkspace) Import(ctx context.Context, journalId string, p *model.Project) error

Import satisfies the Store interface; delegates to AppendRaw.

func (*LocalWorkspace) JournalIds

func (s *LocalWorkspace) JournalIds() ([]string, error)

JournalIds returns the ids of all .journal files in the workspace, sorted.

func (*LocalWorkspace) Journals

func (s *LocalWorkspace) Journals(ctx context.Context) ([]string, error)

Journals satisfies the Store interface (alias for JournalIds, ignoring ctx).

func (*LocalWorkspace) ParseJournalEntries

func (s *LocalWorkspace) ParseJournalEntries(id string) ([]model.Entry, error)

ParseJournalEntries returns the entries in a single journal file, with synthetic ids assigned. Used by `bitwave migrate` to push journals one at a time.

func (*LocalWorkspace) Project

func (s *LocalWorkspace) Project(ctx context.Context) (*model.Project, error)

Project parses every .ledger and .journal file and merges them into one in-memory project for reports.

func (*LocalWorkspace) ResolveJournal

func (s *LocalWorkspace) ResolveJournal(ctx context.Context, explicit string) (string, error)

ResolveJournal picks the journal a write should target.

• explicit non-empty: returned as-is
• 0 journal files: auto-create config.DefaultJournal (or DefaultJournal) and return its id
• 1 journal file: return that single id
• >=2 journal files: return ErrAmbiguousJournal — caller must pass --journal

func (*LocalWorkspace) SetEntryStatus

func (s *LocalWorkspace) SetEntryStatus(ctx context.Context, entryID string, status model.Status, postingAccount string) error

SetEntryStatus rewrites the journal file containing entryID. The journal is derived from the id prefix (everything before the first ":").

type Store

type Store interface {
	// Project loads the full workspace view (all journals merged).
	Project(ctx context.Context) (*model.Project, error)

	// Journals lists the journal ids in the workspace, sorted.
	Journals(ctx context.Context) ([]string, error)

	// EnsureJournal creates the named journal if it doesn't exist.
	EnsureJournal(ctx context.Context, journalId string) error

	// AddAccount declares an account at the workspace scope.
	AddAccount(ctx context.Context, a model.Account) error

	// AddPrice records a price observation at the workspace scope.
	AddPrice(ctx context.Context, p model.Price) error

	// AddEntry appends an entry to the named journal. Returns the assigned id.
	AddEntry(ctx context.Context, journalId string, e model.Entry) (string, error)

	// SetEntryStatus flips an entry (or one posting) status. The journal is
	// recovered from the entry id by the implementation.
	SetEntryStatus(ctx context.Context, entryID string, status model.Status, postingAccount string) error

	// Import appends a parsed ledger blob to the named journal.
	Import(ctx context.Context, journalId string, p *model.Project) error
}

Store is the bitwave-flavored ledger store. The journal id is passed through on every write so callers don't have to construct a new store per journal.