@naturalpay/sdk 0.1.1

package/README.md

@@ -0,0 +1,261 @@
+# Natural Payments TypeScript SDK
+
+Official TypeScript/Node.js SDK for Natural Payments - AI agent payment infrastructure.
+
+## Installation
+
+```bash
+npm install @naturalpay/sdk
+# or
+pnpm add @naturalpay/sdk
+# or
+yarn add @naturalpay/sdk
+```
+
+## Quick Start
+
+```typescript
+import { NaturalClient } from '@naturalpay/sdk';
+
+const client = new NaturalClient({
+  apiKey: process.env.NATURAL_API_KEY, // or pass directly
+});
+
+// Create a payment
+const payment = await client.payments.create({
+  agentId: 'agent_123',
+  instanceId: 'instance_456',
+  amount: 5000,
+  customerPartyId: 'party_456',
+  recipient: 'alice@example.com',
+  memo: 'Payment for consulting',
+  idempotencyKey: 'unique-key-for-this-payment',
+});
+
+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_sandbox_` or `sk_ntl_live_`)
+- `NATURAL_SERVER_URL` - API base URL (default: `https://api.natural.co`)
+
+### Client Options
+
+```typescript
+const client = new NaturalClient({
+  apiKey: 'sk_ntl_sandbox_xxx',        // API key
+  baseUrl: 'https://api.natural.co', // Custom base URL
+  timeout: 30000,                   // Request timeout in ms
+});
+```
+
+## Resources
+
+### 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',
+});
+```
+
+### 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
+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 |
+
+## Error Handling
+
+```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';
+```
+
+## License
+
+MIT