Server side
A plugin’s server code is a Nest module named in plugin.yaml (server: { module, class }). Core
mounts it at /api/v1/plugins/<plugin id> and adds the scoped SDK services to it. Never provide
those services yourself.
A route
Section titled “A route”@Controller({ path: 'leads', version: '1' })@ApiTags('Sales')export class LeadsController { constructor(private readonly sales: SalesService) {}
@Get(':id') @Permissions('sales:read') // declared in plugin.yaml get( @CurrentUser() user: AuthUser, @Param('id', ParseUUIDPipe) id: string, ): Promise<Lead> { return this.sales.lead(user, id); // the service decides whether *this* user sees it }}- Every route needs
@Permissions(...)(permissions from your manifest) or a deliberate@Public(); core refuses to start otherwise. - DTOs use class-validator with
@ApiProperty; unknown properties are rejected. - After changing routes or DTOs:
pnpm api:spec, and commit the result. - In the shared API spec and the generated client, your schemas and operation ids carry your plugin
id:
CreateLeadDtoinaf.salesisaf_sales_CreateLeadDto, andSalesController.listisaf_sales_SalesController_list_v1. Name your classes freely; another plugin’s names can’t collide with yours.
The database
Section titled “The database”@Injectable()export class SalesRepository { constructor(private readonly db: PluginDb) {}
transaction<T>(work: (tx: NodePgDatabase) => Promise<T>): Promise<T> { return this.db.transaction(work); // runs as role af_sales, schema sales }}Write the migration first (db/migrations/000N_<what>.sql plus a journal entry), apply it with
pnpm --filter backend db:migrate, then update db/schema.ts. Use Drizzle’s query builder or
sql\…`` with bound parameters — never string concatenation.
Core services you can inject
Section titled “Core services you can inject”| Service | For |
|---|---|
PluginDb |
Your schema, as your role |
PluginPeople |
get(ids), search(query), presence(ids) |
PluginEvents |
publish(event, payload, { users, transaction, ephemeral }); on(event, handler) for events listed in events.subscribes (runs in the workers, at least once, dedupe on event.id); filterRecipients(event, fn) for your own events’ socket recipients. See docs/backend/server-events.md |
PluginNotifications |
send({ type, recipients, context, idempotencyKey }) |
PluginFiles |
createUpload, complete, get, downloadUrl, list, delete |
PluginWorkflows |
start({ workflow, key, input, transaction }), getStatus, requestCancel |
PluginConfig, PluginSecrets |
Your settings and secrets |
PluginAudit |
record({ action, target, metadata }) |
PluginContracts |
provide(name, caller => api, { actorRequired }), get<T>(name), getAll<T>(name) (extension points); caller.actor() is attached by core. Also in Activities (sdk.contracts) |
PluginRateLimit |
hit(key, { limit, windowMs, cost }): shared by every API replica, counted per call or in units; acquire(key, { limit, leaseMs }) for concurrent slots; never a Map |
PluginCache |
get, set(key, value, { ttlMs }), delete, getOrSet: the instance’s Redis, scoped to you, always with a TTL; never the truth |
PluginJobs |
every(name, everyMs, run): periodic upkeep once per period across replicas, never a timer |
PluginMetrics |
counter / gauge / histogram(name, { help, labels }), exported as af_plugin_<plugin>_<name> |
@Idempotent() (decorator) |
a retried write with the same Idempotency-Key returns the first result; never on routes whose answer holds a secret |
PluginTracer |
span(name, work): a span <plugin id>.<name> in the current trace |
PluginContext |
Your plugin id, version, process, and assetPath() for runtime files you declared |
Resources beyond the defaults
Section titled “Resources beyond the defaults”Some routes need larger bodies, browsers need to send your own header, your files are big, you
want pgvector: ask for it in plugin.yaml, and reviewers see it in one place.
resources: http: bodyLimits: [{ path: /proxy, maxBytes: 20mb }] corsHeaders: [x-my-plugin-key] files: { maxUploadBytes: 2gb, quotaBytes: 200gb } postgres: { extensions: [vector] } assets: [./server/runtime/**]Ceilings, allow-lists and how each works: Plugin resources in the reference docs
(docs/backend/plugin-resources.md). In your migrations, extension types resolve unqualified
(embedding vector(768)). Files over 64 MiB upload in parts: uploadToStorage handles them, and
your complete route stays the same.
Access to records
Section titled “Access to records”Check it in the service, on every call. Return “not found” for records the person may not see.
Express the rule once — Sales has one SQL condition, visibleTo(viewer), used by every query — so
a list, a single read and a write cannot disagree.
Errors
Section titled “Errors”Throw Nest’s exceptions (BadRequestException, ForbiddenException, NotFoundException,
ServiceUnavailableException); core turns them into the error envelope with a trace id and never
leaks database details.