@stellar-snaps/sdk 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -112,22 +112,45 @@ declare function deleteSnap(id: string, options?: {
     serverUrl?: string;
 }): Promise<void>;
 
-interface PaymentSnapOptions {
-    destination: string;
-    amount?: string;
-    assetCode?: string;
-    assetIssuer?: string;
-    memo?: string;
-    memoType?: 'MEMO_TEXT' | 'MEMO_ID' | 'MEMO_HASH' | 'MEMO_RETURN';
-    message?: string;
-    network?: 'public' | 'testnet';
-    callback?: string;
-}
-interface PaymentSnapResult {
-    uri: string;
-    params: Record<string, string>;
-}
-declare function createPaymentSnap(options: PaymentSnapOptions): PaymentSnapResult;
+/**
+ * Snap ID Generation
+ *
+ * Generates unique, URL-safe IDs for snaps.
+ */
+/**
+ * Generates a random snap ID.
+ *
+ * Uses a URL-safe alphabet similar to nanoid.
+ * Default length is 8 characters (similar to YouTube video IDs).
+ *
+ * @example
+ * ```typescript
+ * const id = generateSnapId(); // 'nk1VNcxo'
+ * const longId = generateSnapId(12); // 'nk1VNcxo4Abc'
+ * ```
+ */
+declare function generateSnapId(length?: number): string;
+/**
+ * Validates a snap ID format.
+ *
+ * @example
+ * ```typescript
+ * isValidSnapId('nk1VNcxo'); // true
+ * isValidSnapId(''); // false
+ * isValidSnapId('has spaces'); // false
+ * ```
+ */
+declare function isValidSnapId(id: string): boolean;
+/**
+ * Extracts a snap ID from a URL.
+ *
+ * @example
+ * ```typescript
+ * extractSnapId('https://stellarsnaps.com/s/nk1VNcxo'); // 'nk1VNcxo'
+ * extractSnapId('https://example.com/pay/abc123'); // 'abc123'
+ * ```
+ */
+declare function extractSnapId(url: string, patterns?: string[]): string | null;
 
 /**
  * Stellar network passphrases used for transaction signing.
@@ -160,6 +183,132 @@ type Network = 'public' | 'testnet';
  */
 type MemoType = 'MEMO_TEXT' | 'MEMO_ID' | 'MEMO_HASH' | 'MEMO_RETURN';
 
