@stellar-snaps/sdk 0.1.0

package/README.md

@@ -0,0 +1,295 @@
+# @stellar-snaps/sdk
+
+A complete SDK for building on Stellar Snaps technology. Create shareable payment links, build transactions, integrate wallets, and host your own snap endpoints.
+
+## What is Stellar Snaps?
+
+Stellar Snaps lets you create shareable payment links for the Stellar blockchain - like Venmo/PayPal request links, but for crypto. Share links on Twitter, Discord, or your website, and recipients can pay with one click using their Freighter wallet.
+
+## Installation
+
+```bash
+npm install @stellar-snaps/sdk
+# or
+pnpm add @stellar-snaps/sdk
+```
+
+## Quick Start
+
+### 1. Create a Payment Link
+
+```typescript
+import { createPaymentSnap } from '@stellar-snaps/sdk';
+
+const { uri } = createPaymentSnap({
+  destination: 'GDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOUJ3DTJE4QRK764',
+  amount: '10',
+  assetCode: 'USDC',
+  assetIssuer: 'GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN',
+  memo: 'Coffee payment',
+  network: 'public',
+});
+
+console.log(uri);
+// => web+stellar:pay?destination=GDQP2K...&amount=10&asset_code=USDC&...
+```
+
+### 2. Parse a Payment Link
+
+```typescript
+import { parseSnapUri } from '@stellar-snaps/sdk';
+
+const parsed = parseSnapUri('web+stellar:pay?destination=GDQP2K...&amount=10');
+
+console.log(parsed);
+// => { type: 'pay', destination: 'GDQP2K...', amount: '10', ... }
+```
+
+### 3. Build and Sign a Transaction
+
+```typescript
+import {
+  connectFreighter,
+  buildPaymentTransaction,
+  signWithFreighter,
+  submitTransaction,
+} from '@stellar-snaps/sdk';
+
+// Connect to user's wallet
+const { publicKey, network } = await connectFreighter();
+
+// Build the transaction
+const xdr = buildPaymentTransaction({
+  source: publicKey,
+  sequence: '123456789', // Get from Horizon API
+  destination: 'GBZX...',
+  amount: '10',
+  asset: { code: 'XLM' },
+  network: 'public',
+});
+
+// Sign with Freighter (opens popup)
+const signedXdr = await signWithFreighter(xdr, 'public');
+
+// Submit to Stellar network
+const result = await submitTransaction(signedXdr, 'public');
+
+if (result.successful) {
+  console.log(`Success! Hash: ${result.hash}`);
+}
+```
+
+### 4. Host Your Own Snap Endpoints
+
+Create a discovery file to enable the browser extension to find your snaps:
+
+```typescript
+import { createDiscoveryFile } from '@stellar-snaps/sdk';
+
+const discovery = createDiscoveryFile({
+  name: 'My Payment App',
+  description: 'Accept Stellar payments',
+  rules: [
+    { pathPattern: '/pay/*', apiPath: '/api/snap/$1' },
+  ],
+});
+
+// Save as: public/.well-known/stellar-snap.json
+```
+
+## API Reference
+
+### SEP-0007 URI Functions
+
+#### `createPaymentSnap(options)`
+
+Creates a SEP-0007 payment URI.
+
+```typescript
+interface PaymentSnapOptions {
+  destination: string;          // Recipient's Stellar address
+  amount?: string;              // Amount to send
+  assetCode?: string;           // Asset code (default: XLM)
+  assetIssuer?: string;         // Asset issuer (required for non-XLM)
+  memo?: string;                // Transaction memo
+  memoType?: MemoType;          // Memo type (default: MEMO_TEXT)
+  message?: string;             // Human-readable message (max 300 chars)
+  network?: 'public' | 'testnet';
+  callback?: string;            // Callback URL after signing
+}
+```
+
+#### `createTransactionSnap(options)`
+
+Creates a SEP-0007 transaction URI for arbitrary transactions.
+
+```typescript
+interface TransactionSnapOptions {
+  xdr: string;                  // Transaction XDR
+  network?: 'public' | 'testnet';
+  message?: string;             // Human-readable message
+  callback?: string;            // Callback URL
+  pubkey?: string;              // Required signer's public key
+}
+```
+
+#### `parseSnapUri(uri)`
+
+Parses a SEP-0007 URI back into an object.
+
+```typescript
+const parsed = parseSnapUri('web+stellar:pay?destination=G...');
+// => { type: 'pay', destination: 'G...', ... }
+```
+
+### Validation Functions
+
+#### `isValidStellarAddress(address)`
+
+Returns `true` if the address is a valid Stellar public key (56 chars, starts with 'G').
+
+#### `isValidAssetCode(code)`
+
+Returns `true` if the code is a valid asset code (1-12 alphanumeric chars).
+
+#### `isValidAmount(amount)`
+
+Returns `true` if the amount is a positive number string.
+
+### Transaction Building
+
+#### `buildPaymentTransaction(options)`
+
+Builds a Stellar payment transaction and returns the XDR.
+
+```typescript
+interface BuildPaymentOptions {
+  source: string;               // Payer's address
+  sequence: string;             // Account sequence number
+  destination: string;          // Recipient's address
+  amount: string;               // Amount to send
+  asset?: {
+    code: string;
+    issuer?: string;
+  };
+  memo?: {
+    type: MemoType;
+    value: string;
+  };
+  network: 'public' | 'testnet';
+  timeout?: number;             // Default: 180 seconds
+}
+```
+
+#### `createAsset(code, issuer?)`
+
+Creates a Stellar Asset object.
+
+```typescript
+const xlm = createAsset('XLM');
+const usdc = createAsset('USDC', 'GA5ZS...');
+```
+
+### Freighter Wallet Integration
+
+#### `connectFreighter()`
+
+Connects to Freighter wallet and returns the user's public key and network.
+
+```typescript
+const { publicKey, network } = await connectFreighter();
+```
+
+#### `isFreighterConnected()`
+
+Returns `true` if Freighter is installed and the user has granted access.
+
+#### `getFreighterNetwork()`
+
+Returns the current network from Freighter ('public' or 'testnet').
+
+#### `signWithFreighter(xdr, network)`
+
+Signs a transaction XDR using Freighter. Opens a popup for user approval.
+
+#### `submitTransaction(signedXdr, network)`
+
+Submits a signed transaction to the Stellar network.
+
+```typescript
+const result = await submitTransaction(signedXdr, 'public');
+// => { hash: 'abc...', successful: true, ledger: 12345 }
+```
+
+### Discovery Files
+
+#### `createDiscoveryFile(options)`
+
+Creates a discovery file object for hosting at `/.well-known/stellar-snap.json`.
+
+```typescript
+interface CreateDiscoveryFileOptions {
+  name: string;
+  description?: string;
+  icon?: string;
+  rules: Array<{
+    pathPattern: string;    // URL pattern, e.g., "/pay/*"
+    apiPath: string;        // API path, e.g., "/api/snap/$1"
+  }>;
+}
+```
+
+#### `validateDiscoveryFile(file)`
+
+Type guard that validates if an object is a valid discovery file.
+
+#### `matchUrlToRule(pathname, rules)`
+
+Matches a URL path against rules and returns the API path.
+
+```typescript
+matchUrlToRule('/pay/abc123', rules);
+// => '/api/snap/abc123'
+```
+
+### Error Classes
+
+All errors extend `StellarSnapError` with a `code` property for programmatic handling:
+
+- `InvalidAddressError` - Invalid Stellar address
+- `InvalidAmountError` - Invalid amount
+- `InvalidAssetError` - Invalid asset configuration
+- `InvalidUriError` - Invalid SEP-0007 URI
+
+```typescript
+try {
+  createPaymentSnap({ destination: 'invalid' });
+} catch (error) {
+  if (error instanceof InvalidAddressError) {
+    console.log(error.code); // 'INVALID_ADDRESS'
+  }
+}
+```
+
+### Constants
+
+```typescript
+import { NETWORK_PASSPHRASES, HORIZON_URLS } from '@stellar-snaps/sdk';
+
+NETWORK_PASSPHRASES.public;  // 'Public Global Stellar Network ; September 2015'
+NETWORK_PASSPHRASES.testnet; // 'Test SDF Network ; September 2015'
+
+HORIZON_URLS.public;  // 'https://horizon.stellar.org'
+HORIZON_URLS.testnet; // 'https://horizon-testnet.stellar.org'
+```
+
+### Types
+
+```typescript
+type Network = 'public' | 'testnet';
+type MemoType = 'MEMO_TEXT' | 'MEMO_ID' | 'MEMO_HASH' | 'MEMO_RETURN';
+```
+
+## License
+
+MIT