@atumlabs/payment-gateway-client 3.0.0 → 3.0.1

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+- **Breaking: `PaymentStatus` is one type across all three payment responses**, with the values `pending`, `finalizing`, `completed` and `failed`. Submitting a payment, polling its status and reading its timeline previously returned three unrelated status types, so a caller could not write one function that handled "a payment status". `settling` is gone — it described how far our own bookkeeping had got, not the payment. `cancelled` is gone too: nothing could produce it, and a payment that ends without being delivered is reported as `failed`. `isTerminalStatus('cancelled')` therefore returns `false` now. A caller with an exhaustive `switch` on status gets a compile error and has to add a `finalizing` branch; a caller testing only for `completed` or `failed` is unaffected.
+- **`finalizing` is new, and is NOT terminal.** It means the transaction paying the recipient is on chain and accruing the confirmations its chain requires — made, but not yet irreversible, much as a card authorization is not a settlement. It normally becomes `completed` and can still become `failed`. Nothing emits it yet; it is declared here so clients are ready before the gateway starts sending it.
+- **Breaking: one failure shape.** `PaymentError` and `TimelineError` are replaced by a single `PaymentFailure` used by all three responses, so a failure reads identically however you ask about the payment. On the timeline that is a real change of shape: `chain_id`, `tx_hash` and `revert_reason` were flat on the error and are now nested under `blockchain_context`, which also carries the four fields that endpoint previously discarded — the block number among them.
+- **Breaking: `tx_hash` is now `transaction_hash`**, on `error.blockchain_context` (all three responses) and on `steps[]` (timeline). This is the name the shared error shape and the rest of our published specs already used; the payment API was the outlier. **A caller reading `error.blockchain_context.tx_hash` gets `undefined` after upgrading** — there is no deprecation period because the field moved to the shared definition rather than being duplicated under both names.
+- `PaymentFailure` now carries `docs_url` and `retry_classification`. Both were already computed for every error code but only ever reached failed *requests*, never failed *payments*.
+- The `payment-outcome` CLI no longer maps `cancelled` to exit code 3 (terminal failure), because the gateway no longer reports it. A status this build does not recognise exits 2 (still pending), which is the safe direction: a script that waits one more round costs a poll, a script that gives up on a live payment can cost a second charge.
+- **New `transactions` object** (`deposit`, `fulfillment`) on all three responses, for looking a payment's on-chain transactions up yourself. Declared but not yet populated.
+
+### Security
+- The HTTP client is now axios 1.20.0. 1.13.2 had a run of advisories (prototype-pollution gadgets that could tamper with requests or responses, proxy-authorization leaks, NO_PROXY SSRF, ReDoS). A caller that pins axios independently should take 1.18.0 or newer. A timeout that fires after headers have arrived still surfaces as `GatewayTimeoutError`: axios 1.20 attaches the partial response, and the client drops it so a stalled error body is not reported as a completed HTTP status.
+
+## [3.0.1] - 2026-09-18
+
+### Changed
+- Published under Apache-2.0 with `publishConfig.access: public`. npm will not overwrite 3.0.0, so this version exists to ship the LICENSE, NOTICE, and public visibility that 3.0.0 cannot take.
+
 ## [3.0.0] - 2026-09-16
 
 > **Read this before upgrading if the gateway has been accepting your asset identifiers.**
