bff dev upgrde

api/proto/billing/documents/v1/documents.proto

@@ -0,0 +1,101 @@
+syntax = "proto3";
+
+package billing.documents.v1;
+
+option go_package = "github.com/tech/sendico/pkg/proto/billing/documents/v1;documentsv1";
+
+
+// ---------------------------
+// ENUMS
+// ---------------------------
+
+// DocumentType defines supported accounting document kinds.
+enum DocumentType {
+  DOCUMENT_TYPE_UNSPECIFIED = 0;
+
+  // Invoice issued for the payment
+  DOCUMENT_TYPE_INVOICE     = 1;
+
+  // Service acceptance act (common in EU/RU accounting)
+  DOCUMENT_TYPE_ACT         = 2;
+
+  // Simple receipt confirmation
+  DOCUMENT_TYPE_RECEIPT     = 3;
+}
+
+
+// ---------------------------
+// SERVICE
+// ---------------------------
+
+// DocumentService provides document metadata for payment lists
+// and lazy document generation on demand.
+service DocumentService {
+
+  // BatchResolveDocuments is used by BFF when rendering
+  // a page of payments. This prevents N+1 calls by resolving
+  // document metadata for many payments in a single request.
+  rpc BatchResolveDocuments(BatchResolveDocumentsRequest)
+      returns (BatchResolveDocumentsResponse);
+
+  // GetDocument returns the actual PDF file.
+  // If the document was not generated before, the service
+  // generates it lazily, stores it, and returns it.
+  rpc GetDocument(GetDocumentRequest)
+      returns (GetDocumentResponse);
+}
+
+
+// ---------------------------
+// BATCH RESOLVE (for payment tables)
+// ---------------------------
+
+// BatchResolveDocumentsRequest contains a list of payment references
+// for which document availability should be resolved.
+message BatchResolveDocumentsRequest {
+  repeated string payment_refs = 1;
+}
+
+// DocumentMeta describes document availability for a single payment.
+message DocumentMeta {
+  // Payment reference
+  string payment_ref = 1;
+
+  // Document types that are applicable for this payment
+  // based on business rules and payment snapshot.
+  repeated DocumentType available_types = 2;
+
+  // Document types that were already generated and stored.
+  // Other available types will be generated lazily when requested.
+  repeated DocumentType ready_types = 3;
+}
+
+// BatchResolveDocumentsResponse returns metadata for all requested payments.
+message BatchResolveDocumentsResponse {
+  repeated DocumentMeta items = 1;
+}
+
+
+// ---------------------------
+// GET DOCUMENT (lazy generation)
+// ---------------------------
+
+// GetDocumentRequest requests a specific document for a payment.
+message GetDocumentRequest {
+  string payment_ref = 1;
+
+  // Type of document to retrieve (invoice, act, receipt, etc.)
+  DocumentType type  = 2;
+}
+
+// GetDocumentResponse returns the generated PDF content.
+message GetDocumentResponse {
+  // Raw PDF bytes
+  bytes  content   = 1;
+
+  // Suggested filename for download (e.g. invoice_123.pdf)
+  string filename  = 2;
+
+  // MIME type, typically "application/pdf"
+  string mime_type = 3;
+}

api/proto/common/account_role/v1/account_role.proto

@@ -0,0 +1,19 @@
+syntax = "proto3";
+
+package common.account_role.v1;
+option go_package = "github.com/tech/sendico/pkg/proto/common/account_role/v1;accountrolev1";
+
+enum AccountRole {
+  ACCOUNT_ROLE_UNSPECIFIED = 0;
+  OPERATING = 1;
+  HOLD = 2;
+  TRANSIT = 3;
+  SETTLEMENT = 4;
+  CLEARING = 5;
+  PENDING = 6;
+  RESERVE = 7;
+  LIQUIDITY = 8;
+  FEE = 9;
+  CHARGEBACK = 10;
+  ADJUSTMENT = 11;
+}

api/proto/common/gateway/v1/gateway.proto

@@ -47,6 +47,7 @@ enum RailOperation {
   RAIL_OPERATION_FX_CONVERT = 6;
   RAIL_OPERATION_BLOCK = 7;
   RAIL_OPERATION_RELEASE = 8;
+  RAIL_OPERATION_MOVE = 9;
 }
 
 // Limits in minor units, e.g. cents

api/proto/connector/v1/connector.proto

@@ -6,6 +6,8 @@ option go_package = "github.com/tech/sendico/pkg/proto/connector/v1;connectorv1"
 
 import "google/protobuf/struct.proto";
 import "google/protobuf/timestamp.proto";
