@soulbatical/tetra-core 0.1.9 → 0.1.10

package/dist/core/adminDb.d.ts

@@ -1,8 +1,17 @@
 import { AuthenticatedRequest } from '../middleware/authMiddleware.js';
 /**
- * Admin database helper - for organization admin operations
- * Enforces admin role and logs access for audit
- * RLS policies will allow access to all organization data
+ * Admin database helper - for organization admin operations.
+ * Creates a Supabase client authenticated with the user's JWT token,
+ * so RLS policies are enforced using the user's identity.
+ *
+ * IMPORTANT — RLS Organization Filtering:
+ * This client passes the user's JWT to Supabase. RLS policies that use
+ * auth_org_id() will filter data by organization. The auth_org_id()
+ * function MUST read from users_public.active_organization_id (database),
+ * NOT from JWT app_metadata claims. JWT claims are set at login time and
+ * become stale when users switch organizations.
+ *
+ * See: packages/core/src/shared/auth/migrations/000_auth_org_helpers.sql
  *
  * @example
  * ```typescript

package/dist/core/adminDb.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adminDb.d.ts","sourceRoot":"","sources":["../../src/core/adminDb.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAMvE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,OAAO,CAAC,GAAG,EAAE,oBAAoB,8FA0BtD"}
+{"version":3,"file":"adminDb.d.ts","sourceRoot":"","sources":["../../src/core/adminDb.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAMvE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,OAAO,CAAC,GAAG,EAAE,oBAAoB,8FA0BtD"}

package/dist/core/adminDb.js

@@ -2,9 +2,18 @@ import { SupabaseUserClient } from './SupabaseUserClient.js';
 import { createLogger } from '../utils/logger.js';
 const logger = createLogger('security:db:admin');
 /**
- * Admin database helper - for organization admin operations
- * Enforces admin role and logs access for audit
- * RLS policies will allow access to all organization data
+ * Admin database helper - for organization admin operations.
+ * Creates a Supabase client authenticated with the user's JWT token,
+ * so RLS policies are enforced using the user's identity.
+ *
+ * IMPORTANT — RLS Organization Filtering:
+ * This client passes the user's JWT to Supabase. RLS policies that use
+ * auth_org_id() will filter data by organization. The auth_org_id()
+ * function MUST read from users_public.active_organization_id (database),
+ * NOT from JWT app_metadata claims. JWT claims are set at login time and
+ * become stale when users switch organizations.
+ *
+ * See: packages/core/src/shared/auth/migrations/000_auth_org_helpers.sql
  *
  * @example
  * ```typescript

package/dist/core/adminDb.js.map

@@ -1 +1 @@
-{"version":3,"file":"adminDb.js","sourceRoot":"","sources":["../../src/core/adminDb.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,MAAM,MAAM,GAAG,YAAY,CAAC,mBAAmB,CAAC,CAAC;AAEjD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,GAAyB;IACrD,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC;QACnB,0EAA0E;QAC1E,MAAM,IAAI,KAAK,CACb,0CAA0C;YAC1C,wEAAwE;YACxE,yDAAyD,CAC1D,CAAC;IACJ,CAAC;IAED,sEAAsE;IACtE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,cAAc,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,aAAa,EAAE,CAAC;QAC1D,MAAM,CAAC,KAAK,CAAC,kDAAkD,GAAG,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;QAC/E,4EAA4E;QAC5E,MAAM,IAAI,KAAK,CACb,qCAAqC;YACrC,sFAAsF;YACtF,mEAAmE,CACpE,CAAC;IACJ,CAAC;IAED,gEAAgE;IAChE,MAAM,CAAC,KAAK,CAAC,+BAA+B,GAAG,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,CAAC,IAAI,CAAC,cAAc,IAAI,YAAY,EAAE,CAAC,CAAC;IAE1G,8DAA8D;IAC9D,OAAO,kBAAkB,CAAC,aAAa,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;AACzD,CAAC"}
+{"version":3,"file":"adminDb.js","sourceRoot":"","sources":["../../src/core/adminDb.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,MAAM,MAAM,GAAG,YAAY,CAAC,mBAAmB,CAAC,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,GAAyB;IACrD,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC;QACnB,0EAA0E;QAC1E,MAAM,IAAI,KAAK,CACb,0CAA0C;YAC1C,wEAAwE;YACxE,yDAAyD,CAC1D,CAAC;IACJ,CAAC;IAED,sEAAsE;IACtE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,cAAc,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,aAAa,EAAE,CAAC;QAC1D,MAAM,CAAC,KAAK,CAAC,kDAAkD,GAAG,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;QAC/E,4EAA4E;QAC5E,MAAM,IAAI,KAAK,CACb,qCAAqC;YACrC,sFAAsF;YACtF,mEAAmE,CACpE,CAAC;IACJ,CAAC;IAED,gEAAgE;IAChE,MAAM,CAAC,KAAK,CAAC,+BAA+B,GAAG,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,CAAC,IAAI,CAAC,cAAc,IAAI,YAAY,EAAE,CAAC,CAAC;IAE1G,8DAA8D;IAC9D,OAAO,kBAAkB,CAAC,aAAa,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;AACzD,CAAC"}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@soulbatical/tetra-core",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "publishConfig": {
     "access": "restricted"
   },
-  "description": "The foundation framework for VCA platform projects — config-driven Express + Supabase + TypeScript",
+  "description": "The foundation framework for Tetra platform projects (Soulbatical BV) — config-driven Express + Supabase + TypeScript",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -27,7 +27,9 @@
   },
   "files": [
     "dist",
-    "scripts"
+    "scripts",
+    "src/shared/auth/migrations",
+    "src/shared/affiliate/migrations"
   ],
   "scripts": {
     "build": "tsc",

package/src/shared/affiliate/migrations/001_create_affiliates.sql

@@ -0,0 +1,49 @@
+-- ============================================================================
+-- Affiliate Module: affiliates table
+-- Template from @soulbatical/tetra-core
+-- Multi-tenant: organization_id on every row
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS public.affiliates (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  organization_id uuid NOT NULL REFERENCES public.organizations(id),
+  user_id uuid REFERENCES public.users_public(id),
+  email text NOT NULL,
+  contact_name text NOT NULL,
+  company_name text,
+  phone text,
+  address text,
+  postal_code text,
+  city text,
+  country text DEFAULT 'NL',
+  vat_number text,
+  kvk_number text,
+  website text,
+  status text NOT NULL DEFAULT 'pending',
+  referral_code text NOT NULL,
+  tier text NOT NULL DEFAULT 'starter',
+  commission_percentage numeric NOT NULL DEFAULT 30,
+  cookie_duration_days integer DEFAULT 90,
+  total_clicks integer DEFAULT 0,
+  total_sales integer DEFAULT 0,
+  total_revenue numeric DEFAULT 0,
+  total_commission_earned numeric DEFAULT 0,
+  total_commission_paid numeric DEFAULT 0,
+  active_since timestamptz,
+  last_sale_at timestamptz,
+  notes text,
+  created_at timestamptz DEFAULT now(),
+  updated_at timestamptz DEFAULT now()
+);
+
+-- Unique constraints
+ALTER TABLE public.affiliates ADD CONSTRAINT affiliates_email_org_unique UNIQUE (organization_id, email);
+ALTER TABLE public.affiliates ADD CONSTRAINT affiliates_referral_code_unique UNIQUE (referral_code);
+
+-- Indexes
+CREATE INDEX IF NOT EXISTS idx_affiliates_org_id ON public.affiliates(organization_id);
+CREATE INDEX IF NOT EXISTS idx_affiliates_referral_code ON public.affiliates(referral_code);
+CREATE INDEX IF NOT EXISTS idx_affiliates_status ON public.affiliates(status);
+CREATE INDEX IF NOT EXISTS idx_affiliates_tier ON public.affiliates(tier);
+CREATE INDEX IF NOT EXISTS idx_affiliates_user_id ON public.affiliates(user_id);
+CREATE INDEX IF NOT EXISTS idx_affiliates_email ON public.affiliates(email);

package/src/shared/affiliate/migrations/002_create_affiliate_commissions.sql

@@ -0,0 +1,31 @@
+-- ============================================================================
+-- Affiliate Module: affiliate_commissions table
+-- Template from @soulbatical/tetra-core
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS public.affiliate_commissions (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  organization_id uuid NOT NULL REFERENCES public.organizations(id),
+  affiliate_id uuid NOT NULL REFERENCES public.affiliates(id) ON DELETE CASCADE,
+  order_id uuid NOT NULL,
+  affiliate_source text NOT NULL DEFAULT 'internal',
+  external_click_ref text,
+  product_name text NOT NULL DEFAULT 'Order',
+  order_amount_excl_vat numeric NOT NULL,
+  commission_percentage numeric NOT NULL,
+  commission_amount numeric NOT NULL,
+  status text NOT NULL DEFAULT 'pending',
+  approved_at timestamptz,
+  approved_by uuid REFERENCES public.users_public(id),
+  paid_at timestamptz,
+  payment_id uuid,
+  notes text,
+  created_at timestamptz DEFAULT now(),
+  updated_at timestamptz DEFAULT now()
+);
+
+-- Indexes
+CREATE INDEX IF NOT EXISTS idx_affiliate_commissions_org_id ON public.affiliate_commissions(organization_id);
+CREATE INDEX IF NOT EXISTS idx_affiliate_commissions_affiliate ON public.affiliate_commissions(affiliate_id);
+CREATE INDEX IF NOT EXISTS idx_affiliate_commissions_order ON public.affiliate_commissions(order_id);
+CREATE INDEX IF NOT EXISTS idx_affiliate_commissions_status ON public.affiliate_commissions(status);

package/src/shared/affiliate/migrations/003_create_affiliate_clicks.sql

@@ -0,0 +1,26 @@
+-- ============================================================================
+-- Affiliate Module: affiliate_clicks table
+-- Template from @soulbatical/tetra-core
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS public.affiliate_clicks (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  organization_id uuid REFERENCES public.organizations(id),
+  affiliate_id uuid REFERENCES public.affiliates(id) ON DELETE SET NULL,
+  visitor_ip text,
+  visitor_country text,
+  user_agent text,
+  referrer_url text,
+  landing_page text,
+  affiliate_source text NOT NULL DEFAULT 'internal',
+  external_click_ref text,
+  converted boolean DEFAULT false,
+  order_id uuid,
+  conversion_time_hours integer,
+  clicked_at timestamptz DEFAULT now()
+);
+
+-- Indexes
+CREATE INDEX IF NOT EXISTS idx_affiliate_clicks_org_id ON public.affiliate_clicks(organization_id);
+CREATE INDEX IF NOT EXISTS idx_affiliate_clicks_affiliate ON public.affiliate_clicks(affiliate_id);
+CREATE INDEX IF NOT EXISTS idx_affiliate_clicks_converted ON public.affiliate_clicks(converted);

package/src/shared/affiliate/migrations/004_create_affiliate_payments.sql

@@ -0,0 +1,34 @@
+-- ============================================================================
+-- Affiliate Module: affiliate_payments table
+-- Template from @soulbatical/tetra-core
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS public.affiliate_payments (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  organization_id uuid NOT NULL REFERENCES public.organizations(id),
+  affiliate_id uuid NOT NULL REFERENCES public.affiliates(id) ON DELETE CASCADE,
+  payment_amount numeric NOT NULL,
+  payment_date date NOT NULL,
+  payment_method text,
+  payment_reference text,
+  commission_ids uuid[] NOT NULL,
+  notes text,
+  created_at timestamptz DEFAULT now()
+);
+
+-- Add FK from commissions to payments (after payments table exists)
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM information_schema.table_constraints
+    WHERE constraint_name = 'affiliate_commissions_payment_id_fkey'
+  ) THEN
+    ALTER TABLE public.affiliate_commissions
+      ADD CONSTRAINT affiliate_commissions_payment_id_fkey
+      FOREIGN KEY (payment_id) REFERENCES public.affiliate_payments(id);
+  END IF;
+END $$;
+
+-- Indexes
+CREATE INDEX IF NOT EXISTS idx_affiliate_payments_org_id ON public.affiliate_payments(organization_id);
+CREATE INDEX IF NOT EXISTS idx_affiliate_payments_affiliate ON public.affiliate_payments(affiliate_id);

package/src/shared/affiliate/migrations/005_create_affiliate_tier_history.sql

@@ -0,0 +1,19 @@
+-- ============================================================================
+-- Affiliate Module: affiliate_tier_history table
+-- Template from @soulbatical/tetra-core
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS public.affiliate_tier_history (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  affiliate_id uuid NOT NULL REFERENCES public.affiliates(id) ON DELETE CASCADE,
+  old_tier text NOT NULL,
+  new_tier text NOT NULL,
+  old_commission_percentage numeric NOT NULL,
+  new_commission_percentage numeric NOT NULL,
+  reason text,
+  triggered_by_sale_count integer,
+  changed_at timestamptz DEFAULT now()
+);
+
+-- Indexes
+CREATE INDEX IF NOT EXISTS idx_affiliate_tier_history_affiliate ON public.affiliate_tier_history(affiliate_id);

package/src/shared/affiliate/migrations/006_create_affiliate_rpc_functions.sql

@@ -0,0 +1,209 @@
+-- ============================================================================
+-- Affiliate Module: RPC functions
+-- Template from @soulbatical/tetra-core
+--
+-- NOTE: These are template functions. Projects should generate their own
+-- using `npm run generate:rpc affiliates` from the featureConfig, which
+-- produces optimized SQL matching the project's exact filter/count setup.
+--
+-- These templates provide a working baseline.
+-- ============================================================================
+
+-- ─── Results Function ─────────────────────────────────────────
+
+DROP FUNCTION IF EXISTS public.get_affiliates_results;
+
+CREATE OR REPLACE FUNCTION public.get_affiliates_results(
+  p_org_id uuid DEFAULT NULL,
+  p_ids uuid[] DEFAULT NULL,
+  p_status text DEFAULT NULL,
+  p_tier text DEFAULT NULL,
+  p_search text DEFAULT NULL,
+  p_has_user text DEFAULT NULL,
+  p_time_period text DEFAULT NULL,
+  p_limit int DEFAULT 20,
+  p_offset int DEFAULT 0,
+  p_sort_by text DEFAULT 'date-desc'
+)
+RETURNS TABLE (
+  data jsonb,
+  total_count bigint
+)
+LANGUAGE plpgsql
+STABLE
+SECURITY DEFINER
+SET search_path = ''
+AS $$
+DECLARE
+  v_is_service_role boolean := (
+    auth.role() = 'service_role'
+    OR session_user = 'postgres'
+  );
+BEGIN
+  IF NOT v_is_service_role THEN
+    IF NOT EXISTS (SELECT 1 FROM public.auth_admin_organizations()) THEN
+      RAISE EXCEPTION 'Access denied: authentication required'
+        USING ERRCODE = '42501';
+    END IF;
+    IF p_org_id IS NOT NULL AND p_org_id NOT IN (SELECT public.auth_admin_organizations()) THEN
+      RAISE EXCEPTION 'Access denied: not authorized for organization %', p_org_id
+        USING ERRCODE = '42501';
+    END IF;
+  END IF;
+
+  RETURN QUERY
+  WITH results AS (
+    SELECT
+      a.*,
+      COUNT(*) OVER() as total_count
+    FROM public.affiliates a
+    WHERE (p_org_id IS NULL OR a.organization_id = p_org_id OR a.organization_id IS NULL)
+      AND (p_ids IS NULL OR a.id = ANY(p_ids))
+      AND (p_status IS NULL OR p_status = 'all' OR a.status::text = p_status)
+      AND (p_tier IS NULL OR p_tier = 'all' OR a.tier::text = p_tier)
+      AND (
+        p_search IS NULL OR p_search = '' OR p_search = 'all'
+        OR a.contact_name ILIKE '%' || p_search || '%'
+        OR a.email ILIKE '%' || p_search || '%'
+        OR a.company_name ILIKE '%' || p_search || '%'
+        OR a.referral_code ILIKE '%' || p_search || '%'
+      )
+      AND (
+        p_has_user IS NULL OR p_has_user = 'all'
+        OR (p_has_user = 'with' AND a.user_id IS NOT NULL)
+        OR (p_has_user = 'without' AND a.user_id IS NULL)
+      )
+      AND (
+        p_time_period IS NULL OR p_time_period = 'all'
+        OR (p_time_period = 'today' AND a.created_at >= CURRENT_DATE)
+        OR (p_time_period = 'this_week' AND a.created_at >= CURRENT_DATE - INTERVAL '7 days')
+        OR (p_time_period = 'this_month' AND a.created_at >= CURRENT_DATE - INTERVAL '30 days')
+        OR (p_time_period = 'older' AND a.created_at >= CURRENT_DATE - INTERVAL '90 days')
+      )
+      AND (
+        v_is_service_role
+        OR a.organization_id IN (SELECT public.auth_admin_organizations())
+        OR a.organization_id IS NULL
+      )
+    ORDER BY
+      CASE WHEN p_sort_by = 'date-desc' THEN a.created_at END DESC NULLS LAST,
+      CASE WHEN p_sort_by = 'date-asc' THEN a.created_at END ASC NULLS LAST,
+      CASE WHEN p_sort_by = 'name-asc' THEN LOWER(a.contact_name) END ASC NULLS LAST,
+      CASE WHEN p_sort_by = 'name-desc' THEN LOWER(a.contact_name) END DESC NULLS LAST,
+      CASE WHEN p_sort_by = 'sales-desc' THEN a.total_sales END DESC NULLS LAST,
+      CASE WHEN p_sort_by = 'sales-asc' THEN a.total_sales END ASC NULLS LAST,
+      CASE WHEN p_sort_by = 'revenue-desc' THEN a.total_revenue END DESC NULLS LAST,
+      CASE WHEN p_sort_by = 'revenue-asc' THEN a.total_revenue END ASC NULLS LAST,
+      CASE WHEN p_sort_by = 'commission-desc' THEN a.total_commission_earned END DESC NULLS LAST,
+      CASE WHEN p_sort_by = 'commission-asc' THEN a.total_commission_earned END ASC NULLS LAST,
+      a.created_at DESC
+    LIMIT p_limit
+    OFFSET p_offset
+  )
+  SELECT
+    to_jsonb(results.*) - 'total_count' as data,
+    results.total_count
+  FROM results;
+END;
+$$;
+
+-- ─── Counts Function ──────────────────────────────────────────
+
+DROP FUNCTION IF EXISTS public.get_affiliates_counts;
+
+CREATE OR REPLACE FUNCTION public.get_affiliates_counts(
+  p_org_id uuid DEFAULT NULL,
+  p_ids uuid[] DEFAULT NULL,
+  p_status text DEFAULT NULL,
+  p_tier text DEFAULT NULL,
+  p_search text DEFAULT NULL,
+  p_has_user text DEFAULT NULL,
+  p_time_period text DEFAULT NULL
+)
+RETURNS jsonb
+LANGUAGE plpgsql
+STABLE
+SECURITY DEFINER
+SET search_path = ''
+AS $$
+DECLARE
+  result jsonb;
+  v_is_service_role boolean := (
+    auth.role() = 'service_role'
+    OR session_user = 'postgres'
+  );
+BEGIN
+  IF NOT v_is_service_role THEN
+    IF NOT EXISTS (SELECT 1 FROM public.auth_admin_organizations()) THEN
+      RAISE EXCEPTION 'Access denied: authentication required'
+        USING ERRCODE = '42501';
+    END IF;
+    IF p_org_id IS NOT NULL AND p_org_id NOT IN (SELECT public.auth_admin_organizations()) THEN
+      RAISE EXCEPTION 'Access denied: not authorized for organization %', p_org_id
+        USING ERRCODE = '42501';
+    END IF;
+  END IF;
+
+  WITH filtered_items AS (
+    SELECT a.*
+    FROM public.affiliates a
+    WHERE (p_org_id IS NULL OR a.organization_id = p_org_id OR a.organization_id IS NULL)
+      AND (p_ids IS NULL OR a.id = ANY(p_ids))
+      AND (p_status IS NULL OR p_status = 'all' OR a.status::text = p_status)
+      AND (p_tier IS NULL OR p_tier = 'all' OR a.tier::text = p_tier)
+      AND (
+        p_search IS NULL OR p_search = '' OR p_search = 'all'
+        OR a.contact_name ILIKE '%' || p_search || '%'
+        OR a.email ILIKE '%' || p_search || '%'
+        OR a.company_name ILIKE '%' || p_search || '%'
+        OR a.referral_code ILIKE '%' || p_search || '%'
+      )
+      AND (
+        p_has_user IS NULL OR p_has_user = 'all'
+        OR (p_has_user = 'with' AND a.user_id IS NOT NULL)
+        OR (p_has_user = 'without' AND a.user_id IS NULL)
+      )
+      AND (
+        p_time_period IS NULL OR p_time_period = 'all'
+        OR (p_time_period = 'today' AND a.created_at >= CURRENT_DATE)
+        OR (p_time_period = 'this_week' AND a.created_at >= CURRENT_DATE - INTERVAL '7 days')
+        OR (p_time_period = 'this_month' AND a.created_at >= CURRENT_DATE - INTERVAL '30 days')
+        OR (p_time_period = 'older' AND a.created_at >= CURRENT_DATE - INTERVAL '90 days')
+      )
+      AND (
+        v_is_service_role
+        OR a.organization_id IN (SELECT public.auth_admin_organizations())
+        OR a.organization_id IS NULL
+      )
+  )
+  SELECT jsonb_build_object(
+    'total', (SELECT COUNT(*)::int FROM filtered_items),
+    'byStatus', (
+      SELECT jsonb_object_agg(status_value, cnt) FROM (
+        SELECT 'pending' as status_value, COUNT(*)::int as cnt FROM filtered_items WHERE status::text = 'pending'
+        UNION ALL SELECT 'active', COUNT(*)::int FROM filtered_items WHERE status::text = 'active'
+        UNION ALL SELECT 'inactive', COUNT(*)::int FROM filtered_items WHERE status::text = 'inactive'
+        UNION ALL SELECT 'rejected', COUNT(*)::int FROM filtered_items WHERE status::text = 'rejected'
+      ) subquery
+    ),
+    'byTier', (
+      SELECT jsonb_object_agg(tier_value, cnt) FROM (
+        SELECT 'starter' as tier_value, COUNT(*)::int as cnt FROM filtered_items WHERE tier::text = 'starter'
+        UNION ALL SELECT 'active', COUNT(*)::int FROM filtered_items WHERE tier::text = 'active'
+      ) subquery
+    ),
+    'byUserAccount', jsonb_build_object(
+      'with', (SELECT COUNT(*)::int FROM filtered_items WHERE user_id IS NOT NULL),
+      'without', (SELECT COUNT(*)::int FROM filtered_items WHERE user_id IS NULL)
+    ),
+    'byTimePeriod', jsonb_build_object(
+      'today', (SELECT COUNT(*)::int FROM filtered_items WHERE created_at >= CURRENT_DATE),
+      'this_week', (SELECT COUNT(*)::int FROM filtered_items WHERE created_at >= CURRENT_DATE - INTERVAL '7 days'),
+      'this_month', (SELECT COUNT(*)::int FROM filtered_items WHERE created_at >= CURRENT_DATE - INTERVAL '30 days'),
+      'older', (SELECT COUNT(*)::int FROM filtered_items WHERE created_at >= CURRENT_DATE - INTERVAL '90 days')
+    )
+  ) INTO result;
+
+  RETURN result;
+END;
+$$;

package/src/shared/affiliate/migrations/007_create_affiliate_rls_policies.sql

@@ -0,0 +1,123 @@
+-- ============================================================================
+-- Affiliate Module: RLS Policies
+-- Template from @soulbatical/tetra-core
+-- Multi-tenant: all policies filter by organization_id
+-- ============================================================================
+
+-- Enable RLS on all affiliate tables
+ALTER TABLE public.affiliates ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.affiliate_commissions ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.affiliate_clicks ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.affiliate_payments ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.affiliate_tier_history ENABLE ROW LEVEL SECURITY;
+
+-- ─── affiliates ───────────────────────────────────────────────
+
+-- Admin: full access within organization
+CREATE POLICY "Admin: full access to affiliates"
+  ON public.affiliates
+  FOR ALL
+  TO authenticated
+  USING (organization_id IN (SELECT public.auth_admin_organizations()))
+  WITH CHECK (organization_id IN (SELECT public.auth_admin_organizations()));
+
+-- User: read own affiliate record
+CREATE POLICY "User: read own affiliate"
+  ON public.affiliates
+  FOR SELECT
+  TO authenticated
+  USING (user_id = auth.uid());
+
+-- Service role: bypass RLS
+CREATE POLICY "Service role: full access to affiliates"
+  ON public.affiliates
+  FOR ALL
+  TO service_role
+  USING (true)
+  WITH CHECK (true);
+
+-- ─── affiliate_commissions ────────────────────────────────────
+
+CREATE POLICY "Admin: full access to affiliate_commissions"
+  ON public.affiliate_commissions
+  FOR ALL
+  TO authenticated
+  USING (organization_id IN (SELECT public.auth_admin_organizations()))
+  WITH CHECK (organization_id IN (SELECT public.auth_admin_organizations()));
+
+-- User: read own commissions (via affiliate)
+CREATE POLICY "User: read own commissions"
+  ON public.affiliate_commissions
+  FOR SELECT
+  TO authenticated
+  USING (
+    affiliate_id IN (
+      SELECT id FROM public.affiliates WHERE user_id = auth.uid()
+    )
+  );
+
+CREATE POLICY "Service role: full access to affiliate_commissions"
+  ON public.affiliate_commissions
+  FOR ALL
+  TO service_role
+  USING (true)
+  WITH CHECK (true);
+
+-- ─── affiliate_clicks ─────────────────────────────────────────
+
+CREATE POLICY "Admin: full access to affiliate_clicks"
+  ON public.affiliate_clicks
+  FOR ALL
+  TO authenticated
+  USING (organization_id IN (SELECT public.auth_admin_organizations()))
+  WITH CHECK (organization_id IN (SELECT public.auth_admin_organizations()));
+
+-- Public: insert clicks (anonymous tracking)
+CREATE POLICY "Public: insert affiliate clicks"
+  ON public.affiliate_clicks
+  FOR INSERT
+  TO anon
+  WITH CHECK (true);
+
+CREATE POLICY "Service role: full access to affiliate_clicks"
+  ON public.affiliate_clicks
+  FOR ALL
+  TO service_role
+  USING (true)
+  WITH CHECK (true);
+
+-- ─── affiliate_payments ───────────────────────────────────────
+
+CREATE POLICY "Admin: full access to affiliate_payments"
+  ON public.affiliate_payments
+  FOR ALL
+  TO authenticated
+  USING (organization_id IN (SELECT public.auth_admin_organizations()))
+  WITH CHECK (organization_id IN (SELECT public.auth_admin_organizations()));
+
+CREATE POLICY "Service role: full access to affiliate_payments"
+  ON public.affiliate_payments
+  FOR ALL
+  TO service_role
+  USING (true)
+  WITH CHECK (true);
+
+-- ─── affiliate_tier_history ───────────────────────────────────
+
+CREATE POLICY "Admin: read affiliate tier history"
+  ON public.affiliate_tier_history
+  FOR SELECT
+  TO authenticated
+  USING (
+    affiliate_id IN (
+      SELECT id FROM public.affiliates
+      WHERE organization_id IN (SELECT public.auth_admin_organizations())
+    )
+  );
+
+CREATE POLICY "Service role: full access to affiliate_tier_history"
+  ON public.affiliate_tier_history
+  FOR ALL
+  TO service_role
+  USING (true)
+  WITH CHECK (true);

package/src/shared/auth/migrations/000_auth_org_helpers.sql

@@ -0,0 +1,71 @@
+-- Tetra Auth Helpers — Organization-scoped RLS functions
+--
+-- PREREQUISITE: This migration requires the users_public table with:
+--   - id UUID PRIMARY KEY REFERENCES auth.users(id)
+--   - active_organization_id UUID
+--
+-- These functions provide the single source of truth for organization
+-- context in RLS policies. They MUST read from the database, not from
+-- JWT claims, because JWT claims are immutable after login and will
+-- get out of sync when users switch organizations.
+--
+-- ARCHITECTURE DECISION:
+-- ┌─────────────────┐     ┌──────────────────────┐
+-- │  Backend (Node)  │     │  Database (RLS)       │
+-- │                  │     │                       │
+-- │  reads from:     │     │  reads from:          │
+-- │  users_public    │────▶│  users_public         │
+-- │  .active_org_id  │     │  .active_org_id       │
+-- └─────────────────┘     └──────────────────────┘
+--         ▲                         ▲
+--         │    SAME SOURCE          │
+--         └─────────────────────────┘
+--
+-- DO NOT read from auth.jwt() -> 'app_metadata' for organization_id.
+-- JWT claims are set at login and don't update when org switches happen.
+
+-- ============================================================================
+-- auth_org_id() — Returns the user's active organization UUID
+--
+-- Usage in RLS policies:
+--   CREATE POLICY "org_select" ON my_table
+--     FOR SELECT USING (organization_id = auth_org_id());
+--
+-- This reads from users_public.active_organization_id, ensuring it
+-- always matches what the backend session service returns.
+-- ============================================================================
+
+CREATE OR REPLACE FUNCTION auth_org_id() RETURNS UUID AS $$
+  SELECT active_organization_id
+  FROM users_public
+  WHERE id = auth.uid();
+$$ LANGUAGE sql STABLE SECURITY DEFINER;
+
+-- ============================================================================
+-- auth_admin_organizations() — Returns org(s) for admin RLS
+--
+-- Used by sparkbuddy-live pattern. Returns a TABLE so it works with
+-- IN (SELECT auth_admin_organizations()) syntax in RLS.
+--
+-- Supports test mode via app.test_user_id / app.test_org_id settings
+-- for integration testing without real JWT tokens.
+-- ============================================================================
+
+CREATE OR REPLACE FUNCTION auth_admin_organizations()
+RETURNS TABLE(organizationid UUID) AS $$
+  SELECT
+    CASE
+      WHEN current_setting('app.test_user_id', true) IS NOT NULL
+      THEN current_setting('app.test_org_id', true)::uuid
+      ELSE up.active_organization_id
+    END AS organizationid
+  FROM users_public up
+  WHERE up.id = COALESCE(
+    current_setting('app.test_user_id', true)::uuid,
+    auth.uid()
+  )
+  AND (
+    current_setting('app.test_user_id', true) IS NOT NULL
+    OR up.active_organization_id IS NOT NULL
+  );
+$$ LANGUAGE sql STABLE SECURITY DEFINER;