@graph8/sdk 0.308.1 → 0.357.0

package/blocks/analytics/lib/analytics-types.ts

@@ -0,0 +1,108 @@
+"use client";
+
+/**
+ * Shapes and helpers for the analytics components.
+ *
+ * Most analytics endpoints return the app's own report wrapper inside the API envelope:
+ *   { data: { success, data: <the report>, meta: { cached, stale, days, ... } } }
+ * Read the report through `reportBody()`, which also accepts the bare shape a few endpoints use (the revenue team
+ * dashboards return the report directly under `data`). `meta.stale` true means the numbers came from a cache after
+ * a failed refresh; show it, do not hide it.
+ */
+
+export interface ReportMeta {
+  cached?: boolean;
+  stale?: boolean;
+  days?: number;
+  timestamp?: string;
+}
+
+/** `GET /analytics/outbound/summary` (rates are percentages, 0 to 100). */
+export interface OutboundSummary {
+  emails_sent?: number;
+  emails_delivered?: number;
+  emails_bounced?: number;
+  emails_replied?: number;
+  delivery_rate?: number;
+  reply_rate?: number;
+  calls_dispatched?: number;
+  calls_connected?: number;
+  connect_rate?: number;
+  meetings_booked?: number;
+  meetings_active?: number;
+  meetings_cancelled?: number;
+  [key: string]: unknown;
+}
+
+/** A row of `GET /analytics/outbound/sdr-activity/leaderboard` (reps with at least 10 emails sent). */
+export interface LeaderRow {
+  sdr_email?: string;
+  emails_sent?: number;
+  replies?: number;
+  bounced?: number;
+  reply_rate?: number;
+  meetings_booked?: number;
+  [key: string]: unknown;
+}
+
+export interface FunnelStep {
+  key: string;
+  label: string;
+  count: number;
+  /** Percent of the previous step, when known. */
+  conversion?: number | null;
+}
+
+export interface ResultRow {
+  key: string;
+  group: Array<{ label?: string | null; value?: unknown } | string | number | null>;
+  measures: Record<string, unknown>;
+  record_count?: number;
+}
+
+export interface ReportResultData {
+  status?: "ok" | "restricted";
+  columns?: Array<{ id: string; kind: string; label?: string | null }>;
+  rows?: ResultRow[];
+  totals?: { record_count: number; measures?: Record<string, unknown> } | null;
+  truncated?: boolean;
+  disclosures?: string[];
+  source?: { slug: string; singular_noun: string; plural_noun: string };
+}
+
+export interface SavedReport {
+  id: string;
+  title: string;
+  chart_type: string;
+  revision: number;
+  visibility: string;
+  source: { slug: string; plural_noun: string };
+  can_delete?: boolean;
+  config: Record<string, unknown>;
+}
+
+/** The report inside the response wrapper, however many `data` layers the endpoint adds. */
+export function reportBody<T>(env: unknown): T {
+  let v: unknown = (env as { data?: unknown } | null)?.data ?? env;
+  for (let i = 0; i < 2; i++) {
+    const o = v as { success?: unknown; data?: unknown } | null;
+    if (o && typeof o === "object" && !Array.isArray(o) && "data" in o && (o.success !== undefined || "meta" in o) && o.data != null) v = o.data;
+  }
+  return v as T;
+}
+
+export function reportMeta(env: unknown): ReportMeta {
+  const outer = (env as { data?: { meta?: ReportMeta } } | null)?.data;
+  return outer?.meta ?? {};
+}
+
+export function formatNumber(n: number | null | undefined): string {
+  return n == null ? "n/a" : n.toLocaleString();
+}
+
+/** `value` is already a percentage (the outbound reports return 12.5, not 0.125). */
+export function formatPercent(value: number | null | undefined, digits = 1): string {
+  return value == null ? "n/a" : `${Number(value).toFixed(digits).replace(/\.0+$/, "")}%`;
+}
+
+export const DAY_RANGES = [7, 30, 90] as const;

