@beechcms/api 0.6.0-preview.1 → 0.6.0-preview.3

package/dist/shared/idempotency.repository.d1.d.ts

@@ -0,0 +1,16 @@
+import { IdempotencyRepository, IdempotencyRecord } from '@beechcms/core';
+import { BaseD1Repository } from './base.repository.d1.js';
+export declare class D1IdempotencyRepository extends BaseD1Repository implements IdempotencyRepository {
+    /**
+     * Looks up an idempotency record by its key.
+     */
+    lookup(idempotencyKey: string): Promise<IdempotencyRecord | null>;
+    /**
+     * Stores or updates an idempotency record.
+     */
+    store(idempotencyData: IdempotencyRecord): Promise<void>;
+    /**
+     * Cleans up expired idempotency records.
+     */
+    cleanup(expirationTimestamp: number): Promise<void>;
+}

package/dist/shared/in-memory-activity-logger.d.ts

@@ -0,0 +1,11 @@
+import type { IActivityLogger, ActivityLogEntry } from '@beechcms/core';
+/**
+ * Test double for {@link IActivityLogger}.
+ *
+ * Captures every call into a public array so test assertions can verify
+ * audit-trail side effects without touching D1. Preserves insertion order.
+ */
+export declare class InMemoryActivityLogger implements IActivityLogger {
+    readonly entries: ActivityLogEntry[];
+    log(entry: ActivityLogEntry): void;
+}

package/dist/shared/in-memory-notification-service.d.ts

@@ -0,0 +1,11 @@
+import type { INotificationService, CreateNotificationInput } from '@beechcms/core';
+/**
+ * Test double for {@link INotificationService}.
+ *
+ * Captures every call into a public array so tests can assert what would have
+ * been delivered without touching D1.
+ */
+export declare class InMemoryNotificationService implements INotificationService {
+    readonly receivedNotifications: CreateNotificationInput[];
+    notify(input: CreateNotificationInput): void;
+}

package/dist/shared/in-memory-seed.repository.d.ts

@@ -0,0 +1,18 @@
+import type { ISeedRepository, Seed, SeedRecord } from '@beechcms/core';
+/**
+ * In-memory ISeedRepository for testing and for the config.seeds back-compat shim.
+ * Returns a fixed seed list with a static version token.
+ */
+export declare class InMemorySeedRepository implements ISeedRepository {
+    private readonly seeds;
+    private version;
+    constructor(seeds: Seed[]);
+    listActive(): Promise<Seed[]>;
+    listAll(): Promise<SeedRecord[]>;
+    get(slug: string): Promise<SeedRecord | null>;
+    upsert(_slug: string, _definition: Seed, _source?: 'code' | 'runtime'): Promise<void>;
+    softDelete(_slug: string): Promise<void>;
+    hardDelete(_slug: string): Promise<void>;
+    getRegistryVersion(): Promise<number>;
+    bumpRegistryVersion(): Promise<number>;
+}

package/dist/shared/media.repository.d1.d.ts

@@ -0,0 +1,35 @@
+import { MediaRepository, MediaObject } from '@beechcms/core';
+/**
+ * Implementation of MediaRepository using Cloudflare D1.
+ * Provides methods to track media uploads, retrieve media metadata, and manage the media library state in the database.
+ */
+export declare class D1MediaRepository implements MediaRepository {
+    private database;
+    constructor(database: D1Database);
+    /**
+     * Registers a new media upload in the database.
+     */
+    trackUpload(mediaObject: Omit<MediaObject, 'created_at'>): Promise<void>;
+    /**
+     * Retrieves a media object's metadata by its unique key.
+     */
+    getByKey(mediaKey: string): Promise<MediaObject | null>;
+    /**
+     * Removes the metadata tracking for a specific media key.
+     */
+    untrack(mediaKey: string): Promise<void>;
+    /**
+     * Lists media objects with pagination support.
+     */
+    list(paginationOptions: {
+        limit: number;
+        offset: number;
+    }): Promise<{
+        items: MediaObject[];
+        total: number;
+    }>;
+    /**
+     * Returns the total number of media objects in the database.
+     */
+    count(): Promise<number>;
+}

