@nivaro/extension-kit 0.1.1

package/README.md

@@ -0,0 +1,78 @@
+# @nivaro/extension-kit
+
+The contract a Nivaro extension is written against.
+
+An extension's entry module cannot import `api/src` — the API compiles with
+`rootDir: src`, and a mounted extension runs against a built image that ships
+no source. Before this package, every extension kept hand-copied mirrors of
+the types it needed and re-implemented the small helpers the API already had.
+This package is the one place those live: the API imports its extension
+contract from here, and so does the extension.
+
+```ts
+import {
+  defineExtension,
+  requesterInsertFields,
+  type ExtensionContext,
+  type IntegrationSignal
+} from '@nivaro/extension-kit'
+
+export default defineExtension({
+  id: 'my-extension',
+  env: [{ name: 'PARTNER_TOKEN', required: true, secret: true }],
+  async register(ctx: ExtensionContext) {
+    ctx.hooks.after('orders', 'create', async ({ result }) => {
+      /* … */
+    })
+    ctx.integrations.registerSignal(mySignal satisfies IntegrationSignal)
+  }
+})
+```
+
+## What is in it
+
+- **Context** — `ExtensionContext`, `ExtensionDefinition`, settings and
+  environment declarations, cron options.
+- **Registrations** — every shape the context accepts: bulk and item actions,
+  readiness and integrity checks, notes providers, mail types, digest
+  sections, links, storage adapters, field types, validators, import parsers,
+  chat-bot tools, event sources.
+- **Flows** — operation and trigger registrations, the execution context.
+- **Integrations** — obligation kinds, signals, signal actions.
+- **Imports** — the import-processor contract and run-report shapes.
+- **Operations** — `OpsTaskDef` (repairs and backfills run from the console),
+  `ConfigSeedDef` (checked-in configuration rows with a drift report) and
+  `SchemaStepDef` (versioned DDL an extension owns, run once at load under
+  the migration lock).
+- **Helpers** — `hasColumn(db, table, column)` (a per-database column probe
+  for writers that must survive an unmigrated database) and
+  `requesterInsertFields` / `requesterSelectColumns` for the ERP submission
+  tables.
+
+Types are exported with `export type`; the helpers and the test context are
+the only runtime code.
+
+## Testing an extension
+
+`createTestContext()` is a context whose every effect is recorded instead of
+sent — notifications, external calls, activity, flow emits, obligations —
+and whose registrations can be run by the test: `runHooks`, `runCron`,
+`deliverEvent`, `invoke` (a route the extension registered). Its database is
+`createTestDb({ tables })`, an in-memory knex-shaped fake covering the chain
+extensions use (where / whereIn / first / pluck / count / insert / update /
+del, `raw`, `schema.hasColumn`, `transaction`); joins are accepted and
+ignored, so seed the joined columns on the row you expect back.
+
+```ts
+const ctx = createTestContext({ tables: { orders: [{ id: 1, owner: 'u1' }] } })
+await myExtension.register(ctx)
+await ctx.runHooks('orders', 'create', 'after', { keys: [1], result: { id: 1, owner: 'u1' } })
+expect(ctx.calls.notifications).toEqual([{ userId: 'u1', opts: { subject: 'Order 1', message: 'created' } }])
+const res = await ctx.invoke('GET', '/api/demo/orders/1')
+```
+
+## Versioning
+
+The kit follows the API: a release that adds to the context adds to the kit
+in the same commit. An extension built against an older kit keeps working —
+members are only ever added.

package/dist/column-probe.d.ts

@@ -0,0 +1,9 @@
+import type { Knex } from 'knex';
+/** server/database of a knex client's connection config — the default probe scope. */
+export declare function databaseKey(db: Knex): string;
+export declare function hasColumn(db: Knex, table: string, column: string, opts?: {
+    scope?: string;
+}): Promise<boolean>;
+/** Test-only: forget every probed result so the next call re-checks. */
+export declare function resetColumnProbes(): void;
+//# sourceMappingURL=column-probe.d.ts.map

