@paxoslabs/amplify-sdk 1.0.0 → 1.0.2

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, PaxosLabs
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,145 @@
+<div align="center">
+
+# Paxos Labs Amplify SDK
+
+**Official TypeScript SDK for the Paxos Labs Amplify API** — vault discovery, deposits, withdrawals, and user positions.
+
+[![npm version](https://img.shields.io/npm/v/@paxoslabs/amplify-sdk.svg?color=2ea043&label=npm)](https://www.npmjs.com/package/@paxoslabs/amplify-sdk)
+[![npm downloads](https://img.shields.io/npm/dm/@paxoslabs/amplify-sdk.svg?color=2ea043)](https://www.npmjs.com/package/@paxoslabs/amplify-sdk)
+[![types](https://img.shields.io/npm/types/@paxoslabs/amplify-sdk.svg?color=3178c6)](https://www.typescriptlang.org)
+[![license](https://img.shields.io/npm/l/@paxoslabs/amplify-sdk.svg?color=blue)](./LICENSE)
+
+[Documentation](https://developers.paxoslabs.com) · [API Reference](https://developers.paxoslabs.com) · [Changelog](./CHANGELOG.md)
+
+</div>
+
+---
+
+Generated from the Amplify OpenAPI specification, so every method, type, and error is fully typed and stays in lockstep with the API.
+
+## Table of contents
+
+- [Installation](#installation)
+- [Quickstart](#quickstart)
+- [Configuration](#configuration)
+- [Resources](#resources)
+- [Error handling](#error-handling)
+- [Types](#types)
+- [License](#license)
+
+## Installation
+
+```bash
+npm install @paxoslabs/amplify-sdk
+# pnpm add @paxoslabs/amplify-sdk
+# yarn add @paxoslabs/amplify-sdk
+# bun add @paxoslabs/amplify-sdk
+```
+
+> Requires Node.js **>= 24**.
+
+## Quickstart
+
+```ts
+import { AmplifyClient } from '@paxoslabs/amplify-sdk'
+
+const client = new AmplifyClient({ apiKey: process.env.PAXOS_LABS_API_KEY! })
+
+const { vaults } = await client.amplify.vaults.list({ filter: 'chainId=1' })
+```
+
+The API key is sent as the `x-api-key` header and authenticates every request.
+
+> [!IMPORTANT]
+> **Keep your API key server-side.** It must never ship to the browser. Call the SDK from a backend (Route Handler, Server Action, or API server), return the prepared transaction payload, and sign it client-side with the user's wallet.
+
+## Configuration
+
+```ts
+interface AmplifyClientOptions {
+  /** API key (required). Sent as the `x-api-key` header on every request. */
+  apiKey: string
+  /** Environment override. Defaults to production. */
+  environment?: string
+  /** Base URL override. Takes precedence over `environment`. */
+  baseUrl?: string
+}
+```
+
+The client targets the production API by default; pass `environment` or `baseUrl` only for non-production use.
+
+## Resources
+
+Each API area is exposed as a subclient on the `AmplifyClient` instance.
+
+| Accessor | Purpose |
+| :--- | :--- |
+| `client.amplify.vaults` | List vaults and assets; fetch APYs, TVLs, compositions, supply caps, and liquidity shortfalls |
+| `client.amplify.deposit` | Prepare deposit transactions |
+| `client.amplify.smartDeposits` | Create a smart deposit address for a user |
+| `client.amplify.withdraw` | Prepare (`prepare`) and cancel (`cancel`) withdrawals; calculate fees (`calculateFee`); list requests (`listRequests`) and volumes (`getVolumes`) |
+| `client.amplify.users` | Fetch user positions |
+| `client.core.authorization` | Detect (`detect`) token authorization requirements (permit, approval, or already approved) |
+
+### Example: prepare a deposit
+
+```ts
+const prepared = await client.amplify.deposit.prepare({
+  vaultAddress,
+  depositAsset,
+  depositAmount,
+  userAddress,
+  chainId,
+})
+
+// prepared.transaction → { to, data, value }
+// Sign and broadcast it with the user's wallet (viem / wagmi / Privy / Dynamic).
+```
+
+### Example: create a smart deposit address
+
+```ts
+const { smartDepositAddress } = await client.amplify.smartDeposits.getAddress({
+  userDestinationAddress,
+  vaultAddress,
+  inputToken,
+  chainId,
+})
+```
+
+## Error handling
+
+Requests reject with `AmplifyError` (carrying `statusCode` and `message`); requests that exceed the timeout reject with `AmplifyTimeoutError`.
+
+```ts
+import { AmplifyError } from '@paxoslabs/amplify-sdk'
+
+try {
+  await client.amplify.deposit.prepare(request)
+} catch (err) {
+  if (err instanceof AmplifyError) {
+    console.error(err.statusCode, err.message)
+  }
+  throw err
+}
+```
+
+## Types
+
+Generated types are available under the `Amplify` namespace:
+
+```ts
+import { Amplify } from '@paxoslabs/amplify-sdk'
+
+// Response types are at the top level
+type DepositResponse = Amplify.PrepareDepositResponseDto
+type AuthResponse = Amplify.AuthorizationResponseDto
+
+// Request types are nested under resource namespaces
+type DepositRequest = Amplify.amplify.deposit.PrepareDepositRequest
+type AuthRequest = Amplify.core.authorization.DetectAuthorizationRequest
+```
+
+## License
+
+[BSD-3-Clause](./LICENSE) © Paxos Labs