package/dist/shared/qstash-notification-service.d.ts

@@ -0,0 +1,18 @@
+import type { INotificationService, CreateNotificationInput } from '@beechcms/core';
+type ScheduleBackgroundTask = (task: Promise<unknown>) => void;
+/**
+ * QStash implementation of {@link INotificationService}.
+ *
+ * This service acts as a publisher, sending the notification payload to Upstash QStash,
+ * which guarantees delivery and retries. QStash will then forward the payload to the
+ * local webhook endpoint where it is actually inserted into D1.
+ */
+export declare class QStashNotificationService implements INotificationService {
+    private readonly scheduleBackgroundTask?;
+    private readonly client;
+    private readonly webhookUrl;
+    constructor(token: string, appUrl: string, scheduleBackgroundTask?: ScheduleBackgroundTask | undefined, qstashUrl?: string);
+    notify(input: CreateNotificationInput): Promise<void> | void;
+    private runPublish;
+}
+export {};

package/dist/shared/query-utils.d.ts

@@ -0,0 +1,36 @@
+import type { FilterGroup, FilterType } from '@beechcms/core';
+/** Entry parsata per le risposte API — contratto immutabile (C7). */
+export interface ContentEntry {
+    id: string;
+    schema_slug: string;
+    slug: string | null;
+    status: string;
+    data: Record<string, unknown>;
+    hasPendingDraft: boolean;
+    created_at: number | null;
+    updated_at: number | null;
+}
+export type QueryFilterType = FilterType;
+export type QueryFilterOperator = 'eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'is_empty' | 'is_not_empty';
+export interface QueryFilterCondition {
+    id?: string;
+    op: QueryFilterOperator;
+    value: string | number | boolean | null;
+}
+/** Formato inviato dalla dashboard (usa columnId). */
+export interface QueryFilterGroup {
+    columnId: string;
+    label?: string;
+    type: QueryFilterType;
+    conditions: QueryFilterCondition[];
+}
+export declare function cleanStr(val: unknown): string | null;
+export declare function safeParseJson(data: unknown): Record<string, unknown>;
+export declare function parsePositiveInt(value: string | undefined, fallback: number): number;
+/** Parse sicuro dei filtri da query-string (formato dashboard con columnId). */
+export declare function parseQueryFilters(raw: string | undefined): QueryFilterGroup[];
+/**
+ * Converte QueryFilterGroup[] (formato dashboard, columnId) in FilterGroup[]
+ * compatibile con buildSelectQuery del Botanical Engine.
+ */
+export declare function toEngineFilters(groups: QueryFilterGroup[]): FilterGroup[];

package/dist/shared/request-utils.d.ts

@@ -0,0 +1,13 @@
+import type { HonoRequest } from "hono";
+/**
+ * Extracts the real client IP address from a Cloudflare Worker request.
+ *
+ * Cloudflare injects the cf-connecting-ip header on every request that
+ * passes through the edge. In local development (wrangler dev) or in
+ * unit tests the header may be absent, in which case the string "unknown"
+ * is returned so that rate-limiter keys remain non-empty and safe to use.
+ *
+ * Never derive security decisions from this value alone; treat it as a
+ * best-effort hint for rate-limiting and logging purposes only.
+ */
+export declare function getClientIp(request: HonoRequest): string;

package/dist/shared/schema-mutator.d1.d.ts

@@ -0,0 +1,12 @@
+import type { ISchemaMutator } from '@beechcms/core';
+export declare class D1SchemaMutator implements ISchemaMutator {
+    private readonly db;
+    constructor(db: D1Database);
+    getColumns(table: string): Promise<Set<string> | null>;
+    execDdl(statements: string[]): Promise<void>;
+    private static assertIdentifier;
+    dropTable(table: string): Promise<void>;
+    dropColumn(table: string, column: string): Promise<void>;
+    renameColumn(table: string, from: string, to: string): Promise<void>;
+    execDestructive(statements: string[]): Promise<void>;
+}

package/dist/shared/seed-layout.repository.d1.d.ts