package/dist/column-probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-probe.d.ts","sourceRoot":"","sources":["../src/column-probe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAyBhC,sFAAsF;AACtF,wBAAgB,WAAW,CAAC,EAAE,EAAE,IAAI,GAAG,MAAM,CAW5C;AAED,wBAAsB,SAAS,CAC7B,EAAE,EAAE,IAAI,EACR,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5B,OAAO,CAAC,OAAO,CAAC,CAiBlB;AAED,wEAAwE;AACxE,wBAAgB,iBAAiB,IAAI,IAAI,CAExC"}

package/dist/column-probe.js

@@ -0,0 +1,58 @@
+/**
+ * "Does this column exist yet?" — asked by writers that must keep working on
+ * a database that has not run the migration adding it (a cloud tenant, an
+ * image ahead of its ledger, a teammate's dev API restarting under you).
+ *
+ * A hit is kept for the life of the process: a column, once added, is never
+ * dropped from under a running process. A miss is asked again after a
+ * minute, so a database that catches up is picked up without a restart.
+ *
+ * Probes are kept per database. Pass `scope` when the process serves several
+ * databases through one knex (cloud mode: the tenant id); otherwise the knex
+ * client's own connection config keys the probe.
+ */
+const MISS_TTL_MS = 60_000;
+const probes = new Map();
+/** server/database of a knex client's connection config — the default probe scope. */
+export function databaseKey(db) {
+    try {
+        const conn = db.client
+            ?.config?.connection;
+        if (!conn)
+            return '';
+        if (typeof conn === 'string')
+            return conn;
+        const c = conn;
+        return `${c.server ?? c.host ?? ''}/${c.database ?? ''}`;
+    }
+    catch {
+        return '';
+    }
+}
+export async function hasColumn(db, table, column, opts = {}) {
+    const key = `${opts.scope ?? databaseKey(db)}\u0000${table}\u0000${column}`;
+    const state = probes.get(key);
+    if (state?.hit)
+        return true;
+    if (state?.inflight)
+        return state.inflight;
+    if (state && Date.now() - state.at < MISS_TTL_MS)
+        return false;
+    const inflight = (async () => {
+        try {
+            return await db.schema.hasColumn(table, column);
+        }
+        catch {
+            return false;
+        }
+    })();
+    probes.set(key, { hit: false, at: state?.at ?? 0, inflight });
+    const hit = await inflight;
+    probes.set(key, { hit, at: Date.now(), inflight: null });
+    return hit;
+}
+/** Test-only: forget every probed result so the next call re-checks. */
+export function resetColumnProbes() {
+    probes.clear();
+}
+//# sourceMappingURL=column-probe.js.map

package/dist/column-probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-probe.js","sourceRoot":"","sources":["../src/column-probe.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,GAAG,MAAM,CAAA;AAQ1B,MAAM,MAAM,GAAG,IAAI,GAAG,EAAsB,CAAA;AAE5C,sFAAsF;AACtF,MAAM,UAAU,WAAW,CAAC,EAAQ;IAClC,IAAI,CAAC;QACH,MAAM,IAAI,GAAI,EAAoE,CAAC,MAAM;YACvF,EAAE,MAAM,EAAE,UAAU,CAAA;QACtB,IAAI,CAAC,IAAI;YAAE,OAAO,EAAE,CAAA;QACpB,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAA;QACzC,MAAM,CAAC,GAAG,IAA6D,CAAA;QACvE,OAAO,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,IAAI,IAAI,EAAE,IAAI,CAAC,CAAC,QAAQ,IAAI,EAAE,EAAE,CAAA;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAA;IACX,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,EAAQ,EACR,KAAa,EACb,MAAc,EACd,OAA2B,EAAE;IAE7B,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,KAAK,IAAI,WAAW,CAAC,EAAE,CAAC,SAAS,KAAK,SAAS,MAAM,EAAE,CAAA;IAC3E,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC7B,IAAI,KAAK,EAAE,GAAG;QAAE,OAAO,IAAI,CAAA;IAC3B,IAAI,KAAK,EAAE,QAAQ;QAAE,OAAO,KAAK,CAAC,QAAQ,CAAA;IAC1C,IAAI,KAAK,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,EAAE,GAAG,WAAW;QAAE,OAAO,KAAK,CAAA;IAC9D,MAAM,QAAQ,GAAG,CAAC,KAAK,IAAI,EAAE;QAC3B,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;QACjD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAA;QACd,CAAC;IACH,CAAC,CAAC,EAAE,CAAA;IACJ,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAA;IAC7D,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAA;IAC1B,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAA;IACxD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,iBAAiB;IAC/B,MAAM,CAAC,KAAK,EAAE,CAAA;AAChB,CAAC"}

