@jerydam/lumina-sdk 0.1.0

package/app/docs/api/endpoints/page.tsx

@@ -0,0 +1,397 @@
+'use client'
+
+import { Breadcrumb } from '@/components/docs/breadcrumb'
+import { TableOfContents } from '@/components/docs/table-of-contents'
+import { CodeBlock } from '@/components/docs/code-block'
+import { Callout } from '@/components/docs/callout'
+
+export default function EndpointsPage() {
+  const headings = [
+    { id: 'wallets', level: 2, text: 'Wallets' },
+    { id: 'transactions', level: 2, text: 'Transactions' },
+    { id: 'users', level: 2, text: 'Users' },
+    { id: 'networks', level: 2, text: 'Networks' },
+    { id: 'analytics', level: 2, text: 'Analytics' },
+  ]
+
+  return (
+    <div className="flex gap-8 max-w-7xl mx-auto px-4 py-8">
+      <main className="flex-1 min-w-0">
+        <Breadcrumb 
+          items={[
+            { label: 'Docs', href: '/docs' },
+            { label: 'API', href: '/docs/api/overview' },
+            { label: 'Endpoints' },
+          ]}
+        />
+
+        <div className="mt-8 prose prose-invert max-w-none">
+          <h1>API Endpoints</h1>
+          
+          <p className="text-lg text-foreground/80">
+            Complete reference for all Lumina REST API endpoints. Each endpoint includes request/response examples.
+          </p>
+
+          <h2 id="wallets">Wallets</h2>
+
+          <h3>Create Wallet</h3>
+          <CodeBlock
+            code={`POST /wallets
+
+{
+  "user_id": "user_abc123",
+  "network": "ethereum",
+  "name": "My Wallet",
+  "metadata": {
+    "app_id": "myapp"
+  }
+}`}
+            language="bash"
+            title="Request"
+          />
+
+          <CodeBlock
+            code={`{
+  "success": true,
+  "data": {
+    "id": "wallet_abc123",
+    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f42e0d",
+    "network": "ethereum",
+    "balance": "0",
+    "created_at": "2024-01-15T10:30:00Z"
+  }
+}`}
+            language="json"
+            title="Response"
+          />
+
+          <h3>Get Wallet</h3>
+          <CodeBlock
+            code={`GET /wallets/{wallet_id}
+
+Response:
+{
+  "success": true,
+  "data": {
+    "id": "wallet_abc123",
+    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f42e0d",
+    "network": "ethereum",
+    "balance": "2.5",
+    "nonce": 42,
+    "created_at": "2024-01-15T10:30:00Z"
+  }
+}`}
+            language="bash"
+            title="Get Wallet"
+          />
+
+          <h3>List Wallets</h3>
+          <CodeBlock
+            code={`GET /wallets?user_id=user_abc123&limit=10&offset=0
+
+Response:
+{
+  "success": true,
+  "data": {
+    "wallets": [
+      {
+        "id": "wallet_1",
+        "address": "0x742d...",
+        "balance": "2.5",
+        "network": "ethereum"
+      },
+      {
+        "id": "wallet_2",
+        "address": "0x123...",
+        "balance": "0.5",
+        "network": "polygon"
+      }
+    ],
+    "total": 2,
+    "limit": 10,
+    "offset": 0
+  }
+}`}
+            language="bash"
+            title="List Wallets"
+          />
+
+          <h3>Update Wallet</h3>
+          <CodeBlock
+            code={`PATCH /wallets/{wallet_id}
+
+{
+  "name": "Updated Wallet Name",
+  "metadata": {
+    "custom_field": "value"
+  }
+}
+
+Response:
+{
+  "success": true,
+  "data": {
+    "id": "wallet_abc123",
+    "name": "Updated Wallet Name",
+    "updated_at": "2024-01-15T10:35:00Z"
+  }
+}`}
+            language="bash"
+            title="Update Wallet"
+          />
+
+          <h2 id="transactions">Transactions</h2>
+
+          <h3>Create Transaction</h3>
+          <CodeBlock
+            code={`POST /transactions
+
+{
+  "wallet_id": "wallet_abc123",
+  "to": "0x123456789...",
+  "amount": "1.5",
+  "token": "ETH",
+  "data": "0x",
+  "gas_limit": "21000",
+  "gas_price": "50",
+  "description": "Payment for order #12345"
+}`}
+            language="bash"
+            title="Request"
+          />
+
+          <CodeBlock
+            code={`{
+  "success": true,
+  "data": {
+    "id": "txn_abc123",
+    "hash": null,
+    "from": "0x742d35Cc6634C0532925a3b844Bc9e7595f42e0d",
+    "to": "0x123456789...",
+    "amount": "1.5",
+    "status": "pending",
+    "created_at": "2024-01-15T10:30:00Z"
+  }
+}`}
+            language="json"
+            title="Response"
+          />
+
+          <h3>Confirm Transaction</h3>
+          <CodeBlock
+            code={`POST /transactions/{txn_id}/confirm
+
+{
+  "signature": "0x...",
+  "nonce": 42
+}
+
+Response:
+{
+  "success": true,
+  "data": {
+    "id": "txn_abc123",
+    "hash": "0xabc123...",
+    "status": "submitted",
+    "confirmed_at": "2024-01-15T10:30:15Z"
+  }
+}`}
+            language="bash"
+            title="Confirm Transaction"
+          />
+
+          <h3>Get Transaction</h3>
+          <CodeBlock
+            code={`GET /transactions/{txn_id}
+
+Response:
+{
+  "success": true,
+  "data": {
+    "id": "txn_abc123",
+    "hash": "0xabc123...",
+    "from": "0x742d35Cc...",
+    "to": "0x123456789...",
+    "amount": "1.5",
+    "status": "confirmed",
+    "gas_used": "21000",
+    "gas_price": "50",
+    "fee": "0.00105",
+    "block_number": 19234567,
+    "created_at": "2024-01-15T10:30:00Z",
+    "confirmed_at": "2024-01-15T10:30:15Z"
+  }
+}`}
+            language="bash"
+            title="Get Transaction"
+          />
+
+          <h3>List Transactions</h3>
+          <CodeBlock
+            code={`GET /transactions?wallet_id=wallet_abc123&status=confirmed&limit=20
+
+Response:
+{
+  "success": true,
+  "data": {
+    "transactions": [
+      {
+        "id": "txn_1",
+        "hash": "0xabc123...",
+        "status": "confirmed",
+        "amount": "1.5"
+      }
+    ],
+    "total": 42,
+    "limit": 20,
+    "offset": 0
+  }
+}`}
+            language="bash"
+            title="List Transactions"
+          />
+
+          <h2 id="users">Users</h2>
+
+          <h3>Create User</h3>
+          <CodeBlock
+            code={`POST /users
+
+{
+  "email": "user@example.com",
+  "name": "John Doe",
+  "metadata": {
+    "app_user_id": "app_123"
+  }
+}
+
+Response:
+{
+  "success": true,
+  "data": {
+    "id": "user_abc123",
+    "email": "user@example.com",
+    "name": "John Doe",
+    "created_at": "2024-01-15T10:30:00Z"
+  }
+}`}
+            language="bash"
+            title="Create User"
+          />
+
+          <h3>Get User</h3>
+          <CodeBlock
+            code={`GET /users/{user_id}
+
+Response:
+{
+  "success": true,
+  "data": {
+    "id": "user_abc123",
+    "email": "user@example.com",
+    "name": "John Doe",
+    "wallet_count": 2,
+    "created_at": "2024-01-15T10:30:00Z"
+  }
+}`}
+            language="bash"
+            title="Get User"
+          />
+
+          <h2 id="networks">Networks</h2>
+
+          <h3>List Supported Networks</h3>
+          <CodeBlock
+            code={`GET /networks
+
+Response:
+{
+  "success": true,
+  "data": {
+    "networks": [
+      {
+        "id": "ethereum",
+        "name": "Ethereum",
+        "chain_id": 1,
+        "rpc_url": "https://eth-mainnet.g.alchemy.com/v2/...",
+        "explorer": "https://etherscan.io"
+      },
+      {
+        "id": "polygon",
+        "name": "Polygon",
+        "chain_id": 137,
+        "rpc_url": "https://polygon-mainnet.g.alchemy.com/v2/...",
+        "explorer": "https://polygonscan.com"
+      }
+    ]
+  }
+}`}
+            language="bash"
+            title="List Networks"
+          />
+
+          <h2 id="analytics">Analytics</h2>
+
+          <h3>Get Wallet Analytics</h3>
+          <CodeBlock
+            code={`GET /analytics/wallets?user_id=user_abc123&period=30d
+
+Response:
+{
+  "success": true,
+  "data": {
+    "total_balance": "5.25",
+    "wallet_count": 2,
+    "transaction_count": 15,
+    "total_volume": "42.5",
+    "average_transaction": "2.83"
+  }
+}`}
+            language="bash"
+            title="Wallet Analytics"
+          />
+
+          <h3>Get Transaction Analytics</h3>
+          <CodeBlock
+            code={`GET /analytics/transactions?wallet_id=wallet_abc123&period=7d
+
+Response:
+{
+  "success": true,
+  "data": {
+    "transaction_count": 5,
+    "total_volume": "10.5",
+    "average_fee": "0.05",
+    "success_rate": 0.95,
+    "by_type": {
+      "send": 3,
+      "swap": 1,
+      "contract_interaction": 1
+    }
+  }
+}`}
+            language="bash"
+            title="Transaction Analytics"
+          />
+
+          <Callout type="info">
+            All timestamps are in ISO 8601 format (UTC). All amounts are in wei for ETH and ERC-20 tokens unless specified otherwise.
+          </Callout>
+        </div>
+
+        <div className="flex justify-between mt-12 pt-8 border-t border-white/10">
+          <a href="/docs/api/overview" className="text-emerald-400 hover:text-emerald-300">
+            ← Overview
+          </a>
+          <a href="/docs/api/errors" className="text-emerald-400 hover:text-emerald-300">
+            Error Handling →
+          </a>
+        </div>
+      </main>
+
+      <aside className="hidden lg:block w-64 flex-shrink-0">
+        <TableOfContents headings={headings} />
+      </aside>
+    </div>
+  )
+}

