feat(ledger): a journal entry line's cash flow row, and the in-place re-tag

robosystems_client/api/robo_ledger_ledger_events/update_journal_entry.py

@@ -113,20 +113,25 @@ def sync_detailed(
 ) -> Response[ErrorResponse | OperationEnvelopeJournalEntryResponse]:
   """Update Journal Entry
 
-   Update a draft journal entry. Posted entries are immutable and must be corrected via `create-event-
-  block(event_type='journal_entry_reversed')`. If line_items is provided, existing line items are
-  replaced atomically, the new set must balance, and a line on a retired (`is_active=false`) account
-  is refused.
+   Update a draft journal entry, or re-tag any entry's flows. If line_items is provided, existing line
+  items are replaced atomically, the new set must balance, and a line on a retired (`is_active=false`)
+  account is refused. `line_flows` sets the cash flow row of the named lines in place, on a posted
+  entry too, closed month included, since a flow moves no balance; the lines on the other side of the
+  entry follow when that side carries one flow. Posted entries accept nothing else and are corrected
+  via `create-event-block(event_type='journal_entry_reversed')`.
 
   **Idempotency**: supply an `Idempotency-Key` header to make safe retries; replays within 24 hours
   return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.
 
   Args:
       graph_id (str):
       idempotency_key (None | str | Unset):
-      body (UpdateJournalEntryRequest): Update a draft journal entry. Posted entries cannot be
-          updated —
-          create a reversal and a corrected entry instead.
+      body (UpdateJournalEntryRequest): Update a draft journal entry, or re-tag any entry's
+          flows.
+
+          Posted entries accept only `line_flows`: a flow moves no balance, so it
+          changes in place, closed month or not. Anything else on a posted entry is
+          a reversal and a corrected entry.
 
           Omitted fields are left unchanged. If `line_items` is provided, the
           existing line items are replaced entirely (atomic delete + insert)
@@ -163,20 +168,25 @@ def sync(
 ) -> ErrorResponse | OperationEnvelopeJournalEntryResponse | None:
   """Update Journal Entry
 
-   Update a draft journal entry. Posted entries are immutable and must be corrected via `create-event-
-  block(event_type='journal_entry_reversed')`. If line_items is provided, existing line items are
-  replaced atomically, the new set must balance, and a line on a retired (`is_active=false`) account
-  is refused.
+   Update a draft journal entry, or re-tag any entry's flows. If line_items is provided, existing line
+  items are replaced atomically, the new set must balance, and a line on a retired (`is_active=false`)
+  account is refused. `line_flows` sets the cash flow row of the named lines in place, on a posted
+  entry too, closed month included, since a flow moves no balance; the lines on the other side of the
+  entry follow when that side carries one flow. Posted entries accept nothing else and are corrected
+  via `create-event-block(event_type='journal_entry_reversed')`.
 
   **Idempotency**: supply an `Idempotency-Key` header to make safe retries; replays within 24 hours
   return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.
 
   Args:
       graph_id (str):
       idempotency_key (None | str | Unset):
-      body (UpdateJournalEntryRequest): Update a draft journal entry. Posted entries cannot be
-          updated —
-          create a reversal and a corrected entry instead.
+      body (UpdateJournalEntryRequest): Update a draft journal entry, or re-tag any entry's
+          flows.
+
+          Posted entries accept only `line_flows`: a flow moves no balance, so it
+          changes in place, closed month or not. Anything else on a posted entry is
+          a reversal and a corrected entry.
 
           Omitted fields are left unchanged. If `line_items` is provided, the
           existing line items are replaced entirely (atomic delete + insert)