@@ -44,6 +61,8 @@ corridor is refused rather than silently served.
 ### Added
 - **`ensureSourceApproval` and `needsSourceApproval`**, so the Permit2 prerequisite this package has always stated can now be satisfied from it. Paying from EVM or Tron needs a one-off approval of the source token for Permit2; without it a payment is built correctly, signed correctly, accepted by the gateway, and then reverts on-chain at settlement — the most expensive way to learn about a missing allowance. Until now the README and `send-payment --help` named the requirement and offered no way to meet it. `ensureSourceApproval` reads the current allowance and sends an approval only if it falls short; `needsSourceApproval` answers the same question read-only, spending no gas, so a payer can be warned before being asked to sign. Solana reports that no approval is needed rather than doing nothing, since its deposit authorizes the transfer itself. **This is the first part of this package that broadcasts a transaction and spends gas.** Everything else builds and signs offline, and that has not changed: you pass a connected ethers signer (or a TronWeb instance for Tron), so the package still never chooses an RPC endpoint or holds a key. An approval is unlimited by default, so later payments need no further transaction; `approvalAmount` bounds it instead, at the cost of having to renew it as Permit2 consumes it — pair a bound with `requiredAllowance` across repeated payments, or the bound stops covering itself as soon as the first charge is decremented from it. Waiting for the approval to confirm is bounded by `confirmation.timeoutMs` (one minute by default) rather than indefinite, and `onSubmitted` hands you the transaction hash the moment it is broadcast. Tokens that refuse to overwrite a non-zero allowance — mainnet USDT most notably — are reset to zero first, but only where the token actually demands it. An approval is refused outright when the signer you pass does not hold the `owner` account whose allowance was read: an approval only ever applies to the account that sends it, so a mismatched signer would approve that account, hand back a transaction hash that reads as success, and leave the owner exactly as unable to pay as before. The read-only `needsSourceApproval` is unaffected, since asking whether a payer is ready without holding their keys is a legitimate preflight. `isUnconfirmed` ships alongside them for telling a broadcast-but-unseen approval apart from one that failed: the wait for a confirmation is bounded, and reaching that bound is not a failure, so the two need opposite responses. `approve-permit2` reports an unconfirmed run as `{"unconfirmed": true, "txHash": ...}` on stdout rather than as a bare non-zero exit indistinguishable from a revert. These helpers raise an allowance and never lower one, so `--amount` below an allowance the wallet already holds leaves it alone and says so.
 - **`approve-permit2`**, a command that performs that approval. `approve-permit2 <sender> <sourceAsset> --rpc-url <url>` takes the same CAIP-19 asset string as `send-payment`, and `--check` reports whether an approval is needed without sending anything or needing a key. It is a separate command rather than a flag on `send-payment` because it is a different kind of act: it spends gas, once per wallet and token, and is worth doing deliberately and ahead of time rather than as a side effect of paying. The private key comes from `PRIVATE_KEY` or an interactive prompt and is never accepted as a flag, which would put it in shell history and in the process list. EVM and Tron; Tron additionally needs `tronweb`, an optional peer dependency, so that EVM-only installs do not carry it. The result JSON goes to stdout, like the other commands. The allowance is read before a key is ever requested, so an already-approved wallet — which is every wallet after the first run — never has to produce a secret to learn there was nothing to do, and the key is checked against `<sender>` before anything is sent, so a mismatched key cannot approve the wrong account and report success.
