@stellar-snaps/sdk 0.3.1 → 0.3.3

package/README.md

@@ -95,7 +95,29 @@ if (result.successful) {
 }
 ```
 
-### 4. Create Shareable Snaps (Web App API)
+### 4. Payment flow (payment route like the web app)
+
+Implement a **payment route** (e.g. `/s/[id]`) with the same behavior as stellar-snaps.vercel.app: fetch the snap, then run the full pay flow (Freighter connect → build tx → sign → submit) in one call.
+
+```typescript
+import { getSnap, executeSnapPayment, getTransactionUrl } from '@stellar-snaps/sdk';
+
+// On your /s/[id] page: load snap, then on "Pay" click:
+const snap = await getSnap(id, { baseUrl: 'https://your-app.com' });
+const amount = snap.amount ?? userEnteredAmount;
+
+const result = await executeSnapPayment({ snap, amount });
+
+if (result.successful) {
+  const explorerUrl = getTransactionUrl(result.hash, snap.network as 'public' | 'testnet');
+  console.log('Paid! View:', explorerUrl);
+}
+```
+
+- **`getAccountSequence(publicKey, network)`** – Fetches account sequence from Horizon (for building a transaction).
+- **`executeSnapPayment({ snap, amount })`** – Full flow: connect Freighter, build payment tx, sign with Freighter, submit. Same behavior as the web app’s “Pay with Stellar” button. **Browser only** (requires Freighter).
+
+### 5. 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.
 
@@ -134,7 +156,21 @@ const { url } = await createSnap({
 });
 ```
 
-### 5. Host Your Own Snap Endpoints
+**Show the same modal overlay as the web app** (browser only): open the snap URL in a modal so users can pay without leaving your page:
+
+```typescript
+import { createSnap, openSnapModal, closeSnapModal } from '@stellar-snaps/sdk';
+
+const { url } = await createSnap({ creator: 'G...', title: 'Tip', destination: 'G...' });
+openSnapModal(url, {
+  width: 420,
+  height: 560,
+  onClose: () => console.log('Modal closed'),
+});
+// User sees the same payment UI as stellar-snaps.vercel.app/s/xxx in an overlay
+```
+
+### 6. Host Your Own Snap Endpoints
 
 Create a discovery file to enable the browser extension to find your snaps:
 
