@beechcms/api 0.6.7 → 0.8.0

package/dist/middleware/auth.middleware.d.ts

@@ -1,11 +1,41 @@
 import type { Context, Next } from 'hono';
 import type { Env, Variables } from '../types';
 /**
- * JWT authentication middleware. Reads the Bearer token from the Authorization
- * header and delegates verification to the ITokenService injected in context.
- * Returns 401 on any missing or invalid token; never exposes failure details.
+ * Configuration options for {@link authMiddleware}.
  */
-export declare function authMiddleware(): (c: Context<{
+export interface AuthMiddlewareOptions {
+    /**
+     * Whether to accept opaque OAuth 2.1 access tokens in addition to admin JWTs.
+     *
+     * @defaultValue false
+     *
+     * @remarks
+     * When `false` (the default), only admin JWTs are accepted. This ensures that internal endpoints
+     * — developer custom routes (`factory.ts`), OAuth consent APIs (`features/oauth/index.ts`), and the
+     * search router (`features/search/search.ts`) — stay JWT-only.
+     *
+     * When `true`, accepts both admin JWTs and opaque OAuth access tokens looked up via `oauthTokenRepository`.
+     * Only `apiProtected` sets this, and only in combination with `oauthScopeMiddleware()`.
+     */
+    acceptOAuth?: boolean;
+}
+/**
+ * Authentication middleware for API routes.
+ *
+ * @remarks
+ * Extracts the Bearer token from the `Authorization` header and validates credentials:
+ * - When {@link AuthMiddlewareOptions.acceptOAuth} is `true` and the token is a 64-character hex string,
+ *   looks up the active access token record via `oauthTokenRepository` and hydrates user claims from `userRepository`.
+ *   Populates `jwtPayload` and sets `oauthGrant` in the Hono context.
+ * - Otherwise, delegates verification to the `ITokenService` injected in context, setting `jwtPayload` and
+ *   clearing `oauthGrant` (`null`).
+ * - Emits HTTP 401 Unauthorized for missing, malformed, expired, or invalid tokens without exposing failure details.
+ *
+ * @param options - Configuration options controlling token acceptance.
+ * @returns A Hono middleware handler.
+ * @throws {HTTPException} 401 Unauthorized when authentication fails.
+ */
+export declare function authMiddleware(options?: AuthMiddlewareOptions): (c: Context<{
     Bindings: Env;
     Variables: Variables;
 }>, next: Next) => Promise<Response | void>;

package/dist/middleware/oauth-scope.middleware.d.ts

@@ -0,0 +1,60 @@
+import type { Context, Next } from 'hono';
+import type { OAuthScope } from '@beechcms/core';
+import type { Env, Variables } from '../types';
+/**
+ * Route mapping definition for OAuth scope enforcement.
+ */
+export interface OAuthScopeRoute {
+    /** HTTP method accepted for the route. */
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    /** Regular expression tested against the full request path (`c.req.path`). */
+    pattern: RegExp;
+    /** Scope required to access this endpoint. */
+    scope: OAuthScope;
+    /** Informational identifier of the MCP tool(s) backed by this endpoint. */
+    tools: string;
+}
+/**
+ * Closed allowlist of API routes accessible via OAuth 2.1 access tokens and their required scopes.
+ *
+ * @remarks
+ * Enforcement is fail-closed: any `/api/*` path not explicitly registered in this table
+ * is denied for OAuth-authenticated requests. Centralized enforcement ensures that forgetting
+ * to register a route refuses access rather than accidentally permitting it.
+ *
+ * Route mappings correspond directly to MCP tools (`beech_schema_export` and `beech_schema_validate`
+ * share `GET /api/schema`).
+ *
+ * `POST /api/seeds/:slug/mcp-plan` is intentionally mapped to `schema:read` because it performs
+ * a dry-run calculation (DDL and safety classification) without mutating state. Only `mcp-apply`
+ * requires `schema:write`.
+ *
+ * Patterns match against `c.req.path`, which includes the `/api` prefix.
+ */
+export declare const OAUTH_SCOPE_ROUTES: readonly OAuthScopeRoute[];
+/**
+ * Resolves the required OAuth scope for a given route.
+ *
+ * @param method - The HTTP request method (e.g. `'GET'`, `'POST'`).
+ * @param path - The full request pathname (e.g. `c.req.path`).
+ * @returns The required {@link OAuthScope}, or `null` if the route is not OAuth-reachable.
+ */
+export declare function resolveRequiredScope(method: string, path: string): OAuthScope | null;
+/**
+ * Middleware enforcing OAuth 2.1 scope boundaries on protected API routes.
+ *
+ * @remarks
+ * This middleware operates in a fail-closed manner:
+ * - Must be registered immediately after `authMiddleware({ acceptOAuth: true })`, which populates `oauthGrant`.
+ * - Requests authenticated via the admin JWT carry `oauthGrant === null` and pass through untouched.
+ * - For OAuth requests, verifies that the route is allowlisted in {@link OAUTH_SCOPE_ROUTES} and that the token
+ *   grant includes the necessary {@link OAuthScope}.
+ * - Returns HTTP 403 (`insufficient_scope`) on failure rather than 401, allowing MCP clients to distinguish
+ *   insufficient privileges from expired or invalid credentials.
+ *
+ * @returns A Hono middleware handler enforcing scope boundaries.
+ */
+export declare function oauthScopeMiddleware(): (c: Context<{
+    Bindings: Env;
+    Variables: Variables;
+}>, next: Next) => Promise<Response | void>;

package/dist/middleware/rate-limit.middleware.d.ts

@@ -1,9 +1,11 @@
 import type { IRateLimiter } from '@beechcms/core';
-import type { AppEnv } from '../types';
-export type RateLimiterName = 'login' | 'tokenRefresh' | 'forgotPassword' | 'resetPassword' | 'publicApiRead' | 'publicApiWrite';
+import type { AppEnv, Env } from '../types';
+export type RateLimiterName = 'login' | 'loginAccount' | 'tokenRefresh' | 'forgotPassword' | 'forgotPasswordAccount' | 'resetPassword' | 'publicApiRead' | 'publicApiWrite' | 'oauthToken' | 'oauthTokenAccount';
 export interface IRateLimiterRegistry {
     getLimiter(name: RateLimiterName): IRateLimiter;
+    resetAll?(): void;
 }
+export declare function buildDefaultRegistry(_env?: Env): IRateLimiterRegistry;
 export declare const rateLimiterMiddleware: (overrides?: {
     registry?: IRateLimiterRegistry;
 }) => import("hono").MiddlewareHandler<AppEnv, string, {}, Response>;

package/dist/middleware/repository.middleware.d.ts

@@ -1,4 +1,4 @@
-import type { ContentRepository, IdempotencyRepository, MediaRepository, SystemStatsRepository, IUserRepository, ISessionRepository, IPasswordResetTokenRepository, IActivityLogRepository, INotificationRepository, IWidgetRepository, ISearchRepository, IAnalyticsRepository, IContentScanRepository, IClock, IIdGenerator, IAutomationRunner, IAutomationRepository, IScheduler, ISiteSettingsRepository, IDemoDataRepository, ISeedLayoutRepository, ISeedRepository, ISchemaMutator, IDashboardLayoutRepository, BeechHooks, IKanbanPositionRepository } from '@beechcms/core';
+import type { ContentRepository, IdempotencyRepository, MediaRepository, SystemStatsRepository, IUserRepository, ISessionRepository, IPasswordResetTokenRepository, IActivityLogRepository, INotificationRepository, IWidgetRepository, ISearchRepository, IAnalyticsRepository, IContentScanRepository, IClock, IIdGenerator, IAutomationRunner, IAutomationRepository, IScheduler, ISiteSettingsRepository, IDemoDataRepository, ISeedLayoutRepository, ISeedRepository, ISchemaMutator, IDashboardLayoutRepository, BeechHooks, IKanbanPositionRepository, IAntivirusProvider, ITimeTrapTokenRepository, IPrivacyService, IOAuthClientRepository, IOAuthAuthorizationCodeRepository, IOAuthTokenRepository, IOAuthConsentRepository, IRoleGuard } from '@beechcms/core';
 import type { Env, Variables } from '../types';
 interface RepositoryOverrides {
     repository?: ContentRepository;
@@ -26,7 +26,15 @@ interface RepositoryOverrides {
     schemaMutator?: ISchemaMutator;
     dashboardLayoutRepository?: IDashboardLayoutRepository;
     kanbanPositionRepository?: IKanbanPositionRepository;
+    antivirusProvider?: IAntivirusProvider;
+    timeTrapTokenRepository?: ITimeTrapTokenRepository;
+    oauthClientRepository?: IOAuthClientRepository;
+    oauthAuthorizationCodeRepository?: IOAuthAuthorizationCodeRepository;
+    oauthTokenRepository?: IOAuthTokenRepository;
+    oauthConsentRepository?: IOAuthConsentRepository;
+    roleGuard?: IRoleGuard;
     hooks?: BeechHooks;
+    privacyService?: IPrivacyService;
 }
 export declare const repositoryMiddleware: (overrides?: RepositoryOverrides) => import("hono").MiddlewareHandler<{
     Bindings: Env;

package/dist/public/api-key-middleware.d.ts

@@ -1,6 +1,2 @@
 import type { Context, Next } from 'hono';
-/**
- * API key auth middleware for Public API routes.
- * Uses X-API-Key header only.
- */
 export declare function apiKeyMiddleware(): (c: Context, next: Next) => Promise<Response | void>;

package/dist/public/public-add.d.ts

@@ -1,3 +1,3 @@
 import type { Context } from 'hono';
-import { AppEnv } from '../types';
+import type { AppEnv } from '../types.js';
 export declare function publicAddHandler(context: Context<AppEnv>): Promise<Response>;

package/dist/rate-limit/in-memory-rate-limiter.d.ts

@@ -1,8 +1 @@
-import type { IRateLimiter, RateLimitResult } from '@beechcms/core';
-export declare class InMemoryRateLimiter implements IRateLimiter {
-    private readonly maxAllowedHits;
-    private readonly windowSeconds;
-    private readonly hitCounts;
-    constructor(maxAllowedHits: number, windowSeconds?: number);
-    checkLimit(key: string): Promise<RateLimitResult>;
-}
+export { TokenBucketRateLimiter as InMemoryRateLimiter } from '@beechcms/core';

package/dist/shared/db/repositories/content.repository.d1.d.ts

@@ -1,4 +1,4 @@
-import { ContentRepository, type BulkFieldUpdate, type BatchWrite, type DraftSummary, type Seed, type SelectOptions, type RepositoryOptions, type BeechHooks, type IPrivacyService } from '@beechcms/core';
+import { ContentRepository, type BulkFieldUpdate, type BatchWrite, type DraftSummary, type Seed, type SelectOptions, type RepositoryOptions, type BeechHooks, type IPrivacyService, type IQueueService } from '@beechcms/core';
 import { BaseD1Repository } from './base.repository.d1';
 export declare function prepareBlindIndexOptions(seed: Seed, options: SelectOptions, privacyService: IPrivacyService): Promise<SelectOptions>;
 /**
@@ -16,7 +16,9 @@ export declare function prepareBlindIndexOptions(seed: Seed, options: SelectOpti
 export declare class D1ContentRepository extends BaseD1Repository implements ContentRepository {
     private readonly hooks?;
     private readonly privacyService?;
-    constructor(database: D1Database, hooks?: BeechHooks | undefined, privacyService?: IPrivacyService | undefined);
+    private queue?;
+    constructor(database: D1Database, hooks?: BeechHooks | undefined, privacyService?: IPrivacyService | undefined, queue?: IQueueService);
+    setQueue(queue: IQueueService): void;
     /** Assembles the {@link HookContext} passed to every lifecycle hook invocation. */
     private hookCtx;
     private serializeAndProtect;

package/dist/shared/db/repositories/d1-oauth-authorization-code.repository.d.ts

@@ -0,0 +1,9 @@
+import type { IOAuthAuthorizationCodeRepository, NewAuthorizationCode, AuthorizationCodeRecord, IClock } from '@beechcms/core';
+export declare class D1OAuthAuthorizationCodeRepository implements IOAuthAuthorizationCodeRepository {
+    private readonly db;
+    private readonly clock;
+    constructor(db: D1Database, clock: IClock);
+    save(record: NewAuthorizationCode): Promise<void>;
+    findByHash(codeHash: string, nowTimestamp: number): Promise<AuthorizationCodeRecord | null>;
+    consumeByHash(codeHash: string, nowTimestamp: number): Promise<boolean>;
+}

package/dist/shared/db/repositories/d1-oauth-client.repository.d.ts

@@ -0,0 +1,6 @@
+import type { IOAuthClientRepository, OAuthClientRecord } from '@beechcms/core';
+export declare class D1OAuthClientRepository implements IOAuthClientRepository {
+    private readonly db;
+    constructor(db: D1Database);
+    findActiveById(clientId: string): Promise<OAuthClientRecord | null>;
+}

package/dist/shared/db/repositories/d1-oauth-consent.repository.d.ts

@@ -0,0 +1,10 @@
+import type { IOAuthConsentRepository, ConsentRecord, OAuthScope, IIdGenerator } from '@beechcms/core';
+export declare class D1OAuthConsentRepository implements IOAuthConsentRepository {
+    private readonly db;
+    private readonly idGenerator;
+    constructor(db: D1Database, idGenerator: IIdGenerator);
+    findActive(clientId: string, userId: string): Promise<ConsentRecord | null>;
+    grant(id: string, clientId: string, userId: string, scopes: readonly OAuthScope[], nowTimestamp: number): Promise<void>;
+    revoke(clientId: string, userId: string, nowTimestamp: number): Promise<boolean>;
+    listForUser(userId: string): Promise<ConsentRecord[]>;
+}

package/dist/shared/db/repositories/d1-oauth-token.repository.d.ts

@@ -0,0 +1,12 @@
+import type { IOAuthTokenRepository, NewOAuthToken, OAuthTokenRecord, OAuthTokenType, AuthorizedClientSummary, IClock } from '@beechcms/core';
+export declare class D1OAuthTokenRepository implements IOAuthTokenRepository {
+    private readonly db;
+    private readonly clock;
+    constructor(db: D1Database, clock: IClock);
+    save(record: NewOAuthToken): Promise<void>;
+    findActiveByHash(tokenHash: string, tokenType: OAuthTokenType, nowTimestamp: number): Promise<OAuthTokenRecord | null>;
+    revokeByHash(tokenHash: string, nowTimestamp: number): Promise<boolean>;
+    revokeByAuthorizationCode(authorizationCodeHash: string, nowTimestamp: number): Promise<number>;
+    revokeAllForClientAndUser(clientId: string, userId: string, nowTimestamp: number): Promise<number>;
+    listAuthorizedClientsForUser(userId: string, nowTimestamp: number): Promise<AuthorizedClientSummary[]>;
+}

package/dist/shared/db/repositories/d1-search.query.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @module shared/db/repositories/d1-search.query
+ * Pure SQL query builder utilities for SQLite/D1 FTS5 full-text search.
+ */
+import type { Seed, SearchResultRow } from '@beechcms/core';
+/**
+ * Raw database row returned by the UNION ALL FTS query.
+ * Field names use snake_case to match SQLite column aliases verbatim.
+ */
+export interface FtsRow {
+    entry_id: string;
+    schema_slug: string;
+    slug: string | null;
+    status: string;
+    title: string | null;
+    excerpt: string;
+    rank: number;
+}
+/**
+ * Validated query parameters passed to {@link buildFtsQuery}.
+ */
+export interface FtsQueryParams {
+    queryText: string;
+    schemaSlug: string | null;
+    statusFilter: string | null;
+    pageSize: number;
+    cursor: string | null;
+}
+/**
+ * Result of {@link buildFtsQuery}: parameterised SQL for both the
+ * paginated data fetch and the total-count query.
+ */
+export interface FtsQueryResult {
+    sql: string;
+    binds: unknown[];
+    countSql: string;
+    countBinds: unknown[];
+}
+/**
+ * Decodes a pagination cursor (`${rank}:${entryId}`).
+ */
+export declare function decodeCursor(cursor: string): {
+    rank: number;
+    entryId: string;
+} | null;
+/**
+ * Builds a UNION ALL query across all per-seed FTS tables that satisfy
+ * {@link isSeedFullTextSearchable}.
+ */
+export declare function buildFtsQuery(params: FtsQueryParams, seeds: Seed[]): FtsQueryResult;
+/**
+ * Maps raw FtsRow database representation to core SearchResultRow.
+ */
+export declare function mapFtsRowToResultRow(row: FtsRow): SearchResultRow;

package/dist/shared/db/repositories/d1-vector.repository.d.ts

@@ -0,0 +1,11 @@
+import type { Seed, IVectorRepository } from '@beechcms/core';
+export declare class D1VectorRepository implements IVectorRepository {
+    private readonly db;
+    constructor(db: D1Database);
+    saveVector(seed: Seed, entryId: string, vector: Float32Array): Promise<void>;
+    deleteVector(seed: Seed, entryId: string): Promise<void>;
+    getAllVectors(seed: Seed): Promise<{
+        entryId: string;
+        vector: Float32Array;
+    }[]>;
+}

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

@@ -1,4 +1,4 @@
-import type { ISeedRepository, Seed, SeedRecord } from '@beechcms/core';
+import type { ISeedRepository, Seed, SeedRecord, SeedApplyInput, SeedApplyResult } 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.
@@ -15,4 +15,5 @@ export declare class InMemorySeedRepository implements ISeedRepository {
     hardDelete(_slug: string): Promise<void>;
     getRegistryVersion(): Promise<number>;
     bumpRegistryVersion(): Promise<number>;
+    applyAtomic(input: SeedApplyInput): Promise<SeedApplyResult>;
 }

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

@@ -1,6 +1,7 @@
-import type { ISeedRepository, SeedRecord, Seed } from '@beechcms/core';
+import type { ISeedRepository, SeedRecord, Seed, SeedApplyInput, SeedApplyResult } from '@beechcms/core';
 export declare class D1SeedRepository implements ISeedRepository {
     private readonly db;
+    private static readonly UPSERT_SEED_SQL;
     constructor(db: D1Database);
     listActive(): Promise<Seed[]>;
     listAll(): Promise<SeedRecord[]>;
@@ -10,4 +11,5 @@ export declare class D1SeedRepository implements ISeedRepository {
     hardDelete(slug: string): Promise<void>;
     getRegistryVersion(): Promise<number>;
     bumpRegistryVersion(): Promise<number>;
+    applyAtomic(input: SeedApplyInput): Promise<SeedApplyResult>;
 }

package/dist/shared/db/repositories/time-trap-token.repository.d1.d.ts

@@ -0,0 +1,7 @@
+import type { ITimeTrapTokenRepository } from '@beechcms/core';
+import { BaseD1Repository } from './base.repository.d1.js';
+export declare class D1TimeTrapTokenRepository extends BaseD1Repository implements ITimeTrapTokenRepository {
+    isTokenUsed(tokenHash: string): Promise<boolean>;
+    markTokenUsed(tokenHash: string, usedAt: number, expiresAt: number): Promise<void>;
+    cleanup(nowSeconds: number): Promise<void>;
+}

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

@@ -1,8 +1,88 @@
-import { BeechBucket } from '@beechcms/core';
+import { BeechBucket, PutBucketOptions, GetBucketResult, PresignOptions } from '@beechcms/core';
 import { Env } from '../../types';
+export { R2BucketAdapter } from './r2-bucket';
 /**
- * Single storage path: S3-compatible HTTP API.
- * Prod → Cloudflare R2 with S3 API token.
- * Dev  → MinIO container (or R2 staging bucket).
+ * Fallback implementation of {@link BeechBucket} used when storage is not configured.
+ *
+ * @remarks
+ * Every bucket operation unconditionally throws an HTTP 503 Service Unavailable exception
+ * with error code `storage_not_configured`, providing diagnostic instructions on how to
+ * configure Cloudflare R2 credentials or MinIO for local development.
+ */
+export declare class NullBucket implements BeechBucket {
+    /**
+     * Creates an HTTP 503 exception explaining that storage is not configured.
+     */
+    private createException;
+    /**
+     * @throws {HTTPException} Always returns a rejected promise with 503 Service Unavailable.
+     */
+    put(_key?: string, _body?: ArrayBuffer | Uint8Array | ReadableStream, _options?: PutBucketOptions): Promise<void>;
+    /**
+     * @throws {HTTPException} Always returns a rejected promise with 503 Service Unavailable.
+     */
+    get(_key?: string): Promise<GetBucketResult | null>;
+    /**
+     * @throws {HTTPException} Always returns a rejected promise with 503 Service Unavailable.
+     */
+    delete(_key?: string): Promise<void>;
+    /**
+     * @throws {HTTPException} Always returns a rejected promise with 503 Service Unavailable.
+     */
+    head(_key?: string): Promise<{
+        size: number;
+        contentType?: string;
+        metadata?: Record<string, string>;
+    } | null>;
+    /**
+     * @throws {HTTPException} Always throws 503 Service Unavailable.
+     */
+    getUrl(_key?: string): string;
+    /**
+     * @throws {HTTPException} Always returns a rejected promise with 503 Service Unavailable.
+     */
+    getTotalSize(): Promise<number>;
+    /**
+     * @throws {HTTPException} Always returns a rejected promise with 503 Service Unavailable.
+     */
+    list(_options?: {
+        prefix?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        objects: Array<{
+            key: string;
+            size: number;
+        }>;
+        cursor?: string;
+    }>;
+    /**
+     * @throws {HTTPException} Always returns a rejected promise with 503 Service Unavailable.
+     */
+    presignPut(_key?: string, _options?: PresignOptions): Promise<string>;
+    /**
+     * @throws {HTTPException} Always returns a rejected promise with 503 Service Unavailable.
+     */
+    presignGet(_key?: string, _options?: PresignOptions): Promise<string>;
+}
+/**
+ * Resets the warning flags for storage provider configuration.
+ *
+ * @remarks
+ * Useful for test isolation to ensure diagnostic warnings are verified reliably across test suites.
+ */
+export declare function resetNullBucketWarning(): void;
+/**
+ * Creates and configures the appropriate {@link BeechBucket} storage provider based on environment settings.
+ *
+ * @remarks
+ * Selection precedence:
+ * 1. **S3Bucket**: Used when all R2 S3 credentials (`R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_ENDPOINT`, `R2_BUCKET_NAME`) are set.
+ * 2. **R2BucketAdapter**: Used when the native Cloudflare Worker `MEDIA_BUCKET` binding is detected (with a notice that presigned uploads require S3 credentials).
+ * 3. **NullBucket**: Fallback when no storage is configured. Logs a warning in `development` mode.
+ *
+ * @param env - Application environment configuration.
+ * @param baseUrl - Base URL of the API server used for constructing fallback media URLs.
+ * @returns An initialized {@link BeechBucket} provider instance.
  */
 export declare function createBucketProvider(env: Env, baseUrl: string): BeechBucket;

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

@@ -0,0 +1,127 @@
+import { BeechBucket, PutBucketOptions, GetBucketResult, PresignOptions } from '@beechcms/core';
+/**
+ * Implementation of {@link BeechBucket} using Cloudflare Workers' native `R2Bucket` binding.
+ *
+ * @remarks
+ * Used when running inside Cloudflare Workers with an `r2_buckets` binding (e.g. `MEDIA_BUCKET`).
+ * Provides direct access to Cloudflare R2 storage without needing external S3 SDK requests.
+ *
+ * Note: Generating presigned URLs (`presignPut`, `presignGet`) is not supported by native `R2Bucket`
+ * bindings and will throw HTTP 501 (`presigned_urls_require_s3_credentials`). Direct client uploads
+ * with presigned URLs require S3 credentials configured via {@link S3Bucket}.
+ */
+export declare class R2BucketAdapter implements BeechBucket {
+    /** Native Cloudflare Workers R2 bucket binding instance. */
+    private bucket;
+    /** Base URL of the API server used for fallback asset access URLs. */
+    private baseUrl;
+    /** Optional custom CDN base URL prepended to media assets when served via CDN. */
+    private cdnUrl;
+    /**
+     * Initializes a new instance of {@link R2BucketAdapter}.
+     *
+     * @param bucket - The native Cloudflare Workers `R2Bucket` binding.
+     * @param baseUrl - Base URL of the API server used to construct fallback media URLs.
+     * @param cdnUrl - Optional custom CDN base URL.
+     */
+    constructor(bucket: R2Bucket, baseUrl: string, cdnUrl?: string);
+    /**
+     * Uploads an object directly to the native R2 bucket binding.
+     *
+     * @param key - The unique object key (path) within the bucket.
+     * @param body - The object content as an `ArrayBuffer`, `Uint8Array`, or `ReadableStream`.
+     * @param options - Optional upload settings such as `contentType` (stored in `httpMetadata`) and custom `metadata`.
+     * @throws {Error} If the R2 upload operation fails.
+     * @returns A promise that resolves when the upload completes.
+     */
+    put(key: string, body: ArrayBuffer | Uint8Array | ReadableStream, options?: PutBucketOptions): Promise<void>;
+    /**
+     * Retrieves an object from the native R2 bucket.
+     *
+     * @param key - The unique object key (path) within the bucket.
+     * @returns A promise resolving to a {@link GetBucketResult} containing the object's body, metadata, and content type, or `null` if the object does not exist.
+     * @throws {Error} If reading from the R2 binding fails.
+     */
+    get(key: string): Promise<GetBucketResult | null>;
+    /**
+     * Deletes an object from the native R2 bucket.
+     *
+     * @param key - The unique object key (path) to delete.
+     * @throws {Error} If the deletion operation fails.
+     * @returns A promise that resolves when the object is deleted.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Retrieves object metadata from the native R2 bucket without reading the body.
+     *
+     * @param key - The unique object key (path) within the bucket.
+     * @returns A promise resolving to the object's size, content type, and custom metadata, or `null` if the object is not found.
+     * @throws {Error} If the head request fails.
+     */
+    head(key: string): Promise<{
+        size: number;
+        contentType?: string;
+        metadata?: Record<string, string>;
+    } | null>;
+    /**
+     * Constructs the public access URL for an object key.
+     *
+     * @remarks
+     * If a CDN URL is configured, returns the CDN-prefixed path (`${cdnUrl}/${encodedKey}`).
+     * Otherwise, returns the API fallback path (`${baseUrl}/api/media/${encodedKey}`).
+     *
+     * @param key - The storage object key.
+     * @returns The fully qualified URL to access the media object.
+     */
+    getUrl(key: string): string;
+    /**
+     * Computes the cumulative size in bytes of all objects stored in the bucket.
+     *
+     * @remarks
+     * Iterates through all bucket objects using paginated R2 `list` requests.
+     *
+     * @returns A promise resolving to the total storage size in bytes.
+     */
+    getTotalSize(): Promise<number>;
+    /**
+     * Lists objects in the R2 bucket matching an optional prefix, with pagination support.
+     *
+     * @param options - Optional listing parameters including `prefix`, `limit`, and pagination `cursor`.
+     * @returns A promise resolving to an array of object summaries (key and size) and an optional continuation cursor.
+     */
+    list(options?: {
+        prefix?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        objects: Array<{
+            key: string;
+            size: number;
+        }>;
+        cursor?: string;
+    }>;
+    /**
+     * Generates a presigned URL for direct upload via HTTP PUT.
+     *
+     * @remarks
+     * Native Cloudflare `R2Bucket` bindings cannot generate cryptographic SigV4 signatures.
+     * This method throws an HTTP 501 exception instructing the user to configure S3 API credentials.
+     *
+     * @param _key - The target object key (path).
+     * @param _options - Presigning options.
+     * @throws {HTTPException} Always throws 501 Not Implemented because native bindings lack SigV4 signing capability.
+     */
+    presignPut(_key: string, _options: PresignOptions): Promise<string>;
+    /**
+     * Generates a presigned URL for direct download via HTTP GET.
+     *
+     * @remarks
+     * Native Cloudflare `R2Bucket` bindings cannot generate cryptographic SigV4 signatures.
+     * This method throws an HTTP 501 exception instructing the user to configure S3 API credentials.
+     *
+     * @param _key - The target object key (path).
+     * @param _options - Presigning options.
+     * @throws {HTTPException} Always throws 501 Not Implemented because native bindings lack SigV4 signing capability.
+     */
+    presignGet(_key: string, _options: PresignOptions): Promise<string>;
+}