+/**
+ * Database Schema Types
+ *
+ * Type definitions for snap storage. These types can be used
+ * with any database (PostgreSQL, SQLite, MongoDB, etc.).
+ */
+
+/**
+ * Snap record as stored in the database.
+ */
+interface Snap {
+    /** Unique snap ID (e.g., 'nk1VNcxo') */
+    id: string;
+    /** Creator's Stellar address */
+    creator: string;
+    /** Display title */
+    title: string;
+    /** Optional description */
+    description?: string | null;
+    /** Optional image URL */
+    imageUrl?: string | null;
+    /** Payment destination address */
+    destination: string;
+    /** Asset code (default: 'XLM') */
+    assetCode: string;
+    /** Asset issuer (required for non-XLM) */
+    assetIssuer?: string | null;
+    /** Fixed amount (null = payer chooses) */
+    amount?: string | null;
+    /** Transaction memo */
+    memo?: string | null;
+    /** Memo type */
+    memoType: MemoType | string;
+    /** Network ('public' or 'testnet') */
+    network: Network | string;
+    /** Creation timestamp */
+    createdAt: Date | string;
+    /** Last update timestamp */
+    updatedAt: Date | string;
+}
+/**
+ * Input for creating a new snap.
+ */
+interface CreateSnapInput {
+    /** Creator's Stellar address (required) */
+    creator: string;
+    /** Display title (required) */
+    title: string;
+    /** Payment destination address (required) */
+    destination: string;
+    /** Optional description */
+    description?: string;
+    /** Optional image URL */
+    imageUrl?: string;
+    /** Asset code (default: 'XLM') */
+    assetCode?: string;
+    /** Asset issuer (required for non-XLM) */
+    assetIssuer?: string;
+    /** Fixed amount */
+    amount?: string;
+    /** Transaction memo */
+    memo?: string;
+    /** Memo type (default: 'MEMO_TEXT') */
+    memoType?: MemoType;
+    /** Network (default: 'testnet') */
+    network?: Network;
+}
+/**
+ * Input for updating a snap.
+ */
+interface UpdateSnapInput {
+    /** Display title */
+    title?: string;
+    /** Description */
+    description?: string | null;
+    /** Image URL */
+    imageUrl?: string | null;
+    /** Payment amount */
+    amount?: string | null;
+    /** Transaction memo */
+    memo?: string | null;
+    /** Memo type */
+    memoType?: MemoType;
+}
+/**
+ * Validates snap input data.
+ *
+ * @throws Error if validation fails
+ */
+declare function validateSnapInput(input: CreateSnapInput): void;
+/**
+ * Creates a snap object with defaults.
+ */
+declare function createSnapObject(id: string, input: CreateSnapInput): Snap;
+/**
+ * SQL schema for PostgreSQL.
+ *
+ * @example
+ * ```typescript
+ * // Run this SQL to create the snaps table:
+ * await db.execute(POSTGRES_SCHEMA);
+ * ```
+ */
+declare const POSTGRES_SCHEMA = "\nCREATE TABLE IF NOT EXISTS snaps (\n  id TEXT PRIMARY KEY,\n  creator TEXT NOT NULL,\n  title TEXT NOT NULL,\n  description TEXT,\n  image_url TEXT,\n  destination TEXT NOT NULL,\n  asset_code TEXT NOT NULL DEFAULT 'XLM',\n  asset_issuer TEXT,\n  amount TEXT,\n  memo TEXT,\n  memo_type TEXT NOT NULL DEFAULT 'MEMO_TEXT',\n  network TEXT NOT NULL DEFAULT 'testnet',\n  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),\n  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()\n);\n\nCREATE INDEX IF NOT EXISTS idx_snaps_creator ON snaps(creator);\nCREATE INDEX IF NOT EXISTS idx_snaps_destination ON snaps(destination);\n";
+/**
+ * SQL schema for SQLite.
+ */
+declare const SQLITE_SCHEMA = "\nCREATE TABLE IF NOT EXISTS snaps (\n  id TEXT PRIMARY KEY,\n  creator TEXT NOT NULL,\n  title TEXT NOT NULL,\n  description TEXT,\n  image_url TEXT,\n  destination TEXT NOT NULL,\n  asset_code TEXT NOT NULL DEFAULT 'XLM',\n  asset_issuer TEXT,\n  amount TEXT,\n  memo TEXT,\n  memo_type TEXT NOT NULL DEFAULT 'MEMO_TEXT',\n  network TEXT NOT NULL DEFAULT 'testnet',\n  created_at TEXT DEFAULT (datetime('now')),\n  updated_at TEXT DEFAULT (datetime('now'))\n);\n\nCREATE INDEX IF NOT EXISTS idx_snaps_creator ON snaps(creator);\nCREATE INDEX IF NOT EXISTS idx_snaps_destination ON snaps(destination);\n";
+
+interface PaymentSnapOptions {
+    destination: string;
+    amount?: string;
+    assetCode?: string;
+    assetIssuer?: string;
+    memo?: string;
+    memoType?: 'MEMO_TEXT' | 'MEMO_ID' | 'MEMO_HASH' | 'MEMO_RETURN';
+    message?: string;
+    network?: 'public' | 'testnet';
+    callback?: string;
+}
+interface PaymentSnapResult {
+    uri: string;
+    params: Record<string, string>;
+}
+declare function createPaymentSnap(options: PaymentSnapOptions): PaymentSnapResult;
+
 /**
  * Options for creating a transaction snap URI.
  * Used for advanced use cases where you need to sign arbitrary transactions,
@@ -594,6 +743,397 @@ declare function validateDiscoveryFile(file: unknown): file is DiscoveryFile;
  */
 declare function matchUrlToRule(pathname: string, rules: DiscoveryRule[]): string | null;
 
