@jerydam/lumina-sdk 0.1.0

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

@@ -0,0 +1,306 @@
+'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 APIOverviewPage() {
+  const headings = [
+    { id: 'introduction', level: 2, text: 'Introduction' },
+    { id: 'base-url', level: 2, text: 'Base URL' },
+    { id: 'authentication', level: 2, text: 'Authentication' },
+    { id: 'requests', level: 2, text: 'Making Requests' },
+    { id: 'response-format', level: 2, text: 'Response Format' },
+    { id: 'headers', level: 2, text: 'Headers' },
+    { id: 'rate-limits', level: 2, text: 'Rate Limits' },
+  ]
+
+  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: 'Overview' },
+          ]}
+        />
+
+        <div className="mt-8 prose prose-invert max-w-none">
+          <h1>REST API Overview</h1>
+          
+          <p className="text-lg text-foreground/80">
+            The Lumina REST API provides programmatic access to wallet management, transactions, and account operations.
+          </p>
+
+          <h2 id="introduction">Introduction</h2>
+          <p>
+            The Lumina API is built on REST principles and uses standard HTTP methods. All responses are JSON-encoded. The API uses API keys for authentication and enforces rate limits to ensure fair usage.
+          </p>
+
+          <Callout type="info">
+            All API requests must use HTTPS. Unencrypted HTTP requests will be rejected.
+          </Callout>
+
+          <h2 id="base-url">Base URL</h2>
+          <CodeBlock
+            code={`# Production
+https://api.lumina.dev/v1
+
+# Testnet
+https://testnet-api.lumina.dev/v1`}
+            language="bash"
+            title="Base URLs"
+          />
+
+          <h2 id="authentication">Authentication</h2>
+          <p>
+            Lumina uses API key-based authentication. Include your API key in the Authorization header:
+          </p>
+
+          <CodeBlock
+            code={`Authorization: Bearer YOUR_SECRET_KEY`}
+            language="bash"
+            title="Authorization Header"
+          />
+
+          <h3>Example Request</h3>
+          <CodeBlock
+            code={`curl -X GET https://api.lumina.dev/v1/wallets \\
+  -H "Authorization: Bearer sk_live_abc123def456..." \\
+  -H "Content-Type: application/json"`}
+            language="bash"
+            title="cURL Example"
+          />
+
+          <h3>API Key Types</h3>
+          <CodeBlock
+            code={`// Public Key (pk_*)
+// - Use on client-side
+// - Limited permissions
+// - Safe to expose in frontend code
+
+// Secret Key (sk_*)
+// - Use on server-side only
+// - Full permissions
+// - Never expose in frontend code`}
+            language="text"
+            title="Key Types"
+          />
+
+          <h2 id="requests">Making Requests</h2>
+
+          <h3>JavaScript/TypeScript</h3>
+          <CodeBlock
+            code={`const response = await fetch('https://api.lumina.dev/v1/wallets', {
+  method: 'GET',
+  headers: {
+    'Authorization': \`Bearer \${process.env.LUMINA_SECRET_KEY}\`,
+    'Content-Type': 'application/json',
+  },
+})
+
+const data = await response.json()`}
+            language="typescript"
+            title="Fetch API"
+          />
+
+          <h3>Python</h3>
+          <CodeBlock
+            code={`import requests
+
+headers = {
+    'Authorization': f'Bearer {secret_key}',
+    'Content-Type': 'application/json',
+}
+
+response = requests.get(
+    'https://api.lumina.dev/v1/wallets',
+    headers=headers
+)
+
+data = response.json()`}
+            language="python"
+            title="Python Example"
+          />
+
+          <h3>cURL</h3>
+          <CodeBlock
+            code={`curl -X GET https://api.lumina.dev/v1/wallets \\
+  -H "Authorization: Bearer sk_live_abc123..." \\
+  -H "Content-Type: application/json"`}
+            language="bash"
+            title="cURL Example"
+          />
+
+          <h2 id="response-format">Response Format</h2>
+          <p>
+            All API responses follow a consistent JSON format:
+          </p>
+
+          <CodeBlock
+            code={`{
+  "success": true,
+  "data": {
+    "id": "wallet_abc123",
+    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f42e0d",
+    "balance": "2.5",
+    "network": "ethereum"
+  },
+  "timestamp": "2024-01-15T10:30:00Z"
+}`}
+            language="json"
+            title="Success Response"
+          />
+
+          <h3>Error Responses</h3>
+          <CodeBlock
+            code={`{
+  "success": false,
+  "error": {
+    "code": "AUTHENTICATION_FAILED",
+    "message": "Invalid API key",
+    "details": {
+      "provided_key": "sk_test_invalid..."
+    }
+  },
+  "timestamp": "2024-01-15T10:30:00Z"
+}`}
+            language="json"
+            title="Error Response"
+          />
+
+          <h2 id="headers">Headers</h2>
+
+          <p>
+            Required and optional headers for API requests:
+          </p>
+
+          <CodeBlock
+            code={`// Required
+Authorization: Bearer YOUR_SECRET_KEY
+Content-Type: application/json
+
+// Optional
+X-Idempotency-Key: unique-request-id
+X-Request-Timeout: 30000
+X-Webhook-Secret: your-webhook-secret`}
+            language="text"
+            title="Request Headers"
+          />
+
+          <h3>Idempotency</h3>
+          <p>
+            For critical operations (transfers, swaps), use an idempotency key to ensure the request is only processed once:
+          </p>
+
+          <CodeBlock
+            code={`curl -X POST https://api.lumina.dev/v1/transactions \\
+  -H "Authorization: Bearer sk_live_abc123..." \\
+  -H "Content-Type: application/json" \\
+  -H "X-Idempotency-Key: txn_12345_attempt_1" \\
+  -d '{
+    "to": "0x...",
+    "amount": "1.0",
+    "token": "ETH"
+  }'`}
+            language="bash"
+            title="Idempotency Example"
+          />
+
+          <h2 id="rate-limits">Rate Limits</h2>
+
+          <p>
+            API rate limits are enforced per API key and vary by plan:
+          </p>
+
+          <CodeBlock
+            code={`Free Plan:
+- 100 requests per minute
+- 10,000 requests per day
+
+Pro Plan:
+- 500 requests per minute
+- 100,000 requests per day
+
+Enterprise:
+- Custom limits
+- Contact support`}
+            language="text"
+            title="Rate Limits by Plan"
+          />
+
+          <h3>Rate Limit Headers</h3>
+          <CodeBlock
+            code={`// Response headers include:
+X-RateLimit-Limit: 100        // Maximum requests per minute
+X-RateLimit-Remaining: 95     // Remaining requests
+X-RateLimit-Reset: 1705318200 // Unix timestamp when limit resets
+
+// Example
+curl -i https://api.lumina.dev/v1/wallets \\
+  -H "Authorization: Bearer sk_live_abc123..."
+
+// Response headers:
+// X-RateLimit-Limit: 100
+// X-RateLimit-Remaining: 99
+// X-RateLimit-Reset: 1705318200`}
+            language="bash"
+            title="Rate Limit Headers"
+          />
+
+          <Callout type="warning">
+            When you hit the rate limit (429 Too Many Requests), wait until the X-RateLimit-Reset timestamp before making additional requests.
+          </Callout>
+
+          <h3>Rate Limit Best Practices</h3>
+          <CodeBlock
+            code={`// Implement exponential backoff
+async function apiCall(url, options, attempt = 1) {
+  try {
+    const response = await fetch(url, options)
+    
+    if (response.status === 429) {
+      const resetTime = parseInt(
+        response.headers.get('X-RateLimit-Reset')
+      ) * 1000
+      const waitTime = resetTime - Date.now()
+      
+      console.log(\`Rate limited. Waiting \${waitTime}ms\`)
+      await new Promise(resolve => setTimeout(resolve, waitTime))
+      
+      return apiCall(url, options, attempt + 1)
+    }
+    
+    return response.json()
+  } catch (error) {
+    if (attempt < 3) {
+      const delay = Math.pow(2, attempt) * 1000
+      await new Promise(resolve => setTimeout(resolve, delay))
+      return apiCall(url, options, attempt + 1)
+    }
+    throw error
+  }
+}`}
+            language="typescript"
+            title="Exponential Backoff"
+          />
+        </div>
+
+        <div className="flex justify-between mt-12 pt-8 border-t border-white/10">
+          <a href="/docs/sdk/transaction-confirm" className="text-emerald-400 hover:text-emerald-300">
+            ← Transaction Confirm
+          </a>
+          <a href="/docs/api/endpoints" className="text-emerald-400 hover:text-emerald-300">
+            Endpoints →
+          </a>
+        </div>
+      </main>
+
+      <aside className="hidden lg:block w-64 flex-shrink-0">
+        <TableOfContents headings={headings} />
+      </aside>
+    </div>
+  )
+}

