@fayz-ai/plugin-agenda 0.1.3 → 0.1.6

package/src/integrations/google-calendar/integration.test.ts

@@ -0,0 +1,74 @@
+// Integration contract + capability test for the Google Calendar connector.
+//
+// TDD anchor: the connector contract, manifest integrity, and the pure
+// booking↔event mapping are all proven HERE — before/without the deployed edge
+// function. The data-plane behaviors that need a live Google account are written
+// as it.todo specs so the intended contract is documented and pending, not
+// silently missing. See PLUGIN_PATTERNS.md → integration capability.
+import { describe, it, expect } from 'vitest'
+import { assertConnectorContract } from '@fayz-ai/core/testing'
+import { googleCalendarConnector } from './connector'
+import { bookingToEvent, eventToBookingPatch, bookingSummary } from './mapping'
+import type { CalendarBooking } from '../../types'
+
+function booking(overrides: Partial<CalendarBooking> = {}): CalendarBooking {
+  return {
+    id: 'b1', tenantId: 't1', kind: 'appointment',
+    startsAt: '2026-06-18T13:00:00-03:00', endsAt: '2026-06-18T14:00:00-03:00',
+    status: 'scheduled', notes: null, orderId: 'b1', locationId: null, metadata: {},
+    clientId: null, clientName: 'Sarah', clientPhone: null, clientEmail: 'sarah@x.com', clientAvatarUrl: null,
+    professionalId: null, professionalName: 'Ana', professionalAvatarUrl: null,
+    locationName: 'HQ', orderTotal: null, orderStatus: null,
+    services: [{ id: 's1', serviceId: 'svc1', name: 'Haircut', durationMinutes: 60, price: 100, assigneeId: null }] as any,
+    totalDurationMinutes: 60, createdAt: '', updatedAt: '',
+    ...overrides,
+  }
+}
+
+describe('google-calendar · connector contract (integrity)', () => {
+  it('declares a valid connector descriptor', () => {
+    expect(() => assertConnectorContract(googleCalendarConnector)).not.toThrow()
+    expect(googleCalendarConnector.capabilities[0].direction).toBe('bidirectional')
+  })
+})
+
+describe('google-calendar · booking↔event mapping (pure, TDD)', () => {
+  it('builds an event title from services + client', () => {
+    expect(bookingSummary(booking())).toBe('Haircut — Sarah')
+  })
+
+  it('maps a booking to a Google event input with start/end', () => {
+    const ev = bookingToEvent(booking())
+    expect(ev).not.toBeNull()
+    expect(ev!.summary).toBe('Haircut — Sarah')
+    expect(ev!.start.dateTime).toBe('2026-06-18T13:00:00-03:00')
+    expect(ev!.end.dateTime).toBe('2026-06-18T14:00:00-03:00')
+  })
+
+  it('refuses to map a booking with no end time', () => {
+    expect(bookingToEvent(booking({ endsAt: null }))).toBeNull()
+  })
+
+  it('maps an inbound reschedule to a booking patch', () => {
+    const patch = eventToBookingPatch({
+      id: 'e1', start: { dateTime: '2026-06-18T15:00:00-03:00' }, end: { dateTime: '2026-06-18T16:00:00-03:00' },
+    })
+    expect(patch.startsAt).toBe('2026-06-18T15:00:00-03:00')
+    expect(patch.endsAt).toBe('2026-06-18T16:00:00-03:00')
+  })
+
+  it('maps an inbound cancellation to a cancelled status', () => {
+    const patch = eventToBookingPatch({ id: 'e1', status: 'cancelled', start: {}, end: {} })
+    expect(patch.status).toBe('cancelled')
+  })
+})
+
+// Data-plane behaviors — require a live Google account + the deployed
+// google-calendar-sync edge function. Documented as the pending contract (TDD).
+describe('google-calendar · sync data plane (pending — needs edge function)', () => {
+  it.todo('push_event: creating a booking creates a Google event and stores its id on bookings.metadata')
+  it.todo('push_event: updating a booking patches the linked Google event')
+  it.todo('push_event: cancelling a booking deletes the Google event')
+  it.todo('pull_events: a Google reschedule updates the linked booking; a cancel cancels it')
+  it.todo('pull_events: advances and persists the incremental syncToken')
+})

