Qualifications

qualifications records who may do what. A qualification type, such as a forklift licence, a first aid course or an ISO certificate, says which holders it applies to (members, companies or assets), how many months a holding stays valid and whether it needs evidence. Requirements name who must hold it: a role, a team, a job title, an asset kind, a segment or one holder. The gap report lists the holders who lack a required qualification, or whose holding has expired or is about to.

better-supabase add qualifications

import { createQualifications } from "better-supabase/blocks/qualifications";

The module requires memberships, permissions and subjects. Company holders need contacts and asset holders assets. Team requirements need teams, job title requirements employees and segment requirements segments. With courses a type names a course and members earn it with the course's certificate, with attachments the evidence is a file, with notifications members hear about their expiring holdings, with outbox it records the events, and with audit every change is audited.

TablesCopy Anchor Link

Members read the types and requirements of their organizations and their own holdings. Everything else needs a permission:

Admins have all three; members get none by default.

Types and requirementsCopy Anchor Link

const forklift = await db.qualifications
  .saveType(organizationId, {
    key: "forklift",
    name: "Forklift licence",
    holderTypes: ["member"],
    validForMonths: 36,
    evidenceRequired: true,
  })
  .orThrow();

await db.qualifications
  .addRequirement(forklift.id, "role", "warehouse")
  .orThrow();

saveType creates the type or updates the one with the same key. validForMonths is between 1 and 240; leave it out for a qualification that never expires. archiveType stops a type from taking new holdings and from showing up in the gap report; its holdings stay. types lists them by name, with { includeArchived: true } for the archived ones too.

Adding the same target twice keeps one requirement. removeRequirement deletes one, and requirements(typeId) lists them.

HoldingsCopy Anchor Link

const held = await db.qualifications
  .grant(organizationId, {
    typeKey: "forklift",
    holderType: "member",
    holderId: userId,
    grantedOn: Temporal.PlainDate.from("2026-09-01"),
    evidenceAttachmentId: fileId,
  })
  .orThrow();
// held.expiresOn is 2029-09-01, held.status is "valid"

grantedOn defaults to today, and expiresOn is grantedOn plus the type's validForMonths. A type with evidenceRequired needs an evidenceAttachmentId or an evidenceNote. A holding's status is valid, expiring (inside the renewal window, 30 days by default), expired or revoked. revoke(qualificationId, reason) withdraws one, and revoking twice keeps the first revocation. of(holderType, holderId) returns every holding of one holder, the newest grant first.

A new grant of the same type doesn't replace the old one: the holder keeps both, and the latest expiry counts.

GapsCopy Anchor Link

const gaps = await db.qualifications
  .gaps(organizationId, { holderType: "member", status: "expiring" })
  .orThrow();
// [{ holderType, holderId, holderTitle, typeKey, typeName, status, expiresOn }]

gaps lists each holder a requirement applies to whose holding is missing, expired or expiring. Filter it by holderType (default member), holderId, teamId (with teams), typeKey or status. It needs qualifications.read, except that a member may read their own gaps by passing their user id as holderId.

Qualified holdersCopy Anchor Link

const drivers = await db.qualifications
  .qualifiedHolders(organizationId, "forklift", {
    on: Temporal.PlainDate.from("2026-12-14"),
  })
  .orThrow();
// ["9f0c…", "b31e…"]

qualifiedHolders returns the ids of the holders with a valid holding of a type on a day (today by default), so a schedule can check who may work a shift. Every member of the organization may call it.

ExpiryCopy Anchor Link

Run notifyExpiring daily with the service role, for example from a job. It records qualification.expiry_warned once when a holding enters the renewal window and qualification.expired once when it expires, skipping holdings that a newer one of the same type replaces. With notifications installed, a member holder gets a notification for each. Set the window with options.renewalWindowDays:

blocks: {
  qualifications: { options: { renewalWindowDays: 60 } },
},

From a courseCopy Anchor Link

With courses installed and owning its certificates table, a type that names a courseId is granted to a member when they earn the course's certificate, with source: "course". It expires with the type's validity, or with the certificate when the type has none. Revoking the certificate revokes the holding.

OptionsCopy Anchor Link

Pass a Standard Schema as fields to type the extra columns, parse them on reads and validate them on grant:

const qualifications = createQualifications({
  transport,
  fields: z.object({ licence_number: z.string().optional() }),
});

Adopting tablesCopy Anchor Link

An app with its own tables keeps them: the module runs over them and maps their columns. The type's description and course columns, the holding's revokeReason, evidenceNote and grantedBy columns, and the timestamps are optional; map them to null and the module leaves out what needs them.

blocks: {
  qualifications: {
    tables: {
      types: "public.certifications",
      requirements: "public.certification_rules",
      qualifications: "public.certificates_held",
    },
    columns: {
      types: { name: "title", course: null },
      qualifications: { expiresOn: "valid_until", evidenceNote: null },
    },
  },
},

EventsCopy Anchor Link

HooksCopy Anchor Link

before_qualification_type_save, after_qualification_type_save, before_qualification_grant, after_qualification_grant, before_qualification_revoke and after_qualification_revoke run in the same transaction as the change. See extending blocks.

ErrorsCopy Anchor Link

Without the clientCopy Anchor Link

db.qualifications is this client. Code that does not go through bsb.db() builds it with a transport:

import { createQualifications } from "better-supabase/blocks/qualifications";

const qualifications = createQualifications({ transport });
const gaps = await qualifications.gaps(organizationId).orThrow();