@stellar-snaps/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,521 @@
+import * as StellarSdk from '@stellar/stellar-sdk';
+
+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;
+
+/**
+ * Stellar network passphrases used for transaction signing.
+ * Each network has a unique passphrase that identifies it.
+ */
+declare const NETWORK_PASSPHRASES: {
+    readonly public: "Public Global Stellar Network ; September 2015";
+    readonly testnet: "Test SDF Network ; September 2015";
+};
+/**
+ * Horizon API URLs for each Stellar network.
+ * Horizon is the REST API for interacting with the Stellar network.
+ */
+declare const HORIZON_URLS: {
+    readonly public: "https://horizon.stellar.org";
+    readonly testnet: "https://horizon-testnet.stellar.org";
+};
+/**
+ * Supported Stellar networks.
+ * - `public`: The main Stellar network (real money)
+ * - `testnet`: Test network for development (free test tokens)
+ */
+type Network = 'public' | 'testnet';
+/**
+ * Stellar memo types for attaching metadata to transactions.
+ * - `MEMO_TEXT`: Plain text (max 28 bytes)
+ * - `MEMO_ID`: 64-bit unsigned integer
+ * - `MEMO_HASH`: 32-byte hash
+ * - `MEMO_RETURN`: 32-byte hash (for returning payments)
+ */
+type MemoType = 'MEMO_TEXT' | 'MEMO_ID' | 'MEMO_HASH' | 'MEMO_RETURN';
+
+/**
+ * Options for creating a transaction snap URI.
+ * Used for advanced use cases where you need to sign arbitrary transactions,
+ * not just simple payments.
+ */
+interface TransactionSnapOptions {
+    /** The transaction in XDR format (Stellar's binary encoding) */
+    xdr: string;
+    /** The network this transaction is for (default: 'public') */
+    network?: Network;
+    /** Human-readable message to show the user when signing */
+    message?: string;
+    /** URL to call after the transaction is signed */
+    callback?: string;
+    /** Public key of the required signer */
+    pubkey?: string;
+}
+/**
+ * Result of creating a transaction snap.
+ */
+interface TransactionSnapResult {
+    /** The complete SEP-0007 URI */
+    uri: string;
+    /** The parsed parameters */
+    params: Record<string, string>;
+}
+/**
+ * Creates a SEP-0007 transaction URI for signing arbitrary Stellar transactions.
+ *
+ * Unlike payment snaps which are for simple payments, transaction snaps can
+ * encode any Stellar transaction (multi-operation, account creation, etc.).
+ *
+ * @param options - Transaction snap configuration
+ * @returns The generated URI and parsed parameters
+ * @throws {InvalidUriError} If the XDR is missing or invalid
+ *
+ * @example
+ * ```typescript
+ * const { uri } = createTransactionSnap({
+ *   xdr: 'AAAA...', // Your transaction XDR
+ *   network: 'testnet',
+ *   message: 'Please sign this transaction',
+ * });
+ * // => web+stellar:tx?xdr=AAAA...&network_passphrase=Test%20SDF%20Network...
+ * ```
+ */
+declare function createTransactionSnap(options: TransactionSnapOptions): TransactionSnapResult;
+
+interface ParsedSnap {
+    type: 'pay' | 'tx';
+    destination?: string;
+    amount?: string;
+    assetCode?: string;
+    assetIssuer?: string;
+    memo?: string;
+    memoType?: string;
+    message?: string;
+    networkPassphrase?: string;
+    callback?: string;
+    xdr?: string;
+}
+declare function parseSnapUri(uri: string): ParsedSnap;
+
+/**
+ * Validates a Stellar public address.
+ * Valid addresses are 56 characters long and start with 'G'.
+ *
+ * @param address - The address to validate
+ * @returns true if the address is valid
+ *
+ * @example
+ * ```typescript
+ * isValidStellarAddress('GDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOUJ3DTJE4QRK764');
+ * // => true
+ *
+ * isValidStellarAddress('invalid');
+ * // => false
+ * ```
+ */
+declare function isValidStellarAddress(address: string): boolean;
+/**
+ * Validates a Stellar asset code.
+ * Asset codes are 1-12 alphanumeric characters.
+ * "XLM" is the native asset and is always valid.
+ *
+ * @param code - The asset code to validate
+ * @returns true if the asset code is valid
+ *
+ * @example
+ * ```typescript
+ * isValidAssetCode('USDC');
+ * // => true
+ *
+ * isValidAssetCode('XLM');
+ * // => true
+ *
+ * isValidAssetCode('ThisIsTooLongForAnAssetCode');
+ * // => false
+ * ```
+ */
+declare function isValidAssetCode(code: string): boolean;
+/**
+ * Validates a payment amount.
+ * Amounts must be positive numbers represented as strings.
+ * Stellar supports up to 7 decimal places.
+ *
+ * @param amount - The amount to validate
+ * @returns true if the amount is valid
+ *
+ * @example
+ * ```typescript
+ * isValidAmount('10');
+ * // => true
+ *
+ * isValidAmount('0.0000001');
+ * // => true
+ *
+ * isValidAmount('-5');
+ * // => false
+ *
+ * isValidAmount('0');
+ * // => false
+ * ```
+ */
+declare function isValidAmount(amount: string): boolean;
+
+/**
+ * Options for building a payment transaction.
+ */
+interface BuildPaymentOptions {
+    /** The payer's Stellar public address */
+    source: string;
+    /** The account sequence number (prevents replay attacks) */
+    sequence: string;
+    /** The recipient's Stellar public address */
+    destination: string;
+    /** The amount to send (as a string for precision) */
+    amount: string;
+    /** The asset to send (defaults to XLM if not specified) */
+    asset?: {
+        /** Asset code, e.g., "USDC", "XLM" */
+        code: string;
+        /** Asset issuer address (required for non-XLM assets) */
+        issuer?: string;
+    };
+    /** Optional memo to attach to the transaction */
+    memo?: {
+        /** The memo type */
+        type: MemoType;
+        /** The memo value */
+        value: string;
+    };
+    /** The network to build for */
+    network: Network;
+    /** Transaction validity timeout in seconds (default: 180) */
+    timeout?: number;
+}
+/**
+ * Creates a Stellar Asset object.
+ *
+ * @param code - The asset code (e.g., "XLM", "USDC")
+ * @param issuer - The asset issuer address (required for non-XLM assets)
+ * @returns A Stellar Asset object
+ * @throws {InvalidAssetError} If a non-XLM asset is missing an issuer
+ *
+ * @example
+ * ```typescript
+ * // Native XLM
+ * const xlm = createAsset('XLM');
+ *
+ * // Custom asset
+ * const usdc = createAsset('USDC', 'GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN');
+ * ```
+ */
+declare function createAsset(code: string, issuer?: string): StellarSdk.Asset;
+/**
+ * Builds a Stellar payment transaction and returns the XDR.
+ *
+ * This function creates a complete unsigned transaction that can be
+ * signed by a wallet like Freighter.
+ *
+ * @param options - The payment options
+ * @returns The transaction XDR string
+ * @throws {InvalidAddressError} If source or destination address is invalid
+ * @throws {InvalidAmountError} If amount is invalid
+ * @throws {InvalidAssetError} If asset configuration is invalid
+ *
+ * @example
+ * ```typescript
+ * const xdr = buildPaymentTransaction({
+ *   source: 'GDQP2K...',
+ *   sequence: '123456789',
+ *   destination: 'GBZX...',
+ *   amount: '10.5',
+ *   asset: { code: 'USDC', issuer: 'GA5ZS...' },
+ *   memo: { type: 'MEMO_TEXT', value: 'Payment for coffee' },
+ *   network: 'public',
+ * });
+ * ```
+ */
+declare function buildPaymentTransaction(options: BuildPaymentOptions): string;
+
+/**
+ * Result of connecting to Freighter wallet.
+ */
+interface FreighterConnectionResult {
+    /** The user's Stellar public address */
+    publicKey: string;
+    /** The network the wallet is connected to */
+    network: Network;
+}
+/**
+ * Result of submitting a transaction.
+ */
+interface TransactionSubmitResult {
+    /** The transaction hash (can be used in block explorers) */
+    hash: string;
+    /** Whether the transaction was successful */
+    successful: boolean;
+    /** The ledger number the transaction was included in */
+    ledger?: number;
+}
+/**
+ * Checks if Freighter wallet extension is installed and connected.
+ *
+ * @returns true if Freighter is installed and the user has granted access
+ *
+ * @example
+ * ```typescript
+ * if (await isFreighterConnected()) {
+ *   console.log('Ready to sign transactions!');
+ * } else {
+ *   console.log('Please connect your Freighter wallet');
+ * }
+ * ```
+ */
+declare function isFreighterConnected(): Promise<boolean>;
+/**
+ * Gets the current network from Freighter wallet.
+ *
+ * @returns The network the user's wallet is connected to
+ * @throws {StellarSnapError} If unable to get network
+ *
+ * @example
+ * ```typescript
+ * const network = await getFreighterNetwork();
+ * console.log(`Connected to ${network}`); // 'public' or 'testnet'
+ * ```
+ */
+declare function getFreighterNetwork(): Promise<Network>;
+/**
+ * Connects to the Freighter wallet and returns the user's public key and network.
+ *
+ * This will prompt the user to grant access if they haven't already.
+ *
+ * @returns The user's public key and current network
+ * @throws {StellarSnapError} If Freighter is not installed or connection fails
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const { publicKey, network } = await connectFreighter();
+ *   console.log(`Connected: ${publicKey} on ${network}`);
+ * } catch (error) {
+ *   console.error('Failed to connect:', error.message);
+ * }
+ * ```
+ */
+declare function connectFreighter(): Promise<FreighterConnectionResult>;
+/**
+ * Signs a transaction using Freighter wallet.
+ *
+ * This will open the Freighter popup for the user to review and approve the transaction.
+ *
+ * @param xdr - The unsigned transaction XDR
+ * @param network - The network the transaction is for
+ * @returns The signed transaction XDR
+ * @throws {StellarSnapError} If signing fails or user rejects
+ *
+ * @example
+ * ```typescript
+ * const unsignedXdr = buildPaymentTransaction({ ... });
+ * const signedXdr = await signWithFreighter(unsignedXdr, 'public');
+ * ```
+ */
+declare function signWithFreighter(xdr: string, network: Network): Promise<string>;
+/**
+ * Submits a signed transaction to the Stellar network.
+ *
+ * @param signedXdr - The signed transaction XDR
+ * @param network - The network to submit to
+ * @returns The transaction result including hash and success status
+ * @throws {StellarSnapError} If submission fails
+ *
+ * @example
+ * ```typescript
+ * const signedXdr = await signWithFreighter(unsignedXdr, 'public');
+ * const result = await submitTransaction(signedXdr, 'public');
+ *
+ * if (result.successful) {
+ *   console.log(`Transaction successful! Hash: ${result.hash}`);
+ *   console.log(`View on explorer: https://stellar.expert/explorer/public/tx/${result.hash}`);
+ * }
+ * ```
+ */
+declare function submitTransaction(signedXdr: string, network: Network): Promise<TransactionSubmitResult>;
+
+/**
+ * A rule for matching URL paths to API endpoints.
+ */
+interface DiscoveryRule {
+    /**
+     * URL path pattern with wildcards.
+     * Use `*` as a wildcard that matches any characters.
+     *
+     * @example "/s/*" matches "/s/abc123"
+     * @example "/pay/*" matches "/pay/user123"
+     */
+    pathPattern: string;
+    /**
+     * API endpoint path template.
+     * Use `$1`, `$2`, etc. to insert captured wildcards.
+     *
+     * @example "/api/snap/$1" with pathPattern "/s/*" and URL "/s/abc"
+     *          resolves to "/api/snap/abc"
+     */
+    apiPath: string;
+}
+/**
+ * Discovery file structure for Stellar Snaps.
+ *
+ * This file should be hosted at `/.well-known/stellar-snap.json` on your domain
+ * to enable the browser extension to discover and render your snaps.
+ */
+interface DiscoveryFile {
+    /** The name of your application */
+    name: string;
+    /** A short description of your application */
+    description?: string;
+    /** URL to your application's icon (recommended: 128x128 PNG) */
+    icon?: string;
+    /** Rules for matching URLs to snap metadata endpoints */
+    rules: DiscoveryRule[];
+}
+/**
+ * Options for creating a discovery file.
+ */
+interface CreateDiscoveryFileOptions {
+    /** The name of your application */
+    name: string;
+    /** A short description of your application */
+    description?: string;
+    /** URL to your application's icon */
+    icon?: string;
+    /** Rules for matching URLs to snap metadata endpoints */
+    rules: DiscoveryRule[];
+}
+/**
+ * Creates a valid discovery file object.
+ *
+ * Use this to generate the JSON that should be hosted at
+ * `/.well-known/stellar-snap.json` on your domain.
+ *
+ * @param options - The discovery file configuration
+ * @returns A valid DiscoveryFile object
+ *
+ * @example
+ * ```typescript
+ * const discovery = createDiscoveryFile({
+ *   name: 'My Payment App',
+ *   description: 'Accept Stellar payments easily',
+ *   rules: [
+ *     { pathPattern: '/pay/*', apiPath: '/api/snap/$1' },
+ *     { pathPattern: '/donate/*', apiPath: '/api/donation/$1' },
+ *   ],
+ * });
+ *
+ * // Save as /.well-known/stellar-snap.json
+ * fs.writeFileSync(
+ *   'public/.well-known/stellar-snap.json',
+ *   JSON.stringify(discovery, null, 2)
+ * );
+ * ```
+ */
+declare function createDiscoveryFile(options: CreateDiscoveryFileOptions): DiscoveryFile;
+/**
+ * Validates that an unknown object is a valid discovery file.
+ *
+ * Use this to validate discovery files fetched from other domains.
+ *
+ * @param file - The object to validate
+ * @returns true if the object is a valid DiscoveryFile
+ *
+ * @example
+ * ```typescript
+ * const response = await fetch('https://example.com/.well-known/stellar-snap.json');
+ * const data = await response.json();
+ *
+ * if (validateDiscoveryFile(data)) {
+ *   console.log('Valid discovery file:', data.name);
+ * } else {
+ *   console.error('Invalid discovery file');
+ * }
+ * ```
+ */
+declare function validateDiscoveryFile(file: unknown): file is DiscoveryFile;
+/**
+ * Matches a URL pathname against discovery rules and returns the API path.
+ *
+ * This is used to find which API endpoint to call for a given URL.
+ *
+ * @param pathname - The URL pathname to match (e.g., "/s/abc123")
+ * @param rules - The discovery rules to match against
+ * @returns The resolved API path, or null if no match
+ *
+ * @example
+ * ```typescript
+ * const rules = [
+ *   { pathPattern: '/s/*', apiPath: '/api/snap/$1' },
+ *   { pathPattern: '/pay/*', apiPath: '/api/payment/$1' },
+ * ];
+ *
+ * matchUrlToRule('/s/abc123', rules);
+ * // => '/api/snap/abc123'
+ *
+ * matchUrlToRule('/pay/user456', rules);
+ * // => '/api/payment/user456'
+ *
+ * matchUrlToRule('/unknown/path', rules);
+ * // => null
+ * ```
+ */
+declare function matchUrlToRule(pathname: string, rules: DiscoveryRule[]): string | null;
+
+/**
+ * Base error class for all Stellar Snaps SDK errors.
+ * Includes an error code for programmatic error handling.
+ */
+declare class StellarSnapError extends Error {
+    code: string;
+    constructor(message: string, code: string);
+}
+/**
+ * Thrown when a Stellar address is invalid.
+ * Valid addresses are 56 characters long and start with 'G'.
+ */
+declare class InvalidAddressError extends StellarSnapError {
+    constructor(address: string);
+}
+/**
+ * Thrown when an amount is invalid.
+ * Amounts must be positive numbers represented as strings.
+ */
+declare class InvalidAmountError extends StellarSnapError {
+    constructor(amount: string);
+}
+/**
+ * Thrown when an asset configuration is invalid.
+ * Non-XLM assets require both a code and an issuer address.
+ */
+declare class InvalidAssetError extends StellarSnapError {
+    constructor(message: string);
+}
+/**
+ * Thrown when a SEP-0007 URI is invalid or malformed.
+ */
+declare class InvalidUriError extends StellarSnapError {
+    constructor(message: string);
+}
+
+export { type BuildPaymentOptions, type CreateDiscoveryFileOptions, 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, createTransactionSnap, getFreighterNetwork, isFreighterConnected, isValidAmount, isValidAssetCode, isValidStellarAddress, matchUrlToRule, parseSnapUri, signWithFreighter, submitTransaction, validateDiscoveryFile };