@naturalpay/sdk 0.1.2 → 0.1.4

package/README.md

@@ -1,260 +1,52 @@
-# Natural Payments TypeScript SDK
+# Natural Payments SDK
 
-Official TypeScript/Node.js SDK for Natural Payments - AI agent payment infrastructure.
+[![NPM version](https://img.shields.io/npm/v/@naturalpay/sdk.svg)](https://npmjs.org/package/@naturalpay/sdk)
+
+The Natural Payments SDK provides access to the [Natural API](https://docs.natural.co) from server-side TypeScript and JavaScript applications, for building AI agents that send, receive, and manage money.
+
+## Documentation
+
+Full documentation, guides, and API reference are available at **[docs.natural.co/guides/platform/sdks](https://docs.natural.co/guides/platform/sdks)**.
 
 ## Installation
 
-```bash
+```sh
 npm install @naturalpay/sdk
-# or
-pnpm add @naturalpay/sdk
-# or
-yarn add @naturalpay/sdk
 ```
 
-## Quick Start
+## Getting started
 
 ```typescript
 import { NaturalClient } from '@naturalpay/sdk';
 
-const client = new NaturalClient({
-  apiKey: process.env.NATURAL_API_KEY, // or pass directly
-});
+const client = new NaturalClient({ apiKey: process.env['NATURAL_API_KEY'] });
 
-// Create a payment
 const payment = await client.payments.create({
-  agentId: 'agent_123',
-  instanceId: 'instance_456',
-  amount: 5000,
-  customerPartyId: 'party_456',
   recipient: 'alice@example.com',
+  amount: 5000,
   memo: 'Payment for consulting',
-  idempotencyKey: 'unique-key-for-this-payment',
+  agentId: 'agt_019cd1798d637a4da75dce386343931d',
+  instanceId: 'session-abc123',
+  customerPartyId: 'pty_019cd34e27c179bfbbe6870486b11b67',
+  idempotencyKey: 'pay_unique_key',
 });
 
-console.log(`Payment created: ${payment.transactionId}`);
-
-// Check balance
-const balance = await client.wallet.balance();
-console.log(`Available: ${balance.available.amountMinor} minor units`);
-```
-
-## Configuration
-
-### Environment Variables
-
-- `NATURAL_API_KEY` - Your API key (starts with `sk_ntl_dev_` or `sk_ntl_prod_`)
-- `NATURAL_SERVER_URL` - API base URL (default: `https://api.natural.co`)
-
-### Client Options
-
-```typescript
-const client = new NaturalClient({
-  apiKey: 'sk_ntl_dev_xxx',             // API key
-  baseUrl: 'https://api.natural.co', // Custom base URL
-  timeout: 30000,                   // Request timeout in ms
-});
+console.log(payment.transactionId);
 ```
 
-## Resources
+## MCP server
 
-### Payments
-
-```typescript
-// Create a payment
-const payment = await client.payments.create({
-  agentId: 'agent_123',
-  instanceId: 'instance_789', // required when agentId is provided
-  amount: 10000,
-  customerPartyId: 'party_456',
-  recipient: 'alice@example.com', // email, phone, or party ID (pty_xxx)
-  memo: 'Payment description',
-  idempotencyKey: 'unique-key-for-this-payment',
-});
-```
+The SDK ships with an MCP server for AI agent integration with Claude Desktop, Cursor, and other MCP clients:
 
-### Wallet
-
-```typescript
-// Get account balance
-const balance = await client.wallet.balance();
-
-// Withdraw funds
-const withdrawal = await client.wallet.withdraw({
-  amount: 50000,
-  externalFundingSourceId: 'efs_xxx',
-  idempotencyKey: 'wd_unique_key',
-});
-```
-
-### Transactions
-
-```typescript
-import { TransactionTypeFilter } from '@naturalpay/sdk';
-
-// List all transactions
-const transactions = await client.transactions.list({
-  limit: 100,
-  agentId: 'agent_123',
-  instanceId: 'instance_789', // required when agentId is provided
-});
-
-// List only transfers
-const transfers = await client.transactions.list({
-  type: TransactionTypeFilter.TRANSFER,
-});
-
-// List only payments
-const payments = await client.transactions.list({
-  type: TransactionTypeFilter.PAYMENT,
-});
-```
-
-### Agents
-
-```typescript
-// List agents
-const agents = await client.agents.list({
-  status: 'ACTIVE',
-  limit: 50,
-});
-
-// Create an agent
-const agent = await client.agents.create({
-  name: 'Shopping Assistant',
-  partyId: 'party_123',
-  description: 'Handles shopping tasks',
-});
-
-// Update an agent
-const updated = await client.agents.update('agent_id', {
-  name: 'Updated Name',
-  status: 'REVOKED',
-});
-
-// Delete an agent
-await client.agents.delete('agent_id');
-```
-
-### Delegations
-
-```typescript
-// List agent delegations
-const delegations = await client.delegations.list({
-  limit: 50,
-});
-
-// Get delegation details
-const delegation = await client.delegations.get('adl_xxx');
-```
-
-### Customers
-
-```typescript
-// List customers who have delegated to you
-const customers = await client.customers.list({
-  limit: 50,
-});
-```
-
-## MCP Server
-
-The SDK includes an MCP (Model Context Protocol) server for AI agent integration.
-
-### CLI Usage
-
-Use `npx` to run the CLI without global installation:
-
-```bash
-# Show help
-npx @naturalpay/sdk --help
-
-# Start MCP server with stdio transport
+```sh
 npx @naturalpay/sdk mcp serve
-
-# With explicit options
-npx @naturalpay/sdk mcp serve --api-key sk_ntl_sandbox_xxx --mcp-url https://mcp.natural.co
 ```
 
-> **Note:** We recommend `npx` over global installation to avoid conflicts if you also use the Python SDK (`uvx naturalpay` or `python -m naturalpay`).
-
-### Claude Desktop / Cursor Config
-
-```json
-{
-  "mcpServers": {
-    "natural": {
-      "command": "npx",
-      "args": ["@naturalpay/sdk", "mcp", "serve"],
-      "env": { "NATURAL_API_KEY": "sk_ntl_..." }
-    }
-  }
-}
-```
-
-### Available MCP Tools
-
-| Tool | Description |
-|------|-------------|
-| `create_payment` | Create a payment to a recipient |
-| `get_payment_status` | Check payment status by transfer ID |
-| `get_account_balance` | Get current wallet balance |
-| `list_transactions` | List recent transactions |
-| `list_agents` | List agents for the partner |
-| `list_customers` | List customers who delegated to you |
+See [docs.natural.co/guides/platform/sdks#mcp-server](https://docs.natural.co/guides/platform/sdks#mcp-server) for client configuration.
 
-## Error Handling
+## Requirements
 
-```typescript
-import {
-  NaturalError,
-  AuthenticationError,
-  InvalidRequestError,
-  PaymentError,
-  InsufficientFundsError,
-  RecipientNotFoundError,
-  RateLimitError,
-  ServerError,
-} from '@naturalpay/sdk';
-
-try {
-  await client.payments.create({ ... });
-} catch (error) {
-  if (error instanceof AuthenticationError) {
-    // Handle authentication issues (401)
-  } else if (error instanceof InsufficientFundsError) {
-    // Handle insufficient balance
-  } else if (error instanceof RecipientNotFoundError) {
-    // Handle invalid recipient
-  } else if (error instanceof RateLimitError) {
-    // Handle rate limiting (429)
-    console.log(`Retry after: ${error.retryAfter}s`);
-  } else if (error instanceof ServerError) {
-    // Handle server errors (5xx)
-  } else if (error instanceof NaturalError) {
-    // Handle other API errors
-    console.log(`Error: ${error.message}, Code: ${error.code}`);
-  }
-}
-```
-
-## TypeScript Support
-
-This SDK is written in TypeScript and provides full type definitions:
-
-```typescript
-import type {
-  PaymentCreateParams,
-  AccountBalance,
-  Transaction,
-  TransactionListResponse,
-  Agent,
-  AgentDelegation,
-  WithdrawResponse,
-} from '@naturalpay/sdk';
-
-import { TransactionTypeFilter } from '@naturalpay/sdk';
-```
+Node.js 18+
 
 ## License