@fayz-ai/plugin-marketing 0.8.0 → 0.8.2

package/src/integrations/ranklayer/RANKLAYER.md

@@ -0,0 +1,40 @@
+# RankLayer connector
+
+Surfaces in **Marketing → settings → Integrações** (rendered by the shared
+`ConnectorsHub`). Follows the connector contract in
+`packages/core/src/integrations/index.ts` and mirrors the PlugBank precedent
+(`beauty-saas/src/plugins/openbanking`).
+
+## Status: SCAFFOLD
+
+This ships the control plane only:
+
+- `connectorDef.tsx` — the `ConnectorDefinition` (api-key form: API Key + site
+  domain, status badge, `ExtraPanel` with a "sync coming soon" note).
+- `data/supabase.ts` — persists the connection row and reads the sync log.
+- `../../migrations/004_ranklayer.sql` — `plg_marketing_ranklayer_integrations`
+  + `plg_marketing_ranklayer_sync_log` (tenant RLS).
+
+`testConnection` currently accepts any non-empty API key and **no real sync
+runs** — RankLayer has no public API wired yet.
+
+## What the RankLayer PR needs to fill in
+
+1. **Edge function** `functions/ranklayer-sync/index.ts` holding the RankLayer
+   API key server-side (move it out of the `api_key` column into a secret if the
+   provider requires it), with actions:
+   - `test_connection` — validate the key against RankLayer.
+   - `sync` — the agreed direction. RankLayer generates/publishes SEO pages and
+     articles, so the likely first flow is **inbound**: pull RankLayer-published
+     articles and upsert them as `plg_blog_posts` (status `published`) so they
+     appear on the site's `/blog`. Confirm direction with the RankLayer team.
+2. **Real `testConnection` / `sync`** in `data/supabase.ts` — replace the stubs
+   to invoke the edge function; write a `plg_marketing_ranklayer_sync_log` row
+   per run (the `SyncRun` audit shape).
+3. **ExtraPanel** — swap the "coming soon" note for a "Sync now" button + the
+   real history table (the history rendering is already wired).
+
+The connector is already registered on the marketing manifest
+(`connectors: [ranklayerConnectorDef]`) and the Integrações tab is enabled
+(`hostPluginId: 'marketing'` on the settings panel), so no wiring changes are
+needed — only the data-plane implementation above.

package/src/integrations/ranklayer/connectorDef.tsx