+import "google/protobuf/wrappers.proto";
+import "common/account_role/v1/account_role.proto";
 import "common/describable/v1/describable.proto";
 import "common/money/v1/money.proto";
 import "common/pagination/v1/cursor.proto";
@@ -18,6 +20,7 @@ service ConnectorService {
   rpc GetAccount(GetAccountRequest) returns (GetAccountResponse);
   rpc ListAccounts(ListAccountsRequest) returns (ListAccountsResponse);
   rpc GetBalance(GetBalanceRequest) returns (GetBalanceResponse);
+  rpc UpdateAccountState(UpdateAccountStateRequest) returns (UpdateAccountStateResponse);
 
   rpc SubmitOperation(SubmitOperationRequest) returns (SubmitOperationResponse);
   rpc GetOperation(GetOperationRequest) returns (GetOperationResponse);
@@ -133,6 +136,7 @@ message Account {
   google.protobuf.Timestamp created_at = 8;
   google.protobuf.Timestamp updated_at = 9;
   common.describable.v1.Describable describable = 10;
+  common.account_role.v1.AccountRole role = 11; // functional role within the organization (ledger-only; unset for non-ledger connectors)
 }
 
 message Balance {
@@ -167,6 +171,8 @@ message Operation {
   string provider_ref = 11;
   google.protobuf.Timestamp created_at = 12;
   google.protobuf.Timestamp updated_at = 13;
+  common.account_role.v1.AccountRole from_role = 14;
+  common.account_role.v1.AccountRole to_role = 15;
 }
 
 message OperationReceipt {
@@ -192,6 +198,7 @@ message OpenAccountRequest {
   google.protobuf.Struct params = 6;
   string correlation_id = 7;
   string parent_intent_id = 8;
+  common.account_role.v1.AccountRole role = 9; // functional role (ledger-only; ignored by non-ledger connectors)
 }
 
 message OpenAccountResponse {
@@ -208,11 +215,17 @@ message GetAccountResponse {
 }
 
 message ListAccountsRequest {
-  string owner_ref = 1;
+  reserved 1;
+  reserved "owner_ref";
   AccountKind kind = 2;
   string asset = 3; // canonical asset string (USD, ETH, USDT-TRC20)
   common.pagination.v1.CursorPageRequest page = 4;
-  string organization_ref = 5; // optional org scope (preferred over owner_ref)
+  string organization_ref = 5;
+  // Optional owner filter with 3-state semantics:
+  // - not set: return all accounts within organization
+  // - set to empty string: return accounts where owner_ref is null/empty
+  // - set to a value: return accounts where owner_ref matches
+  google.protobuf.StringValue owner_ref_filter = 6;
 }
 
 message ListAccountsResponse {
@@ -220,6 +233,17 @@ message ListAccountsResponse {
   common.pagination.v1.CursorPageResponse page = 2;
 }
 
+message UpdateAccountStateRequest {
+  AccountRef account_ref = 1;
+  AccountState target_state = 2;
+  common.account_role.v1.AccountRole source_role = 3; // optional: assert account has this role before mutation
+}
+
+message UpdateAccountStateResponse {
+  Account account = 1;
+  ConnectorError error = 2;
+}
+
 message GetBalanceRequest {
   AccountRef account_ref = 1;
 }

api/proto/gateway/chain/v1/chain.proto

@@ -5,6 +5,7 @@ package chain.gateway.v1;
 option go_package = "github.com/tech/sendico/pkg/proto/gateway/chain/v1;chainv1";
 
 import "google/protobuf/timestamp.proto";
+import "google/protobuf/wrappers.proto";
 import "common/money/v1/money.proto";
 import "common/pagination/v1/cursor.proto";
 import "common/describable/v1/describable.proto";
@@ -85,9 +86,15 @@ message GetManagedWalletResponse {
 
 message ListManagedWalletsRequest {
   string organization_ref = 1;
-  string owner_ref = 2;
+  reserved 2;
+  reserved "owner_ref";
   Asset asset = 3;
   common.pagination.v1.CursorPageRequest page = 4;
+  // Optional owner filter with 3-state semantics:
+  // - not set: return all wallets within organization
+  // - set to empty string: return wallets where owner_ref is null/empty
+  // - set to a value: return wallets where owner_ref matches
+  google.protobuf.StringValue owner_ref_filter = 5;
 }
 
 message ListManagedWalletsResponse {

api/proto/ledger/v1/ledger.proto

@@ -5,6 +5,7 @@ package ledger.v1;
 option go_package = "github.com/tech/sendico/pkg/proto/ledger/v1;ledgerv1";
 
 import "google/protobuf/timestamp.proto";
+import "google/protobuf/wrappers.proto";
 import "common/describable/v1/describable.proto";
 import "common/money/v1/money.proto";
 
@@ -43,6 +44,21 @@ enum AccountStatus {
   ACCOUNT_STATUS_FROZEN      = 2;
 }
 
+enum AccountRole {
+  ACCOUNT_ROLE_UNSPECIFIED = 0;
+  ACCOUNT_ROLE_OPERATING   = 1;
+  ACCOUNT_ROLE_HOLD        = 2;
+  ACCOUNT_ROLE_TRANSIT     = 3;
+  ACCOUNT_ROLE_SETTLEMENT  = 4;
+  ACCOUNT_ROLE_CLEARING    = 5;
+  ACCOUNT_ROLE_PENDING     = 6;
+  ACCOUNT_ROLE_RESERVE     = 7;
+  ACCOUNT_ROLE_LIQUIDITY   = 8;
+  ACCOUNT_ROLE_FEE         = 9;
+  ACCOUNT_ROLE_CHARGEBACK  = 10;
+  ACCOUNT_ROLE_ADJUSTMENT  = 11;
+}
+
 // LedgerAccount captures the canonical representation of an account resource.
 message LedgerAccount {
   string ledger_account_ref          = 1;
@@ -52,12 +68,14 @@ message LedgerAccount {
   string currency                    = 5;
   AccountStatus status               = 6;
   bool allow_negative                = 7;
-  bool is_settlement                 = 8;
+  reserved 8;
+  reserved "is_settlement";
   map<string, string> metadata       = 9;
   google.protobuf.Timestamp created_at = 10;
   google.protobuf.Timestamp updated_at = 11;
   common.describable.v1.Describable describable = 12;
   string owner_ref            = 13;
+  AccountRole role            = 14;
 }
 
 // A single posting line (mirrors your PostingLine model)
@@ -78,9 +96,11 @@ message CreateAccountRequest {
   string currency         = 5;
   AccountStatus status    = 6;
   bool allow_negative     = 7;
-  bool is_settlement      = 8;
+  reserved 8;
+  reserved "is_settlement";
   map<string, string> metadata = 9;
   common.describable.v1.Describable describable = 10;
+  AccountRole role = 11;
 }
 
 message CreateAccountResponse {
@@ -98,6 +118,7 @@ message PostCreditRequest {
   map<string, string> metadata     = 7;
   google.protobuf.Timestamp event_time = 8;
   string contra_ledger_account_ref = 9; // optional override for settlement/contra account
+  AccountRole role                 = 10; // optional: assert target account has this role
 }
 
 message PostDebitRequest {
@@ -110,6 +131,7 @@ message PostDebitRequest {
   map<string, string> metadata     = 7;
   google.protobuf.Timestamp event_time = 8;
   string contra_ledger_account_ref = 9; // optional override for settlement/contra account
+  AccountRole role                 = 10; // optional: assert target account has this role
 }
 
 message TransferRequest {
@@ -122,6 +144,8 @@ message TransferRequest {
   repeated PostingLine charges     = 7; // optional FEE/SPREAD lines
   map<string, string> metadata     = 8;
   google.protobuf.Timestamp event_time = 9;
+  AccountRole from_role = 10;
+  AccountRole to_role = 11;
 }
 
 message FXRequest {
@@ -188,8 +212,35 @@ message StatementResponse {
 
 message ListAccountsRequest {
   string organization_ref = 1;
+  // Optional owner filter with 3-state semantics:
+  // - not set: return all accounts within organization
+  // - set to empty string: return accounts where owner_ref is null/empty
+  // - set to a value: return accounts where owner_ref matches
+  google.protobuf.StringValue owner_ref_filter = 2;
 }
 
 message ListAccountsResponse {
   repeated LedgerAccount accounts = 1;
 }
+
+// ---- Account status mutations ----
+
+message BlockAccountRequest {
+  string ledger_account_ref = 1;
+  string organization_ref   = 2;
+  AccountRole role           = 3; // optional: assert account has this role before blocking
+}
+
+message BlockAccountResponse {
+  LedgerAccount account = 1;
+}
+
+message UnblockAccountRequest {
+  string ledger_account_ref = 1;
+  string organization_ref   = 2;
+  AccountRole role           = 3; // optional: assert account has this role before unblocking
+}
+
+message UnblockAccountResponse {
+  LedgerAccount account = 1;
+}