+- **Signing helpers for all three PaymentRequest signatures**, available from the `@atum-labs/payment-gateway-client/signing` subpath. A PaymentRequest carries three unrelated signatures and choosing the wrong one is the mistake this surface exists to prevent, so they are named for what they authorize rather than for how they are built. `signPaymentRequest` fills `sender_auth.signed_messages[]` and authorizes the **on-chain transfer**. `signDeclaration` attests that the **document** came from its signer, as a W3C Data Integrity proof over the URDNA2015-canonicalized request — it is exported under that name, rather than the upstream library's `signPaymentRequest`, precisely so the two cannot be confused. `buildEnvelope` and `buildEnvelopeForAccount` carry the **originator's identity** as a holder-signed PaymentRequestEnvelope. Signing one does not stand in for another: a request with a valid `sender_auth` and no envelope authorizes a transfer by an unidentified originator, and the reverse identifies an originator who has authorized nothing. Every one of them takes a **signer, never a private key** — a hex key would force raw key material into a JavaScript string that cannot be zeroized, is copied on assignment, and lands in heap snapshots and any log line that stringifies the surrounding object, and it would exclude every custodian whose key sits in a KMS or an HSM. `signerFromEthersWallet` covers a local key; a custodial signer implements `signDigest` over its own call. The signature contract is 65 bytes of `r || s || v` with **v ∈ {0, 1}**: a signature whose v is already 27 or 28 is refused, because applying the alignment twice recovers a *different* address, which is a well-formed signature that verifies as somebody else. Also exported: `computeRequestHash`, `verifyDeclaration` (which **throws** rather than returning a flag, and refuses a document whose signature recovers a signer other than the one it claims), `verifyPaymentRequest` for checking what a `sender_auth` signature actually commits to before submitting, `didForAccount`, `verificationMethodForAccount`, and their types. See `docs/signing.md`.
+- **`jsonld` is a new dependency**, and it is pinned exactly rather than floating. It runs URDNA2015, the canonicalization that determines exactly what a signature covers, so a minor release that changed its output would change what customers sign, on their machines, with nothing in our CI to notice.
 - **`send-payment --prepare-only` and `send-payment --submit <file>`** split the single-shot command in two. `--prepare-only` builds and signs a payment request, prints it to stdout, and stops without submitting; `--submit` sends one that was prepared earlier (`-` reads stdin, so the two pipe together). Together they turn the single-shot command into an inspect-then-approve flow: the printed document is byte-for-byte what that run would have POSTed, so it can be read and reviewed before any money moves. Treat it like a signed cheque: it is a signed authorization rather than a draft and `--submit` needs no key, so delete the file once the payment is sent or abandoned. Re-preparing under the same `request_id` targets the same payment and cannot pay twice, but does not reproduce the same bytes: the deadlines are stamped from the clock on each run and the signature covers them. Two things to know. `--prepare-only` still calls the gateway, which is where the corridor addresses come from, so it is not an offline signing mode. And the exit-code table describes a *submitted* payment, so it does not apply under `--prepare-only`, where `0` means the request was built and signed and no payment exists — do not chain a payment-conditional step off such a run. If you intend to submit later, widen the quote window with `--quote-deadline-seconds` — but by tens of seconds, not minutes. A prepared document is submittable only while its window is open (the default is 10 seconds), and that same window is the settler auction: the gateway waits it out before selecting, and settler quotes expire on their own, so an over-long window ends in a terminal `QUOTES_EXPIRED`. `--submit` signs nothing and needs no private key, takes no corridor arguments, refuses the options that only shape a request being built rather than ignoring them, and reports with the same exit codes and streams as an ordinary run; it supports `--wait` the same way. The two flags are mutually exclusive, and a short invocation now names both forms rather than reporting a missing argument.
 - The Permit2 approval prerequisite now appears at the top of `send-payment --help`, above the arguments and options, instead of in the last paragraph. It is the most common cause of a payment that is built and signed correctly and still fails to settle, and it was previously about a hundred lines below the usage line. The contract addresses stay at the end of the help, where the prerequisite points.
 - **`waitForTerminalStatus` and `isTerminalStatus` are exported**, so following a submitted payment to its end is one call rather than a hand-written loop. A submission usually comes back `pending`, so waiting is the ordinary path, and the previous answer — write your own poll — put the burden of getting it right on every caller. A failed status check does not end the wait: a blip while a payment is settling is the worst moment to stop looking, so failures are counted in `errorCount`, reported through `onError`, and polling continues to the budget. The outcome reports `timedOut` so a caller can tell "still in flight" from "finished", which a bare loop cannot. This is the same helper behind the `send-payment --wait` flag, so the command-line tools and the SDK now agree by construction. `isTerminalStatus` is the single definition of which states are final, so a caller no longer keeps its own copy of that list in step with the contract. `budgetMs` is optional and in milliseconds, defaulting to `DEFAULT_WAIT_BUDGET_MS` (one minute); the seconds-based constant behind the command line's `--wait-seconds` stays internal, so there is one unit on the public surface and no way to pass 60 where 60000 was meant. An optional `signal` ends the wait early for a caller that must stop on shutdown or when its request is cancelled, and the outcome reports `aborted` — which always implies `timedOut`, so an interrupted wait can never be read as a settled payment. Also exported: `DEFAULT_WAIT_BUDGET_MS`, `DEFAULT_POLL_INTERVAL_MS`, `StatusSnapshot`, `WaitOutcome`, `WaitParams`.

package/LICENSE

