@jerydam/lumina-sdk 0.1.0

package/app/docs/guides/react/page.tsx

@@ -0,0 +1,230 @@
+import { Breadcrumb } from '@/components/docs/breadcrumb'
+import { CodeBlock } from '@/components/docs/code-block'
+import { Callout } from '@/components/docs/callout'
+
+export const metadata = {
+  title: 'React Integration Guide - Lumina Docs',
+  description: 'Complete guide to integrating Lumina SDK with React applications.',
+}
+
+export default function ReactGuidePage() {
+  return (
+    <>
+      <Breadcrumb />
+
+      <div className="space-y-8">
+        <div className="space-y-4">
+          <h1 className="text-4xl font-bold text-white">React Integration</h1>
+          <p className="text-lg text-foreground/80">
+            Step-by-step guide to integrating Lumina with React. This guide covers setup, authentication, and transaction handling.
+          </p>
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">Installation</h2>
+          <CodeBlock
+            code="npm install @lumina/sdk @lumina/react"
+            language="bash"
+          />
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">1. Wrap with LuminaProvider</h2>
+          <CodeBlock
+            code={`import React from 'react'
+import { LuminaProvider } from '@lumina/react'
+import App from './App'
+
+export default function Root() {
+  return (
+    <LuminaProvider
+      apiKey={process.env.REACT_APP_LUMINA_API_KEY}
+      network="mainnet"
+    >
+      <App />
+    </LuminaProvider>
+  )
+}
+
+// Render the root component
+// ReactDOM.createRoot(document.getElementById('root')).render(<Root />)`}
+            language="tsx"
+            title="main.tsx or index.tsx"
+          />
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">2. Use Hooks in Components</h2>
+          <CodeBlock
+            code={`'use client'
+
+import { useLumina } from '@lumina/react'
+
+export default function Dashboard() {
+  const { user, isConnected, logout } = useLumina()
+
+  if (!isConnected) {
+    return <div>Please connect your wallet</div>
+  }
+
+  return (
+    <div>
+      <h1>Welcome, {user?.email}!</h1>
+      <p>Address: {user?.walletAddress}</p>
+      <button onClick={logout}>Logout</button>
+    </div>
+  )
+}`}
+            language="tsx"
+          />
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">3. Authentication Flow</h2>
+          <CodeBlock
+            code={`import { WalletLogin } from '@lumina/react'
+import { useNavigate } from 'react-router-dom'
+
+export default function LoginPage() {
+  const navigate = useNavigate()
+
+  return (
+    <WalletLogin
+      onSuccess={(user) => {
+        console.log('Logged in:', user)
+        navigate('/dashboard')
+      }}
+      authMethods={['email', 'passkey', 'google']}
+    />
+  )
+}`}
+            language="tsx"
+          />
+        </div>
+
+        <Callout type="info" title="React Router Integration">
+          Lumina works seamlessly with React Router. Use the <code className="bg-black/40 px-2 py-1 rounded text-xs">useNavigate</code> hook in the <code className="bg-black/40 px-2 py-1 rounded text-xs">onSuccess</code> callback to redirect after authentication.
+        </Callout>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">4. Protected Routes</h2>
+          <CodeBlock
+            code={`import { useLumina } from '@lumina/react'
+import { Navigate } from 'react-router-dom'
+
+export function ProtectedRoute({ children }) {
+  const { isConnected } = useLumina()
+
+  if (!isConnected) {
+    return <Navigate to="/login" replace />
+  }
+
+  return children
+}
+
+// Usage
+<ProtectedRoute>
+  <Dashboard />
+</ProtectedRoute>`}
+            language="tsx"
+          />
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">5. Handling Transactions</h2>
+          <CodeBlock
+            code={`import { useLumina, TransactionConfirm } from '@lumina/react'
+import { useState } from 'react'
+
+export function SendFunds() {
+  const { user } = useLumina()
+  const [isPending, setIsPending] = useState(false)
+  const [txHash, setTxHash] = useState<string | null>(null)
+
+  const handleSend = async () => {
+    const tx = {
+      to: '0x742d35Cc6634C0532925a3b844Bc1e8181f42f9f',
+      value: '0.1',
+      network: 'ethereum',
+    }
+
+    setIsPending(true)
+    try {
+      const result = await user?.sendTransaction(tx)
+      setTxHash(result?.hash)
+    } catch (error) {
+      console.error('Transaction failed:', error)
+    } finally {
+      setIsPending(false)
+    }
+  }
+
+  return (
+    <div>
+      <button onClick={handleSend} disabled={isPending}>
+        {isPending ? 'Processing...' : 'Send 0.1 ETH'}
+      </button>
+      {txHash && <p>Transaction: {txHash}</p>}
+    </div>
+  )
+}`}
+            language="tsx"
+          />
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">Complete Example App</h2>
+          <CodeBlock
+            code={`import React, { useState } from 'react'
+import { LuminaProvider, WalletLogin, useLumina } from '@lumina/react'
+
+function Dashboard() {
+  const { user, logout } = useLumina()
+
+  return (
+    <div className="p-8">
+      <h1>Dashboard</h1>
+      <p>Welcome, {user?.email}</p>
+      <p>Balance: {user?.balance} ETH</p>
+      <button onClick={logout}>Logout</button>
+    </div>
+  )
+}
+
+function LoginPage({ onSuccess }) {
+  return (
+    <WalletLogin
+      onSuccess={(user) => {
+        onSuccess(user)
+      }}
+    />
+  )
+}
+
+export default function App() {
+  const [loggedIn, setLoggedIn] = useState(false)
+
+  return (
+    <LuminaProvider
+      apiKey={process.env.REACT_APP_LUMINA_API_KEY}
+      network="mainnet"
+    >
+      {loggedIn ? (
+        <Dashboard />
+      ) : (
+        <LoginPage onSuccess={() => setLoggedIn(true)} />
+      )}
+    </LuminaProvider>
+  )
+}`}
+            language="tsx"
+          />
+        </div>
+
+        <Callout type="success" title="React Guide Complete">
+          You now have everything you need to build a full React app with Lumina. Check out the <a href="/docs/guides/security" className="text-emerald-400 hover:underline">Security Guide</a> next.
+        </Callout>
+      </div>
+    </>
+  )
+}

