moai-adk 0.8.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-platform-clerk/modules/advanced-patterns.md

@@ -0,0 +1,417 @@
+# Clerk Advanced Patterns
+
+Extended patterns for Core 2 migration, role-based access control, and webhook integration.
+
+## Core 2 Migration Patterns
+
+Environment variable changes:
+
+```bash
+# Core 1 (deprecated)
+CLERK_FRONTEND_API=clerk.xxx.lcl.dev
+CLERK_API_KEY=sk_xxx
+
+# Core 2 (current)
+NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxx
+CLERK_SECRET_KEY=sk_test_xxx
+```
+
+Middleware migration from authMiddleware to clerkMiddleware:
+
+```typescript
+// Core 1 (deprecated) - DO NOT USE
+import { authMiddleware } from '@clerk/nextjs'
+export default authMiddleware()
+
+// Core 2 (current) - USE THIS
+import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'
+
+const isPublicRoute = createRouteMatcher(['/sign-in(.*)', '/sign-up(.*)'])
+
+export default clerkMiddleware(async (auth, request) => {
+  if (!isPublicRoute(request)) {
+    await auth.protect()
+  }
+})
+```
+
+Server imports changed path:
+
+```typescript
+// Core 1 (deprecated)
+import { auth } from '@clerk/nextjs'
+
+// Core 2 (current)
+import { auth } from '@clerk/nextjs/server'
+```
+
+setSession replaced with setActive:
+
+```typescript
+// Core 1 (deprecated)
+await setSession(sessionObj, () => void)
+
+// Core 2 (current)
+await setActive({ session: sessionObj, beforeEmit: () => void })
+```
+
+Image property consolidation:
+
+```typescript
+// Core 1 (deprecated)
+user.profileImageUrl
+organization.logoUrl
+externalAccount.avatarUrl
+
+// Core 2 (current)
+user.imageUrl
+organization.imageUrl
+externalAccount.imageUrl
+```
+
+Pagination argument changes:
+
+```typescript
+// Core 1 (deprecated)
+{ limit: 10, offset: 0 }
+
+// Core 2 (current)
+{ pageSize: 10, initialPage: 1 }
+```
+
+## Role-Based Access Control
+
+Protecting routes by permission:
+
+```typescript
+// middleware.ts
+import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'
+
+const isAdminRoute = createRouteMatcher(['/admin(.*)'])
+const isMemberRoute = createRouteMatcher(['/dashboard(.*)'])
+
+export default clerkMiddleware(async (auth, req) => {
+  if (isAdminRoute(req)) {
+    await auth.protect((has) => has({ permission: 'org:admin:access' }))
+  }
+
+  if (isMemberRoute(req)) {
+    await auth.protect()
+  }
+})
+```
+
+Checking permissions in components:
+
+```tsx
+'use client'
+import { useAuth } from '@clerk/nextjs'
+
+export function AdminPanel() {
+  const { has, isLoaded } = useAuth()
+
+  if (!isLoaded) {
+    return <div>Loading...</div>
+  }
+
+  const isAdmin = has?.({ permission: 'org:admin:access' })
+
+  if (!isAdmin) {
+    return <div>Access denied</div>
+  }
+
+  return <div>Admin Panel Content</div>
+}
+```
+
+Protecting with organization roles:
+
+```typescript
+// middleware.ts
+import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'
+
+const isOrgAdminRoute = createRouteMatcher(['/org/(.*)/settings(.*)'])
+
+export default clerkMiddleware(async (auth, req) => {
+  if (isOrgAdminRoute(req)) {
+    await auth.protect((has) => has({ role: 'org:admin' }))
+  }
+})
+```
+
+## Webhook Integration
+
+Webhook handler example:
+
+```typescript
+// app/api/webhooks/clerk/route.ts
+import { Webhook } from 'svix'
+import { headers } from 'next/headers'
+import { WebhookEvent } from '@clerk/nextjs/server'
+
+export async function POST(req: Request) {
+  const WEBHOOK_SECRET = process.env.CLERK_WEBHOOK_SECRET
+
+  if (!WEBHOOK_SECRET) {
+    throw new Error('Missing CLERK_WEBHOOK_SECRET')
+  }
+
+  const headerPayload = await headers()
+  const svix_id = headerPayload.get('svix-id')
+  const svix_timestamp = headerPayload.get('svix-timestamp')
+  const svix_signature = headerPayload.get('svix-signature')
+
+  if (!svix_id || !svix_timestamp || !svix_signature) {
+    return new Response('Missing svix headers', { status: 400 })
+  }
+
+  const payload = await req.json()
+  const body = JSON.stringify(payload)
+
+  const wh = new Webhook(WEBHOOK_SECRET)
+  let evt: WebhookEvent
+
+  try {
+    evt = wh.verify(body, {
+      'svix-id': svix_id,
+      'svix-timestamp': svix_timestamp,
+      'svix-signature': svix_signature,
+    }) as WebhookEvent
+  } catch (err) {
+    return new Response('Invalid signature', { status: 400 })
+  }
+
+  const eventType = evt.type
+
+  if (eventType === 'user.created') {
+    const { id, email_addresses, first_name, last_name } = evt.data
+    // Sync user to your database
+  }
+
+  if (eventType === 'user.updated') {
+    const { id, first_name, last_name } = evt.data
+    // Update user in your database
+  }
+
+  if (eventType === 'user.deleted') {
+    const { id } = evt.data
+    // Handle user deletion
+  }
+
+  if (eventType === 'organization.created') {
+    const { id, name, slug } = evt.data
+    // Create organization in your database
+  }
+
+  return new Response('Webhook received', { status: 200 })
+}
+```
+
+## Custom Authentication Flows
+
+Custom sign-in with useSignIn:
+
+```tsx
+'use client'
+import { useSignIn } from '@clerk/nextjs'
+import { useState } from 'react'
+
+export function CustomSignIn() {
+  const { signIn, isLoaded, setActive } = useSignIn()
+  const [email, setEmail] = useState('')
+  const [password, setPassword] = useState('')
+  const [error, setError] = useState('')
+
+  if (!isLoaded) {
+    return <div>Loading...</div>
+  }
+
+  async function handleSubmit(e: React.FormEvent) {
+    e.preventDefault()
+    setError('')
+
+    try {
+      const result = await signIn.create({
+        identifier: email,
+        password,
+      })
+
+      if (result.status === 'complete') {
+        await setActive({ session: result.createdSessionId })
+      }
+    } catch (err: any) {
+      setError(err.errors?.[0]?.message || 'Sign in failed')
+    }
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input
+        type="email"
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+        placeholder="Email"
+      />
+      <input
+        type="password"
+        value={password}
+        onChange={(e) => setPassword(e.target.value)}
+        placeholder="Password"
+      />
+      {error && <p className="text-red-500">{error}</p>}
+      <button type="submit">Sign In</button>
+    </form>
+  )
+}
+```
+
+Custom sign-up with useSignUp:
+
+```tsx
+'use client'
+import { useSignUp } from '@clerk/nextjs'
+import { useState } from 'react'
+import { useRouter } from 'next/navigation'
+
+export function CustomSignUp() {
+  const { signUp, isLoaded, setActive } = useSignUp()
+  const [email, setEmail] = useState('')
+  const [password, setPassword] = useState('')
+  const [code, setCode] = useState('')
+  const [pendingVerification, setPendingVerification] = useState(false)
+  const router = useRouter()
+
+  if (!isLoaded) {
+    return <div>Loading...</div>
+  }
+
+  async function handleSubmit(e: React.FormEvent) {
+    e.preventDefault()
+
+    try {
+      await signUp.create({
+        emailAddress: email,
+        password,
+      })
+
+      await signUp.prepareEmailAddressVerification({
+        strategy: 'email_code',
+      })
+
+      setPendingVerification(true)
+    } catch (err: any) {
+      console.error(err.errors?.[0]?.message)
+    }
+  }
+
+  async function handleVerify(e: React.FormEvent) {
+    e.preventDefault()
+
+    try {
+      const result = await signUp.attemptEmailAddressVerification({
+        code,
+      })
+
+      if (result.status === 'complete') {
+        await setActive({ session: result.createdSessionId })
+        router.push('/dashboard')
+      }
+    } catch (err: any) {
+      console.error(err.errors?.[0]?.message)
+    }
+  }
+
+  if (pendingVerification) {
+    return (
+      <form onSubmit={handleVerify}>
+        <input
+          type="text"
+          value={code}
+          onChange={(e) => setCode(e.target.value)}
+          placeholder="Verification code"
+        />
+        <button type="submit">Verify</button>
+      </form>
+    )
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input
+        type="email"
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+        placeholder="Email"
+      />
+      <input
+        type="password"
+        value={password}
+        onChange={(e) => setPassword(e.target.value)}
+        placeholder="Password"
+      />
+      <button type="submit">Sign Up</button>
+    </form>
+  )
+}
+```
+
+## Integration with External Services
+
+Clerk with Supabase:
+
+```typescript
+// lib/supabase.ts
+import { createClient } from '@supabase/supabase-js'
+import { auth } from '@clerk/nextjs/server'
+
+export async function createClerkSupabaseClient() {
+  const { getToken } = await auth()
+  const supabaseToken = await getToken({ template: 'supabase' })
+
+  return createClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+    {
+      global: {
+        headers: {
+          Authorization: `Bearer ${supabaseToken}`,
+        },
+      },
+    }
+  )
+}
+```
+
+Clerk with Convex:
+
+```typescript
+// convex/auth.config.ts
+export default {
+  providers: [
+    {
+      domain: process.env.CLERK_JWT_ISSUER_DOMAIN,
+      applicationID: "convex",
+    },
+  ],
+}
+```
+
+```tsx
+// app/providers.tsx
+'use client'
+import { ClerkProvider, useAuth } from '@clerk/nextjs'
+import { ConvexProviderWithClerk } from 'convex/react-clerk'
+import { ConvexReactClient } from 'convex/react'
+
+const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!)
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <ClerkProvider>
+      <ConvexProviderWithClerk client={convex} useAuth={useAuth}>
+        {children}
+      </ConvexProviderWithClerk>
+    </ClerkProvider>
+  )
+}
+```

