feat(api): api update

.github/workflows/ci.yml

@@ -55,3 +55,22 @@ jobs:
 
       - name: Run build
         run: uv build
+
+  test:
+    timeout-minutes: 10
+    name: test
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
+        with:
+          version: '0.10.2'
+
+      - name: Bootstrap
+        run: ./scripts/bootstrap
+
+      - name: Run tests
+        run: ./scripts/test

.stats.yml

@@ -1,3 +1,3 @@
 configured_endpoints: 238
-openapi_spec_hash: ed21325b0e3f886a49c45d2decc4f5d0
+openapi_spec_hash: 27aa7d8f7762271b625489f107ff4e8a
 config_hash: 2ae0d8aaecf01b38cbf9f9e112822c23

pyproject.toml

@@ -90,18 +90,14 @@ include = [
 packages = ["src/increase"]
 
 [tool.hatch.build.targets.sdist]
-# Basically everything except hidden files/directories (such as .github, .devcontainers, .python-version, etc)
+# Runtime package (src/) plus top-level metadata only.
+# Dev files (tests/, examples/, tooling) stay out of the published sdist.
 include = [
   "/*.toml",
   "/*.json",
   "/*.lock",
   "/*.md",
-  "/mypy.ini",
-  "/noxfile.py",
-  "bin/*",
-  "examples/*",
   "src/*",
-  "tests/*",
 ]
 
 [tool.hatch.metadata.hooks.fancy-pypi-readme]

src/increase/resources/accounts.py

@@ -83,8 +83,9 @@ def create(
 
           loan: The loan details for the account.
 
-          program_id: The identifier for the Program that this Account falls under. Required if you
-              operate more than one Program.
+          program_id: The identifier for the Program that this Account falls under. Required if your
+              Group operates more than one Program. List your [Programs](#programs) to find
+              their identifiers.
 
           extra_headers: Send extra headers
 
@@ -423,8 +424,9 @@ async def create(
 
           loan: The loan details for the account.
 
-          program_id: The identifier for the Program that this Account falls under. Required if you
-              operate more than one Program.
+          program_id: The identifier for the Program that this Account falls under. Required if your
+              Group operates more than one Program. List your [Programs](#programs) to find
+              their identifiers.
 
           extra_headers: Send extra headers
 

src/increase/resources/ach_transfers.py

@@ -97,26 +97,34 @@ def create(
               help the customer recognize the transfer. You are highly encouraged to pass
               `individual_name` and `company_name` instead of relying on this fallback.
 
-          account_number: The account number for the destination account.
+          account_number: The receiver's account number. For credit transfers (positive `amount`) this is
+              the account that funds will be sent to. For debit transfers (negative `amount`)
+              this is the account that funds will be pulled from.
 
-          addenda: Additional information that will be sent to the recipient. This is included in
-              the transfer data sent to the receiving bank.
+          addenda: Additional information passed through to the receiving bank with the transfer.
+              Most ACH transfers do not need this. Only set this if your recipient has asked
+              for addendum data, typically unstructured remittance information. Corporate
+              Trade Exchange (CTX) flows can carry structured X12 remittance advice instead.
 
-          company_descriptive_date: The description of the date of the transfer, usually in the format `YYMMDD`.
-              This is included in the transfer data sent to the receiving bank.
+          company_descriptive_date: A description of the transfer date (typically `YYMMDD`), sent in the company
+              batch header. This value is informational and does not affect funds movement,
+              settlement timing, or returns. Only set this if your recipient has asked for it.
 
-          company_discretionary_data: The data you choose to associate with the transfer. This is included in the
-              transfer data sent to the receiving bank.
+          company_discretionary_data: Custom data sent in the company batch header. This value is informational and
+              does not affect funds movement, settlement timing, or returns. Most ACH
+              transfers do not need this. Only set this if your recipient has asked for it.
 
-          company_entry_description: A description of the transfer, included in the transfer data sent to the
-              receiving bank. Standardized formatting may be required, for example `PAYROLL`
-              for payroll-related Prearranged Payments and Deposits (PPD) credit transfers.
+          company_entry_description: A short description sent in the company batch header. Most receivers do not
+              surface this. Only set this if your recipient has asked for a specific value or
+              if Nacha mandates one for your Standard Entry Class (SEC) code and use case. For
+              example, Prearranged Payment and Deposit (PPD) payroll credits must use
+              `PAYROLL`, and reversals must use `REVERSAL`.
 
-          company_name: The name by which the recipient knows you. This is included in the transfer data
-              sent to the receiving bank.
+          company_name: The name by which the recipient knows you, sent in the company batch header. We
+              recommend setting this on every transfer; if you do not, we fall back to the ACH
+              company name configured on your account.
 
-          destination_account_holder: The type of entity that owns the account to which the ACH Transfer is being
-              sent.
+          destination_account_holder: The type of entity that owns the receiver's account.
 
               - `business` - The External Account is owned by a business.
               - `individual` - The External Account is owned by an individual.
@@ -125,14 +133,15 @@ def create(
           external_account_id: The ID of an External Account to initiate a transfer to. If this parameter is
               provided, `account_number`, `routing_number`, and `funding` must be absent.
 
-          funding: The type of the account to which the transfer will be sent.
+          funding: The type of the receiver's bank account.
 
               - `checking` - A checking account.
               - `savings` - A savings account.
               - `loan` - A loan account used in a lender-borrower relationship. Uncommon.
               - `general_ledger` - A bank's general ledger. Uncommon.
 
-          individual_id: Your identifier for the transfer recipient.
+          individual_id: Your internal identifier for the transfer recipient. This value is informational
+              and not verified by the recipient's bank. Most callers can leave this unset.
 
           individual_name: The name of the transfer recipient. This value is informational and not verified
               by the recipient's bank.
@@ -144,12 +153,13 @@ def create(
 
           require_approval: Whether the transfer requires explicit approval via the dashboard or API.
 
-          routing_number: The American Bankers' Association (ABA) Routing Transit Number (RTN) for the
-              destination account.
+          routing_number: The American Bankers' Association (ABA) Routing Transit Number (RTN) of the
+              receiver's bank.
 
           standard_entry_class_code: The
               [Standard Entry Class (SEC) code](/documentation/ach-standard-entry-class-codes)
-              to use for the transfer.
+              to use for the transfer. If not provided, the default is
+              `corporate_credit_or_debit`.
 
               - `corporate_credit_or_debit` - Corporate Credit and Debit (CCD) is used for
                 business-to-business payments.
@@ -475,26 +485,34 @@ async def create(
               help the customer recognize the transfer. You are highly encouraged to pass
               `individual_name` and `company_name` instead of relying on this fallback.
 
-          account_number: The account number for the destination account.
+          account_number: The receiver's account number. For credit transfers (positive `amount`) this is
+              the account that funds will be sent to. For debit transfers (negative `amount`)
+              this is the account that funds will be pulled from.
 
-          addenda: Additional information that will be sent to the recipient. This is included in
-              the transfer data sent to the receiving bank.
+          addenda: Additional information passed through to the receiving bank with the transfer.
+              Most ACH transfers do not need this. Only set this if your recipient has asked
+              for addendum data, typically unstructured remittance information. Corporate
+              Trade Exchange (CTX) flows can carry structured X12 remittance advice instead.
 
-          company_descriptive_date: The description of the date of the transfer, usually in the format `YYMMDD`.
-              This is included in the transfer data sent to the receiving bank.
+          company_descriptive_date: A description of the transfer date (typically `YYMMDD`), sent in the company
+              batch header. This value is informational and does not affect funds movement,
+              settlement timing, or returns. Only set this if your recipient has asked for it.
 
-          company_discretionary_data: The data you choose to associate with the transfer. This is included in the
-              transfer data sent to the receiving bank.
+          company_discretionary_data: Custom data sent in the company batch header. This value is informational and
+              does not affect funds movement, settlement timing, or returns. Most ACH
+              transfers do not need this. Only set this if your recipient has asked for it.
 
-          company_entry_description: A description of the transfer, included in the transfer data sent to the
-              receiving bank. Standardized formatting may be required, for example `PAYROLL`
-              for payroll-related Prearranged Payments and Deposits (PPD) credit transfers.
+          company_entry_description: A short description sent in the company batch header. Most receivers do not
+              surface this. Only set this if your recipient has asked for a specific value or
+              if Nacha mandates one for your Standard Entry Class (SEC) code and use case. For
+              example, Prearranged Payment and Deposit (PPD) payroll credits must use
+              `PAYROLL`, and reversals must use `REVERSAL`.
 
-          company_name: The name by which the recipient knows you. This is included in the transfer data
-              sent to the receiving bank.
+          company_name: The name by which the recipient knows you, sent in the company batch header. We
+              recommend setting this on every transfer; if you do not, we fall back to the ACH
+              company name configured on your account.
 
-          destination_account_holder: The type of entity that owns the account to which the ACH Transfer is being
-              sent.
+          destination_account_holder: The type of entity that owns the receiver's account.
 
               - `business` - The External Account is owned by a business.
               - `individual` - The External Account is owned by an individual.
@@ -503,14 +521,15 @@ async def create(
           external_account_id: The ID of an External Account to initiate a transfer to. If this parameter is
               provided, `account_number`, `routing_number`, and `funding` must be absent.
 
-          funding: The type of the account to which the transfer will be sent.
+          funding: The type of the receiver's bank account.
 
               - `checking` - A checking account.
               - `savings` - A savings account.
               - `loan` - A loan account used in a lender-borrower relationship. Uncommon.
               - `general_ledger` - A bank's general ledger. Uncommon.
 
-          individual_id: Your identifier for the transfer recipient.
+          individual_id: Your internal identifier for the transfer recipient. This value is informational
+              and not verified by the recipient's bank. Most callers can leave this unset.
 
           individual_name: The name of the transfer recipient. This value is informational and not verified
               by the recipient's bank.
@@ -522,12 +541,13 @@ async def create(
 
           require_approval: Whether the transfer requires explicit approval via the dashboard or API.
 
-          routing_number: The American Bankers' Association (ABA) Routing Transit Number (RTN) for the
-              destination account.
+          routing_number: The American Bankers' Association (ABA) Routing Transit Number (RTN) of the
+              receiver's bank.
 
           standard_entry_class_code: The
               [Standard Entry Class (SEC) code](/documentation/ach-standard-entry-class-codes)
-              to use for the transfer.
+              to use for the transfer. If not provided, the default is
+              `corporate_credit_or_debit`.
 
               - `corporate_credit_or_debit` - Corporate Credit and Debit (CCD) is used for
                 business-to-business payments.

src/increase/resources/inbound_mail_items.py

@@ -153,7 +153,9 @@ def action(
         idempotency_key: str | None = None,
     ) -> InboundMailItem:
         """
-        Action an Inbound Mail Item
+        Deposits or ignores each check contained in a pending Inbound Mail Item.
+        Depositing a check creates a [Check Deposit](#check-deposits) into the Account
+        you specify.
 
         Args:
           inbound_mail_item_id: The identifier of the Inbound Mail Item to action.
@@ -319,7 +321,9 @@ async def action(
         idempotency_key: str | None = None,
     ) -> InboundMailItem:
         """
-        Action an Inbound Mail Item
+        Deposits or ignores each check contained in a pending Inbound Mail Item.
+        Depositing a check creates a [Check Deposit](#check-deposits) into the Account
+        you specify.
 
         Args:
           inbound_mail_item_id: The identifier of the Inbound Mail Item to action.

src/increase/resources/lockbox_addresses.py

@@ -56,8 +56,12 @@ def create(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
         idempotency_key: str | None = None,
     ) -> LockboxAddress:
-        """
-        Create a Lockbox Address
+        """The Lockbox Address starts with a `pending` status and a null `address`.
+
+        Shortly
+        after creation, Increase generates the mailing address and the status becomes
+        `active`. You can only create Lockbox Recipients for an `active` Lockbox
+        Address.
 
         Args:
           description: The description you choose for the Lockbox Address.
@@ -271,8 +275,12 @@ async def create(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
         idempotency_key: str | None = None,
     ) -> LockboxAddress:
-        """
-        Create a Lockbox Address
+        """The Lockbox Address starts with a `pending` status and a null `address`.
+
+        Shortly
+        after creation, Increase generates the mailing address and the status becomes
+        `active`. You can only create Lockbox Recipients for an `active` Lockbox
+        Address.
 
         Args:
           description: The description you choose for the Lockbox Address.

src/increase/resources/lockbox_recipients.py

@@ -65,7 +65,8 @@ def create(
         Args:
           account_id: The Account that checks sent to this Lockbox Recipient should be deposited into.
 
-          lockbox_address_id: The Lockbox Address where this Lockbox Recipient may receive mail.
+          lockbox_address_id: The Lockbox Address where this Lockbox Recipient may receive mail. The Lockbox
+              Address must have a `status` of `active`.
 
           description: The description you choose for the Lockbox Recipient.
 
@@ -313,7 +314,8 @@ async def create(
         Args:
           account_id: The Account that checks sent to this Lockbox Recipient should be deposited into.
 
-          lockbox_address_id: The Lockbox Address where this Lockbox Recipient may receive mail.
+          lockbox_address_id: The Lockbox Address where this Lockbox Recipient may receive mail. The Lockbox
+              Address must have a `status` of `active`.
 
           description: The description you choose for the Lockbox Recipient.
 

src/increase/resources/simulations/card_authorizations.py

@@ -102,7 +102,10 @@ def create(
         `card_authorization` or a [Declined Transaction](#declined-transactions) of type
         `card_decline`. You can pass either a Card id or a
         [Digital Wallet Token](#digital-wallet-tokens) id to simulate the two different
-        ways purchases can be made.
+        ways purchases can be made. The response will contain either a
+        `pending_transaction` or a `declined_transaction`; the other attribute will be
+        null. If the authorization is declined, the reason is available on the Declined
+        Transaction at `source.card_decline.reason`.
 
         Args:
           amount: The authorization amount in cents.
@@ -306,7 +309,10 @@ async def create(
         `card_authorization` or a [Declined Transaction](#declined-transactions) of type
         `card_decline`. You can pass either a Card id or a
         [Digital Wallet Token](#digital-wallet-tokens) id to simulate the two different
-        ways purchases can be made.
+        ways purchases can be made. The response will contain either a
+        `pending_transaction` or a `declined_transaction`; the other attribute will be
+        null. If the authorization is declined, the reason is available on the Declined
+        Transaction at `source.card_decline.reason`.
 
         Args:
           amount: The authorization amount in cents.

src/increase/resources/simulations/inbound_ach_transfers.py

@@ -116,7 +116,8 @@ def create(
 
           company_id: The sender's company ID.
 
-          company_name: The name of the sender.
+          company_name: The name of the sender. This corresponds to the `originator_company_name` field
+              on the resulting Inbound ACH Transfer.
 
           receiver_id_number: The ID of the receiver of the transfer.
 
@@ -275,7 +276,8 @@ async def create(
 
           company_id: The sender's company ID.
 
-          company_name: The name of the sender.
+          company_name: The name of the sender. This corresponds to the `originator_company_name` field
+              on the resulting Inbound ACH Transfer.
 
           receiver_id_number: The ID of the receiver of the transfer.