@tekki-forge/runtime-api 0.1.0

package/dist/service.d.ts

@@ -0,0 +1,168 @@
+import type { AppIR, EntityIR, FieldIR, Operation, PermissionIR } from "@tekki-forge/compiler";
+import { type Decision } from "@tekki-forge/runtime-permissions";
+import { ComputedEngine } from "./computed.js";
+import { EventBus } from "./events.js";
+import { NotificationService, type MailSender } from "./notifications.js";
+import type { EntityExtension, EntityHooks, ForgeRequestContext, HookContext } from "./extension.js";
+import { type QueryAccess } from "./query.js";
+import { ApiKeyService } from "./api-keys.js";
+type Row = Record<string, any>;
+type Db = any;
+/** Provided by the storage plugin; required when the schema has file or image fields. */
+export interface FileStore {
+    /** Check that `fileId` may be attached to this field (uploaded here, right field, caller allowed). Returns an error message or null. */
+    validateAttachment(db: Db, input: {
+        entity: EntityIR;
+        field: FieldIR;
+        fileId: string;
+        ctx: ForgeRequestContext;
+        recordId?: string;
+    }): Promise<string | null>;
+    attach(db: Db, input: {
+        entity: EntityIR;
+        field: FieldIR;
+        fileId: string;
+        recordId: string;
+    }): Promise<void>;
+    /** Called after commit for files that are no longer referenced. */
+    release(fileIds: string[]): Promise<void>;
+}
+export interface ForgeServiceOptions {
+    app: AppIR;
+    prisma: any;
+    auth: any;
+    extensions?: EntityExtension[];
+    /** `Prisma.DbNull` from the generated client, used to clear JSON columns. */
+    dbNull?: unknown;
+    /** Social providers with credentials configured; exposed to the sign-in page. */
+    socialProviders?: string[];
+    events?: EventBus;
+    files?: FileStore;
+    /** Templated mail service (from @tekki-forge/emails createMail). */
+    mail?: MailSender;
+}
+export declare class ForgeService {
+    private readonly options;
+    readonly app: AppIR;
+    readonly prisma: any;
+    readonly auth: any;
+    readonly socialProviders: string[];
+    readonly events: EventBus;
+    readonly computed: ComputedEngine;
+    readonly notifications: NotificationService;
+    readonly apiKeys: ApiKeyService;
+    /** Services shared between plugins and exposed to hooks via ctx.use(name). */
+    readonly shared: Map<string, unknown>;
+    private readonly byPath;
+    private readonly byName;
+    private readonly byStorage;
+    private readonly extensions;
+    constructor(options: ForgeServiceOptions);
+    /** Plugins attach behaviour (hooks, actions, event handlers) to the entities they contribute. */
+    addExtension(ext: EntityExtension): void;
+    /** Used by the storage plugin during setup. */
+    useFileStore(store: FileStore): void;
+    /** Startup check once plugins have been set up. */
+    assertReady(): void;
+    entity(path: string): EntityIR;
+    entityByName(name: string): EntityIR | undefined;
+    /** The entity rows were stored under (`files.entity`, `audit_logs.entity`…): stable across renames. */
+    entityByStorageName(storageName: string): EntityIR | undefined;
+    resolveContext(headers: Headers, ip?: string): Promise<ForgeRequestContext>;
+    get mail(): MailSender | undefined;
+    hookContext(entity: EntityIR, ctx: ForgeRequestContext, db?: Db): HookContext;
+    private require;
+    authorizeOp(entity: EntityIR, op: Operation, ctx: ForgeRequestContext): Extract<Decision, {
+        allowed: true;
+    }>;
+    private requireTenant;
+    baseWhere(entity: EntityIR, ctx: ForgeRequestContext, trashed?: "without" | "with" | "only"): Row[];
+    /** Prisma condition restricting a conditional decision (owner / policies) on lists. */
+    scopeWhere(entity: EntityIR, decision: Extract<Decision, {
+        allowed: true;
+    }>, ctx: ForgeRequestContext): Row[];
+    /** Full read scope for the caller: tenancy, soft delete and row-level permissions. */
+    readWhere(entity: EntityIR, ctx: ForgeRequestContext, trashed?: "without" | "with" | "only"): Row[];
+    policyCheck(entity: EntityIR, ctx: ForgeRequestContext): (name: string, record: Row) => boolean | Promise<boolean>;
+    queryAccess(entity: EntityIR, ctx: ForgeRequestContext): QueryAccess;
+    /** Load a record the caller may apply `op` (or `rule`) to; 404 when they cannot even see it. Raw Prisma row. */
+    loadFor(entity: EntityIR, id: string, op: Operation, ctx: ForgeRequestContext, opts?: {
+        trashed?: "without" | "with" | "only";
+        rule?: PermissionIR;
+    }): Promise<Row>;
+    delegate(entity: EntityIR, db?: Db): any;
+    /** Serialize for this caller, dropping fields they may not read. */
+    present(entity: EntityIR, record: Row, ctx: ForgeRequestContext): Promise<Row>;
+    /** Explain why read-only keys cannot be written instead of a generic "unknown field". */
+    private rejectReadOnly;
+    private validate;
+    private finalizeJson;
+    private relationTargetsExist;
+    /** Field-level write permissions, ownership assignment and cross-tenant integrity of relations and files. */
+    private checkWrite;
+    private checkManyToMany;
+    private checkFile;
+    private checkManyToOne;
+    /** Attach newly referenced files; returns ids of files no longer referenced (released after commit). */
+    private syncFiles;
+    private audit;
+    private emit;
+    private tx;
+    list(entity: EntityIR, query: Row, ctx: ForgeRequestContext): Promise<{
+        data: any[];
+        meta: {
+            page: number;
+            pageSize: number;
+            total: any;
+            pages: number;
+        };
+    }>;
+    exportCsv(entity: EntityIR, query: Row, ctx: ForgeRequestContext): Promise<string>;
+    get(entity: EntityIR, id: string, ctx: ForgeRequestContext, query?: Row): Promise<Row>;
+    create(entity: EntityIR, body: unknown, ctx: ForgeRequestContext, options?: {
+        auditAction?: string;
+    }): Promise<Row>;
+    update(entity: EntityIR, id: string, body: unknown, ctx: ForgeRequestContext): Promise<Row>;
+    remove(entity: EntityIR, id: string, ctx: ForgeRequestContext): Promise<void>;
+    bulkDelete(entity: EntityIR, body: unknown, ctx: ForgeRequestContext): Promise<{
+        deleted: number;
+    }>;
+    restore(entity: EntityIR, id: string, ctx: ForgeRequestContext): Promise<Row>;
+    transition(entity: EntityIR, id: string, name: string, body: unknown, ctx: ForgeRequestContext): Promise<Row>;
+    runAction(entity: EntityIR, id: string, name: string, body: unknown, ctx: ForgeRequestContext): Promise<{
+        ok: boolean;
+        result: {} | null;
+    }>;
+    lookup(entity: EntityIR, query: Row, ctx: ForgeRequestContext): Promise<{
+        data: any;
+    }>;
+    lookupUsers(query: Row, ctx: ForgeRequestContext): Promise<{
+        data: any;
+    }>;
+    stats(ctx: ForgeRequestContext): Promise<{
+        data: {
+            entity: string;
+            path: string;
+            label: string;
+            count: number;
+        }[];
+    }>;
+    auditLogs(query: Row, ctx: ForgeRequestContext): Promise<{
+        data: any;
+        meta: {
+            page: number;
+            pageSize: number;
+            total: any;
+            pages: number;
+        };
+    }>;
+    private parse;
+}
+/** The person a write is made for: the signed-in user, or the creator of the API key in use. */
+export declare function actingUserId(ctx: ForgeRequestContext): string;
+/**
+ * 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 declare function composeHooks(existing?: EntityHooks, added?: EntityHooks): EntityHooks | undefined;
+export {};