@sardis/sdk 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2025-01-27
+
+### Added
+
+- Full TypeScript SDK for Sardis stablecoin execution layer
+- `SardisClient` class with comprehensive API coverage
+- Payment execution with mandate support (AP2 bundles)
+- Pre-authorization holds (create, capture, void, extend)
+- Webhook management for real-time events
+- Agent-to-Agent (A2A) marketplace integration
+- Transaction gas estimation and status tracking
+- Ledger queries and entry verification
+- Agent management with spending policies
+- Wallet management with MPC provider support
+- Framework integrations:
+  - LangChain.js toolkit
+  - Vercel AI SDK tools
+  - OpenAI function calling
+
+### Features
+
+- ESM, CommonJS, and browser bundle support
+- Full TypeScript type definitions
+- Typed error classes for precise error handling
+- Retry logic with exponential backoff
+- Request/response logging support
+- Multi-chain support (Base, Polygon, Ethereum, Arbitrum, Optimism)
+- Multi-token support (USDC, USDT, PYUSD, EURC)
+
+## [0.1.0] - 2025-01-15
+
+### Added
+
+- Initial release
+- Basic client implementation
+- Payment execution support
+- Wallet management
+
+[0.2.0]: https://github.com/sardis-network/sardis-sdk-js/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/sardis-network/sardis-sdk-js/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sardis
+
+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