package/blocks/analytics/lib/use-debounced.ts

@@ -0,0 +1,16 @@
+"use client";
+
+/**
+ * useDebounced: a value that follows `value` after it has stopped changing for `ms`. Use it for search and slug
+ * inputs so each keystroke does not fire a request.
+ */
+import { useEffect, useState } from "react";
+
+export function useDebounced<T>(value: T, ms = 300): T {
+  const [v, setV] = useState(value);
+  useEffect(() => {
+    const t = setTimeout(() => setV(value), ms);
+    return () => clearTimeout(t);
+  }, [value, ms]);
+  return v;
+}

package/blocks/analytics/recipes/01-weekly-outbound-report.ts

@@ -0,0 +1,32 @@
+/**
+ * @title Weekly outbound report: top-line numbers, rep leaderboard and meeting funnel
+ * @when A Monday summary for a manager, or an agent answering "how did outbound do?". Read-only, spends nothing.
+ * Every report answers `{ success, data, meta }` inside the API's `data`, so the numbers are at `res.data.data`.
+ * Rates are percentages (12.5, not 0.125). `meta.stale` true means a cached answer after a failed refresh.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+type Wrapped<T> = { data?: { success?: boolean; data?: T; meta?: { stale?: boolean; cached?: boolean } } };
+
+const days = 7;
+const summary = (await g8.api.analytics.getOutboundSummary({ query: { days } })) as Wrapped<{
+  emails_sent?: number;
+  reply_rate?: number;
+  calls_dispatched?: number;
+  connect_rate?: number;
+  meetings_booked?: number;
+}>;
+const s = summary.data?.data;
+console.log(`Last ${days} days: ${s?.emails_sent} emails (${s?.reply_rate}% reply), ${s?.calls_dispatched} calls (${s?.connect_rate}% connected), ${s?.meetings_booked} meetings`);
+if (summary.data?.meta?.stale) console.log("(numbers are from a cache)");
+
+// Reps are ranked by reply rate once they have sent at least 10 emails.
+const board = (await g8.api.analytics.getSdrLeaderboard({ query: { days, limit: 10 } })) as Wrapped<
+  Array<{ sdr_email?: string; reply_rate?: number; emails_sent?: number; meetings_booked?: number }>
+>;
+for (const [i, r] of (board.data?.data ?? []).entries()) console.log(`${i + 1}. ${r.sdr_email} ${r.reply_rate}% of ${r.emails_sent} emails, ${r.meetings_booked} meetings`);
+
+const funnel = (await g8.api.analytics.getMeetingFunnel({ query: { days } })) as Wrapped<{ summary?: Record<string, number> }>;
+console.log("meeting funnel", JSON.stringify(funnel.data?.data?.summary));

package/blocks/analytics/recipes/02-revenue-snapshot.ts

@@ -0,0 +1,22 @@
+/**
+ * @title Revenue snapshot: team dashboard, conversion funnel and forecast
+ * @when A board-pack style summary of pipeline health. Read-only. These three reports return the report object
+ * directly under `data` (no `{ success, data, meta }` wrapper), unlike the outbound reports. The forecast is the
+ * open pipeline weighted by stage probabilities; stages with no probability set contribute nothing, so check
+ * the deals block's StageEditor first if the number looks low.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const dashboard = await g8.api.revenueAnalytics.getTeamRevenueDashboard({ query: { period_days: 30 } });
+console.log("dashboard", JSON.stringify(dashboard.data));
+
+const funnel = (await g8.api.revenueAnalytics.getTeamConversionFunnel({ query: { period_days: 90 } })) as {
+  data?: { funnel_stages?: Array<{ stage_label: string; count: number; conversion_rate?: number | null }>; overall_conversion_rate?: number };
+};
+for (const stage of funnel.data?.funnel_stages ?? []) console.log(stage.stage_label, stage.count, stage.conversion_rate != null ? `${stage.conversion_rate}% of previous` : "");
+console.log("overall", funnel.data?.overall_conversion_rate, "%");
+
+const forecast = await g8.api.revenueAnalytics.getTeamRevenueForecast();
+console.log("forecast", JSON.stringify(forecast.data));

package/blocks/analytics/recipes/03-saved-report.ts

@@ -0,0 +1,30 @@
+/**
+ * @title Define, preview, save and run a custom-object report
+ * @when Reporting on a custom object (the objects block): "records by status", "sum of amount by month". The reports
+ * feature is switched on per organisation (404 while off). Preview and execute count against shared report-run
+ * slots (429 `too_many_report_runs`: wait and retry). Deleting a saved report is destructive, so ask first.
+ */
+import { g8 } from "@graph8/sdk";
+import type { ApiInput } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const objectSlug = process.argv[2];
+if (!objectSlug) throw new Error("usage: tsx 03-saved-report.ts <object slug>");
+
+type Preview = ApiInput<"preview_object_report_api_reports_preview_post">["body"];
+const definition: Preview = {
+  object_slug: objectSlug,
+  chart_type: "table",
+  // Count the records, grouped by the month they were created in.
+  config: { measures: [{ kind: "count" }], group_by: [{ kind: "created_at", grain: "month" }], filters: [] },
+};
+
+// 1. Run it unsaved first.
+const preview = await g8.api.reports.previewObjectReportApi({ body: definition });
+for (const row of preview.data.rows ?? []) console.log(JSON.stringify(row.group), JSON.stringify(row.measures), row.record_count);
+
+// 2. Save it (private by default), then run the saved definition by id.
+const created = await g8.api.reports.createObjectReportApi({ body: { ...definition, title: "Records by month", visibility: "private" } });
+const run = await g8.api.reports.executeObjectReportApi({ path: { report_id: created.data.id }, body: {} });
+console.log(JSON.stringify(run.data).slice(0, 400));

