@beechcms/api 0.6.7 → 0.8.0

package/dist/features/seeds/seeds.helpers.d.ts

@@ -0,0 +1,118 @@
+import type { Context } from 'hono';
+import type { Branch, Seed } from '@beechcms/core';
+import { SLUG_RE, SEED_SLUG_RE } from '@beechcms/core';
+import type { Env, Variables } from '../../types';
+export type AppContext = Context<{
+    Bindings: Env;
+    Variables: Variables;
+}>;
+export { SLUG_RE, SEED_SLUG_RE };
+/**
+ * Guard ensuring the authenticated caller possesses the `'admin'` role.
+ *
+ * @param context - The Hono request context with bound JWT payload variables.
+ * @returns A 403 Forbidden RFC 7807 Problem Details Response if unauthorized, or `null` if authorized.
+ */
+export declare function requireAdmin(context: AppContext): Response | null;
+/**
+ * Extracts audit logging actor metadata from the request's JWT payload.
+ *
+ * @param context - The Hono request context.
+ * @returns The actor representation containing user ID (`sub`), email address, and formatted full name.
+ */
+export declare function actorFromContext(context: AppContext): {
+    id: string;
+    email: string;
+    name: string | null;
+};
+/**
+ * Safely parses the incoming HTTP request body as JSON.
+ *
+ * @param context - The Hono request context.
+ * @returns The parsed JSON body payload, or a 400 Bad Request Problem Details Response on syntax failure.
+ */
+export declare function parseJsonBody(context: AppContext): Promise<unknown>;
+/**
+ * Retrieves an active seed record by slug from the database repository.
+ *
+ * @param context - The Hono request context.
+ * @param slug - The unique slug identifier of the seed.
+ * @returns The active seed entity record, or a 404 Not Found Problem Details Response if nonexistent or soft-deleted.
+ */
+export declare function getActiveSeed(context: AppContext, slug: string): Promise<Response | import("@beechcms/core").SeedRecord>;
+/**
+ * Validates a candidate seed definition against active system seeds and applies additive schema mutations.
+ *
+ * @remarks
+ * 1. Checks relational constraints, duplicate aliases, and format validity across all active seeds.
+ * 2. Compares definition against physical database columns (`content_<slug>`).
+ * 3. Plans and executes DDL via `planCreateSeed` (new table) or `planExtendSeed` (additive columns).
+ * 4. Upserts definition into `SeedRepository` with `'runtime'` source and bumps the registry version for OCC.
+ * 5. Dispatches an audit event to the activity logger.
+ *
+ * @param context - The Hono request context.
+ * @param slug - The target seed slug.
+ * @param candidate - The proposed seed definition.
+ * @param action - Action tag for activity logging (`'create'` or `'update'`).
+ * @param logDetails - Metadata payload for audit trail recording.
+ * @returns `null` upon successful execution, or a 422 Unprocessable Entity Problem Details Response on validation or DDL failure.
+ */
+export declare function validateAndApplySeedDef(context: AppContext, slug: string, candidate: Seed, action: 'create' | 'update', logDetails: any): Promise<Response | null>;
+/**
+ * Executes destructive DDL statements and persists the updated seed definition.
+ *
+ * @remarks
+ * Used for operations that cannot be planned additively (e.g. column drops, renames, and type conversions).
+ * Runs SQL statements through `schemaMutator.execDestructive`, updates the stored definition,
+ * increments the schema registry version, and logs the operation.
+ *
+ * @param context - The Hono request context.
+ * @param slug - The unique slug identifier of the seed.
+ * @param updatedDef - The new seed definition reflecting the destructive change.
+ * @param stmts - The SQL DDL statements generated for the destructive migration.
+ * @param logDetails - Operation details for the audit log.
+ * @returns `null` on success, or a 422 Unprocessable Entity Problem Details Response on DDL execution failure.
+ */
+export declare function applyDestructiveSeedDef(context: AppContext, slug: string, updatedDef: Seed, stmts: string[], logDetails: any): Promise<Response | null>;
+/**
+ * Typed confirmation guard for destructive operations.
+ *
+ * @remarks
+ * Validates that the request body contains a string field `confirm` matching `expected`
+ * (e.g. `<slug>` for hard drops, or `<slug>.<branchAlias>` for column drops/renames/retypes).
+ *
+ * @param context - The Hono request context.
+ * @param expected - Expected confirmation token string.
+ * @param body - Parsed request body object.
+ * @returns `null` if confirmation matches, or a 400 Bad Request Problem Details Response on mismatch.
+ */
+export declare function requireConfirm(context: AppContext, expected: string, body: unknown): Response | null;
+/**
+ * Validates incoming branches during a definition update (PUT) to reject unconfirmed destructive operations.
+ *
+ * @remarks
+ * Compares incoming branches against stored definitions by ID. If an alias rename or branch type change
+ * is detected, rejects the request with a 422 error pointing the caller to dedicated PATCH endpoints.
+ * Automatically allocates next sequential branch IDs for any newly appended branches lacking an ID.
+ *
+ * @param incomingBranches - Branch definitions provided in the update payload.
+ * @param storedBranches - Currently persisted branch definitions in the repository.
+ * @param slug - The seed slug being updated.
+ * @param context - The Hono request context.
+ * @returns `null` if valid, or a 422 Unprocessable Entity Problem Details Response on rejected destructive changes.
+ */
+export declare function validateIncomingBranches(incomingBranches: Branch[], storedBranches: Branch[], slug: string, context: AppContext): Response | null;
+/**
+ * Scans content records of a seed to extract and delete referenced R2 media objects before table deletion.
+ *
+ * @remarks
+ * Gathers all file branches defined on the seed, selects their column values from `content_<slug>`,
+ * extracts storage object keys, and deletes them from Cloudflare R2 storage in batches.
+ * Any errors encountered during cleanup are treated as non-fatal warnings to allow table drop to proceed.
+ *
+ * @param context - The Hono request context.
+ * @param slug - The seed slug whose media assets are being purged.
+ * @param seed - The seed definition containing branch configurations.
+ * @param schemaMutator - Schema mutator instance used to query existing database columns.
+ */
+export declare function deleteSeedMediaObjects(context: AppContext, slug: string, seed: Seed, schemaMutator: any): Promise<void>;

