Pipelines

pipelines puts any record your app registers in config.subjects on a pipeline the organization edits: deals, quotes, job applications, tickets, tasks. Each organization can keep several pipelines per record type, each with its own stages, and every stage has a category your config declares. A category maps to one of three fixed outcomes, open, success or failure, so reports and policies read the outcome and never a stage name.

The module writes a history row every time a record changes stage, keeps the time it entered its current stage, totals each board column per currency, and can set a status column from the stage category, so won on a deal still runs through the state machine.

Reading pipelines and boards needs pipelines.read, and creating, renaming, reordering or archiving pipelines and stages needs pipelines.manage. Admins get both and members get pipelines.read. Moving a record is an update of its own table, so your table's policies decide who may move it.

better-supabase sql add pipelines

The module needs tenant, access and subjects.

Bind a record typeCopy Anchor Link

Register the record in config.subjects, add a stage_id and a pipeline_id column (both uuid) to its table, and bind it in the module's options. categories is required: it names the categories stages of this type can have and maps each to an outcome. stages is the template the first pipeline of an organization starts with.

subjects: {
  deal: {
    table: "public.deals",
    idType: "uuid",
    rank: { column: "rank", group: "stage_id" },
  },
},
sql: {
  modules: {
    pipelines: {
      options: {
        subjects: {
          deal: {
            categories: { open: "open", won: "success", lost: "failure" },
            enteredAt: "stage_entered_at",
            amount: "amount",
            currency: "currency",
            probability: "probability",
            owner: "owner_id",
            status: { column: "outcome", values: { open: "open", won: "won", lost: "lost" } },
            stages: [
              { key: "qualified", name: "Qualified", category: "open", probability: 20 },
              { key: "proposal", name: "Proposal", category: "open", probability: 55 },
              { key: "won", name: "Closed won", category: "won", probability: 100 },
              { key: "lost", name: "Closed lost", category: "lost", probability: 0 },
            ],
          },
        },
      },
    },
  },
},

An insert without a pipeline lands in the organization's default pipeline for the type and scope, created from stages the first time. An insert without a stage lands in the first open stage. The first pipeline an admin creates for a type and scope becomes its default.

Manage pipelines and stagesCopy Anchor Link

import { createPipelines } from "better-supabase/blocks/pipelines";

const pipelines = createPipelines({ transport });
const renewals = await pipelines
  .save(organizationId, {
    subjectType: "deal",
    key: "renewals",
    name: "Renewals",
  })
  .orThrow();
await pipelines
  .saveStage(renewals.id, {
    key: "due",
    name: "Renewal due",
    category: "open",
    probability: 70,
    rottingAfterDays: 14,
    wipLimit: 25,
  })
  .orThrow();
const [deals] = await pipelines.list(organizationId, "deal").orThrow();

saveStage adds a stage at the end, or changes one when you pass its id. Its category must be one the type declares (PIPELINE_CATEGORY_UNKNOWN), and a stage that holds records keeps its outcome (PIPELINE_STAGE_IN_USE), so a won stage never turns open under its deals. reorderStage(stageId, { previous, next }) moves a stage between two rank keys. archiveStage and archive refuse a stage or pipeline that still holds records, and a pipeline keeps at least one open stage (PIPELINE_LAST_OPEN_STAGE).

Without transitions, a record moves from any stage to any other. setTransitions(pipelineId, [{ from, to }]) limits the moves to the pairs you list, and an empty list allows every move again (PIPELINE_TRANSITION_INVALID for any other move).

Move recordsCopy Anchor Link

A record changes stage when its stage column changes. An update from your app, a bulk action or a board drag all go through the same trigger, which refuses a stage of another pipeline, an archived stage, or a stage of another organization (PIPELINE_STAGE_INVALID), checks the transitions, closes the previous history row and opens a new one.

On a board, move the card with rank and the stage id as the group, so the rank key and the stage change in one update:

import { createRank } from "better-supabase/blocks/rank";

const rank = createRank({ transport });
await rank
  .move("deal", dealId, {
    previous: aboveId,
    next: belowId,
    group: proposalStageId,
  })
  .orThrow();

With status set, a stage in a mapped category also writes the status column in a separate update, so a state machine on that column checks the change and records status.changed. Moving a deal to Closed won sets outcome to won, and moving it back to an open stage sets open again.

Board, stats and healthCopy Anchor Link

const columns = await pipelines
  .board("deal", pipelineId, { owner: userId })
  .orThrow();
// [{ stageId, name, outcome, count, overLimit, totals: [{ currency, amount, weighted }] }]

const stats = await pipelines
  .stats(pipelineId, { since: quarterStart, until: quarterEnd })
  .orThrow();
// { won, lost, winRate, stages: [{ stageId, entered, averageSeconds }] }

const stuck = (await pipelines.health(pipelineId).orThrow()).filter(
  (row) => row.rotting,
);

board returns every active stage in order with the number of records the caller can see and, per currency, the total amount and the amount weighted by probability (the record's own, else the stage's). Amounts are bigint minor units, and currencies are never added together. overLimit is true when a stage holds more records than its WIP limit. All three reads run as the caller, so the record table's policies decide what they count.

stats reads the stage history in a time window: how many records entered each stage, how long the ones that left stayed on average, and the win rate (records that entered a success stage over those that entered a success or failure stage). health lists the open records with the time they entered their stage, their days in stage and whether they sit longer than the stage's rottingAfterDays.

WatchingCopy Anchor Link

With the notifications module installed, the owner column's user watches the record at the participating level when the record is created or reassigned, and a level the user already chose stays. Every stage change notifies the record's watchers with a pipeline.stage_changed notification. Anyone else watches a record with the notifications client's subscribe({ subject: { type: "deal", id } }).

EventsCopy Anchor Link

pipeline.stage_changed carries the record as its subject, so the activity feed shows it on the record's timeline. Pipeline and stage changes are written to the audit log as configuration changes.

HooksCopy Anchor Link

The module calls before_pipeline_save, after_pipeline_save, before_pipeline_stage_save and after_pipeline_stage_save around admin changes, and before_pipeline_stage_change(subject_type text, subject_id text, from_stage uuid, to_stage uuid) and after_pipeline_stage_change(subject_type text, subject_id text, to_stage uuid) inside the trigger. A before_ hook raises to refuse the move. The TypeScript client takes hooks for its methods (see extending blocks).

Wire it to ReUICopy Anchor Link

The ReUI Kanban commits a finished drag through onValueCommit(value, meta). Call rank.move with the card's new neighbours in meta.overContainer and the column's stage id as the group, and restore meta.previousValue when the result is an error. Read the column headers from board, and the count and totals of each column from its entry.

ErrorsCopy Anchor Link