@@ -0,0 +1,439 @@
+# Sardis TypeScript SDK
+
+[![npm version](https://img.shields.io/npm/v/@sardis/sdk.svg)](https://www.npmjs.com/package/@sardis/sdk)
+[![npm downloads](https://img.shields.io/npm/dm/@sardis/sdk.svg)](https://www.npmjs.com/package/@sardis/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+
+The official TypeScript SDK for the Sardis stablecoin execution layer. Enables AI agents to execute programmable payments using stablecoins across multiple chains.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Features](#features)
+- [Error Handling](#error-handling)
+- [Configuration](#configuration)
+- [Agents](#agents)
+- [Wallets](#wallets)
+- [Supported Chains](#supported-chains)
+- [Supported Tokens](#supported-tokens)
+- [TypeScript Support](#typescript-support)
+- [Framework Integrations](#framework-integrations)
+- [Browser Usage](#browser-usage)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Installation
+
+```bash
+npm install @sardis/sdk
+# or
+yarn add @sardis/sdk
+# or
+pnpm add @sardis/sdk
+```
+
+## Quick Start
+
+```typescript
+import { SardisClient } from '@sardis/sdk';
+
+const client = new SardisClient({
+  apiKey: 'your-api-key',
+});
+
+// Check API health
+const health = await client.health();
+console.log(`API Status: ${health.status}`);
+
+// Execute a payment mandate
+const result = await client.payments.executeMandate({
+  mandate_id: 'mandate_123',
+  subject: 'wallet_abc',
+  destination: '0x...',
+  amount_minor: 10000000, // $10.00 USDC (6 decimals)
+  token: 'USDC',
+  chain: 'base',
+});
+console.log(`Payment executed: ${result.tx_hash}`);
+```
+
+## Features
+
+### Payments
+
+Execute single mandates or full AP2 payment bundles:
+
+```typescript
+// Execute AP2 bundle (Intent → Cart → Payment)
+const result = await client.payments.executeAP2(
+  intentMandate,
+  cartMandate,
+  paymentMandate
+);
+```
+
+### Holds (Pre-Authorization)
+
+Create, capture, and void pre-authorization holds:
+
+```typescript
+// Create a hold
+const hold = await client.holds.create({
+  wallet_id: 'wallet_123',
+  amount: '100.00',
+  token: 'USDC',
+  merchant_id: 'merchant_456',
+  duration_hours: 24,
+});
+
+// Capture the hold (complete payment)
+const captured = await client.holds.capture(hold.hold_id, '95.00');
+
+// Or void the hold (cancel)
+await client.holds.void(hold.hold_id);
+```
+
+### Webhooks
+
+Manage webhook subscriptions for real-time events:
+
+```typescript
+// Create a webhook subscription
+const webhook = await client.webhooks.create({
+  url: 'https://your-server.com/webhooks',
+  events: ['payment.completed', 'hold.captured'],
+});
+
+// List deliveries
+const deliveries = await client.webhooks.listDeliveries(webhook.id);
+```
+
+### Marketplace (A2A)
+
+Discover and interact with agent-to-agent services:
+
+```typescript
+// List available services
+const services = await client.marketplace.listServices({
+  category: 'ai',
+});
+
+// Create an offer
+const offer = await client.marketplace.createOffer({
+  service_id: 'service_123',
+  consumer_agent_id: 'agent_456',
+  total_amount: '50.00',
+});
+
+// Accept an offer (as provider)
+await client.marketplace.acceptOffer(offer.id);
+```
+
+### Transactions
+
+Get gas estimates and transaction status:
+
+```typescript
+// Estimate gas
+const estimate = await client.transactions.estimateGas({
+  chain: 'base',
+  to_address: '0x...',
+  amount: '100.00',
+  token: 'USDC',
+});
+console.log(`Estimated cost: ${estimate.estimated_cost_wei} wei`);
+
+// Check transaction status
+const status = await client.transactions.getStatus('0x...', 'base');
+```
+
+### Ledger
+
+Query the append-only ledger:
+
+```typescript
+// List ledger entries
+const entries = await client.ledger.listEntries({ wallet_id: 'wallet_123' });
+
+// Verify an entry
+const verification = await client.ledger.verifyEntry('tx_123');
+```
+
+## Error Handling
+
+The SDK provides typed exceptions for common error cases:
+
+```typescript
+import {
+  SardisError,
+  APIError,
+  AuthenticationError,
+  RateLimitError,
+  InsufficientBalanceError,
+} from '@sardis/sdk';
+
+try {
+  const result = await client.payments.executeMandate(mandate);
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error('Invalid API key');
+  } else if (error instanceof RateLimitError) {
+    console.error(`Rate limited, retry after ${error.retryAfter} seconds`);
+  } else if (error instanceof InsufficientBalanceError) {
+    console.error(`Need ${error.required} ${error.currency}, have ${error.available}`);
+  } else if (error instanceof APIError) {
+    console.error(`API error [${error.code}]: ${error.message}`);
+  }
+}
+```
+
+## Configuration
+
+```typescript
+const client = new SardisClient({
+  baseUrl: 'https://api.sardis.network', // API base URL (optional)
+  apiKey: 'sk_live_...',                  // Your API key (required)
+  timeout: 30000,                         // Request timeout in ms (optional)
+  maxRetries: 3,                          // Max retry attempts (optional)
+});
+```
+
+## Agents
+
+Create and manage AI agents with spending policies:
+
+```typescript
+// Create an agent
+const agent = await client.agents.create({
+  name: 'Invoice Processing Agent',
+  description: 'Processes invoices and pays vendors',
+  spending_limits: {
+    per_transaction: '500.00',
+    daily: '5000.00',
+    monthly: '50000.00',
+  },
+  policy: {
+    blocked_categories: ['gambling', 'adult'],
+    approval_threshold: '1000.00',
+  },
+});
+
+// Update spending limits
+await client.agents.update(agent.id, {
+  spending_limits: { daily: '10000.00' },
+});
+
+// List agents
+const agents = await client.agents.list({ is_active: true, limit: 50 });
+```
+
+## Wallets
+
+Manage non-custodial MPC wallets:
+
+```typescript
+// Create a wallet for an agent
+const wallet = await client.wallets.create({
+  agent_id: agent.id,
+  mpc_provider: 'turnkey', // or 'fireblocks'
+  limit_per_tx: '500.00',
+  limit_total: '10000.00',
+});
+
+// Get wallet balance (read from chain)
+const balance = await client.wallets.getBalance(wallet.id, 'base', 'USDC');
+console.log(`Balance: ${balance.balance} USDC`);
+
+// Set chain address
+await client.wallets.setAddress(wallet.id, 'base', '0x...');
+```
+
+## Policies (Natural Language → Deterministic Enforcement)
+
+LLMs help **write** policies, but Sardis uses deterministic code to **enforce** them.
+
+```typescript
+// Preview what the system understood (human-in-the-loop)
+const preview = await client.policies.preview(
+  "Max $100 per transaction, block gambling",
+  "agent_demo_001"
+);
+console.log(preview.parsed);
+
+// Apply policy to agent
+const applied = await client.policies.apply(
+  "Max $100 per transaction, block gambling",
+  "agent_demo_001"
+);
+console.log(applied.policy_id);
+```
+
+## Cards (Virtual Cards + Simulated Purchase Demo)
+
+```typescript
+// Issue a virtual card (Lithic-backed)
+const card = await client.cards.issue({
+  wallet_id: wallet.id,
+  limit_per_tx: "100.00",
+});
+
+// Simulate a purchase (e.g. gambling MCC -> policy deny + optional auto-freeze)
+const result = await client.cards.simulatePurchase(card.card_id, {
+  amount: "25.00",
+  currency: "USD",
+  merchant_name: "Demo Casino",
+  mcc_code: "7995",
+});
+console.log(result.policy, result.transaction);
+
+// Show card transactions
+const txs = await client.cards.transactions(card.card_id, 20);
+console.log(txs.length);
+```
+
+## Stablecoin Transfers (Agent is Sender)
+
+This is intended to be called by an agent process using an API key:
+
+```typescript
+const tx = await client.wallets.transfer(wallet.id, {
+  destination: "0x000000000000000000000000000000000000dEaD",
+  amount: "1.00",
+  token: "USDC",
+  chain: "base_sepolia",
+  domain: "localhost",
+  memo: "demo stablecoin transfer",
+});
+console.log(tx.tx_hash);
+```
+
+## Supported Chains
+
+| Chain | Mainnet | Testnet |
+|-------|---------|---------|
+| Base | `base` | `base_sepolia` |
+| Polygon | `polygon` | `polygon_amoy` |
+| Ethereum | `ethereum` | `ethereum_sepolia` |
+| Arbitrum | `arbitrum` | `arbitrum_sepolia` |
+| Optimism | `optimism` | `optimism_sepolia` |
+
+> **Note:** Solana support is planned but not yet implemented.
+
+## Supported Tokens
+
+- **USDC** - USD Coin (Circle)
+- **USDT** - Tether USD
+- **PYUSD** - PayPal USD
+- **EURC** - Euro Coin (Circle)
+
+## TypeScript Support
+
+This SDK is written in TypeScript and provides full type definitions for all API responses.
+
+```typescript
+import type {
+  Chain,
+  Token,
+  MPCProvider,
+  Payment,
+  Hold,
+  Webhook,
+  Service,
+  GasEstimate,
+  Agent,
+  Wallet,
+  WalletBalance,
+} from '@sardis/sdk';
+
+// Type-safe chain selection
+const chain: Chain = 'base';
+const token: Token = 'USDC';
+```
+
+## Framework Integrations
+
+### LangChain.js
+
+```typescript
+import { SardisToolkit } from '@sardis/sdk/integrations/langchain';
+
+const toolkit = new SardisToolkit({ client });
+const tools = toolkit.getTools();
+
+// Use with LangChain agent
+const agent = createOpenAIFunctionsAgent({ llm, tools, prompt });
+```
+
+### Vercel AI SDK
+
+```typescript
+import { sardisTools } from '@sardis/sdk/integrations/vercel-ai';
+
+const tools = sardisTools(client);
+
+// Use with Vercel AI
+const { text } = await generateText({
+  model: openai('gpt-4'),
+  tools,
+  messages,
+});
+```
+
+### OpenAI Function Calling
+
+```typescript
+import { sardisFunctions, handleSardisCall } from '@sardis/sdk/integrations/openai';
+
+// Get function definitions
+const functions = sardisFunctions(client);
+
+// Handle function calls
+const result = await handleSardisCall(client, functionName, args);
+```
+
+## Browser Usage
+
+The SDK includes a browser-optimized bundle:
+
+```html
+<!-- Via CDN -->
+<script src="https://unpkg.com/@sardis/sdk@latest/dist/browser/sardis.umd.min.js"></script>
+<script>
+  const client = new Sardis.SardisClient({
+    apiKey: 'your-api-key',
+  });
+</script>
+```
+
+Or import the browser bundle directly:
+
+```typescript
+import { SardisClient } from '@sardis/sdk/browser';
+```
+
+## Requirements
+
+- Node.js 18.0.0 or higher
+- TypeScript 4.7+ (optional, for type definitions)
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](https://github.com/sardis-network/sardis-sdk-js/blob/main/CONTRIBUTING.md) for details.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## Support
+
+- [Documentation](https://docs.sardis.network)
+- [GitHub Issues](https://github.com/sardis-network/sardis-sdk-js/issues)
+- [Discord Community](https://discord.gg/sardis)
+
+## License
+
+MIT - see [LICENSE](./LICENSE) for details.