@@ -208,20 +218,25 @@ async def asyncio_detailed(
 ) -> Response[ErrorResponse | OperationEnvelopeJournalEntryResponse]:
   """Update Journal Entry
 
-   Update a draft journal entry. Posted entries are immutable and must be corrected via `create-event-
-  block(event_type='journal_entry_reversed')`. If line_items is provided, existing line items are
-  replaced atomically, the new set must balance, and a line on a retired (`is_active=false`) account
-  is refused.
+   Update a draft journal entry, or re-tag any entry's flows. If line_items is provided, existing line
+  items are replaced atomically, the new set must balance, and a line on a retired (`is_active=false`)
+  account is refused. `line_flows` sets the cash flow row of the named lines in place, on a posted
+  entry too, closed month included, since a flow moves no balance; the lines on the other side of the
+  entry follow when that side carries one flow. Posted entries accept nothing else and are corrected
+  via `create-event-block(event_type='journal_entry_reversed')`.
 
   **Idempotency**: supply an `Idempotency-Key` header to make safe retries; replays within 24 hours
   return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.
 
   Args:
       graph_id (str):
       idempotency_key (None | str | Unset):
-      body (UpdateJournalEntryRequest): Update a draft journal entry. Posted entries cannot be
-          updated —
-          create a reversal and a corrected entry instead.
+      body (UpdateJournalEntryRequest): Update a draft journal entry, or re-tag any entry's
+          flows.
+
+          Posted entries accept only `line_flows`: a flow moves no balance, so it
+          changes in place, closed month or not. Anything else on a posted entry is
+          a reversal and a corrected entry.
 
           Omitted fields are left unchanged. If `line_items` is provided, the
           existing line items are replaced entirely (atomic delete + insert)
@@ -256,20 +271,25 @@ async def asyncio(
 ) -> ErrorResponse | OperationEnvelopeJournalEntryResponse | None:
   """Update Journal Entry
 
-   Update a draft journal entry. Posted entries are immutable and must be corrected via `create-event-
-  block(event_type='journal_entry_reversed')`. If line_items is provided, existing line items are
-  replaced atomically, the new set must balance, and a line on a retired (`is_active=false`) account
-  is refused.
+   Update a draft journal entry, or re-tag any entry's flows. If line_items is provided, existing line
+  items are replaced atomically, the new set must balance, and a line on a retired (`is_active=false`)
+  account is refused. `line_flows` sets the cash flow row of the named lines in place, on a posted
+  entry too, closed month included, since a flow moves no balance; the lines on the other side of the
+  entry follow when that side carries one flow. Posted entries accept nothing else and are corrected
+  via `create-event-block(event_type='journal_entry_reversed')`.
 
   **Idempotency**: supply an `Idempotency-Key` header to make safe retries; replays within 24 hours
   return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.
 
   Args:
       graph_id (str):
       idempotency_key (None | str | Unset):
-      body (UpdateJournalEntryRequest): Update a draft journal entry. Posted entries cannot be
-          updated —
-          create a reversal and a corrected entry instead.
+      body (UpdateJournalEntryRequest): Update a draft journal entry, or re-tag any entry's
+          flows.
+
+          Posted entries accept only `line_flows`: a flow moves no balance, so it
+          changes in place, closed month or not. Anything else on a posted entry is
+          a reversal and a corrected entry.
 
           Omitted fields are left unchanged. If `line_items` is provided, the
           existing line items are replaced entirely (atomic delete + insert)

robosystems_client/clients/ledger_client.py

