@jerydam/lumina-sdk 0.1.0

package/app/docs/sdk/wallet-login/page.tsx

@@ -0,0 +1,207 @@
+import { Breadcrumb } from '@/components/docs/breadcrumb'
+import { CodeBlock } from '@/components/docs/code-block'
+import { Callout } from '@/components/docs/callout'
+
+export const metadata = {
+  title: 'WalletLogin - SDK Reference',
+  description: 'Add authentication to your app with the WalletLogin component.',
+}
+
+export default function WalletLoginPage() {
+  return (
+    <>
+      <Breadcrumb />
+
+      <div className="space-y-8">
+        <div className="space-y-4">
+          <h1 className="text-4xl font-bold text-white">WalletLogin</h1>
+          <p className="text-lg text-foreground/80">
+            A complete authentication component supporting email, passkeys, and social login. Handles user registration and login flows automatically.
+          </p>
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">Basic Usage</h2>
+          <CodeBlock
+            code={`'use client'
+
+import { WalletLogin } from '@lumina/sdk'
+
+export default function LoginPage() {
+  return (
+    <div className="flex items-center justify-center min-h-screen">
+      <WalletLogin
+        onSuccess={(user) => {
+          console.log('User logged in:', user)
+          // Redirect or update state
+        }}
+        onError={(error) => {
+          console.error('Login error:', error)
+        }}
+      />
+    </div>
+  )
+}`}
+            language="tsx"
+          />
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">Props</h2>
+          <div className="space-y-4">
+            <div className="p-4 rounded-lg bg-white/5 border border-white/10">
+              <p className="font-semibold text-emerald-400 mb-2">onSuccess</p>
+              <p className="text-sm text-foreground/80 mb-2">
+                <span className="text-red-400">Required</span> • <span className="text-blue-400">(user: User) =&gt; void</span>
+              </p>
+              <p className="text-sm text-foreground/80">
+                Callback when authentication is successful.
+              </p>
+            </div>
+
+            <div className="p-4 rounded-lg bg-white/5 border border-white/10">
+              <p className="font-semibold text-emerald-400 mb-2">onError</p>
+              <p className="text-sm text-foreground/80 mb-2">
+                <span className="text-green-400">Optional</span> • <span className="text-blue-400">(error: Error) =&gt; void</span>
+              </p>
+              <p className="text-sm text-foreground/80">
+                Callback when authentication fails.
+              </p>
+            </div>
+
+            <div className="p-4 rounded-lg bg-white/5 border border-white/10">
+              <p className="font-semibold text-emerald-400 mb-2">authMethods</p>
+              <p className="text-sm text-foreground/80 mb-2">
+                <span className="text-green-400">Optional</span> • <span className="text-blue-400">('email' | 'passkey' | 'google' | 'discord')[]</span>
+              </p>
+              <p className="text-sm text-foreground/80 mb-3">
+                Authentication methods to display. All supported by default.
+              </p>
+              <CodeBlock
+                code={`<WalletLogin
+  authMethods={['email', 'passkey']}
+  onSuccess={handleSuccess}
+/>`}
+                language="tsx"
+              />
+            </div>
+
+            <div className="p-4 rounded-lg bg-white/5 border border-white/10">
+              <p className="font-semibold text-emerald-400 mb-2">redirectUrl</p>
+              <p className="text-sm text-foreground/80 mb-2">
+                <span className="text-green-400">Optional</span> • <span className="text-blue-400">string</span>
+              </p>
+              <p className="text-sm text-foreground/80">
+                URL to redirect to after successful login. If not provided, uses onSuccess callback only.
+              </p>
+            </div>
+
+            <div className="p-4 rounded-lg bg-white/5 border border-white/10">
+              <p className="font-semibold text-emerald-400 mb-2">className</p>
+              <p className="text-sm text-foreground/80 mb-2">
+                <span className="text-green-400">Optional</span> • <span className="text-blue-400">string</span>
+              </p>
+              <p className="text-sm text-foreground/80">
+                Custom CSS classes to style the component.
+              </p>
+            </div>
+          </div>
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">With Redirect</h2>
+          <CodeBlock
+            code={`<WalletLogin
+  authMethods={['email', 'passkey', 'google']}
+  redirectUrl="/dashboard"
+  onError={(error) => {
+    console.error('Login failed:', error.message)
+  }}
+/>`}
+            language="tsx"
+          />
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">Authentication Methods</h2>
+          <p className="text-foreground/80 mb-4">
+            WalletLogin supports multiple authentication methods:
+          </p>
+          <div className="space-y-3">
+            <div className="p-4 rounded-lg bg-white/5 border border-white/10">
+              <p className="font-semibold text-foreground mb-2">Email</p>
+              <p className="text-sm text-foreground/80">
+                Magic link or password-based authentication. Users receive a verification email.
+              </p>
+            </div>
+
+            <div className="p-4 rounded-lg bg-white/5 border border-white/10">
+              <p className="font-semibold text-foreground mb-2">Passkey</p>
+              <p className="text-sm text-foreground/80">
+                WebAuthn-based passwordless authentication using biometrics or security keys.
+              </p>
+            </div>
+
+            <div className="p-4 rounded-lg bg-white/5 border border-white/10">
+              <p className="font-semibold text-foreground mb-2">Social (Google, Discord)</p>
+              <p className="text-sm text-foreground/80">
+                One-click login using existing social accounts. Requires OAuth configuration.
+              </p>
+            </div>
+          </div>
+        </div>
+
+        <Callout type="info" title="User Object Structure">
+          <CodeBlock
+            code={`interface User {
+  id: string
+  email: string
+  walletAddress: string
+  balance: string
+  authMethod: 'email' | 'passkey' | 'google' | 'discord'
+  createdAt: Date
+}`}
+            language="typescript"
+          />
+        </Callout>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">Error Handling</h2>
+          <CodeBlock
+            code={`<WalletLogin
+  onSuccess={(user) => {
+    // Handle successful login
+  }}
+  onError={(error) => {
+    if (error.code === 'EMAIL_ALREADY_EXISTS') {
+      // Show "Please use login instead" message
+    } else if (error.code === 'INVALID_EMAIL') {
+      // Show "Invalid email address" message
+    } else {
+      // Show generic error
+      console.error(error)
+    }
+  }}
+/>`}
+            language="tsx"
+          />
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">Custom Styling</h2>
+          <CodeBlock
+            code={`<WalletLogin
+  onSuccess={handleSuccess}
+  className="bg-emerald-900/50 border-2 border-emerald-500"
+/>`}
+            language="tsx"
+          />
+        </div>
+
+        <Callout type="warning" title="OAuth Setup Required">
+          To enable Google and Discord login, you need to configure OAuth credentials in the Lumina dashboard. See the <a href="/docs/guides/security" className="text-emerald-400 hover:underline">Security Guide</a> for details.
+        </Callout>
+      </div>
+    </>
+  )
+}

