orionapi 2.26.0__tar.gz → 2.28.0__tar.gz

{orionapi-2.26.0 → orionapi-2.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orionapi
-Version: 2.26.0
+Version: 2.28.0
 Summary: A python interface for the Orion Advisors platform web API
 Author: spencerogden-dsam
 Author-email: 67068943+spencerogden-dsam@users.noreply.github.com

{orionapi-2.26.0 → orionapi-2.28.0}/orionapi/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "2.26.0"
+__version__ = "2.28.0"
 
 import logging
 import re
@@ -56,10 +56,16 @@ TRADE_INSTANCE_SUBTYPES = {
 }
 
 # TradingApplication mappings for the v2 /TradeOrder/Trades endpoints.
-# Not published in the Swagger (which lists the ints with no names) -- recovered
-# 2026-07-28 from the API's own rejection messages ("Trade Application <Name> is
-# not supported."). Only MANUAL_TRADE (11) actually creates trade orders; see
+# Not published in the Swagger (which lists the ints with no names). Names 0-10
+# and 12-18 were recovered 2026-07-28 from the API's own rejection messages
+# ("Trade Application <Name> is not supported."); 11 is QuickTrades, confirmed
+# 2026-08-03 by Orion support and verified live (the string "QuickTrades" and the
+# int 11 return identical results). Only 11 creates trade orders -- see
 # EclipseV2.create_trades.
+#
+# These names are also accepted as *strings* in the ``application`` field, e.g.
+# ``{"application": "QuickTrades"}``. A name outside this set is rejected with
+# 400 "Error converting value ... to type 'OAS.Eclipse.Core.Enums.TradingApplication'".
 TRADING_APPLICATIONS = {
     0: "BuySell",
     1: "CashNeeds",
@@ -72,7 +78,7 @@ TRADING_APPLICATIONS = {
     8: "TaxLossHarvesting",
     9: "TickerSwap",
     10: "TradeToTargetPercent",
-    11: "ManualTrade",
+    11: "QuickTrades",
     12: "TacticalTrades",
     13: "PartialShare",
     14: "(unnamed, accepted but creates nothing)",
@@ -86,7 +92,12 @@ TRADING_APPLICATIONS = {
 # POST /api/v2/TradeOrder/Trades. Every other value except 14 returns
 # 400 "Trade Application <Name> is not supported."; 14 returns 200 with an
 # empty ``tradeId`` list and creates nothing. Live-verified 2026-07-28.
-TRADING_APPLICATION_MANUAL = 11
+TRADING_APPLICATION_QUICK_TRADES = 11
+
+# Deprecated alias. 2.26.0 shipped this as TRADING_APPLICATION_MANUAL on the
+# mistaken belief that 11 was named "ManualTrade"; the API rejects that name.
+# Kept so 2.26.0/2.27.0 callers keep working -- the value is unchanged.
+TRADING_APPLICATION_MANUAL = TRADING_APPLICATION_QUICK_TRADES
 
 # Set-Aside Cash Constants (from Eclipse API)
 CASH_TYPE_DOLLAR = 1
@@ -159,6 +170,31 @@ BILLING_BILL_TYPES = [
     "AdvanceCreditDebit",
 ]
 
+# Fields of the Orion API ReceiveableSummaryDto, the body of
+# POST /Billing/SyncCashtoEclipse. Identical to the CashFundingGridDto rows
+# returned by get_cash_funding(), except the grid's "id" is "accountId" here.
+RECEIVABLE_SUMMARY_FIELDS = (
+    "accountId",
+    "registrationName",
+    "registrationId",
+    "fundFamily",
+    "productName",
+    "moneyMarketBalance",
+    "balanceDue",
+    "difference",
+    "payMethod",
+    "clientId",
+    "clientLastName",
+    "clientName",
+    "accountType",
+    "accountNumber",
+    "managementStyle",
+    "accountIsActive",
+    "representativeName",
+    "feeReqSrc",
+    "instanceType",
+)
+
 
 class OrionAPIError(Exception):
     """Base exception for Orion API errors."""
@@ -178,6 +214,17 @@ class NotFoundError(OrionAPIError):
     pass
 
 
+class AmbiguousAccountError(OrionAPIError):
+    """Raised when an account search matches more than one account.
+
+    The message lists the candidate accounts (id, name, accountNumber) so the
+    caller can retry with an exact internal id, a full account number, or the
+    deliberate fuzzy workflow (``search_accounts_number_and_name``).
+    """
+
+    pass
+
+
 class RateLimiter:
     """Thread-safe rate limiter to prevent API abuse.
 
@@ -1655,10 +1702,13 @@ class OrionAPI(BaseAPI):
         if not isinstance(take, int) or take < 1:
             raise ValueError("take must be a positive integer")
 
+        # forecast is a boolean: Orion's own docs claim "1 = Forecast Bill,
+        # 0 = Live Bill", but the endpoint 400s on 0/1 and only accepts
+        # true/false.
         params = {
             "startDate": start_date,
             "endDate": end_date,
-            "forecast": 1 if is_forecast else 0,
+            "forecast": "true" if is_forecast else "false",
             "take": take,
         }
         if skip > 0:
@@ -1699,6 +1749,42 @@ class OrionAPI(BaseAPI):
         res = self.api_request(url, requests.post)
         return res.json()
 
+    def sync_cash_to_eclipse(self, account):
+        """Export one cash funding row to Eclipse as a cash set-aside.
+
+        This is the API equivalent of the Cash Funding grid's export action:
+        Orion creates (or updates) a set-aside in Eclipse for the account's
+        balance due, so the fee cash is reserved from trading.
+
+        Orion documents this as a draft endpoint that takes a single account
+        per call, so exporting a whole report means looping over the rows of
+        get_cash_funding().
+
+        Args:
+            account: A cash funding row as returned by get_cash_funding().
+                The row's ``id`` is the Orion account ID and is sent as
+                ``accountId``. A dict already keyed ``accountId`` is also
+                accepted. Keys outside ReceiveableSummaryDto are dropped.
+
+        Returns:
+            dict: The created/updated Eclipse set-aside
+                (EclipseCashFundingResponse) with id, accountId, cashAmount,
+                cashAmountTypeId, description, expirationTypeId, etc.
+        """
+        if not isinstance(account, dict):
+            raise ValueError("account must be a cash funding row dict")
+
+        account_id = account.get("accountId", account.get("id"))
+        if account_id is None:
+            raise ValueError("account must have an 'id' (or 'accountId') field")
+
+        payload = {k: account[k] for k in RECEIVABLE_SUMMARY_FIELDS if k in account}
+        payload["accountId"] = account_id
+
+        url = f"{self.base_url}/Billing/SyncCashtoEclipse"
+        res = self.api_request(url, requests.post, json=payload)
+        return res.json()
+
     # -------------------------------------------------------------------------
     # Bill Management
     # -------------------------------------------------------------------------
@@ -2284,30 +2370,71 @@ class EclipseBase(BaseAPI):
         res = self.api_request(f"{self.base_url}/account/accounts/simple")
         return res.json()
 
-    def get_internal_account_id(self, search_param):
+    def get_internal_account_id(self, search_param, fuzzy=False):
         """Get internal Eclipse account ID from a search parameter.
 
-        Searches across id, accountName, accountNumber, and portfolioName.
-        Best use is to pass a full custodian account number.
+        Searches across id, accountName, accountNumber, and portfolioName,
+        then resolves in tiers:
+
+        1. **Exact match:** a result whose internal ``id`` or ``accountNumber``
+           equals ``search_param`` is returned immediately. If an exact-id and
+           an exact-account-number match point at *different* accounts, raises
+           ``AmbiguousAccountError`` rather than guessing.
+        2. A single remaining candidate is returned.
+        3. Multiple candidates raise ``AmbiguousAccountError`` listing them,
+           unless ``fuzzy=True``, which returns the first match (the pre-2.28
+           behavior).
+
+        Best use is to pass a full custodian account number. Callers that
+        already hold the internal id should pass it via the
+        ``internal_account_id=`` keyword on scoped methods instead of
+        resolving here. For deliberate partial-number + name resolution use
+        :meth:`search_accounts_number_and_name`.
 
         Args:
             search_param: Account number, name, or ID to search for
+            fuzzy: When True, silently return the first match when multiple
+                candidates remain (default False)
 
         Returns:
             int: The internal Eclipse account ID
 
         Raises:
             NotFoundError: If no matching account is found
-
-        Note:
-            Returns the first matching result, which may not be expected
-            if multiple accounts match the search parameter.
+            AmbiguousAccountError: If multiple accounts match and no exact
+                match singles one out (and ``fuzzy`` is False)
         """
         res = self.search_accounts(search_param)
         logging.debug("search_accounts result: %s", res)
         if not res:
             raise NotFoundError(f"No account found for search: {search_param}")
-        return res[0]["id"]
+
+        def _candidates(accounts):
+            return [{k: a.get(k) for k in ("id", "name", "accountNumber")} for a in accounts]
+
+        search_str = str(search_param)
+        id_exact = [a for a in res if str(a.get("id")) == search_str]
+        number_exact = [a for a in res if a.get("accountNumber") == search_str]
+        exact = id_exact + [a for a in number_exact if a not in id_exact]
+        if len(exact) == 1:
+            return exact[0]["id"]
+        if len(exact) > 1:
+            raise AmbiguousAccountError(
+                f"Search '{search_param}' exactly matches both an internal id and "
+                f"other account numbers; pass internal_account_id= or a full "
+                f"account number. Candidates: {_candidates(exact)}"
+            )
+
+        if len(res) == 1:
+            return res[0]["id"]
+        if fuzzy:
+            return res[0]["id"]
+        raise AmbiguousAccountError(
+            f"Search '{search_param}' matched {len(res)} accounts with no exact "
+            f"id/accountNumber match. Pass an exact identifier, use "
+            f"search_accounts_number_and_name(), or pass fuzzy=True to accept "
+            f"the first match. Candidates: {_candidates(res)}"
+        )
 
     def search_accounts(self, search_param):
         """Search for accounts by various criteria.
@@ -2403,7 +2530,7 @@ class EclipseV1(EclipseBase):
         res = self.api_request(f"{self.base_url}/admin/authorization/user")
         return res.json()["userLoginId"]
 
-    def get_set_asides(self, account_id, active_only=False):
+    def get_set_asides(self, account_id=None, active_only=False, *, internal_account_id=None):
         """Get set-aside cash settings for a specific account (v1 surface).
 
         Returns the raw v1 records from ``GET /account/accounts/{id}/asidecash``.
@@ -2415,11 +2542,25 @@ class EclipseV1(EclipseBase):
             account_id: Account ID, number, or name (resolved via search).
             active_only: When True, keep only records where ``isActive`` is truthy.
                 Defaults to False (includes expired/inactive).
+            internal_account_id: Eclipse internal account id, used verbatim with
+                no search resolution — the deterministic path for callers that
+                already hold the id. Mutually exclusive with ``account_id``.
 
         Returns:
             list: Raw v1 set-aside records for the account.
-        """
-        internal_id = self.get_internal_account_id(account_id)
+
+        Raises:
+            ValueError: If both or neither of ``account_id`` /
+                ``internal_account_id`` are given.
+        """
+        if account_id is not None and internal_account_id is not None:
+            raise ValueError("pass account_id (search) or internal_account_id, not both")
+        if internal_account_id is not None:
+            internal_id = int(internal_account_id)
+        elif account_id is not None:
+            internal_id = self.get_internal_account_id(account_id)
+        else:
+            raise ValueError("account_id or internal_account_id is required")
         res = self.api_request(f"{self.base_url}/account/accounts/{internal_id}/asidecash")
         records = res.json()
         if active_only:
@@ -2428,8 +2569,8 @@ class EclipseV1(EclipseBase):
 
     def create_set_aside(
         self,
-        account_number,
-        amount,
+        account_number=None,
+        amount=None,
         min_amount=0.0,
         max_amount=0.0,
         description=None,
@@ -2442,11 +2583,14 @@ class EclipseV1(EclipseBase):
         deplete_over_time=False,
         percent_calc_type=0,
         sync=True,
+        *,
+        internal_account_id=None,
     ):
         """Create a set-aside cash reservation for an account.
 
         Args:
-            account_number: Full custodial account number
+            account_number: Full custodial account number (resolved via search).
+                Mutually exclusive with ``internal_account_id``.
             amount: Cash amount to set aside
             min_amount: Minimum cash amount (default 0.0)
             max_amount: Maximum cash amount (default 0.0)
@@ -2463,11 +2607,27 @@ class EclipseV1(EclipseBase):
             percent_calc_type: 0='Use Default/Managed Value', 1='Use Total Value',
                               2='Use Excluded Value' (default 0)
             sync: Wait for analytics to complete (default True)
+            internal_account_id: Eclipse internal account id, used verbatim with
+                no search resolution — the deterministic path for callers that
+                already hold the id. Mutually exclusive with ``account_number``.
 
         Returns:
             dict: Created set-aside details
-        """
-        account_id = self.get_internal_account_id(account_number)
+
+        Raises:
+            ValueError: If both or neither of ``account_number`` /
+                ``internal_account_id`` are given, or ``amount`` is missing.
+        """
+        if account_number is not None and internal_account_id is not None:
+            raise ValueError("pass account_number (search) or internal_account_id, not both")
+        if amount is None:
+            raise ValueError("amount is required")
+        if internal_account_id is not None:
+            account_id = int(internal_account_id)
+        elif account_number is not None:
+            account_id = self.get_internal_account_id(account_number)
+        else:
+            raise ValueError("account_number or internal_account_id is required")
 
         cash_type_map = {
             # end point account/accounts/asideCashAmountType
@@ -2969,6 +3129,13 @@ class EclipseV1(EclipseBase):
             :meth:`EclipseV2.create_trades` handles buys *and* sells and honours
             share count and dollar amount exactly.
 
+            Orion support's answer to the sell-500 case (2026-08-03) was to use
+            the **v2** wrapper body (``application`` / ``trades[]`` / ``action`` /
+            ``tradeShares``). That body is not accepted here -- posting it to this
+            v1 endpoint returns ``422 "Invalid trade order type id"`` for buys and
+            sells alike -- so it is a redirect to the v2 surface, not a fix for
+            this one. The v1 sell 500 remains unexplained upstream.
+
         The generic per-trade creator behind Eclipse's Quick Trade / journal flows,
         as opposed to the ``/tradetool/`` generators (:meth:`cash_needs_trade`,
         :meth:`rebalance_trade`, ...) which operate on whole portfolios.
@@ -6561,7 +6728,7 @@ class EclipseV2(EclipseBase):
             "end_date": end_date,
         }
 
-    def get_set_asides(self, account_id=None, active_only=False):
+    def get_set_asides(self, account_id=None, active_only=False, *, internal_account_id=None):
         """Get set-aside cash reservations, including the Eclipse set-aside id.
 
         Uses the v2 batch endpoint, which accepts a list of internal account IDs
@@ -6573,15 +6740,27 @@ class EclipseV2(EclipseBase):
 
         Args:
             account_id: Account ID, number, or name to restrict to a single
-                account. When None (default), returns set-asides firm-wide by
-                issuing one batch POST over all accounts.
+                account (resolved via search). When neither this nor
+                ``internal_account_id`` is given, returns set-asides firm-wide
+                by issuing one batch POST over all accounts.
             active_only: When True, return only currently-active set-asides.
                 Defaults to False (includes expired/inactive).
+            internal_account_id: Eclipse internal account id, used verbatim with
+                no search resolution — the deterministic path for callers that
+                already hold the id. Mutually exclusive with ``account_id``.
 
         Returns:
             list: Augmented set-aside records
-        """
-        if account_id is not None:
+
+        Raises:
+            ValueError: If both ``account_id`` and ``internal_account_id`` are
+                given.
+        """
+        if account_id is not None and internal_account_id is not None:
+            raise ValueError("pass account_id (search) or internal_account_id, not both")
+        if internal_account_id is not None:
+            account_ids = [int(internal_account_id)]
+        elif account_id is not None:
             account_ids = [self.get_internal_account_id(account_id)]
         else:
             account_ids = [a["id"] for a in self.get_all_accounts()]
@@ -7264,7 +7443,7 @@ class EclipseV2(EclipseBase):
     def validate_trades(
         self,
         trades,
-        application=TRADING_APPLICATION_MANUAL,
+        application=TRADING_APPLICATION_QUICK_TRADES,
         trade_tool_selection=2,
         trade_instance_type=5,
         trade_instance_sub_type=11,
@@ -7291,10 +7470,13 @@ class EclipseV2(EclipseBase):
                 Size each with ``shares`` (share count) or ``amount`` (dollars) --
                 see :meth:`build_trade` for the full parameter table.
             application: ``TradingApplication`` -- see :data:`TRADING_APPLICATIONS`.
-                Defaults to 11 (ManualTrade), the only value that creates orders on
-                :meth:`create_trades`. This endpoint tolerates other values, but
-                keeping the two in step avoids validating under one application and
-                creating under another.
+                Defaults to 11 (``QuickTrades``), the only value that creates orders
+                on :meth:`create_trades`. The enum name is also accepted as a string
+                (``"QuickTrades"``) and behaves identically. This endpoint tolerates
+                other values, but they are not equivalent: ``application=1``
+                (CashNeeds) returns ``isValid: False`` with ``tradeAmount: 0`` rather
+                than pricing the trade, so validating under one application and
+                creating under another gives a meaningless pre-flight.
             trade_tool_selection: 1=Portfolio, 2=Account, 3=Model, ... (default 2)
             trade_instance_type: See :data:`TRADE_INSTANCE_TYPES` (default 5, Quick Trade)
             trade_instance_sub_type: See :data:`TRADE_INSTANCE_SUBTYPES`
@@ -7325,7 +7507,7 @@ class EclipseV2(EclipseBase):
     def create_trades(
         self,
         trades,
-        application=TRADING_APPLICATION_MANUAL,
+        application=TRADING_APPLICATION_QUICK_TRADES,
         trade_tool_selection=2,
         trade_instance_type=5,
         trade_instance_sub_type=11,
@@ -7363,7 +7545,8 @@ class EclipseV2(EclipseBase):
                 Size each with ``shares`` (share count) or ``amount`` (dollars);
                 see :meth:`build_trade` for the full parameter table.
             application: ``TradingApplication`` -- see :data:`TRADING_APPLICATIONS`.
-                **Only 11 (ManualTrade) creates orders**, and it is the default.
+                **Only 11 (``QuickTrades``) creates orders**, and it is the default.
+                The enum name is also accepted as a string (``"QuickTrades"``).
                 Every other value except 14 returns 400 "Trade Application <Name>
                 is not supported."; 14 returns 200 with an empty ``tradeId`` list
                 and creates nothing, so it is rejected here rather than allowed to
@@ -7391,11 +7574,11 @@ class EclipseV2(EclipseBase):
             >>> e.create_trades([t])["tradeId"]
             [72495]
         """
-        if application != TRADING_APPLICATION_MANUAL:
+        if application != TRADING_APPLICATION_QUICK_TRADES:
             name = TRADING_APPLICATIONS.get(application, "unknown")
             raise ValueError(
                 f"application={application} ({name}) does not create trade orders on "
-                f"this endpoint; only {TRADING_APPLICATION_MANUAL} (ManualTrade) does. "
+                f"this endpoint; only {TRADING_APPLICATION_QUICK_TRADES} (QuickTrades) does. "
                 "Other values return 400, and 14 returns 200 while creating nothing."
             )
         for i, t in enumerate(trades or []):
@@ -11484,13 +11667,19 @@ class Eclipse(EclipseBase):
 
     # --- v2-preferred overrides (documented best-of-both choices) ---------------
 
-    def get_set_asides(self, account_id=None, active_only=False):
+    def get_set_asides(self, account_id=None, active_only=False, *, internal_account_id=None):
         """Set-asides via the v2 batch endpoint (best: firm-wide + set-aside id).
 
         Delegates to :meth:`EclipseV2.get_set_asides`. Use ``self.v1.get_set_asides``
-        for the raw per-account v1 form.
+        for the raw per-account v1 form. Pass ``internal_account_id=`` when you
+        already hold the Eclipse internal id — it is used verbatim, with no
+        search resolution.
         """
-        return self.v2.get_set_asides(account_id=account_id, active_only=active_only)
+        return self.v2.get_set_asides(
+            account_id=account_id,
+            active_only=active_only,
+            internal_account_id=internal_account_id,
+        )
 
 
 class EclipseAPI(Eclipse):

{orionapi-2.26.0 → orionapi-2.28.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "orionapi"
-version = "2.26.0"
+version = "2.28.0"
 description = "A python interface for the Orion Advisors platform web API"
 authors = ["spencerogden-dsam <67068943+spencerogden-dsam@users.noreply.github.com>"]