package/dist/features/seeds/seeds.mcp.d.ts

@@ -0,0 +1,37 @@
+import { Hono } from 'hono';
+import type { Seed } from '@beechcms/core';
+import type { Env, Variables } from '../../types';
+/**
+ * Normalizes a candidate seed definition for MCP operations:
+ * - Preserves existing branch IDs from stored definition by alias matching if omitted.
+ * - Auto-assigns sequential branch IDs via `nextBranchId` for new branches that lack one.
+ * - Defaults `displayNameAlias` from stored definition or first text branch if omitted.
+ */
+export declare function normalizeCandidate(candidate: Seed, storedDef: Seed | null): Seed;
+/**
+ * Classification of schema migration intent for MCP agents:
+ * - `'create'`: Seed does not exist; requires initial table and index creation.
+ * - `'additive'`: Additive schema extensions (adding new columns/branches).
+ * - `'destructive'`: Involves dropping, renaming, or retyping columns; disallowed in generic MCP apply.
+ */
+export type McpClassification = 'create' | 'additive' | 'destructive';
+/**
+ * Diffs a proposed candidate seed against the stored seed definition to detect destructive intent.
+ *
+ * @remarks
+ * Evaluates whether any branches are omitted (drops), have altered aliases (renames),
+ * or have changed types. Because `planExtendSeed` is strictly additive and cannot emit destructive DDL,
+ * destructive intent must be classified here to reject or require confirmation.
+ *
+ * @param stored - Stored seed definition from the repository, or `null` if creating.
+ * @param candidate - Proposed candidate seed definition.
+ * @returns An object with the classification (`create`, `additive`, or `destructive`) and a list of blocking reasons.
+ */
+export declare function classifyCandidate(stored: Seed | null, candidate: Seed): {
+    classification: McpClassification;
+    blockedReasons: string[];
+};
+export declare const mcpApp: Hono<{
+    Bindings: Env;
+    Variables: Variables;
+}, import("hono/types").BlankSchema, "/">;

package/dist/features/upload/index.d.ts

@@ -2,8 +2,8 @@
  * Upload feature — presigned R2 uploads and media serving.
  * The Worker never receives file bytes: it acts as auth gatekeeper and signer only.
  */
-import { Hono } from 'hono';
+import { Hono, type Context } from 'hono';
 import { AppEnv } from '../../types';
 export declare const uploadRoutes: Hono<AppEnv, import("hono/types").BlankSchema, "/">;
 /** Serve a file from storage (used by the public /api/media/:key route). */
-export declare function serveMediaHandler(c: any): Promise<Response>;
+export declare function serveMediaHandler(c: Context<AppEnv>): Promise<Response>;