@chainrails/sdk 0.1.0 → 0.2.1

package/README.md

@@ -8,10 +8,69 @@ A TypeScript SDK for interacting with the Chainrails API - enabling seamless cro
 - 🌉 **Bridge Routing** - Find optimal routes and pricing across multiple bridge protocols
 - 💰 **Quote Management** - Get real-time quotes from various bridge providers
 - 📋 **Intent Management** - Create and manage cross-chain transfer intents
+- 🔐 **Session Authentication** - Secure session-based auth for modal payment flows (NEW in v0.1.0)
 - ⛓️ **Chain Support** - Support for 11+ blockchain networks including Ethereum, Arbitrum, Base, Starknet, and more
 - 🔐 **Secure** - API key-based authentication with automatic header injection
 - 📦 **Tree-shakeable** - Built with ES modules for optimal bundle sizes
 
+## What's New in v0.1.0 (January 2026)
+
+### New: Session Token Authentication Module
+
+The `Auth` module provides secure session-based authentication for modal payment flows:
+
+```typescript
+const session = await crapi.auth.getSessionToken({
+  recipient: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
+  destinationChain: "ARBITRUM_MAINNET",
+  token: "USDC",
+  amount: "100"
+})
+
+// Returns: { sessionToken, sessionId, expiresAt }
+```
+
+**Use Cases:**
+- Iframe-based payment modal initialization
+- Client-side session management with automatic expiration
+- Secure token propagation to frontend applications
+
+### Enhanced Intent APIs
+
+New session-aware methods for managing intents within modal context:
+
+```typescript
+// Create intent for session (simplified parameters)
+const intent = await crapi.intents.createForSession({
+  /* minimal parameters */
+})
+
+// Get intents associated with a session
+const sessionIntents = await crapi.intents.getForSession("0x...")
+
+// Get intent by contract address
+const intent = await crapi.intents.getForAddress("0x...")
+
+// Trigger processing within session context
+const result = await crapi.intents.triggerProcessingForSession("0x...")
+```
+
+### Session-Based Quote Queries
+
+Retrieve quotes within a payment session context:
+
+```typescript
+const quotes = await crapi.quotes.getAllForSession({
+  // session-specific parameters
+})
+```
+
+### Breaking Changes
+
+- **Intent Creation**: Use `createForSession()` for modal flows instead of `create()`
+- **Response Types**: Quote responses now have enhanced types for session context
+- **Authentication**: Session token required for iframe communication
+
 ## Installation
 
 ```bash
@@ -65,6 +124,45 @@ Supported chains include:
 
 ## API Reference
 
+### Auth Module (New in v0.1.0)
+
+Manage session-based authentication for modal payment flows.
+
+#### Get Session Token
+
+Creates a secure session token for iframe-based payment modal initialization.
+
+```typescript
+const session = await crapi.auth.getSessionToken({
+  recipient: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
+  destinationChain: "ARBITRUM_MAINNET",
+  token: "USDC",
+  amount: "100"
+})
+```
+
+**Parameters:**
+- `recipient` (required): Recipient wallet address on destination chain
+- `destinationChain` (required): Destination blockchain network
+- `token` (required): Token symbol (e.g., "USDC", "ETH")
+- `amount` (required): Transfer amount (string or number)
+
+**Response:**
+```typescript
+interface getSessionTokenOutput {
+  sessionToken: string    // JWT token for iframe communication
+  sessionId: string       // Unique session identifier
+  expiresAt: string      // ISO 8601 expiration timestamp
+}
+```
+
+**Use Cases:**
+- Initialize payment modal with secure authentication
+- Manage session lifecycle with automatic expiration
+- Propagate credentials to iframe securely via postMessage
+
+---
+
 ### Intents Module
 
 Manage cross-chain transfer intents.
@@ -183,6 +281,48 @@ const updated = await crapi.intents.update("123", {
 
 **Status values:** `"PENDING"`, `"FUNDED"`, `"INITIATED"`, `"COMPLETED"`, `"EXPIRED"`
 
+#### Create Intent for Session (New in v0.1.0)
+
+Creates an intent specifically for modal-based payment flows with simplified parameters.
+
+```typescript
+const intent = await crapi.intents.createForSession({
+  // Simplified parameters for session context
+  // See API documentation for complete parameter list
+})
+```
+
+**Use Case:** Use this method when creating intents within a modal payment session context instead of `create()`.
+
+#### Get Intents for Session (New in v0.1.0)
+
+Retrieves all intents associated with a specific session.
+
+```typescript
+const sessionIntents = await crapi.intents.getForSession("0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb")
+```
+
+**Parameters:**
+- `address` (required): Session address identifier
+
+#### Trigger Processing for Session (New in v0.1.0)
+
+Triggers payment processing for an intent within a modal session context.
+
+```typescript
+const result = await crapi.intents.triggerProcessingForSession("0x4E60e01263E750eD9D087157e19D2480Fd86A900")
+```
+
+**Parameters:**
+- `intentAddress` (required): Contract address of the intent
+
+**Response:**
+```typescript
+interface triggerProcessingOutput {
+  // Processing status and receipt information
+}
+```
+
 ---
 
 ### Router Module
@@ -335,6 +475,18 @@ const multiSourceQuotes = await crapi.quotes.getAll({
 - `tokenOut` (required): Output token address
 - `recipient` (optional): Recipient address
 
+#### Get Quotes for Session (New in v0.1.0)
+
+Retrieves all available bridge quotes within a payment session context.
+
+```typescript
+const sessionQuotes = await crapi.quotes.getAllForSession({
+  // session-specific parameters
+})
+```
+
+**Use Case:** Use this method to get quotes when operating within a modal session context. Returns quotes in the same format as `getBestAcrossBridges()` for consistency.
+
 ---
 
 ### Chains Module