@stellar-snaps/sdk 0.3.1 → 0.3.2

package/README.md

@@ -134,6 +134,20 @@ const { url } = await createSnap({
 });
 ```
 
+**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
+```
+
 ### 5. Host Your Own Snap Endpoints
 
 Create a discovery file to enable the browser extension to find your snaps:
@@ -225,6 +239,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)`

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
  *
@@ -1179,4 +1213,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, 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, 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, buildUrl, closeSnapModal, 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, 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
  *
@@ -1179,4 +1213,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, 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, 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, buildUrl, closeSnapModal, 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, 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) {
@@ -1205,6 +1273,7 @@ exports.StellarSnapError = StellarSnapError;
 exports.addDomain = addDomain;
 exports.buildPaymentTransaction = buildPaymentTransaction;
 exports.buildUrl = buildUrl;
+exports.closeSnapModal = closeSnapModal;
 exports.connectFreighter = connectFreighter;
 exports.createAsset = createAsset;
 exports.createDiscoveryFile = createDiscoveryFile;
@@ -1242,6 +1311,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;