package/app/docs/troubleshooting/common-issues/page.tsx

@@ -0,0 +1,301 @@
+'use client'
+
+import { Breadcrumb } from '@/components/docs/breadcrumb'
+import { CodeBlock } from '@/components/docs/code-block'
+import { Callout } from '@/components/docs/callout'
+
+export default function CommonIssuesPage() {
+  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: 'Troubleshooting', href: '/docs/troubleshooting/faq' },
+            { label: 'Common Issues' },
+          ]}
+        />
+
+        <div className="mt-8 prose prose-invert max-w-none">
+          <h1>Common Issues & Solutions</h1>
+          
+          <p className="text-lg text-foreground/80">
+            Solutions to frequently encountered problems when using Lumina.
+          </p>
+
+          <h2>Authentication Issues</h2>
+
+          <h3>Error: "Invalid API Key"</h3>
+          <Callout type="error">
+            The API key provided is invalid or has expired.
+          </Callout>
+
+          <p>
+            <strong>Causes:</strong>
+          </p>
+          <ul>
+            <li>API key is malformed or incomplete</li>
+            <li>API key has been revoked</li>
+            <li>Using test key in production (or vice versa)</li>
+            <li>API key is missing the <code>Bearer</code> prefix</li>
+          </ul>
+
+          <p>
+            <strong>Solution:</strong>
+          </p>
+          <CodeBlock
+            code={`// ❌ Wrong
+Authorization: sk_live_abc123...
+
+// ✓ Correct
+Authorization: Bearer sk_live_abc123...
+
+// Verify your API key
+curl -X GET https://api.lumina.dev/v1/wallets \\
+  -H "Authorization: Bearer sk_live_abc123..."`}
+            language="bash"
+            title="Authorization Format"
+          />
+
+          <h3>Error: "NEXT_PUBLIC_LUMINA_PUBLIC_KEY is undefined"</h3>
+          <p>
+            <strong>Cause:</strong> Environment variable not set in your application.
+          </p>
+
+          <p>
+            <strong>Solution:</strong>
+          </p>
+          <CodeBlock
+            code={`# .env.local
+NEXT_PUBLIC_LUMINA_PUBLIC_KEY=pk_live_abc123def456...
+
+# After adding, restart your dev server:
+# npm run dev
+
+# Verify it's loaded:
+console.log(process.env.NEXT_PUBLIC_LUMINA_PUBLIC_KEY)`}
+            language="bash"
+            title="Environment Setup"
+          />
+
+          <h2>Wallet Issues</h2>
+
+          <h3>Error: "INSUFFICIENT_BALANCE"</h3>
+          <p>
+            <strong>Cause:</strong> Wallet doesn't have enough funds for the transaction.
+          </p>
+
+          <p>
+            <strong>Solution:</strong>
+          </p>
+          <CodeBlock
+            code={`// Check balance before transaction
+const wallet = await fetch(\`/api/wallets/\${walletId}\`)
+const { balance } = wallet.data
+
+// Verify sufficient balance
+const required = '1.5'
+if (parseFloat(balance) < parseFloat(required)) {
+  console.error('Insufficient balance')
+  // Fund the wallet or show error to user
+}`}
+            language="typescript"
+            title="Balance Check"
+          />
+
+          <h3>Error: "Wallet Not Found"</h3>
+          <p>
+            <strong>Cause:</strong> Wallet ID is invalid or doesn't exist.
+          </p>
+
+          <p>
+            <strong>Solution:</strong>
+          </p>
+          <CodeBlock
+            code={`// List wallets to verify IDs
+const response = await fetch('/api/wallets?user_id=user_123')
+const { wallets } = response.json()
+
+console.log('Available wallets:', wallets.map(w => w.id))
+
+// Use correct wallet ID
+const correctWalletId = wallets[0].id`}
+            language="typescript"
+            title="List Wallets"
+          />
+
+          <h2>Transaction Issues</h2>
+
+          <h3>Error: "Transaction Failed"</h3>
+          <p>
+            <strong>Causes:</strong>
+          </p>
+          <ul>
+            <li>Insufficient gas fees</li>
+            <li>Network congestion</li>
+            <li>Invalid recipient address</li>
+            <li>Smart contract revert</li>
+          </ul>
+
+          <p>
+            <strong>Solution:</strong>
+          </p>
+          <CodeBlock
+            code={`// Get detailed error information
+const response = await fetch('/api/transactions/txn_123/details')
+const { error, details } = response.json()
+
+console.log('Error code:', error.code)
+console.log('Reason:', details.revert_reason)
+
+// Retry with higher gas price
+const txResponse = await fetch('/api/transactions', {
+  method: 'POST',
+  body: JSON.stringify({
+    ...txData,
+    gas_price: '150', // Increase from 100
+  }),
+})`}
+            language="typescript"
+            title="Transaction Details"
+          />
+
+          <h3>Error: "Gas Estimation Failed"</h3>
+          <p>
+            <strong>Cause:</strong> Unable to estimate gas for the transaction (usually contract-related).
+          </p>
+
+          <p>
+            <strong>Solution:</strong>
+          </p>
+          <CodeBlock
+            code={`// Try with explicit gas limit
+const response = await fetch('/api/transactions', {
+  method: 'POST',
+  body: JSON.stringify({
+    wallet_id: walletId,
+    to: recipient,
+    amount: '1.0',
+    gas_limit: '100000', // Provide explicit gas limit
+    skip_gas_estimation: false,
+  }),
+})`}
+            language="typescript"
+            title="Explicit Gas Limit"
+          />
+
+          <h2>Network Issues</h2>
+
+          <h3>Error: "Network Error" or Timeout</h3>
+          <p>
+            <strong>Cause:</strong> Network connectivity issue or API service unavailable.
+          </p>
+
+          <p>
+            <strong>Solution:</strong>
+          </p>
+          <CodeBlock
+            code={`// Implement retry logic with exponential backoff
+async function apiCallWithRetry(url, options, attempt = 1) {
+  try {
+    const response = await fetch(url, {
+      ...options,
+      signal: AbortSignal.timeout(30000), // 30 second timeout
+    })
+    return response
+  } catch (error) {
+    if (attempt < 3 && error.name === 'AbortError') {
+      const delay = Math.pow(2, attempt - 1) * 1000
+      console.log(\`Retry attempt \${attempt} in \${delay}ms\`)
+      await new Promise(r => setTimeout(r, delay))
+      return apiCallWithRetry(url, options, attempt + 1)
+    }
+    throw error
+  }
+}`}
+            language="typescript"
+            title="Retry Logic"
+          />
+
+          <h2>Rate Limiting</h2>
+
+          <h3>Error: "Rate Limit Exceeded" (429)</h3>
+          <p>
+            <strong>Cause:</strong> Too many requests in a short period.
+          </p>
+
+          <p>
+            <strong>Solution:</strong>
+          </p>
+          <CodeBlock
+            code={`// Check rate limit headers
+const response = await fetch(url)
+
+const rateLimit = {
+  limit: response.headers.get('X-RateLimit-Limit'),
+  remaining: response.headers.get('X-RateLimit-Remaining'),
+  reset: response.headers.get('X-RateLimit-Reset'),
+}
+
+if (response.status === 429) {
+  const resetTime = parseInt(rateLimit.reset) * 1000
+  const waitMs = resetTime - Date.now()
+  
+  console.log(\`Rate limited. Wait \${waitMs}ms until \${new Date(resetTime)}\`)
+  
+  // Wait before retrying
+  await new Promise(r => setTimeout(r, waitMs))
+}`}
+            language="typescript"
+            title="Rate Limit Handling"
+          />
+
+          <h2>Development Issues</h2>
+
+          <h3>Hot Reload Not Working</h3>
+          <p>
+            <strong>Solution:</strong> Restart dev server after changing environment variables.
+          </p>
+          <CodeBlock
+            code={`# Stop the dev server
+Ctrl+C
+
+# Restart it
+npm run dev`}
+            language="bash"
+            title="Restart Dev Server"
+          />
+
+          <h3>CORS Errors</h3>
+          <p>
+            <strong>Solution:</strong> Use API routes instead of calling Lumina API directly from client.
+          </p>
+          <CodeBlock
+            code={`// ❌ Wrong - CORS error
+const data = await fetch('https://api.lumina.dev/v1/wallets', {
+  headers: { 'Authorization': 'Bearer ...' }
+})
+
+// ✓ Correct - Use API route
+const data = await fetch('/api/wallets')`}
+            language="typescript"
+            title="Avoid CORS"
+          />
+
+          <Callout type="info">
+            Check the request_id in error responses. Include it when contacting support for faster troubleshooting.
+          </Callout>
+        </div>
+
+        <div className="flex justify-between mt-12 pt-8 border-t border-white/10">
+          <a href="/docs/troubleshooting/faq" className="text-emerald-400 hover:text-emerald-300">
+            ← FAQ
+          </a>
+          <a href="/docs/guides/security" className="text-emerald-400 hover:text-emerald-300">
+            Security Guide →
+          </a>
+        </div>
+      </main>
+    </div>
+  )
+}

