neutron-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Neutron
+
+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,340 @@
+# Neutron SDK
+
+[![npm version](https://img.shields.io/npm/v/neutron-sdk.svg)](https://www.npmjs.com/package/neutron-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+The official TypeScript/Node.js SDK for [Neutron](https://neutron.me) — Bitcoin Lightning, stablecoins, and fiat payments through a single API.
+
+## Install
+
+```bash
+npm install neutron-sdk
+```
+
+## Quick Start
+
+```typescript
+import { Neutron } from "neutron-sdk";
+
+const neutron = new Neutron({
+  apiKey: process.env.NEUTRON_API_KEY!,
+  apiSecret: process.env.NEUTRON_API_SECRET!,
+});
+
+// Check your balances
+const wallets = await neutron.account.wallets();
+console.log(wallets); // [{ ccy: "BTC", availableBalance: 0.05 }, ...]
+
+// Create a Lightning invoice
+const invoice = await neutron.lightning.createInvoice({ amountSats: 10000 });
+console.log(invoice.invoice); // "lnbc100u1p..."
+```
+
+That's it. Auth, token refresh, and retries are handled automatically.
+
+---
+
+## Resources
+
+The SDK is organized into resources, like Stripe's SDK:
+
+```
+neutron.account       // Account info, wallets, deposit addresses
+neutron.transactions  // Create, confirm, list, track payments
+neutron.lightning     // Lightning invoices, payments, utilities
+neutron.webhooks      // Webhook management
+neutron.rates         // Exchange rates
+neutron.fiat          // Fiat payouts and bank lookups
+```
+
+---
+
+## Usage Examples
+
+### Receive Bitcoin via Lightning
+
+```typescript
+const invoice = await neutron.lightning.createInvoice({
+  amountSats: 50000,         // 50,000 sats
+  memo: "Order #1234",       // shown to payer
+  extRefId: "order-1234",    // your tracking ID
+});
+
+// Give this to your customer
+console.log(invoice.invoice);    // BOLT11 string
+console.log(invoice.qrPageUrl);  // hosted QR code page
+console.log(invoice.txnId);      // track payment status
+```
+
+### Send to a Lightning Address
+
+```typescript
+const txn = await neutron.lightning.payAddress("alice@getalby.com", {
+  amountSats: 5000,
+});
+// Review the quote
+console.log(txn.sourceReq.neutronpayFees); // fees in BTC
+
+// Confirm to send
+await neutron.transactions.confirm(txn.txnId);
+```
+
+### Pay a Lightning Invoice
+
+```typescript
+const txn = await neutron.lightning.payInvoice("lnbc100u1p...");
+await neutron.transactions.confirm(txn.txnId);
+```
+
+### Check Wallet Balances
+
+```typescript
+const wallets = await neutron.account.wallets();
+for (const w of wallets) {
+  console.log(`${w.ccy}: ${w.availableBalance}`);
+}
+```
+
+### Convert BTC to USDT
+
+```typescript
+const txn = await neutron.transactions.create({
+  sourceReq: { ccy: "BTC", method: "neutronpay", amtRequested: 0.001, reqDetails: {} },
+  destReq: { ccy: "USDT", method: "neutronpay", reqDetails: {} },
+});
+console.log(`Rate: ${txn.fxRate}`);
+await neutron.transactions.confirm(txn.txnId);
+```
+
+### Send Bitcoin On-Chain
+
+```typescript
+const txn = await neutron.transactions.create({
+  sourceReq: { ccy: "BTC", method: "neutronpay" },
+  destReq: {
+    ccy: "BTC",
+    method: "on-chain",
+    amtRequested: 0.005,
+    reqDetails: { address: "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh" },
+  },
+});
+await neutron.transactions.confirm(txn.txnId);
+```
+
+### Get Deposit Addresses
+
+```typescript
+const btc = await neutron.account.btcAddress();
+console.log(btc.address);  // "bc1q..." or "3M5A..."
+
+const usdt = await neutron.account.usdtAddress("TRON");
+console.log(usdt.address);  // "T..."
+```
+
+### Fiat Payout (Bank Transfer)
+
+```typescript
+// Look up bank codes first
+const banks = await neutron.fiat.institutions("VN");
+
+// Send VND to a bank account
+const txn = await neutron.fiat.payout({
+  sourceCcy: "BTC",
+  sourceAmount: 0.001,
+  destCcy: "VND",
+  destMethod: "vnd-instant",
+  bankAcctNum: "0123456789",
+  institutionCode: "970422",
+  recipientName: "LE VAN A",
+  countryCode: "VN",
+});
+await neutron.transactions.confirm(txn.txnId);
+```
+
+### Exchange Rates
+
+```typescript
+const rates = await neutron.rates.get();
+console.log(rates); // { BTCUSD: 97500, BTCVND: 2437500000, ... }
+```
+
+### Webhooks
+
+```typescript
+// Create
+const webhook = await neutron.webhooks.create({
+  callback: "https://myapp.com/webhooks/neutron",
+  secret: "my-webhook-secret",
+});
+
+// List
+const hooks = await neutron.webhooks.list();
+
+// Update
+await neutron.webhooks.update(webhook.id, { callback: "https://myapp.com/v2/webhooks" });
+
+// Delete
+await neutron.webhooks.delete(webhook.id);
+```
+
+### Lightning Utilities
+
+```typescript
+// Decode an invoice before paying
+const decoded = await neutron.lightning.decodeInvoice("lnbc100u1p...");
+console.log(decoded.amount, decoded.expiry);
+
+// Verify a Lightning Address exists
+const info = await neutron.lightning.resolveAddress("alice@getalby.com");
+console.log(info.minSendable, info.maxSendable);
+
+// Resolve an LNURL
+const lnurl = await neutron.lightning.resolveLnurl("lnurl1dp68gurn...");
+console.log(lnurl.tag); // "payRequest" or "withdrawRequest"
+```
+
+---
+
+## Verify Webhook Signatures
+
+One-liner verification — no client instance needed:
+
+```typescript
+import { Neutron } from "neutron-sdk";
+
+// Express example
+app.post("/webhooks/neutron", express.raw({ type: "application/json" }), (req, res) => {
+  try {
+    const event = Neutron.verifyWebhook(
+      req.body,
+      req.headers["x-neutronpay-signature"],
+      "my-webhook-secret"
+    );
+    res.status(200).send("OK");
+
+    // Event is verified — safe to use
+    if (event.txnState === "completed") {
+      fulfillOrder(event.extRefId);
+    }
+  } catch (err) {
+    res.status(401).send("Invalid signature");
+  }
+});
+```
+
+## Wait for Transaction Completion
+
+```typescript
+const txn = await neutron.lightning.payInvoice("lnbc...");
+await neutron.transactions.confirm(txn.txnId);
+
+// Poll until done (with state change callbacks)
+const result = await neutron.transactions.waitForCompletion(txn.txnId, {
+  intervalMs: 2000,
+  timeoutMs: 60000,
+  onStateChange: (state) => console.log("State:", state),
+});
+console.log(result.txnState); // "completed"
+```
+
+## Utility Helpers
+
+```typescript
+import { satsToBtc, btcToSats, formatSats, formatBtc } from "neutron-sdk";
+
+satsToBtc(10000);      // 0.0001
+btcToSats(0.0001);     // 10000
+formatSats(1500000);   // "1,500,000 sats"
+formatBtc(0.00015);    // "0.00015000 BTC"
+```
+
+## Constants
+
+```typescript
+import { Currency, PaymentMethod, TransactionStates, Chain } from "neutron-sdk";
+
+// Use in transaction creation for type safety
+const txn = await neutron.transactions.create({
+  sourceReq: { ccy: Currency.BTC, method: PaymentMethod.NEUTRON, amtRequested: 0.001, reqDetails: {} },
+  destReq: { ccy: Currency.USDT, method: PaymentMethod.NEUTRON, reqDetails: {} },
+});
+
+// Check states
+if (txn.txnState === TransactionStates.COMPLETED) { ... }
+
+// USDT chains
+const { address } = await neutron.account.usdtAddress(Chain.TRON);
+```
+
+## Error Handling
+
+```typescript
+import { NeutronApiError, NeutronAuthError, NeutronValidationError } from "neutron-sdk";
+
+try {
+  await neutron.lightning.createInvoice({ amountSats: 10000 });
+} catch (err) {
+  if (err instanceof NeutronApiError) {
+    console.log(err.status);       // 400, 401, 429, etc.
+    console.log(err.code);         // Neutron error code
+    console.log(err.message);      // Human-readable message
+    console.log(err.isRetryable);  // true for 5xx/429
+    console.log(err.isRateLimited); // true for 429
+  } else if (err instanceof NeutronAuthError) {
+    console.log("Check your API credentials");
+  } else if (err instanceof NeutronValidationError) {
+    console.log("Invalid parameters:", err.message);
+  }
+}
+```
+
+---
+
+## Configuration
+
+```typescript
+const neutron = new Neutron({
+  apiKey: "your-api-key",       // Required
+  apiSecret: "your-api-secret", // Required
+  baseUrl: "https://enapi.npay.dev",  // Sandbox (default: enapi.npay.live)
+  timeout: 15000,               // Request timeout in ms (default: 30000)
+  maxRetries: 3,                // Retry attempts for 5xx/429 (default: 2)
+  debug: true,                  // Log requests to stderr
+});
+```
+
+---
+
+## Key Concepts
+
+- **Amounts are in BTC**, not satoshis. `0.0001` BTC = 10,000 sats.
+- **Two-step flow**: `.create()` returns a quote → `.confirm()` executes it.
+- **Set amount on one side only** — `sourceReq` OR `destReq`, not both.
+- **`createInvoice()` auto-confirms** — no second step needed for receiving.
+- **KYC only for fiat payouts**. Lightning, on-chain, and stablecoin transfers don't require KYC.
+- **Token management is automatic** — the SDK authenticates on first request and refreshes as needed.
+
+---
+
+## Supported Payment Methods
+
+| Type | Methods |
+|------|---------|
+| **Bitcoin Lightning** | Bolt11 invoices, Lightning Addresses, LNURL |
+| **Bitcoin On-Chain** | Standard BTC transactions |
+| **Stablecoins** | USDT on TRON (TRC-20) and Ethereum (ERC-20) |
+| **Fiat Payouts** | Bank transfers (VND, USD, etc.) |
+| **Internal** | Wallet-to-wallet swaps (BTC ↔ USDT ↔ fiat) |
+
+---
+
+## Links
+
+- **Documentation**: [docs.neutron.me](https://docs.neutron.me)
+- **API Reference**: [docs.neutron.me/reference](https://docs.neutron.me/reference/overview)
+- **MCP Server**: [neutron-mcp](https://www.npmjs.com/package/neutron-mcp) (for AI agents)
+- **Contact**: support@neutron.me
+
+## License
+
+MIT