package/app/docs/guides/security/page.tsx

@@ -0,0 +1,284 @@
+import { Breadcrumb } from '@/components/docs/breadcrumb'
+import { CodeBlock } from '@/components/docs/code-block'
+import { Callout } from '@/components/docs/callout'
+
+export const metadata = {
+  title: 'Security Best Practices - Lumina Guides',
+  description: 'Security best practices for integrating Lumina into your application.',
+}
+
+export default function SecurityPage() {
+  return (
+    <>
+      <Breadcrumb />
+
+      <div className="space-y-8">
+        <div className="space-y-4">
+          <h1 className="text-4xl font-bold text-white">Security Best Practices</h1>
+          <p className="text-lg text-foreground/80">
+            Learn how to securely integrate Lumina and protect your users&apos; assets.
+          </p>
+        </div>
+
+        <Callout type="warning" title="Security is Critical">
+          Wallet security is paramount. Follow these practices to ensure your users&apos; assets are protected.
+        </Callout>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">1. API Key Management</h2>
+          <p className="text-foreground/80 mb-4">
+            Your API keys are credentials that grant access to Lumina. Handle them with care.
+          </p>
+
+          <div className="space-y-3">
+            <div className="p-4 rounded-lg bg-white/5 border border-white/10">
+              <p className="font-semibold text-emerald-400 mb-2">Do&apos;s</p>
+              <ul className="space-y-1 text-sm text-foreground/80">
+                <li>✓ Store secret keys in environment variables only</li>
+                <li>✓ Rotate keys regularly (every 90 days)</li>
+                <li>✓ Use key scoping to limit permissions</li>
+                <li>✓ Monitor key usage in the dashboard</li>
+                <li>✓ Use different keys for dev, staging, and production</li>
+              </ul>
+            </div>
+
+            <div className="p-4 rounded-lg bg-white/5 border border-white/10">
+              <p className="font-semibold text-red-400 mb-2">Don&apos;ts</p>
+              <ul className="space-y-1 text-sm text-foreground/80">
+                <li>✗ Commit keys to version control</li>
+                <li>✗ Share keys via email or chat</li>
+                <li>✗ Expose secret keys in client-side code</li>
+                <li>✗ Use the same key for multiple environments</li>
+                <li>✗ Log or display keys to users</li>
+              </ul>
+            </div>
+          </div>
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">2. Environment Setup</h2>
+          <CodeBlock
+            code={`# .env.local (never commit this file)
+NEXT_PUBLIC_LUMINA_API_KEY=pk_prod_xxxxx
+LUMINA_SECRET_KEY=sk_prod_xxxxx
+NEXT_PUBLIC_LUMINA_NETWORK=mainnet
+
+# .env.example (safe to commit)
+NEXT_PUBLIC_LUMINA_API_KEY=your_public_key_here
+LUMINA_SECRET_KEY=your_secret_key_here
+NEXT_PUBLIC_LUMINA_NETWORK=mainnet`}
+            language="env"
+            title="Environment Variable Setup"
+          />
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">3. Transaction Verification</h2>
+          <p className="text-foreground/80 mb-4">
+            Always verify transactions before signing.
+          </p>
+
+          <CodeBlock
+            code={`'use client'
+
+import { TransactionConfirm } from '@lumina/sdk'
+
+export function SendFunds() {
+  const handleConfirm = async (txHash) => {
+    // Verify transaction on the blockchain
+    const receipt = await provider.getTransactionReceipt(txHash)
+    
+    if (receipt.status === 1) {
+      // Transaction confirmed
+      console.log('Transaction confirmed:', txHash)
+    } else {
+      // Transaction failed
+      console.error('Transaction failed')
+    }
+  }
+
+  return (
+    <TransactionConfirm
+      transaction={{
+        to: '0x...',
+        value: '1.0',
+        data: '0x...',
+        network: 'ethereum',
+      }}
+      onConfirm={handleConfirm}
+    />
+  )
+}`}
+            language="tsx"
+          />
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">4. SSL/TLS Configuration</h2>
+          <p className="text-foreground/80 mb-4">
+            Always use HTTPS in production and enforce it in your deployment:
+          </p>
+
+          <CodeBlock
+            code={`// next.config.mjs
+export default {
+  headers: async () => {
+    return [
+      {
+        source: '/:path*',
+        headers: [
+          {
+            key: 'Strict-Transport-Security',
+            value: 'max-age=31536000; includeSubDomains',
+          },
+          {
+            key: 'X-Content-Type-Options',
+            value: 'nosniff',
+          },
+          {
+            key: 'X-Frame-Options',
+            value: 'DENY',
+          },
+        ],
+      },
+    ]
+  },
+}`}
+            language="typescript"
+          />
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">5. Rate Limiting</h2>
+          <p className="text-foreground/80 mb-4">
+            Implement rate limiting on your API routes to prevent abuse.
+          </p>
+
+          <CodeBlock
+            code={`import { Ratelimit } from '@upstash/ratelimit'
+import { Redis } from '@upstash/redis'
+
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.fixedWindow(10, '1 h'),
+})
+
+export async function POST(request) {
+  const identifier = request.headers.get('x-forwarded-for')
+  const { success } = await ratelimit.limit(identifier)
+
+  if (!success) {
+    return Response.json(
+      { error: 'Rate limited' },
+      { status: 429 }
+    )
+  }
+
+  // Handle request
+}`}
+            language="typescript"
+          />
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">6. Input Validation</h2>
+          <p className="text-foreground/80 mb-4">
+            Always validate user input before sending to Lumina.
+          </p>
+
+          <CodeBlock
+            code={`import { isAddress } from 'ethers'
+
+export function validateTransaction(tx) {
+  // Validate recipient address
+  if (!isAddress(tx.to)) {
+    throw new Error('Invalid recipient address')
+  }
+
+  // Validate amount
+  if (parseFloat(tx.value) <= 0) {
+    throw new Error('Amount must be greater than 0')
+  }
+
+  // Validate network
+  const validNetworks = ['ethereum', 'polygon', 'arbitrum']
+  if (!validNetworks.includes(tx.network)) {
+    throw new Error('Invalid network')
+  }
+
+  return true
+}`}
+            language="typescript"
+          />
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">7. Error Handling</h2>
+          <p className="text-foreground/80 mb-4">
+            Don&apos;t expose sensitive information in error messages.
+          </p>
+
+          <CodeBlock
+            code={`// BAD - Exposes sensitive info
+console.log('API Key:', process.env.LUMINA_SECRET_KEY)
+
+// GOOD - Safe error handling
+try {
+  await lumina.sendTransaction(tx)
+} catch (error) {
+  // Log to secure monitoring service
+  logToSentry({
+    message: 'Transaction failed',
+    context: { userId, amount: tx.value },
+    // Don't include keys or sensitive data
+  })
+  
+  // Show generic message to user
+  showNotification('Transaction failed. Please try again.')
+}`}
+            language="typescript"
+          />
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">8. Audit Logging</h2>
+          <p className="text-foreground/80 mb-4">
+            Log important events for security auditing.
+          </p>
+
+          <CodeBlock
+            code={`interface AuditLog {
+  timestamp: Date
+  userId: string
+  action: string
+  resource: string
+  result: 'success' | 'failure'
+  details?: Record<string, unknown>
+}
+
+export async function logAuditEvent(event: AuditLog) {
+  await db.auditLogs.create({
+    ...event,
+    timestamp: new Date(),
+  })
+}`}
+            language="typescript"
+          />
+        </div>
+
+        <Callout type="success" title="Security Checklist">
+          Before deploying to production:
+          <ul className="mt-3 space-y-2 text-sm">
+            <li>✓ All API keys are in environment variables</li>
+            <li>✓ HTTPS is enforced</li>
+            <li>✓ Input validation is implemented</li>
+            <li>✓ Error handling is secure</li>
+            <li>✓ Rate limiting is enabled</li>
+            <li>✓ Audit logging is in place</li>
+            <li>✓ Security headers are configured</li>
+          </ul>
+        </Callout>
+      </div>
+    </>
+  )
+}

package/app/docs/layout.tsx

@@ -0,0 +1,32 @@
+'use client'
+
+import { useState } from 'react'
+import { DocsSidebar } from '@/components/docs/docs-sidebar'
+import { TableOfContents } from '@/components/docs/table-of-contents'
+
+export default function DocsLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  const [sidebarOpen, setSidebarOpen] = useState(false)
+
+  return (
+    <div className="flex h-screen overflow-hidden bg-background">
+      <DocsSidebar isOpen={sidebarOpen} onClose={() => setSidebarOpen(false)} />
+
+      <main className="flex-1 overflow-y-auto">
+        <div className="max-w-7xl mx-auto px-6 py-8">
+          <div className="flex gap-8">
+            <article className="flex-1 min-w-0">
+              {children}
+            </article>
+            <aside className="hidden xl:block w-5 shrink-0">
+              <TableOfContents />
+            </aside>
+          </div>
+        </div>
+      </main>
+    </div>
+  )
+}