tech/sendico
2
0
Fork 0
Code Issues 32 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

refactored notificatoin / tgsettle responsibility boundaries

Browse Source
This commit is contained in:
Stephan D
2026-02-19 18:56:59 +01:00
parent 47f0a3d890
commit 2fd8a6ebb7
73 changed files with 3705 additions and 681 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
api/proto/ledger/v1/ledger.proto
View File

@@ -11,51 +11,89 @@ import "api/proto/common/money/v1/money.proto";
// ===== Enums =====
// EntryType classifies the kind of journal entry.
enum EntryType {
// ENTRY_TYPE_UNSPECIFIED is the default zero value.
ENTRY_TYPE_UNSPECIFIED = 0;
// ENTRY_CREDIT records an inbound credit.
ENTRY_CREDIT = 1;
// ENTRY_DEBIT records an outbound debit.
ENTRY_DEBIT = 2;
// ENTRY_TRANSFER records a transfer between accounts.
ENTRY_TRANSFER = 3;
// ENTRY_FX records a foreign-exchange conversion.
ENTRY_FX = 4;
// ENTRY_FEE records a fee charge.
ENTRY_FEE = 5;
// ENTRY_ADJUST records a manual adjustment.
ENTRY_ADJUST = 6;
// ENTRY_REVERSE records a reversal of a prior entry.
ENTRY_REVERSE = 7;
}
// LineType classifies the purpose of a posting line within an entry.
enum LineType {
// LINE_TYPE_UNSPECIFIED is the default zero value.
LINE_TYPE_UNSPECIFIED = 0;
// LINE_MAIN is the primary posting line.
LINE_MAIN = 1;
// LINE_FEE is a fee posting line.
LINE_FEE = 2;
// LINE_SPREAD is an FX spread posting line.
LINE_SPREAD = 3;
// LINE_REVERSAL is a reversal posting line.
LINE_REVERSAL = 4;
}
// AccountType classifies the fundamental accounting type of an account.
enum AccountType {
// ACCOUNT_TYPE_UNSPECIFIED is the default zero value.
ACCOUNT_TYPE_UNSPECIFIED = 0;
// ACCOUNT_TYPE_ASSET represents an asset account.
ACCOUNT_TYPE_ASSET = 1;
// ACCOUNT_TYPE_LIABILITY represents a liability account.
ACCOUNT_TYPE_LIABILITY = 2;
// ACCOUNT_TYPE_REVENUE represents a revenue account.
ACCOUNT_TYPE_REVENUE = 3;
// ACCOUNT_TYPE_EXPENSE represents an expense account.
ACCOUNT_TYPE_EXPENSE = 4;
}
// AccountStatus indicates whether an account is active or frozen.
enum AccountStatus {
// ACCOUNT_STATUS_UNSPECIFIED is the default zero value.
ACCOUNT_STATUS_UNSPECIFIED = 0;
// ACCOUNT_STATUS_ACTIVE means the account accepts postings.
ACCOUNT_STATUS_ACTIVE = 1;
// ACCOUNT_STATUS_FROZEN means the account is blocked from new postings.
ACCOUNT_STATUS_FROZEN = 2;
}
// AccountRole defines the functional role of an account within an organization.
enum AccountRole {
// ACCOUNT_ROLE_UNSPECIFIED is the default zero value.
ACCOUNT_ROLE_UNSPECIFIED = 0;
// ACCOUNT_ROLE_OPERATING is the main operating account.
ACCOUNT_ROLE_OPERATING = 1;
// ACCOUNT_ROLE_HOLD is a temporary hold account.
ACCOUNT_ROLE_HOLD = 2;
// ACCOUNT_ROLE_TRANSIT is an in-transit account.
ACCOUNT_ROLE_TRANSIT = 3;
// ACCOUNT_ROLE_SETTLEMENT is a settlement account.
ACCOUNT_ROLE_SETTLEMENT = 4;
// ACCOUNT_ROLE_CLEARING is a clearing account.
ACCOUNT_ROLE_CLEARING = 5;
// ACCOUNT_ROLE_PENDING is a pending-settlement account.
ACCOUNT_ROLE_PENDING = 6;
// ACCOUNT_ROLE_RESERVE is a reserve account.
ACCOUNT_ROLE_RESERVE = 7;
// ACCOUNT_ROLE_LIQUIDITY is a liquidity pool account.
ACCOUNT_ROLE_LIQUIDITY = 8;
// ACCOUNT_ROLE_FEE is a fee collection account.
ACCOUNT_ROLE_FEE = 9;
// ACCOUNT_ROLE_CHARGEBACK is a chargeback account.
ACCOUNT_ROLE_CHARGEBACK = 10;
// ACCOUNT_ROLE_ADJUSTMENT is an adjustment account.
ACCOUNT_ROLE_ADJUSTMENT = 11;
}
@@ -87,6 +125,7 @@ message PostingLine {
// ===== Requests/Responses =====
// CreateAccountRequest is the request to create a new ledger account.
message CreateAccountRequest {
string organization_ref = 1;
string owner_ref = 2;
@@ -103,6 +142,7 @@ message CreateAccountRequest {
AccountRole role = 11;
}
// CreateAccountResponse is the response for CreateAccount.
message CreateAccountResponse {
LedgerAccount account = 1;
}
@@ -121,6 +161,7 @@ message PostCreditRequest {
AccountRole role = 10; // optional: assert target account has this role
}
// PostDebitRequest is the request to post a debit entry.
message PostDebitRequest {
string idempotency_key = 1;
string organization_ref = 2;
@@ -134,6 +175,7 @@ message PostDebitRequest {
AccountRole role = 10; // optional: assert target account has this role
}
// TransferRequest is the request to transfer funds between two ledger accounts.
message TransferRequest {
string idempotency_key = 1;
string organization_ref = 2;
@@ -148,6 +190,7 @@ message TransferRequest {
AccountRole to_role = 11;
}
// FXRequest is the request to post a foreign-exchange conversion entry.
message FXRequest {
string idempotency_key = 1;
string organization_ref = 2;
@@ -164,6 +207,7 @@ message FXRequest {
google.protobuf.Timestamp event_time = 11;
}
// PostResponse is the common response returned after any posting operation.
message PostResponse {
string journal_entry_ref = 1;
int64 version = 2; // ledger's entry version (monotonic per scope)
@@ -172,10 +216,12 @@ message PostResponse {
// ---- Balances & Entries ----
// GetBalanceRequest is the request to retrieve an account balance.
message GetBalanceRequest {
string ledger_account_ref = 1;
}
// BalanceResponse holds the current balance of a ledger account.
message BalanceResponse {
string ledger_account_ref = 1;
common.money.v1.Money balance = 2;
@@ -183,10 +229,12 @@ message BalanceResponse {
google.protobuf.Timestamp last_updated = 4;
}
// GetEntryRequest is the request to retrieve a journal entry by reference.
message GetEntryRequest {
string entry_ref = 1;
}
// JournalEntryResponse represents a complete journal entry with all posting lines.
message JournalEntryResponse {
string entry_ref = 1;
string idempotency_key = 2;
@@ -199,17 +247,20 @@ message JournalEntryResponse {
repeated string ledger_account_refs = 9; // denormalized set for client-side filtering
}
// GetStatementRequest is the request to retrieve paginated journal entries for an account.
message GetStatementRequest {
string ledger_account_ref = 1;
string cursor = 2; // opaque
int32 limit = 3; // page size
}
// StatementResponse is a paginated list of journal entries.
message StatementResponse {
repeated JournalEntryResponse entries = 1;
string next_cursor = 2;
}
// ListAccountsRequest is the request to list ledger accounts with optional filters.
message ListAccountsRequest {
string organization_ref = 1;
// Optional owner filter with 3-state semantics:
@@ -219,28 +270,33 @@ message ListAccountsRequest {
google.protobuf.StringValue owner_ref_filter = 2;
}
// ListAccountsResponse is the response for ListAccounts.
message ListAccountsResponse {
repeated LedgerAccount accounts = 1;
}
// ---- Account status mutations ----
// BlockAccountRequest is the request to freeze (block) a ledger account.
message BlockAccountRequest {
string ledger_account_ref = 1;
string organization_ref = 2;
AccountRole role = 3; // optional: assert account has this role before blocking
}
// BlockAccountResponse is the response for BlockAccount.
message BlockAccountResponse {
LedgerAccount account = 1;
}
// UnblockAccountRequest is the request to unfreeze (unblock) a ledger account.
message UnblockAccountRequest {
string ledger_account_ref = 1;
string organization_ref = 2;
AccountRole role = 3; // optional: assert account has this role before unblocking
}
// UnblockAccountResponse is the response for UnblockAccount.
message UnblockAccountResponse {
LedgerAccount account = 1;
}