@fayz-ai/plugin-agenda 0.8.1 → 0.8.4

package/src/migrations/004_public_booking_assignee.sql

@@ -0,0 +1,176 @@
+-- ---------------------------------------------------------------------------
+-- Public booking — respect the professional the visitor saw
+-- ---------------------------------------------------------------------------
+-- Until now create_public_booking IGNORED which professional the site showed
+-- availability for and re-picked by working hours (ORDER BY assignee_id
+-- LIMIT 1). With several professionals covering the same slot the booking
+-- landed on someone else than displayed ("Equipe Great DJs" on the site,
+-- "Rafa Groove" in the agenda). New optional p_assignee_id:
+--   * provided → validate THAT professional's working hours cover the slot and
+--     book them — never silently reassign (mismatch becomes an explicit error);
+--   * NULL → auto-pick as before (sites that don't pin a professional).
+-- Conflict check + advisory lock already run against the resolved assignee, so
+-- the double-book guard follows whichever path resolves.
+--
+-- Signature change (8th arg): the old 7-arg function is DROPPED first —
+-- CREATE OR REPLACE with a different signature would create an ambiguous
+-- PostgREST overload instead of replacing.
+-- Includes 003's tenant-configurable client kind. Idempotent.
+-- ---------------------------------------------------------------------------
+DROP FUNCTION IF EXISTS public.create_public_booking(uuid, uuid, timestamptz, text, text, text, text);
+
+CREATE OR REPLACE FUNCTION public.create_public_booking(
+  p_tenant_id uuid,
+  p_service_id uuid,
+  p_starts_at timestamptz,
+  p_name text,
+  p_phone text,
+  p_email text DEFAULT NULL,
+  p_notes text DEFAULT NULL,
+  p_assignee_id uuid DEFAULT NULL
+) RETURNS TABLE (booking_id uuid, starts_at timestamptz, ends_at timestamptz)
+LANGUAGE plpgsql SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE
+  v_service record;
+  v_person_id uuid;
+  v_assignee uuid;
+  v_ends timestamptz;
+  v_order uuid;
+  v_booking uuid;
+  v_phone text;
+  v_tz text;
+  v_notes text;
+  v_client_kind text;
+BEGIN
+  -- validation: anon-callable, everything tight
+  IF p_name IS NULL OR length(trim(p_name)) NOT BETWEEN 2 AND 120 THEN
+    RAISE EXCEPTION 'invalid name';
+  END IF;
+  v_phone := regexp_replace(COALESCE(p_phone, ''), '\D', '', 'g');
+  IF length(v_phone) NOT BETWEEN 8 AND 15 THEN
+    RAISE EXCEPTION 'invalid phone';
+  END IF;
+  IF p_email IS NOT NULL AND (length(p_email) > 254 OR p_email !~ '^[^@\s]+@[^@\s]+\.[^@\s]+$') THEN
+    RAISE EXCEPTION 'invalid email';
+  END IF;
+  v_notes := left(p_notes, 500);
+  IF p_starts_at IS NULL OR p_starts_at <= now() OR p_starts_at > now() + interval '90 days' THEN
+    RAISE EXCEPTION 'invalid start';
+  END IF;
+
+  SELECT s.id, s.name, s.price, COALESCE(s.duration_minutes, 30) AS duration_minutes
+    INTO v_service
+  FROM services s
+  WHERE s.id = p_service_id AND s.tenant_id = p_tenant_id
+    AND s.is_active AND s.status = 'active';
+  IF NOT FOUND THEN RAISE EXCEPTION 'unknown service'; END IF;
+
+  v_ends := p_starts_at + make_interval(mins => v_service.duration_minutes);
+
+  -- tenant config: timezone + client kind (admin-set; sanitized, never caller input)
+  SELECT COALESCE(t.settings->>'timezone', 'America/Sao_Paulo'),
+         COALESCE(NULLIF(trim(t.settings->'booking'->>'client_kind'), ''), 'customer')
+    INTO v_tz, v_client_kind
+  FROM tenants t WHERE t.id = p_tenant_id;
+  IF v_tz IS NULL THEN RAISE EXCEPTION 'unknown tenant'; END IF;
+  IF v_client_kind !~ '^[a-z_]{2,32}$' THEN v_client_kind := 'customer'; END IF;
+
+  -- resolve the professional: the one the visitor saw (validated), else the
+  -- first whose working hours cover the slot
+  SELECT sc.assignee_id INTO v_assignee
+  FROM schedules sc
+  WHERE sc.tenant_id = p_tenant_id
+    AND sc.kind = 'working_hours'
+    AND sc.is_active
+    AND (p_assignee_id IS NULL OR sc.assignee_id = p_assignee_id)
+    AND (
+      sc.specific_date = (p_starts_at AT TIME ZONE v_tz)::date
+      OR (sc.specific_date IS NULL
+          AND sc.day_of_week = EXTRACT(dow FROM p_starts_at AT TIME ZONE v_tz)::smallint)
+    )
+    AND (p_starts_at AT TIME ZONE v_tz)::time >= sc.starts_at
+    AND (v_ends AT TIME ZONE v_tz)::time <= sc.ends_at
+  ORDER BY sc.assignee_id
+  LIMIT 1;
+  IF v_assignee IS NULL THEN RAISE EXCEPTION 'slot outside working hours'; END IF;
+
+  -- serialize per (tenant, assignee) to kill the double-book race
+  PERFORM pg_advisory_xact_lock(hashtextextended(p_tenant_id::text || v_assignee::text, 0));
+
+  IF EXISTS (
+    SELECT 1 FROM appointments b
+    WHERE b.tenant_id = p_tenant_id
+      AND b.assignee_id = v_assignee
+      AND b.status NOT IN ('cancelled', 'no_show')
+      AND b.starts_at < v_ends
+      AND COALESCE(b.ends_at, b.starts_at) > p_starts_at
+  ) THEN
+    RAISE EXCEPTION 'slot no longer available';
+  END IF;
+
+  -- anti-spam: cap open future public bookings per phone per tenant
+  IF (
+    SELECT count(*) FROM appointments b
+    JOIN people p ON p.id = b.party_id
+    WHERE b.tenant_id = p_tenant_id
+      AND p.phone = v_phone
+      AND b.starts_at > now()
+      AND b.status = 'scheduled'
+  ) >= 3 THEN
+    RAISE EXCEPTION 'too many open bookings for this phone';
+  END IF;
+
+  -- upsert the client by (tenant, kind, phone), serialized by advisory lock
+  -- (kind is tenant-configured, so the customer-only partial index can't
+  -- arbitrate)
+  PERFORM pg_advisory_xact_lock(hashtextextended(p_tenant_id::text || ':' || v_phone, 1));
+
+  SELECT p.id INTO v_person_id
+  FROM people p
+  WHERE p.tenant_id = p_tenant_id AND p.kind = v_client_kind AND p.phone = v_phone
+  ORDER BY p.created_at
+  LIMIT 1;
+
+  IF v_person_id IS NOT NULL THEN
+    UPDATE people SET
+      name = trim(p_name),
+      email = COALESCE(p_email, people.email),
+      updated_at = now()
+    WHERE id = v_person_id;
+  ELSE
+    INSERT INTO people (tenant_id, kind, name, phone, email, metadata)
+    VALUES (p_tenant_id, v_client_kind, trim(p_name), v_phone, p_email,
+            jsonb_build_object('source', 'public_booking'))
+    RETURNING id INTO v_person_id;
+  END IF;
+
+  -- order + booking + order_item (statuses hardcoded — caller cannot set)
+  INSERT INTO orders (tenant_id, kind, status, party_id, assignee_id, subtotal, total, notes, metadata)
+  VALUES (p_tenant_id, 'appointment', 'scheduled', v_person_id, v_assignee,
+          v_service.price, v_service.price, v_notes,
+          jsonb_build_object('source', 'public_booking',
+                             'serviceNames', v_service.name,
+                             'contactName', trim(p_name)))
+  RETURNING id INTO v_order;
+
+  INSERT INTO appointments (tenant_id, kind, party_id, assignee_id, order_id,
+                        starts_at, ends_at, status, notes, metadata)
+  VALUES (p_tenant_id, 'appointment', v_person_id, v_assignee, v_order,
+          p_starts_at, v_ends, 'scheduled', v_notes,
+          jsonb_build_object('source', 'public_booking', 'serviceNames', v_service.name))
+  RETURNING id INTO v_booking;
+
+  INSERT INTO order_items (order_id, service_id, name, quantity, unit_price, total,
+                           sort_order, duration_minutes, assignee_id)
+  VALUES (v_order, v_service.id, v_service.name, 1, v_service.price, v_service.price,
+          0, v_service.duration_minutes, v_assignee);
+
+  RETURN QUERY SELECT v_booking, p_starts_at, v_ends;
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.create_public_booking(uuid, uuid, timestamptz, text, text, text, text, uuid) FROM public;
+GRANT EXECUTE ON FUNCTION public.create_public_booking(uuid, uuid, timestamptz, text, text, text, text, uuid)
+  TO anon, authenticated, service_role;

package/src/migrations/005_agent_rpcs.sql

@@ -0,0 +1,168 @@
+-- ============================================================================
+-- plugin-agenda 005: server-plane agent write RPC.
+--
+-- public.agent_agenda_create_appointment — the INTERNAL (operator-actor)
+-- counterpart of create_public_booking (001 §5): same invariants (working
+-- hours, advisory-lock race safety, hardcoded statuses), but:
+--   * actor-authorized: public.agent_guard (spine 015) runs role→plan→limit
+--     BEFORE anything — denial comes back as a structured jsonb the agent can
+--     explain conversationally, never a raised exception;
+--   * the client is an EXISTING person id (the agent resolves names→ids via
+--     reads first — ambiguity is a conversation problem, not a SQL one);
+--   * a requested professional is honored (working hours permitting);
+--   * 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 (the Fayz broker
+-- calls with the pool service key and injects tenant/actor server-side).
+-- ============================================================================
+
+CREATE OR REPLACE FUNCTION public.agent_agenda_create_appointment(
+  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_client_id uuid;
+  v_service_id uuid;
+  v_professional uuid;
+  v_starts timestamptz;
+  v_notes text;
+  v_service record;
+  v_client record;
+  v_ends timestamptz;
+  v_tz text;
+  v_order uuid;
+  v_booking uuid;
+BEGIN
+  -- ── payload ──────────────────────────────────────────────────────────────
+  BEGIN
+    v_client_id    := (p_payload->>'client_id')::uuid;
+    v_service_id   := (p_payload->>'service_id')::uuid;
+    v_professional := (p_payload->>'professional_id')::uuid;
+    v_starts       := (p_payload->>'starts_at')::timestamptz;
+  EXCEPTION WHEN OTHERS THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'invalid payload: ' || SQLERRM);
+  END;
+  v_notes := left(p_payload->>'notes', 500);
+  IF v_client_id IS NULL OR v_service_id IS NULL OR v_starts IS NULL THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'client_id, service_id and starts_at are required');
+  END IF;
+  IF v_starts <= now() OR v_starts > now() + interval '365 days' THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'starts_at must be in the future (max 1 year)');
+  END IF;
+
+  -- ── authorization: role → plan → bookings_month cap ──────────────────────
+  SELECT count(*) INTO v_used FROM appointments b
+  WHERE b.tenant_id = p_tenant_id
+    AND b.created_at >= date_trunc('month', now());
+  v_denial := agent_guard(p_tenant_id, p_actor_user_id,
+                          'appointments', 'create', 'bookings_month', v_used, 1);
+  IF v_denial IS NOT NULL THEN
+    RETURN jsonb_build_object('ok', false, 'denial', v_denial);
+  END IF;
+
+  -- ── invariants ───────────────────────────────────────────────────────────
+  SELECT p.id, p.name INTO v_client
+  FROM people p
+  WHERE p.id = v_client_id AND p.tenant_id = p_tenant_id;
+  IF NOT FOUND THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'unknown client for this tenant');
+  END IF;
+
+  SELECT s.id, s.name, s.price, COALESCE(s.duration_minutes, 30) AS duration_minutes
+    INTO v_service
+  FROM services s
+  WHERE s.id = v_service_id AND s.tenant_id = p_tenant_id
+    AND s.is_active AND s.status = 'active';
+  IF NOT FOUND THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'unknown or inactive service');
+  END IF;
+
+  v_ends := v_starts + make_interval(mins => v_service.duration_minutes);
+  SELECT COALESCE(t.settings->>'timezone', 'America/Sao_Paulo') INTO v_tz
+  FROM tenants t WHERE t.id = p_tenant_id;
+
+  -- requested professional honored; otherwise pick one whose hours cover the slot
+  SELECT sc.assignee_id INTO v_professional
+  FROM schedules sc
+  WHERE sc.tenant_id = p_tenant_id
+    AND sc.kind = 'working_hours'
+    AND sc.is_active
+    AND (v_professional IS NULL OR sc.assignee_id = v_professional)
+    AND (
+      sc.specific_date = (v_starts AT TIME ZONE v_tz)::date
+      OR (sc.specific_date IS NULL
+          AND sc.day_of_week = EXTRACT(dow FROM v_starts AT TIME ZONE v_tz)::smallint)
+    )
+    AND (v_starts AT TIME ZONE v_tz)::time >= sc.starts_at
+    AND (v_ends AT TIME ZONE v_tz)::time <= sc.ends_at
+  ORDER BY sc.assignee_id
+  LIMIT 1;
+  IF v_professional IS NULL THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'slot outside working hours for the requested professional');
+  END IF;
+
+  -- race safety: serialize per (tenant, professional), then conflict-check
+  PERFORM pg_advisory_xact_lock(hashtextextended(p_tenant_id::text || v_professional::text, 0));
+  IF EXISTS (
+    SELECT 1 FROM appointments b
+    WHERE b.tenant_id = p_tenant_id
+      AND b.assignee_id = v_professional
+      AND b.status NOT IN ('cancelled', 'no_show')
+      AND b.starts_at < v_ends
+      AND COALESCE(b.ends_at, b.starts_at) > v_starts
+  ) THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'slot no longer available');
+  END IF;
+
+  -- ── write (statuses hardcoded) + audit ───────────────────────────────────
+  INSERT INTO orders (tenant_id, kind, status, party_id, assignee_id, subtotal, total, notes, metadata)
+  VALUES (p_tenant_id, 'appointment', 'scheduled', v_client_id, v_professional,
+          v_service.price, v_service.price, v_notes,
+          jsonb_build_object('source', 'agent', 'serviceNames', v_service.name))
+  RETURNING id INTO v_order;
+
+  INSERT INTO appointments (tenant_id, kind, party_id, assignee_id, order_id,
+                            starts_at, ends_at, status, notes, metadata)
+  VALUES (p_tenant_id, 'appointment', v_client_id, v_professional, v_order,
+          v_starts, v_ends, 'scheduled', v_notes,
+          jsonb_build_object('source', 'agent', 'serviceNames', v_service.name))
+  RETURNING id INTO v_booking;
+
+  INSERT INTO order_items (order_id, service_id, name, quantity, unit_price, total,
+                           sort_order, duration_minutes, assignee_id)
+  VALUES (v_order, v_service.id, v_service.name, 1, v_service.price, v_service.price,
+          0, v_service.duration_minutes, v_professional);
+
+  INSERT INTO audit_logs (tenant_id, user_id, action, entity_type, entity_id, metadata)
+  VALUES (p_tenant_id, p_actor_user_id, 'agent.createAppointment', 'appointment', v_booking::text,
+          jsonb_build_object('payload', p_payload, 'order_id', v_order));
+
+  RETURN jsonb_build_object(
+    'ok', true,
+    'id', v_booking,
+    'record', jsonb_build_object(
+      'ref', jsonb_build_object('id', v_booking, 'resource', 'appointments',
+                                'archetype', 'schedule:appointment'),
+      'starts_at', v_starts,
+      'ends_at', v_ends,
+      'client_name', v_client.name,
+      'service_name', v_service.name,
+      'price', v_service.price,
+      'status', 'scheduled'
+    )
+  );
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.agent_agenda_create_appointment(uuid, uuid, jsonb) FROM public;
+REVOKE EXECUTE ON FUNCTION public.agent_agenda_create_appointment(uuid, uuid, jsonb) FROM anon;
+GRANT EXECUTE ON FUNCTION public.agent_agenda_create_appointment(uuid, uuid, jsonb)
+  TO authenticated, service_role;

