diff --git a/apps/events/CHANGELOG.md b/apps/events/CHANGELOG.md index 3d20297..3d86156 100644 --- a/apps/events/CHANGELOG.md +++ b/apps/events/CHANGELOG.md @@ -7,6 +7,24 @@ and this project follows [Semantic Versioning](https://semver.org/). ## [Unreleased] +### Added + +- **AI helpers — the plumbing** (2.0, roadmap §15). The site calls AI through the Cross Events Hub + (protocol §3b, Hub 1.6.0), which holds the Claude API key and a monthly allowance in rand per + licence; no key is ever stored on the site. `GET /api/v2/ai/status` says whether to show the AI + buttons: hidden when the licence has no AI (worked out from the licence token, without asking the + Hub), disabled with the reason once the month's allowance is used up or the Hub can't be reached. + The answer is cached for a minute and refreshed by every AI call. `` and + `useAiStatus()` on the frontend; only supervisors and admins see AI. +- **Site settings → AI** (admins): this month's use against the allowance, use per person, per + helper and per day, a switch per helper, and an optional most-uses-per-person-per-day. Admins are + emailed once a month when 80% is used. Changes are audited (`ai_settings_changed`). +- Each AI call is logged in `AiCall` (person, helper, outcome, cost — never the prompt or answer); + anonymising an account unlinks its calls, and calls go after 13 months. Anthropic is added to the + operator register, switched off until a site uses AI. Migration `20261030120000_ai_helpers`. +- v2 errors have a new code, `UNAVAILABLE` (503), for when the Hub or the AI service can't be + reached. + ## [1.51.17] - 2026-10-30 — security release ### Security diff --git a/apps/events/backend/prisma/migrations/20261030120000_ai_helpers/migration.sql b/apps/events/backend/prisma/migrations/20261030120000_ai_helpers/migration.sql new file mode 100644 index 0000000..9376809 --- /dev/null +++ b/apps/events/backend/prisma/migrations/20261030120000_ai_helpers/migration.sql @@ -0,0 +1,28 @@ +-- AlterEnum +ALTER TYPE "AdminAuditAction" ADD VALUE 'ai_settings_changed'; + +-- CreateTable +CREATE TABLE "AiCall" ( + "id" TEXT NOT NULL, + "userId" TEXT, + "helper" TEXT NOT NULL, + "outcome" TEXT NOT NULL, + "chargedCents" DOUBLE PRECISION NOT NULL DEFAULT 0, + "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP, + + CONSTRAINT "AiCall_pkey" PRIMARY KEY ("id") +); + +-- CreateIndex +CREATE INDEX "AiCall_createdAt_idx" ON "AiCall"("createdAt"); + +-- CreateIndex +CREATE INDEX "AiCall_userId_createdAt_idx" ON "AiCall"("userId", "createdAt"); + +-- AddForeignKey +ALTER TABLE "AiCall" ADD CONSTRAINT "AiCall_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User"("id") ON DELETE SET NULL ON UPDATE CASCADE; + + +-- 2.0 AI helpers: Anthropic in the operator register, off until the site uses AI. +INSERT INTO "Operator" ("id", "name", "purpose", "dataShared", "location", "website", "active", "order", "updatedAt") VALUES + (gen_random_uuid()::text, 'Anthropic (Claude), through the software provider''s Hub', 'AI helpers for staff: drafting events and messages, improving text, summarising reports and feedback', 'The text a staff member asks to draft or improve, report figures, and feedback comments with names and contact details removed. Not kept by the software provider; Anthropic''s commercial terms apply', 'United States', 'https://www.anthropic.com/legal/privacy', false, 9, CURRENT_TIMESTAMP); diff --git a/apps/events/backend/prisma/schema.prisma b/apps/events/backend/prisma/schema.prisma index 50fb040..a74abac 100644 --- a/apps/events/backend/prisma/schema.prisma +++ b/apps/events/backend/prisma/schema.prisma @@ -165,6 +165,7 @@ model User { seriesFollows SeriesFollow[] seasonPassPurchases SeasonPassPurchase[] savedFilters SavedFilter[] + aiCalls AiCall[] swapsAsked VolunteerSwap[] @relation("VolunteerSwapFrom") swapsTaken VolunteerSwap[] @relation("VolunteerSwapTo") @@ -820,6 +821,7 @@ enum AdminAuditAction { season_pass_changed webhook_endpoint_changed registrations_bulk + ai_settings_changed } // Append-only audit trail for admin/supervisor-initiated actions with money or @@ -2315,3 +2317,21 @@ model SavedFilter { @@unique([userId, page, name]) @@index([userId, page]) } + +/// One AI helper call (2.0). The Hub meters the money; this copy is for Site settings → AI (use +/// per person, per helper and per day) and per-person daily limits. No prompt or answer text is +/// kept. `userId` is cleared when the account is anonymised; rows go after 13 months. +model AiCall { + id String @id @default(uuid()) + userId String? + helper String + // ok, refused, incomplete, failed, cap_reached, unavailable + outcome String + // What the church was charged, in cents (fractions of a cent). + chargedCents Float @default(0) + createdAt DateTime @default(now()) + user User? @relation(fields: [userId], references: [id], onDelete: SetNull) + + @@index([createdAt]) + @@index([userId, createdAt]) +} diff --git a/apps/events/backend/src/ai/index.ts b/apps/events/backend/src/ai/index.ts new file mode 100644 index 0000000..ecfec21 --- /dev/null +++ b/apps/events/backend/src/ai/index.ts @@ -0,0 +1,263 @@ +/** + * AI helpers (2.0, roadmap §15). The site never holds a Claude API key: every call goes through + * the Cross Events Hub (docs/hub-protocol.md §3b), which checks the licence's monthly cap in rand, + * calls Claude and meters the call. This module: + * - works out what the AI buttons do (`aiStatus`): hidden, working, or disabled until the + * allowance renews — from the licence token first, then the Hub (cached for a minute); + * - runs one helper call (`runHelper`), with this site's own switches per helper and an optional + * daily limit per person, and logs it in `AiCall` (no prompt or answer text); + * - emails the site admins once a month when 80% of the allowance is used. + * The helpers themselves (prompts, schemas, what they send) are in ./helpers.ts. + */ + +import { ApiError } from '../v2/errors'; +import { prisma } from '../v2/legacy'; + +/* eslint-disable @typescript-eslint/no-explicit-any -- the JS Hub client and helpers aren't typed */ +const hub = require('../hub/client') as { + PROTOCOL_VERSION: number; + signedPost(path: string, body: object, opts?: { timeoutMs?: number }): Promise; + HubError: new (...args: any[]) => Error & { code: string; statusCode: number; data: any }; +}; +const { licenceStatus } = require('../hub/licence') as { + licenceStatus(): Promise<{ connected: boolean; claims: { limits?: { aiMonthlyCapCents?: number } } | null; state: string; readOnly: boolean }>; +}; +const email = require('../utils/email') as { + sendMail(m: { to: string; subject: string; html: string; text: string }): Promise; + emailWrapper(body: string): string; + isSmtpConfigured(): boolean; +}; +const { logAdminAction } = require('../utils/adminAudit') as { logAdminAction(entry: object): Promise }; + +export const HELPERS = ['draft_event', 'summarise_report', 'draft_message', 'summarise_feedback', 'improve_text'] as const; +export type HelperName = (typeof HELPERS)[number]; + +/** What the Hub says (§3b). Cents are charged rand, with fractions. */ +export type HubAiStatus = { enabled: boolean; capReached: boolean; capCents: number; usedCents: number; usedPercent: number; renewsOn: string | null }; +/** What the buttons need: the Hub's answer, whether it could be reached, and this site's switches. */ +export type AiStatus = HubAiStatus & { available: boolean; helpers: Record }; + +export type AiSettings = { helpers: Record; dailyLimitPerPerson: number }; +const SETTINGS_KEY = 'ai_settings'; +const WARNED_KEY = 'ai_warned_month'; +const STATUS_TTL_MS = 60 * 1000; +const CALL_TIMEOUT_MS = 90 * 1000; +const KEEP_CALLS_DAYS = 400; + +const OFF: HubAiStatus = { enabled: false, capReached: false, capCents: 0, usedCents: 0, usedPercent: 0, renewsOn: null }; + +// ─── This site's settings ───────────────────────────────────────────────────── + +export const DEFAULT_SETTINGS: AiSettings = { helpers: Object.fromEntries(HELPERS.map(h => [h, true])) as Record, dailyLimitPerPerson: 0 }; + +export async function getAiSettings(): Promise { + const row = await prisma.appSetting.findUnique({ where: { key: SETTINGS_KEY } }); + let saved: Partial = {}; + try { saved = row ? JSON.parse(row.value) : {}; } catch { /* keep the defaults */ } + return { + helpers: { ...DEFAULT_SETTINGS.helpers, ...Object.fromEntries(HELPERS.filter(h => typeof saved.helpers?.[h] === 'boolean').map(h => [h, saved.helpers![h]])) }, + dailyLimitPerPerson: Number.isInteger(saved.dailyLimitPerPerson) && saved.dailyLimitPerPerson! >= 0 ? saved.dailyLimitPerPerson! : 0, + }; +} + +export async function saveAiSettings(next: { helpers?: Partial>; dailyLimitPerPerson?: number }, actor: { id: string; role: string }, ip?: string): Promise { + const current = await getAiSettings(); + const changed = Object.fromEntries(HELPERS.filter(h => typeof next.helpers?.[h] === 'boolean').map(h => [h, next.helpers![h]])); + const value: AiSettings = { + helpers: { ...current.helpers, ...changed }, + dailyLimitPerPerson: next.dailyLimitPerPerson ?? current.dailyLimitPerPerson, + }; + await prisma.appSetting.upsert({ where: { key: SETTINGS_KEY }, update: { value: JSON.stringify(value) }, create: { key: SETTINGS_KEY, value: JSON.stringify(value) } }); + await logAdminAction({ actorId: actor.id, actorRole: actor.role, action: 'ai_settings_changed', targetType: 'setting', targetId: SETTINGS_KEY, metadata: value, ip }); + return value; +} + +// ─── Status ─────────────────────────────────────────────────────────────────── + +let cached: { at: number; value: HubAiStatus; available: boolean } | null = null; + +/** Keep what the Hub just said (every AI reply and error carries it). */ +function remember(value: unknown, available = true): void { + const v = value as Partial | null; + if (v && typeof v.enabled === 'boolean') cached = { at: Date.now(), value: { ...OFF, ...v } as HubAiStatus, available }; +} + +export function clearAiStatusCache(): void { + cached = null; +} + +/** + * The cap from the licence token (refreshed by every heartbeat): no Hub call is needed to know AI + * is off, which is most sites. + */ +async function licenceCap(): Promise { + const l = await licenceStatus(); + if (!l.connected || !l.claims || l.readOnly) return 0; + return Number(l.claims.limits?.aiMonthlyCapCents) || 0; +} + +async function hubStatus(fresh = false): Promise<{ value: HubAiStatus; available: boolean }> { + if (!fresh && cached && Date.now() - cached.at < STATUS_TTL_MS) return cached; + try { + remember(await hub.signedPost('/api/installs/ai/status', { protocolVersion: hub.PROTOCOL_VERSION })); + } catch (e) { + const err = e as { code?: string; statusCode?: number }; + // A Hub before 1.6.0 has no AI; a released install has no licence: both mean off. + if (err.statusCode === 404) cached = { at: Date.now(), value: OFF, available: true }; + else { + console.warn('[ai] could not ask the Hub for the AI status:', (e as Error).message); + // Unreachable: keep showing the buttons (they say AI is unavailable when pressed). + cached = { at: Date.now(), value: { ...(cached?.value || OFF), enabled: true }, available: false }; + } + } + return cached!; +} + +export async function aiStatus({ fresh = false } = {}): Promise { + const settings = await getAiSettings(); + if ((await licenceCap()) <= 0) return { ...OFF, available: true, helpers: settings.helpers }; + const { value, available } = await hubStatus(fresh); + return { ...value, available, helpers: settings.helpers }; +} + +// ─── Running a helper ───────────────────────────────────────────────────────── + +export type HelperRequest = { + /** The helper's fixed instructions (the Hub has Claude cache them). */ + system: string; + /** This request's text. Never names, contact details, medical or children's information. */ + input: string; + /** A JSON schema: the answer comes back as JSON in this shape. */ + schema?: object; + maxTokens: number; + effort?: 'low' | 'medium' | 'high'; +}; + +const failure = (code: 'FORBIDDEN' | 'RATE_LIMITED' | 'UNAVAILABLE', reason: string, message: string) => Object.assign(new ApiError(code, message), { reason }); + +function renewsText(renewsOn: string | null): string { + if (!renewsOn) return 'next month'; + return new Date(`${renewsOn}T12:00:00Z`).toLocaleDateString('en-ZA', { day: 'numeric', month: 'long', timeZone: 'Africa/Johannesburg' }); +} + +/** The Hub's errors (§3b) as v2 errors, and what to log. */ +function fromHubError(e: { code?: string; statusCode?: number; message: string; data?: any }): { error: ApiError; outcome: string } { + remember(e.data?.status); + switch (e.code) { + case 'AI_CAP_REACHED': + return { outcome: 'cap_reached', error: failure('FORBIDDEN', 'AI_CAP_REACHED', `This month's AI allowance is used up — it renews on ${renewsText(e.data?.status?.renewsOn ?? null)}.`) }; + case 'AI_OFF': case 'LICENCE_INACTIVE': case 'AI_NOT_CONFIGURED': + return { outcome: 'unavailable', error: failure('FORBIDDEN', 'AI_OFF', 'AI helpers are not available on this site.') }; + case 'AI_REFUSED': + return { outcome: 'refused', error: failure('UNAVAILABLE', 'AI_REFUSED', "The AI couldn't help with this one. Try wording it differently.") }; + case 'AI_INCOMPLETE': + return { outcome: 'incomplete', error: failure('UNAVAILABLE', 'AI_INCOMPLETE', 'The answer was too long and got cut off. Try asking for less.') }; + case 'AI_INPUT_TOO_LARGE': + return { outcome: 'failed', error: failure('UNAVAILABLE', 'AI_INPUT_TOO_LARGE', 'There is too much here to send in one go.') }; + case 'AI_FAILED': + return { outcome: 'failed', error: failure('UNAVAILABLE', 'AI_FAILED', "The AI's answer couldn't be used. Try again.") }; + default: + return { outcome: 'unavailable', error: failure('UNAVAILABLE', 'AI_UNAVAILABLE', 'AI is unavailable right now. Try again in a few minutes.') }; + } +} + +/** Starts of today in South African time, for the per-person daily limit. */ +function startOfToday(now = new Date()): Date { + const sast = new Date(now.getTime() + 2 * 3600 * 1000); + return new Date(Date.UTC(sast.getUTCFullYear(), sast.getUTCMonth(), sast.getUTCDate()) - 2 * 3600 * 1000); +} + +let prunedOn = ''; +/** Calls older than about 13 months go (once a day, on the first call). */ +async function pruneOldCalls(now = new Date()): Promise { + const today = now.toISOString().slice(0, 10); + if (prunedOn === today) return; + prunedOn = today; + await prisma.aiCall.deleteMany({ where: { createdAt: { lt: new Date(now.getTime() - KEEP_CALLS_DAYS * 86400000) } } }).catch(() => {}); +} + +/** At 80% of the allowance, the site's admins get one email a month. */ +async function warnAt80(status: HubAiStatus): Promise { + if (!status.enabled || status.usedPercent < 80 || !status.renewsOn) return; + const row = await prisma.appSetting.findUnique({ where: { key: WARNED_KEY } }); + if (row?.value === status.renewsOn) return; + await prisma.appSetting.upsert({ where: { key: WARNED_KEY }, update: { value: status.renewsOn }, create: { key: WARNED_KEY, value: status.renewsOn } }); + if (!email.isSmtpConfigured()) return; + const admins = await prisma.user.findMany({ where: { role: 'admin', isActive: true }, select: { email: true } }); + const when = renewsText(status.renewsOn); + const text = `This site has used ${status.usedPercent}% of this month's AI allowance (R${(status.usedCents / 100).toFixed(2)} of R${(status.capCents / 100).toFixed(2)}). The AI buttons stop working when it runs out, until it renews on ${when}. Site settings → AI shows who used it and for what.`; + for (const a of admins) { + await email.sendMail({ to: a.email, subject: `AI allowance ${status.usedPercent}% used`, text, html: email.emailWrapper(`

${text}

`) }) + .catch(e => console.warn('[ai] 80% warning email failed:', (e as Error).message)); + } +} + +/** + * Run one helper call for a person. Resolves to the answer (text, or JSON when a schema was + * given) and the new status; throws an ApiError with a `reason` (AI_OFF, AI_HELPER_OFF, + * AI_CAP_REACHED, AI_DAILY_LIMIT, AI_REFUSED, AI_INCOMPLETE, AI_UNAVAILABLE…). + */ +export async function runHelper(helper: HelperName, userId: string, req: HelperRequest): Promise<{ output: unknown; status: AiStatus }> { + const status = await aiStatus(); + if (!status.enabled) throw failure('FORBIDDEN', 'AI_OFF', 'AI helpers are not available on this site.'); + if (!status.helpers[helper]) throw failure('FORBIDDEN', 'AI_HELPER_OFF', 'This AI helper is switched off in Site settings → AI.'); + if (status.capReached) throw failure('FORBIDDEN', 'AI_CAP_REACHED', `This month's AI allowance is used up — it renews on ${renewsText(status.renewsOn)}.`); + const { dailyLimitPerPerson } = await getAiSettings(); + if (dailyLimitPerPerson > 0) { + const today = await prisma.aiCall.count({ where: { userId, createdAt: { gte: startOfToday() }, outcome: { in: ['ok', 'refused', 'incomplete'] } } }); + if (today >= dailyLimitPerPerson) throw failure('RATE_LIMITED', 'AI_DAILY_LIMIT', `You've used the AI helpers ${dailyLimitPerPerson} times today, the most this site allows. Try again tomorrow.`); + } + + let outcome = 'ok'; + let chargedCents = 0; + try { + const reply = await hub.signedPost('/api/installs/ai/complete', { protocolVersion: hub.PROTOCOL_VERSION, helper, ...req }, { timeoutMs: CALL_TIMEOUT_MS }); + chargedCents = Number(reply.chargedCents) || 0; + remember(reply.status); + await warnAt80(reply.status).catch(e => console.warn('[ai] 80% check failed:', (e as Error).message)); + return { output: reply.output, status: { ...(cached?.value || OFF), available: true, helpers: status.helpers } }; + } catch (e) { + if (e instanceof ApiError) throw e; + const mapped = fromHubError(e as Error & { code?: string; data?: any }); + outcome = mapped.outcome; + if ((e as { code?: string }).code === 'HUB_UNREACHABLE') remember(cached?.value || { ...OFF, enabled: true }, false); + throw mapped.error; + } finally { + await prisma.aiCall.create({ data: { userId, helper, outcome, chargedCents } }).catch(err => console.warn('[ai] could not log the call:', (err as Error).message)); + await pruneOldCalls(); + } +} + +// ─── Usage (Site settings → AI) ─────────────────────────────────────────────── + +/** This month's use on this site: per person, per helper and per day (South African time). */ +export async function usageThisMonth(now = new Date()) { + const sast = new Date(now.getTime() + 2 * 3600 * 1000); + const from = new Date(Date.UTC(sast.getUTCFullYear(), sast.getUTCMonth(), 1) - 2 * 3600 * 1000); + const calls = await prisma.aiCall.findMany({ where: { createdAt: { gte: from } }, select: { userId: true, helper: true, outcome: true, chargedCents: true, createdAt: true } }); + const add = (m: Map, key: string, cents: number) => { + const v = m.get(key) || { uses: 0, chargedCents: 0 }; + v.uses++; + v.chargedCents += cents; + m.set(key, v); + }; + const byPerson = new Map(); + const byHelper = new Map(); + const byDay = new Map(); + for (const c of calls) { + if (c.outcome === 'cap_reached' || c.outcome === 'unavailable') continue; + add(byPerson, c.userId || '', c.chargedCents); + add(byHelper, c.helper, c.chargedCents); + add(byDay, new Date(c.createdAt.getTime() + 2 * 3600 * 1000).toISOString().slice(0, 10), c.chargedCents); + } + const people = await prisma.user.findMany({ where: { id: { in: [...byPerson.keys()].filter(Boolean) } }, select: { id: true, name: true } }); + const names = new Map(people.map(p => [p.id, p.name])); + return { + people: [...byPerson.entries()].map(([id, v]) => ({ userId: id || null, name: id ? names.get(id) || 'Unknown' : 'Removed account', ...v })).sort((a, b) => b.chargedCents - a.chargedCents), + helpers: [...byHelper.entries()].map(([helper, v]) => ({ helper, ...v })).sort((a, b) => b.chargedCents - a.chargedCents), + days: [...byDay.entries()].map(([day, v]) => ({ day, ...v })).sort((a, b) => a.day.localeCompare(b.day)), + }; +} + +// For tests. +export const _internal = { fromHubError, startOfToday, renewsText }; diff --git a/apps/events/backend/src/hub/client.js b/apps/events/backend/src/hub/client.js index 4b5dc4c..53d5f87 100644 --- a/apps/events/backend/src/hub/client.js +++ b/apps/events/backend/src/hub/client.js @@ -25,10 +25,12 @@ function hubUrl() { } class HubError extends Error { - constructor(message, code, status) { + constructor(message, code, status, data = null) { super(message); this.code = code; this.statusCode = status; + // The Hub's whole error body (AI errors carry the new AI status, protocol §3b). + this.data = data; } } @@ -53,7 +55,7 @@ async function read(keys) { return Object.fromEntries(rows.map(r => [r.key, r.value])); } -async function post(path, body, headers = {}) { +async function post(path, body, headers = {}, timeoutMs = TIMEOUT_MS) { const raw = JSON.stringify(body); let res; try { @@ -61,18 +63,21 @@ async function post(path, body, headers = {}) { method: 'POST', headers: { 'Content-Type': 'application/json', ...(typeof headers === 'function' ? headers(raw) : headers) }, body: raw, - signal: AbortSignal.timeout(TIMEOUT_MS), + signal: AbortSignal.timeout(timeoutMs), }); } catch (e) { throw new HubError(`The Hub (${hubUrl()}) could not be reached: ${e?.message || e}`, 'HUB_UNREACHABLE', 502); } const data = await res.json().catch(() => ({})); - if (!res.ok) throw new HubError(data.message || `The Hub answered ${res.status}`, data.code || 'HUB_ERROR', res.status); + if (!res.ok) throw new HubError(data.message || `The Hub answered ${res.status}`, data.code || 'HUB_ERROR', res.status, data); return data; } -/** POST signed with the install secret (§3). Throws NOT_CONNECTED when there is no connection. */ -async function signedPost(path, body) { +/** + * POST signed with the install secret (§3). Throws NOT_CONNECTED when there is no connection. + * AI calls wait longer than the default (Claude can take a while to write). + */ +async function signedPost(path, body, { timeoutMs = TIMEOUT_MS } = {}) { const s = await read(['hub_install_id', 'hub_install_secret']); if (!s.hub_install_id || !s.hub_install_secret) throw new HubError('This site isn\'t connected to the Hub yet.', 'NOT_CONNECTED', 400); const secret = decrypt(s.hub_install_secret); @@ -83,7 +88,7 @@ async function signedPost(path, body) { 'X-Hub-Timestamp': timestamp, 'X-Hub-Signature': crypto.createHmac('sha256', secret).update(`${timestamp}.${raw}`).digest('hex'), }; - }); + }, timeoutMs); } /** Register this install with a licence key. Returns the licence claims. */ @@ -211,4 +216,4 @@ function heartbeatSoon(delayMs = 30 * 1000) { soonTimer.unref?.(); } -module.exports = { PROTOCOL_VERSION, HUB_KEYS, hubUrl, HubError, connect, heartbeat, heartbeatSoon, requestUpdate, cancelUpdateRequest, snoozeUpdate }; +module.exports = { PROTOCOL_VERSION, HUB_KEYS, hubUrl, HubError, signedPost, connect, heartbeat, heartbeatSoon, requestUpdate, cancelUpdateRequest, snoozeUpdate }; diff --git a/apps/events/backend/src/utils/privacy.js b/apps/events/backend/src/utils/privacy.js index fe19a3b..204e3c8 100644 --- a/apps/events/backend/src/utils/privacy.js +++ b/apps/events/backend/src/utils/privacy.js @@ -469,6 +469,8 @@ async function anonymiseUser(userId, db = prisma) { await tx.webhookDelivery.deleteMany({ where: { userId } }); // Their saved list filters (can hold search text, such as names). await tx.savedFilter.deleteMany({ where: { userId } }); + // AI helper calls (2.0): kept for the site's monthly totals, no longer linked to them. + await tx.aiCall.updateMany({ where: { userId }, data: { userId: null } }); return { attendees: attendeeIds.length, formAnswers: answers.count, providerRecords: txns.length + checkouts.length, familyDeleted, shiftsGivenUp }; }); diff --git a/apps/events/backend/src/v2/errors.ts b/apps/events/backend/src/v2/errors.ts index f34ae48..959973c 100644 --- a/apps/events/backend/src/v2/errors.ts +++ b/apps/events/backend/src/v2/errors.ts @@ -14,6 +14,7 @@ export type ErrorCode = | 'CONFLICT' | 'RATE_LIMITED' | 'READ_ONLY' + | 'UNAVAILABLE' | 'INTERNAL'; export const ERROR_STATUS: Record = { @@ -24,6 +25,8 @@ export const ERROR_STATUS: Record = { CONFLICT: 409, RATE_LIMITED: 429, READ_ONLY: 403, + // Something this depends on (the Hub, the AI service) can't be reached right now. + UNAVAILABLE: 503, INTERNAL: 500, }; @@ -54,7 +57,7 @@ export function zodFields(err: ZodError): Record { return fields; } -const STATUS_CODE: Record = { 400: 'VALIDATION_FAILED', 401: 'UNAUTHENTICATED', 403: 'FORBIDDEN', 404: 'NOT_FOUND', 409: 'CONFLICT', 423: 'READ_ONLY', 429: 'RATE_LIMITED' }; +const STATUS_CODE: Record = { 400: 'VALIDATION_FAILED', 401: 'UNAUTHENTICATED', 403: 'FORBIDDEN', 404: 'NOT_FOUND', 409: 'CONFLICT', 423: 'READ_ONLY', 429: 'RATE_LIMITED', 503: 'UNAVAILABLE' }; const PRISMA_CODE: Record = { P2002: 'CONFLICT', P2025: 'NOT_FOUND', P2003: 'CONFLICT' }; type LegacyError = Error & { statusCode?: number; status?: number; code?: string }; diff --git a/apps/events/backend/src/v2/index.ts b/apps/events/backend/src/v2/index.ts index f90438a..b88735e 100644 --- a/apps/events/backend/src/v2/index.ts +++ b/apps/events/backend/src/v2/index.ts @@ -21,6 +21,7 @@ import './resources/peopleMessaging'; import './resources/adminPrivacy'; import './resources/checkin'; import './resources/auth'; +import './resources/ai'; const pkg = require('../../package.json') as { version: string }; diff --git a/apps/events/backend/src/v2/resources/ai.ts b/apps/events/backend/src/v2/resources/ai.ts new file mode 100644 index 0000000..c6f39aa --- /dev/null +++ b/apps/events/backend/src/v2/resources/ai.ts @@ -0,0 +1,77 @@ +import { z } from 'zod'; +import { defineRoute } from '../route'; +import { single } from '../paging'; +import { aiStatus, getAiSettings, saveAiSettings, usageThisMonth, HELPERS, clearAiStatusCache } from '../../ai'; + +/* eslint-disable @typescript-eslint/no-explicit-any -- the JS helpers below aren't typed yet */ +const { campusIndependent } = require('../../utils/campusScope') as { campusIndependent(reason: string): any }; +const { getClientIp } = require('../../utils/requestUtils') as { getClientIp(req: unknown): string }; + +const helperFlags = z.object(Object.fromEntries(HELPERS.map(h => [h, z.boolean()])) as Record<(typeof HELPERS)[number], z.ZodBoolean>); + +const status = z.object({ + enabled: z.boolean().describe('false: hide the AI buttons (the licence has no AI, or the site isn\'t connected to the Hub)'), + capReached: z.boolean().describe('true: show the buttons disabled until `renewsOn`'), + available: z.boolean().describe('false: the Hub couldn\'t be reached just now'), + capCents: z.number().describe('The monthly allowance, in cents'), + usedCents: z.number().describe('Used this month, in cents (fractions of a cent)'), + usedPercent: z.number(), + renewsOn: z.string().nullable().describe('YYYY-MM-DD'), + helpers: helperFlags.describe('Each helper switched on or off in Site settings → AI'), +}); + +const settings = z.object({ + helpers: helperFlags, + dailyLimitPerPerson: z.number().int().min(0).max(1000).describe('0 = no limit'), +}); + +const use = z.object({ uses: z.number().int(), chargedCents: z.number() }); + +export const getAiStatus = defineRoute({ + method: 'get', + path: '/ai/status', + tag: 'AI', + summary: 'Whether to show the AI buttons', + description: 'Hidden when `enabled` is false; shown but disabled when `capReached` (until `renewsOn`, or until the allowance is raised). Cached for a minute; every AI call refreshes it.', + access: 'supervisor', + campusScope: 'campusIndependent (the site\'s AI allowance)', + middleware: [campusIndependent('the site\'s AI allowance')], + response: single(status), + async handler() { + return { data: await aiStatus() }; + }, +}); + +export const getAiUsage = defineRoute({ + method: 'get', + path: '/ai/usage', + tag: 'AI', + summary: 'AI use this month', + description: 'For Site settings → AI: the allowance, this site\'s switches, and this month\'s use per person, per helper and per day.', + access: 'admin', + response: single(z.object({ + status, + settings, + people: z.array(use.extend({ userId: z.string().nullable(), name: z.string() })), + helpers: z.array(use.extend({ helper: z.string() })), + days: z.array(use.extend({ day: z.string() })), + })), + async handler() { + clearAiStatusCache(); + const [s, settingsNow, usage] = await Promise.all([aiStatus({ fresh: true }), getAiSettings(), usageThisMonth()]); + return { data: { status: s, settings: settingsNow, ...usage } }; + }, +}); + +export const updateAiSettings = defineRoute({ + method: 'put', + path: '/ai/settings', + tag: 'AI', + summary: 'Switch helpers on or off, and set a daily limit', + access: 'admin', + body: z.object({ helpers: helperFlags.partial().optional(), dailyLimitPerPerson: z.number().int().min(0).max(1000).optional() }), + response: single(settings), + async handler({ body, user, req }) { + return { data: await saveAiSettings(body, user!, getClientIp(req)) }; + }, +}); diff --git a/apps/events/backend/tests/ai.test.ts b/apps/events/backend/tests/ai.test.ts new file mode 100644 index 0000000..8bbdabc --- /dev/null +++ b/apps/events/backend/tests/ai.test.ts @@ -0,0 +1,134 @@ +// AI helpers (2.0): what the buttons do, and how a helper call goes through the Hub (§3b). + +const mockCalls: Array> = []; +const mockSettings = new Map(); +const mockDb = { + appSetting: { + findUnique: jest.fn(async ({ where }: { where: { key: string } }) => (mockSettings.has(where.key) ? { key: where.key, value: mockSettings.get(where.key) } : null)), + upsert: jest.fn(async ({ where, update }: { where: { key: string }; update: { value: string } }) => { mockSettings.set(where.key, update.value); }), + }, + aiCall: { + count: jest.fn(async () => mockCalls.filter(c => c.outcome === 'ok').length), + create: jest.fn(async ({ data }: { data: Record }) => { mockCalls.push(data); return data; }), + deleteMany: jest.fn(async () => ({ count: 0 })), + }, + user: { findMany: jest.fn(async () => [{ email: 'admin@test.local' }]) }, +}; +jest.mock('../src/config/db', () => mockDb); + +const mockLicence = { connected: true, readOnly: false, state: 'active', claims: { limits: { aiMonthlyCapCents: 5000 } } as { limits: { aiMonthlyCapCents: number } } | null }; +jest.mock('../src/hub/licence', () => ({ licenceStatus: jest.fn(async () => mockLicence) })); + +class MockHubError extends Error { + constructor(message: string, public code: string, public statusCode: number, public data: unknown = null) { super(message); } +} +const mockPost = jest.fn(); +jest.mock('../src/hub/client', () => ({ PROTOCOL_VERSION: 1, HubError: MockHubError, signedPost: (...a: unknown[]) => mockPost(...a) })); +const mockMail = jest.fn(async (_m: unknown) => undefined); +jest.mock('../src/utils/email', () => ({ sendMail: (m: unknown) => mockMail(m), emailWrapper: (s: string) => s, isSmtpConfigured: () => true })); +jest.mock('../src/utils/adminAudit', () => ({ logAdminAction: jest.fn(async () => undefined) })); + +import { aiStatus, runHelper, saveAiSettings, clearAiStatusCache, _internal } from '../src/ai'; + +const hubStatus = (over = {}) => ({ enabled: true, capReached: false, capCents: 5000, usedCents: 100, usedPercent: 2, renewsOn: '2026-12-01', ...over }); +const req = { system: 'Write a friendly message.', input: 'Bring a sleeping bag.', maxTokens: 500 }; + +beforeEach(() => { + mockCalls.length = 0; + mockSettings.clear(); + mockPost.mockReset(); + mockMail.mockClear(); + mockLicence.connected = true; + mockLicence.readOnly = false; + mockLicence.claims = { limits: { aiMonthlyCapCents: 5000 } }; + clearAiStatusCache(); +}); + +describe('status', () => { + test('a licence without AI never asks the Hub', async () => { + mockLicence.claims = { limits: { aiMonthlyCapCents: 0 } }; + expect(await aiStatus()).toMatchObject({ enabled: false, capReached: false }); + mockLicence.connected = false; + expect((await aiStatus()).enabled).toBe(false); + expect(mockPost).not.toHaveBeenCalled(); + }); + + test('asks the Hub and caches its answer for a minute', async () => { + mockPost.mockResolvedValue(hubStatus()); + expect(await aiStatus()).toMatchObject({ enabled: true, available: true, usedCents: 100, helpers: { draft_event: true } }); + await aiStatus(); + expect(mockPost).toHaveBeenCalledTimes(1); + expect(mockPost).toHaveBeenCalledWith('/api/installs/ai/status', { protocolVersion: 1 }); + }); + + test('a Hub without AI (404) means off; an unreachable Hub keeps the buttons, marked unavailable', async () => { + mockPost.mockRejectedValueOnce(new MockHubError('Not found', 'NOT_FOUND', 404)); + expect((await aiStatus()).enabled).toBe(false); + clearAiStatusCache(); + mockPost.mockRejectedValueOnce(new MockHubError('down', 'HUB_UNREACHABLE', 502)); + expect(await aiStatus()).toMatchObject({ enabled: true, available: false }); + }); +}); + +describe('running a helper', () => { + test('sends the request to the Hub, logs the call, returns the answer', async () => { + mockPost.mockResolvedValueOnce(hubStatus()).mockResolvedValueOnce({ output: 'Hi all!', chargedCents: 0.31, status: hubStatus({ usedCents: 100.31 }) }); + const r = await runHelper('draft_message', 'u1', req); + expect(r.output).toBe('Hi all!'); + expect(r.status.usedCents).toBe(100.31); + expect(mockPost).toHaveBeenLastCalledWith('/api/installs/ai/complete', { protocolVersion: 1, helper: 'draft_message', ...req }, { timeoutMs: 90000 }); + expect(mockCalls).toEqual([{ userId: 'u1', helper: 'draft_message', outcome: 'ok', chargedCents: 0.31 }]); + }); + + test('a helper switched off, or the cap reached, never reaches the Hub', async () => { + mockPost.mockResolvedValue(hubStatus({ capReached: true })); + await expect(runHelper('draft_message', 'u1', req)).rejects.toMatchObject({ code: 'FORBIDDEN', reason: 'AI_CAP_REACHED' }); + clearAiStatusCache(); + mockPost.mockResolvedValue(hubStatus()); + await saveAiSettings({ helpers: { draft_message: false } }, { id: 'a1', role: 'admin' }); + await expect(runHelper('draft_message', 'u1', req)).rejects.toMatchObject({ reason: 'AI_HELPER_OFF' }); + expect(mockPost).not.toHaveBeenCalledWith('/api/installs/ai/complete', expect.anything(), expect.anything()); + }); + + test('the per-person daily limit', async () => { + await saveAiSettings({ dailyLimitPerPerson: 1 }, { id: 'a1', role: 'admin' }); + mockPost.mockResolvedValueOnce(hubStatus()).mockResolvedValueOnce({ output: 'x', chargedCents: 0.1, status: hubStatus() }); + await runHelper('draft_message', 'u1', req); + await expect(runHelper('draft_message', 'u1', req)).rejects.toMatchObject({ code: 'RATE_LIMITED', reason: 'AI_DAILY_LIMIT' }); + }); + + test('the Hub refusing at the cap updates the status, so the buttons disable at once', async () => { + mockPost.mockResolvedValueOnce(hubStatus()) + .mockRejectedValueOnce(new MockHubError('used up', 'AI_CAP_REACHED', 402, { code: 'AI_CAP_REACHED', status: hubStatus({ capReached: true }) })); + await expect(runHelper('draft_message', 'u1', req)).rejects.toMatchObject({ reason: 'AI_CAP_REACHED', message: expect.stringContaining('1 December') }); + expect((await aiStatus()).capReached).toBe(true); + expect(mockCalls[0]).toMatchObject({ outcome: 'cap_reached', chargedCents: 0 }); + }); + + test('admins are emailed once a month at 80%', async () => { + const at80 = hubStatus({ usedPercent: 81, usedCents: 4050 }); + mockPost.mockResolvedValueOnce(hubStatus()).mockResolvedValue({ output: 'x', chargedCents: 1, status: at80 }); + await runHelper('draft_message', 'u1', req); + await runHelper('draft_message', 'u1', req); + expect(mockMail).toHaveBeenCalledTimes(1); + expect(mockMail.mock.calls[0]).toEqual([expect.objectContaining({ to: 'admin@test.local', subject: 'AI allowance 81% used' })]); + }); +}); + +describe('Hub errors', () => { + test.each([ + ['AI_REFUSED', 'UNAVAILABLE', 'refused'], + ['AI_INCOMPLETE', 'UNAVAILABLE', 'incomplete'], + ['AI_OFF', 'FORBIDDEN', 'unavailable'], + ['HUB_UNREACHABLE', 'UNAVAILABLE', 'unavailable'], + ])('%s → %s, logged as %s', (hubCode, code, outcome) => { + const r = _internal.fromHubError({ code: hubCode, message: 'x' }); + expect(r.error.code).toBe(code); + expect(r.outcome).toBe(outcome); + }); + + test('today starts at midnight South African time', () => { + expect(_internal.startOfToday(new Date('2026-11-10T22:30:00Z')).toISOString()).toBe('2026-11-10T22:00:00.000Z'); + expect(_internal.startOfToday(new Date('2026-11-10T10:00:00Z')).toISOString()).toBe('2026-11-09T22:00:00.000Z'); + }); +}); diff --git a/apps/events/docs/hub-protocol.md b/apps/events/docs/hub-protocol.md index d4f143c..342c101 100644 --- a/apps/events/docs/hub-protocol.md +++ b/apps/events/docs/hub-protocol.md @@ -178,6 +178,65 @@ X-Hub-Install / X-Hub-Timestamp / X-Hub-Signature (as in §3) history. Rate-limited with update requests. A Hub older than 1.4.0 answers `404 NOT_FOUND`. - **"Not now"** (no reminders until the next version) stays on the install; the Hub isn't told. +## 3b. AI (Cross Events 2.0, Hub 1.6.0) + +Installs never hold the Claude API key. Each AI helper call goes through the Hub, which adds the +key, checks the licence's monthly cap, calls Claude and meters the call. Both requests are signed +exactly like the heartbeat. The install keeps its prompts; the Hub stores **no prompt or response +text** — only the install, helper name, tokens, cost and time. + +### Status + +``` +POST /api/installs/ai/status +X-Hub-Install / X-Hub-Timestamp / X-Hub-Signature (as in §3) +{ "protocolVersion": 1 } +→ 200 { "enabled": true, "capReached": false, "capCents": 5000, "usedCents": 812.4, + "usedPercent": 16, "renewsOn": "2026-12-01" } +``` + +- **`enabled: false`** — hide the AI buttons everywhere: the licence's cap is R0, the licence isn't + active (suspended, revoked, or past its grace days), or the Hub's AI isn't set up. +- **`capReached: true`** — show the buttons **disabled** ("This month's AI allowance is used up — it + renews on 1 December"). Reached means there isn't room left for even a small call. +- Amounts are cents (rand) as **charged** to the church, with fractions (a call costs a fraction of a + cent). The month is South African time; `renewsOn` is the 1st of the next month. + +### A helper call + +``` +POST /api/installs/ai/complete +X-Hub-Install / X-Hub-Timestamp / X-Hub-Signature (as in §3) +{ + "protocolVersion": 1, + "helper": "draft_event", // lower-case name, for usage reports + "system": "…", // the helper's fixed instructions (cached by Claude) + "input": "…", // this request's text + "schema": { … }, // optional JSON schema: the reply is JSON in that shape + "maxTokens": 2000, // 1–8000 + "effort": "low" // optional: low (default) | medium | high +} +→ 200 { "output": "…" | { … }, // text, or the parsed JSON when a schema was given + "usage": { "inputTokens": 1840, "outputTokens": 420 }, + "chargedCents": 0.31, + "status": { …as above… } } +``` + +- **Errors** are `{ code, message, status }` — `status` is the new AI status, so buttons can disable + straight after the call that used up the allowance: + - `402 AI_CAP_REACHED` — this call could pass the cap (checked before calling Claude). + - `403 AI_OFF` (cap R0) · `403 LICENCE_INACTIVE` · `503 AI_NOT_CONFIGURED` (Hub not set up). + - `422 AI_REFUSED` — Claude declined. `502 AI_INCOMPLETE` — the answer hit `maxTokens`. + `502 AI_FAILED` — not usable (e.g. JSON in the wrong shape). These still cost what was used. + - `503 AI_BUSY` / `503 AI_UNAVAILABLE` — Claude unreachable or rate-limited; nothing is charged. + - `400 BAD_REQUEST`, `413 AI_INPUT_TOO_LARGE` (about 90 000 tokens), and the §3 errors. +- **Metering:** real cost = tokens × the model's price × the exchange rate set in the Hub; charged = + real × (1 + markup). The cap counts charged rand. Before calling Claude the Hub holds the worst + case (an over-estimate of the prompt, plus `maxTokens`) against the cap in one transaction per + install, so calls at the same moment can't pass it; afterwards the hold becomes the real amount. +- Rate-limited to 60 a minute per IP (against runaway loops; money is limited by the cap). +- A Hub older than 1.6.0 answers `404 NOT_FOUND`: the install treats that as "AI off". + ## 4. Licence token `hel1..` — `payload` is base64url JSON, `signature` is the base64url @@ -195,7 +254,7 @@ Ed25519 signature of the ASCII string `hel1.`. "graceDays": 14, "issuedAt": "2026-10-24T08:15:00.000Z", "validUntil": "2026-11-23T08:15:00.000Z", // issuedAt + 30 days - "limits": { "aiMonthlyCapCents": 0 } + "limits": { "aiMonthlyCapCents": 0 } // the AI cap (§3b); 0 = AI off } ``` @@ -221,8 +280,3 @@ grace starts). Blocking the Hub can't keep a suspended licence active for more t fields to a heartbeat or a token doesn't need a new version — both sides ignore fields they don't know. - The Hub accepts protocol `N` and `N-1`; anything else is `400 UNSUPPORTED_PROTOCOL`. - -## 6. Later (not in v1) - -- **AI proxy** (Cross Events 2.0): `POST /api/ai/complete`, signed like the heartbeat; the Hub holds - the Claude API key, meters each call in rand and enforces `limits.aiMonthlyCapCents`. diff --git a/apps/events/frontend/src/app/dashboard/admin/settings/page.tsx b/apps/events/frontend/src/app/dashboard/admin/settings/page.tsx index b46d220..1d6ba5a 100644 --- a/apps/events/frontend/src/app/dashboard/admin/settings/page.tsx +++ b/apps/events/frontend/src/app/dashboard/admin/settings/page.tsx @@ -8,7 +8,7 @@ import { ApiError, resolveToApiOrigin } from "@/lib/api"; import { apiV2Raw, apiV2Data } from "@/lib/apiV2"; import { useSiteSettings } from "@/contexts/SiteSettingsContext"; import { useDismissingState } from "@/hooks/useDismissingState"; -import { Building2, Palette, Bell, Mail, Scale, MessageCircle, CreditCard, DatabaseBackup, Timer, KeyRound, MapPinned, type LucideIcon, Webhook } from "lucide-react"; +import { Building2, Palette, Bell, Mail, Scale, MessageCircle, CreditCard, DatabaseBackup, Timer, KeyRound, MapPinned, type LucideIcon, Webhook, Sparkles } from "lucide-react"; import { ColorPickerField } from "@/components/admin/ColorPickerField"; import { BrandingPreviewPanel } from "@/components/admin/BrandingPreviewPanel"; import { BackupsTab } from "@/components/admin/BackupsTab"; @@ -16,6 +16,7 @@ import { JobsTab } from "@/components/admin/JobsTab"; import { PaymentsTab } from "@/components/admin/PaymentsTab"; import { LicenceTab } from "@/components/admin/LicenceTab"; import { WebhooksTab } from "@/components/admin/WebhooksTab"; +import { AiTab } from "@/components/admin/AiTab"; import { CampusesTab } from "@/components/admin/CampusesTab"; import { extractDominantColors } from "@/lib/extractColors"; import { mapsSearchUrl } from "@/lib/maps"; @@ -23,7 +24,7 @@ import { errorMessage } from "@/lib/utils"; import { BackLink } from "@/components/shared/BackLink"; import { uploadImage } from "@/lib/eventSetup"; -type TabId = "organisation" | "campuses" | "branding" | "notifications" | "email" | "legal" | "whatsapp" | "payments" | "webhooks" | "backups" | "jobs" | "licence"; +type TabId = "organisation" | "campuses" | "branding" | "notifications" | "email" | "legal" | "whatsapp" | "payments" | "webhooks" | "backups" | "jobs" | "licence" | "ai"; const TABS: { id: TabId; label: string; icon: LucideIcon }[] = [ { id: "organisation", label: "Organisation", icon: Building2 }, @@ -38,6 +39,7 @@ const TABS: { id: TabId; label: string; icon: LucideIcon }[] = [ { id: "backups", label: "Backups", icon: DatabaseBackup }, { id: "jobs", label: "Background jobs", icon: Timer }, { id: "licence", label: "Licence", icon: KeyRound }, + { id: "ai", label: "AI", icon: Sparkles }, ]; const inputCls = @@ -717,6 +719,7 @@ function SiteSettingsPageInner() { {activeTab === "webhooks" && } {activeTab === "jobs" && } {activeTab === "licence" && } + {activeTab === "ai" && } {activeTab === "campuses" && } diff --git a/apps/events/frontend/src/components/admin/AiTab.tsx b/apps/events/frontend/src/components/admin/AiTab.tsx new file mode 100644 index 0000000..e018da0 --- /dev/null +++ b/apps/events/frontend/src/components/admin/AiTab.tsx @@ -0,0 +1,147 @@ +"use client"; + +import React, { useEffect, useState } from "react"; +import { Sparkles } from "lucide-react"; +import { useAuth } from "@/hooks/useAuth"; +import { apiV2, type V2Result } from "@/lib/apiV2"; +import { loadAiStatus, renewsText } from "@/lib/ai"; +import { errorMessage } from "@/lib/utils"; + +type Usage = V2Result<"/ai/usage", "get">["data"]; +type Helper = keyof Usage["settings"]["helpers"]; + +const HELPERS: { key: Helper; label: string; where: string }[] = [ + { key: "draft_event", label: "Draft an event", where: "New event: describe it and the form is filled in" }, + { key: "summarise_report", label: "Summarise this report", where: "Reports: a few plain-language insights" }, + { key: "draft_message", label: "Draft a message", where: "Emails and WhatsApp messages to attendees, broadcasts" }, + { key: "summarise_feedback", label: "Summarise feedback", where: "Post-event feedback results" }, + { key: "improve_text", label: "Improve this text", where: "Event descriptions, the banner, message boxes" }, +]; + +// Fractions of a cent add up: show R0.0123 below a rand. +const money = (cents: number) => (cents > 0 && cents < 100 ? `R${(cents / 100).toFixed(4)}` : `R${(cents / 100).toFixed(2)}`); + +/** Site settings → AI: the monthly allowance, who used it for what, and a switch per helper. */ +export function AiTab({ active }: { active: boolean }) { + const { token } = useAuth(); + const [usage, setUsage] = useState(null); + const [limit, setLimit] = useState("0"); + const [msg, setMsg] = useState<{ ok: boolean; text: string } | null>(null); + const [busy, setBusy] = useState(false); + + useEffect(() => { + if (!active || !token) return; + let alive = true; + apiV2("get", "/ai/usage", { authToken: token }) + .then(({ data }) => { if (alive) { setUsage(data); setLimit(String(data.settings.dailyLimitPerPerson)); } }) + .catch(e => { if (alive) setMsg({ ok: false, text: errorMessage(e) || "Could not load AI use." }); }); + return () => { alive = false; }; + }, [active, token]); + + const save = async (helpers: Partial>, dailyLimitPerPerson?: number) => { + if (!token) return; + setBusy(true); + setMsg(null); + try { + const { data } = await apiV2("put", "/ai/settings", { authToken: token, body: { helpers, ...(dailyLimitPerPerson != null ? { dailyLimitPerPerson } : {}) } }); + setUsage(u => (u ? { ...u, settings: data, status: { ...u.status, helpers: data.helpers } } : u)); + setMsg({ ok: true, text: "Saved." }); + loadAiStatus(token, { fresh: true }).catch(() => {}); + } catch (e) { setMsg({ ok: false, text: errorMessage(e) || "Could not save." }); } + setBusy(false); + }; + + if (!usage) return msg ?

{msg.text}

:

Loading…

; + const s = usage.status; + const maxDay = Math.max(0.0001, ...usage.days.map(d => d.chargedCents)); + + return ( +
+
+

AI helpers

+

+ One-click helpers for supervisors and admins: drafting events and messages, improving text, summarising reports and feedback. A person always checks the suggestion before anything is saved or sent. +

+
+ + {!s.enabled ? ( +
+ AI helpers aren't part of this site's licence, so their buttons are hidden. To add them, ask your provider for a monthly AI allowance. +
+ ) : ( +
+
+ This month + {money(s.usedCents)} of {money(s.capCents)} · renews on {renewsText(s.renewsOn)} +
+
+
= 80 ? "bg-amber-500" : "bg-violet-500"}`} style={{ width: `${s.usedPercent}%` }} /> +
+ {s.capReached &&

The allowance is used up: the AI buttons are disabled until {renewsText(s.renewsOn)}, or until your provider raises it.

} + {!s.available &&

The provider's Hub can't be reached right now, so AI is unavailable. Everything else works as usual.

} +

Admins get an email when 80% is used.

+
+ )} + +
+

Helpers

+
    + {HELPERS.map(h => ( +
  • +
    + +

    {h.where}

    +
    + save({ [h.key]: e.target.checked })} /> +
  • + ))} +
+
+ +
{ e.preventDefault(); save({}, Math.max(0, parseInt(limit, 10) || 0)); }}> +
+ + setLimit(e.target.value)} /> +

0 = no limit. Guards against one person using up the month.

+
+ +
+ {msg &&

{msg.text}

} + + {s.enabled && ( +
+
+

By person this month

+ {usage.people.length === 0 ?

Nobody has used AI yet this month.

: ( + + + {usage.people.map(p => )} +
PersonUsesCost
{p.name}{p.uses}{money(p.chargedCents)}
+ )} +
+
+

By helper this month

+ {usage.helpers.length === 0 ?

—

: ( + + + {usage.helpers.map(h => )} +
HelperUsesCost
{HELPERS.find(x => x.key === h.helper)?.label || h.helper}{h.uses}{money(h.chargedCents)}
+ )} +
+ {usage.days.length > 0 && ( +
+

Per day

+
+ {usage.days.map(d =>
)} +
+
+ )} +
+ )} + +

+ Requests go through your provider's Hub to Anthropic (Claude) in the United States. Only what a helper needs is sent — never names, contact details, medical or children's information — and nothing is kept by the provider. Add Anthropic to your operator register (Admin → Privacy) when you start using AI. +

+
+ ); +} diff --git a/apps/events/frontend/src/components/shared/AiButton.tsx b/apps/events/frontend/src/components/shared/AiButton.tsx new file mode 100644 index 0000000..4f447a7 --- /dev/null +++ b/apps/events/frontend/src/components/shared/AiButton.tsx @@ -0,0 +1,51 @@ +"use client"; + +import React, { useId } from "react"; +import { Loader2, Sparkles } from "lucide-react"; +import { useAiStatus } from "@/hooks/useAiStatus"; +import { disabledReason, type AiHelper } from "@/lib/ai"; + +/** + * A button for one AI helper. Not shown at all when the site has no AI (or for anyone but + * supervisors and admins); shown but disabled, with the reason, when this month's allowance is + * used up, the Hub can't be reached, or the helper is switched off in Site settings → AI. + */ +export function AiButton({ helper, onClick, busy = false, children, className = "", size = "md" }: { + helper: AiHelper; + onClick: () => void; + busy?: boolean; + children: React.ReactNode; + className?: string; + size?: "sm" | "md"; +}) { + const status = useAiStatus(); + const reasonId = useId(); + if (!status?.enabled) return null; + const reason = disabledReason(status, helper); + const pad = size === "sm" ? "px-2 py-1 text-xs" : "px-3 py-1.5 text-sm"; + return ( + + + {reason && {reason}} + + ); +} + +/** Under every AI result: a person checks it before anything is saved or sent. */ +export function AiNotice({ className = "" }: { className?: string }) { + return ( +

+ AI suggestion — check it before saving. +

+ ); +} diff --git a/apps/events/frontend/src/hooks/useAiStatus.ts b/apps/events/frontend/src/hooks/useAiStatus.ts new file mode 100644 index 0000000..03b5b75 --- /dev/null +++ b/apps/events/frontend/src/hooks/useAiStatus.ts @@ -0,0 +1,24 @@ +"use client"; + +import { useEffect, useState } from "react"; +import { useAuth } from "@/hooks/useAuth"; +import { currentAiStatus, loadAiStatus, subscribeAiStatus, type AiStatus } from "@/lib/ai"; + +/** + * Whether to show the AI buttons, shared across the page (one request per page load). Null while + * loading, and for anyone who isn't a supervisor or admin — AI helpers are theirs only. + */ +export function useAiStatus(): AiStatus | null { + const { user, token } = useAuth(); + const allowed = !!token && (user?.role === "admin" || user?.role === "supervisor"); + const [status, setStatus] = useState(() => (allowed ? currentAiStatus() : null)); + + useEffect(() => { + if (!allowed || !token) return; + const off = subscribeAiStatus(setStatus); + loadAiStatus(token).then(setStatus).catch(() => {}); + return off; + }, [allowed, token]); + + return allowed ? status : null; +} diff --git a/apps/events/frontend/src/lib/ai.ts b/apps/events/frontend/src/lib/ai.ts new file mode 100644 index 0000000..04d977d --- /dev/null +++ b/apps/events/frontend/src/lib/ai.ts @@ -0,0 +1,76 @@ +import { apiV2Data, apiV2Raw } from "@/lib/apiV2"; +import type { V2Result } from "@/lib/apiV2"; + +/** + * AI helpers (2.0). The site calls AI through the Cross Events Hub, which keeps a monthly + * allowance in rand per licence. One status per page load is shared by every AI button + * (`useAiStatus`), and every helper call refreshes it — so the buttons disable straight after the + * call that used up the allowance. + */ + +export type AiStatus = V2Result<"/ai/status", "get">["data"]; +export type AiHelper = keyof AiStatus["helpers"]; + +const OFF: AiStatus = { + enabled: false, capReached: false, available: true, capCents: 0, usedCents: 0, usedPercent: 0, renewsOn: null, + helpers: { draft_event: false, summarise_report: false, draft_message: false, summarise_feedback: false, improve_text: false }, +}; + +let current: AiStatus | null = null; +let loading: Promise | null = null; +const listeners = new Set<(s: AiStatus) => void>(); + +function publish(s: AiStatus) { + current = s; + listeners.forEach(l => l(s)); +} + +/** The status, fetched once per page load (staff never see AI, so they never ask). */ +export function loadAiStatus(authToken: string, { fresh = false } = {}): Promise { + if (current && !fresh) return Promise.resolve(current); + if (!loading || fresh) { + loading = (apiV2Data("get", "/ai/status", { authToken }) as Promise) + .then(s => { publish(s); return s; }) + .catch(() => { publish(OFF); return OFF; }) + .finally(() => { loading = null; }); + } + return loading; +} + +export function subscribeAiStatus(fn: (s: AiStatus) => void): () => void { + listeners.add(fn); + return () => { listeners.delete(fn); }; +} + +export function currentAiStatus(): AiStatus | null { + return current; +} + +/** "1 December" from "2026-12-01". */ +export function renewsText(renewsOn: string | null): string { + if (!renewsOn) return "next month"; + return new Date(`${renewsOn}T12:00:00Z`).toLocaleDateString("en-ZA", { day: "numeric", month: "long" }); +} + +/** What the button's tooltip says when it can't be used. */ +export function disabledReason(s: AiStatus, helper: AiHelper): string | null { + if (s.capReached) return `This month's AI allowance is used up — it renews on ${renewsText(s.renewsOn)}.`; + if (!s.available) return "AI is unavailable right now. Try again in a few minutes."; + if (!s.helpers[helper]) return "This AI helper is switched off in Site settings → AI."; + return null; +} + +/** + * Run a helper (`POST /api/v2/ai/`). Resolves to its answer; throws the API error (with + * a message written for people). Either way the shared status is refreshed. + */ +export async function runAi(helper: AiHelper, body: object, authToken: string): Promise { + try { + const res = await apiV2Raw<{ output: T; status: AiStatus }>("post", `/ai/${helper.replace(/_/g, "-")}`, { authToken, body }); + publish(res.status); + return res.output; + } catch (e) { + loadAiStatus(authToken, { fresh: true }).catch(() => {}); + throw e; + } +} diff --git a/apps/events/frontend/src/lib/api-v2/openapi.json b/apps/events/frontend/src/lib/api-v2/openapi.json index 505071a..3129415 100644 --- a/apps/events/frontend/src/lib/api-v2/openapi.json +++ b/apps/events/frontend/src/lib/api-v2/openapi.json @@ -97,6 +97,9 @@ }, { "name": "Webhooks" + }, + { + "name": "AI" } ], "paths": { @@ -39939,6 +39942,548 @@ } } } + }, + "/ai/status": { + "get": { + "tags": [ + "AI" + ], + "summary": "Whether to show the AI buttons", + "description": "Hidden when `enabled` is false; shown but disabled when `capReached` (until `renewsOn`, or until the allowance is raised). Cached for a minute; every AI call refreshes it.\n\n**Who:** Supervisors and admins.", + "operationId": "getAiStatus", + "security": [ + { + "bearerAuth": [] + } + ], + "parameters": [], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "false: hide the AI buttons (the licence has no AI, or the site isn't connected to the Hub)" + }, + "capReached": { + "type": "boolean", + "description": "true: show the buttons disabled until `renewsOn`" + }, + "available": { + "type": "boolean", + "description": "false: the Hub couldn't be reached just now" + }, + "capCents": { + "type": "number", + "description": "The monthly allowance, in cents" + }, + "usedCents": { + "type": "number", + "description": "Used this month, in cents (fractions of a cent)" + }, + "usedPercent": { + "type": "number" + }, + "renewsOn": { + "description": "YYYY-MM-DD", + "type": [ + "string", + "null" + ] + }, + "helpers": { + "type": "object", + "properties": { + "draft_event": { + "type": "boolean" + }, + "summarise_report": { + "type": "boolean" + }, + "draft_message": { + "type": "boolean" + }, + "summarise_feedback": { + "type": "boolean" + }, + "improve_text": { + "type": "boolean" + } + }, + "required": [ + "draft_event", + "summarise_report", + "draft_message", + "summarise_feedback", + "improve_text" + ], + "additionalProperties": false, + "description": "Each helper switched on or off in Site settings → AI" + } + }, + "required": [ + "enabled", + "capReached", + "available", + "capCents", + "usedCents", + "usedPercent", + "renewsOn", + "helpers" + ], + "additionalProperties": false + } + }, + "required": [ + "data" + ], + "additionalProperties": false + } + } + } + }, + "401": { + "description": "Not signed in (UNAUTHENTICATED)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Not allowed for this role (FORBIDDEN)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/ai/usage": { + "get": { + "tags": [ + "AI" + ], + "summary": "AI use this month", + "description": "For Site settings → AI: the allowance, this site's switches, and this month's use per person, per helper and per day.\n\n**Who:** Admins only.", + "operationId": "getAiUsage", + "security": [ + { + "bearerAuth": [] + } + ], + "parameters": [], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "status": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "false: hide the AI buttons (the licence has no AI, or the site isn't connected to the Hub)" + }, + "capReached": { + "type": "boolean", + "description": "true: show the buttons disabled until `renewsOn`" + }, + "available": { + "type": "boolean", + "description": "false: the Hub couldn't be reached just now" + }, + "capCents": { + "type": "number", + "description": "The monthly allowance, in cents" + }, + "usedCents": { + "type": "number", + "description": "Used this month, in cents (fractions of a cent)" + }, + "usedPercent": { + "type": "number" + }, + "renewsOn": { + "description": "YYYY-MM-DD", + "type": [ + "string", + "null" + ] + }, + "helpers": { + "type": "object", + "properties": { + "draft_event": { + "type": "boolean" + }, + "summarise_report": { + "type": "boolean" + }, + "draft_message": { + "type": "boolean" + }, + "summarise_feedback": { + "type": "boolean" + }, + "improve_text": { + "type": "boolean" + } + }, + "required": [ + "draft_event", + "summarise_report", + "draft_message", + "summarise_feedback", + "improve_text" + ], + "additionalProperties": false, + "description": "Each helper switched on or off in Site settings → AI" + } + }, + "required": [ + "enabled", + "capReached", + "available", + "capCents", + "usedCents", + "usedPercent", + "renewsOn", + "helpers" + ], + "additionalProperties": false + }, + "settings": { + "type": "object", + "properties": { + "helpers": { + "type": "object", + "properties": { + "draft_event": { + "type": "boolean" + }, + "summarise_report": { + "type": "boolean" + }, + "draft_message": { + "type": "boolean" + }, + "summarise_feedback": { + "type": "boolean" + }, + "improve_text": { + "type": "boolean" + } + }, + "required": [ + "draft_event", + "summarise_report", + "draft_message", + "summarise_feedback", + "improve_text" + ], + "additionalProperties": false + }, + "dailyLimitPerPerson": { + "type": "integer", + "minimum": 0, + "maximum": 1000, + "description": "0 = no limit" + } + }, + "required": [ + "helpers", + "dailyLimitPerPerson" + ], + "additionalProperties": false + }, + "people": { + "type": "array", + "items": { + "type": "object", + "properties": { + "uses": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "chargedCents": { + "type": "number" + }, + "userId": { + "type": [ + "string", + "null" + ] + }, + "name": { + "type": "string" + } + }, + "required": [ + "uses", + "chargedCents", + "userId", + "name" + ], + "additionalProperties": false + } + }, + "helpers": { + "type": "array", + "items": { + "type": "object", + "properties": { + "uses": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "chargedCents": { + "type": "number" + }, + "helper": { + "type": "string" + } + }, + "required": [ + "uses", + "chargedCents", + "helper" + ], + "additionalProperties": false + } + }, + "days": { + "type": "array", + "items": { + "type": "object", + "properties": { + "uses": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "chargedCents": { + "type": "number" + }, + "day": { + "type": "string" + } + }, + "required": [ + "uses", + "chargedCents", + "day" + ], + "additionalProperties": false + } + } + }, + "required": [ + "status", + "settings", + "people", + "helpers", + "days" + ], + "additionalProperties": false + } + }, + "required": [ + "data" + ], + "additionalProperties": false + } + } + } + }, + "401": { + "description": "Not signed in (UNAUTHENTICATED)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Not allowed for this role (FORBIDDEN)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/ai/settings": { + "put": { + "tags": [ + "AI" + ], + "summary": "Switch helpers on or off, and set a daily limit", + "description": "**Who:** Admins only.", + "operationId": "putAiSettings", + "security": [ + { + "bearerAuth": [] + } + ], + "parameters": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "helpers": { + "type": "object", + "properties": { + "draft_event": { + "type": "boolean" + }, + "summarise_report": { + "type": "boolean" + }, + "draft_message": { + "type": "boolean" + }, + "summarise_feedback": { + "type": "boolean" + }, + "improve_text": { + "type": "boolean" + } + } + }, + "dailyLimitPerPerson": { + "type": "integer", + "minimum": 0, + "maximum": 1000 + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "helpers": { + "type": "object", + "properties": { + "draft_event": { + "type": "boolean" + }, + "summarise_report": { + "type": "boolean" + }, + "draft_message": { + "type": "boolean" + }, + "summarise_feedback": { + "type": "boolean" + }, + "improve_text": { + "type": "boolean" + } + }, + "required": [ + "draft_event", + "summarise_report", + "draft_message", + "summarise_feedback", + "improve_text" + ], + "additionalProperties": false + }, + "dailyLimitPerPerson": { + "type": "integer", + "minimum": 0, + "maximum": 1000, + "description": "0 = no limit" + } + }, + "required": [ + "helpers", + "dailyLimitPerPerson" + ], + "additionalProperties": false + } + }, + "required": [ + "data" + ], + "additionalProperties": false + } + } + } + }, + "400": { + "description": "Validation failed (VALIDATION_FAILED)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Not signed in (UNAUTHENTICATED)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Not allowed for this role (FORBIDDEN)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } } }, "components": { @@ -39973,6 +40518,7 @@ "CONFLICT", "RATE_LIMITED", "READ_ONLY", + "UNAVAILABLE", "INTERNAL" ] }, diff --git a/apps/events/frontend/src/lib/api-v2/schema.d.ts b/apps/events/frontend/src/lib/api-v2/schema.d.ts index d94cd79..b910625 100644 --- a/apps/events/frontend/src/lib/api-v2/schema.d.ts +++ b/apps/events/frontend/src/lib/api-v2/schema.d.ts @@ -6930,6 +6930,70 @@ export interface paths { patch?: never; trace?: never; }; + "/ai/status": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Whether to show the AI buttons + * @description Hidden when `enabled` is false; shown but disabled when `capReached` (until `renewsOn`, or until the allowance is raised). Cached for a minute; every AI call refreshes it. + * + * **Who:** Supervisors and admins. + */ + get: operations["getAiStatus"]; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/ai/usage": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * AI use this month + * @description For Site settings → AI: the allowance, this site's switches, and this month's use per person, per helper and per day. + * + * **Who:** Admins only. + */ + get: operations["getAiUsage"]; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/ai/settings": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + /** + * Switch helpers on or off, and set a daily limit + * @description **Who:** Admins only. + */ + put: operations["putAiSettings"]; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; } export type webhooks = Record; export interface components { @@ -6937,7 +7001,7 @@ export interface components { Error: { error: { /** @enum {string} */ - code: "VALIDATION_FAILED" | "UNAUTHENTICATED" | "FORBIDDEN" | "NOT_FOUND" | "CONFLICT" | "RATE_LIMITED" | "READ_ONLY" | "INTERNAL"; + code: "VALIDATION_FAILED" | "UNAUTHENTICATED" | "FORBIDDEN" | "NOT_FOUND" | "CONFLICT" | "RATE_LIMITED" | "READ_ONLY" | "UNAVAILABLE" | "INTERNAL"; message: string; /** @description Per-field problems (VALIDATION_FAILED only) */ fields?: { @@ -29721,4 +29785,229 @@ export interface operations { }; }; }; + getAiStatus: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description OK */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + data: { + /** @description false: hide the AI buttons (the licence has no AI, or the site isn't connected to the Hub) */ + enabled: boolean; + /** @description true: show the buttons disabled until `renewsOn` */ + capReached: boolean; + /** @description false: the Hub couldn't be reached just now */ + available: boolean; + /** @description The monthly allowance, in cents */ + capCents: number; + /** @description Used this month, in cents (fractions of a cent) */ + usedCents: number; + usedPercent: number; + /** @description YYYY-MM-DD */ + renewsOn: string | null; + /** @description Each helper switched on or off in Site settings → AI */ + helpers: { + draft_event: boolean; + summarise_report: boolean; + draft_message: boolean; + summarise_feedback: boolean; + improve_text: boolean; + }; + }; + }; + }; + }; + /** @description Not signed in (UNAUTHENTICATED) */ + 401: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["Error"]; + }; + }; + /** @description Not allowed for this role (FORBIDDEN) */ + 403: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["Error"]; + }; + }; + }; + }; + getAiUsage: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description OK */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + data: { + status: { + /** @description false: hide the AI buttons (the licence has no AI, or the site isn't connected to the Hub) */ + enabled: boolean; + /** @description true: show the buttons disabled until `renewsOn` */ + capReached: boolean; + /** @description false: the Hub couldn't be reached just now */ + available: boolean; + /** @description The monthly allowance, in cents */ + capCents: number; + /** @description Used this month, in cents (fractions of a cent) */ + usedCents: number; + usedPercent: number; + /** @description YYYY-MM-DD */ + renewsOn: string | null; + /** @description Each helper switched on or off in Site settings → AI */ + helpers: { + draft_event: boolean; + summarise_report: boolean; + draft_message: boolean; + summarise_feedback: boolean; + improve_text: boolean; + }; + }; + settings: { + helpers: { + draft_event: boolean; + summarise_report: boolean; + draft_message: boolean; + summarise_feedback: boolean; + improve_text: boolean; + }; + /** @description 0 = no limit */ + dailyLimitPerPerson: number; + }; + people: { + uses: number; + chargedCents: number; + userId: string | null; + name: string; + }[]; + helpers: { + uses: number; + chargedCents: number; + helper: string; + }[]; + days: { + uses: number; + chargedCents: number; + day: string; + }[]; + }; + }; + }; + }; + /** @description Not signed in (UNAUTHENTICATED) */ + 401: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["Error"]; + }; + }; + /** @description Not allowed for this role (FORBIDDEN) */ + 403: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["Error"]; + }; + }; + }; + }; + putAiSettings: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody: { + content: { + "application/json": { + helpers?: { + draft_event?: boolean; + summarise_report?: boolean; + draft_message?: boolean; + summarise_feedback?: boolean; + improve_text?: boolean; + }; + dailyLimitPerPerson?: number; + }; + }; + }; + responses: { + /** @description OK */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + data: { + helpers: { + draft_event: boolean; + summarise_report: boolean; + draft_message: boolean; + summarise_feedback: boolean; + improve_text: boolean; + }; + /** @description 0 = no limit */ + dailyLimitPerPerson: number; + }; + }; + }; + }; + /** @description Validation failed (VALIDATION_FAILED) */ + 400: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["Error"]; + }; + }; + /** @description Not signed in (UNAUTHENTICATED) */ + 401: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["Error"]; + }; + }; + /** @description Not allowed for this role (FORBIDDEN) */ + 403: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["Error"]; + }; + }; + }; + }; } diff --git a/apps/events/frontend/src/lib/commandPages.ts b/apps/events/frontend/src/lib/commandPages.ts index 6a29bfa..f3ae6ac 100644 --- a/apps/events/frontend/src/lib/commandPages.ts +++ b/apps/events/frontend/src/lib/commandPages.ts @@ -61,7 +61,7 @@ export const COMMAND_PAGES: CommandPage[] = [ ...([ ["organisation", "Organisation"], ["campuses", "Campuses"], ["branding", "Branding"], ["notifications", "Notifications"], ["email", "Email"], ["legal", "Legal"], ["whatsapp", "WhatsApp"], ["payments", "Payments"], ["webhooks", "Webhooks"], - ["backups", "Backups"], ["jobs", "Background jobs"], ["licence", "Licence & updates"], + ["backups", "Backups"], ["jobs", "Background jobs"], ["licence", "Licence & updates"], ["ai", "AI helpers"], ] as const).map(([tab, label]): CommandPage => ({ group: "Settings", label: `Settings: ${label}`, href: `/dashboard/admin/settings?tab=${tab}`, roles: ADM, keywords: "site settings" })), // Reports — every report in the catalogue ...REPORTS.map((r): CommandPage => ({ group: "Reports", label: `Report: ${r.label}`, href: `/dashboard/supervisor/reports?report=${r.key}`, roles: SUP, keywords: `report ${r.category} ${r.description}` })),