package/src/integrations/google-calendar/mapping.ts

@@ -0,0 +1,43 @@
+// Booking ↔ Google Calendar event mapping (pure helpers).
+//
+// Shared shape used both by the SDK (docs/tests) and mirrored by the edge
+// function. Keeping it pure makes the field decisions reviewable in one place.
+import type { CalendarBooking } from '../../types'
+import type { GCalEvent } from './types'
+
+export interface GCalEventInput {
+  summary: string
+  description?: string
+  start: { dateTime: string; timeZone?: string }
+  end: { dateTime: string; timeZone?: string }
+}
+
+/** Build the event title from the booking's services + client. */
+export function bookingSummary(b: Pick<CalendarBooking, 'services' | 'clientName'>): string {
+  const services = (b.services ?? []).map((s) => s.name).filter(Boolean).join(', ')
+  const who = b.clientName ?? ''
+  if (services && who) return `${services} — ${who}`
+  return services || who || 'Appointment'
+}
+
+/** Map a Fayz booking to a Google Calendar event input. Returns null when the booking has no end. */
+export function bookingToEvent(b: CalendarBooking, timeZone?: string): GCalEventInput | null {
+  if (!b.startsAt || !b.endsAt) return null
+  const notes = [b.notes, b.professionalName ? `Pro: ${b.professionalName}` : '', b.locationName ?? '']
+    .filter(Boolean).join('\n')
+  return {
+    summary: bookingSummary(b),
+    description: notes || undefined,
+    start: { dateTime: b.startsAt, timeZone },
+    end: { dateTime: b.endsAt, timeZone },
+  }
+}
+
+/** Map an inbound Google event change to a partial booking update (reschedule/cancel). */
+export function eventToBookingPatch(ev: GCalEvent): { startsAt?: string; endsAt?: string; status?: 'cancelled' } {
+  if (ev.status === 'cancelled') return { status: 'cancelled' }
+  return {
+    startsAt: ev.start?.dateTime,
+    endsAt: ev.end?.dateTime,
+  }
+}

package/src/integrations/google-calendar/migrations/001_google_calendar.sql

