skills/plugins/library-navigator/skills/api-stack/api-plugins/sp-api-plugin-asset-register/SKILL.md

name, description

name

description

sp-api-plugin-asset-register

Fixed-asset lifecycle plugin for the Fetch-native @suaveplan/api platform. Authored with @suaveplan/api-plugin-kit definePlugin, contributes 15 typed RouteDescriptors under /assets, persisting to its own SurrealDB tables via four SurrealDB-backed repositories from one injected SurrealAdapter (plugin OWNS its persistence). Computes depreciation (straight-line, reducing-balance, units-of-activity), renders asset-tag QR labels with @suaveplan/qrcode, manages maintenance records and cost-centre assignments. Server-tier.

@suaveplan/api-plugin-asset-register

Purpose

Fixed-asset lifecycle plugin for the Fetch-native @suaveplan/api platform. Authored with @suaveplan/api-plugin-kit definePlugin, it contributes 15 typed RouteDescriptors under /assets, persisting to its own SurrealDB tables (asset, depreciation_schedule, maintenance_record, asset_assignment) via four SurrealDB-backed repositories constructed from one injected SurrealAdapter — the plugin OWNS its persistence.

It computes depreciation (straight-line, reducing-balance, units-of-activity) with @suaveplan/datetime date math, renders asset-tag QR labels with @suaveplan/qrcode, and manages maintenance records and cost-centre assignments.

Architecture

Component	Source	Role
createAssetRegisterPlugin	src/plugin/plugin.ts	Plugin factory
createAssetRegister	src/plugin/plugin.ts	Returns { plugin, repositories } for live access
calculateDepreciation	src/depreciation/depreciation.ts	Pure depreciation engine
SurrealAssetRepository	src/repositories/asset/asset.ts	Asset CRUD persistence
SurrealDepreciationRepository	src/repositories/depreciation/depreciation.ts	Depreciation schedule persistence
SurrealMaintenanceRepository	src/repositories/maintenance/maintenance.ts	Maintenance record persistence
SurrealAssignmentRepository	src/repositories/assignment/assignment.ts	Cost-centre assignment persistence
ASSET_REGISTER_API_CODES	src/error-codes/error-codes.ts	Error-code registry

File Structure

src/
  index.ts              # Barrel: plugin factories, repositories, routes, depreciation, codes, types
  plugin/
    plugin.ts           # createAssetRegisterPlugin, createAssetRegister
  depreciation/
    depreciation.ts     # calculateDepreciation (pure)
  repositories/
    asset/              # SurrealAssetRepository + InMemoryAssetStore
    depreciation/       # SurrealDepreciationRepository + InMemoryDepreciationStore
    maintenance/        # SurrealMaintenanceRepository + InMemoryMaintenanceStore
    assignment/         # SurrealAssignmentRepository + InMemoryAssignmentStore
    shared/             # Row mappers, query helpers
  routes/
    all-routes/         # buildAllAssetRegisterRoutes
    assets/             # CRUD, depreciation, maintenance, assignment, label routes
  schema/
    schema.ts           # SurrealQL DDL + applyAssetRegisterSchema
  error-codes/
    error-codes.ts      # ASSET_REGISTER_API_CODES + AssetRegisterApiError
  otel/
    instruments.ts      # asset_register_api.* OTel bundle

Entry Points

Import	Exports
@suaveplan/api-plugin-asset-register	createAssetRegisterPlugin, createAssetRegister, repositories, routes, depreciation, codes, types
@suaveplan/api-plugin-asset-register/plugin	createAssetRegisterPlugin, createAssetRegister, AssetRegisterWiring
@suaveplan/api-plugin-asset-register/depreciation	calculateDepreciation, DepreciationContext, DepreciationResult
@suaveplan/api-plugin-asset-register/routes	buildAllAssetRegisterRoutes, buildAssetRoutes, RouteDeps
@suaveplan/api-plugin-asset-register/repositories/asset	SurrealAssetRepository, InMemoryAssetStore, types
@suaveplan/api-plugin-asset-register/error-codes	ASSET_REGISTER_API_CODES, AssetRegisterApiError
@suaveplan/api-plugin-asset-register/otel	OTel instruments
@suaveplan/api-plugin-asset-register/schemas	AssetRegisterPluginOptionsSchema
@suaveplan/api-plugin-asset-register/types	Public types

Patterns

Basic usage

import { createApi } from "@suaveplan/api";
import { createAuth } from "@suaveplan/api-plugin-auth";
import { createAssetRegister } from "@suaveplan/api-plugin-asset-register";
import { SurrealAdapter } from "@suaveplan/surrealdb";

const db = new SurrealAdapter({ url: "ws://localhost:8000" });
await db.connect();

const { plugin: authPlugin, sessionResolver } = createAuth({ betterAuth });
const { plugin } = createAssetRegister({ db });

const runtime = createApi({
    plugins: [authPlugin, plugin],
    sessionResolver,
    tenantResolver,
});
await runtime.start("auth");
await runtime.start("asset-register");

Routes

All routes are auth-gated and tenant-scoped. Default mount prefix /.

Method	Path	Operation
GET	/assets	list assets
POST	/assets	create asset
GET	/assets/:id	read one asset
PATCH	/assets/:id	update asset
POST	/assets/:id/dispose	dispose asset
GET	/assets/:id/label	QR SVG label
GET	/assets/:id/depreciation	compute depreciation snapshot
GET	/assets/:id/depreciation/history	depreciation audit trail
GET	/assets/:id/maintenance	list maintenance records
POST	/assets/:id/maintenance	schedule maintenance
PATCH	/assets/:id/maintenance/:maintenanceId	complete maintenance
DELETE	/assets/:id/maintenance/:maintenanceId	cancel maintenance
GET	/assets/:id/assignments	list assignments
POST	/assets/:id/assignments	assign to cost centre
POST	/assets/:id/assignments/:assignmentId/return	return assignment

Constraints

• Server-tier — consumes @suaveplan/surrealdb.
• Owns its persistence — four SurrealDB tables: asset, depreciation_schedule, maintenance_record, asset_assignment.
• Depreciation methods — straight-line, reducing-balance, units-of-activity.
• Lifecycle enforcement — disposed assets reject further updates (409); invalid maintenance transitions raise MAINTENANCE_CONFLICT (409); at most one active assignment per asset.
• In-memory variants — each repository has an InMemory*Store for testing.
• Dependencies: @suaveplan/api, @suaveplan/api-plugin-auth, @suaveplan/api-plugin-kit, @suaveplan/api-types, @suaveplan/datetime, @suaveplan/error, @suaveplan/qrcode, @suaveplan/surrealdb, @suaveplan/types, @opentelemetry/api, tslib, zod.

Checklist

• Read src/depreciation/depreciation.ts before modifying depreciation logic
• Read src/plugin/plugin.ts before changing plugin wiring
• Preserve lifecycle state-machine constraints
• Ensure disposed assets remain immutable