package/src/migrations/006_agent_rpc_localtime.sql

@@ -0,0 +1,181 @@
+-- ============================================================================
+-- plugin-agenda 006: agent_agenda_create_appointment speaks LOCAL time.
+--
+-- Models reliably mangle UTC↔local offsets ("10h" became 13:00 BRT via a
+-- wrong sign). The RPC knows the tenant's timezone — so stop asking the model
+-- to convert: `starts_at` WITHOUT an offset (2026-07-27T10:00) is interpreted
+-- in the tenant tz; an explicit offset still works. The result now carries
+-- starts_at_local/ends_at_local strings so the reply echoes the truth in the
+-- user's own clock. Supersedes 005's function body (new file — applied
+-- migrations are never edited).
+-- ============================================================================
+
+CREATE OR REPLACE FUNCTION public.agent_agenda_create_appointment(
+  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_client_id uuid;
+  v_service_id uuid;
+  v_professional uuid;
+  v_starts timestamptz;
+  v_starts_raw text;
+  v_notes text;
+  v_service record;
+  v_client record;
+  v_ends timestamptz;
+  v_tz text;
+  v_order uuid;
+  v_booking uuid;
+BEGIN
+  SELECT COALESCE(t.settings->>'timezone', 'America/Sao_Paulo') INTO v_tz
+  FROM tenants t WHERE t.id = p_tenant_id;
+  IF v_tz IS NULL THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'unknown tenant');
+  END IF;
+
+  -- ── payload ──────────────────────────────────────────────────────────────
+  BEGIN
+    v_client_id    := (p_payload->>'client_id')::uuid;
+    v_service_id   := (p_payload->>'service_id')::uuid;
+    v_professional := (p_payload->>'professional_id')::uuid;
+    v_starts_raw   := p_payload->>'starts_at';
+    IF v_starts_raw ~ '(Z|[+-][0-9]{2}:?[0-9]{2})$' THEN
+      v_starts := v_starts_raw::timestamptz;              -- explicit offset
+    ELSE
+      v_starts := (v_starts_raw::timestamp) AT TIME ZONE v_tz;  -- tenant-local
+    END IF;
+  EXCEPTION WHEN OTHERS THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'invalid payload: ' || SQLERRM);
+  END;
+  v_notes := left(p_payload->>'notes', 500);
+  IF v_client_id IS NULL OR v_service_id IS NULL OR v_starts IS NULL THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'client_id, service_id and starts_at are required');
+  END IF;
+  IF v_starts <= now() OR v_starts > now() + interval '365 days' THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'starts_at must be in the future (max 1 year)');
+  END IF;
+
+  -- ── authorization: role → plan → bookings_month cap ──────────────────────
+  SELECT count(*) INTO v_used FROM appointments b
+  WHERE b.tenant_id = p_tenant_id
+    AND b.created_at >= date_trunc('month', now());
+  v_denial := agent_guard(p_tenant_id, p_actor_user_id,
+                          'appointments', 'create', 'bookings_month', v_used, 1);
+  IF v_denial IS NOT NULL THEN
+    RETURN jsonb_build_object('ok', false, 'denial', v_denial);
+  END IF;
+
+  -- ── invariants ───────────────────────────────────────────────────────────
+  SELECT p.id, p.name INTO v_client
+  FROM people p
+  WHERE p.id = v_client_id AND p.tenant_id = p_tenant_id;
+  IF NOT FOUND THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'unknown client for this tenant');
+  END IF;
+
+  SELECT s.id, s.name, s.price, COALESCE(s.duration_minutes, 30) AS duration_minutes
+    INTO v_service
+  FROM services s
+  WHERE s.id = v_service_id AND s.tenant_id = p_tenant_id
+    AND s.is_active AND s.status = 'active';
+  IF NOT FOUND THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'unknown or inactive service');
+  END IF;
+
+  v_ends := v_starts + make_interval(mins => v_service.duration_minutes);
+
+  SELECT sc.assignee_id INTO v_professional
+  FROM schedules sc
+  WHERE sc.tenant_id = p_tenant_id
+    AND sc.kind = 'working_hours'
+    AND sc.is_active
+    AND (v_professional IS NULL OR sc.assignee_id = v_professional)
+    AND (
+      sc.specific_date = (v_starts AT TIME ZONE v_tz)::date
+      OR (sc.specific_date IS NULL
+          AND sc.day_of_week = EXTRACT(dow FROM v_starts AT TIME ZONE v_tz)::smallint)
+    )
+    AND (v_starts AT TIME ZONE v_tz)::time >= sc.starts_at
+    AND (v_ends AT TIME ZONE v_tz)::time <= sc.ends_at
+    -- prefer a professional who is actually FREE at the slot (when the user
+    -- did not name one, the first busy professional must not block the booking)
+    AND NOT EXISTS (
+      SELECT 1 FROM appointments b
+      WHERE b.tenant_id = p_tenant_id
+        AND b.assignee_id = sc.assignee_id
+        AND b.status NOT IN ('cancelled', 'no_show')
+        AND b.starts_at < v_ends
+        AND COALESCE(b.ends_at, b.starts_at) > v_starts
+    )
+  ORDER BY sc.assignee_id
+  LIMIT 1;
+  IF v_professional IS NULL THEN
+    RETURN jsonb_build_object('ok', false, 'error',
+      'no professional is available at that slot (outside working hours or already booked). Suggest a different time. Times are tenant-local, tz ' || v_tz);
+  END IF;
+
+  PERFORM pg_advisory_xact_lock(hashtextextended(p_tenant_id::text || v_professional::text, 0));
+  IF EXISTS (
+    SELECT 1 FROM appointments b
+    WHERE b.tenant_id = p_tenant_id
+      AND b.assignee_id = v_professional
+      AND b.status NOT IN ('cancelled', 'no_show')
+      AND b.starts_at < v_ends
+      AND COALESCE(b.ends_at, b.starts_at) > v_starts
+  ) THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'slot no longer available');
+  END IF;
+
+  -- ── write + audit ────────────────────────────────────────────────────────
+  INSERT INTO orders (tenant_id, kind, status, party_id, assignee_id, subtotal, total, notes, metadata)
+  VALUES (p_tenant_id, 'appointment', 'scheduled', v_client_id, v_professional,
+          v_service.price, v_service.price, v_notes,
+          jsonb_build_object('source', 'agent', 'serviceNames', v_service.name))
+  RETURNING id INTO v_order;
+
+  INSERT INTO appointments (tenant_id, kind, party_id, assignee_id, order_id,
+                            starts_at, ends_at, status, notes, metadata)
+  VALUES (p_tenant_id, 'appointment', v_client_id, v_professional, v_order,
+          v_starts, v_ends, 'scheduled', v_notes,
+          jsonb_build_object('source', 'agent', 'serviceNames', v_service.name))
+  RETURNING id INTO v_booking;
+
+  INSERT INTO order_items (order_id, service_id, name, quantity, unit_price, total,
+                           sort_order, duration_minutes, assignee_id)
+  VALUES (v_order, v_service.id, v_service.name, 1, v_service.price, v_service.price,
+          0, v_service.duration_minutes, v_professional);
+
+  INSERT INTO audit_logs (tenant_id, user_id, action, entity_type, entity_id, metadata)
+  VALUES (p_tenant_id, p_actor_user_id, 'agent.createAppointment', 'appointment', v_booking::text,
+          jsonb_build_object('payload', p_payload, 'order_id', v_order));
+
+  RETURN jsonb_build_object(
+    'ok', true,
+    'id', v_booking,
+    'record', jsonb_build_object(
+      'ref', jsonb_build_object('id', v_booking, 'resource', 'appointments',
+                                'archetype', 'schedule:appointment'),
+      'starts_at', v_starts,
+      'ends_at', v_ends,
+      'starts_at_local', to_char(v_starts AT TIME ZONE v_tz, 'YYYY-MM-DD (Dy) HH24:MI') || ' ' || v_tz,
+      'ends_at_local', to_char(v_ends AT TIME ZONE v_tz, 'HH24:MI'),
+      'client_name', v_client.name,
+      'service_name', v_service.name,
+      'price', v_service.price,
+      'status', 'scheduled'
+    )
+  );
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.agent_agenda_create_appointment(uuid, uuid, jsonb) FROM public;
+REVOKE EXECUTE ON FUNCTION public.agent_agenda_create_appointment(uuid, uuid, jsonb) FROM anon;
+GRANT EXECUTE ON FUNCTION public.agent_agenda_create_appointment(uuid, uuid, jsonb)
+  TO authenticated, service_role;