Audits and inspections

inspections plans and runs audits and inspections. A programme lists the inspections of a period, each inspection has a lead, a team and a checklist form, its findings record what the team saw, and a nonconformity gets a case before the inspection closes.

better-supabase add inspections

import { createInspections } from "better-supabase/blocks/inspections";

The module requires tenant, permissions, subjects and forms, which holds the checklist. With cases a finding opens a case. With compliance a finding names the control it concerns, and with relations the inspection assesses that control. With numbering the number comes from an inspection sequence (AUD-{yyyy}-{n:3}); without it the number is AUD- and the inspection's position in the organization. With calendar and options.calendar planned inspections appear in a calendar, and with notifications the team hears about assignments and overdue inspections. With outbox it records the events, and with audit every change is audited.

TablesCopy Anchor Link

Members with inspections.read read every table. Everyone else reads only the inspections they are on the team of, with their team and findings. Writes go through the functions below. Inspections and findings are subjects of type inspection and inspection_finding, so comments, attachments, tags and the other subject blocks work on them.

A team role decides what a member with inspections.write may do:

inspections.manage acts as a lead on every inspection.

ProgrammesCopy Anchor Link

saveProgram creates a programme or, with programId, changes one; it needs inspections.manage. A programme goes from draft to approved with approveProgram and to closed with closeProgram.

const program = await db.inspections
  .saveProgram({
    name: "Audit programme 2026",
    periodStart: Temporal.PlainDate.from("2026-01-01"),
    periodEnd: Temporal.PlainDate.from("2026-12-31"),
  })
  .orThrow();

await db.inspections.approveProgram(program.id).orThrow();

Running an inspectionCopy Anchor Link

schedule creates a planned inspection. The kind must be one of options.kinds, and the auditee is any subject, such as a supplier or a site.

const audit = await db.inspections
  .schedule({
    kind: "supplier_audit",
    title: "Acme Metals annual audit",
    programId: program.id,
    auditee: { type: "contact", id: supplierId },
    leadId,
    plannedStart: Temporal.PlainDate.from("2026-03-10"),
    checklistFormId,
    members: [{ userId: auditorId, role: "auditor" }],
  })
  .orThrow();
// audit.number is "AUD-2026-001"

The inspection then moves through these statuses:

saveChecklist saves the answers to the checklist form, and { draft: false } submits them. complete fails with INSPECTION_CHECKLIST_INCOMPLETE until the checklist is submitted.

Findings and casesCopy Anchor Link

Findings are recorded while the inspection is in progress or reporting. The type must be one of options.findingTypes.

const finding = await db.inspections
  .addFinding(audit.id, {
    type: "major_nonconformity",
    title: "Unlabelled stock",
    clause: "ISO 9001 7.5.3",
    controlId,
  })
  .orThrow();
// finding.needsCase is true

await db.inspections.raiseCase(finding.id).orThrow();
await db.inspections.close(audit.id).orThrow();

A finding of a type in options.caseFindingTypes needs a case, and close fails with INSPECTION_FINDINGS_OPEN until each such finding has one. raiseCase opens a case of the kind finding, or of the kind it is given, titled AUD-2026-001: Unlabelled stock, with the source inspection when the cases block's options.sources lists it and internal otherwise, and links the case to the finding as created_from. A finding with a case can't be deleted.

Calendar, files and notificationsCopy Anchor Link

An inspection is a subject of type inspection, so attachments, comments and tags attach to it like to any record. A finding and a programme are subjects too.

Name a calendar in options.calendar to mirror inspections. Each inspection that is planned or running and has a plannedStart gets one all-day event in that calendar, from plannedStart to plannedEnd, with the uid inspection-<id> and the inspection as its subject. The event follows the dates and title, and goes away when the inspection closes, is canceled or loses its dates. An organization without a calendar of that name gets no events.

With notifications, a user added to the team of a planned or running inspection gets an inspection.assigned notification, once per user. The overdue schedule runs notifyOverdue() daily: the lead (or the auditors, without a lead) gets an inspection.overdue notification once per planned end for each planned or running inspection past it.

MethodsCopy Anchor Link

list filters by programId, kind, status, leadId, from, to, auditee and search, with limit and offset.

OptionsCopy Anchor Link

ErrorsCopy Anchor Link

EventsCopy Anchor Link

inspection_program.created, inspection_program.updated, inspection_program.approved, inspection_program.closed, inspection.scheduled, inspection.updated, inspection.started, inspection.completed, inspection.closed, inspection.cancelled, inspection_finding.created, inspection_finding.updated, inspection_finding.deleted and inspection_finding.case_raised. The events page lists their payloads.

Without the clientCopy Anchor Link

db.inspections is this client. Code that does not go through bsb.db() builds it with a transport and an organization id:

const inspections = createInspections({ transport, tenant: organizationId });

const audits = await inspections.list({ status: "in_progress" }).orThrow();