package/blocks/appointments/README.md

@@ -0,0 +1,80 @@
+# appointments: scheduling and meetings
+
+Event types, weekly working hours, a booking page, a list of booked and recorded meetings, and the actions a
+rep takes on a booking (confirm, cancel, add a note). Install with `npx @graph8/sdk add appointments`
+(depends on `crm`).
+
+## The flow, in order
+
+1. **Hours** (`AvailabilityEditor`): `GET /appointments/schedules` -> pick `schedule.id` ->
+   `GET /appointments/schedules/{id}/availability` -> `PATCH` the same path with the full rule set.
+   Days are ISO weekdays (1 = Monday ... 7 = Sunday), times are `"HH:MM"`. The PATCH **replaces** the rules.
+2. **Event type** (`EventTypeEditor`): `POST /appointments/event-types` with `{ title, slug, length,
+   schedule_id }` returns the event type; **save its `id`**. There is no list-event-types operation.
+3. **Slots** (`BookingPage`): `GET /appointments/slots?event_type_id=&start=&end=&time_zone=` returns
+   `{ slots: { "YYYY-MM-DD": [{ time, duration }] } }` (window at most 60 days, never in the past).
+4. **Book** (`BookingPage`, **external**, confirm first): `POST /appointments/bookings` with
+   `{ event_type_id, start_time (the slot's time), end_time, attendees: [{ name, email, time_zone }] }`.
+   It creates the calendar event and emails the attendee. An `Idempotency-Key` makes a double click safe.
+5. **Manage** (`MeetingList` -> `MeetingDetail`): `GET /appointments/bookings` (paged with `skip`/`take`)
+   -> `GET /appointments/bookings/{uid}` -> `confirm` (accept or decline a pending booking, external),
+   `cancel` (destructive) or `notes` (external). Recorded meetings (`GET /inbox/meetings`, then
+   `/inbox/meetings/{id}`) carry transcripts and AI summaries and are a different record from a booking.
+
+IDs passed between steps: `schedule.id` (hours -> event type), `eventType.id` (event type -> slots ->
+booking), `booking.uid` (list -> detail -> confirm/cancel/notes), recorded `meeting.id`.
+
+## Prerequisites a human must do
+
+- **Connect the host's calendar in the graph8 app** (`where: "app"`). Calendar OAuth (Google/Microsoft) is
+  not in the API. `AvailabilityEditor` shows connection state and links out via `connectCalendarUrl`.
+- Use an API key minted by the host. Appointments act as a person; an organisation key can read and
+  list slots, but anything personal (profile, slot reservation) requires a personal key.
+- Scopes: `meetings:read`, `meetings:write`, `meetings:run`, `meetings:delete` (cancel a booking, delete an event type).
+
+## Defaults (the agent does not need to ask)
+
+- New event type: 30 minutes, 120 minutes minimum notice, no host confirmation.
+- New schedule: Monday to Friday 09:00 to 17:00 in the host's zone.
+- BookingPage offers 14 days ahead.
+- Ask the human about two things only: **whether the booking page is public**, and **where event type ids
+  are stored**.
+
+## Public booking pages: read this
+
+The contract deliberately has **no unauthenticated booking operations** (a prospect's browser cannot call the
+API directly). `BookingPage` therefore books on behalf of a prospect through your `/api/g8` proxy with the
+org key. Use it inside your app (a rep scheduling), or for a public page add your own protections: the
+proxy `authorize` hook, an `allowedPrefixes` of exactly `/appointments/slots`, `/appointments/event-types`
+and `/appointments/bookings`, rate limits and bot protection. Never mount the proxy open to the internet
+with the full API key.
+
+## Operations
+
+| Operation | Method and path | Tier | Used by |
+|---|---|---|---|
+| `appointments.listSchedules` | GET /appointments/schedules | read | EventTypeEditor, AvailabilityEditor |
+| `appointments.getEventType` | GET /appointments/event-types/{id} | read | EventTypeEditor, BookingPage |
+| `appointments.createEventType` | POST /appointments/event-types | write | EventTypeEditor |
+| `appointments.updateEventType` | PATCH /appointments/event-types/{id} | write | EventTypeEditor |
+| `appointments.deleteEventType` | DELETE /appointments/event-types/{id} | destructive | EventTypeEditor |
+| `appointments.getAvailability` | GET /appointments/schedules/{id}/availability | read | AvailabilityEditor |
+| `appointments.updateAvailability` | PATCH /appointments/schedules/{id}/availability | write | AvailabilityEditor |
+| `appointments.listCalendars` | GET /appointments/calendars | read | AvailabilityEditor |
+| `appointments.getAvailableSlots` | GET /appointments/slots | read | BookingPage |
+| `appointments.createBooking` | POST /appointments/bookings | external | BookingPage |
+| `appointments.listBookings` | GET /appointments/bookings | read | MeetingList |
+| `appointments.getBooking` | GET /appointments/bookings/{uid} | read | MeetingDetail |
+| `appointments.confirmBooking` | POST /appointments/bookings/{uid}/confirm | external | MeetingDetail |
+| `appointments.cancelBooking` | POST /appointments/bookings/{uid}/cancel | destructive | MeetingDetail |
+| `appointments.addBookingNote` | POST /appointments/bookings/{uid}/notes | external | MeetingDetail |
+| `meetings.listMeetings` | GET /inbox/meetings | read | MeetingList |
+| `meetings.getMeeting` | GET /inbox/meetings/{id} | read | MeetingDetail |
+
+## Recipes (server side)
+
+- `01-create-event-type-and-hours.ts`: schedule + event type.
+- `02-find-slots-and-book.ts`: slots, then an external booking.
+- `03-bookings-digest.ts`: upcoming bookings, pending approvals, recorded meetings.
+- `04-calendar-invite.ts`: ad-hoc invite via `calendarInvites.createCalendarInvite` (not part of the block's
+  UI; add the operation to your own proxy allowlist if you call it from the browser).

