@naturalpay/sdk 0.1.1 → 0.1.3

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_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
-});
+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
 

package/dist/index.cjs

@@ -62,7 +62,7 @@ var ServerError = class extends NaturalError {
 };
 
 // src/version.ts
-var VERSION = "0.1.1";
+var VERSION = "0.1.3";
 
 // src/logging.ts
 var LOG_LEVEL_VALUES = {
@@ -312,6 +312,39 @@ function getToolCallHeader() {
 var logger = getLogger("http");
 var DEFAULT_BASE_URL = "https://api.natural.co";
 var DEFAULT_TIMEOUT = 3e4;
+var API_KEY_PREFIX_REGEX = /^sk_ntl_(dev|sandbox|prod)_/;
+function parseApiKeyEnv(key) {
+  const match = API_KEY_PREFIX_REGEX.exec(key);
+  if (match) {
+    return match[1];
+  }
+  const preview = key.length > 16 ? `${key.slice(0, 16)}...` : key;
+  throw new InvalidRequestError(
+    `Invalid API key prefix. Expected a key starting with 'sk_ntl_dev_', 'sk_ntl_sandbox_', or 'sk_ntl_prod_'. Got: '${preview}'`
+  );
+}
+function validateBaseUrl(baseUrl) {
+  let url;
+  try {
+    url = new URL(baseUrl);
+  } catch {
+    throw new InvalidRequestError(`Invalid baseUrl: '${baseUrl}'. Must be a valid absolute URL.`);
+  }
+  if (url.protocol === "https:") {
+    return;
+  }
+  const host = url.hostname;
+  if (host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]") {
+    return;
+  }
+  const allowHttp = process.env["NATURAL_ALLOW_HTTP"];
+  if (allowHttp && allowHttp !== "0" && allowHttp.toLowerCase() !== "false") {
+    return;
+  }
+  throw new InvalidRequestError(
+    `baseUrl must use HTTPS (got '${baseUrl}'). To allow plaintext HTTP for development, set NATURAL_ALLOW_HTTP=1 or use a localhost host.`
+  );
+}
 function hashString(str) {
   let hash = 0;
   for (let i = 0; i < str.length; i++) {
@@ -329,6 +362,10 @@ var HTTPClient = class {
   constructor(options = {}) {
     this.apiKey = options.apiKey ?? process.env["NATURAL_API_KEY"] ?? "";
     this.baseUrl = (options.baseUrl ?? process.env["NATURAL_SERVER_URL"] ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    validateBaseUrl(this.baseUrl);
+    if (this.apiKey) {
+      parseApiKeyEnv(this.apiKey);
+    }
     this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
   }
   /**
@@ -338,9 +375,6 @@ var HTTPClient = class {
     if (!this.apiKey) {
       throw new AuthenticationError();
     }
-    if (!this.apiKey.startsWith("sk_ntl_")) {
-      return this.apiKey;
-    }
     const cacheKey = hashString(this.apiKey);
     const cached = this.jwtCache.get(cacheKey);
     if (cached && Date.now() < cached.expiresAt) {
@@ -1224,6 +1258,8 @@ exports.getLogger = getLogger;
 exports.logApiCall = logApiCall;
 exports.logError = logError;
 exports.logToolCall = logToolCall;
+exports.parseApiKeyEnv = parseApiKeyEnv;
 exports.runWithContext = runWithContext;
+exports.validateBaseUrl = validateBaseUrl;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map