@@ -152,6 +188,40 @@ const discovery = createDiscoveryFile({
 // Save as: public/.well-known/stellar-snap.json
 ```
 
+### 7. Build your own project (full flow)
+
+Everything in the stellar-snaps web app can be built in **your own project** using only this SDK. Use the same APIs and flows so creators can create snaps, share URLs, and payers can pay from your domain.
+
+**1. Backend (your server or serverless)**
+
+| Endpoint | Purpose | SDK usage |
+|----------|---------|-----------|
+| `POST /api/snaps` | Create snap, return `{ id, ... }` | Store snap in your DB; return `id`. Use `validateSnapInput`, `createSnapObject`, `generateSnapId` from SDK. |
+| `GET /api/snap/[id]` | Get full snap | Return snap from DB. |
+| `GET /api/metadata/[id]` | Snap metadata for extension | Same as above; return flat object: `id`, `title`, `destination`, `amount`, `assetCode`, `assetIssuer`, `memo`, `memoType`, `network`. |
+| `POST /api/build-tx` | Build XDR for extension | `buildPaymentXdrFromPayload(req.body)` → return `{ xdr }`. Extension calls this when user clicks "Pay with Stellar" on your snap links. |
+| `DELETE /api/snaps?id=...&creator=...` | Delete snap | Optional; enforce creator ownership. |
+
+**2. Payment page (e.g. `/s/[id]`)**
+
+- Load snap: `getSnap(id, { baseUrl: 'https://your-app.com' })`.
+- On "Pay" click: `executeSnapPayment({ snap, amount })` (browser only; requires Freighter).
+- Show success: `getTransactionUrl(result.hash, snap.network)`.
+
+**3. Discovery file**
+
+- Host `/.well-known/stellar-snap.json` with rules mapping your snap path to your metadata API, e.g. `pathPattern: "/s/*"`, `apiPath: "/api/metadata/$1"`. Use `createDiscoveryFile` from the SDK.
+
+**4. Extension and registry**
+
+- Add your domain to the Stellar Snaps registry (or the registry your extension uses) so the extension shows snap cards for links to your domain.
+
+**5. Create snap from your app**
+
+- Call `createSnap({ creator, title, destination, ..., baseUrl: 'https://your-app.com' })` from the SDK; use the returned `url` (e.g. `https://your-app.com/s/abc123`) as the shareable link.
+
+End-to-end: **create snap** (SDK + your API) → **share URL** → **payer opens `/s/[id]`** (your payment page using `executeSnapPayment`) or **payer sees link on Twitter** → extension fetches metadata and build-tx from your API → **pay with Stellar**. All of this works in your own project using only the library.
+
 ## API Reference
 
 ### Shareable Snap API (Web App)
@@ -225,6 +295,22 @@ interface Snap {
 }
 ```
 
+#### `openSnapModal(snapUrl, options?)`
+
+Opens a snap URL in a full-screen modal overlay (iframe). Same payment UI as opening the link on the Stellar Snaps web app. **Browser only**; no-op in Node.
+
+```typescript
+interface OpenSnapModalOptions {
+  width?: number;   // Default: 420
+  height?: number;  // Default: 560
+  onClose?: () => void;
+}
+```
+
+#### `closeSnapModal()`
+
+Closes the snap modal if one is open. Safe to call anytime.
+
 ### SEP-0007 URI Functions
 
 #### `createPaymentSnap(options)`
@@ -316,6 +402,42 @@ const xlm = createAsset('XLM');
 const usdc = createAsset('USDC', 'GA5ZS...');
 ```
 
+#### `buildPaymentXdrFromPayload(payload)`
+
+Builds payment XDR from the same payload the browser extension sends to `POST /api/build-tx`. Use in your server handler so the extension can build transactions when users click "Pay with Stellar" on your snap links.
+
+```typescript
+// In your POST /api/build-tx handler:
+const xdr = buildPaymentXdrFromPayload(req.body);
+res.json({ xdr });
+```
+
+Payload: `{ source, sequence, destination, amount, assetCode?, assetIssuer?, memo?, memoType?, network? }`. Returns the transaction XDR string.
+
+### Payment Flow (Web App–Style Pay-with-Snap)
+
+#### `getAccountSequence(publicKey, network)`
+
+Fetches the account's current sequence from Horizon (for building a transaction). Use in browser or Node; requires network access.
+
+```typescript
+const sequence = await getAccountSequence(publicKey, 'testnet');
+```
+
+#### `executeSnapPayment(options)`
+
+Runs the full payment flow for a snap: connect Freighter, build payment transaction, sign with Freighter, submit to the network. Same behavior as the web app's "Pay with Stellar" button on `/s/[id]`. **Browser only** (requires Freighter).
+
+```typescript
+const result = await executeSnapPayment({
+  snap: await getSnap(id, { baseUrl: 'https://your-app.com' }),
+  amount: '10',
+});
+// => { hash: '...', successful: true, ledger?: number }
+```
+
+Use this to implement a payment route (e.g. `/s/[id]`) with the same functionality as stellar-snaps.vercel.app.
+
 ### Freighter Wallet Integration
 
 #### `connectFreighter()`

package/dist/index.d.mts

@@ -102,6 +102,40 @@ declare function deleteSnap(id: string, creator: string, options?: {
     baseUrl?: string;
 }): Promise<void>;
 
+/**
+ * Snap Modal Overlay
+ *
+ * Opens a snap URL (e.g. from createSnap) in a modal overlay so users can pay
+ * without leaving the page. Same payment UI as the web app, loaded in an iframe.
+ * Browser-only; no-op in Node.
+ */
+interface OpenSnapModalOptions {
+    /** Width of the iframe content area (default: 420) */
+    width?: number;
+    /** Height of the iframe (default: 560) */
+    height?: number;
+    /** Called when the user closes the modal */
+    onClose?: () => void;
+}
+/**
+ * Opens a snap URL in a modal overlay (iframe). Same experience as opening
+ * the link on the Stellar Snaps web app—payment form, Freighter, etc.
+ * Use the URL returned from createSnap(), e.g. result.url.
+ *
+ * Browser-only; does nothing in Node.
+ *
+ * @example
+ * ```typescript
+ * const { url } = await createSnap({ ... });
+ * openSnapModal(url, { onClose: () => console.log('Closed') });
+ * ```
+ */
+declare function openSnapModal(snapUrl: string, options?: OpenSnapModalOptions): void;
+/**
+ * Closes the snap modal if one is open. Safe to call anytime.
+ */
+declare function closeSnapModal(): void;
+
 /**
  * Snap ID Generation
  *
@@ -500,6 +534,38 @@ declare function createAsset(code: string, issuer?: string): StellarSdk.Asset;
  * ```
  */
 declare function buildPaymentTransaction(options: BuildPaymentOptions): string;
+/**
+ * Payload shape sent by the browser extension to POST /api/build-tx.
+ * Use this to implement the build-tx endpoint so the extension can build
+ * transactions when users pay from your domain.
+ */
+interface BuildTxPayload {
+    source: string;
+    sequence: string;
+    destination: string;
+    amount: string;
+    assetCode?: string;
+    assetIssuer?: string;
+    memo?: string;
+    memoType?: string;
+    network?: Network;
+}
+/**
+ * Builds payment transaction XDR from the same payload the browser extension
+ * sends to POST /api/build-tx. Use in your server handler so the extension
+ * can build transactions when users click "Pay with Stellar" on your snap links.
+ *
+ * @param payload - Request body: source, sequence, destination, amount, assetCode?, assetIssuer?, memo?, memoType?, network?
+ * @returns Transaction XDR string
+ *
+ * @example
+ * ```typescript
+ * // In your POST /api/build-tx handler:
+ * const xdr = buildPaymentXdrFromPayload(req.body);
+ * res.json({ xdr });
+ * ```
+ */
+declare function buildPaymentXdrFromPayload(payload: BuildTxPayload): string;
 
 /**
  * Result of connecting to Freighter wallet.
@@ -606,6 +672,52 @@ declare function signWithFreighter(xdr: string, network: Network): Promise<strin
  */
 declare function submitTransaction(signedXdr: string, network: Network): Promise<TransactionSubmitResult>;
 
+/**
+ * Payment Flow
+ *
+ * Full "pay with snap" flow matching the web app: connect Freighter,
+ * build payment transaction, sign, submit. Use this to implement a
+ * payment route (e.g. /s/[id]) with the same behavior as stellar-snaps.vercel.app.
+ */
+
+interface ExecuteSnapPaymentOptions {
+    /** Snap from getSnap(id, { baseUrl }) */
+    snap: Snap$1;
+    /** Amount to send (use snap.amount for fixed-amount snaps) */
+    amount: string;
+}
+/**
+ * Fetches the current account sequence from Horizon (for building a transaction).
+ * Use in browser or Node; requires network access.
+ *
+ * @param publicKey - Stellar account public key
+ * @param network - 'public' or 'testnet'
+ * @returns The account's sequence number as string
+ */
+declare function getAccountSequence(publicKey: string, network: Network): Promise<string>;
+/**
+ * Executes the full payment flow for a snap: connect Freighter, build payment tx,
+ * sign with Freighter, submit to the network. Same behavior as the web app's
+ * "Pay with Stellar" button on /s/[id].
+ *
+ * Call this from your payment page when the user clicks Pay. Requires browser
+ * with Freighter installed.
+ *
+ * @param options - { snap, amount }
+ * @returns Transaction result (hash, successful, ledger)
+ *
+ * @example
+ * ```typescript
+ * const snap = await getSnap(id, { baseUrl: 'https://your-app.com' });
+ * const amount = snap.amount ?? userEnteredAmount;
+ * const result = await executeSnapPayment({ snap, amount });
+ * if (result.successful) {
+ *   console.log('Paid! TX:', result.hash);
+ * }
+ * ```
+ */
+declare function executeSnapPayment(options: ExecuteSnapPaymentOptions): Promise<TransactionSubmitResult>;
+
 /**
  * A rule for matching URL paths to API endpoints.
  */
@@ -1179,4 +1291,4 @@ declare class SnapApiError extends StellarSnapError {
     constructor(message: string, statusCode?: number | undefined);
 }
 
-export { type ApiResponse, type BuildPaymentOptions, CACHE_HEADERS, CORS_HEADERS, type CreateDiscoveryFileOptions, type CreateSnapInput, type CreateSnapOptions, type CreateSnapResult, type DiscoveryFile, type DiscoveryRule, type DomainEntry, type DomainStatus, EXPLORER_URLS, type ExplorerType, type FreighterConnectionResult, HORIZON_URLS, InvalidAddressError, InvalidAmountError, InvalidAssetError, InvalidUriError, type MemoType, type MetaTags, NETWORK_PASSPHRASES, type Network, POSTGRES_SCHEMA, type ParsedSnap, type PaymentSnapOptions, type PaymentSnapResult, type RateLimitBucket, type Registry, type ResolvedUrl, SHORTENER_DOMAINS, SQLITE_SCHEMA, type Snap$1 as Snap, SnapApiError, type SnapMetadata, SnapNotFoundError, type Snap as SnapRecord, SnapUnauthorizedError, StellarSnapError, type TransactionSnapOptions, type TransactionSnapResult, type TransactionSubmitResult, type UpdateSnapInput, addDomain, buildPaymentTransaction, buildUrl, connectFreighter, createAsset, createDiscoveryFile, createPaymentSnap, createRateLimiter, createRegistry, createSnap, createSnapObject, createTransactionSnap, deleteSnap, errorResponse, extractDomain, extractPath, extractSnapId, generateJsonLd, generateMetaTags, generateSnapId, getAccountUrl, getAssetUrl, getBlockedDomains, getDomainStatus, getFreighterNetwork, getOperationUrl, getSnap, getTransactionUrl, getVerifiedDomains, isDomainBlocked, isDomainVerified, isFreighterConnected, isShortenerUrl, isValidAmount, isValidAssetCode, isValidSnapId, isValidStellarAddress, listSnaps, matchUrlToRule, metaTagsToHtml, parseAddress, parseQueryParams, parseSnapUri, removeDomain, resolveUrl, resolveUrls, signWithFreighter, submitTransaction, successResponse, validateDiscoveryFile, validateRegistry, validateRequired, validateSnapInput };
+export { type ApiResponse, type BuildPaymentOptions, type BuildTxPayload, CACHE_HEADERS, CORS_HEADERS, type CreateDiscoveryFileOptions, type CreateSnapInput, type CreateSnapOptions, type CreateSnapResult, type DiscoveryFile, type DiscoveryRule, type DomainEntry, type DomainStatus, EXPLORER_URLS, type ExecuteSnapPaymentOptions, type ExplorerType, type FreighterConnectionResult, HORIZON_URLS, InvalidAddressError, InvalidAmountError, InvalidAssetError, InvalidUriError, type MemoType, type MetaTags, NETWORK_PASSPHRASES, type Network, type OpenSnapModalOptions, POSTGRES_SCHEMA, type ParsedSnap, type PaymentSnapOptions, type PaymentSnapResult, type RateLimitBucket, type Registry, type ResolvedUrl, SHORTENER_DOMAINS, SQLITE_SCHEMA, type Snap$1 as Snap, SnapApiError, type SnapMetadata, SnapNotFoundError, type Snap as SnapRecord, SnapUnauthorizedError, StellarSnapError, type TransactionSnapOptions, type TransactionSnapResult, type TransactionSubmitResult, type UpdateSnapInput, addDomain, buildPaymentTransaction, buildPaymentXdrFromPayload, buildUrl, closeSnapModal, connectFreighter, createAsset, createDiscoveryFile, createPaymentSnap, createRateLimiter, createRegistry, createSnap, createSnapObject, createTransactionSnap, deleteSnap, errorResponse, executeSnapPayment, extractDomain, extractPath, extractSnapId, generateJsonLd, generateMetaTags, generateSnapId, getAccountSequence, getAccountUrl, getAssetUrl, getBlockedDomains, getDomainStatus, getFreighterNetwork, getOperationUrl, getSnap, getTransactionUrl, getVerifiedDomains, isDomainBlocked, isDomainVerified, isFreighterConnected, isShortenerUrl, isValidAmount, isValidAssetCode, isValidSnapId, isValidStellarAddress, listSnaps, matchUrlToRule, metaTagsToHtml, openSnapModal, parseAddress, parseQueryParams, parseSnapUri, removeDomain, resolveUrl, resolveUrls, signWithFreighter, submitTransaction, successResponse, validateDiscoveryFile, validateRegistry, validateRequired, validateSnapInput };

package/dist/index.d.ts

@@ -102,6 +102,40 @@ declare function deleteSnap(id: string, creator: string, options?: {
     baseUrl?: string;
 }): Promise<void>;
 
+/**
+ * Snap Modal Overlay
+ *
+ * Opens a snap URL (e.g. from createSnap) in a modal overlay so users can pay
+ * without leaving the page. Same payment UI as the web app, loaded in an iframe.
+ * Browser-only; no-op in Node.
+ */
+interface OpenSnapModalOptions {
+    /** Width of the iframe content area (default: 420) */
+    width?: number;
+    /** Height of the iframe (default: 560) */
+    height?: number;
+    /** Called when the user closes the modal */
+    onClose?: () => void;
+}
+/**
+ * Opens a snap URL in a modal overlay (iframe). Same experience as opening
+ * the link on the Stellar Snaps web app—payment form, Freighter, etc.
+ * Use the URL returned from createSnap(), e.g. result.url.
+ *
+ * Browser-only; does nothing in Node.
+ *
+ * @example
+ * ```typescript
+ * const { url } = await createSnap({ ... });
+ * openSnapModal(url, { onClose: () => console.log('Closed') });
+ * ```
+ */
+declare function openSnapModal(snapUrl: string, options?: OpenSnapModalOptions): void;
+/**
+ * Closes the snap modal if one is open. Safe to call anytime.
+ */
+declare function closeSnapModal(): void;
+
 /**
  * Snap ID Generation
  *
@@ -500,6 +534,38 @@ declare function createAsset(code: string, issuer?: string): StellarSdk.Asset;
  * ```
  */
 declare function buildPaymentTransaction(options: BuildPaymentOptions): string;
+/**
+ * Payload shape sent by the browser extension to POST /api/build-tx.
+ * Use this to implement the build-tx endpoint so the extension can build
+ * transactions when users pay from your domain.
+ */
+interface BuildTxPayload {
+    source: string;
+    sequence: string;
+    destination: string;
+    amount: string;
+    assetCode?: string;
+    assetIssuer?: string;
+    memo?: string;
+    memoType?: string;
+    network?: Network;
+}
+/**
+ * Builds payment transaction XDR from the same payload the browser extension
+ * sends to POST /api/build-tx. Use in your server handler so the extension
+ * can build transactions when users click "Pay with Stellar" on your snap links.
+ *
+ * @param payload - Request body: source, sequence, destination, amount, assetCode?, assetIssuer?, memo?, memoType?, network?
+ * @returns Transaction XDR string
+ *
+ * @example
+ * ```typescript
+ * // In your POST /api/build-tx handler:
+ * const xdr = buildPaymentXdrFromPayload(req.body);
+ * res.json({ xdr });
+ * ```
+ */
+declare function buildPaymentXdrFromPayload(payload: BuildTxPayload): string;
 
 /**
  * Result of connecting to Freighter wallet.
@@ -606,6 +672,52 @@ declare function signWithFreighter(xdr: string, network: Network): Promise<strin
  */
 declare function submitTransaction(signedXdr: string, network: Network): Promise<TransactionSubmitResult>;
 
+/**
+ * Payment Flow
+ *
+ * Full "pay with snap" flow matching the web app: connect Freighter,
+ * build payment transaction, sign, submit. Use this to implement a
+ * payment route (e.g. /s/[id]) with the same behavior as stellar-snaps.vercel.app.
+ */
+
+interface ExecuteSnapPaymentOptions {
+    /** Snap from getSnap(id, { baseUrl }) */
+    snap: Snap$1;
+    /** Amount to send (use snap.amount for fixed-amount snaps) */
+    amount: string;
+}
+/**
+ * Fetches the current account sequence from Horizon (for building a transaction).
+ * Use in browser or Node; requires network access.
+ *
+ * @param publicKey - Stellar account public key
+ * @param network - 'public' or 'testnet'
+ * @returns The account's sequence number as string
+ */
+declare function getAccountSequence(publicKey: string, network: Network): Promise<string>;
+/**
+ * Executes the full payment flow for a snap: connect Freighter, build payment tx,
+ * sign with Freighter, submit to the network. Same behavior as the web app's
+ * "Pay with Stellar" button on /s/[id].
+ *
+ * Call this from your payment page when the user clicks Pay. Requires browser
+ * with Freighter installed.
+ *
+ * @param options - { snap, amount }
+ * @returns Transaction result (hash, successful, ledger)
+ *
+ * @example
+ * ```typescript
+ * const snap = await getSnap(id, { baseUrl: 'https://your-app.com' });
+ * const amount = snap.amount ?? userEnteredAmount;
+ * const result = await executeSnapPayment({ snap, amount });
+ * if (result.successful) {
+ *   console.log('Paid! TX:', result.hash);
+ * }
+ * ```
+ */
+declare function executeSnapPayment(options: ExecuteSnapPaymentOptions): Promise<TransactionSubmitResult>;
+
 /**
  * A rule for matching URL paths to API endpoints.
  */
@@ -1179,4 +1291,4 @@ declare class SnapApiError extends StellarSnapError {
     constructor(message: string, statusCode?: number | undefined);
 }
 
-export { type ApiResponse, type BuildPaymentOptions, CACHE_HEADERS, CORS_HEADERS, type CreateDiscoveryFileOptions, type CreateSnapInput, type CreateSnapOptions, type CreateSnapResult, type DiscoveryFile, type DiscoveryRule, type DomainEntry, type DomainStatus, EXPLORER_URLS, type ExplorerType, type FreighterConnectionResult, HORIZON_URLS, InvalidAddressError, InvalidAmountError, InvalidAssetError, InvalidUriError, type MemoType, type MetaTags, NETWORK_PASSPHRASES, type Network, POSTGRES_SCHEMA, type ParsedSnap, type PaymentSnapOptions, type PaymentSnapResult, type RateLimitBucket, type Registry, type ResolvedUrl, SHORTENER_DOMAINS, SQLITE_SCHEMA, type Snap$1 as Snap, SnapApiError, type SnapMetadata, SnapNotFoundError, type Snap as SnapRecord, SnapUnauthorizedError, StellarSnapError, type TransactionSnapOptions, type TransactionSnapResult, type TransactionSubmitResult, type UpdateSnapInput, addDomain, buildPaymentTransaction, buildUrl, connectFreighter, createAsset, createDiscoveryFile, createPaymentSnap, createRateLimiter, createRegistry, createSnap, createSnapObject, createTransactionSnap, deleteSnap, errorResponse, extractDomain, extractPath, extractSnapId, generateJsonLd, generateMetaTags, generateSnapId, getAccountUrl, getAssetUrl, getBlockedDomains, getDomainStatus, getFreighterNetwork, getOperationUrl, getSnap, getTransactionUrl, getVerifiedDomains, isDomainBlocked, isDomainVerified, isFreighterConnected, isShortenerUrl, isValidAmount, isValidAssetCode, isValidSnapId, isValidStellarAddress, listSnaps, matchUrlToRule, metaTagsToHtml, parseAddress, parseQueryParams, parseSnapUri, removeDomain, resolveUrl, resolveUrls, signWithFreighter, submitTransaction, successResponse, validateDiscoveryFile, validateRegistry, validateRequired, validateSnapInput };
+export { type ApiResponse, type BuildPaymentOptions, type BuildTxPayload, CACHE_HEADERS, CORS_HEADERS, type CreateDiscoveryFileOptions, type CreateSnapInput, type CreateSnapOptions, type CreateSnapResult, type DiscoveryFile, type DiscoveryRule, type DomainEntry, type DomainStatus, EXPLORER_URLS, type ExecuteSnapPaymentOptions, type ExplorerType, type FreighterConnectionResult, HORIZON_URLS, InvalidAddressError, InvalidAmountError, InvalidAssetError, InvalidUriError, type MemoType, type MetaTags, NETWORK_PASSPHRASES, type Network, type OpenSnapModalOptions, POSTGRES_SCHEMA, type ParsedSnap, type PaymentSnapOptions, type PaymentSnapResult, type RateLimitBucket, type Registry, type ResolvedUrl, SHORTENER_DOMAINS, SQLITE_SCHEMA, type Snap$1 as Snap, SnapApiError, type SnapMetadata, SnapNotFoundError, type Snap as SnapRecord, SnapUnauthorizedError, StellarSnapError, type TransactionSnapOptions, type TransactionSnapResult, type TransactionSubmitResult, type UpdateSnapInput, addDomain, buildPaymentTransaction, buildPaymentXdrFromPayload, buildUrl, closeSnapModal, connectFreighter, createAsset, createDiscoveryFile, createPaymentSnap, createRateLimiter, createRegistry, createSnap, createSnapObject, createTransactionSnap, deleteSnap, errorResponse, executeSnapPayment, extractDomain, extractPath, extractSnapId, generateJsonLd, generateMetaTags, generateSnapId, getAccountSequence, getAccountUrl, getAssetUrl, getBlockedDomains, getDomainStatus, getFreighterNetwork, getOperationUrl, getSnap, getTransactionUrl, getVerifiedDomains, isDomainBlocked, isDomainVerified, isFreighterConnected, isShortenerUrl, isValidAmount, isValidAssetCode, isValidSnapId, isValidStellarAddress, listSnaps, matchUrlToRule, metaTagsToHtml, openSnapModal, parseAddress, parseQueryParams, parseSnapUri, removeDomain, resolveUrl, resolveUrls, signWithFreighter, submitTransaction, successResponse, validateDiscoveryFile, validateRegistry, validateRequired, validateSnapInput };

package/dist/index.js

@@ -176,6 +176,74 @@ async function deleteSnap(id, creator, options = {}) {
   }
 }
 
+// src/snap-modal.ts
+var MODAL_ID = "stellar-snap-modal";
+var IFRAME_ID = "stellar-snap-modal-iframe";
+function isBrowser() {
+  return typeof document !== "undefined" && typeof window !== "undefined";
+}
+function openSnapModal(snapUrl, options = {}) {
+  if (!isBrowser()) return;
+  closeSnapModal();
+  const { width = 420, height = 560, onClose } = options;
+  const overlay = document.createElement("div");
+  overlay.id = MODAL_ID;
+  overlay.setAttribute("role", "dialog");
+  overlay.setAttribute("aria-modal", "true");
+  overlay.setAttribute("aria-label", "Stellar Snap payment");
+  const styles = {
+    position: "fixed",
+    inset: "0",
+    zIndex: "2147483647",
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    backgroundColor: "rgba(0, 0, 0, 0.6)",
+    padding: "20px",
+    boxSizing: "border-box"
+  };
+  Object.assign(overlay.style, styles);
+  const container = document.createElement("div");
+  container.style.position = "relative";
+  container.style.width = `${width}px`;
+  container.style.maxWidth = "100%";
+  container.style.height = `${height}px`;
+  container.style.maxHeight = "90vh";
+  container.style.backgroundColor = "rgb(23, 23, 23)";
+  container.style.borderRadius = "16px";
+  container.style.boxShadow = "0 25px 50px -12px rgba(0, 0, 0, 0.5)";
+  container.style.overflow = "hidden";
+  const closeBtn = document.createElement("button");
+  closeBtn.type = "button";
+  closeBtn.setAttribute("aria-label", "Close");
+  closeBtn.textContent = "\xD7";
+  closeBtn.style.cssText = "position:absolute;top:12px;right:12px;z-index:10;width:32px;height:32px;border:none;border-radius:8px;background:rgba(255,255,255,0.1);color:#e5e5e5;font-size:24px;line-height:1;cursor:pointer;display:flex;align-items:center;justify-content:center;";
+  closeBtn.onclick = () => {
+    closeSnapModal();
+    onClose?.();
+  };
+  const iframe = document.createElement("iframe");
+  iframe.id = IFRAME_ID;
+  iframe.src = snapUrl;
+  iframe.title = "Stellar Snap payment";
+  iframe.style.cssText = "width:100%;height:100%;border:none;border-radius:16px;";
+  container.appendChild(closeBtn);
+  container.appendChild(iframe);
+  overlay.appendChild(container);
+  overlay.addEventListener("click", (e) => {
+    if (e.target === overlay) {
+      closeSnapModal();
+      onClose?.();
+    }
+  });
+  document.body.appendChild(overlay);
+}
+function closeSnapModal() {
+  if (!isBrowser()) return;
+  const el = document.getElementById(MODAL_ID);
+  if (el) el.remove();
+}
+
 // src/snap-id.ts
 var ALPHABET = "useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict";
 function generateSnapId(length = 8) {
@@ -545,6 +613,21 @@ function buildPaymentTransaction(options) {
   const transaction = builder.build();
   return transaction.toXDR();
 }
+function buildPaymentXdrFromPayload(payload) {
+  const network = payload.network === "public" ? "public" : "testnet";
+  return buildPaymentTransaction({
+    source: payload.source,
+    sequence: payload.sequence,
+    destination: payload.destination,
+    amount: payload.amount,
+    asset: payload.assetCode && payload.assetCode !== "XLM" && payload.assetIssuer ? { code: payload.assetCode, issuer: payload.assetIssuer } : void 0,
+    memo: payload.memo != null ? {
+      type: payload.memoType ?? "MEMO_TEXT",
+      value: payload.memo
+    } : void 0,
+    network
+  });
+}
 async function isFreighterConnected() {
   try {
     const connected = await freighterApi.isConnected();
@@ -661,6 +744,47 @@ async function submitTransaction(signedXdr, network) {
   }
 }
 
+// src/payment-flow.ts
+async function getAccountSequence(publicKey, network) {
+  const horizonUrl = HORIZON_URLS[network];
+  const response = await fetch(`${horizonUrl}/accounts/${publicKey}`);
+  if (!response.ok) {
+    if (response.status === 404) {
+      throw new Error("Account not found. Fund the account first.");
+    }
+    throw new Error(`Failed to load account: ${response.status}`);
+  }
+  const data = await response.json();
+  return String(data.sequence);
+}
+async function executeSnapPayment(options) {
+  const { snap, amount } = options;
+  if (!amount || Number(amount) <= 0) {
+    throw new Error("Please enter a valid amount");
+  }
+  const network = snap.network === "public" ? "public" : "testnet";
+  const { publicKey } = await connectFreighter();
+  const currentNetwork = await getFreighterNetwork();
+  if (currentNetwork !== network) {
+    throw new Error(`Please switch Freighter to ${network}. Currently on ${currentNetwork}.`);
+  }
+  const sequence = await getAccountSequence(publicKey, network);
+  const xdr = buildPaymentTransaction({
+    source: publicKey,
+    sequence,
+    destination: snap.destination,
+    amount,
+    asset: snap.assetCode && snap.assetCode !== "XLM" && snap.assetIssuer ? { code: snap.assetCode, issuer: snap.assetIssuer } : void 0,
+    memo: snap.memo ? {
+      type: snap.memoType ?? "MEMO_TEXT",
+      value: snap.memo
+    } : void 0,
+    network
+  });
+  const signedXdr = await signWithFreighter(xdr, network);
+  return submitTransaction(signedXdr, network);
+}
+
 // src/discovery.ts
 function createDiscoveryFile(options) {
   const { name, description, icon, rules } = options;
@@ -1204,7 +1328,9 @@ exports.SnapUnauthorizedError = SnapUnauthorizedError;
 exports.StellarSnapError = StellarSnapError;
 exports.addDomain = addDomain;
 exports.buildPaymentTransaction = buildPaymentTransaction;
+exports.buildPaymentXdrFromPayload = buildPaymentXdrFromPayload;
 exports.buildUrl = buildUrl;
+exports.closeSnapModal = closeSnapModal;
 exports.connectFreighter = connectFreighter;
 exports.createAsset = createAsset;
 exports.createDiscoveryFile = createDiscoveryFile;
@@ -1216,12 +1342,14 @@ exports.createSnapObject = createSnapObject;
 exports.createTransactionSnap = createTransactionSnap;
 exports.deleteSnap = deleteSnap;
 exports.errorResponse = errorResponse;
+exports.executeSnapPayment = executeSnapPayment;
 exports.extractDomain = extractDomain;
 exports.extractPath = extractPath;
 exports.extractSnapId = extractSnapId;
 exports.generateJsonLd = generateJsonLd;
 exports.generateMetaTags = generateMetaTags;
 exports.generateSnapId = generateSnapId;
+exports.getAccountSequence = getAccountSequence;
 exports.getAccountUrl = getAccountUrl;
 exports.getAssetUrl = getAssetUrl;
 exports.getBlockedDomains = getBlockedDomains;
@@ -1242,6 +1370,7 @@ exports.isValidStellarAddress = isValidStellarAddress;
 exports.listSnaps = listSnaps;
 exports.matchUrlToRule = matchUrlToRule;
 exports.metaTagsToHtml = metaTagsToHtml;
+exports.openSnapModal = openSnapModal;
 exports.parseAddress = parseAddress;
 exports.parseQueryParams = parseQueryParams;
 exports.parseSnapUri = parseSnapUri;