@stellar-snaps/sdk 0.2.0 → 0.3.1

package/README.md

@@ -14,6 +14,22 @@ npm install @stellar-snaps/sdk
 pnpm add @stellar-snaps/sdk
 ```
 
+**Peer dependencies** (install if you use transaction building or Freighter):  
+`@stellar/freighter-api`, `@stellar/stellar-sdk`
+
+## How it works
+
+- **Shareable Snap API** (`createSnap`, `getSnap`, `listSnaps`, `deleteSnap`)  
+  Calls the Stellar Snaps web app at `https://stellar-snaps.vercel.app` by default. Snaps are stored there; you get back shareable URLs (e.g. `https://stellar-snaps.vercel.app/s/abc123`). Works in **Node.js** and **browser** (CORS is enabled on the API). Use `baseUrl` to point at your own deployment.
+
+- **SEP-0007 URIs** (`createPaymentSnap`, `createTransactionSnap`, `parseSnapUri`)  
+  Pure logic, no network. Build or parse `web+stellar:...` payment/transaction links.
+
+- **Transactions & Freighter** (`buildPaymentTransaction`, `signWithFreighter`, `submitTransaction`, etc.)  
+  Run in a **browser** with the [Freighter](https://www.freighter.app/) extension installed. Uses `@stellar/freighter-api` and `@stellar/stellar-sdk`.
+
+So: install the package, use the Shareable Snap API from any environment; use Freighter-related APIs only in a browser with Freighter installed.
+
 ## Quick Start
 
 ### 1. Create a Payment Link
@@ -79,7 +95,46 @@ if (result.successful) {
 }
 ```
 
-### 4. Host Your Own Snap Endpoints
+### 4. Create Shareable Snaps (Web App API)
+
+Create, fetch, list, and delete database-backed snaps—same behavior as the web dashboard. Uses `https://stellar-snaps.vercel.app` by default.
+
+```typescript
+import { createSnap, getSnap, listSnaps, deleteSnap } from '@stellar-snaps/sdk';
+
+// Create a snap (stores on server, returns shareable URL)
+const { url, snap } = await createSnap({
+  creator: 'GCNZMNUTQ5UMQ5QL0FUAW3CUADWB...',
+  title: 'Buy me a coffee',
+  destination: 'GCNZMNUTQ5UMQ5QL0FUAW3CUADWB...',
+  amount: '5',
+  network: 'testnet',
+});
+console.log(url);
+// => https://stellar-snaps.vercel.app/s/u8oYHLhl
+
+// Fetch a snap by ID
+const fetchedSnap = await getSnap('u8oYHLhl');
+
+// List all snaps for a creator
+const snaps = await listSnaps('GCNZMNUTQ5UMQ5QL0FUAW3CUADWB...');
+
+// Delete a snap (requires creator address)
+await deleteSnap('u8oYHLhl', 'GCNZMNUTQ5UMQ5QL0FUAW3CUADWB...');
+```
+
+Use `baseUrl` to point at your own Stellar Snaps instance:
+
+```typescript
+const { url } = await createSnap({
+  creator: 'G...',
+  title: 'Test',
+  destination: 'G...',
+  baseUrl: 'https://your-stellar-snaps.vercel.app',
+});
+```
+
+### 5. Host Your Own Snap Endpoints
 
 Create a discovery file to enable the browser extension to find your snaps:
 
@@ -99,6 +154,77 @@ const discovery = createDiscoveryFile({
 
 ## API Reference
 
+### Shareable Snap API (Web App)
+
+These functions mirror the Stellar Snaps web app API. Use them to create and manage snaps that are stored on a server and get shareable URLs.
+
+#### `createSnap(options)`
+
+Creates a snap on the server and returns the shareable URL.
+
+```typescript
+interface CreateSnapOptions {
+  creator: string;              // Creator's Stellar address (required)
+  title: string;                // Display title (required)
+  destination: string;          // Payment destination (required)
+  description?: string;
+  amount?: string;              // Omit for open amount
+  assetCode?: string;           // Default: 'XLM'
+  assetIssuer?: string;         // Required for non-XLM
+  memo?: string;
+  memoType?: MemoType;
+  network?: 'public' | 'testnet'; // Default: 'testnet'
+  imageUrl?: string;
+  baseUrl?: string;             // Default: 'https://stellar-snaps.vercel.app'
+}
+
+interface CreateSnapResult {
+  id: string;
+  url: string;                  // Full shareable URL
+  snap: Snap;
+}
+```
+
+#### `getSnap(id, options?)`
+
+Fetches a snap by ID. Uses `GET /api/snap/[id]`.
+
+- **Throws** `SnapNotFoundError` if the snap does not exist.
+- **Throws** `SnapApiError` on other API errors.
+
+#### `listSnaps(creator, options?)`
+
+Lists all snaps for a creator. Uses `GET /api/snaps?creator=...`.
+
+#### `deleteSnap(id, creator, options?)`
+
+Deletes a snap. Requires the creator's address (ownership). Uses `DELETE /api/snaps?id=...&creator=...`.
+
+- **Throws** `SnapNotFoundError` if the snap does not exist.
+- **Throws** `SnapUnauthorizedError` if the creator does not own the snap.
+- **Throws** `SnapApiError` on other API errors.
+
+#### `Snap` type
+
+```typescript
+interface Snap {
+  id: string;
+  creator?: string;             // Omitted in GET /api/snap/[id] response
+  title: string;
+  description?: string | null;
+  destination: string;
+  amount?: string | null;
+  assetCode: string;
+  assetIssuer?: string | null;
+  memo?: string | null;
+  memoType?: string;
+  network: string;
+  imageUrl?: string | null;
+  createdAt?: string;
+  updatedAt?: string;
+}
+```
+
 ### SEP-0007 URI Functions
 
 #### `createPaymentSnap(options)`
@@ -260,6 +386,9 @@ All errors extend `StellarSnapError` with a `code` property for programmatic han
 - `InvalidAmountError` - Invalid amount
 - `InvalidAssetError` - Invalid asset configuration
 - `InvalidUriError` - Invalid SEP-0007 URI
+- `SnapNotFoundError` - Snap not found (404 from API)
+- `SnapUnauthorizedError` - Not authorized to perform action (e.g. delete another user's snap)
+- `SnapApiError` - Stellar Snaps API returned an error (includes optional `statusCode`)
 
 ```typescript
 try {
@@ -269,6 +398,14 @@ try {
     console.log(error.code); // 'INVALID_ADDRESS'
   }
 }
+
+try {
+  const snap = await getSnap('missing-id');
+} catch (error) {
+  if (error instanceof SnapNotFoundError) {
+    console.log(error.code); // 'SNAP_NOT_FOUND'
+  }
+}
 ```
 
 ### Constants