package/dist/context.d.ts

@@ -0,0 +1,361 @@
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
+import type { Inngest } from 'inngest';
+import type { Knex } from 'knex';
+import type { FlowOpRegistration, FlowTriggerRegistration } from './flows.js';
+import type { ExtensionHookHandler, HookAction } from './hooks.js';
+import type { ImportProcessorDef } from './imports.js';
+import type { DigestSectionProvider, MailTypeDef, NotificationChannelDef, NotificationSourceProvider, NotifyUserOptions } from './notifications.js';
+import type { ObligationKindDef, ObligationResolvePatch, ObligationTrigger, ObligationTriggerContext } from './obligations.js';
+import type { BotToolDef, BriefLineProvider, BulkActionDef, CallOptions, CallResult, ChainTable, CollectionViewDef, ConfigSeedDef, DashboardWidgetDef, EventSourceDef, FieldTypeDef, ImportParserDef, IntegrityCheck, ItemActionDef, LinkRegistration, MachineMarkerSet, OpsTaskDef, ReadinessCheck, RelatedNoteProvider, SchemaStepDef, StorageAdapter, ValidatorDef } from './registrations.js';
+import type { IntegrationSignal, SignalActionHandler } from './signals.js';
+export type ExtensionSettingValue = string | number | boolean | null;
+/** A handler for the extension's own durable events (ctx.events). */
+export type ExtensionEventHandler = (event: {
+    id: number;
+    extension: string;
+    event_type: string;
+    payload: unknown;
+}) => void | Promise<void>;
+export interface ExtensionCronOpts {
+    /** Plain-language purpose — what the job does and what it touches. */
+    description?: string;
+    /** Serialised with every other heavy job; yields to pool pressure. */
+    heavy?: boolean;
+    /** 'unsafe' = run-now duplicates mail or mutations. */
+    idempotent?: 'safe' | 'unsafe' | 'unknown';
+    /** The job's own no-write report, offered on Background Jobs. */
+    dryRun?: () => Promise<unknown>;
+}
+export interface ExtensionCronMeta {
+    description?: string;
+    heavy?: boolean;
+    idempotent?: 'safe' | 'unsafe' | 'unknown';
+    /** The deployment flag this job no-ops behind, and whether it currently
+     *  lets the job run. */
+    gate?: {
+        flag: string;
+        enabled: boolean;
+    };
+}
+/** A scheduled job as the core's cron manager lists it. */
+export interface ExtensionCronEntry {
+    id: string;
+    expression: string;
+    defaultExpression: string;
+    overridden: boolean;
+    extensionId?: string;
+    nextRun: Date | null;
+    heavy?: boolean;
+    idempotent?: 'safe' | 'unsafe' | 'unknown';
+    description?: string;
+    gate?: {
+        flag: string;
+        enabled: boolean;
+    };
+    paused?: boolean;
+    supports_dry_run?: boolean;
+}
+/** The core's cron manager as extensions may read it (`ctx.app.cron`). */
+export interface ExtensionCronManager {
+    list(): ExtensionCronEntry[];
+    pause(id: string): void;
+    resume(id: string): void;
+}
+/** The Fastify instance with the core decorations an extension may rely on. */
+export type ExtensionApp = FastifyInstance & {
+    cron: ExtensionCronManager;
+};
+/**
+ * What `register()` receives. Every member is a capability the core exposes
+ * to extensions; members marked optional arrived in a later core release
+ * than the earliest an extension may run against, so an extension checks
+ * before using them.
+ */
+export interface ExtensionContext {
+    app: ExtensionApp;
+    database: Knex;
+    inngest: Inngest;
+    logger: FastifyInstance['log'];
+    /** Admin-editable extension settings — declared on the export. Values are
+     *  parsed by the declared type (number/boolean), 30s cache. */
+    settings?: {
+        get(key: string): Promise<ExtensionSettingValue>;
+        getAll(): Promise<Record<string, ExtensionSettingValue>>;
+    };
+    /** Durable event outbox — publish inserts a pending row delivered by the
+     *  sweep cron; `on` registers a delivery handler for this extension's
+     *  events ('*' = every type). Delivery retries with exponential backoff. */
+    events: {
+        publish(eventType: string, payload?: unknown): Promise<number | null>;
+        on(eventType: string | '*', fn: ExtensionEventHandler): void;
+    };
+    /** Call a configured external API by name or numeric ID. Auth resolved
+     *  automatically; every call lands in the API's call log. */
+    callExternalApi(nameOrId: string | number, options?: CallOptions): Promise<CallResult>;
+    /** Long-running SQL outside knex.raw's request timeout — one statement,
+     *  its own timeout (default 20 minutes), rows back. Bind nothing: the
+     *  batch is sent as text, so only interpolate values you built yourself. */
+    sql: {
+        runLong<T = Record<string, unknown>>(sql: string, opts?: {
+            timeoutMs?: number;
+        }): Promise<T[]>;
+    };
+    /** Write an audit entry to nivaro_activity for a mutation that bypasses
+     *  the items service. The action is namespaced `<extId>:<action>`. Never
+     *  throws. */
+    logActivity(entry: {
+        action: string;
+        user?: string | null;
+        collection?: string;
+        item?: string | number;
+        comment?: string;
+        /** person | machine | import | integration — default: machine with no user. */
+        origin?: 'person' | 'machine' | 'import' | 'integration';
+    }): Promise<number | null>;
+    /** Deliver a notification through the full channel stack — inbox row,
+     *  live socket event, browser push, optional email — honouring the
+     *  recipient's notification rules. The only way an extension may notify a
+     *  person; a raw nivaro_notifications insert bypasses every preference.
+     *  Never throws. */
+    notifyUser(userId: string, opts: NotifyUserOptions): Promise<void>;
+    /** Hook helpers scoped to this extension — hooks are tagged and can be
+     *  disabled / removed with it. */
+    hooks: {
+        before(collection: string | '*', action: HookAction | '*', fn: ExtensionHookHandler): void;
+        after(collection: string | '*', action: HookAction | '*', fn: ExtensionHookHandler): void;
+    };
+    /** Cron helpers scoped to this extension — jobs pause and resume with it. */
+    cron: {
+        /** Register a recurring job. `id` is scoped to this extension. */
+        schedule(id: string, expression: string, fn: () => void | Promise<void>, opts?: ExtensionCronOpts): void;
+        /** Cancel a previously scheduled job. */
+        unschedule(id: string): void;
+        /** Attach a description / heavy / idempotent flag / gate after scheduling. */
+        annotate(id: string, meta: ExtensionCronMeta): void;
+    };
+    /** Bulk actions in the collection browser / queue selection bar. */
+    bulkActions: {
+        register(def: BulkActionDef): void;
+    };
+    /** Contextual buttons in the record form's toolbar. */
+    itemActions: {
+        register(def: ItemActionDef): void;
+    };
+    /** Custom notification delivery channels (SMS, Slack, Teams…). */
+    notificationChannels: {
+        register(def: NotificationChannelDef): void;
+    };
+    /** Extension-owned alert subscriptions on the profile's notification
+     *  sources card. */
+    notificationSources: {
+        register(provider: NotificationSourceProvider): void;
+    };
+    /** Read-only entries in a record's Notes thread, and the machine markers
+     *  the thread should drop. */
+    notes: {
+        registerSource(provider: RelatedNoteProvider): void;
+        registerMachineMarkers(set: MachineMarkerSet): void;
+    };
+    dashboardWidgets: {
+        register(def: DashboardWidgetDef): void;
+    };
+    /** Named file storage adapters (S3, Azure Blob…). */
+    storage: {
+        register(name: string, adapter: StorageAdapter): void;
+        /** Activate a registered adapter for all new uploads. */
+        setActive(name: string): void;
+    };
+    fieldTypes: {
+        register(def: FieldTypeDef): void;
+    };
+    collectionViews: {
+        register(def: CollectionViewDef): void;
+    };
+    importParsers: {
+        register(def: ImportParserDef): void;
+    };
+    /** Processors for staged imports whose file spans several collections;
+     *  `key` is `<extension>:<name>` and is what an import definition names. */
+    importProcessors: {
+        register(def: ImportProcessorDef): void;
+    };
+    validators: {
+        register(def: ValidatorDef): void;
+    };
+    approvalBrief: {
+        /** One short line on the transition confirm's approval brief. */
+        registerLine(collection: string, fn: BriefLineProvider): void;
+    };
+    digest: {
+        /** A per-user section of the daily action digest email. */
+        registerSection(fn: DigestSectionProvider): void;
+    };
+    readiness: {
+        /** A scored check on the go-live readiness scorecard. */
+        registerCheck(check: ReadinessCheck): void;
+    };
+    /** Operational tasks — repairs, backfills, migrations — run from the admin
+     *  console (dry run by default, one at a time, every run recorded). */
+    tasks: {
+        register(def: OpsTaskDef): void;
+    };
+    /** Checked-in rows of a configuration collection, applied by a task —
+     *  never at boot — with a drift report as its dry run. */
+    seeds: {
+        register(def: ConfigSeedDef): void;
+    };
+    /** A versioned schema change the extension owns, run at load under the
+     *  migration lock and recorded once per database (#826). */
+    schema: {
+        step(id: string, def: Omit<SchemaStepDef, 'id'>): void;
+    };
+    chain: {
+        /** Start a chain for one feed event (e.g. one shipment) and run fn inside it. */
+        begin<T>(root: {
+            source: string;
+            ref: string;
+        }, fn: () => Promise<T>): Promise<T>;
+        /** The chain currently open, or null. */
+        current(): {
+            chain_id: string;
+            parent: string | null;
+        } | null;
+        /** chain_id/chain_parent for an insert into a core table (probe-aware).
+         *  A table outside ChainTable yields {}. */
+        fields(table: ChainTable | (string & {}), opts?: {
+            parent?: string | null;
+        }): Promise<Record<string, string | null>>;
+    };
+    integrations: {
+        /** Declare an outbound obligation kind. Core owns the ledger and the
+         *  sweep; the extension owns the sends. */
+        registerObligationKind(def: ObligationKindDef): void;
+        /** Open an obligation for a decision point in the extension's own code.
+         *  Null when no registered kind claims the context. */
+        openObligation(ctx: ObligationTriggerContext, opts: {
+            trigger: ObligationTrigger;
+            trigger_ref?: string | null;
+            due_at?: Date;
+        }): Promise<number | null>;
+        /** Close an obligation with its outcome. A null id is a no-op. */
+        resolveObligation(id: number | null, patch: ObligationResolvePatch): Promise<void>;
+        /** A signal on the Integrations console's Firefight list. */
+        registerSignal(def: IntegrationSignal): void;
+        /** An action a signal row may offer (kind 'extension', id = def.id). */
+        registerSignalAction(def: SignalActionHandler): void;
+        /** An event source on the Integrations console's Events feed. */
+        registerEventSource(def: EventSourceDef): void;
+    };
+    integrity: {
+        /** A Data Integrity check the sweep, the record banner and Fix run. */
+        registerCheck(check: IntegrityCheck): void;
+    };
+    links: {
+        /** The headless frontend's base URL + route map (Settings wins). */
+        register(reg: LinkRegistration): void;
+    };
+    mail: {
+        /** An email type for the admin mail harness. */
+        registerType(def: MailTypeDef): void;
+        /** Dry-run an active flow with a payload; what its mail op would send. */
+        renderViaFlow(flowName: string, payload: Record<string, unknown>): Promise<{
+            to: string;
+            subject: string;
+            html: string;
+        } | null>;
+        /** Render a named Liquid mail template (core or extension root). */
+        renderTemplate(name: string, data: Record<string, unknown>): Promise<string>;
+    };
+    flows: {
+        /** A custom operation type: parsed options, current flow data, context. */
+        registerOperation(op: FlowOpRegistration): void;
+        /** A custom trigger type; `flows.emit(type, payload)` fires it. */
+        registerTrigger(trigger: FlowTriggerRegistration): void;
+        /** Fire every active flow on this trigger type. Fire-and-forget. */
+        emit(triggerType: string, payload: Record<string, unknown>): void;
+    };
+    /** Tools the AI chat bot may call, run as the asking user. */
+    chatBot: {
+        registerTool(def: BotToolDef): void;
+    };
+    /** Auth middleware — use as Fastify `onRequest` / `preHandler` handlers. */
+    auth: {
+        authenticate: (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
+        requireAuth: (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
+        requireAdmin: (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
+    };
+    /** Cloud-only context — populated when CLOUD_META_DB_URL is set. */
+    cloud?: {
+        /** Immutable tenant UUID for the current request; undefined outside one. */
+        getTenantId(): string | undefined;
+        /** Tenant slug for the current request; undefined outside one. */
+        getTenantSlug(): string | undefined;
+        /** Knex client connected to the Nivaro Cloud meta database. */
+        metaDb: Knex;
+    };
+}
+export interface ExtensionSettingDeclInput {
+    key: string;
+    label: string;
+    type?: 'string' | 'number' | 'boolean' | 'secret';
+    description?: string;
+    default?: string;
+    /** Legacy spelling of `type: 'secret'`. */
+    secret?: boolean;
+    /** What production is expected to hold; the readiness scorecard warns
+     *  when the live value differs. */
+    production_expect?: string;
+    /** Refuse a value with a message (null = fine). */
+    validate?: (value: ExtensionSettingValue) => string | null | Promise<string | null>;
+    /** Applied the moment a value is saved (no restart, no cache wait). */
+    on_change?: (value: ExtensionSettingValue) => void | Promise<void>;
+}
+/** A declared setting as the admin API serves it (types normalised,
+ *  handlers reduced to flags). */
+export interface ExtensionSettingDecl {
+    key: string;
+    label: string;
+    type: 'string' | 'number' | 'boolean' | 'secret';
+    description?: string;
+    default?: string;
+    production_expect?: string;
+    has_validate?: boolean;
+    has_on_change?: boolean;
+}
+/** An environment variable the extension reads. A missing REQUIRED one fails
+ *  /api/preflight and the readiness scorecard by name; values are never
+ *  reported. */
+export interface ExtensionEnvDecl {
+    name: string;
+    required?: boolean;
+    description?: string;
+    /** A credential: the registry says only whether it is set. */
+    secret?: boolean;
+}
+/** The default export of an extension's entry module. */
+export interface ExtensionDefinition {
+    id: string;
+    register(ctx: ExtensionContext): void | Promise<void>;
+    /** Permission scopes: what this extension touches — a declared manifest
+     *  shown before enabling, not an enforcement boundary. */
+    scopes?: string[];
+    /** Extension ids that must load FIRST. */
+    requires?: string[];
+    /** Command-palette entries served to the admin palette. */
+    palette?: Array<{
+        label: string;
+        path: string;
+    }>;
+    /** Admin-editable settings, stored in nivaro_extension_settings. */
+    settings?: ExtensionSettingDeclInput[];
+    /** Freeform declared capabilities ('routes', 'cron', 'hooks', …). */
+    capabilities?: string[];
+    /** Quick self-check surfaced on the Extensions page. */
+    healthCheck?(): Promise<{
+        ok: boolean;
+        note?: string;
+    }>;
+    /** The environment variables this extension reads. */
+    env?: ExtensionEnvDecl[];
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}

package/dist/context.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":""}

package/dist/flows.d.ts

@@ -0,0 +1,58 @@
+import type { FastifyBaseLogger } from 'fastify';
+export interface FlowData extends Record<string, unknown> {
+}
+export interface FlowTraceStep {
+    key: string;
+    name: string;
+    type: string;
+    status: 'resolve' | 'reject' | 'async';
+    preview?: unknown;
+}
+/** What a flow operation handler runs inside. */
+export interface FlowExecutionContext {
+    flowId: string;
+    flowName: string;
+    trigger: string;
+    payload: Record<string, unknown>;
+    log: FastifyBaseLogger;
+    userId?: string;
+    /** Test mode: side-effect ops render but do not send — a preview lands in
+     *  the trace instead. A custom op must honour it. */
+    dryRun?: boolean;
+    /** When provided, the executor appends one step per executed operation. */
+    trace?: FlowTraceStep[];
+}
+export type OpResult = {
+    status: 'resolve' | 'reject';
+    output: FlowData;
+};
+export type OpHandler = (opts: Record<string, unknown>, data: FlowData, ctx: FlowExecutionContext) => Promise<OpResult>;
+export interface OpFieldSchema {
+    key: string;
+    label: string;
+    type: 'string' | 'number' | 'boolean' | 'select' | 'textarea' | 'json';
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    placeholder?: string;
+    required?: boolean;
+    description?: string;
+    defaultValue?: unknown;
+}
+export interface FlowOpRegistration {
+    type: string;
+    label: string;
+    description?: string;
+    /** hex, e.g. '#7c3aed' */
+    color?: string;
+    fields?: OpFieldSchema[];
+    handler: OpHandler;
+}
+export interface FlowTriggerRegistration {
+    type: string;
+    label: string;
+    description?: string;
+    fields?: OpFieldSchema[];
+}
+//# sourceMappingURL=flows.d.ts.map

package/dist/flows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flows.d.ts","sourceRoot":"","sources":["../src/flows.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAEhD,MAAM,WAAW,QAAS,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAAG;AAE5D,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAA;IACtC,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,iDAAiD;AACjD,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAChC,GAAG,EAAE,iBAAiB,CAAA;IACtB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;yDACqD;IACrD,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,2EAA2E;IAC3E,KAAK,CAAC,EAAE,aAAa,EAAE,CAAA;CACxB;AAED,MAAM,MAAM,QAAQ,GAAG;IAAE,MAAM,EAAE,SAAS,GAAG,QAAQ,CAAC;IAAC,MAAM,EAAE,QAAQ,CAAA;CAAE,CAAA;AACzE,MAAM,MAAM,SAAS,GAAG,CACtB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,EAAE,QAAQ,EACd,GAAG,EAAE,oBAAoB,KACtB,OAAO,CAAC,QAAQ,CAAC,CAAA;AAEtB,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAA;IACtE,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACjD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,0BAA0B;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,aAAa,EAAE,CAAA;IACxB,OAAO,EAAE,SAAS,CAAA;CACnB;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,CAAC,EAAE,aAAa,EAAE,CAAA;CACzB"}

package/dist/flows.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=flows.js.map

package/dist/flows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flows.js","sourceRoot":"","sources":["../src/flows.ts"],"names":[],"mappings":""}

package/dist/hooks.d.ts

@@ -0,0 +1,26 @@
+import type { FastifyRequest } from 'fastify';
+import type { Knex } from 'knex';
+import type { ExtensionUser } from './user.js';
+export type HookAction = 'create' | 'update' | 'delete' | 'read';
+export type HookTiming = 'before' | 'after';
+/** What a before/after hook receives. `previousData` is set on update and
+ *  delete (captured before the write); `result` on after-hooks; `keys` holds
+ *  the record id(s) the write concerned. */
+export interface ExtensionHookContext {
+    collection: string;
+    action: HookAction;
+    keys?: Array<string | number>;
+    payload?: Record<string, unknown>;
+    result?: unknown;
+    previousData?: Record<string, unknown>;
+    /** Caller-supplied justification for this write (change-reason config). */
+    changeReason?: string;
+    /** True while a write is being rehearsed (`dry_run`): a hook may read and
+     *  shape the payload, and must not write, send or notify. */
+    dryRun?: boolean;
+    user?: ExtensionUser;
+    database: Knex;
+    req?: FastifyRequest;
+}
+export type ExtensionHookHandler = (ctx: ExtensionHookContext) => void | Promise<void>;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAC7C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAChC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAE9C,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAA;AAChE,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAA;AAE3C;;4CAE4C;AAC5C,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,UAAU,CAAA;IAClB,IAAI,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAA;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACjC,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACtC,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;iEAC6D;IAC7D,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,IAAI,CAAC,EAAE,aAAa,CAAA;IACpB,QAAQ,EAAE,IAAI,CAAA;IACd,GAAG,CAAC,EAAE,cAAc,CAAA;CACrB;AAED,MAAM,MAAM,oBAAoB,GAAG,CAAC,GAAG,EAAE,oBAAoB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA"}

package/dist/hooks.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=hooks.js.map

package/dist/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":""}