Program Metrics

The area-program summary of the active project: total target versus allocated area, plus a per-department breakdown. This is the program-mode "am I hitting my area targets?" read — per-entity geometry measurements (a single space's area, volume, bounding box) live under the geometry namespaces, not here. Accessed via snaptrude.program.metrics.

This namespace is read-only and never throws: when the project has no program, get returns an empty breakdown with zero totals. It is a host API call that returns a Promise. It complements snaptrude.program.areas (the FAR / built-up-area lens); department targets are set through snaptrude.program.departments.setTargetArea.

At a glance

Method	What it does	Mutates?
get()	Get the area-program summary — totals plus per-department breakdown	—

Area-units convention

Every area in the summary is reported in its units field ("ft2" or "m2"). This convention applies to every area-returning method in the plugin API: a result carries exactly one units field, at the top level of the value the method returns — on the response envelope for list/multi/composite results, and on the record itself only for a single .get that returns a bare record. Inner/leaf records never repeat it.

Types

PluginAreaUnit

The unit areas are reported in.

Value	Description
"ft2"	Square feet
"m2"	Square metres

PluginProgramDepartmentMetric

Per-department area figures within the program summary. Areas are in the enclosing PluginProgramMetricsSummary's units.

Property	Type	Description
departmentId	string	Department id
name	string	Department name
targetArea	number | null	Target area in project units, or null if no target is set
allocatedArea	number	Area currently allocated to this department, in project units

PluginProgramMetricsSummary

Result of get. Every area is in units.

Reconciliation invariant: totalAllocatedArea equals unassignedArea plus the sum of every departments[].allocatedArea (within a small float tolerance). totalTargetArea is the sum of every departments[].targetArea — a null target counts as 0; unassigned area has no target.

Property	Type	Description
units	"ft2" | "m2"	The unit every area in this summary is reported in
totalTargetArea	number	Sum of all department target areas
totalAllocatedArea	number	Total allocated area = departments + unassignedArea
unassignedArea	number	Allocated area not attributed to any listed department (site/unassigned) — the delta that reconciles the total
departments	PluginProgramDepartmentMetric[]	Per-department area breakdown

Functions

get()

Get the area-program summary for the active project — project-level totals and a per-department area breakdown.

• Returns: PluginProgramMetricsSummary — empty breakdown with zero totals when the project has no program.

const m = await snaptrude.program.metrics.get();
console.log(`${m.totalAllocatedArea} / ${m.totalTargetArea} ${m.units}`);
console.log("unassigned:", m.unassignedArea);
for (const d of m.departments) {
  const status = d.targetArea === null ? "no target" : d.allocatedArea - d.targetArea;
  console.log(d.name, d.allocatedArea, d.targetArea, status);
}

Errors

Failed calls reject with a typed PluginError — see Error Handling. This namespace has no specific error conditions: get is a total read — a project with no program returns an empty breakdown with zero totals rather than throwing.