npm package: @rozoai/deeplink-core
Description: Core library for deeplink
Author: Rozo AI
Latest version: 1.1.4

# DeepLink QR Code Parser

A universal QR code parser that supports multiple blockchain protocols and payment standards.

## Overview

The DeepLink parser automatically detects and parses QR codes for:

- **Ethereum/EVM** addresses and EIP-681 payment requests
- **Solana** addresses and Solana Pay requests
- **Stellar** addresses and SEP-7 payment requests
- **Website URLs**

## Quick Start

```typescript
import { parseDeeplink } from "@rozoai/deeplink-core";

// Parse any QR code string
const result = parseDeeplink(qrCodeString);
if (result) {
  console.log(result.type); // "ethereum" | "address" | "solana" | "stellar" | "website"
}
```

## Supported Formats

### Ethereum/EVM

- **EIP-681 Payment Requests**: `ethereum:<contract_address>@<chain_id>/<function_name>?<params>`
- **EVM Addresses**: `0x...` (plain addresses without default chain or asset configuration)

### Solana

- **Solana Pay**: `solana:<address>?<params>`
- **Solana Addresses**: Base58 encoded addresses

### Stellar

- **SEP-7 Payment URI**: `web+stellar:(pay|tx)?<params>`
- **Stellar Addresses**: G-prefixed public keys

### Websites

- **HTTP/HTTPS URLs**: Any valid web URL

## Return Types

The `parseDeeplink` function returns a `DeeplinkData` object, which is a union of the following types:

```typescript
// The main union type for all parsing results
export type DeeplinkData =
  | StellarParseResult
  | EthereumParseResult
  | SolanaParseResult
  | WebsiteParseResult
  | AddressParseResult;

// Base interface for all blockchain-related results
export interface BlockchainParseResult {
  type: "stellar" | "ethereum" | "solana" | "address";
  operation?: string;
  address?: string;
  amount?: string;
  message?: string;
  asset?: {
    code?: string;
    issuer?: string;
    contract?: string;
    decimals?: number;
    name?: string;
  };
  // ... and many other optional fields for different protocols
}

export interface WebsiteParseResult {
  type: "website";
  url: string;
}
```

For the full details of all fields, please refer to `src/types.ts`.

## Examples

```typescript
// EIP-681 Payment Request for USDC on Base
parseDeeplink(
  "ethereum:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913@8453/transfer?address=0xRecipient&uint256=1000000"
);
// Returns:
// {
//   type: "ethereum",
//   operation: "transfer",
//   address: "0xRecipient",
//   asset: { contract: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" },
//   chain_id: 8453,
//   amount: "1000000",
//   raw: { data: "ethereum:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913@8453/transfer?address=0xRecipient&uint256=1000000" }
// }

// EVM Address
parseDeeplink("0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6");
// Returns:
// {
//   type: "ethereum",
//   address: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
//   operation: "transfer",
//   raw: { data: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6" }
// }

// Website
parseDeeplink("https://rozo.ai");
// Returns: { type: "website", url: "https://rozo.ai" }

// Solana Address
parseDeeplink("7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU");
// Returns:
// {
//   type: "solana",
//   address: "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
//   raw: { data: "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU" }
// }

// Stellar Payment Request
parseDeeplink(
  "web+stellar:pay?destination=GC...&amount=100&asset_code=USDC&asset_issuer=GA..."
);
// Returns:
// {
//   type: "stellar",
//   operation: "pay",
//   address: "GC...",
//   amount: "100",
//   asset: { code: "USDC", issuer: "GA..." },
//   raw: { data: "web+stellar:pay?destination=GC...&amount=100&asset_code=USDC&asset_issuer=GA..." }
// }
```

## Architecture

The parser uses a **chain of responsibility** pattern, trying each parser in a specific order:

1.  **Website Parser**: Checks for `http://` or `https://` prefixes.
2.  **Address Parser**: Checks for standalone EVM addresses (`0x...`).
3.  **Ethereum Parser**: Handles EIP-681 URIs (`ethereum:...`).
4.  **Solana Parser**: Detects Solana Pay URIs (`solana:...`) and standalone addresses.
5.  **Stellar Parser**: Handles SEP-7 URIs (`web+stellar:...`) and standalone addresses.

If no parser can handle the input, it returns `null`.

## Adding New Protocols

To add support for a new blockchain:

1. Create a new parser file (e.g., `bitcoin.ts`) in `src/protocols/`.
2. Implement and export a `parseBitcoin(input: string): DeeplinkData | null` function.
3. Add your new parser to the `parsers` array in `src/index.ts`.
4. Add your new result type to the `DeeplinkData` union in `src/types.ts`.

```typescript
// Example: Adding Bitcoin support
export function parseBitcoin(input: string): DeeplinkData | null {
  const bitcoinRegex = /^bitcoin:([13][a-km-zA-HJ-NP-Z1-9]{25,34})/;
  const match = input.match(bitcoinRegex);
  if (match) {
    return {
      type: "bitcoin",
      address: match[1],
      raw: { data: input },
    };
  }
  return null;
}
```

## Error Handling

- Invalid formats return `null` from individual parsers.
- The top-level `parseDeeplink` function will throw an error if no parser matches. This behavior might be updated to return `null` in the future for consistency.
- All parsers are designed to be safe and avoid throwing exceptions themselves.

## Usage in Components

```typescript
import { parseDeeplink } from "@rozoai/deeplink-core";

function QRScanner() {
  const handleQRCode = (qrData: string) => {
    try {
      const parsed = parseDeeplink(qrData);

      switch (parsed.type) {
        case "ethereum":
          // Handle Ethereum payment
          break;
        case "website":
          // Open website
          window.open(parsed.url);
          break;
        // ... handle other cases
      }
    } catch (error) {
      console.error("Failed to parse QR code:", error);
      // Show an error message to the user
    }
  };
}
```

---

## Related Packages

- **[@rozoai/deeplink-react](../scan-qr)**: A React component for scanning QR codes and parsing them with this library.
- **[@rozoai/deeplink-react-native](../react-native)**: A React Native component for scanning QR codes with Expo support.
- **[Demo Application](../../apps/demo)**: A Next.js application demonstrating the usage of `@rozoai/deeplink-core` and `@rozoai/deeplink-react`.