@prenta/admin 0.92.0

package/src/lib/forms-service.ts

@@ -0,0 +1,569 @@
+/**
+ * Forms service — typed client over the cms-core Forms REST endpoints.
+ *
+ * Every Forms admin component reads/writes through this module (never raw
+ * `cmsApi` / `fetch`), so the network contract lives in one place. Read
+ * fetchers re-surface `cmsApi`'s `{ error }` as a thrown error (so the
+ * resource hook can show error/retry UI); mutations return `{ error? }`.
+ *
+ * The endpoint paths here are the contract implemented by cms-core
+ * `packages/cms-core/src/api/handlers.ts` (PR 2). Domain types are re-used
+ * from `@prenta/core` so the admin can never drift from the server.
+ */
+import { cmsApi, getApiBase } from './api.js'
+import type {
+  FormDefinition,
+  FormSchemaVersion,
+  FormField,
+  FormAnalyticsConfig,
+  FormNotificationSettings,
+  FormEmbedSettings,
+  FormWebhookConfig,
+  FormWebhookEvent,
+  FormStatus,
+  FormStats,
+  FormsSidebarCount,
+  FetchFormsParams,
+  FormSubmission,
+  FetchFormEntriesParams,
+  EntryCounts,
+} from '@prenta/core'
+
+export type {
+  FormDefinition,
+  FormSchemaVersion,
+  FormField,
+  FormFieldType,
+  FormFieldOption,
+  FieldValidationRules,
+  FormAnalyticsConfig,
+  FormNotificationSettings,
+  FormEmbedSettings,
+  FormWebhookConfig,
+  FormWebhookEvent,
+  FormStatus,
+  FormStats,
+  FormsSidebarCount,
+  FormSubmission,
+  FormSubmissionFile,
+  FetchFormEntriesParams,
+  EntryCounts,
+  SpamStatus,
+} from '@prenta/core'
+
+/**
+ * `cmsApi` never throws — it returns `{ error, status }` on a network/HTTP
+ * failure. Read (GET) fetchers must re-surface that as a thrown error so the
+ * resource hook can distinguish "request failed" from "empty result".
+ */
+function throwIfError(res: { error?: string }): void {
+  if (res.error) throw new Error(res.error)
+}
+
+/**
+ * A form as returned by `GET /forms` — the typed definition plus the legacy
+ * numeric aliases the list endpoint adds for backward compatibility.
+ */
+export interface FormListItem extends FormDefinition {
+  /** `fields.length` precomputed by the server. */
+  fieldCount?: number
+  /** Alias of `totalEntries`. */
+  submissions?: number
+}
+
+export interface FormSchemaResult {
+  fields: FormField[]
+  activeVersionId: string | null
+  versions: FormSchemaVersion[]
+}
+
+// ─── Forms list / stats / sidebar ────────────────────────────────────────
+
+function buildFormsQuery(params: FetchFormsParams): string {
+  const qs = new URLSearchParams()
+  if (params.search) qs.set('search', params.search)
+  if (params.status) qs.set('status', params.status)
+  if (typeof params.notifyEnabled === 'boolean') {
+    qs.set('notifyEnabled', String(params.notifyEnabled))
+  }
+  if (params.sortBy) qs.set('sortBy', params.sortBy)
+  if (params.sortDirection) qs.set('sortDirection', params.sortDirection)
+  if (params.page) qs.set('page', String(params.page))
+  if (params.pageSize) qs.set('pageSize', String(params.pageSize))
+  const str = qs.toString()
+  return str ? `?${str}` : ''
+}
+
+export async function fetchForms(params: FetchFormsParams = {}): Promise<FormListItem[]> {
+  const res = await cmsApi<FormListItem[]>(`/forms${buildFormsQuery(params)}`)
+  throwIfError(res)
+  return res.data ?? []
+}
+
+export async function fetchFormById(id: string): Promise<FormDefinition | null> {
+  const res = await cmsApi<FormDefinition>(`/forms/${encodeURIComponent(id)}`)
+  throwIfError(res)
+  return res.data ?? null
+}
+
+const EMPTY_STATS: FormStats = {
+  totalForms: 0,
+  activeForms: 0,
+  totalEntries: 0,
+  unreadEntries: 0,
+}
+
+export async function fetchFormStats(): Promise<FormStats> {
+  const res = await cmsApi<FormStats>('/forms/stats')
+  throwIfError(res)
+  return res.data ?? EMPTY_STATS
+}
+
+export async function fetchFormsSidebarCounts(): Promise<FormsSidebarCount[]> {
+  const res = await cmsApi<FormsSidebarCount[]>('/forms/sidebar-counts')
+  throwIfError(res)
+  return res.data ?? []
+}
+
+// ─── Form mutations ──────────────────────────────────────────────────────
+
+export interface CreateFormPayload {
+  name: string
+  slug?: string
+  description?: string
+  status?: FormStatus
+  template?: string
+  fields?: FormField[]
+  successMessage?: string
+  redirectUrl?: string
+  analytics?: FormAnalyticsConfig
+}
+
+export async function createForm(
+  payload: CreateFormPayload,
+): Promise<{ data?: FormDefinition; error?: string }> {
+  const res = await cmsApi<FormDefinition>('/forms', {
+    method: 'POST',
+    body: JSON.stringify(payload),
+  })
+  return { data: res.data, error: res.error }
+}
+
+/** Patch shape accepted by `PATCH /forms/:id` (cms-core `UpdateFormInput`). */
+export interface UpdateFormPayload {
+  name?: string
+  description?: string
+  status?: FormStatus
+  successMessage?: string
+  redirectUrl?: string
+  analytics?: FormAnalyticsConfig
+}
+
+export async function updateForm(
+  id: string,
+  payload: UpdateFormPayload,
+): Promise<{ data?: FormDefinition; error?: string }> {
+  const res = await cmsApi<FormDefinition>(`/forms/${encodeURIComponent(id)}`, {
+    method: 'PATCH',
+    body: JSON.stringify(payload),
+  })
+  return { data: res.data, error: res.error }
+}
+
+export async function duplicateForm(
+  id: string,
+): Promise<{ data?: FormDefinition; error?: string }> {
+  const res = await cmsApi<FormDefinition>(`/forms/${encodeURIComponent(id)}/duplicate`, {
+    method: 'POST',
+  })
+  return { data: res.data, error: res.error }
+}
+
+/** Move a form to the archived state (hidden from embed pickers, no new submissions). */
+export async function archiveForm(id: string): Promise<{ error?: string }> {
+  return updateForm(id, { status: 'archived' })
+}
+
+/** Restore an archived form back to draft. */
+export async function restoreForm(id: string): Promise<{ error?: string }> {
+  return updateForm(id, { status: 'draft' })
+}
+
+export async function deleteForm(
+  id: string,
+  opts: { force?: boolean } = {},
+): Promise<{ error?: string }> {
+  const qs = opts.force ? '?force=true' : ''
+  const res = await cmsApi(`/forms/${encodeURIComponent(id)}${qs}`, { method: 'DELETE' })
+  return { error: res.error }
+}
+
+// ─── Schema ──────────────────────────────────────────────────────────────
+
+export async function fetchFormSchema(id: string): Promise<FormSchemaResult> {
+  const res = await cmsApi<FormSchemaResult>(`/forms/${encodeURIComponent(id)}/schema`)
+  throwIfError(res)
+  return res.data ?? { fields: [], activeVersionId: null, versions: [] }
+}
+
+export async function saveFormSchema(
+  id: string,
+  fields: FormField[],
+  notes?: string,
+): Promise<{ data?: { form: FormDefinition; version: FormSchemaVersion }; error?: string }> {
+  const res = await cmsApi<{ form: FormDefinition; version: FormSchemaVersion }>(
+    `/forms/${encodeURIComponent(id)}/schema`,
+    { method: 'PUT', body: JSON.stringify({ fields, notes }) },
+  )
+  return { data: res.data, error: res.error }
+}
+
+// ─── Notifications ─────────────────────────────────────────────────────────
+
+export async function fetchNotificationSettings(id: string): Promise<FormNotificationSettings> {
+  const res = await cmsApi<FormNotificationSettings>(
+    `/forms/${encodeURIComponent(id)}/notifications`,
+  )
+  throwIfError(res)
+  return res.data ?? { enabled: false, recipients: [] }
+}
+
+export async function updateNotificationSettings(
+  id: string,
+  payload: Partial<FormNotificationSettings>,
+): Promise<{ data?: FormNotificationSettings; error?: string }> {
+  const res = await cmsApi<FormNotificationSettings>(
+    `/forms/${encodeURIComponent(id)}/notifications`,
+    { method: 'PUT', body: JSON.stringify(payload) },
+  )
+  return { data: res.data, error: res.error }
+}
+
+/** Lightweight notify on/off toggle used by the forms-list switch. */
+export async function setNotifyEnabled(
+  id: string,
+  enabled: boolean,
+): Promise<{ data?: { notifyEnabled: boolean }; error?: string }> {
+  const res = await cmsApi<{ notifyEnabled: boolean }>(`/forms/${encodeURIComponent(id)}/notify`, {
+    method: 'PUT',
+    body: JSON.stringify({ enabled }),
+  })
+  return { data: res.data, error: res.error }
+}
+
+/** Send a sample notification email to the first configured recipient. */
+export async function testNotificationSettings(id: string): Promise<{
+  data?: { notified: number; autoresponded: boolean; skippedReason?: string }
+  error?: string
+}> {
+  const res = await cmsApi<{ notified: number; autoresponded: boolean; skippedReason?: string }>(
+    `/forms/${encodeURIComponent(id)}/notifications/test`,
+    { method: 'POST', body: '{}' },
+  )
+  return { data: res.data, error: res.error }
+}
+
+// ─── Embed ───────────────────────────────────────────────────────────────
+
+export async function fetchEmbedSettings(id: string): Promise<FormEmbedSettings> {
+  const res = await cmsApi<FormEmbedSettings>(`/forms/${encodeURIComponent(id)}/embed`)
+  throwIfError(res)
+  return res.data ?? {}
+}
+
+export async function updateEmbedSettings(
+  id: string,
+  payload: Partial<FormEmbedSettings>,
+): Promise<{ data?: FormEmbedSettings; error?: string }> {
+  const res = await cmsApi<FormEmbedSettings>(`/forms/${encodeURIComponent(id)}/embed`, {
+    method: 'PUT',
+    body: JSON.stringify(payload),
+  })
+  return { data: res.data, error: res.error }
+}
+
+// ─── Webhooks (CRM / Zapier) ───────────────────────────────────────────────
+
+export interface WebhookTestResult {
+  ok: boolean
+  status: number
+  attempts: number
+  error?: string
+}
+
+export interface CreateFormWebhookPayload {
+  url: string
+  events?: FormWebhookEvent[]
+  enabled?: boolean
+  retryCount?: number
+}
+
+export interface UpdateFormWebhookPayload {
+  url?: string
+  events?: FormWebhookEvent[]
+  enabled?: boolean
+  retryCount?: number
+}
+
+/** Plaintext secret is returned only on create — store it before closing the dialog. */
+export type CreatedFormWebhook = FormWebhookConfig & { secret: string }
+
+export async function fetchFormWebhooks(formId: string): Promise<FormWebhookConfig[]> {
+  const res = await cmsApi<FormWebhookConfig[]>(`/forms/${encodeURIComponent(formId)}/webhooks`)
+  throwIfError(res)
+  return res.data ?? []
+}
+
+export async function createFormWebhook(
+  formId: string,
+  payload: CreateFormWebhookPayload,
+): Promise<{ data?: CreatedFormWebhook; error?: string }> {
+  const res = await cmsApi<CreatedFormWebhook>(`/forms/${encodeURIComponent(formId)}/webhooks`, {
+    method: 'POST',
+    body: JSON.stringify(payload),
+  })
+  return { data: res.data, error: res.error }
+}
+
+export async function updateFormWebhook(
+  formId: string,
+  webhookId: string,
+  payload: UpdateFormWebhookPayload,
+): Promise<{ data?: FormWebhookConfig; error?: string }> {
+  const res = await cmsApi<FormWebhookConfig>(
+    `/forms/${encodeURIComponent(formId)}/webhooks/${encodeURIComponent(webhookId)}`,
+    { method: 'PATCH', body: JSON.stringify(payload) },
+  )
+  return { data: res.data, error: res.error }
+}
+
+export async function deleteFormWebhook(
+  formId: string,
+  webhookId: string,
+): Promise<{ error?: string }> {
+  const res = await cmsApi(
+    `/forms/${encodeURIComponent(formId)}/webhooks/${encodeURIComponent(webhookId)}`,
+    { method: 'DELETE' },
+  )
+  return { error: res.error }
+}
+
+export async function testFormWebhook(
+  formId: string,
+  webhookId: string,
+): Promise<{ data?: WebhookTestResult; error?: string }> {
+  const res = await cmsApi<WebhookTestResult>(
+    `/forms/${encodeURIComponent(formId)}/webhooks/${encodeURIComponent(webhookId)}/test`,
+    { method: 'POST' },
+  )
+  return { data: res.data, error: res.error }
+}
+
+// ─── Entries (submissions) ─────────────────────────────────────────────────
+
+/** A page of submissions as returned by `GET /forms/entries`. */
+export interface EntriesPage {
+  entries: FormSubmission[]
+  total: number
+  page: number
+  pageSize: number
+}
+
+/** Patch shape accepted by the entry mutation endpoints. */
+export interface EntryPatch {
+  unread?: boolean
+  starred?: boolean
+  archived?: boolean
+}
+
+function buildEntriesQuery(params: FetchFormEntriesParams): string {
+  const qs = new URLSearchParams()
+  if (params.search) qs.set('search', params.search)
+  if (params.formId) qs.set('formId', params.formId)
+  if (typeof params.unread === 'boolean') qs.set('unread', String(params.unread))
+  if (typeof params.starred === 'boolean') qs.set('starred', String(params.starred))
+  if (typeof params.archived === 'boolean') qs.set('archived', String(params.archived))
+  if (params.spamStatus) qs.set('spamStatus', params.spamStatus)
+  if (params.dateFrom) qs.set('dateFrom', params.dateFrom)
+  if (params.dateTo) qs.set('dateTo', params.dateTo)
+  if (params.thisWeek) qs.set('thisWeek', 'true')
+  if (params.sortBy) qs.set('sortBy', params.sortBy)
+  if (params.sortDirection) qs.set('sortDirection', params.sortDirection)
+  if (params.page) qs.set('page', String(params.page))
+  if (params.pageSize) qs.set('pageSize', String(params.pageSize))
+  const str = qs.toString()
+  return str ? `?${str}` : ''
+}
+
+const EMPTY_PAGE: EntriesPage = { entries: [], total: 0, page: 1, pageSize: 25 }
+
+export async function fetchEntries(params: FetchFormEntriesParams = {}): Promise<EntriesPage> {
+  const res = await cmsApi<EntriesPage>(`/forms/entries${buildEntriesQuery(params)}`)
+  throwIfError(res)
+  return res.data ?? EMPTY_PAGE
+}
+
+const EMPTY_COUNTS: EntryCounts = { total: 0, unread: 0, starred: 0, thisWeek: 0, byForm: {} }
+
+export async function fetchEntryCounts(params: FetchFormEntriesParams = {}): Promise<EntryCounts> {
+  const res = await cmsApi<EntryCounts>(`/forms/entries/counts${buildEntriesQuery(params)}`)
+  throwIfError(res)
+  return res.data ?? EMPTY_COUNTS
+}
+
+/** A single entry rendered against the schema version it was captured with. */
+export interface EntryDetail {
+  entry: FormSubmission
+  fields: FormField[]
+}
+
+export async function fetchEntry(id: string): Promise<EntryDetail | null> {
+  const res = await cmsApi<EntryDetail>(`/forms/entries/${encodeURIComponent(id)}`)
+  throwIfError(res)
+  return res.data ?? null
+}
+
+export async function updateEntry(
+  id: string,
+  patch: EntryPatch,
+): Promise<{ data?: FormSubmission; error?: string }> {
+  const res = await cmsApi<FormSubmission>(`/forms/entries/${encodeURIComponent(id)}`, {
+    method: 'PATCH',
+    body: JSON.stringify(patch),
+  })
+  return { data: res.data, error: res.error }
+}
+
+export async function deleteEntry(id: string): Promise<{ error?: string }> {
+  const res = await cmsApi(`/forms/entries/${encodeURIComponent(id)}`, { method: 'DELETE' })
+  return { error: res.error }
+}
+
+export async function bulkUpdateEntries(
+  ids: string[],
+  patch: EntryPatch,
+): Promise<{ data?: { updated: number }; error?: string }> {
+  const res = await cmsApi<{ updated: number }>('/forms/entries/bulk', {
+    method: 'POST',
+    body: JSON.stringify({ ids, patch }),
+  })
+  return { data: res.data, error: res.error }
+}
+
+export type EntriesExportFormat = 'csv' | 'xlsx'
+
+/**
+ * Download the full server-side entries export (all pages, decrypted values,
+ * attribution columns — bounded server-side to 5,000 rows). Scoped to one
+ * form when `formId` is set, otherwise exports across all forms. Uses raw
+ * `fetch` because the response is a file, not the JSON envelope `cmsApi`
+ * unwraps.
+ */
+export async function downloadEntriesExport(
+  options: {
+    formId?: string
+    format?: EntriesExportFormat
+  } = {},
+): Promise<{ error?: string }> {
+  const format: EntriesExportFormat = options.format ?? 'csv'
+  const qs = new URLSearchParams({ format })
+  if (options.formId) qs.set('formId', options.formId)
+
+  let res: Response
+  try {
+    res = await fetch(`${getApiBase()}/forms/entries/export?${qs.toString()}`, {
+      credentials: 'include',
+    })
+  } catch (err) {
+    return { error: err instanceof Error ? err.message : 'Network error' }
+  }
+  if (!res.ok) {
+    const body = (await res.json().catch(() => ({}))) as { error?: string }
+    return { error: body.error || `Export failed (${res.status})` }
+  }
+
+  const blob = await res.blob()
+  const disposition = res.headers.get('content-disposition') ?? ''
+  const filename = /filename="([^"]+)"/.exec(disposition)?.[1] ?? `entries.${format}`
+  const url = URL.createObjectURL(blob)
+  const a = document.createElement('a')
+  a.href = url
+  a.download = filename
+  a.click()
+  URL.revokeObjectURL(url)
+  return {}
+}
+
+// ─── Delivery attempts (#675) ─────────────────────────────────────────────
+
+export type FormDeliveryChannel = 'email_notify' | 'email_autoresponder' | 'form_webhook'
+export type FormDeliveryStatus = 'pending' | 'retrying' | 'success' | 'failed' | 'skipped'
+
+export interface FormDeliveryAttempt {
+  id: string
+  submissionId: string
+  formId: string
+  channel: FormDeliveryChannel
+  destination: string
+  webhookId: string | null
+  status: FormDeliveryStatus
+  attempts: number
+  maxAttempts: number
+  lastAttemptAt: string | null
+  nextRetryAt: string | null
+  error: string | null
+  responseStatus: number | null
+  skippedReason: string | null
+  alertedAt: string | null
+  createdAt: string
+  updatedAt: string
+  entryNumber?: number | null
+  formName?: string | null
+}
+
+export interface FormDeliveriesPage {
+  docs: FormDeliveryAttempt[]
+  total: number
+  page: number
+  pageSize: number
+}
+
+export interface FetchFormDeliveriesParams {
+  formId?: string
+  submissionId?: string
+  status?: string
+  page?: number
+  pageSize?: number
+}
+
+export async function fetchFormDeliveries(
+  params: FetchFormDeliveriesParams = {},
+): Promise<FormDeliveriesPage> {
+  const qs = new URLSearchParams()
+  if (params.formId) qs.set('formId', params.formId)
+  if (params.submissionId) qs.set('submissionId', params.submissionId)
+  if (params.status) qs.set('status', params.status)
+  if (params.page) qs.set('page', String(params.page))
+  if (params.pageSize) qs.set('pageSize', String(params.pageSize))
+  const suffix = qs.toString() ? `?${qs.toString()}` : ''
+  const res = await cmsApi<FormDeliveriesPage>(`/forms/deliveries${suffix}`)
+  throwIfError(res)
+  return res.data ?? { docs: [], total: 0, page: 1, pageSize: 25 }
+}
+
+export async function retryFormDelivery(
+  attemptId: string,
+): Promise<{ data?: FormDeliveryAttempt; error?: string }> {
+  const res = await cmsApi<FormDeliveryAttempt>(
+    `/forms/deliveries/${encodeURIComponent(attemptId)}/retry`,
+    { method: 'POST' },
+  )
+  return { data: res.data, error: res.error }
+}
+
+export async function fetchFailedDeliveryCount(formId?: string): Promise<number> {
+  const qs = formId ? `?formId=${encodeURIComponent(formId)}` : ''
+  const res = await cmsApi<{ count: number }>(`/forms/deliveries/failed-count${qs}`)
+  throwIfError(res)
+  return res.data?.count ?? 0
+}