@@ -1,83 +1,202 @@
-# ATUM LABS, INC. – PAYMENT GATEWAY CLIENT PRIVATE REPOSITORY LICENSE AGREEMENT
-**Last Updated: January 28, 2026**
-
-This Private Repository License Agreement (“Agreement”) governs your (“Licensee”) access to the Atum Labs, Inc. (“Atum”) private GitHub repository containing Atum’s proprietary source code, SDK components, documentation, and implementation examples relating to the Atum Payment Gateway Client (“Payment Gateway Client Code”).
-By accessing or using the Repository, Licensee agrees to be bound by this Agreement.
-## 1. Purpose of Access
-Atum is granting limited access to the Payment Gateway Client Code solely for the following permitted purpose (the “Authorized Purpose”):
-- Integrating, installing, operating, and testing the Payment Gateway Client in connection with Licensee's use of the Atum settlement network, Goji-facing transaction flows, and any other Atum-authorized payment operations.
-- Conducting internal audits, security review, and compliance assessments necessary to support the above operations.
-
-No other use is permitted.
-## 2. License Grant
-Subject to Licensee’s full compliance with this Agreement, Atum grants Licensee a limited, revocable, non-exclusive, non-transferable, non-sublicensable license to:
-1. Access the private GitHub repository containing the Payment Gateway Client Code (“Repository”);
-2. Download and internally use the Payment Gateway Client Code solely for the Authorized Purpose;
-3. Deploy and run compiled or interpreted versions of the Payment Gateway Client Code only within Licensee’s secure infrastructure and only for the Authorized Purpose;
-4. Create internal configuration changes or implementation wrappers necessary for integration, provided that all such modifications remain Atum Confidential Information and are disclosed to Atum upon request.
-
-No other rights are granted.
-## 3. Restrictions
-Licensee must not, and must not permit any third party to:
-1. Use the Payment Gateway Client Code for any purpose outside the Authorized Purpose;
-2. Make the Repository or any portion of the Payment Gateway Client Code available to any third party, including affiliates, without Atum’s written consent;
-3. Publicly disclose, publish, or commit any portion of the Payment Gateway Client Code to any public forum or repository;
-4. Use the Payment Gateway Client Code to build or support any competing products or networks;
-5. Reverse engineer, decompile, or otherwise attempt to derive the underlying trade secrets in the Payment Gateway Client Code (except to the limited extent permitted by applicable law);
-6. Remove or alter any proprietary notices;
-7. Use Atum’s code, data, or architecture to train or fine-tune any AI, LLM, or ML models;
-8. Use the Payment Gateway Client Code in violation of applicable law or Atum instructions.
-## 4. Ownership
-Atum retains all rights, title, and interest in and to:
-- the Payment Gateway Client Code,
-- the Repository contents,
-- the underlying architecture, algorithms, settlement workflows, and SDK components, and
-- all modifications, derivative works, feedback, or improvements.
-No ownership rights are transferred to Licensee.
-## 5. Confidentiality
-The Payment Gateway Client Code and all related documentation constitute Atum Confidential Information. Licensee must:
-1. Protect the code using industry-standard security practices;
-2. Disclose it only to employees or contractors with a legitimate need to know and who are bound by written confidentiality obligations at least as protective as this Agreement;
-3. Use it only for the Authorized Purpose;
-4. Not disclose it to any third party without Atum’s written consent;
-5. Upon termination, immediately cease use, destroy all copies (including cached or compiled forms), and certify destruction to Atum.
-
-## 6. Compliance and Security Requirements
-Licensee must comply with:
-- Atum’s security and technical standards for Payment Gateway integrations,
-- Atum’s operational procedures for network participants,
-- Key rotation, signing authority, and release-only settlement authority rules, and
-- Any written security or technical notices issued by Atum.
-
-Atum may audit Licensee’s technical implementation upon reasonable notice.
-## 7. No Warranty
-The Payment Gateway Client Code is provided “AS IS”, without any express or implied warranties. Atum does not warrant that the code will be error-free or suitable for any particular purpose.
-## 8. Limitation of Liability
-To the fullest extent permitted by law:
-- Atum will not be liable for any indirect, incidental, special, or consequential damages;
-- Atum’s total cumulative liability under this Agreement will not exceed $100.
-## 9. Term and Termination
-This Agreement is effective upon Licensee’s first access to the Repository and continues until:
-1. Terminated by either party with 10 days’ written notice;
-2. Automatically terminated if Licensee ceases to be an authorized Credit Coop participant on Atum’s network; or
-3. Automatically terminated upon any breach of Sections 2–6.
-Upon termination:
-- All rights granted hereunder immediately cease;
-- Licensee must stop using the Payment Gateway Client Code;
-- Licensee must destroy all copies and derivatives and certify destruction upon request.
-The following provisions survive termination:
-- Confidentiality (Section 5)
-- Security & Compliance Obligations (Section 6)
-- Ownership (Section 4)
-- Restrictions (Section 3)
-- No Warranty (Section 7)
-- Limitation of Liability (Section 8)
-- Governing Law (Section 10)
-- Any provisions intended by their nature to survive
-## 10. Governing Law
-Delaware law governs this Agreement.
-## 11. Entire Agreement
-This Agreement constitutes the entire agreement between the parties relating to the Payment Gateway Client Code and supersedes all prior or contemporaneous agreements specific to such access.
-
-ATUM LABS, INC.
-All rights reserved.
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,2 @@
+Atum Protocol
+Copyright 2026 Atum Labs, Inc.