package/blocks/appointments/block.json

@@ -0,0 +1,218 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "appointments",
+  "title": "Appointments & meetings",
+  "summary": "Scheduling: event types, working hours, a booking page, and lists and details of booked and recorded meetings.",
+  "features": [
+    "create and edit bookable event types",
+    "weekly working hours with multiple windows and date overrides",
+    "booking page: day, time, attendee, confirmed invite",
+    "bookings list (upcoming, past, cancelled) and recorded meetings with summaries",
+    "confirm, cancel and annotate a booking"
+  ],
+  "dependsOn": [
+    "crm"
+  ],
+  "operations": [
+    "add_booking_note_appointments_bookings__booking_uid__notes_post",
+    "cancel_booking_appointments_bookings__booking_uid__cancel_post",
+    "confirm_booking_appointments_bookings__booking_uid__confirm_post",
+    "create_booking_appointments_bookings_post",
+    "create_event_type_appointments_event_types_post",
+    "delete_event_type_appointments_event_types__event_type_id__delete",
+    "get_availability_appointments_schedules__schedule_id__availability_get",
+    "get_available_slots_appointments_slots_get",
+    "get_booking_appointments_bookings__booking_uid__get",
+    "get_event_type_appointments_event_types__event_type_id__get",
+    "get_meeting_inbox_meetings__meeting_id__get",
+    "list_bookings_appointments_bookings_get",
+    "list_calendars_appointments_calendars_get",
+    "list_meetings_inbox_meetings_get",
+    "list_schedules_appointments_schedules_get",
+    "update_availability_appointments_schedules__schedule_id__availability_patch",
+    "update_event_type_appointments_event_types__event_type_id__patch"
+  ],
+  "components": [
+    {
+      "name": "EventTypeEditor",
+      "file": "components/event-type-editor.tsx",
+      "purpose": "Create or edit a meeting type (title, length, schedule, notice, confirmation); delete behind a confirm dialog.",
+      "operations": [
+        "create_event_type_appointments_event_types_post",
+        "delete_event_type_appointments_event_types__event_type_id__delete",
+        "get_event_type_appointments_event_types__event_type_id__get",
+        "list_schedules_appointments_schedules_get",
+        "update_event_type_appointments_event_types__event_type_id__patch"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "AvailabilityEditor",
+      "file": "components/availability-editor.tsx",
+      "purpose": "Weekly working hours and date overrides for a schedule, plus connected calendars with a link out to connect them.",
+      "operations": [
+        "get_availability_appointments_schedules__schedule_id__availability_get",
+        "list_calendars_appointments_calendars_get",
+        "list_schedules_appointments_schedules_get",
+        "update_availability_appointments_schedules__schedule_id__availability_patch"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "BookingPage",
+      "file": "components/booking-page.tsx",
+      "purpose": "Pick a day and time from live slots, enter the attendee, and book (external, confirmed).",
+      "operations": [
+        "create_booking_appointments_bookings_post",
+        "get_available_slots_appointments_slots_get",
+        "get_event_type_appointments_event_types__event_type_id__get"
+      ],
+      "tiers": [
+        "read",
+        "external"
+      ]
+    },
+    {
+      "name": "MeetingList",
+      "file": "components/meeting-list.tsx",
+      "purpose": "Upcoming, past and cancelled bookings plus recorded meetings, with paging and search.",
+      "operations": [
+        "list_bookings_appointments_bookings_get",
+        "list_meetings_inbox_meetings_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "MeetingDetail",
+      "file": "components/meeting-detail.tsx",
+      "purpose": "One booking (confirm, cancel, notes) or one recorded meeting (summary, topics, action items, transcript).",
+      "operations": [
+        "add_booking_note_appointments_bookings__booking_uid__notes_post",
+        "cancel_booking_appointments_bookings__booking_uid__cancel_post",
+        "confirm_booking_appointments_bookings__booking_uid__confirm_post",
+        "get_booking_appointments_bookings__booking_uid__get",
+        "get_meeting_inbox_meetings__meeting_id__get"
+      ],
+      "tiers": [
+        "read",
+        "external",
+        "destructive"
+      ]
+    }
+  ],
+  "hooks": [
+    {
+      "name": "useSchedules",
+      "file": "hooks/use-schedules.ts",
+      "purpose": "The org's availability schedules, default first.",
+      "operations": [
+        "list_schedules_appointments_schedules_get"
+      ]
+    },
+    {
+      "name": "useAvailableSlots",
+      "file": "hooks/use-available-slots.ts",
+      "purpose": "Bookable times for an event type grouped by local date.",
+      "operations": [
+        "get_available_slots_appointments_slots_get"
+      ]
+    }
+  ],
+  "lib": [
+    {
+      "file": "lib/appointments-types.ts",
+      "purpose": "Event type, schedule, booking and slot types plus unwrap/listOf helpers for the engine's mixed response shapes."
+    },
+    {
+      "file": "lib/idempotency.ts",
+      "purpose": "useIdempotencyKey: one Idempotency-Key per distinct payload, rotated when the body changes so an edited retry never hits a 409."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/01-create-event-type-and-hours.ts",
+      "title": "Create working hours and a bookable event type",
+      "when": "Setting up scheduling for an org or rep; both writes are low risk."
+    },
+    {
+      "file": "recipes/02-find-slots-and-book.ts",
+      "title": "Find open times and book a meeting",
+      "when": "An agent scheduling for a rep; booking emails the attendee so a human approves first."
+    },
+    {
+      "file": "recipes/03-bookings-digest.ts",
+      "title": "Upcoming bookings and pending approvals",
+      "when": "A read-only daily digest, including recorded meetings."
+    },
+    {
+      "file": "recipes/04-calendar-invite.ts",
+      "title": "Create an ad-hoc calendar invite",
+      "when": "A shareable invite without an event type or booking."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "calendar-connected",
+      "description": "A Google or Microsoft calendar connected for the host. Calendar OAuth exists only in the graph8 app, so a human must connect it; without it busy time is not checked and bookings do not create calendar events.",
+      "where": "app",
+      "verify": "GET /appointments/calendars returns a calendar with is_valid true (AvailabilityEditor shows it as connected)."
+    },
+    {
+      "id": "personal-key",
+      "description": "Event types, schedules, slots and bookings act as a person. Use an API key minted by the host (an org key works for most reads and for slots; profile and slot reservation need a personal key).",
+      "where": "api",
+      "verify": "`g8.api.appointments.listSchedules()` returns the host's schedules, not a 404 User not found."
+    },
+    {
+      "id": "meetings-scopes",
+      "description": "Key scopes meetings:read, meetings:write, meetings:run (booking, confirm, notes are tier external) and meetings:delete (cancel, delete event type).",
+      "where": "api",
+      "verify": "`g8.api.me.describeCurrentKey()` lists the meetings:* scopes."
+    }
+  ],
+  "scopes": [
+    "meetings:delete",
+    "meetings:read",
+    "meetings:run",
+    "meetings:write"
+  ],
+  "defaults": [
+    {
+      "decision": "Meeting length and notice for a new event type",
+      "default": "30 minutes, 120 minutes minimum notice, no host confirmation",
+      "askHuman": false
+    },
+    {
+      "decision": "Working hours for a new schedule",
+      "default": "Monday to Friday 09:00 to 17:00 in the host's time zone",
+      "askHuman": false
+    },
+    {
+      "decision": "How far ahead the BookingPage offers times",
+      "default": "14 days (the API allows at most 60)",
+      "askHuman": false
+    },
+    {
+      "decision": "Whether the BookingPage is public to prospects or only used by reps inside the app",
+      "default": "Inside the app. A public page needs your own auth and bot protection on the proxy because the API has no public booking operations",
+      "askHuman": true
+    },
+    {
+      "decision": "Where event type ids are stored (there is no list-event-types operation)",
+      "default": "Your own database, saved from the create response",
+      "askHuman": true
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  }
+}