package/app/docs/examples/basic-setup/page.tsx

@@ -0,0 +1,256 @@
+import { Breadcrumb } from '@/components/docs/breadcrumb'
+import { CodeBlock } from '@/components/docs/code-block'
+import { Callout } from '@/components/docs/callout'
+
+export const metadata = {
+  title: 'Basic Setup Example - Lumina Examples',
+  description: 'Complete example of setting up Lumina in a Next.js app.',
+}
+
+export default function BasicSetupPage() {
+  return (
+    <>
+      <Breadcrumb />
+
+      <div className="space-y-8">
+        <div className="space-y-4">
+          <h1 className="text-4xl font-bold text-white">Basic Setup Example</h1>
+          <p className="text-lg text-foreground/80">
+            A complete, minimal Next.js application with Lumina authentication and wallet display.
+          </p>
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">Project Structure</h2>
+          <CodeBlock
+            code={`my-app/
+├── app/
+│   ├── layout.tsx
+│   ├── page.tsx
+│   ├── login/
+│   │   └── page.tsx
+│   └── dashboard/
+│       └── page.tsx
+├── .env.local
+├── package.json
+└── tsconfig.json`}
+            language="bash"
+          />
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">1. Root Layout</h2>
+          <CodeBlock
+            code={`import { LuminaProvider } from '@lumina/sdk'
+import './globals.css'
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <html>
+      <body>
+        <LuminaProvider
+          apiKey={process.env.NEXT_PUBLIC_LUMINA_API_KEY!}
+          network={
+            process.env.NODE_ENV === 'production'
+              ? 'mainnet'
+              : 'testnet'
+          }
+        >
+          {children}
+        </LuminaProvider>
+      </body>
+    </html>
+  )
+}`}
+            language="tsx"
+            title="app/layout.tsx"
+          />
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">2. Home Page</h2>
+          <CodeBlock
+            code={`'use client'
+
+import Link from 'next/link'
+import { useLumina } from '@lumina/sdk'
+
+export default function Home() {
+  const { isConnected } = useLumina()
+
+  return (
+    <main className="flex items-center justify-center min-h-screen">
+      <div className="text-center space-y-4">
+        <h1 className="text-4xl font-bold">Welcome to Lumina</h1>
+        <p className="text-lg text-gray-600">
+          Secure Web3 Wallet Infrastructure
+        </p>
+
+        {!isConnected ? (
+          <Link
+            href="/login"
+            className="px-6 py-3 bg-emerald-600 text-white rounded-lg hover:bg-emerald-700"
+          >
+            Get Started
+          </Link>
+        ) : (
+          <Link
+            href="/dashboard"
+            className="px-6 py-3 bg-emerald-600 text-white rounded-lg hover:bg-emerald-700"
+          >
+            Go to Dashboard
+          </Link>
+        )}
+      </div>
+    </main>
+  )
+}`}
+            language="tsx"
+            title="app/page.tsx"
+          />
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">3. Login Page</h2>
+          <CodeBlock
+            code={`'use client'
+
+import { useRouter } from 'next/navigation'
+import { WalletLogin } from '@lumina/sdk'
+
+export default function LoginPage() {
+  const router = useRouter()
+
+  return (
+    <main className="flex items-center justify-center min-h-screen bg-gray-100">
+      <div className="w-full max-w-md">
+        <WalletLogin
+          onSuccess={() => {
+            router.push('/dashboard')
+          }}
+          authMethods={['email', 'passkey']}
+        />
+      </div>
+    </main>
+  )
+}`}
+            language="tsx"
+            title="app/login/page.tsx"
+          />
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">4. Dashboard Page</h2>
+          <CodeBlock
+            code={`'use client'
+
+import { useRouter } from 'next/navigation'
+import { useLumina, WalletDisplay } from '@lumina/sdk'
+
+export default function DashboardPage() {
+  const router = useRouter()
+  const { user, isConnected, logout } = useLumina()
+
+  if (!isConnected) {
+    router.push('/login')
+    return null
+  }
+
+  const handleLogout = () => {
+    logout()
+    router.push('/')
+  }
+
+  return (
+    <main className="min-h-screen bg-gray-50 p-8">
+      <div className="max-w-4xl mx-auto">
+        <div className="flex justify-between items-center mb-8">
+          <h1 className="text-3xl font-bold">Dashboard</h1>
+          <button
+            onClick={handleLogout}
+            className="px-4 py-2 bg-red-600 text-white rounded-lg hover:bg-red-700"
+          >
+            Logout
+          </button>
+        </div>
+
+        <div className="bg-white rounded-lg shadow p-6">
+          <h2 className="text-xl font-semibold mb-4">Account Info</h2>
+          <p className="text-gray-600 mb-4">Email: {user?.email}</p>
+
+          <WalletDisplay
+            address={user?.walletAddress!}
+            balance={user?.balance!}
+            network="ethereum"
+          />
+        </div>
+      </div>
+    </main>
+  )
+}`}
+            language="tsx"
+            title="app/dashboard/page.tsx"
+          />
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">5. Environment Variables</h2>
+          <CodeBlock
+            code={`NEXT_PUBLIC_LUMINA_API_KEY=pk_test_xxxxx
+LUMINA_SECRET_KEY=sk_test_xxxxx
+NEXT_PUBLIC_LUMINA_NETWORK=testnet`}
+            language="env"
+            title=".env.local"
+          />
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">6. Package Dependencies</h2>
+          <CodeBlock
+            code={`{
+  "dependencies": {
+    "next": "^14.0.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "@lumina/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.0.0",
+    "typescript": "^5.0.0"
+  }
+}`}
+            language="json"
+            title="package.json (dependencies)"
+          />
+        </div>
+
+        <Callout type="success" title="Ready to Run">
+          This is a complete, working example. Just update the API key and run <code className="bg-black/40 px-2 py-1 rounded text-xs">npm run dev</code> to start!
+        </Callout>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">Next Steps</h2>
+          <ul className="space-y-2 text-foreground/80 text-sm">
+            <li className="flex gap-3">
+              <span className="text-emerald-400">▸</span>
+              <a href="/docs/guides/security" className="text-emerald-400 hover:underline">Add security features</a> - Implement best practices
+            </li>
+            <li className="flex gap-3">
+              <span className="text-emerald-400">▸</span>
+              <a href="/docs/examples/send-transaction" className="text-emerald-400 hover:underline">Add transactions</a> - Enable sending funds
+            </li>
+            <li className="flex gap-3">
+              <span className="text-emerald-400">▸</span>
+              <a href="/docs/guides/nextjs" className="text-emerald-400 hover:underline">Advanced setup</a> - Learn more features
+            </li>
+          </ul>
+        </div>
+      </div>
+    </>
+  )
+}