package/README.md

@@ -3,9 +3,10 @@
 TypeScript client for Atum Payment Gateway API with CLI support.
 Full documentation: [docs.atum.xyz](https://docs.atum.xyz).
 
-> **Proprietary software - not open source.**
+> Copyright 2026 Atum Labs, Inc.
 >
-> Copyright (c) 2026 Atum Labs, Inc. All rights reserved. Access to and use of `@atumlabs/payment-gateway-client` are limited to entities expressly authorized by Atum and are governed by the Atum Payment Gateway Client Private Repository License Agreement in the LICENSE file included with this package. Do not redistribute, publish, mirror, sublicense, or provide this package to any unauthorized person. By accessing, installing, copying, or using the package, you agree to the license terms.
+> Licensed under the Apache License, Version 2.0. See the `LICENSE` file
+> distributed with this package.
 
 > NOTE: Before your first payment from an EVM or Tron chain, the source token must be approved
 > for the Permit2 contract. Without it a payment is built, signed and accepted by the gateway,
@@ -15,8 +16,7 @@ Full documentation: [docs.atum.xyz](https://docs.atum.xyz).
 
 ## Installation
 
-`@atumlabs/payment-gateway-client` is a private npm package. Once your npm account
-has been granted access, install it with npm.
+`@atumlabs/payment-gateway-client` is on the public npm registry.
 
 To use the SDK in a project:
 
@@ -98,7 +98,7 @@ runs the next step only for a settled payment:
 | ---- | --------------------------------------------------------------------------- |
 | `0`  | `completed` — settled                                                       |
 | `2`  | `pending` — accepted, no result yet                                          |
-| `3`  | `failed` / `cancelled` — terminal; a fresh attempt needs a new `--request-id` |
+| `3`  | `failed` — terminal; a fresh attempt needs a new `--request-id`              |
 | `1`  | no outcome obtained (rejected, gateway unreachable, bad arguments)            |
 
 On `2`, follow the payment with **`payment-status <payment_id>`** — the id is in the
@@ -417,7 +417,6 @@ async function sendPayment() {
         console.log('Destination TX:', response.fulfillment_confirmation?.destination_tx_hash);
         break;
       case 'failed':
-      case 'cancelled':
         // Terminal, and this request_id stays bound to it. A fresh attempt needs a NEW id.
         console.error('Failed:', response.error?.code, response.error?.message);
         break;
@@ -453,11 +452,11 @@ it is what you need to find the payment again.
 | Status | Meaning |
 | --- | --- |
 | `pending` | Accepted, not yet settled |
+| `finalizing` | Paid on chain, collecting confirmations. Not final |
 | `completed` | Delivered |
 | `failed` | Did not settle |
-| `cancelled` | Cancelled before completion |
 
-`completed`, `failed` and `cancelled` are final. A payment that reaches one of them keeps
+`completed` and `failed` are final. A payment that reaches one of them keeps
 its `request_id` for good, so re-submitting that id returns the same finished payment
 rather than trying again — a genuine new attempt needs a **new** `request_id`. Any status
 this client does not recognise is treated as still in flight. `isTerminalStatus` is exported
@@ -481,7 +480,7 @@ if (snapshot.error) {
   console.error(
     snapshot.error.code,
     snapshot.error.message,
-    snapshot.error.blockchain_context?.tx_hash ?? '',
+    snapshot.error.blockchain_context?.transaction_hash ?? '',
   );
 }
 ```
@@ -578,18 +577,24 @@ investigate a payment that did not settle:
 const timeline = await client.payments.getPaymentTimeline({ paymentId });
 
 for (const step of timeline.steps) {
-  console.log(step.status, step.label, step.tx_hash ?? '');
+  console.log(step.status, step.label, step.transaction_hash ?? '');
 }
 
 if (timeline.error) {
   // Why it failed, and where: for an on-chain failure this carries the chain id, the
   // transaction hash and the revert reason.
-  console.error(timeline.error.code, timeline.error.message, timeline.error.revert_reason ?? '');
+  console.error(
+    timeline.error.code,
+    timeline.error.message,
+    timeline.error.blockchain_context?.revert_reason ?? '',
+  );
 }
 ```
 
-The timeline reports `settling` while on-chain steps are running, for a payment that
-`getPaymentStatus` still reports as `pending`.
+A payment reads the same on every endpoint: `getPayment`, `getPaymentStatus` and
+`getPaymentTimeline` all report the one `PaymentStatus`. `finalizing` means the
+transaction paying your recipient is on chain and accruing confirmations — it is not
+final, and it is not a reason to treat the payment as delivered.
 
 ### Solana signing
 
@@ -847,9 +852,21 @@ See [docs/idempotency.md](docs/idempotency.md) for the full model: the two
 guarantees and which endpoints each covers, when the `409` applies, how to read
 the outcome, and the per-chain differences (EVM/Tron vs Solana).
 
+## Signing
+
+A PaymentRequest carries three unrelated signatures: `signPaymentRequest` authorizes the
+on-chain transfer, `signDeclaration` attests the document, and an identity envelope carries the
+originator. None substitutes for another.
+
+Both signing surfaces take a **signer**, never a private key, so a key held in a KMS, an HSM or
+a custodial provider works without leaving its boundary; `signerFromEthersWallet` covers a local
+key. See [docs/signing.md](docs/signing.md) for which signature to use when, what the proof does
+and does not cover, and the two details a custodial signer must get right.
+
 ## What is in the package
 
 - `dist/` — compiled JavaScript and TypeScript declarations, ready to use
 - `dist/cli/` — the five command-line tools
 - `docs/` — reference documentation, including [idempotency and retries](docs/idempotency.md)
+  and [signing](docs/signing.md)
 - `LICENSE`, `THIRD-PARTY-NOTICES.txt` — license terms and third-party attribution

package/THIRD-PARTY-NOTICES.txt

@@ -2,12 +2,11 @@ THIRD-PARTY SOFTWARE NOTICES AND INFORMATION
 ==============================================================================
 @atumlabs/payment-gateway-client
 
-@atumlabs/payment-gateway-client is proprietary software, governed by the license
-agreement in the package-root LICENSE file. THIS file is not that license. This
+@atumlabs/payment-gateway-client is licensed under the Apache License, Version 2.0, as stated
+in the package-root LICENSE file. THIS file is not that license. This
 package includes the third-party software identified below; the licenses and
 notices reproduced here apply only to those third-party components. They do not
-modify the proprietary license governing this package or any Atum-authored code,
-and they do not make it open source.
+modify the Apache-2.0 license governing this package or any Atum-authored code.
 
 The published artifact of this package (the compiled code under dist/) statically
 bundles the third-party open-source components listed below; their source is
@@ -15,7 +14,7 @@ redistributed within this package, so their license and copyright notices are
 reproduced here. Components and versions were taken from the exact modules the
 build inlined. This file does NOT cover packages the consumer installs separately
 as dependencies of this package (for example @solana/web3.js, axios, ethers, bs58,
-commander, dotenv, tweetnacl, and zod) — those ship under their own licenses and are not
+commander, dotenv, jsonld, tweetnacl, and zod) — those ship under their own licenses and are not
 redistributed here.
 
 LICENSE SUMMARY (1 component)