@@ -1992,6 +1992,12 @@ def create_journal_entry(
     ``entity_id`` names the entity whose books the entry goes into; omitted,
     the group parent's.
 
+    A line dict may carry ``flow_qname``, the cash flow row its cash belongs
+    to (a ``qname`` from ``get_flow_candidates``): only for a loan drawn or
+    repaid, capital put in or taken out, an asset bought or sold. A flow on
+    one side of the entry tags the untagged lines on the other; one that is
+    not a row of the entity's statement is refused.
+
     Returns the EventBlockEnvelope (event row fields).
     """
     metadata: dict[str, Any] = {
@@ -2024,7 +2030,13 @@ def create_journal_entry(
   def update_journal_entry(
     self, graph_id: str, body: dict[str, Any]
   ) -> JournalEntryResponse:
-    """Update a draft journal entry. Posted entries are immutable."""
+    """Update a draft journal entry, or re-tag any entry's flows.
+
+    ``line_flows`` (``[{"line_id", "flow_qname"}]``) sets the cash flow row
+    of the named lines in place, on a posted entry too, closed month
+    included, since a flow moves no balance; the lines on the other side of
+    the entry follow. It is the only change a posted entry accepts.
+    """
     request = UpdateJournalEntryRequest.from_dict(body)
     response = op_update_journal_entry(
       graph_id=graph_id, body=request, client=self._get_client()

robosystems_client/graphql/generated/list_ledger_journal_entries.py

@@ -47,6 +47,7 @@ class ListLedgerJournalEntriesJournalEntriesEntriesLineItems(BaseModel):
   credit_amount: float = Field(alias="creditAmount")
   description: Optional[str]
   line_order: int = Field(alias="lineOrder")
+  flow_qname: Optional[str] = Field(alias="flowQname")
 
 
 class ListLedgerJournalEntriesJournalEntriesPagination(BaseModel):

robosystems_client/graphql/generated/operations.py

@@ -1659,6 +1659,7 @@
         creditAmount
         description
         lineOrder
+        flowQname
       }
     }
     pagination {

robosystems_client/graphql/operations/ledger/ListLedgerJournalEntries.graphql

@@ -27,7 +27,7 @@ query ListLedgerJournalEntries(
       totalDebit totalCredit balanced
       lineItems {
         id accountId accountName accountCode
-        debitAmount creditAmount description lineOrder
+        debitAmount creditAmount description lineOrder flowQname
       }
     }
     pagination { total limit offset hasMore }

robosystems_client/graphql/schema.graphql

@@ -2257,6 +2257,7 @@ type LedgerLineItem {
   creditAmount: Float!
   description: String
   lineOrder: Int!
+  flowQname: String
 }
 
 """

robosystems_client/models/__init__.py

@@ -375,6 +375,7 @@
 from .invoice import Invoice
 from .invoice_line_item import InvoiceLineItem
 from .invoices_response import InvoicesResponse
+from .journal_entry_line_flow import JournalEntryLineFlow
 from .journal_entry_line_item_input import JournalEntryLineItemInput
 from .journal_entry_line_item_input_metadata_type_0 import (
   JournalEntryLineItemInputMetadataType0,
@@ -1460,6 +1461,7 @@
   "Invoice",
   "InvoiceLineItem",
   "InvoicesResponse",
+  "JournalEntryLineFlow",
   "JournalEntryLineItemInput",
   "JournalEntryLineItemInputMetadataType0",
   "JournalEntryLineItemResponse",

robosystems_client/models/journal_entry_line_flow.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, TypeVar, cast
+
+from attrs import define as _attrs_define
+from attrs import field as _attrs_field
+
+from ..types import UNSET, Unset
+
+T = TypeVar("T", bound="JournalEntryLineFlow")
+
+
+@_attrs_define
+class JournalEntryLineFlow:
+  """A line's cash flow row, set in place.
+
+  Attributes:
+      line_id (str): The line to re-tag, by id.
+      flow_qname (None | str | Unset): The rs-gaap flow qname the line takes; null clears it, back to the account's
+          default flow.
+  """
+
+  line_id: str
+  flow_qname: None | str | Unset = UNSET
+  additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict)
+
+  def to_dict(self) -> dict[str, Any]:
+    line_id = self.line_id
+
+    flow_qname: None | str | Unset
+    if isinstance(self.flow_qname, Unset):
+      flow_qname = UNSET
+    else:
+      flow_qname = self.flow_qname
+
+    field_dict: dict[str, Any] = {}
+    field_dict.update(self.additional_properties)
+    field_dict.update(
+      {
+        "line_id": line_id,
+      }
+    )
+    if flow_qname is not UNSET:
+      field_dict["flow_qname"] = flow_qname
+
+    return field_dict
+
+  @classmethod
+  def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T:
+    d = dict(src_dict)
+    line_id = d.pop("line_id")
+
+    def _parse_flow_qname(data: object) -> None | str | Unset:
+      if data is None:
+        return data
+      if isinstance(data, Unset):
+        return data
+      return cast(None | str | Unset, data)
+
+    flow_qname = _parse_flow_qname(d.pop("flow_qname", UNSET))
+
+    journal_entry_line_flow = cls(
+      line_id=line_id,
+      flow_qname=flow_qname,
+    )
+
+    journal_entry_line_flow.additional_properties = d
+    return journal_entry_line_flow
+
+  @property
+  def additional_keys(self) -> list[str]:
+    return list(self.additional_properties.keys())
+
+  def __getitem__(self, key: str) -> Any:
+    return self.additional_properties[key]
+
+  def __setitem__(self, key: str, value: Any) -> None:
+    self.additional_properties[key] = value
+
+  def __delitem__(self, key: str) -> None:
+    del self.additional_properties[key]
+
+  def __contains__(self, key: str) -> bool:
+    return key in self.additional_properties

robosystems_client/models/journal_entry_line_item_input.py

@@ -29,6 +29,11 @@ class JournalEntryLineItemInput:
           debit_amount (int | Unset): Debit amount in cents. Must be 0 if `credit_amount` > 0. Default: 0.
           credit_amount (int | Unset): Credit amount in cents. Must be 0 if `debit_amount` > 0. Default: 0.
           description (None | str | Unset): Per-line memo (overrides the entry-level memo on this line).
+          flow_qname (None | str | Unset): The cash flow row this line's cash belongs to, an rs-gaap flow qname
+              (`flowCandidates(entityId)` lists the rows this company's statement offers). Only for a loan drawn or repaid,
+              capital put in or taken out, an asset bought or sold; omitted, the account's default flow applies. A flow set on
+              one side of the entry tags the untagged lines on the other: the cash flow statement reads the cash line and the
+              roll-forwards read the account line. Refused when it is not a row of the entity's cash flow statement.
           metadata (JournalEntryLineItemInputMetadataType0 | None | Unset): Optional per-line metadata stamped on
               `LineItem.metadata_`. Used to carry source-system fields the standard columns don't cover — e.g. an external
               flow-tag code that drives rollforward attribution (`transaction_description_code`), an external memo, or a cost-
@@ -40,6 +45,7 @@ class JournalEntryLineItemInput:
   debit_amount: int | Unset = 0
   credit_amount: int | Unset = 0
   description: None | str | Unset = UNSET
+  flow_qname: None | str | Unset = UNSET
   metadata: JournalEntryLineItemInputMetadataType0 | None | Unset = UNSET
   additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict)
 
@@ -60,6 +66,12 @@ def to_dict(self) -> dict[str, Any]:
     else:
       description = self.description
 
+    flow_qname: None | str | Unset
+    if isinstance(self.flow_qname, Unset):
+      flow_qname = UNSET
+    else:
+      flow_qname = self.flow_qname
+
     metadata: dict[str, Any] | None | Unset
     if isinstance(self.metadata, Unset):
       metadata = UNSET
@@ -81,6 +93,8 @@ def to_dict(self) -> dict[str, Any]:
       field_dict["credit_amount"] = credit_amount
     if description is not UNSET:
       field_dict["description"] = description
+    if flow_qname is not UNSET:
+      field_dict["flow_qname"] = flow_qname
     if metadata is not UNSET:
       field_dict["metadata"] = metadata
 
@@ -108,6 +122,15 @@ def _parse_description(data: object) -> None | str | Unset:
 
     description = _parse_description(d.pop("description", UNSET))
 
+    def _parse_flow_qname(data: object) -> None | str | Unset:
+      if data is None:
+        return data
+      if isinstance(data, Unset):
+        return data
+      return cast(None | str | Unset, data)
+
+    flow_qname = _parse_flow_qname(d.pop("flow_qname", UNSET))
+
     def _parse_metadata(
       data: object,
     ) -> JournalEntryLineItemInputMetadataType0 | None | Unset:
@@ -132,6 +155,7 @@ def _parse_metadata(
       debit_amount=debit_amount,
       credit_amount=credit_amount,
       description=description,
+      flow_qname=flow_qname,
       metadata=metadata,
     )