@naturalpay/sdk 0.0.2

package/README.md

@@ -0,0 +1,290 @@
+# Natural Payments TypeScript SDK
+
+Official TypeScript/Node.js SDK for Natural Payments - AI agent payment infrastructure.
+
+## Installation
+
+```bash
+npm install naturalpay
+# or
+pnpm add naturalpay
+# or
+yarn add naturalpay
+```
+
+## 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({
+  recipientEmail: 'alice@example.com',
+  amount: 50.00,
+  currency: 'USD',
+  memo: 'Payment for consulting',
+  agentId: 'agent_123',
+  customerPartyId: 'party_456',
+});
+
+console.log(`Payment created: ${payment.transferId}`);
+
+// Check balance
+const balance = await client.wallet.balance();
+console.log(`Available: $${balance.balances[0]?.available.amountDollars}`);
+```
+
+## Configuration
+
+### Environment Variables
+
+- `NATURAL_API_KEY` - Your API key (starts with `pk_sandbox_` or `pk_live_`)
+- `NATURAL_SERVER_URL` - API base URL (default: `https://api.natural.co`)
+
+### Client Options
+
+```typescript
+const client = new NaturalClient({
+  apiKey: 'pk_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({
+  recipientEmail: 'alice@example.com',
+  // or recipientPhone: '+1234567890',
+  amount: 100.00,
+  currency: 'USD',
+  memo: 'Payment description',
+  agentId: 'agent_123',
+  customerPartyId: 'party_456',
+  instanceId: 'instance_789', // optional, for audit grouping
+});
+
+// Get payment status
+const status = await client.payments.retrieve('transfer_id');
+
+// Cancel a pending payment
+const result = await client.payments.cancel('transfer_id');
+```
+
+### Wallet
+
+```typescript
+// Get account balance
+const balance = await client.wallet.balance();
+
+// Deposit funds (sandbox only)
+const deposit = await client.wallet.deposit({
+  amount: 1000,
+  currency: 'USD',
+});
+
+// Withdraw funds
+const withdrawal = await client.wallet.withdraw({
+  amount: 500,
+  bankAccountId: 'bank_account_id',
+});
+```
+
+### Transactions
+
+```typescript
+import { TransactionTypeFilter } from '@naturalpay/sdk';
+
+// List all transactions
+const transactions = await client.transactions.list({
+  limit: 100,
+  customerFilter: '_self', // or customer agent_id
+  agentId: 'agent_123',
+  customerPartyId: 'party_456',
+});
+
+// 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 delegations
+const delegations = await client.delegations.list({
+  status: 'ACTIVE',
+  limit: 50,
+});
+
+// Get delegation details
+const delegation = await client.delegations.retrieve('delegation_id');
+
+// Create a delegation
+const newDelegation = await client.delegations.create({
+  targetPartyId: 'party_123',
+  permissions: ['payment:create', 'balance:read'],
+});
+
+// Update delegation
+const updatedDelegation = await client.delegations.update('delegation_id', {
+  status: 'REVOKED',
+});
+```
+
+### Customers
+
+```typescript
+// List customers
+const customers = await client.customers.list({
+  limit: 50,
+});
+
+// Get customer details
+const customer = await client.customers.retrieve('customer_party_id');
+```
+
+## 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 --help
+
+# Start MCP server with stdio transport
+npx naturalpay mcp serve
+
+# Start with HTTP transport
+npx naturalpay mcp serve --transport http --port 8080
+```
+
+> **Note:** We recommend `npx` over global installation to avoid conflicts if you also use the Python SDK (`uvx naturalpay` or `python -m naturalpay`).
+
+### Programmatic Usage
+
+```typescript
+import { createServer } from 'naturalpay/mcp';
+
+const server = createServer('pk_sandbox_xxx');
+
+// Start with stdio
+server.start({ transportType: 'stdio' });
+
+// Or start with HTTP
+server.start({
+  transportType: 'httpStream',
+  httpStream: { port: 8080 },
+});
+```
+
+### Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `create_payment` | Create a payment to a recipient |
+| `get_payment_status` | Check payment status by transfer ID |
+| `cancel_payment` | Cancel a pending payment |
+| `get_account_balance` | Get current wallet balance |
+| `list_transactions` | List recent transactions |
+| `list_agents` | List agents for the partner |
+
+## 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 {
+  Payment,
+  PaymentCreateParams,
+  AccountBalance,
+  Transaction,
+  TransactionTypeFilter,
+  Agent,
+  Delegation,
+  Customer,
+} from '@naturalpay/sdk';
+```
+
+## License
+
+MIT