moai-adk 0.32.8__py3-none-any.whl → 0.41.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-platform-supabase/modules/realtime-presence.md

@@ -0,0 +1,354 @@
+---
+name: realtime-presence
+description: Real-time subscriptions and presence tracking for collaborative features
+parent-skill: moai-platform-supabase
+version: 1.0.0
+updated: 2026-01-06
+---
+
+# Real-time and Presence Module
+
+## Overview
+
+Supabase provides real-time capabilities through Postgres Changes (database change notifications) and Presence (user state tracking) for building collaborative applications.
+
+## Postgres Changes Subscription
+
+### Basic Setup
+
+Subscribe to all changes on a table:
+
+```typescript
+import { createClient } from '@supabase/supabase-js'
+
+const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY)
+
+const channel = supabase.channel('db-changes')
+  .on('postgres_changes',
+    { event: '*', schema: 'public', table: 'messages' },
+    (payload) => console.log('Change:', payload)
+  )
+  .subscribe()
+```
+
+### Event Types
+
+Available events:
+- `INSERT` - New row added
+- `UPDATE` - Row modified
+- `DELETE` - Row removed
+- `*` - All events
+
+### Filtered Subscriptions
+
+Filter changes by specific conditions:
+
+```typescript
+supabase.channel('project-updates')
+  .on('postgres_changes',
+    {
+      event: 'UPDATE',
+      schema: 'public',
+      table: 'projects',
+      filter: `id=eq.${projectId}`
+    },
+    (payload) => handleProjectUpdate(payload.new)
+  )
+  .subscribe()
+```
+
+### Multiple Tables
+
+Subscribe to multiple tables on one channel:
+
+```typescript
+const channel = supabase.channel('app-changes')
+  .on('postgres_changes',
+    { event: '*', schema: 'public', table: 'tasks' },
+    handleTaskChange
+  )
+  .on('postgres_changes',
+    { event: '*', schema: 'public', table: 'comments' },
+    handleCommentChange
+  )
+  .subscribe()
+```
+
+## Presence Tracking
+
+### Presence State Interface
+
+```typescript
+interface PresenceState {
+  user_id: string
+  online_at: string
+  typing?: boolean
+  cursor?: { x: number; y: number }
+}
+```
+
+### Channel Setup with Presence
+
+```typescript
+const channel = supabase.channel('room:collaborative-doc', {
+  config: { presence: { key: userId } }
+})
+
+channel
+  .on('presence', { event: 'sync' }, () => {
+    const state = channel.presenceState<PresenceState>()
+    console.log('Online users:', Object.keys(state))
+  })
+  .on('presence', { event: 'join' }, ({ key, newPresences }) => {
+    console.log('User joined:', key, newPresences)
+  })
+  .on('presence', { event: 'leave' }, ({ key, leftPresences }) => {
+    console.log('User left:', key, leftPresences)
+  })
+  .subscribe(async (status) => {
+    if (status === 'SUBSCRIBED') {
+      await channel.track({
+        user_id: userId,
+        online_at: new Date().toISOString()
+      })
+    }
+  })
+```
+
+### Update Presence State
+
+Update user presence in real-time:
+
+```typescript
+// Track typing status
+await channel.track({ typing: true })
+
+// Track cursor position
+await channel.track({ cursor: { x: 100, y: 200 } })
+
+// Clear typing after timeout
+setTimeout(async () => {
+  await channel.track({ typing: false })
+}, 1000)
+```
+
+## Collaborative Features
+
+### Collaborative Cursors
+
+```typescript
+interface CursorState {
+  user_id: string
+  user_name: string
+  cursor: { x: number; y: number }
+  color: string
+}
+
+function setupCollaborativeCursors(documentId: string, userId: string, userName: string) {
+  const channel = supabase.channel(`cursors:${documentId}`, {
+    config: { presence: { key: userId } }
+  })
+
+  const colors = ['#FF6B6B', '#4ECDC4', '#45B7D1', '#96CEB4', '#FFEAA7']
+  const userColor = colors[Math.abs(userId.hashCode()) % colors.length]
+
+  channel
+    .on('presence', { event: 'sync' }, () => {
+      const state = channel.presenceState<CursorState>()
+      renderCursors(Object.values(state).flat())
+    })
+    .subscribe(async (status) => {
+      if (status === 'SUBSCRIBED') {
+        await channel.track({
+          user_id: userId,
+          user_name: userName,
+          cursor: { x: 0, y: 0 },
+          color: userColor
+        })
+      }
+    })
+
+  // Track mouse movement
+  document.addEventListener('mousemove', async (e) => {
+    await channel.track({
+      user_id: userId,
+      user_name: userName,
+      cursor: { x: e.clientX, y: e.clientY },
+      color: userColor
+    })
+  })
+
+  return channel
+}
+```
+
+### Live Editing Indicators
+
+```typescript
+interface EditingState {
+  user_id: string
+  user_name: string
+  editing_field: string | null
+}
+
+function setupFieldLocking(formId: string) {
+  const channel = supabase.channel(`form:${formId}`, {
+    config: { presence: { key: currentUserId } }
+  })
+
+  channel
+    .on('presence', { event: 'sync' }, () => {
+      const state = channel.presenceState<EditingState>()
+      updateFieldLocks(Object.values(state).flat())
+    })
+    .subscribe()
+
+  return {
+    startEditing: async (fieldName: string) => {
+      await channel.track({
+        user_id: currentUserId,
+        user_name: currentUserName,
+        editing_field: fieldName
+      })
+    },
+    stopEditing: async () => {
+      await channel.track({
+        user_id: currentUserId,
+        user_name: currentUserName,
+        editing_field: null
+      })
+    }
+  }
+}
+```
+
+## Broadcast Messages
+
+Send arbitrary messages to channel subscribers:
+
+```typescript
+const channel = supabase.channel('room:chat')
+
+// Subscribe to broadcasts
+channel
+  .on('broadcast', { event: 'message' }, ({ payload }) => {
+    console.log('Received:', payload)
+  })
+  .subscribe()
+
+// Send broadcast
+await channel.send({
+  type: 'broadcast',
+  event: 'message',
+  payload: { text: 'Hello everyone!', sender: userId }
+})
+```
+
+## Subscription Management
+
+### Unsubscribe
+
+```typescript
+// Unsubscribe from specific channel
+await supabase.removeChannel(channel)
+
+// Unsubscribe from all channels
+await supabase.removeAllChannels()
+```
+
+### Subscription Status
+
+```typescript
+channel.subscribe((status) => {
+  switch (status) {
+    case 'SUBSCRIBED':
+      console.log('Connected to channel')
+      break
+    case 'CLOSED':
+      console.log('Channel closed')
+      break
+    case 'CHANNEL_ERROR':
+      console.log('Channel error')
+      break
+    case 'TIMED_OUT':
+      console.log('Connection timed out')
+      break
+  }
+})
+```
+
+## React Integration
+
+### Custom Hook for Presence
+
+```typescript
+import { useEffect, useState } from 'react'
+import { supabase } from './supabase/client'
+
+export function usePresence<T>(channelName: string, userId: string, initialState: T) {
+  const [presences, setPresences] = useState<Record<string, T[]>>({})
+
+  useEffect(() => {
+    const channel = supabase.channel(channelName, {
+      config: { presence: { key: userId } }
+    })
+
+    channel
+      .on('presence', { event: 'sync' }, () => {
+        setPresences(channel.presenceState<T>())
+      })
+      .subscribe(async (status) => {
+        if (status === 'SUBSCRIBED') {
+          await channel.track(initialState)
+        }
+      })
+
+    return () => {
+      supabase.removeChannel(channel)
+    }
+  }, [channelName, userId])
+
+  const updatePresence = async (state: Partial<T>) => {
+    const channel = supabase.getChannels().find(c => c.topic === channelName)
+    if (channel) {
+      await channel.track({ ...initialState, ...state } as T)
+    }
+  }
+
+  return { presences, updatePresence }
+}
+```
+
+### Usage
+
+```typescript
+function CollaborativeEditor({ documentId, userId }) {
+  const { presences, updatePresence } = usePresence(
+    `doc:${documentId}`,
+    userId,
+    { user_id: userId, typing: false, cursor: null }
+  )
+
+  return (
+    <div>
+      {Object.values(presences).flat().map(p => (
+        <Cursor key={p.user_id} position={p.cursor} />
+      ))}
+    </div>
+  )
+}
+```
+
+## Context7 Query Examples
+
+For latest real-time documentation:
+
+Topic: "realtime postgres_changes subscription"
+Topic: "presence tracking channel"
+Topic: "broadcast messages supabase"
+
+---
+
+Related Modules:
+- typescript-patterns.md - Client architecture
+- auth-integration.md - Authenticated subscriptions