@@ -0,0 +1,9 @@
+import type { ISeedLayoutRepository, SeedLayoutRecord, FormLayout } from '@beechcms/core';
+export declare class D1SeedLayoutRepository implements ISeedLayoutRepository {
+    private readonly db;
+    constructor(db: D1Database);
+    get(slug: string): Promise<SeedLayoutRecord | null>;
+    getAllAsMap(): Promise<Map<string, FormLayout>>;
+    upsert(slug: string, layout: FormLayout, updatedBy: string): Promise<void>;
+    remove(slug: string): Promise<void>;
+}

package/dist/shared/seed-registry-cache.d.ts

@@ -0,0 +1,12 @@
+import type { ISeedRegistry, BackrefMap, ISeedRepository } from '@beechcms/core';
+/**
+ * Returns a fresh-enough { registry, backrefMap }. Reads the version token once per
+ * request (cheap indexed D1 read); rebuilds from listActive() only when the token
+ * changed or TTL lapsed.
+ */
+export declare function getHydratedRegistry(repo: ISeedRepository): Promise<{
+    registry: ISeedRegistry;
+    backrefMap: BackrefMap;
+}>;
+/** Test seam: drop the isolate cache. */
+export declare function __resetSeedRegistryCache(): void;

package/dist/shared/seed.repository.d1.d.ts

@@ -0,0 +1,13 @@
+import type { ISeedRepository, SeedRecord, Seed } from '@beechcms/core';
+export declare class D1SeedRepository implements ISeedRepository {
+    private readonly db;
+    constructor(db: D1Database);
+    listActive(): Promise<Seed[]>;
+    listAll(): Promise<SeedRecord[]>;
+    get(slug: string): Promise<SeedRecord | null>;
+    upsert(slug: string, definition: Seed, source?: 'code' | 'runtime'): Promise<void>;
+    softDelete(slug: string): Promise<void>;
+    hardDelete(slug: string): Promise<void>;
+    getRegistryVersion(): Promise<number>;
+    bumpRegistryVersion(): Promise<number>;
+}

package/dist/shared/sequential-id-generator.d.ts

@@ -0,0 +1,13 @@
+import type { IIdGenerator } from '@beechcms/core';
+/**
+ * Test-only IIdGenerator implementation. Each call returns a stable,
+ * monotonically increasing identifier (`test-id-0001`, `test-id-0002`, …)
+ * so snapshot assertions and insert-order checks remain deterministic
+ * across runs.
+ */
+export declare class SequentialIdGenerator implements IIdGenerator {
+    private counter;
+    uuid(): string;
+    isValid(value: unknown): value is string;
+    reset(): void;
+}

package/dist/shared/site-settings.repository.d1.d.ts

@@ -0,0 +1,7 @@
+import type { ISiteSettingsRepository, SiteSettings } from '@beechcms/core';
+export declare class D1SiteSettingsRepository implements ISiteSettingsRepository {
+    private readonly db;
+    constructor(db: D1Database);
+    getAll(): Promise<SiteSettings>;
+    setMany(values: Partial<SiteSettings>): Promise<void>;
+}

package/dist/shared/storage/factory.d.ts

@@ -0,0 +1,8 @@
+import { BeechBucket } from '@beechcms/core';
+import { Env } from '../../types';
+/**
+ * Single storage path: S3-compatible HTTP API.
+ * Prod → Cloudflare R2 with S3 API token.
+ * Dev  → MinIO container (or R2 staging bucket).
+ */
+export declare function createBucketProvider(env: Env, baseUrl: string): BeechBucket;

package/dist/shared/storage/s3-bucket.d.ts