package/app/docs/troubleshooting/faq/page.tsx

@@ -0,0 +1,105 @@
+import { Breadcrumb } from '@/components/docs/breadcrumb'
+import { Callout } from '@/components/docs/callout'
+
+export const metadata = {
+  title: 'FAQ - Lumina Documentation',
+  description: 'Frequently asked questions about Lumina.',
+}
+
+export default function FAQPage() {
+  const faqs = [
+    {
+      question: 'What is Lumina?',
+      answer:
+        'Lumina is an embedded wallet infrastructure that allows developers to integrate secure, user-friendly wallet functionality into their applications without requiring users to install external wallets.',
+    },
+    {
+      question: 'Which blockchains does Lumina support?',
+      answer:
+        'Lumina supports Ethereum, Polygon, Arbitrum, Optimism, Base, Avalanche, and more. You can configure which chains to support in your LuminaProvider configuration.',
+    },
+    {
+      question: 'Is Lumina free to use?',
+      answer:
+        'Lumina offers a free tier for development and testing. Production use requires a paid plan. Check our pricing page for details.',
+    },
+    {
+      question: 'How do I get an API key?',
+      answer:
+        'Sign up for free at our dashboard and create a new API key. You\'ll get both a public key (for client-side use) and a secret key (for server-side use).',
+    },
+    {
+      question: 'Can I use Lumina with Next.js?',
+      answer:
+        'Absolutely! Lumina works great with Next.js. See our Next.js Integration guide for best practices and setup instructions.',
+    },
+    {
+      question: 'What authentication methods does Lumina support?',
+      answer:
+        'Lumina supports email, passkeys, Google OAuth, and Discord OAuth. You can enable/disable specific methods in your configuration.',
+    },
+    {
+      question: 'Is my key secure?',
+      answer:
+        'Yes. Lumina uses industry-standard encryption and key management practices. Keys are stored securely on our infrastructure and are never exposed.',
+    },
+    {
+      question: 'Can I customize the UI components?',
+      answer:
+        'Yes. All Lumina components support custom styling via CSS classes. You can also use composition to create custom layouts.',
+    },
+    {
+      question: 'How do I test with testnet?',
+      answer:
+        'Set NEXT_PUBLIC_LUMINA_NETWORK=testnet in your environment variables. Testnet uses Sepolia, Goerli, and other test networks.',
+    },
+    {
+      question: 'What\'s the difference between public and secret API keys?',
+      answer:
+        'Public keys are exposed to clients and should be used in browser code. Secret keys must be kept private and only used server-side. Never expose your secret key.',
+    },
+    {
+      question: 'Can I use Lumina in production?',
+      answer:
+        'Yes, but you need a production API key with appropriate rate limits and security settings. Contact our sales team for enterprise plans.',
+    },
+    {
+      question: 'How do I handle errors in my integration?',
+      answer:
+        'All Lumina components support onError callbacks. See our Error Handling guide for best practices.',
+    },
+  ]
+
+  return (
+    <>
+      <Breadcrumb />
+
+      <div className="space-y-8">
+        <div className="space-y-4">
+          <h1 className="text-4xl font-bold text-white">Frequently Asked Questions</h1>
+          <p className="text-lg text-foreground/80">
+            Find answers to common questions about Lumina
+          </p>
+        </div>
+
+        <div className="space-y-6">
+          {faqs.map((faq, index) => (
+            <details key={index} className="group p-6 rounded-lg border border-white/10 hover:border-emerald-600/30 transition-colors cursor-pointer">
+              <summary className="flex items-center justify-between font-semibold text-lg text-foreground cursor-pointer">
+                <span className="group-open:text-emerald-400">{faq.question}</span>
+                <span className="text-2xl text-foreground/50 group-open:text-emerald-400 group-open:rotate-180 transition-transform">
+                  ▶
+                </span>
+              </summary>
+              <p className="mt-4 text-foreground/80">{faq.answer}</p>
+            </details>
+          ))}
+        </div>
+
+        <Callout type="info" title="Still have questions?">
+          If you can&apos;t find the answer you&apos;re looking for, reach out to our support team at support@lumina.dev or join our Discord community.
+        </Callout>
+      </div>
+    </>
+  )
+}