@@ -0,0 +1,98 @@
+// RankLayer as a unified ConnectorDefinition, surfaced in Marketing → settings
+// → Integrações (rendered by the shared ConnectorsHub). SCAFFOLD: the hub gives
+// us the API-key form + Test/Save; the ExtraPanel below explains that automated
+// SEO content sync is being prepared. The real sync lands via an external PR —
+// see ./RANKLAYER.md.
+import React, { useEffect, useState } from 'react'
+import { Sparkles, History, CheckCircle2, AlertCircle } from 'lucide-react'
+import type { ConnectorDefinition } from '@fayz-ai/core'
+import { createRankLayerProvider } from './data/supabase'
+import type { RankLayerIntegration, RankLayerSyncLogEntry } from './types'
+
+const provider = createRankLayerProvider()
+
+function RankLayerExtraPanel() {
+  const [integration, setIntegration] = useState<RankLayerIntegration | null>(null)
+  const [log, setLog] = useState<RankLayerSyncLogEntry[]>([])
+  const [loaded, setLoaded] = useState(false)
+
+  useEffect(() => {
+    let cancelled = false
+    ;(async () => {
+      try {
+        const found = await provider.getIntegration()
+        if (cancelled) return
+        setIntegration(found)
+        if (found) setLog(await provider.getSyncLog(found.id))
+      } catch {
+        /* not connected / no client — nothing to show */
+      } finally {
+        if (!cancelled) setLoaded(true)
+      }
+    })()
+    return () => { cancelled = true }
+  }, [])
+
+  if (!loaded || !integration) return null // nothing until the connection is saved
+
+  return (
+    <div className="space-y-4 border-t pt-4">
+      <div className="flex items-start gap-3 rounded-md border border-dashed p-3">
+        <Sparkles className="mt-0.5 h-4 w-4 shrink-0 text-muted-foreground" />
+        <div className="space-y-1">
+          <h4 className="text-sm font-semibold">Sincronização de conteúdo — em breve</h4>
+          <p className="text-xs text-muted-foreground">
+            A publicação automática de páginas e artigos de SEO com a RankLayer está em preparação.
+            {integration.siteDomain ? ` Domínio configurado: ${integration.siteDomain}.` : ''} Assim que a
+            integração estiver ativa, o histórico de sincronizações aparece aqui.
+          </p>
+        </div>
+      </div>
+
+      {log.length > 0 && (
+        <div className="space-y-2">
+          <div className="flex items-center gap-2">
+            <History className="h-4 w-4 text-muted-foreground" />
+            <h4 className="text-sm font-semibold">Histórico</h4>
+          </div>
+          <div className="divide-y rounded-md border text-sm">
+            {log.map((r) => (
+              <div key={r.id} className="flex items-center gap-3 px-3 py-2">
+                <span className="text-xs text-muted-foreground">{new Date(r.createdAt).toLocaleString('pt-BR')}</span>
+                <span className="ml-auto text-xs">{r.written}/{r.fetched} publicadas</span>
+                {r.status === 'success'
+                  ? <CheckCircle2 className="h-3.5 w-3.5 text-success" />
+                  : <AlertCircle className="h-3.5 w-3.5 text-warning" />}
+              </div>
+            ))}
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}
+
+export const ranklayerConnectorDef: ConnectorDefinition = {
+  id: 'ranklayer',
+  hostPluginId: 'marketing',
+  name: 'RankLayer',
+  description: 'Publicação de conteúdo e páginas de SEO por serviço/bairro para ser encontrado no Google e em assistentes de IA.',
+  icon: 'Search',
+  authKind: 'api-key',
+  fields: [
+    { key: 'apiKey', label: 'API Key', type: 'password', placeholder: '••••••••' },
+    { key: 'siteDomain', label: 'Domínio do site', type: 'text', placeholder: 'exemplo.com.br' },
+  ],
+  async getStatus() {
+    try {
+      const found = await provider.getIntegration()
+      return { connected: !!found?.apiKey, detail: found?.siteDomain }
+    } catch {
+      return { connected: false }
+    }
+  },
+  testConnection: (values) => provider.testConnection({ apiKey: values.apiKey }),
+  saveConnection: async (values) => { await provider.saveIntegration({ apiKey: values.apiKey, siteDomain: values.siteDomain }) },
+  disconnect: () => provider.disconnect(),
+  ExtraPanel: RankLayerExtraPanel,
+}

package/src/integrations/ranklayer/data/supabase.ts

@@ -0,0 +1,106 @@
+import { getSupabaseClientOptional, getActiveTenantId } from '@fayz-ai/core'
+import type { TestConnectionResult } from '@fayz-ai/core'
+import type { RankLayerIntegration, RankLayerSyncLogEntry } from '../types'
+
+// ---------------------------------------------------------------------------
+// RankLayer connector — control-plane client (SCAFFOLD).
+//
+// Reads/writes the connection row (plg_marketing_ranklayer_integrations) and
+// reads the sync log. `testConnection` and `sync` are stubbed: RankLayer has no
+// public API wired yet, so the real work (an edge function calling RankLayer)
+// lands via an external PR — see ../RANKLAYER.md. Everything here is safe to
+// ship: it only persists the tenant's API key + domain and surfaces status.
+// ---------------------------------------------------------------------------
+
+const INTEGRATIONS = 'plg_marketing_ranklayer_integrations'
+const SYNC_LOG = 'plg_marketing_ranklayer_sync_log'
+
+function getClient() {
+  const supabase = getSupabaseClientOptional() as { from: (t: string) => any } | null
+  if (!supabase) throw new Error('[ranklayer] Supabase not initialized')
+  return supabase
+}
+
+function requireTenantId(): string {
+  const tenantId = getActiveTenantId()
+  if (!tenantId) throw new Error('[ranklayer] No active tenant')
+  return tenantId
+}
+
+function toIntegration(row: Record<string, any>): RankLayerIntegration {
+  return {
+    id: row.id,
+    apiKey: row.api_key ?? undefined,
+    siteDomain: row.site_domain ?? undefined,
+    active: row.active ?? true,
+    lastSyncAt: row.last_sync_at ?? undefined,
+  }
+}
+
+export function createRankLayerProvider() {
+  return {
+    async getIntegration(): Promise<RankLayerIntegration | null> {
+      const tenantId = getActiveTenantId()
+      if (!tenantId) return null
+      const { data } = await getClient()
+        .from(INTEGRATIONS)
+        .select('*')
+        .eq('tenant_id', tenantId)
+        .maybeSingle()
+      return data ? toIntegration(data) : null
+    },
+
+    async saveIntegration(values: { apiKey: string; siteDomain?: string }): Promise<RankLayerIntegration> {
+      const tenantId = requireTenantId()
+      const payload = {
+        tenant_id: tenantId,
+        api_key: values.apiKey,
+        site_domain: values.siteDomain ?? null,
+        active: true,
+        updated_at: new Date().toISOString(),
+      }
+      // Upsert on the unique tenant_id.
+      const { data, error } = await getClient()
+        .from(INTEGRATIONS)
+        .upsert(payload, { onConflict: 'tenant_id' })
+        .select('*')
+        .single()
+      if (error) throw error
+      return toIntegration(data)
+    },
+
+    async disconnect(): Promise<void> {
+      const tenantId = getActiveTenantId()
+      if (!tenantId) return
+      await getClient().from(INTEGRATIONS).delete().eq('tenant_id', tenantId)
+    },
+
+    // SCAFFOLD: no RankLayer API yet — accept any non-empty key so the connect
+    // flow can be exercised. Replace with a real credential check in the PR.
+    async testConnection(values: { apiKey: string }): Promise<TestConnectionResult> {
+      if (!values.apiKey || values.apiKey.trim().length < 8) {
+        return { ok: false, message: 'Informe uma API Key válida da RankLayer.' }
+      }
+      return { ok: true, message: 'Chave aceita (validação real pendente — integração em preparação).' }
+    },
+
+    async getSyncLog(integrationId: string): Promise<RankLayerSyncLogEntry[]> {
+      const { data } = await getClient()
+        .from(SYNC_LOG)
+        .select('*')
+        .eq('integration_id', integrationId)
+        .order('created_at', { ascending: false })
+        .limit(20)
+      return (data ?? []).map((r: Record<string, any>) => ({
+        id: r.id,
+        createdAt: r.created_at,
+        status: r.status,
+        message: r.message ?? undefined,
+        fetched: r.fetched ?? 0,
+        written: r.written ?? 0,
+      }))
+    },
+  }
+}
+
+export type RankLayerProvider = ReturnType<typeof createRankLayerProvider>

package/src/integrations/ranklayer/types.ts

@@ -0,0 +1,16 @@
+export interface RankLayerIntegration {
+  id: string
+  apiKey?: string
+  siteDomain?: string
+  active: boolean
+  lastSyncAt?: string
+}
+
+export interface RankLayerSyncLogEntry {
+  id: string
+  createdAt: string
+  status: 'success' | 'partial' | 'error'
+  message?: string
+  fetched: number
+  written: number
+}

package/src/migrations/004_ranklayer.sql

@@ -0,0 +1,50 @@
+-- Marketing Plugin: RankLayer integration (SEO content publishing).
+-- Control-plane state for the RankLayer connector rendered in Marketing →
+-- Integrações. Prefix: plg_marketing_ranklayer_. Scaffold: the real sync
+-- (edge function + RankLayer API calls) lands via an external PR — see
+-- src/integrations/ranklayer/RANKLAYER.md.
+
+CREATE TABLE IF NOT EXISTS public.plg_marketing_ranklayer_integrations (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
+  api_key text,
+  site_domain text,
+  active boolean NOT NULL DEFAULT true,
+  last_sync_at timestamptz,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+ALTER TABLE public.plg_marketing_ranklayer_integrations ENABLE ROW LEVEL SECURITY;
+CREATE UNIQUE INDEX IF NOT EXISTS uq_plg_marketing_ranklayer_integrations_tenant
+  ON public.plg_marketing_ranklayer_integrations(tenant_id);
+
+CREATE TABLE IF NOT EXISTS public.plg_marketing_ranklayer_sync_log (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
+  integration_id uuid REFERENCES public.plg_marketing_ranklayer_integrations(id) ON DELETE CASCADE,
+  status text NOT NULL DEFAULT 'success' CHECK (status IN ('success', 'partial', 'error')),
+  message text,
+  fetched integer NOT NULL DEFAULT 0,
+  written integer NOT NULL DEFAULT 0,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+ALTER TABLE public.plg_marketing_ranklayer_sync_log ENABLE ROW LEVEL SECURITY;
+CREATE INDEX IF NOT EXISTS idx_plg_marketing_ranklayer_sync_log_tenant
+  ON public.plg_marketing_ranklayer_sync_log(tenant_id, created_at DESC);
+
+-- RLS: authenticated tenant CRUD
+DROP POLICY IF EXISTS plg_marketing_ranklayer_integrations_select ON public.plg_marketing_ranklayer_integrations;
+DROP POLICY IF EXISTS plg_marketing_ranklayer_integrations_insert ON public.plg_marketing_ranklayer_integrations;
+DROP POLICY IF EXISTS plg_marketing_ranklayer_integrations_update ON public.plg_marketing_ranklayer_integrations;
+DROP POLICY IF EXISTS plg_marketing_ranklayer_integrations_delete ON public.plg_marketing_ranklayer_integrations;
+CREATE POLICY plg_marketing_ranklayer_integrations_select ON public.plg_marketing_ranklayer_integrations FOR SELECT TO authenticated USING (tenant_id IN (SELECT public.user_tenant_ids()));
+CREATE POLICY plg_marketing_ranklayer_integrations_insert ON public.plg_marketing_ranklayer_integrations FOR INSERT TO authenticated WITH CHECK (tenant_id IN (SELECT public.user_tenant_ids()));
+CREATE POLICY plg_marketing_ranklayer_integrations_update ON public.plg_marketing_ranklayer_integrations FOR UPDATE TO authenticated USING (tenant_id IN (SELECT public.user_tenant_ids()));
+CREATE POLICY plg_marketing_ranklayer_integrations_delete ON public.plg_marketing_ranklayer_integrations FOR DELETE TO authenticated USING (tenant_id IN (SELECT public.user_tenant_ids()));
+GRANT SELECT, INSERT, UPDATE, DELETE ON public.plg_marketing_ranklayer_integrations TO authenticated;
+
+DROP POLICY IF EXISTS plg_marketing_ranklayer_sync_log_select ON public.plg_marketing_ranklayer_sync_log;
+DROP POLICY IF EXISTS plg_marketing_ranklayer_sync_log_insert ON public.plg_marketing_ranklayer_sync_log;
+CREATE POLICY plg_marketing_ranklayer_sync_log_select ON public.plg_marketing_ranklayer_sync_log FOR SELECT TO authenticated USING (tenant_id IN (SELECT public.user_tenant_ids()));
+CREATE POLICY plg_marketing_ranklayer_sync_log_insert ON public.plg_marketing_ranklayer_sync_log FOR INSERT TO authenticated WITH CHECK (tenant_id IN (SELECT public.user_tenant_ids()));
+GRANT SELECT, INSERT ON public.plg_marketing_ranklayer_sync_log TO authenticated;

package/src/migrations/005_analytics_base.sql

@@ -0,0 +1,60 @@
+-- Marketing Plugin: analytics base tables (channels + campaigns).
+-- Prefix: plg_marketing_
+-- Channels are tenant-owned rows lazily seeded from the app's domain preset
+-- (channel_key = preset/config id). Campaign performance is DERIVED at read
+-- time from v_marketing_attribution (006); only spend is stored.
+-- Canonical RLS form: tenant_id IN (SELECT public.user_tenant_ids()).
+
+CREATE TABLE IF NOT EXISTS public.plg_marketing_channels (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
+  channel_key text NOT NULL,
+  label text NOT NULL,
+  icon text,
+  kind text NOT NULL DEFAULT 'organic'
+    CHECK (kind IN ('paid', 'organic', 'social', 'referral', 'direct', 'outbound')),
+  is_active boolean NOT NULL DEFAULT true,
+  monthly_spend numeric NOT NULL DEFAULT 0,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS idx_plg_marketing_channels_tenant ON public.plg_marketing_channels(tenant_id);
+CREATE UNIQUE INDEX IF NOT EXISTS u_plg_marketing_channels_tenant_key ON public.plg_marketing_channels(tenant_id, channel_key);
+
+CREATE TABLE IF NOT EXISTS public.plg_marketing_campaigns (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
+  name text NOT NULL,
+  channel_key text NOT NULL,
+  status text NOT NULL DEFAULT 'draft'
+    CHECK (status IN ('active', 'paused', 'ended', 'draft')),
+  starts_at timestamptz,
+  ends_at timestamptz,
+  spend numeric NOT NULL DEFAULT 0,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS idx_plg_marketing_campaigns_tenant ON public.plg_marketing_campaigns(tenant_id);
+CREATE INDEX IF NOT EXISTS idx_plg_marketing_campaigns_channel ON public.plg_marketing_campaigns(tenant_id, channel_key);
+
+DO $$
+DECLARE t text;
+BEGIN
+  FOR t IN SELECT unnest(ARRAY['plg_marketing_channels','plg_marketing_campaigns'])
+  LOOP
+    EXECUTE format('ALTER TABLE public.%I ENABLE ROW LEVEL SECURITY', t);
+    EXECUTE format('GRANT SELECT, INSERT, UPDATE, DELETE ON public.%I TO authenticated', t);
+    IF NOT EXISTS (SELECT 1 FROM pg_policies WHERE schemaname='public' AND tablename=t AND policyname=t||'_select') THEN
+      EXECUTE format('CREATE POLICY %I ON public.%I FOR SELECT TO authenticated USING (tenant_id IN (SELECT public.user_tenant_ids()))', t||'_select', t);
+    END IF;
+    IF NOT EXISTS (SELECT 1 FROM pg_policies WHERE schemaname='public' AND tablename=t AND policyname=t||'_insert') THEN
+      EXECUTE format('CREATE POLICY %I ON public.%I FOR INSERT TO authenticated WITH CHECK (tenant_id IN (SELECT public.user_tenant_ids()))', t||'_insert', t);
+    END IF;
+    IF NOT EXISTS (SELECT 1 FROM pg_policies WHERE schemaname='public' AND tablename=t AND policyname=t||'_update') THEN
+      EXECUTE format('CREATE POLICY %I ON public.%I FOR UPDATE TO authenticated USING (tenant_id IN (SELECT public.user_tenant_ids()))', t||'_update', t);
+    END IF;
+    IF NOT EXISTS (SELECT 1 FROM pg_policies WHERE schemaname='public' AND tablename=t AND policyname=t||'_delete') THEN
+      EXECUTE format('CREATE POLICY %I ON public.%I FOR DELETE TO authenticated USING (tenant_id IN (SELECT public.user_tenant_ids()))', t||'_delete', t);
+    END IF;
+  END LOOP;
+END $$;

package/src/migrations/006_analytics_views.sql

@@ -0,0 +1,68 @@
+-- Marketing Plugin: analytics read views.
+-- v_marketing_channels / v_marketing_campaigns — bridge views for the surface
+-- and the agent's data primitives.
+-- v_marketing_attribution — GENERIC, spine-only attribution event stream
+-- (people/appointments/orders metadata). `channel_raw` is the unnormalized
+-- origin string; the provider matches it against the app's channel set
+-- (id or label, case/punctuation-insensitive).
+-- Apps whose origin lives in an app-local extension table (e.g. beauty's
+-- clients.origin) may CREATE OR REPLACE this view in their own incubator
+-- migration, KEEPING the column contract:
+--   (tenant_id uuid, kind text, source text, channel_raw text,
+--    occurred_at timestamptz, value numeric)
+
+CREATE OR REPLACE VIEW public.v_marketing_channels WITH (security_invoker=true) AS
+SELECT c.id, c.tenant_id, c.channel_key, c.label, c.icon, c.kind,
+       c.is_active, c.monthly_spend, c.created_at, c.updated_at
+FROM public.plg_marketing_channels c;
+GRANT SELECT ON public.v_marketing_channels TO authenticated;
+
+CREATE OR REPLACE VIEW public.v_marketing_campaigns WITH (security_invoker=true) AS
+SELECT g.id, g.tenant_id, g.name, g.channel_key, ch.label AS channel_label,
+       g.status, g.starts_at, g.ends_at, g.spend, g.created_at, g.updated_at
+FROM public.plg_marketing_campaigns g
+LEFT JOIN public.plg_marketing_channels ch
+  ON ch.tenant_id = g.tenant_id AND ch.channel_key = g.channel_key;
+GRANT SELECT ON public.v_marketing_campaigns TO authenticated;
+
+CREATE OR REPLACE VIEW public.v_marketing_attribution WITH (security_invoker=true) AS
+-- lead events (CRM leads; sourceId aligns with lead-sources/channel ids)
+SELECT p.tenant_id,
+       'lead'::text AS kind,
+       'crm'::text AS source,
+       COALESCE(p.metadata->>'sourceId', p.metadata->>'sourceName', p.metadata->>'origin') AS channel_raw,
+       p.created_at AS occurred_at,
+       NULLIF(p.metadata->>'value', '')::numeric AS value
+FROM public.people p
+WHERE p.kind = 'lead'
+UNION ALL
+-- booking conversions (agenda verticals)
+SELECT b.tenant_id, 'conversion', 'agenda',
+       COALESCE(b.metadata->>'origin', pc.metadata->>'origin', pc.metadata->>'sourceId', pc.metadata->>'sourceName'),
+       b.starts_at,
+       o.total
+FROM public.appointments b
+LEFT JOIN public.people pc ON pc.id = b.party_id
+LEFT JOIN public.orders o ON o.id = b.order_id
+WHERE b.status NOT IN ('cancelled', 'no_show')
+UNION ALL
+-- order conversions (commerce verticals)
+SELECT o.tenant_id, 'conversion', 'orders',
+       COALESCE(o.metadata->>'origin', pp.metadata->>'origin', pp.metadata->>'sourceId'),
+       o.created_at,
+       o.total
+FROM public.orders o
+LEFT JOIN public.people pp ON pp.id = o.party_id
+WHERE o.kind NOT IN ('appointment', 'deal')
+  AND o.status NOT IN ('cancelled', 'draft')
+UNION ALL
+-- won-deal conversions (CRM verticals)
+SELECT o.tenant_id, 'conversion', 'crm',
+       COALESCE(pp.metadata->>'sourceId', pp.metadata->>'sourceName', o.metadata->>'origin'),
+       o.updated_at,
+       o.total
+FROM public.orders o
+LEFT JOIN public.people pp ON pp.id = o.party_id
+WHERE o.kind = 'deal' AND o.status = 'won';
+
+GRANT SELECT ON public.v_marketing_attribution TO authenticated;

package/src/migrations/007_agent_rpcs.sql

@@ -0,0 +1,119 @@
+-- ============================================================================
+-- plugin-marketing 007: server-plane agent write RPC.
+--
+-- public.agent_marketing_create_campaign — guarded campaign create for the
+-- assistant. Mirrors agent_agenda_create_appointment (agenda 005):
+--   * actor-authorized: public.agent_guard (spine 015) runs role→plan→limit
+--     BEFORE anything — denial comes back as structured jsonb;
+--   * channel is validated against the tenant's plg_marketing_channels rows
+--     (key or label, case/punctuation-insensitive); when the tenant has no
+--     channel rows yet (surface not opened → lazy seed not run) the raw key is
+--     accepted as-is;
+--   * audited: audit_logs row with the acting user.
+--
+-- Contract (all agent_* RPCs): (p_tenant_id, p_actor_user_id, p_payload jsonb)
+-- → jsonb {ok:true, id, record:{...}} | {ok:false, denial:{...}} | {ok:false,
+-- error text}. GRANT authenticated+service_role — NEVER anon.
+-- ============================================================================
+
+CREATE OR REPLACE FUNCTION public.agent_marketing_create_campaign(
+  p_tenant_id uuid,
+  p_actor_user_id uuid,
+  p_payload jsonb
+) RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE
+  v_denial jsonb;
+  v_used int;
+  v_name text;
+  v_channel_raw text;
+  v_channel_key text;
+  v_status text;
+  v_starts timestamptz;
+  v_ends timestamptz;
+  v_spend numeric;
+  v_has_channels boolean;
+  v_id uuid;
+BEGIN
+  -- ── payload ──────────────────────────────────────────────────────────────
+  v_name := left(trim(p_payload->>'name'), 200);
+  v_channel_raw := trim(p_payload->>'channel_key');
+  v_status := COALESCE(NULLIF(trim(p_payload->>'status'), ''), 'draft');
+  v_spend := COALESCE(NULLIF(p_payload->>'spend', '')::numeric, 0);
+  BEGIN
+    v_starts := NULLIF(p_payload->>'starts_at', '')::timestamptz;
+    v_ends := NULLIF(p_payload->>'ends_at', '')::timestamptz;
+  EXCEPTION WHEN OTHERS THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'invalid payload: ' || SQLERRM);
+  END;
+  IF v_name IS NULL OR v_name = '' OR v_channel_raw IS NULL OR v_channel_raw = '' THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'name and channel_key are required');
+  END IF;
+  IF v_status NOT IN ('active', 'paused', 'ended', 'draft') THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'status must be one of active|paused|ended|draft');
+  END IF;
+
+  -- ── authorization: role → plan → campaigns_active cap ────────────────────
+  SELECT count(*) INTO v_used FROM plg_marketing_campaigns c
+  WHERE c.tenant_id = p_tenant_id AND c.status = 'active';
+  v_denial := agent_guard(p_tenant_id, p_actor_user_id,
+                          'marketing', 'create', 'campaigns_active', v_used,
+                          CASE WHEN v_status = 'active' THEN 1 ELSE 0 END);
+  IF v_denial IS NOT NULL THEN
+    RETURN jsonb_build_object('ok', false, 'denial', v_denial);
+  END IF;
+
+  -- ── channel resolution (key or label, normalized) ────────────────────────
+  SELECT EXISTS (SELECT 1 FROM plg_marketing_channels ch WHERE ch.tenant_id = p_tenant_id)
+    INTO v_has_channels;
+  IF v_has_channels THEN
+    SELECT ch.channel_key INTO v_channel_key
+    FROM plg_marketing_channels ch
+    WHERE ch.tenant_id = p_tenant_id
+      AND (
+        regexp_replace(lower(ch.channel_key), '[^a-z0-9]', '', 'g')
+          = regexp_replace(lower(v_channel_raw), '[^a-z0-9]', '', 'g')
+        OR regexp_replace(lower(ch.label), '[^a-z0-9]', '', 'g')
+          = regexp_replace(lower(v_channel_raw), '[^a-z0-9]', '', 'g')
+      )
+    LIMIT 1;
+    IF v_channel_key IS NULL THEN
+      RETURN jsonb_build_object('ok', false, 'error',
+        'unknown channel "' || v_channel_raw || '" — valid channels: ' ||
+        COALESCE((SELECT string_agg(ch.channel_key, ', ' ORDER BY ch.channel_key)
+                  FROM plg_marketing_channels ch WHERE ch.tenant_id = p_tenant_id), ''));
+    END IF;
+  ELSE
+    v_channel_key := v_channel_raw;
+  END IF;
+
+  -- ── write + audit ────────────────────────────────────────────────────────
+  INSERT INTO plg_marketing_campaigns (tenant_id, name, channel_key, status, starts_at, ends_at, spend)
+  VALUES (p_tenant_id, v_name, v_channel_key, v_status, COALESCE(v_starts, now()), v_ends, v_spend)
+  RETURNING id INTO v_id;
+
+  INSERT INTO audit_logs (tenant_id, user_id, action, entity_type, entity_id, metadata)
+  VALUES (p_tenant_id, p_actor_user_id, 'agent.createCampaign', 'marketing_campaign', v_id::text,
+          jsonb_build_object('payload', p_payload));
+
+  RETURN jsonb_build_object(
+    'ok', true,
+    'id', v_id,
+    'record', jsonb_build_object(
+      'id', v_id,
+      'name', v_name,
+      'channel_key', v_channel_key,
+      'status', v_status,
+      'starts_at', COALESCE(v_starts, now()),
+      'spend', v_spend
+    )
+  );
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.agent_marketing_create_campaign(uuid, uuid, jsonb) FROM public;
+REVOKE EXECUTE ON FUNCTION public.agent_marketing_create_campaign(uuid, uuid, jsonb) FROM anon;
+GRANT EXECUTE ON FUNCTION public.agent_marketing_create_campaign(uuid, uuid, jsonb)
+  TO authenticated, service_role;