@@ -0,0 +1,43 @@
+import { BeechBucket, PutBucketOptions, GetBucketResult, PresignOptions } from '@beechcms/core';
+/**
+ * Implementation of BeechBucket using S3-compatible API (AWS SDK).
+ * Used for production when connecting to R2 or any other S3 provider via HTTP.
+ */
+export declare class S3Bucket implements BeechBucket {
+    private client;
+    private bucketName;
+    private baseUrl;
+    private cdnUrl;
+    constructor(config: {
+        endpoint: string;
+        accessKeyId: string;
+        secretAccessKey: string;
+        bucketName: string;
+        baseUrl: string;
+        cdnUrl?: string;
+    });
+    put(key: string, body: ArrayBuffer | Uint8Array | ReadableStream, options?: PutBucketOptions): Promise<void>;
+    private streamToUint8Array;
+    get(key: string): Promise<GetBucketResult | null>;
+    delete(key: string): Promise<void>;
+    head(key: string): Promise<{
+        size: number;
+        contentType?: string;
+        metadata?: Record<string, string>;
+    } | null>;
+    getUrl(key: string): string;
+    getTotalSize(): Promise<number>;
+    presignPut(key: string, options: PresignOptions): Promise<string>;
+    presignGet(key: string, options: PresignOptions): Promise<string>;
+    list(options?: {
+        prefix?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        objects: Array<{
+            key: string;
+            size: number;
+        }>;
+        cursor?: string;
+    }>;
+}

package/dist/shared/storage-utils.d.ts

@@ -0,0 +1,7 @@
+import { S3Client } from '@aws-sdk/client-s3';
+/**
+ * Calcola la dimensione totale occupata in un bucket R2 (in byte).
+ * Nota: esegue una scansione completa del bucket. Per bucket molto grandi
+ * andrebbe implementata una cache o usato Cloudflare Logpush/Analytics.
+ */
+export declare function getBucketSize(client: S3Client, bucketName: string): Promise<number>;

package/dist/shared/system-stats.repository.d1.d.ts

@@ -0,0 +1,25 @@
+import { SystemStatsRepository } from '@beechcms/core';
+/**
+ * Implementation of SystemStatsRepository using Cloudflare D1.
+ * Manages global system statistics such as total storage usage.
+ */
+export declare class D1SystemStatsRepository implements SystemStatsRepository {
+    private database;
+    constructor(database: D1Database);
+    /**
+     * Increments the total storage usage count.
+     */
+    incrementStorage(byteCount: number): Promise<void>;
+    /**
+     * Decrements the total storage usage count, ensuring it doesn't fall below zero.
+     */
+    decrementStorage(byteCount: number): Promise<void>;
+    /**
+     * Sets the total storage usage count to a specific value.
+     */
+    setStorage(byteCount: number): Promise<void>;
+    /**
+     * Retrieves the current total storage usage in bytes.
+     */
+    getStorageUsage(): Promise<number>;
+}

package/dist/types.d.ts

@@ -0,0 +1,85 @@
+import type { Seed, ContentRepository, IdempotencyRepository, BeechBucket, MediaRepository, SystemStatsRepository, IHashProvider, ITokenService, IUserRepository, ISessionRepository, IPasswordResetTokenRepository, IActivityLogger, IActivityLogRepository, INotificationRepository, INotificationService, IWidgetRepository, ISearchRepository, IAnalyticsRepository, IContentScanRepository, ISeedRegistry, IClock, IIdGenerator, IAutomationRunner, IAutomationRepository, IScheduler, BackrefMap, ISiteSettingsRepository, IDemoDataRepository, JwtClaims, ISeedLayoutRepository, ISeedRepository, ISchemaMutator, IDashboardLayoutRepository } from '@beechcms/core';
+import type { IRateLimiterRegistry } from './middleware/rate-limit.middleware';
+import type { ISetupChecklistRepository } from './shared/d1-setup-checklist.repository';
+export interface Env {
+    DB: D1Database;
+    JWT_SECRET: string;
+    JWT_ISSUER?: string;
+    JWT_AUDIENCE?: string;
+    R2_ACCESS_KEY_ID?: string;
+    R2_SECRET_ACCESS_KEY?: string;
+    R2_ENDPOINT?: string;
+    R2_BUCKET_NAME?: string;
+    LOGIN_RATE_LIMITER?: RateLimit;
+    REFRESH_RATE_LIMITER?: RateLimit;
+    PUBLIC_READ_RATE_LIMITER?: RateLimit;
+    PUBLIC_WRITE_RATE_LIMITER?: RateLimit;
+    CORS_ORIGINS?: string;
+    PUBLIC_READ_API_KEY?: string;
+    PUBLIC_WRITE_API_KEY?: string;
+    PUBLIC_PUBLISHED_ONLY?: string;
+    PUBLIC_IDEMPOTENCY_TTL_SECONDS?: string;
+    MEDIA_BASE_URL?: string;
+    MEDIA_CDN_URL?: string;
+    MAX_UPLOAD_BYTES?: string;
+    RESEND_API_KEY?: string;
+    EMAIL_API_KEY?: string;
+    APP_URL?: string;
+    EMAIL_FROM?: string;
+    EMAIL_PROVIDER?: string;
+    SMTP_HOST?: string;
+    SMTP_PORT?: string;
+    WEBHOOK_TESTER_URL?: string;
+    FORGOT_PASSWORD_RATE_LIMITER?: RateLimit;
+    RESET_PASSWORD_RATE_LIMITER?: RateLimit;
+    ENV?: string;
+    DATE_FORMAT?: string;
+    ASSETS?: Fetcher;
+    QSTASH_TOKEN?: string;
+    QSTASH_URL?: string;
+    /** Public base URL the worker is reachable at, used by QStash to call back the webhook (e.g. an ngrok tunnel in dev). Falls back to APP_URL. */
+    QSTASH_CALLBACK_URL?: string;
+    QSTASH_CURRENT_SIGNING_KEY?: string;
+    QSTASH_NEXT_SIGNING_KEY?: string;
+}
+export interface Variables {
+    jwtPayload: JwtClaims;
+    getSeed: (slug: string) => Seed | null;
+    seedRegistry: ISeedRegistry;
+    repository: ContentRepository;
+    idempotencyRepository: IdempotencyRepository;
+    bucket: BeechBucket;
+    mediaRepository: MediaRepository;
+    systemStatsRepository: SystemStatsRepository;
+    hashProvider: IHashProvider;
+    tokenService: ITokenService;
+    userRepository: IUserRepository;
+    sessionRepository: ISessionRepository;
+    passwordResetTokenRepository: IPasswordResetTokenRepository;
+    rateLimiters: IRateLimiterRegistry;
+    activityLogger: IActivityLogger;
+    activityLogRepository: IActivityLogRepository;
+    notificationRepository: INotificationRepository;
+    notificationService: INotificationService;
+    widgetRepository: IWidgetRepository;
+    searchRepository: ISearchRepository;
+    analyticsRepository: IAnalyticsRepository;
+    contentScanRepository: IContentScanRepository;
+    clock: IClock;
+    idGenerator: IIdGenerator;
+    automationRepository: IAutomationRepository;
+    automationRunner: IAutomationRunner;
+    scheduler: IScheduler;
+    backrefMap: BackrefMap;
+    siteSettingsRepository: ISiteSettingsRepository;
+    demoDataRepository: IDemoDataRepository;
+    setupChecklistRepository: ISetupChecklistRepository;
+    seedLayoutRepository: ISeedLayoutRepository;
+    seedRepository: ISeedRepository;
+    schemaMutator: ISchemaMutator;
+    dashboardLayoutRepository: IDashboardLayoutRepository;
+}
+export type AppEnv = {
+    Bindings: Env;
+    Variables: Variables;
+};

package/dist/upload.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Media Engine — Single-path presigned uploads.
+ * Il Worker non riceve mai i bytes: agisce solo da gatekeeper (auth, validazione, firma).
+ */
+import { Hono } from 'hono';
+import { AppEnv } from './types';
+export declare function deleteR2Objects(c: {
+    var: {
+        bucket: any;
+        mediaRepository: any;
+        systemStatsRepository: any;
+    };
+}, objectKeys: string[]): Promise<void>;
+export declare const uploadRoutes: Hono<AppEnv, import("hono/types").BlankSchema, "/">;
+/** Serve un file dallo storage (usato dalla rotta pubblica /api/media/:key). */
+export declare function serveMediaHandler(c: any): Promise<Response>;

package/dist/widget.d.ts

@@ -0,0 +1,7 @@
+import { Hono } from 'hono';
+import type { Env, Variables } from './types';
+declare const widgetApp: Hono<{
+    Bindings: Env;
+    Variables: Variables;
+}, import("hono/types").BlankSchema, "/">;
+export { widgetApp };