moai_adk/templates/.claude/skills/moai-platform-clerk/reference.md

@@ -0,0 +1,273 @@
+# Clerk Modern Authentication - Reference Documentation
+
+## Official Resources
+
+### Core Documentation
+- **Clerk Documentation**: https://clerk.com/docs
+  - Complete documentation hub
+  - Getting started guides
+  - API references
+
+- **Quickstart Guides**: https://clerk.com/docs/quickstarts
+  - Next.js quickstart
+  - React quickstart
+  - Express quickstart
+  - Remix quickstart
+
+- **SDK Reference**: https://clerk.com/docs/reference
+  - JavaScript SDK
+  - React hooks
+  - Server SDKs
+  - Backend APIs
+
+### Framework-Specific Documentation
+
+#### Next.js Integration
+- **Next.js Documentation**: https://clerk.com/docs/quickstarts/nextjs
+  - App Router setup
+  - Middleware configuration
+  - Server components
+  - Route handlers
+
+- **Core 2 Migration Guide**: https://clerk.com/docs/guides/development/upgrading/upgrade-guides/core-2/nextjs
+  - Breaking changes
+  - Migration tool: `npx @clerk/upgrade --from=core-1`
+  - Environment variable changes
+  - API updates
+
+#### React Integration
+- **Clerk React SDK**: https://clerk.com/docs/reference/clerk-react
+  - useAuth hook
+  - useUser hook
+  - Components reference
+  - TypeScript types
+
+- **React Reference**: https://clerk.com/docs/reference/js
+  - Clerk object
+  - Authentication methods
+  - Session management
+
+### Authentication Features
+
+#### WebAuthn & Passkeys
+- **WebAuthn Guide**: https://clerk.com/docs/reference/javascript/webauthn
+  - Passkey configuration
+  - Biometric authentication
+  - Security key setup
+
+- **Passwordless Authentication**: https://clerk.com/docs/reference/javascript/passwordless
+  - Magic links
+  - Email codes
+  - Phone verification
+
+#### Multi-Factor Authentication
+- **MFA Guide**: https://clerk.com/docs/authentication/mfa
+  - TOTP setup
+  - Backup codes
+  - MFA policies
+
+#### Organization Management
+- **Organizations**: https://clerk.com/docs/organizations
+  - Organization creation
+  - Member management
+  - Role-based access
+  - Organization switching
+
+### API Reference
+
+#### JavaScript SDK
+- **Clerk JavaScript**: https://clerk.com/docs/reference/javascript
+  - Client initialization
+  - Authentication methods
+  - Session handling
+  - User management
+
+#### React Hooks
+- **useAuth**: https://clerk.com/docs/reference/clerk-react/use-auth
+  - Authentication state
+  - Token access
+  - Session management
+
+- **useUser**: https://clerk.com/docs/reference/clerk-react/use-user
+  - User profile data
+  - User metadata
+  - Profile updates
+
+- **useOrganization**: https://clerk.com/docs/reference/clerk-react/use-organization
+  - Organization context
+  - Membership data
+  - Organization switching
+
+#### Server SDKs
+- **Next.js Server**: https://clerk.com/docs/reference/nextjs
+  - auth() function
+  - currentUser()
+  - Middleware helpers
+
+- **Express Server**: https://clerk.com/docs/reference/express
+  - ClerkExpressRequireAuth
+  - requireMiddleware
+  - Session handling
+
+#### Backend API
+- **Backend API**: https://clerk.com/docs/reference/backend-api
+  - User management
+  - Organization management
+  - Token verification
+  - Webhook handling
+
+### Components Reference
+
+#### Authentication Components
+- **SignIn**: https://clerk.com/docs/components/sign-in
+  - Sign-in page configuration
+  - Flow customization
+  - Redirect handling
+
+- **SignUp**: https://clerk.com/docs/components/sign-up
+  - Sign-up page configuration
+  - Field customization
+  - Verification flows
+
+- **UserButton**: https://clerk.com/docs/components/user-button
+  - User menu component
+  - Account management
+  - Sign-out functionality
+
+- **OrganizationSwitcher**: https://clerk.com/docs/components/organization-switcher
+  - Organization selection
+  - Organization creation
+  - Custom styling
+
+### Configuration & Settings
+
+#### Environment Variables
+- **Configuration Reference**: https://clerk.com/docs/guides/configuration
+  - NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
+  - CLERK_SECRET_KEY
+  - NEXT_PUBLIC_CLERK_SIGN_IN_URL
+  - NEXT_PUBLIC_CLERK_SIGN_UP_URL
+
+#### Middleware
+- **Middleware Guide**: https://clerk.com/docs/nextjs/middleware
+  - Route protection
+  - createRouteMatcher
+  - Clerk middleware setup
+
+### Webhooks & Events
+
+- **Webhooks**: https://clerk.com/docs/integrations/webhooks
+  - Event types
+  - Webhook setup
+  - Signature verification
+  - Svix integration
+
+### Security & Compliance
+
+- **Security Best Practices**: https://clerk.com/docs/guides/security
+  - Token security
+  - Session management
+  - CORS configuration
+  - Rate limiting
+
+- **Compliance**: https://clerk.com/docs/compliance
+  - GDPR compliance
+  - SOC 2 certification
+  - Data residency
+  - Privacy policy
+
+### Context7 Integration
+
+- **Library ID**: /clerk/clerk-docs
+- **Resolution**: Use `mcp__context7__resolve-library-id` with query "clerk"
+- **Documentation**: Use `mcp__context7__get-library-docs` for latest docs
+
+### Module Organization
+
+This skill contains 1 module:
+
+- `modules/advanced-patterns.md` - Advanced implementation patterns including:
+  - Core 2 migration details
+  - Role-based access control (RBAC)
+  - Webhook integration
+  - Custom authentication flows
+  - External service integration
+  - Performance optimization
+  - Testing strategies
+
+### Community & Support
+
+- **Clerk Discord**: https://discord.gg/v5qHfQPW2g
+  - Community chat
+  - Real-time support
+  - Feature discussions
+
+- **GitHub Discussions**: https://github.com/clerk/javascript/discussions
+  - Q&A threads
+  - Feature requests
+  - Community solutions
+
+- **Support Portal**: https://clerk.com/support
+  - Email support
+  - Priority support (Pro/Enterprise)
+  - Status page
+
+### SDK Packages
+
+#### Current Versions (December 2025)
+- **@clerk/nextjs**: 6.x (Core 2)
+  - Requires Next.js 13.0.4+
+  - Requires React 18+
+  - Node.js 18.17.0+
+
+- **@clerk/clerk-react**: 5.x (Core 2)
+  - Requires React 18+
+  - TypeScript support
+
+- **@clerk/express**: 1.x
+  - Express.js integration
+  - Middleware support
+
+- **@clerk/backend**: 1.x
+  - Backend API utilities
+  - JWT verification
+  - Webhook verification
+
+### Examples & Templates
+
+- **Next.js Examples**: https://github.com/clerk/nextjs-examples
+  - App Router examples
+  - Pages Router examples
+  - Middleware examples
+  - Organization examples
+
+- **React Examples**: https://github.com/clerk/react-examples
+  - CRA templates
+  - Vite examples
+  - Remix examples
+
+### Migration Tools
+
+- **Core 2 Upgrade Tool**: https://clerk.com/docs/guides/development/upgrading/upgrade-guides/core-2
+  ```bash
+  npx @clerk/upgrade --from=core-1
+  ```
+  - Automated code migration
+  - Environment variable updates
+  - Breaking change detection
+
+### Related Skills
+
+- **moai-platform-auth0**: Enterprise SSO alternative
+- **moai-platform-firebase-auth**: Firebase authentication
+- **moai-lang-typescript**: TypeScript development patterns
+- **moai-domain-frontend**: React and Next.js integration
+- **moai-platform-supabase**: Supabase authentication
+- **moai-platform-vercel**: Vercel deployment
+
+---
+
+**Last Updated**: 2025-12-30
+**Skill Version**: 2.0.0
+**Total Modules**: 1
+**SDK Version**: @clerk/nextjs 6.x (Core 2)