package/app/docs/api/errors/page.tsx

@@ -0,0 +1,305 @@
+'use client'
+
+import { Breadcrumb } from '@/components/docs/breadcrumb'
+import { CodeBlock } from '@/components/docs/code-block'
+import { Callout } from '@/components/docs/callout'
+
+export default function ErrorHandlingPage() {
+  return (
+    <div className="flex gap-8 max-w-7xl mx-auto px-4 py-8">
+      <main className="flex-1 min-w-0">
+        <Breadcrumb 
+          items={[
+            { label: 'Docs', href: '/docs' },
+            { label: 'API', href: '/docs/api/overview' },
+            { label: 'Error Handling' },
+          ]}
+        />
+
+        <div className="mt-8 prose prose-invert max-w-none">
+          <h1>Error Handling</h1>
+          
+          <p className="text-lg text-foreground/80">
+            Comprehensive guide to handling errors from the Lumina API.
+          </p>
+
+          <h2>HTTP Status Codes</h2>
+
+          <CodeBlock
+            code={`200 OK - Request successful
+201 Created - Resource created successfully
+400 Bad Request - Invalid request parameters
+401 Unauthorized - Missing or invalid API key
+403 Forbidden - API key lacks required permissions
+404 Not Found - Resource not found
+409 Conflict - Resource already exists or state conflict
+429 Too Many Requests - Rate limit exceeded
+500 Internal Server Error - Server error
+503 Service Unavailable - Service temporarily unavailable`}
+            language="text"
+            title="Status Codes"
+          />
+
+          <h2>Error Response Format</h2>
+
+          <CodeBlock
+            code={`{
+  "success": false,
+  "error": {
+    "code": "INSUFFICIENT_BALANCE",
+    "message": "Wallet has insufficient balance for this transaction",
+    "details": {
+      "required": "2.5",
+      "available": "1.0",
+      "shortfall": "1.5"
+    },
+    "request_id": "req_abc123xyz"
+  },
+  "timestamp": "2024-01-15T10:30:00Z"
+}`}
+            language="json"
+            title="Error Response"
+          />
+
+          <h2>Common Error Codes</h2>
+
+          <h3>Authentication Errors</h3>
+          <CodeBlock
+            code={`AUTHENTICATION_FAILED
+Message: Invalid API key
+Status: 401
+
+INVALID_API_KEY_FORMAT
+Message: API key format is invalid
+Status: 401
+
+API_KEY_EXPIRED
+Message: API key has expired
+Status: 401
+
+INVALID_SIGNATURE
+Message: Request signature is invalid
+Status: 401`}
+            language="text"
+            title="Auth Errors"
+          />
+
+          <h3>Validation Errors</h3>
+          <CodeBlock
+            code={`INVALID_REQUEST
+Message: Request validation failed
+Details: Field-specific error messages
+
+INVALID_ADDRESS
+Message: Invalid wallet address format
+Status: 400
+
+INVALID_AMOUNT
+Message: Invalid amount value
+Status: 400
+
+INVALID_NETWORK
+Message: Network not supported
+Status: 400
+
+MISSING_REQUIRED_FIELD
+Message: Required field missing in request
+Status: 400`}
+            language="text"
+            title="Validation Errors"
+          />
+
+          <h3>Business Logic Errors</h3>
+          <CodeBlock
+            code={`INSUFFICIENT_BALANCE
+Message: Wallet balance is insufficient
+Details: required, available, shortfall
+
+INSUFFICIENT_GAS
+Message: Insufficient gas for transaction
+Details: required_gas, available_balance
+
+WALLET_NOT_FOUND
+Message: Wallet doesn't exist
+Status: 404
+
+USER_NOT_FOUND
+Message: User doesn't exist
+Status: 404
+
+TRANSACTION_NOT_FOUND
+Message: Transaction not found
+Status: 404
+
+TRANSACTION_FAILED
+Message: Transaction execution failed
+Details: failure_reason, revert_data
+
+NETWORK_ERROR
+Message: Network connectivity issue
+Status: 503`}
+            language="text"
+            title="Business Logic Errors"
+          />
+
+          <h3>Rate Limit Errors</h3>
+          <CodeBlock
+            code={`RATE_LIMIT_EXCEEDED
+Message: Too many requests
+Status: 429
+Headers:
+  X-RateLimit-Limit: 100
+  X-RateLimit-Remaining: 0
+  X-RateLimit-Reset: 1705318200`}
+            language="text"
+            title="Rate Limit Error"
+          />
+
+          <h2>Handling Errors in Code</h2>
+
+          <h3>JavaScript/TypeScript</h3>
+          <CodeBlock
+            code={`async function createWallet(userId: string) {
+  try {
+    const response = await fetch(
+      'https://api.lumina.dev/v1/wallets',
+      {
+        method: 'POST',
+        headers: {
+          'Authorization': \`Bearer \${apiKey}\`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ user_id: userId }),
+      }
+    )
+
+    const result = await response.json()
+
+    if (!response.ok) {
+      switch (result.error.code) {
+        case 'AUTHENTICATION_FAILED':
+          console.error('Invalid API key')
+          // Refresh API key or redirect to login
+          break
+        case 'INVALID_REQUEST':
+          console.error('Invalid request:', result.error.details)
+          // Fix request parameters
+          break
+        case 'RATE_LIMIT_EXCEEDED':
+          // Wait until X-RateLimit-Reset
+          const resetTime = response.headers.get('X-RateLimit-Reset')
+          console.error('Rate limited. Reset at:', new Date(resetTime * 1000))
+          break
+        default:
+          console.error('API error:', result.error)
+      }
+      throw new Error(result.error.message)
+    }
+
+    return result.data
+  } catch (error) {
+    console.error('Failed to create wallet:', error)
+    throw error
+  }
+}`}
+            language="typescript"
+            title="Error Handling Example"
+          />
+
+          <h3>Python</h3>
+          <CodeBlock
+            code={`import requests
+from time import sleep
+
+def create_wallet(user_id: str):
+    try:
+        response = requests.post(
+            'https://api.lumina.dev/v1/wallets',
+            headers={
+                'Authorization': f'Bearer {api_key}',
+                'Content-Type': 'application/json',
+            },
+            json={'user_id': user_id}
+        )
+
+        if response.status_code == 429:
+            reset_time = int(response.headers.get('X-RateLimit-Reset'))
+            wait_seconds = reset_time - int(time.time())
+            print(f'Rate limited. Waiting {wait_seconds}s...')
+            sleep(wait_seconds)
+            return create_wallet(user_id)
+
+        response.raise_for_status()
+        return response.json()['data']
+
+    except requests.exceptions.HTTPError as e:
+        error = e.response.json()
+        print(f"Error {error['error']['code']}: {error['error']['message']}")
+        raise`}
+            language="python"
+            title="Python Error Handling"
+          />
+
+          <h2>Retry Strategy</h2>
+
+          <CodeBlock
+            code={`async function apiCallWithRetry(
+  url: string,
+  options: RequestInit,
+  maxAttempts: number = 3
+): Promise<any> {
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      const response = await fetch(url, options)
+      const data = await response.json()
+
+      if (response.ok) {
+        return data
+      }
+
+      // Don't retry client errors
+      if (response.status >= 400 && response.status < 500) {
+        throw new Error(data.error.message)
+      }
+
+      // Retry server errors with exponential backoff
+      if (response.status >= 500) {
+        if (attempt < maxAttempts) {
+          const delay = Math.pow(2, attempt - 1) * 1000
+          console.log(\`Attempt \${attempt} failed. Retrying in \${delay}ms...\`)
+          await new Promise(r => setTimeout(r, delay))
+          continue
+        }
+      }
+
+      throw new Error(data.error.message)
+    } catch (error) {
+      if (attempt === maxAttempts) {
+        throw error
+      }
+      const delay = Math.pow(2, attempt) * 1000
+      await new Promise(r => setTimeout(r, delay))
+    }
+  }
+}`}
+            language="typescript"
+            title="Retry with Exponential Backoff"
+          />
+
+          <Callout type="warning">
+            Always include the request_id from error responses when contacting support. It helps us trace the issue.
+          </Callout>
+        </div>
+
+        <div className="flex justify-between mt-12 pt-8 border-t border-white/10">
+          <a href="/docs/api/endpoints" className="text-emerald-400 hover:text-emerald-300">
+            ← Endpoints
+          </a>
+          <a href="/docs/guides/nextjs" className="text-emerald-400 hover:text-emerald-300">
+            Next.js Guide →
+          </a>
+        </div>
+      </main>
+    </div>
+  )
+}