+/**
+ * URL Resolution Utilities
+ *
+ * Handles shortened URL detection and resolution for snap links.
+ */
+/** List of known URL shortener domains */
+declare const SHORTENER_DOMAINS: readonly ["t.co", "bit.ly", "goo.gl", "tinyurl.com", "ow.ly", "is.gd", "buff.ly", "adf.ly", "bit.do", "mcaf.ee", "su.pr", "twit.ac", "tiny.cc", "lnkd.in", "db.tt", "qr.ae", "cur.lv", "ity.im", "q.gs", "po.st", "bc.vc", "u.to", "j.mp", "buzurl.com", "cutt.us", "u.bb", "yourls.org", "x.co", "prettylinkpro.com", "viralurl.com", "twitthis.com", "shorturl.at", "rb.gy", "shorturl.com"];
+interface ResolvedUrl {
+    /** The final resolved URL after following redirects */
+    url: string;
+    /** The domain of the resolved URL */
+    domain: string;
+    /** The original URL before resolution */
+    originalUrl: string;
+    /** Whether the URL was shortened */
+    wasShortened: boolean;
+}
+/**
+ * Checks if a URL is from a known URL shortener.
+ *
+ * @example
+ * ```typescript
+ * isShortenerUrl('https://t.co/abc123'); // true
+ * isShortenerUrl('https://stellarsnaps.com/s/abc'); // false
+ * ```
+ */
+declare function isShortenerUrl(url: string): boolean;
+/**
+ * Extracts the domain from a URL.
+ *
+ * @example
+ * ```typescript
+ * extractDomain('https://stellarsnaps.com/s/abc123'); // 'stellarsnaps.com'
+ * ```
+ */
+declare function extractDomain(url: string): string;
+/**
+ * Extracts the path from a URL.
+ *
+ * @example
+ * ```typescript
+ * extractPath('https://stellarsnaps.com/s/abc123'); // '/s/abc123'
+ * ```
+ */
+declare function extractPath(url: string): string;
+/**
+ * Resolves a shortened URL by following redirects.
+ * This is a server-side function that requires fetch with redirect following.
+ *
+ * @example
+ * ```typescript
+ * const resolved = await resolveUrl('https://t.co/abc123');
+ * console.log(resolved.url); // 'https://stellarsnaps.com/s/xyz789'
+ * ```
+ */
+declare function resolveUrl(url: string): Promise<ResolvedUrl>;
+/**
+ * Batch resolve multiple URLs.
+ *
+ * @example
+ * ```typescript
+ * const urls = ['https://t.co/a', 'https://bit.ly/b'];
+ * const resolved = await resolveUrls(urls);
+ * ```
+ */
+declare function resolveUrls(urls: string[]): Promise<ResolvedUrl[]>;
+
+/**
+ * Domain Registry
+ *
+ * Manages trusted/verified domains for snap hosting.
+ */
+type DomainStatus = 'verified' | 'unverified' | 'blocked';
+interface DomainEntry {
+    /** The domain name */
+    domain: string;
+    /** Trust status */
+    status: DomainStatus;
+    /** Optional display name */
+    name?: string;
+    /** Optional description */
+    description?: string;
+    /** When the domain was added */
+    addedAt?: string;
+    /** When the domain was last verified */
+    verifiedAt?: string;
+}
+interface Registry {
+    /** List of all domain entries */
+    domains: DomainEntry[];
+    /** When the registry was last updated */
+    updatedAt: string;
+    /** Registry version */
+    version: string;
+}
+/**
+ * Creates a new registry.
+ *
+ * @example
+ * ```typescript
+ * const registry = createRegistry([
+ *   { domain: 'stellarsnaps.com', status: 'verified', name: 'Stellar Snaps' },
+ *   { domain: 'example.com', status: 'unverified' },
+ * ]);
+ * ```
+ */
+declare function createRegistry(domains?: DomainEntry[]): Registry;
+/**
+ * Adds a domain to the registry.
+ */
+declare function addDomain(registry: Registry, entry: DomainEntry): Registry;
+/**
+ * Removes a domain from the registry.
+ */
+declare function removeDomain(registry: Registry, domain: string): Registry;
+/**
+ * Gets the status of a domain.
+ *
+ * @example
+ * ```typescript
+ * const status = getDomainStatus(registry, 'stellarsnaps.com');
+ * // { domain: 'stellarsnaps.com', status: 'verified', ... }
+ * ```
+ */
+declare function getDomainStatus(registry: Registry, domain: string): DomainEntry | null;
+/**
+ * Checks if a domain is verified.
+ */
+declare function isDomainVerified(registry: Registry, domain: string): boolean;
+/**
+ * Checks if a domain is blocked.
+ */
+declare function isDomainBlocked(registry: Registry, domain: string): boolean;
+/**
+ * Gets all verified domains.
+ */
+declare function getVerifiedDomains(registry: Registry): DomainEntry[];
+/**
+ * Gets all blocked domains.
+ */
+declare function getBlockedDomains(registry: Registry): DomainEntry[];
+/**
+ * Validates a registry object.
+ */
+declare function validateRegistry(registry: unknown): registry is Registry;
+
+/**
+ * Blockchain Explorer Utilities
+ *
+ * Generate links to Stellar blockchain explorers.
+ */
+
+/** Supported explorer types */
+type ExplorerType = 'stellar.expert' | 'stellarchain' | 'horizon';
+/** Explorer base URLs */
+declare const EXPLORER_URLS: Record<ExplorerType, Record<Network, string>>;
+/**
+ * Generates a transaction URL for a blockchain explorer.
+ *
+ * @example
+ * ```typescript
+ * getTransactionUrl('abc123...', 'testnet');
+ * // 'https://stellar.expert/explorer/testnet/tx/abc123...'
+ *
+ * getTransactionUrl('abc123...', 'public', 'stellarchain');
+ * // 'https://stellarchain.io/transactions/abc123...'
+ * ```
+ */
+declare function getTransactionUrl(hash: string, network?: Network, explorer?: ExplorerType): string;
+/**
+ * Generates an account URL for a blockchain explorer.
+ *
+ * @example
+ * ```typescript
+ * getAccountUrl('GABC...', 'testnet');
+ * // 'https://stellar.expert/explorer/testnet/account/GABC...'
+ * ```
+ */
+declare function getAccountUrl(address: string, network?: Network, explorer?: ExplorerType): string;
+/**
+ * Generates an asset URL for a blockchain explorer.
+ *
+ * @example
+ * ```typescript
+ * getAssetUrl('USDC', 'GCNY...', 'public');
+ * // 'https://stellar.expert/explorer/public/asset/USDC-GCNY...'
+ * ```
+ */
+declare function getAssetUrl(code: string, issuer: string, network?: Network, explorer?: ExplorerType): string;
+/**
+ * Generates an operation URL for a blockchain explorer.
+ */
+declare function getOperationUrl(operationId: string, network?: Network, explorer?: ExplorerType): string;
+
+/**
+ * Meta Tag Generation
+ *
+ * Generate OpenGraph and Twitter meta tags for snap pages.
+ */
+interface SnapMetadata {
+    /** Snap title */
+    title: string;
+    /** Snap description */
+    description?: string;
+    /** Image URL */
+    imageUrl?: string;
+    /** Payment amount */
+    amount?: string;
+    /** Asset code */
+    assetCode?: string;
+    /** Full snap URL */
+    url: string;
+    /** Site name */
+    siteName?: string;
+}
+interface MetaTags {
+    /** OpenGraph tags */
+    og: Record<string, string>;
+    /** Twitter card tags */
+    twitter: Record<string, string>;
+    /** Standard meta tags */
+    standard: Record<string, string>;
+}
+/**
+ * Generates meta tags for a snap page.
+ *
+ * @example
+ * ```typescript
+ * const tags = generateMetaTags({
+ *   title: 'Pay for Coffee',
+ *   description: 'Send 5 XLM for coffee',
+ *   amount: '5',
+ *   assetCode: 'XLM',
+ *   url: 'https://stellarsnaps.com/s/abc123',
+ * });
+ *
+ * // Use in Next.js metadata:
+ * export const metadata = {
+ *   title: tags.standard.title,
+ *   openGraph: tags.og,
+ *   twitter: tags.twitter,
+ * };
+ * ```
+ */
+declare function generateMetaTags(metadata: SnapMetadata): MetaTags;
+/**
+ * Converts meta tags to HTML string.
+ *
+ * @example
+ * ```typescript
+ * const html = metaTagsToHtml(tags);
+ * // <meta property="og:title" content="Pay for Coffee" />
+ * // <meta property="og:description" content="..." />
+ * // ...
+ * ```
+ */
+declare function metaTagsToHtml(tags: MetaTags): string;
+/**
+ * Generates JSON-LD structured data for a snap.
+ *
+ * @example
+ * ```typescript
+ * const jsonLd = generateJsonLd({
+ *   title: 'Pay for Coffee',
+ *   amount: '5',
+ *   assetCode: 'XLM',
+ *   url: 'https://stellarsnaps.com/s/abc123',
+ * });
+ * ```
+ */
+declare function generateJsonLd(metadata: SnapMetadata): object;
+
+/**
+ * Server Utilities
+ *
+ * Helper functions for building Stellar Snaps API endpoints.
+ */
+/**
+ * Standard CORS headers for API responses.
+ */
+declare const CORS_HEADERS: {
+    readonly 'Access-Control-Allow-Origin': "*";
+    readonly 'Access-Control-Allow-Methods': "GET, POST, PUT, DELETE, OPTIONS";
+    readonly 'Access-Control-Allow-Headers': "Content-Type, Authorization";
+    readonly 'Access-Control-Max-Age': "86400";
+};
+/**
+ * Cache headers for different response types.
+ */
+declare const CACHE_HEADERS: {
+    /** No caching */
+    readonly none: {
+        readonly 'Cache-Control': "no-store, no-cache, must-revalidate";
+    };
+    /** Short cache (1 minute) */
+    readonly short: {
+        readonly 'Cache-Control': "public, max-age=60, stale-while-revalidate=30";
+    };
+    /** Medium cache (5 minutes) */
+    readonly medium: {
+        readonly 'Cache-Control': "public, max-age=300, stale-while-revalidate=60";
+    };
+    /** Long cache (1 hour) */
+    readonly long: {
+        readonly 'Cache-Control': "public, max-age=3600, stale-while-revalidate=300";
+    };
+    /** Immutable (1 year) */
+    readonly immutable: {
+        readonly 'Cache-Control': "public, max-age=31536000, immutable";
+    };
+};
+interface ApiResponse<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    code?: string;
+}
+/**
+ * Creates a success API response.
+ */
+declare function successResponse<T>(data: T): ApiResponse<T>;
+/**
+ * Creates an error API response.
+ */
+declare function errorResponse(message: string, code?: string): ApiResponse<never>;
+/**
+ * Validates required fields in a request body.
+ *
+ * @throws Error if required fields are missing
+ */
+declare function validateRequired(body: Record<string, unknown>, fields: string[]): void;
+/**
+ * Extracts query parameters from a URL.
+ */
+declare function parseQueryParams(url: string): Record<string, string>;
+/**
+ * Builds a URL with query parameters.
+ */
+declare function buildUrl(base: string, params: Record<string, string | undefined>): string;
+/**
+ * Rate limiting bucket.
+ */
+interface RateLimitBucket {
+    count: number;
+    resetAt: number;
+}
+/**
+ * Simple in-memory rate limiter.
+ *
+ * @example
+ * ```typescript
+ * const limiter = createRateLimiter({ maxRequests: 100, windowMs: 60000 });
+ *
+ * // In your API handler:
+ * if (!limiter.check(clientIp)) {
+ *   return { error: 'Rate limit exceeded' };
+ * }
+ * ```
+ */
+declare function createRateLimiter(options: {
+    maxRequests: number;
+    windowMs: number;
+}): {
+    /**
+     * Checks if a key is within rate limits.
+     * Returns true if allowed, false if rate limited.
+     */
+    check(key: string): boolean;
+    /**
+     * Gets remaining requests for a key.
+     */
+    remaining(key: string): number;
+    /**
+     * Resets the limiter for a key.
+     */
+    reset(key: string): void;
+    /**
+     * Clears all rate limit data.
+     */
+    clear(): void;
+};
+/**
+ * Parses a Stellar address from various formats.
+ * Handles federation addresses, muxed accounts, etc.
+ */
+declare function parseAddress(input: string): {
+    address: string;
+    muxedId?: string;
+    federation?: string;
+};
+
 /**
  * Base error class for all Stellar Snaps SDK errors.
  * Includes an error code for programmatic error handling.
@@ -630,4 +1170,4 @@ declare class InvalidUriError extends StellarSnapError {
     constructor(message: string);
 }
 
-export { type BuildPaymentOptions, type CreateDiscoveryFileOptions, type CreateSnapOptions, type CreateSnapResult, type DiscoveryFile, type DiscoveryRule, type FreighterConnectionResult, HORIZON_URLS, InvalidAddressError, InvalidAmountError, InvalidAssetError, InvalidUriError, type MemoType, NETWORK_PASSPHRASES, type Network, type ParsedSnap, type PaymentSnapOptions, type PaymentSnapResult, StellarSnapError, type TransactionSnapOptions, type TransactionSnapResult, type TransactionSubmitResult, buildPaymentTransaction, connectFreighter, createAsset, createDiscoveryFile, createPaymentSnap, createSnap, createTransactionSnap, deleteSnap, getFreighterNetwork, getSnap, isFreighterConnected, isValidAmount, isValidAssetCode, isValidStellarAddress, listSnaps, matchUrlToRule, parseSnapUri, signWithFreighter, submitTransaction, validateDiscoveryFile };
+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, type SnapMetadata, 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 };