moai_adk/templates/.claude/skills/moai-platform-supabase/modules/row-level-security.md

@@ -0,0 +1,286 @@
+---
+name: row-level-security
+description: RLS policies for multi-tenant data isolation and access control
+parent-skill: moai-platform-supabase
+version: 1.0.0
+updated: 2026-01-06
+---
+
+# Row-Level Security (RLS) Module
+
+## Overview
+
+Row-Level Security provides automatic data isolation at the database level, ensuring users can only access data they are authorized to see.
+
+## Basic Setup
+
+Enable RLS on a table:
+
+```sql
+ALTER TABLE projects ENABLE ROW LEVEL SECURITY;
+```
+
+## Policy Types
+
+RLS policies can be created for specific operations:
+
+- SELECT: Controls read access
+- INSERT: Controls creation
+- UPDATE: Controls modification
+- DELETE: Controls removal
+- ALL: Applies to all operations
+
+## Basic Tenant Isolation
+
+### JWT-Based Tenant Isolation
+
+Extract tenant ID from JWT claims:
+
+```sql
+CREATE POLICY "tenant_isolation" ON projects FOR ALL
+  USING (tenant_id = (auth.jwt() ->> 'tenant_id')::UUID);
+```
+
+### Owner-Based Access
+
+Restrict access to resource owners:
+
+```sql
+CREATE POLICY "owner_access" ON projects FOR ALL
+  USING (owner_id = auth.uid());
+```
+
+## Hierarchical Access Patterns
+
+### Organization Membership
+
+Allow access based on organization membership:
+
+```sql
+CREATE POLICY "org_member_select" ON organizations FOR SELECT
+  USING (id IN (SELECT org_id FROM org_members WHERE user_id = auth.uid()));
+```
+
+### Role-Based Modification
+
+Restrict modifications to specific roles:
+
+```sql
+CREATE POLICY "org_admin_modify" ON organizations FOR UPDATE
+  USING (id IN (
+    SELECT org_id FROM org_members
+    WHERE user_id = auth.uid() AND role IN ('owner', 'admin')
+  ));
+```
+
+### Cascading Project Access
+
+Grant project access through organization membership:
+
+```sql
+CREATE POLICY "project_access" ON projects FOR ALL
+  USING (org_id IN (SELECT org_id FROM org_members WHERE user_id = auth.uid()));
+```
+
+## Service Role Bypass
+
+Allow service role to bypass RLS for server-side operations:
+
+```sql
+CREATE POLICY "service_bypass" ON organizations FOR ALL TO service_role USING (true);
+```
+
+## Multi-Tenant SaaS Schema
+
+### Complete Schema Setup
+
+```sql
+-- Organizations (tenants)
+CREATE TABLE organizations (
+  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+  name TEXT NOT NULL,
+  slug TEXT UNIQUE NOT NULL,
+  plan TEXT DEFAULT 'free' CHECK (plan IN ('free', 'pro', 'enterprise')),
+  settings JSONB DEFAULT '{}',
+  created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Organization members with roles
+CREATE TABLE organization_members (
+  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+  organization_id UUID REFERENCES organizations(id) ON DELETE CASCADE,
+  user_id UUID NOT NULL,
+  role TEXT NOT NULL CHECK (role IN ('owner', 'admin', 'member', 'viewer')),
+  joined_at TIMESTAMPTZ DEFAULT NOW(),
+  UNIQUE(organization_id, user_id)
+);
+
+-- Projects within organizations
+CREATE TABLE projects (
+  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+  organization_id UUID REFERENCES organizations(id) ON DELETE CASCADE,
+  name TEXT NOT NULL,
+  owner_id UUID NOT NULL,
+  created_at TIMESTAMPTZ DEFAULT NOW()
+);
+```
+
+### Enable RLS on All Tables
+
+```sql
+ALTER TABLE organizations ENABLE ROW LEVEL SECURITY;
+ALTER TABLE organization_members ENABLE ROW LEVEL SECURITY;
+ALTER TABLE projects ENABLE ROW LEVEL SECURITY;
+```
+
+### Comprehensive RLS Policies
+
+```sql
+-- Organization read access
+CREATE POLICY "org_member_select" ON organizations FOR SELECT
+  USING (id IN (SELECT organization_id FROM organization_members WHERE user_id = auth.uid()));
+
+-- Organization admin update
+CREATE POLICY "org_admin_update" ON organizations FOR UPDATE
+  USING (id IN (SELECT organization_id FROM organization_members
+    WHERE user_id = auth.uid() AND role IN ('owner', 'admin')));
+
+-- Project member access
+CREATE POLICY "project_member_access" ON projects FOR ALL
+  USING (organization_id IN (SELECT organization_id FROM organization_members WHERE user_id = auth.uid()));
+
+-- Member management (admin only)
+CREATE POLICY "member_admin_manage" ON organization_members FOR ALL
+  USING (organization_id IN (SELECT organization_id FROM organization_members
+    WHERE user_id = auth.uid() AND role IN ('owner', 'admin')));
+```
+
+## Helper Functions
+
+### Check Organization Membership
+
+```sql
+CREATE OR REPLACE FUNCTION is_org_member(org_id UUID)
+RETURNS BOOLEAN AS $$
+BEGIN
+  RETURN EXISTS (
+    SELECT 1 FROM organization_members
+    WHERE organization_id = org_id AND user_id = auth.uid()
+  );
+END;
+$$ LANGUAGE plpgsql SECURITY DEFINER;
+```
+
+### Check Organization Role
+
+```sql
+CREATE OR REPLACE FUNCTION has_org_role(org_id UUID, required_roles TEXT[])
+RETURNS BOOLEAN AS $$
+BEGIN
+  RETURN EXISTS (
+    SELECT 1 FROM organization_members
+    WHERE organization_id = org_id
+      AND user_id = auth.uid()
+      AND role = ANY(required_roles)
+  );
+END;
+$$ LANGUAGE plpgsql SECURITY DEFINER;
+```
+
+### Usage in Policies
+
+```sql
+CREATE POLICY "project_admin_delete" ON projects FOR DELETE
+  USING (has_org_role(organization_id, ARRAY['owner', 'admin']));
+```
+
+## Performance Optimization
+
+### Index for RLS Queries
+
+Create indexes on foreign keys used in RLS policies:
+
+```sql
+CREATE INDEX idx_org_members_user ON organization_members(user_id);
+CREATE INDEX idx_org_members_org ON organization_members(organization_id);
+CREATE INDEX idx_projects_org ON projects(organization_id);
+```
+
+### Materialized View for Complex Policies
+
+For complex permission checks, use materialized views:
+
+```sql
+CREATE MATERIALIZED VIEW user_accessible_projects AS
+SELECT p.id as project_id, om.user_id, om.role
+FROM projects p
+JOIN organization_members om ON p.organization_id = om.organization_id;
+
+CREATE INDEX idx_uap_user ON user_accessible_projects(user_id);
+
+REFRESH MATERIALIZED VIEW CONCURRENTLY user_accessible_projects;
+```
+
+## Testing RLS Policies
+
+### Test as Authenticated User
+
+```sql
+SET request.jwt.claim.sub = 'user-uuid-here';
+SET request.jwt.claims = '{"role": "authenticated"}';
+
+SELECT * FROM projects;  -- Returns only accessible projects
+```
+
+### Verify Policy Restrictions
+
+```sql
+-- Should fail if not a member
+INSERT INTO projects (organization_id, name, owner_id)
+VALUES ('non-member-org-id', 'Test', auth.uid());
+```
+
+## Common Patterns
+
+### Public Read, Owner Write
+
+```sql
+CREATE POLICY "public_read" ON posts FOR SELECT USING (true);
+CREATE POLICY "owner_write" ON posts FOR INSERT WITH CHECK (author_id = auth.uid());
+CREATE POLICY "owner_update" ON posts FOR UPDATE USING (author_id = auth.uid());
+CREATE POLICY "owner_delete" ON posts FOR DELETE USING (author_id = auth.uid());
+```
+
+### Draft vs Published
+
+```sql
+CREATE POLICY "published_read" ON articles FOR SELECT
+  USING (status = 'published' OR author_id = auth.uid());
+```
+
+### Time-Based Access
+
+```sql
+CREATE POLICY "active_subscription" ON premium_content FOR SELECT
+  USING (
+    EXISTS (
+      SELECT 1 FROM subscriptions
+      WHERE user_id = auth.uid()
+        AND expires_at > NOW()
+    )
+  );
+```
+
+## Context7 Query Examples
+
+For latest RLS documentation:
+
+Topic: "row level security policies supabase"
+Topic: "auth.uid auth.jwt functions"
+Topic: "rls performance optimization"
+
+---
+
+Related Modules:
+- auth-integration.md - Authentication patterns
+- typescript-patterns.md - Client-side access patterns