@tekki-forge/runtime-api 0.1.0

package/dist/service.js

@@ -0,0 +1,757 @@
+import { randomUUID } from "node:crypto";
+import { allowsRecord, authorize, effectiveRoles, evaluate, scopeAllows, teamKey } from "@tekki-forge/runtime-permissions";
+import { validateInput } from "@tekki-forge/runtime-schema";
+import { BadRequestException, ConflictException, ForbiddenException, NotFoundException, NotImplementedException, UnauthorizedException, } from "@nestjs/common";
+import { queryableFields, unreadableFields, unwritableFields } from "./access.js";
+import { ComputedEngine } from "./computed.js";
+import { EventBus } from "./events.js";
+import { NotificationService } from "./notifications.js";
+import { QueryError, parseListQuery, searchWhere } from "./query.js";
+import { diff, label, manyIds, relationInclude, serialize, toCsv, toPrismaData } from "./serialize.js";
+import { ApiKeyService } from "./api-keys.js";
+import { teamIdsOf } from "./teams.js";
+const EXPORT_LIMIT = 10_000;
+const TX = { timeout: 20_000, maxWait: 10_000 };
+const invalid = (issues) => new BadRequestException({ statusCode: 400, error: "Bad Request", message: "Validation failed", issues });
+export class ForgeService {
+    options;
+    app;
+    prisma;
+    auth;
+    socialProviders;
+    events;
+    computed;
+    notifications;
+    apiKeys;
+    /** Services shared between plugins and exposed to hooks via ctx.use(name). */
+    shared = new Map();
+    byPath;
+    byName;
+    byStorage;
+    extensions;
+    constructor(options) {
+        this.options = options;
+        this.app = options.app;
+        this.prisma = options.prisma;
+        this.auth = options.auth;
+        this.socialProviders = options.socialProviders ?? [];
+        this.events = options.events ?? new EventBus();
+        this.computed = new ComputedEngine(options.app);
+        this.apiKeys = new ApiKeyService(options.app, options.prisma);
+        this.notifications = new NotificationService(options.app, options.prisma, options.mail, (entity, principal) => this.policyCheck(entity, { principal, user: null, session: null }));
+        if (options.app.notifications.length)
+            this.events.on("*", (e) => this.notifications.handle(e), "notification rules");
+        this.byPath = new Map(options.app.entities.map((e) => [e.path, e]));
+        this.byName = new Map(options.app.entities.map((e) => [e.name, e]));
+        this.byStorage = new Map(options.app.entities.map((e) => [e.storageName, e]));
+        this.extensions = new Map((options.extensions ?? []).map((x) => [x.entity, x]));
+        for (const x of options.extensions ?? []) {
+            const entity = this.byName.get(x.entity);
+            if (!entity)
+                throw new Error(`[forge] extension for unknown entity "${x.entity}"`);
+            for (const a of entity.actions) {
+                if (!x.actions?.[a.name])
+                    console.warn(`[forge] ${entity.name}: action "${a.name}" has no handler in its extension file`);
+            }
+            for (const t of Object.keys(x.transitions ?? {})) {
+                if (!entity.workflow?.transitions.some((wt) => wt.name === t))
+                    throw new Error(`[forge] ${entity.name}: extension configures unknown transition "${t}"`);
+            }
+            for (const [pattern, handler] of Object.entries(x.on ?? {}))
+                this.events.on(pattern, handler, `${entity.name} extension`);
+        }
+        for (const e of options.app.entities) {
+            const rules = [...Object.values(e.permissions), ...e.fields.flatMap((f) => [f.access?.read, f.access?.write]), ...(e.workflow?.transitions.map((t) => t.permission) ?? [])];
+            const policies = new Set(rules.flatMap((p) => p?.policies ?? []));
+            for (const p of policies) {
+                if (!this.extensions.get(e.name)?.policies?.[p])
+                    throw new Error(`[forge] ${e.name}: policy "${p}" is referenced in forge.config.ts but not implemented in its extension file`);
+            }
+        }
+    }
+    /** Plugins attach behaviour (hooks, actions, event handlers) to the entities they contribute. */
+    addExtension(ext) {
+        const entity = this.byName.get(ext.entity);
+        if (!entity)
+            throw new Error(`[forge] extension for unknown entity "${ext.entity}"`);
+        const existing = this.extensions.get(ext.entity);
+        this.extensions.set(ext.entity, {
+            entity: ext.entity,
+            hooks: composeHooks(existing?.hooks, ext.hooks),
+            actions: { ...existing?.actions, ...ext.actions },
+            policies: { ...existing?.policies, ...ext.policies },
+            transitions: { ...existing?.transitions, ...ext.transitions },
+        });
+        for (const [pattern, handler] of Object.entries(ext.on ?? {}))
+            this.events.on(pattern, handler, `${ext.entity} extension`);
+    }
+    /** Used by the storage plugin during setup. */
+    useFileStore(store) {
+        this.options.files = store;
+    }
+    /** Startup check once plugins have been set up. */
+    assertReady() {
+        for (const e of this.app.entities) {
+            if (e.fields.some((f) => f.file) && !this.options.files) {
+                throw new Error(`[forge] ${e.name} has file/image fields but no file storage is set up — add the storage plugin (forge add storage)`);
+            }
+        }
+    }
+    entity(path) {
+        const e = this.byPath.get(path);
+        if (!e)
+            throw new NotFoundException(`Unknown resource "${path}"`);
+        return e;
+    }
+    entityByName(name) {
+        return this.byName.get(name);
+    }
+    /** The entity rows were stored under (`files.entity`, `audit_logs.entity`…): stable across renames. */
+    entityByStorageName(storageName) {
+        return this.byStorage.get(storageName);
+    }
+    // ─── Request context ────────────────────────────────────────────────────────
+    async resolveContext(headers, ip) {
+        // Scoped API keys: `Authorization: Bearer fk_…` (a bad key is a 401, never an anonymous request).
+        const authorization = headers.get("authorization");
+        if (authorization && /^bearer\s+fk_/i.test(authorization))
+            return this.apiKeys.resolve(authorization.replace(/^bearer\s+/i, ""), ip);
+        const result = await this.auth.api.getSession({ headers }).catch(() => null);
+        if (!result?.user)
+            return { principal: null, user: null, session: null, ...(ip ? { ip } : {}) };
+        const { user, session } = result;
+        let memberRole = null;
+        let organizationId = null;
+        if (this.app.tenancy.enabled && session.activeOrganizationId) {
+            const member = await this.prisma.member.findFirst({ where: { organizationId: session.activeOrganizationId, userId: user.id } });
+            if (member) {
+                memberRole = member.role;
+                organizationId = member.organizationId;
+            }
+        }
+        const teamIds = this.app.teams?.enabled && organizationId ? await teamIdsOf(this.prisma, user.id, organizationId) : undefined;
+        return {
+            principal: { id: user.id, roles: effectiveRoles(user.role, memberRole, this.app.tenancy.enabled), organizationId, ...(teamIds ? { teamIds } : {}) },
+            user: { id: user.id, name: user.name, email: user.email, role: user.role ?? null },
+            session: { id: session.id, activeOrganizationId: session.activeOrganizationId ?? null, impersonatedBy: session.impersonatedBy ?? null },
+            ...(ip ? { ip } : {}),
+        };
+    }
+    get mail() {
+        return this.options.mail;
+    }
+    hookContext(entity, ctx, db = this.prisma) {
+        return {
+            ...ctx,
+            entity,
+            prisma: db,
+            notify: (userIds, input) => this.notifications.notify(userIds, { organizationId: ctx.principal?.organizationId ?? null, ...input }),
+            ...(this.options.mail ? { mail: this.options.mail } : {}),
+            use: (name) => this.shared.get(name),
+        };
+    }
+    // ─── Authorization helpers ──────────────────────────────────────────────────
+    require(decision) {
+        if (decision.allowed)
+            return;
+        if (decision.reason === "unauthenticated")
+            throw new UnauthorizedException("Sign in to continue");
+        throw new ForbiddenException("You do not have permission to perform this action");
+    }
+    authorizeOp(entity, op, ctx) {
+        const decision = authorize(entity, op, ctx.principal);
+        this.require(decision);
+        this.requireTenant(entity, ctx);
+        return decision;
+    }
+    requireTenant(entity, ctx) {
+        if (!entity.features.tenant)
+            return;
+        if (!ctx.principal)
+            throw new UnauthorizedException("Sign in to continue");
+        if (!ctx.principal.organizationId)
+            throw new ForbiddenException("No active organization — create or select an organization first");
+    }
+    baseWhere(entity, ctx, trashed = "without") {
+        const where = [];
+        if (entity.features.tenant)
+            where.push({ organizationId: ctx.principal?.organizationId ?? "__none__" });
+        if (entity.features.softDelete) {
+            if (trashed === "without")
+                where.push({ deletedAt: null });
+            if (trashed === "only")
+                where.push({ deletedAt: { not: null } });
+        }
+        return where;
+    }
+    /** Prisma condition restricting a conditional decision (owner / policies) on lists. */
+    scopeWhere(entity, decision, ctx) {
+        if (decision.scope === "all")
+            return [];
+        const or = [];
+        if (decision.owner && ctx.principal && entity.ownerField) {
+            const fk = entity.fields.find((f) => f.name === entity.ownerField).relation.foreignKey;
+            or.push({ [fk]: ctx.principal.id });
+        }
+        const teamFk = decision.team && ctx.principal ? teamKey(entity) : undefined;
+        if (teamFk)
+            or.push({ [teamFk]: { in: ctx.principal.teamIds ?? [] } });
+        const ext = this.extensions.get(entity.name);
+        for (const name of decision.policies) {
+            const w = ext?.policies?.[name]?.where?.(this.hookContext(entity, ctx));
+            if (w)
+                or.push(w);
+        }
+        return [or.length ? { OR: or } : { id: { in: [] } }];
+    }
+    /** Full read scope for the caller: tenancy, soft delete and row-level permissions. */
+    readWhere(entity, ctx, trashed = "without") {
+        const decision = this.authorizeOp(entity, "read", ctx);
+        return [...this.baseWhere(entity, ctx, trashed), ...this.scopeWhere(entity, decision, ctx)];
+    }
+    policyCheck(entity, ctx) {
+        const ext = this.extensions.get(entity.name);
+        return (name, record) => ext?.policies?.[name]?.check({ ...this.hookContext(entity, ctx), record }) ?? false;
+    }
+    queryAccess(entity, ctx) {
+        const restricted = entity.fields.some((f) => f.access?.read);
+        return { ...(restricted ? { queryable: queryableFields(entity, ctx.principal) } : {}), userId: ctx.principal?.id ?? null };
+    }
+    /** Load a record the caller may apply `op` (or `rule`) to; 404 when they cannot even see it. Raw Prisma row. */
+    async loadFor(entity, id, op, ctx, opts = {}) {
+        const decision = opts.rule ? evaluate(opts.rule, ctx.principal) : authorize(entity, op, ctx.principal);
+        this.require(decision);
+        // Actions and transitions use their own rule; API key scopes still apply.
+        if (ctx.principal?.scopes && !scopeAllows(ctx.principal.scopes, entity.path, op))
+            throw new ForbiddenException("This API key has no scope for this operation");
+        this.requireTenant(entity, ctx);
+        const record = await this.delegate(entity).findFirst({
+            where: { AND: [{ id }, ...this.baseWhere(entity, ctx, opts.trashed ?? "without")] },
+            include: relationInclude(entity),
+        });
+        if (!record)
+            throw new NotFoundException(`${entity.label} not found`);
+        const check = this.policyCheck(entity, ctx);
+        const readable = await allowsRecord(entity, authorize(entity, "read", ctx.principal), ctx.principal, record, check);
+        if (!readable)
+            throw new NotFoundException(`${entity.label} not found`);
+        if (!(await allowsRecord(entity, decision, ctx.principal, record, check))) {
+            throw new ForbiddenException("You do not have permission to perform this action");
+        }
+        return record;
+    }
+    delegate(entity, db = this.prisma) {
+        const d = db[entity.delegate];
+        if (!d)
+            throw new Error(`[forge] Prisma client has no model "${entity.model}" — run \`forge generate\` and \`forge db migrate\``);
+        return d;
+    }
+    /** Serialize for this caller, dropping fields they may not read. */
+    async present(entity, record, ctx) {
+        const omit = entity.fields.some((f) => f.access?.read) ? await unreadableFields(entity, ctx.principal, record, this.policyCheck(entity, ctx)) : undefined;
+        return serialize(entity, record, { ...(omit ? { omit } : {}), apiPrefix: this.app.api.prefix });
+    }
+    // ─── Validation ─────────────────────────────────────────────────────────────
+    /** Explain why read-only keys cannot be written instead of a generic "unknown field". */
+    rejectReadOnly(entity, body) {
+        if (!body || typeof body !== "object")
+            return;
+        const issues = [];
+        for (const f of entity.fields) {
+            const keys = new Set([f.apiName, f.name]);
+            if (![...keys].some((k) => k in body))
+                continue;
+            if (f.computed)
+                issues.push({ path: f.apiName, message: `${f.label} is computed (${f.computed.expression}) and cannot be set` });
+            else if (entity.workflow?.field === f.name) {
+                const names = entity.workflow.transitions.map((t) => t.name).join(", ");
+                issues.push({ path: f.apiName, message: `${f.label} changes through workflow transitions (${names}), not by editing` });
+            }
+            else if (f.readonly && !f.hidden)
+                issues.push({ path: f.apiName, message: `${f.label} is read-only` });
+        }
+        if (issues.length)
+            throw invalid(issues);
+    }
+    validate(entity, mode, body) {
+        this.rejectReadOnly(entity, body);
+        const result = validateInput(entity, mode, body);
+        if (!result.success)
+            throw invalid(result.issues);
+        return toPrismaData(entity, result.data, mode);
+    }
+    finalizeJson(data) {
+        for (const [k, v] of Object.entries(data)) {
+            if (v && typeof v === "object" && v.__forgeDbNull) {
+                if (this.options.dbNull !== undefined)
+                    data[k] = this.options.dbNull;
+                else
+                    delete data[k];
+            }
+        }
+        return data;
+    }
+    async relationTargetsExist(f, ids, ctx) {
+        if (ids.length === 0)
+            return true;
+        const rel = f.relation;
+        const principal = ctx.principal;
+        let found;
+        if (rel.entity === "User") {
+            found = await this.prisma.user.count({
+                where: this.app.tenancy.enabled ? { id: { in: ids }, members: { some: { organizationId: principal.organizationId } } } : { id: { in: ids } },
+            });
+        }
+        else if (rel.entity === "Team") {
+            found = await this.prisma.team.count({ where: { id: { in: ids }, organizationId: principal.organizationId ?? "__none__" } });
+        }
+        else if (rel.entity === "Organization") {
+            found = ids.every((id) => id === principal.organizationId) ? ids.length : 0;
+        }
+        else {
+            const target = this.byName.get(rel.entity);
+            found = await this.delegate(target).count({ where: { AND: [{ id: { in: ids } }, ...this.baseWhere(target, ctx)] } });
+        }
+        return found === new Set(ids).size;
+    }
+    /** Field-level write permissions, ownership assignment and cross-tenant integrity of relations and files. */
+    async checkWrite(entity, data, ctx, existing) {
+        const denied = await unwritableFields(entity, data, ctx.principal, existing ?? data, this.policyCheck(entity, ctx));
+        if (denied.length)
+            throw new ForbiddenException(`You cannot change ${denied.map((f) => f.label).join(", ")}`);
+        const issues = [];
+        for (const f of entity.fields) {
+            const problem = f.relation?.type === "many-to-many"
+                ? await this.checkManyToMany(f, data, ctx)
+                : f.file
+                    ? await this.checkFile(entity, f, data, ctx, existing)
+                    : f.relation
+                        ? await this.checkManyToOne(f, data, ctx, existing)
+                        : null;
+            if (problem)
+                issues.push(problem);
+        }
+        if (issues.length)
+            throw invalid(issues);
+    }
+    async checkManyToMany(f, data, ctx) {
+        const ids = manyIds(data, f);
+        if (!ids || (await this.relationTargetsExist(f, ids, ctx)))
+            return null;
+        return { path: f.apiName, message: `Some ${f.label.toLowerCase()} were not found` };
+    }
+    async checkFile(entity, f, data, ctx, existing) {
+        const fileId = data[f.apiName];
+        if (typeof fileId !== "string" || existing?.[f.apiName] === fileId)
+            return null;
+        const error = await this.options.files.validateAttachment(this.prisma, { entity, field: f, fileId, ctx, ...(existing ? { recordId: existing.id } : {}) });
+        return error ? { path: f.apiName, message: error } : null;
+    }
+    async checkManyToOne(f, data, ctx, existing) {
+        const rel = f.relation;
+        const value = data[rel.foreignKey];
+        if (value === undefined || value === null || existing?.[rel.foreignKey] === value)
+            return null;
+        const principal = ctx.principal;
+        if (rel.owner && value !== actingUserId(ctx) && !principal.roles.includes("admin")) {
+            throw new ForbiddenException(`Only admins can assign the ${f.label.toLowerCase()} to another user`);
+        }
+        if (rel.entity === "Team" && !principal.roles.includes("admin") && !(principal.teamIds ?? []).includes(value)) {
+            throw new ForbiddenException("You can only assign records to teams you belong to");
+        }
+        return (await this.relationTargetsExist(f, [value], ctx)) ? null : { path: rel.foreignKey, message: `${f.label} not found` };
+    }
+    /** Attach newly referenced files; returns ids of files no longer referenced (released after commit). */
+    async syncFiles(db, entity, record, previous) {
+        const released = [];
+        for (const f of entity.fields) {
+            if (!f.file)
+                continue;
+            const now = record?.[f.apiName] ?? null;
+            const before = previous?.[f.apiName] ?? null;
+            if (now === before)
+                continue;
+            if (now)
+                await this.options.files.attach(db, { entity, field: f, fileId: now, recordId: record.id });
+            if (before)
+                released.push(before);
+        }
+        return released;
+    }
+    async audit(db, entity, ctx, action, recordId, changes) {
+        if (!entity.features.audit)
+            return;
+        await db.auditLog.create({
+            data: {
+                entity: entity.storageName,
+                recordId,
+                action,
+                // API keys are recorded as the actor themselves, never as their creator.
+                userId: ctx.apiKey ? null : (ctx.principal?.id ?? null),
+                ...(ctx.apiKey ? { apiKeyId: ctx.apiKey.id } : {}),
+                ...(this.app.tenancy.enabled ? { organizationId: ctx.principal?.organizationId ?? null } : {}),
+                changes: changes ? { ...changes, ...(ctx.session?.impersonatedBy ? { _impersonatedBy: ctx.session.impersonatedBy } : {}) } : undefined,
+                ipAddress: ctx.ip ?? null,
+            },
+        });
+    }
+    async emit(entity, action, ctx, record, extra) {
+        const event = {
+            id: randomUUID(),
+            type: `${entity.name}.${action}`,
+            entity: entity.name,
+            action,
+            record: record ? serialize(entity, record, { apiPrefix: this.app.api.prefix }) : null,
+            actor: ctx.user ? { id: ctx.user.id, name: ctx.user.name } : ctx.apiKey ? { id: `apikey:${ctx.apiKey.id}`, name: `API key "${ctx.apiKey.name}"` } : null,
+            organizationId: ctx.principal?.organizationId ?? record?.organizationId ?? null,
+            occurredAt: new Date().toISOString(),
+            ...extra,
+        };
+        await this.events.emit(event);
+    }
+    tx(fn) {
+        return this.prisma.$transaction(fn, TX);
+    }
+    // ─── CRUD ───────────────────────────────────────────────────────────────────
+    async list(entity, query, ctx) {
+        const decision = this.authorizeOp(entity, "read", ctx);
+        const q = this.parse(entity, query, ctx);
+        const where = { AND: [...this.baseWhere(entity, ctx, q.trashed), ...this.scopeWhere(entity, decision, ctx), ...q.where] };
+        const [total, rows] = await this.prisma.$transaction([
+            this.delegate(entity).count({ where }),
+            this.delegate(entity).findMany({ where, orderBy: q.orderBy, skip: (q.page - 1) * q.pageSize, take: q.pageSize, include: relationInclude(entity) }),
+        ]);
+        return {
+            data: await Promise.all(rows.map((r) => this.present(entity, r, ctx))),
+            meta: { page: q.page, pageSize: q.pageSize, total, pages: Math.max(1, Math.ceil(total / q.pageSize)) },
+        };
+    }
+    async exportCsv(entity, query, ctx) {
+        if (!entity.features.export)
+            throw new NotFoundException("Export is disabled for this resource");
+        const decision = this.authorizeOp(entity, "read", ctx);
+        const q = this.parse(entity, { ...query, page: 1, pageSize: 1 }, ctx);
+        const rows = await this.delegate(entity).findMany({
+            where: { AND: [...this.baseWhere(entity, ctx, q.trashed), ...this.scopeWhere(entity, decision, ctx), ...q.where] },
+            orderBy: q.orderBy,
+            take: EXPORT_LIMIT,
+            include: relationInclude(entity),
+        });
+        // Columns the caller can never read are dropped; per-record restrictions leave empty cells.
+        const queryable = queryableFields(entity, ctx.principal);
+        const hidden = new Set(entity.fields.filter((f) => f.access?.read && !queryable.has(f.name) && !evaluate(f.access.read, ctx.principal).allowed).map((f) => f.name));
+        return toCsv(entity, await Promise.all(rows.map((r) => this.present(entity, r, ctx))), hidden);
+    }
+    async get(entity, id, ctx, query = {}) {
+        this.authorizeOp(entity, "read", ctx);
+        const trashed = entity.features.softDelete && query.trashed === "with" ? "with" : "without";
+        return this.present(entity, await this.loadFor(entity, id, "read", ctx, { trashed }), ctx);
+    }
+    async create(entity, body, ctx, options = {}) {
+        const decision = this.authorizeOp(entity, "create", ctx);
+        let data = this.validate(entity, "create", body);
+        if (entity.ownerField) {
+            const fk = entity.fields.find((f) => f.name === entity.ownerField).relation.foreignKey;
+            data[fk] ??= actingUserId(ctx);
+        }
+        if (entity.workflow)
+            data[entity.workflow.field] = entity.workflow.initial;
+        await this.checkWrite(entity, data, ctx);
+        if (decision.scope === "conditional" && !(await allowsRecord(entity, decision, ctx.principal, data, this.policyCheck(entity, ctx)))) {
+            throw new ForbiddenException("You do not have permission to perform this action");
+        }
+        const hooks = this.extensions.get(entity.name)?.hooks;
+        const include = relationInclude(entity);
+        const record = await this.tx(async (db) => {
+            data = (await hooks?.beforeCreate?.({ ...this.hookContext(entity, ctx, db), data })) ?? data;
+            if (entity.features.tenant)
+                data.organizationId = ctx.principal.organizationId;
+            let row = await this.delegate(entity, db).create({ data: this.finalizeJson(data), include });
+            row = await this.computed.refresh(db, entity, row, include);
+            await this.syncFiles(db, entity, row, null);
+            await this.computed.refreshParents(db, entity, null, row);
+            await this.audit(db, entity, ctx, options.auditAction ?? "create", row.id, { after: serialize(entity, row) });
+            return row;
+        });
+        await this.emit(entity, "created", ctx, record, { recordId: record.id });
+        await hooks?.afterCreate?.({ ...this.hookContext(entity, ctx), record });
+        return this.present(entity, record, ctx);
+    }
+    async update(entity, id, body, ctx) {
+        this.authorizeOp(entity, "update", ctx);
+        const existing = await this.loadFor(entity, id, "update", ctx);
+        let data = this.validate(entity, "update", body);
+        const nulls = entity.fields.filter((f) => f.required && f.apiName in data && data[f.apiName] === null).map((f) => ({ path: f.apiName, message: "Required" }));
+        if (nulls.length)
+            throw invalid(nulls);
+        await this.checkWrite(entity, data, ctx, existing);
+        const hooks = this.extensions.get(entity.name)?.hooks;
+        const include = relationInclude(entity);
+        let released = [];
+        const record = await this.tx(async (db) => {
+            data = (await hooks?.beforeUpdate?.({ ...this.hookContext(entity, ctx, db), data, existing })) ?? data;
+            let row = await this.delegate(entity, db).update({ where: { id }, data: this.finalizeJson(data), include });
+            row = await this.computed.refresh(db, entity, row, include);
+            released = await this.syncFiles(db, entity, row, existing);
+            await this.computed.refreshParents(db, entity, existing, row);
+            const changes = diff(serialize(entity, existing), serialize(entity, row));
+            if (Object.keys(changes).length)
+                await this.audit(db, entity, ctx, "update", id, changes);
+            return row;
+        });
+        if (released.length)
+            await this.options.files.release(released);
+        await this.emit(entity, "updated", ctx, record, {
+            recordId: id,
+            previous: serialize(entity, existing, { apiPrefix: this.app.api.prefix }),
+            changes: diff(serialize(entity, existing), serialize(entity, record)),
+        });
+        await hooks?.afterUpdate?.({ ...this.hookContext(entity, ctx), record, previous: existing });
+        return this.present(entity, record, ctx);
+    }
+    async remove(entity, id, ctx) {
+        this.authorizeOp(entity, "delete", ctx);
+        const record = await this.loadFor(entity, id, "delete", ctx);
+        const hooks = this.extensions.get(entity.name)?.hooks;
+        let released = [];
+        await this.tx(async (db) => {
+            await hooks?.beforeDelete?.({ ...this.hookContext(entity, ctx, db), record });
+            if (entity.features.softDelete)
+                await this.delegate(entity, db).update({ where: { id }, data: { deletedAt: new Date() } });
+            else {
+                await this.delegate(entity, db).delete({ where: { id } });
+                released = entity.fields.filter((f) => f.file && record[f.apiName]).map((f) => record[f.apiName]);
+            }
+            await this.computed.refreshParents(db, entity, record, null);
+            await this.audit(db, entity, ctx, entity.features.softDelete ? "soft-delete" : "delete", id, { before: serialize(entity, record) });
+        });
+        if (released.length)
+            await this.options.files.release(released);
+        await this.emit(entity, "deleted", ctx, record, { recordId: id });
+        await hooks?.afterDelete?.({ ...this.hookContext(entity, ctx), record });
+    }
+    async bulkDelete(entity, body, ctx) {
+        if (!entity.features.bulkDelete)
+            throw new NotFoundException("Bulk delete is disabled for this resource");
+        const ids = body?.ids;
+        if (!Array.isArray(ids) || ids.length === 0 || ids.length > 500 || !ids.every((i) => typeof i === "string")) {
+            throw new BadRequestException("ids must be an array of 1–500 record ids");
+        }
+        let deleted = 0;
+        for (const id of new Set(ids)) {
+            await this.remove(entity, id, ctx);
+            deleted++;
+        }
+        return { deleted };
+    }
+    async restore(entity, id, ctx) {
+        if (!entity.features.softDelete)
+            throw new NotFoundException(`${entity.label} does not support restore`);
+        this.authorizeOp(entity, "update", ctx);
+        await this.loadFor(entity, id, "update", ctx, { trashed: "only" });
+        const include = relationInclude(entity);
+        const record = await this.tx(async (db) => {
+            const row = await this.delegate(entity, db).update({ where: { id }, data: { deletedAt: null }, include });
+            await this.computed.refreshParents(db, entity, null, row);
+            await this.audit(db, entity, ctx, "restore", id, {});
+            return row;
+        });
+        await this.emit(entity, "restored", ctx, record, { recordId: id });
+        return this.present(entity, record, ctx);
+    }
+    async transition(entity, id, name, body, ctx) {
+        const wf = entity.workflow;
+        const t = wf?.transitions.find((x) => x.name === name);
+        if (!wf || !t)
+            throw new NotFoundException(`Unknown transition "${name}"`);
+        const record = await this.loadFor(entity, id, "update", ctx, { rule: t.permission });
+        const from = record[wf.field];
+        if (t.from.length && !t.from.includes(from)) {
+            throw new ConflictException(`Cannot "${t.label}" a ${entity.label.toLowerCase()} that is ${from} (allowed from: ${t.from.join(", ")})`);
+        }
+        const ext = this.extensions.get(entity.name)?.transitions?.[name];
+        const verdict = await ext?.guard?.({ ...this.hookContext(entity, ctx), record, input: (body ?? {}) });
+        if (verdict === false || typeof verdict === "string")
+            throw new ConflictException(typeof verdict === "string" ? verdict : `"${t.label}" is not possible right now`);
+        const include = relationInclude(entity);
+        const updated = await this.tx(async (db) => {
+            let row = await this.delegate(entity, db).update({ where: { id }, data: { [wf.field]: t.to }, include });
+            row = await this.computed.refresh(db, entity, row, include);
+            await this.computed.refreshParents(db, entity, record, row);
+            await this.audit(db, entity, ctx, `transition:${name}`, id, { [wf.field]: { from, to: t.to } });
+            return row;
+        });
+        await this.emit(entity, "transitioned", ctx, updated, {
+            recordId: id,
+            name,
+            previous: serialize(entity, record, { apiPrefix: this.app.api.prefix }),
+            changes: { [wf.field]: { from, to: t.to } },
+        });
+        await ext?.after?.({ ...this.hookContext(entity, ctx), record: updated, previous: record, input: (body ?? {}) });
+        return this.present(entity, updated, ctx);
+    }
+    async runAction(entity, id, name, body, ctx) {
+        const action = entity.actions.find((a) => a.name === name);
+        if (!action)
+            throw new NotFoundException(`Unknown action "${name}"`);
+        const handler = this.extensions.get(entity.name)?.actions?.[name];
+        if (!handler)
+            throw new NotImplementedException(`Action "${name}" has no handler — implement it in ${entity.name.toLowerCase()}.extension.ts`);
+        const record = await this.loadFor(entity, id, "update", ctx, { rule: action.permission });
+        const result = await handler({ ...this.hookContext(entity, ctx), record, input: (body ?? {}) });
+        // Actions may change the record through prisma directly; keep computed values and parents current.
+        const fresh = await this.delegate(entity).findUnique({ where: { id }, include: relationInclude(entity) });
+        if (fresh) {
+            await this.tx(async (db) => {
+                const row = await this.computed.refresh(db, entity, fresh);
+                await this.computed.refreshParents(db, entity, record, row);
+                await this.audit(db, entity, ctx, `action:${name}`, id, {});
+            });
+        }
+        await this.emit(entity, "action", ctx, fresh, { recordId: id, name });
+        return { ok: true, result: result ?? null };
+    }
+    async lookup(entity, query, ctx) {
+        const decision = this.authorizeOp(entity, "read", ctx);
+        const where = [...this.baseWhere(entity, ctx), ...this.scopeWhere(entity, decision, ctx)];
+        const ids = typeof query.ids === "string" && query.ids ? query.ids.split(",") : undefined;
+        if (ids)
+            where.push({ id: { in: ids.slice(0, 100) } });
+        const search = typeof query.search === "string" ? searchWhere(entity, query.search, this.queryAccess(entity, ctx)) : undefined;
+        if (search)
+            where.push(search);
+        const displayIsField = entity.fields.some((f) => f.name === entity.display);
+        const rows = await this.delegate(entity).findMany({
+            where: { AND: where },
+            take: ids ? 100 : 20,
+            orderBy: displayIsField ? { [entity.display]: "asc" } : { id: "asc" },
+            select: { id: true, ...(displayIsField ? { [entity.display]: true } : {}) },
+        });
+        return { data: rows.map((r) => ({ id: r.id, label: label(entity, r) })) };
+    }
+    async lookupUsers(query, ctx) {
+        if (!ctx.principal)
+            throw new UnauthorizedException("Sign in to continue");
+        const where = [];
+        if (this.app.tenancy.enabled)
+            where.push({ members: { some: { organizationId: ctx.principal.organizationId ?? "__none__" } } });
+        const ids = typeof query.ids === "string" && query.ids ? query.ids.split(",") : undefined;
+        if (ids)
+            where.push({ id: { in: ids.slice(0, 100) } });
+        if (typeof query.search === "string" && query.search.trim()) {
+            const t = query.search.trim();
+            where.push({ OR: [{ name: { contains: t, mode: "insensitive" } }, { email: { contains: t, mode: "insensitive" } }] });
+        }
+        const rows = await this.prisma.user.findMany({ where: { AND: where }, take: ids ? 100 : 20, orderBy: { name: "asc" }, select: { id: true, name: true } });
+        return { data: rows.map((u) => ({ id: u.id, label: u.name })) };
+    }
+    async stats(ctx) {
+        const out = [];
+        for (const entity of this.app.entities) {
+            const decision = authorize(entity, "read", ctx.principal);
+            if (!decision.allowed || (entity.features.tenant && !ctx.principal?.organizationId))
+                continue;
+            const count = await this.delegate(entity).count({ where: { AND: [...this.baseWhere(entity, ctx), ...this.scopeWhere(entity, decision, ctx)] } });
+            out.push({ entity: entity.name, path: entity.path, label: entity.pluralLabel, count });
+        }
+        return { data: out };
+    }
+    async auditLogs(query, ctx) {
+        if (!ctx.principal)
+            throw new UnauthorizedException("Sign in to continue");
+        if (!ctx.principal.roles.includes("admin"))
+            throw new ForbiddenException("Only admins can view audit logs");
+        if (ctx.principal.scopes && !scopeAllows(ctx.principal.scopes, "audit-logs", "read"))
+            throw new ForbiddenException("This API key has no scope for the audit log");
+        const page = Math.max(1, Number(query.page) || 1);
+        const pageSize = Math.min(200, Math.max(1, Number(query.pageSize) || 50));
+        const where = {};
+        if (this.app.tenancy.enabled)
+            where.organizationId = ctx.principal.organizationId ?? "__none__";
+        for (const key of ["entity", "recordId", "userId", "action", "apiKeyId"])
+            if (typeof query[key] === "string" && query[key] && (key !== "apiKeyId" || /^[0-9a-f-]{36}$/i.test(query[key])))
+                where[key] = query[key];
+        // Rows are keyed on the storage name; the API speaks entity names.
+        if (typeof where.entity === "string")
+            where.entity = this.byName.get(where.entity)?.storageName ?? where.entity;
+        const [total, rows] = await this.prisma.$transaction([
+            this.prisma.auditLog.count({ where }),
+            this.prisma.auditLog.findMany({
+                where,
+                orderBy: { createdAt: "desc" },
+                skip: (page - 1) * pageSize,
+                take: pageSize,
+                include: { user: { select: { id: true, name: true, email: true } }, apiKey: { select: { id: true, name: true, prefix: true } } },
+            }),
+        ]);
+        // Values of fields the viewer may not read are redacted from change history.
+        const data = rows.map((row) => {
+            const entity = this.byStorage.get(row.entity);
+            const log = entity ? { ...row, entity: entity.name } : row;
+            if (!entity || !log.changes)
+                return log;
+            const secret = entity.fields.filter((f) => f.access?.read && !evaluate(f.access.read, ctx.principal).allowed);
+            if (!secret.length)
+                return log;
+            const redact = (obj) => {
+                if (!obj)
+                    return obj;
+                const out = { ...obj };
+                for (const f of secret)
+                    for (const k of [f.name, f.apiName])
+                        if (k in out)
+                            out[k] = "[redacted]";
+                return out;
+            };
+            const changes = redact(log.changes);
+            if (changes.after)
+                changes.after = redact(changes.after);
+            if (changes.before)
+                changes.before = redact(changes.before);
+            return { ...log, changes };
+        });
+        return { data, meta: { page, pageSize, total, pages: Math.max(1, Math.ceil(total / pageSize)) } };
+    }
+    parse(entity, query, ctx) {
+        try {
+            return parseListQuery(entity, query, this.queryAccess(entity, ctx));
+        }
+        catch (err) {
+            if (err instanceof QueryError)
+                throw new BadRequestException({ statusCode: 400, error: "Bad Request", message: err.message });
+            throw err;
+        }
+    }
+}
+/** The person a write is made for: the signed-in user, or the creator of the API key in use. */
+export function actingUserId(ctx) {
+    return ctx.apiKey ? (ctx.apiKey.createdById ?? "") : ctx.principal.id;
+}
+/**
+ * Run both hook sets: the added hooks first (e.g. plugin limits), then the existing ones (your extension).
+ * before* hooks may return replacement data, which is passed along the chain.
+ */
+export function composeHooks(existing, added) {
+    if (!existing)
+        return added;
+    if (!added)
+        return existing;
+    const out = {};
+    const keys = new Set([...Object.keys(existing), ...Object.keys(added)]);
+    for (const key of keys) {
+        const first = added[key];
+        const second = existing[key];
+        if (!first || !second) {
+            out[key] = first ?? second;
+            continue;
+        }
+        out[key] = async (ctx) => {
+            const r1 = await first(ctx);
+            const next = r1 !== undefined && "data" in ctx ? { ...ctx, data: r1 } : ctx;
+            const r2 = await second(next);
+            return r2 !== undefined ? r2 : r1;
+        };
+    }
+    return out;
+}
+//# sourceMappingURL=service.js.map