@@ -0,0 +1,94 @@
+-- ---------------------------------------------------------------------------
+-- Google Calendar integration (bidirectional) — connection + audit + triggers
+-- ---------------------------------------------------------------------------
+-- Outbound (Fayz booking → Google event) fires from a trigger on saas_core.bookings
+-- via pg_net to the google-calendar-sync edge function (push_event). Inbound
+-- (Google → booking) runs on a pg_cron schedule (pull_events) and/or a Google
+-- watch-channel webhook. The booking↔event link is stored on
+-- saas_core.bookings.metadata.googleCalendarEventId (no schema change there).
+
+CREATE TABLE IF NOT EXISTS public.calendar_integrations (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id uuid NOT NULL REFERENCES saas_core.tenants(id) ON DELETE CASCADE,
+  provider text NOT NULL DEFAULT 'google',
+  oauth_refresh_token text,
+  oauth_access_token text,
+  token_expires_at timestamptz,
+  calendar_id text NOT NULL DEFAULT 'primary',
+  -- Incremental pull cursor + Google watch channel bookkeeping.
+  sync_token text,
+  channel_id text,
+  channel_resource_id text,
+  channel_expires_at timestamptz,
+  active boolean NOT NULL DEFAULT true,
+  last_sync_at timestamptz,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (tenant_id, provider)
+);
+ALTER TABLE public.calendar_integrations ENABLE ROW LEVEL SECURITY;
+CREATE INDEX IF NOT EXISTS idx_calendar_integrations_tenant ON public.calendar_integrations(tenant_id);
+
+CREATE TABLE IF NOT EXISTS public.calendar_sync_log (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id uuid NOT NULL REFERENCES saas_core.tenants(id) ON DELETE CASCADE,
+  direction text NOT NULL,                 -- inbound | outbound
+  trigger text,                            -- on-write | scheduled | webhook | manual
+  status text NOT NULL DEFAULT 'success',  -- success | partial | error
+  fetched integer NOT NULL DEFAULT 0,
+  written integer NOT NULL DEFAULT 0,
+  error text,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+ALTER TABLE public.calendar_sync_log ENABLE ROW LEVEL SECURITY;
+
+-- RLS: tenant isolation.
+DO $$
+DECLARE t text;
+BEGIN
+  FOR t IN SELECT unnest(ARRAY['calendar_integrations','calendar_sync_log'])
+  LOOP
+    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||'_rls') THEN
+      EXECUTE format('CREATE POLICY %I ON public.%I FOR ALL TO authenticated USING (tenant_id IN (SELECT public.user_tenant_ids())) WITH CHECK (tenant_id IN (SELECT public.user_tenant_ids()))', t||'_rls', t);
+    END IF;
+  END LOOP;
+END $$;
+
+-- ---------------------------------------------------------------------------
+-- Outbound trigger: booking change → edge function (push_event).
+-- Requires pg_net + a configured function URL. Set once per project:
+--   ALTER DATABASE postgres SET app.gcal_sync_url = 'https://<ref>.functions.supabase.co/google-calendar-sync';
+--   ALTER DATABASE postgres SET app.gcal_service_key = '<service-role-key>';
+-- Safe to skip in environments without pg_net — outbound also works via the
+-- client-side withGoogleCalendarSync() decorator.
+-- ---------------------------------------------------------------------------
+CREATE OR REPLACE FUNCTION public.fn_gcal_push_booking() RETURNS trigger
+LANGUAGE plpgsql SECURITY DEFINER AS $$
+DECLARE
+  url text := current_setting('app.gcal_sync_url', true);
+  key text := current_setting('app.gcal_service_key', true);
+  rec record := COALESCE(NEW, OLD);
+  op  text := lower(TG_OP);
+BEGIN
+  IF url IS NULL OR url = '' THEN RETURN COALESCE(NEW, OLD); END IF;
+  PERFORM net.http_post(
+    url := url,
+    headers := jsonb_build_object('Content-Type', 'application/json', 'Authorization', 'Bearer ' || COALESCE(key, '')),
+    body := jsonb_build_object('action', 'push_event', 'op', op, 'bookingId', rec.id, 'tenantId', rec.tenant_id)
+  );
+  RETURN COALESCE(NEW, OLD);
+END $$;
+
+DROP TRIGGER IF EXISTS trg_gcal_push ON saas_core.bookings;
+CREATE TRIGGER trg_gcal_push
+  AFTER INSERT OR UPDATE OR DELETE ON saas_core.bookings
+  FOR EACH ROW EXECUTE FUNCTION public.fn_gcal_push_booking();
+
+-- Inbound schedule (optional): pull external changes every 10 minutes.
+--   SELECT cron.schedule('gcal-pull', '*/10 * * * *', $$
+--     SELECT net.http_post(
+--       url := current_setting('app.gcal_sync_url'),
+--       headers := jsonb_build_object('Content-Type','application/json','Authorization','Bearer '||current_setting('app.gcal_service_key')),
+--       body := jsonb_build_object('action','pull_events'));
+--   $$);

package/src/integrations/google-calendar/types.ts

@@ -0,0 +1,31 @@
+// Google Calendar integration — shared types.
+
+export interface CalendarIntegration {
+  id: string
+  provider: string
+  calendarId: string
+  active: boolean
+  connected: boolean
+  lastSyncAt?: string
+}
+
+export interface CalendarSyncLogEntry {
+  id: string
+  direction: string
+  trigger?: string
+  status: string
+  fetched: number
+  written: number
+  error?: string
+  createdAt: string
+}
+
+/** Minimal Google Calendar event shape we read/write (subset of the API). */
+export interface GCalEvent {
+  id: string
+  summary?: string
+  description?: string
+  start: { dateTime?: string; date?: string; timeZone?: string }
+  end: { dateTime?: string; date?: string; timeZone?: string }
+  status?: string
+}