feat(metadata): add NFD avatar and banner image resolution

README.md

@@ -69,6 +69,29 @@ const nfdData = await nfd.resolve('alice.algo', { view: 'brief' })
 const nfdDataById = await nfd.resolve('123456789')
 ```
 
+### Getting NFD Images (Avatar & Banner)
+
+```typescript
+import { NfdClient } from '@txnlab/nfd-sdk'
+
+const nfd = NfdClient.testNet()
+
+// Get avatar image with automatic fallback
+const avatarResult = await nfd.getAvatarImage('alice.algo')
+console.log(avatarResult.url) // Always returns a URL (fallback if needed)
+console.log(avatarResult.verified) // true if from verified NFT properties
+console.log(avatarResult.asaId) // ASA ID if verified image
+
+// Get banner image (may be null)
+const bannerResult = await nfd.getBannerImage('alice.algo')
+console.log(bannerResult.url) // May be null if no banner set
+
+// Fast path: If you already have NFD data
+const nfdData = await nfd.resolve('alice.algo', { view: 'full' })
+const avatar = await nfd.getAvatarImage(nfdData) // No additional resolve needed
+const banner = await nfd.getBannerImage(nfdData) // No additional resolve needed
+```
+
 ### Searching for NFDs
 
 ```typescript
@@ -192,6 +215,7 @@ const customNfd = new NfdClient({
 Check out the [examples directory](./examples) for complete working examples of various SDK features:
 
 - [Resolve](./examples/resolve/): Demonstrates how to resolve NFD names and application IDs
+- [NFD Metadata](./examples/nfd-metadata/): Demonstrates how to resolve avatar and banner images with IPFS support
 - [API Search](./examples/api-search/): Demonstrates how to use the API client to search for NFDs
 - [Reverse Lookup](./examples/reverse-lookup/): Demonstrates how to look up NFDs by wallet address
 - [Mint](./examples/mint/): Demonstrates how to mint NFDs

examples/README.md

@@ -5,6 +5,7 @@ This directory contains example applications demonstrating various features of t
 ## Available Examples
 
 - [Resolve](./resolve/): Demonstrates how to resolve NFD names and application IDs
+- [NFD Metadata](./nfd-metadata/): Demonstrates how to resolve avatar and banner images with IPFS support
 - [API Search](./api-search/): Demonstrates how to use the API client to search for NFDs
 - [Reverse Lookup](./reverse-lookup/): Demonstrates how to look up NFDs by wallet address
 - [Mint](./mint/): Demonstrates how to mint NFDs

examples/nfd-metadata/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

examples/nfd-metadata/README.md

@@ -0,0 +1,46 @@
+# NFD Metadata Example
+
+This example demonstrates how to use the NFD SDK's metadata functionality to resolve avatar and banner images for NFDs.
+
+## Features Demonstrated
+
+- **Avatar Image Resolution**: Get avatar images with automatic fallback to default NFD avatar
+- **Banner Image Resolution**: Get banner images (returns null if not set)
+- **IPFS to HTTPS Conversion**: Automatic conversion of IPFS URLs to accessible HTTPS URLs
+- **Verified vs User-Defined**: Shows verification status and ASA ID for NFT-based images
+- **Optimization Paths**: Demonstrates both slow path (resolve then parse) and fast path (direct parsing)
+
+## What You'll See
+
+- Input field to enter any NFD name or app ID
+- Real-time avatar and banner image display
+- Metadata details including:
+  - Raw on-chain values
+  - Resolved HTTPS URLs
+  - Verification status
+  - ASA ID for verified NFT images
+  - Whether avatar is using fallback default image
+
+## Running the Example
+
+```bash
+# Install dependencies
+pnpm install
+
+# Start the development server
+pnpm dev
+```
+
+Visit `http://localhost:5173` in your browser to try the example.
+
+## Try These NFDs
+
+Some NFDs with interesting metadata to test:
+
+- `nfdomains.algo` - User-defined avatar and banner
+- `doug.algo` - Verified avatar and banner
+- Any NFD name to see the avatar fallback in action
+
+## About the NFD SDK
+
+The NFD SDK provides various methods for interacting with Non-Fungible Domains on the Algorand blockchain. This example is part of a series of examples showcasing different features of the NFD SDK. Check out the other examples in this repository to learn more about the full capabilities of the SDK.

examples/nfd-metadata/eslint.config.js

@@ -0,0 +1,42 @@
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import globals from 'globals'
+import tseslint from 'typescript-eslint'
+import baseConfig from '../../eslint.config.js'
+
+export default tseslint.config(
+  ...baseConfig,
+  {
+    files: ['src/**/*.{ts,tsx}'],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+      parserOptions: {
+        project: './tsconfig.json',
+      },
+    },
+    plugins: {
+      '@typescript-eslint': tseslint.plugin,
+      'react-hooks': reactHooks,
+      'react-refresh': reactRefresh,
+    },
+    rules: {
+      ...reactHooks.configs.recommended.rules,
+      'react-refresh/only-export-components': [
+        'warn',
+        { allowConstantExport: true },
+      ],
+    },
+  },
+  {
+    files: ['*.config.{js,ts}'],
+    languageOptions: {
+      parserOptions: {
+        project: './tsconfig.node.json',
+      },
+    },
+    plugins: {
+      '@typescript-eslint': tseslint.plugin,
+    },
+  },
+)

examples/nfd-metadata/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>NFD Metadata Example</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/index.tsx"></script>
+  </body>
+</html>

examples/nfd-metadata/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@txnlab/nfd-sdk-metadata-example",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "lint": "eslint \"**/*.{js,jsx,ts,tsx}\"",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@txnlab/nfd-sdk": "workspace:*",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.64",
+    "@types/react-dom": "^18.2.21",
+    "@vitejs/plugin-react": "^4.2.1",
+    "vite": "^4.5.2",
+    "vite-plugin-node-polyfills": "^0.23.0"
+  }
+}