@pegaroute/sdk 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simply Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,210 @@
-# Temporary Holding Version
+# @pegaroute/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+TypeScript SDK for the Pegaroute cross-chain swap API.
+
+## Install
+
+```sh
+npm install @pegaroute/sdk
+```
+
+Requires Node.js 22.12+ (or Bun / Deno). The package is ESM only: use `import`, or `require()` from CommonJS, which
+Node supports from 22.12. Where `require()` of ESM isn't available, CommonJS code can load it with
+`const { Pegaroute } = await import("@pegaroute/sdk");`.
+
+The client holds your API key, so **only use it on your backend**, never in browser code. Your frontend talks to your
+backend, and has the user's wallet sign each swap with your wallet library of choice (e.g. viem). The SDK doesn't sign:
+it returns what to sign, and the browser-safe `@pegaroute/sdk/types` (types and type guards, no client) helps your
+frontend read it.
+
+## Quote and swap (backend)
+
+```ts
+import { type CreateSwapParams, hasQuoteRouteFees, Pegaroute } from "@pegaroute/sdk";
+
+const pr = new Pegaroute({ apiKey: process.env.PEGAROUTE_API_KEY!, baseUrl: process.env.PEGAROUTE_BASE_URL! });
+
+const params = {
+  fromChain: "ETH",
+  fromToken: "ETH",
+  toChain: "BTC",
+  toToken: "BTC",
+  amount: "0.05",
+  senderAddress: "0xabc…",
+  destinationAddress: "bc1q…",
+} satisfies CreateSwapParams;
+
+// Routes are best first. No routes means no provider can quote the pair: see `quote.warnings`.
+const quote = await pr.quotes.get(params);
+const best = quote.routes[0];
+
+if (best) {
+  // Show the user what the route costs. `{}` means no fee data, not a zero fee.
+  if (hasQuoteRouteFees(best.fees)) showCost(`$${best.fees.totalUsd} (${best.fees.totalBps} bps)`);
+
+  // Some routes add a fee in the source chain's native coin, which the wallet pays on top of `amount`.
+  if (best.additionalFee) showExtraFee(`${best.additionalFee.amount} ${best.additionalFee.token}`);
+
+  const swap = await pr.swaps.create({ ...params, quoteId: quote.quoteId, routeProvider: best.provider });
+
+  // Send `swap.transactionId` and `swap.execution` to the frontend for signing.
+}
+```
+
+`fees.totalUsd` is never negative. If the output is worth more than the input at reference prices, every fee is `0`,
+so two routes showing `0` can still pay out different amounts: compare routes by `expectedOutput`. Only
+`fees.breakdown.route` can be negative, when the provider's rate beats the reference price.
+
+## Sign (frontend, EVM with viem)
+
+`swap.execution` says what the user's wallet must sign. For an EVM router call (e.g. THORChain):
+
+```ts
+import { isExecutionFamily, isExecutionMode, type SwapExecution } from "@pegaroute/sdk/types";
+import { type Address, createWalletClient, custom, type Hex } from "viem";
+
+async function signSwap(execution: SwapExecution) {
+  if (!isExecutionFamily(execution, "evm") || !isExecutionMode(execution, "contract-call")) {
+    throw new Error("Not handled here");
+  }
+
+  const wallet = createWalletClient({ transport: custom(window.ethereum!) });
+  const [account] = await wallet.requestAddresses();
+
+  // If `execution.approval` is set, send the ERC-20 approve first (see examples/frontend/evm.ts).
+  const txHash = await wallet.sendTransaction({
+    account: account!,
+    chain: null,
+    to: execution.to as Address,
+    data: (execution.data ?? "0x") as Hex,
+    value: BigInt(execution.value?.baseUnits ?? 0),
+  });
+
+  // POST txHash to your backend.
+}
+```
+
+## Other execution families and modes
+
+EVM `contract-call` is one of several. `execution` is a union: switch on `family`, then `mode`, never on the provider.
+
+```ts
+switch (execution.family) {
+  case "evm":    // execution.mode: "contract-call" | "native-transfer" | "erc20-transfer"
+  case "utxo":   // "payment-with-memo" | "serialized-tx" (PSBT)
+  case "cosmos": // "bank-send" | "msg-deposit" | "msg-execute"
+  // … "solana", "sui", "xrp", "stellar", "tron", "near", "hypercore", "cardano", "other"
+}
+
+// Or handle one mode across every family, e.g. a single "send to this deposit address" screen:
+if (isExecutionMode(execution, "deposit-transfer")) showDeposit(execution.to, execution.amount, execution.memo);
+```
+
+The guards `isExecutionFamily(execution, family)` and `isExecutionMode(execution, mode)` narrow `execution` to the
+matching types. Each type documents what to sign.
+
+## Report the tx hash and track status (backend)
+
+```ts
+await pr.swaps.submitTxHash(swap.transactionId, { txHash });
+
+// Poll until the swap finishes (default: every 10 s, for up to 1 hour). Or use webhooks.
+const final = await pr.swaps.waitForCompletion(swap.transactionId);
+if (final.status === "fail") console.log(final.error?.userMessage, final.refund);
+```
+
+## Webhooks
+
+**Registering webhooks:** done once in the Pegaroute UI. Set your endpoint URL on the integration and copy its
+`whsec_…` secret (shown only when created or rotated).
+
+```ts
+import { verifyWebhook, WebhookVerificationError } from "@pegaroute/sdk";
+
+// Verify the raw body: parsing and re-serialising it breaks the signature.
+const event = await verifyWebhook({
+  rawBody,
+  signature: request.headers.get("x-pegasus-signature"),
+  secret: process.env.PEGAROUTE_WEBHOOK_SECRET!,
+});
+
+if (event.event === "transaction.completed") {
+  // `event.data` is fully typed.
+}
+```
+
+`verifyWebhook` throws `WebhookVerificationError` for a missing or wrong signature: respond 401. Delivery is
+at-least-once, so handle events idempotently. A delivery can be replayed, so confirm with `swaps.get` before acting on
+funds.
+
+## Errors
+
+Every API error is a `PegarouteError`, with a subclass per status (`NotFoundError`, `RateLimitError`, …).
+
+```ts
+import { PegarouteError, ProviderChangedError } from "@pegaroute/sdk";
+
+try {
+  await pr.swaps.create({ ...params, quoteId: quote.quoteId, routeProvider: best.provider });
+} catch (error) {
+  if (error instanceof ProviderChangedError) {
+    // The quoted route is gone: show `error.newQuote` to the user, then create the swap with it.
+  } else if (error instanceof PegarouteError) {
+    console.log(error.code, error.status, error.userMessage); // `userMessage` is safe to show users
+  } else {
+    throw error;
+  }
+}
+```
+
+GET requests are retried on connection errors and on errors whose `retryable` is `true` (`maxRetries`, default 2).
+`retryable` is Pegaroute's own flag, or, when the response doesn't carry one (e.g. a proxy's error page), `true` for
+429, 502, 503 and 504. POSTs are never retried.
+
+## Statuses
+
+Pegaroute has two status sets. Use `status` (external) for business logic; `internalStatus` is for debugging.
+
+| internal | external |
+|---|---|
+| pending | pending |
+| submitted, executing, confirming | executing |
+| completed | success |
+| failed, refunded | fail |
+
+| Call | Returns |
+|---|---|
+| `swaps.get`, `transactions.list`, webhooks | `status` (external) + `internalStatus` |
+| `swaps.create` | `status` (external) |
+| `swaps.submitTxHash` | internal (`"submitted"`) |
+| `swaps.events` | internal (audit log) |
+| `transactions.list({ status })` filter | takes internal values |
+
+`toExternalStatus(internal)` and `isTerminalStatus(status)` are exported from both entry points.
+
+## Examples
+
+[`examples/`](examples) has a minimal backend ([Hono](https://hono.dev)) and the full EVM signing example, including
+the ERC-20 approval.
+
+## Development
+
+```sh
+bun install
+bun test                    # unit tests
+bun run test:node           # built package on real Node (needs Node ≥22.12, see .node-version)
+bun run typecheck && bun run lint && bun run build
+bun run check:package       # builds (prepack command), then checks package exports and types
+```
+
+CI runs all of the above, plus `typecheck:examples`, on every pull request. These are the checks contributors run.
+
+End-to-end tests are for maintainers only: they need a local Pegaroute, started from the private Pegaroute repo
+(`docker compose up -d --build`), and an operator login. Copy [`.env.example`](.env.example) to `.env` and fill it in;
+it explains what each variable needs.
+
+```sh
+bun run test:e2e            # REST endpoints and webhooks
+bun run test:e2e:examples   # backend example + EVM signing (nothing is broadcast)
+bun run typecheck:examples  # examples against the built SDK
+```