@btst/stack 3.0.0-rc.1 → 3.0.0-rc.3

package/dist/shared/stack.DQq8DEIv.d.mts

@@ -1,461 +0,0 @@
-import * as _btst_stack_plugins_api from '@btst/stack/plugins/api';
-import { S as StorageAdapter, b as S3UploadToken } from './stack.lkebw2nj.mjs';
-import * as better_call from 'better-call';
-import { z } from 'zod';
-import { A as Asset, F as Folder } from './stack.BMlLOMED.mjs';
-import { DBAdapter } from '@btst/db';
-
-/**
- * Parameters for filtering and paginating the asset list.
- */
-interface AssetListParams {
-    folderId?: string;
-    mimeType?: string;
-    query?: string;
-    offset?: number;
-    limit?: number;
-    tenantId?: string;
-}
-/**
- * Paginated result returned by {@link listAssets}.
- */
-interface AssetListResult {
-    items: Asset[];
-    total: number;
-    limit?: number;
-    offset?: number;
-}
-/**
- * Parameters for filtering the folder list.
- */
-interface FolderListParams {
-    parentId?: string | null;
-    tenantId?: string;
-}
-/**
- * Retrieve all assets matching optional filter criteria.
- * Pure DB function — no hooks, no HTTP context. Safe for server-side use.
- *
- * @remarks **Security:** Authorization hooks are NOT called. The caller is
- * responsible for any access-control checks before invoking this function.
- */
-declare function listAssets(adapter: DBAdapter, params?: AssetListParams): Promise<AssetListResult>;
-/**
- * Retrieve a single asset by its ID.
- * Returns `null` if no asset is found.
- * Pure DB function — no hooks, no HTTP context.
- *
- * @remarks **Security:** Authorization hooks are NOT called.
- */
-declare function getAssetById(adapter: DBAdapter, id: string): Promise<Asset | null>;
-/**
- * Retrieve all folders, optionally filtered by `parentId`.
- * Pass `null` to list root-level folders (those without a parent).
- * Pure DB function — no hooks, no HTTP context.
- *
- * @remarks **Security:** Authorization hooks are NOT called.
- */
-declare function listFolders(adapter: DBAdapter, params?: FolderListParams): Promise<Folder[]>;
-/**
- * Retrieve a single folder by its ID.
- * Returns `null` if no folder is found.
- * Pure DB function — no hooks, no HTTP context.
- *
- * @remarks **Security:** Authorization hooks are NOT called.
- */
-declare function getFolderById(adapter: DBAdapter, id: string): Promise<Folder | null>;
-/**
- * Find a single folder by name, optionally scoped to a specific parent and/or tenant.
- * Pass `null` for `parentId` to search only root-level folders.
- * Pass `undefined` for `parentId` to search regardless of parent.
- * Returns `null` if no matching folder is found.
- *
- * Pure DB function — no hooks, no HTTP context.
- * The caller is responsible for any access-control checks.
- */
-declare function getFolderByName(adapter: DBAdapter, name: string, parentId?: string | null, tenantId?: string): Promise<Folder | null>;
-
-declare const AssetListQuerySchema: z.ZodObject<{
-    folderId: z.ZodOptional<z.ZodString>;
-    mimeType: z.ZodOptional<z.ZodString>;
-    query: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string | undefined, string>>>;
-    offset: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
-    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
-}, z.core.$strip>;
-declare const updateAssetSchema: z.ZodObject<{
-    alt: z.ZodOptional<z.ZodString>;
-    folderId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-}, z.core.$strip>;
-declare const createFolderSchema: z.ZodObject<{
-    name: z.ZodString;
-    parentId: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-
-/**
- * Input for creating a new asset record.
- */
-interface CreateAssetInput {
-    filename: string;
-    originalName: string;
-    mimeType: string;
-    size: number;
-    url: string;
-    folderId?: string;
-    alt?: string;
-    tenantId?: string;
-}
-/**
- * Input for updating an existing asset record.
- */
-interface UpdateAssetInput {
-    alt?: string;
-    folderId?: string | null;
-}
-/**
- * Input for creating a new folder.
- */
-interface CreateFolderInput {
-    name: string;
-    parentId?: string;
-    tenantId?: string;
-}
-/**
- * Create an asset record in the database.
- * Pure DB function — no authorization hooks, no HTTP context.
- *
- * @remarks **Security:** No authorization hooks (e.g. `onBeforeUpload`) are called.
- * The caller is responsible for any access-control checks before invoking this function.
- */
-declare function createAsset(adapter: DBAdapter, input: CreateAssetInput): Promise<Asset>;
-/**
- * Update an asset's `alt` text or `folderId`.
- * Pure DB function — no authorization hooks, no HTTP context.
- *
- * @remarks **Security:** No authorization hooks are called.
- */
-declare function updateAsset(adapter: DBAdapter, id: string, input: UpdateAssetInput): Promise<Asset | null>;
-/**
- * Delete an asset record from the database by its ID.
- * Does NOT delete the underlying file — the caller must do that via the storage adapter.
- * Pure DB function — no authorization hooks, no HTTP context.
- *
- * @remarks **Security:** No authorization hooks are called.
- */
-declare function deleteAsset(adapter: DBAdapter, id: string): Promise<void>;
-/**
- * Create a folder record in the database.
- * Pure DB function — no authorization hooks, no HTTP context.
- *
- * @remarks **Security:** No authorization hooks are called.
- */
-declare function createFolder(adapter: DBAdapter, input: CreateFolderInput): Promise<Folder>;
-/**
- * Delete a folder record from the database by its ID.
- * Child folders are cascade-deleted automatically. Throws if the folder or
- * any of its descendants contain assets (which have associated storage files
- * that must be deleted via the storage adapter first).
- * Pure DB function — no authorization hooks, no HTTP context.
- *
- * @remarks **Security:** No authorization hooks are called.
- */
-declare function deleteFolder(adapter: DBAdapter, id: string): Promise<void>;
-
-/**
- * Context passed to media API hooks.
- */
-interface MediaApiContext<TBody = unknown, TParams = unknown, TQuery = unknown> {
-    body?: TBody;
-    params?: TParams;
-    query?: TQuery;
-    request?: Request;
-    headers?: Headers;
-    [key: string]: unknown;
-}
-/**
- * Configuration hooks for the media backend plugin.
- * All hooks are optional and allow consumers to customise behaviour.
- */
-interface MediaBackendHooks {
-    /**
-     * Called before a file upload is allowed (both direct and signed adapters).
-     * Throw an Error to reject the upload (e.g. if the user is not authenticated).
-     */
-    onBeforeUpload?: (meta: {
-        filename: string;
-        mimeType: string;
-        size?: number;
-    }, context: MediaApiContext) => Promise<void> | void;
-    /**
-     * Called after an asset record is created in the database.
-     */
-    onAfterUpload?: (asset: Asset, context: MediaApiContext) => Promise<void> | void;
-    /**
-     * Called before an asset is deleted. Throw to prevent deletion.
-     */
-    onBeforeDelete?: (asset: Asset, context: MediaApiContext) => Promise<void> | void;
-    /**
-     * Called after an asset has been deleted from the DB and storage.
-     */
-    onAfterDelete?: (assetId: string, context: MediaApiContext) => Promise<void> | void;
-    /**
-     * Called before listing assets. Throw to deny access.
-     */
-    onBeforeListAssets?: (filter: z.infer<typeof AssetListQuerySchema>, context: MediaApiContext) => Promise<void> | void;
-    /**
-     * Called before updating an asset (PATCH). Throw to deny access.
-     */
-    onBeforeUpdateAsset?: (asset: Asset, updates: z.infer<typeof updateAssetSchema>, context: MediaApiContext) => Promise<void> | void;
-    /**
-     * Called before listing folders. Throw to deny access.
-     */
-    onBeforeListFolders?: (filter: {
-        parentId?: string | null;
-    }, context: MediaApiContext) => Promise<void> | void;
-    /**
-     * Called before creating a folder. Throw to deny access.
-     */
-    onBeforeCreateFolder?: (input: z.infer<typeof createFolderSchema>, context: MediaApiContext) => Promise<void> | void;
-    /**
-     * Called before deleting a folder. Throw to deny access.
-     */
-    onBeforeDeleteFolder?: (folder: Folder, context: MediaApiContext) => Promise<void> | void;
-}
-/**
- * Configuration for the media backend plugin.
- */
-interface MediaBackendConfig {
-    /**
-     * The storage adapter to use for file uploads.
-     * - `localAdapter()` — writes to the local filesystem (dev / self-hosted)
-     * - `s3Adapter()` — presigned PUT URL (AWS S3, Cloudflare R2, MinIO)
-     * - `vercelBlobAdapter()` — signed direct upload via Vercel Blob
-     */
-    storageAdapter: StorageAdapter;
-    /**
-     * Maximum file size in bytes.
-     * Enforced server-side for `localAdapter`.
-     * Passed into the Vercel Blob token for edge enforcement.
-     * Validated against the client-reported size for `s3Adapter`.
-     * @default 10485760 (10 MB)
-     */
-    maxFileSizeBytes?: number;
-    /**
-     * MIME type allowlist (e.g. `["image/jpeg", "image/png"]`).
-     * If omitted, all MIME types are accepted.
-     * Enforced server-side for `localAdapter`.
-     * Passed to Vercel Blob token for edge enforcement.
-     * Validated against the client-reported MIME type for `s3Adapter`.
-     */
-    allowedMimeTypes?: string[];
-    /**
-     * URL prefixes that are allowed when creating asset records via `POST /media/assets`.
-     * When omitted the plugin automatically derives a safe default from the storage adapter:
-     * - `s3Adapter` → the configured `publicBaseUrl`
-     * - `vercelBlobAdapter` → any URL whose hostname ends with `.public.blob.vercel-storage.com`
-     * - `localAdapter` → rejects client-supplied URLs; use `POST /media/upload` instead
-     *
-     * Provide this option only when you need to override the automatic default (e.g. to allow
-     * assets from a CDN in front of your storage that uses a different domain). When using
-     * `localAdapter`, setting `allowedUrlPrefixes` explicitly opts `POST /media/assets` back in.
-     *
-     * @remarks
-     * Protocol-only prefixes such as `"https://"` (and especially `"http://"`) disable
-     * origin-based restrictions entirely — any URL with that scheme will be accepted.
-     * Only use them when you intentionally want to allow assets from arbitrary hosts:
-     * `"http://"` URLs will be blocked as mixed content on HTTPS pages, and if your
-     * `onAfterUpload` hook fetches asset URLs server-side, accepting arbitrary hosts
-     * can expose an SSRF surface. Prefer full origin prefixes like
-     * `"https://cdn.example.com"` whenever possible.
-     */
-    allowedUrlPrefixes?: string[];
-    /**
-     * Optional lifecycle hooks for the media backend plugin.
-     */
-    hooks?: MediaBackendHooks;
-    /**
-     * Optional function to resolve a tenant ID from the incoming request context.
-     *
-     * When provided, all asset and folder list/create operations through the HTTP
-     * API are automatically scoped to the returned tenant ID:
-     * - GET /media/assets  →  filters results to the resolved tenant
-     * - POST /media/assets →  tags the created asset with the resolved tenant
-     * - POST /media/upload →  tags the uploaded asset with the resolved tenant
-     * - GET /media/folders →  filters results to the resolved tenant
-     * - POST /media/folders → tags the created folder with the resolved tenant
-     *
-     * When absent, no tenant filtering is applied (existing behaviour).
-     *
-     * Returning `null` or `undefined` means "no tenant" for this request —
-     * the operation proceeds without tenant scoping (useful for super-admin routes).
-     */
-    resolveTenantId?: (context: MediaApiContext) => Promise<string | null | undefined> | string | null | undefined;
-}
-/**
- * Media backend plugin.
- * Provides API endpoints for managing media assets and folders, and supports
- * local, S3-compatible, and Vercel Blob storage backends.
- *
- * @example
- * ```ts
- * import { mediaBackendPlugin, localAdapter } from "@btst/stack/plugins/media/api";
- *
- * mediaBackendPlugin({
- *   storageAdapter: localAdapter(),
- *   hooks: {
- *     onBeforeUpload: async (_meta, ctx) => {
- *       const session = await getSession(ctx.headers as Headers);
- *       if (!session) throw new Error("Unauthorized");
- *     },
- *   },
- * })
- * ```
- */
-declare const mediaBackendPlugin: (config: MediaBackendConfig) => _btst_stack_plugins_api.BackendPlugin<{
-    readonly listAssets: better_call.StrictEndpoint<"/media/assets", {} & {
-        method: "GET";
-    } & {
-        query: better_call.StandardSchemaV1<{
-            folderId?: string | undefined;
-            mimeType?: string | undefined;
-            query?: string | undefined;
-            offset?: unknown;
-            limit?: unknown;
-        }, {
-            folderId?: string | undefined;
-            mimeType?: string | undefined;
-            query?: string | undefined;
-            offset?: unknown;
-            limit?: unknown;
-        }>;
-    }, AssetListResult>;
-    readonly createAsset: better_call.StrictEndpoint<"/media/assets", {} & {
-        method: "POST";
-        body: better_call.StandardSchemaV1<{
-            filename: string;
-            originalName: string;
-            mimeType: string;
-            size: number;
-            url: string;
-            folderId?: string | undefined;
-            alt?: string | undefined;
-        }, {
-            filename: string;
-            originalName: string;
-            mimeType: string;
-            size: number;
-            url: string;
-            folderId?: string | undefined;
-            alt?: string | undefined;
-        }>;
-    }, Asset>;
-    readonly updateAsset: better_call.StrictEndpoint<"/media/assets/:id", {} & {
-        method: "PATCH";
-        body: better_call.StandardSchemaV1<{
-            alt?: string | undefined;
-            folderId?: string | null | undefined;
-        }, {
-            alt?: string | undefined;
-            folderId?: string | null | undefined;
-        }>;
-    }, Asset>;
-    readonly deleteAsset: better_call.StrictEndpoint<"/media/assets/:id", {} & {
-        method: "DELETE";
-        body: better_call.StandardSchemaV1<unknown, unknown>;
-    }, {
-        success: boolean;
-    }>;
-    readonly listFolders: better_call.StrictEndpoint<"/media/folders", {} & {
-        method: "GET";
-    } & {
-        query: better_call.StandardSchemaV1<{
-            parentId: string | null | undefined;
-        } | {
-            parentId?: string | undefined;
-        }, {
-            parentId: string | null | undefined;
-        } | {
-            parentId?: string | undefined;
-        }>;
-    }, Folder[]>;
-    readonly createFolder: better_call.StrictEndpoint<"/media/folders", {} & {
-        method: "POST";
-        body: better_call.StandardSchemaV1<{
-            name: string;
-            parentId?: string | undefined;
-        }, {
-            name: string;
-            parentId?: string | undefined;
-        }>;
-    }, Folder>;
-    readonly deleteFolder: better_call.StrictEndpoint<"/media/folders/:id", {} & {
-        method: "DELETE";
-        body: better_call.StandardSchemaV1<unknown, unknown>;
-    }, {
-        success: boolean;
-    }>;
-    readonly uploadDirect: better_call.StrictEndpoint<"/media/upload", {
-        metadata: {
-            allowedMediaTypes: string[];
-        };
-    } & {
-        method: "POST";
-        body: better_call.StandardSchemaV1<unknown, unknown>;
-    }, Asset>;
-    readonly uploadToken: better_call.StrictEndpoint<"/media/upload/token", {} & {
-        method: "POST";
-        body: better_call.StandardSchemaV1<{
-            filename: string;
-            mimeType: string;
-            size: number;
-            folderId?: string | undefined;
-        }, {
-            filename: string;
-            mimeType: string;
-            size: number;
-            folderId?: string | undefined;
-        }>;
-    }, S3UploadToken>;
-    readonly uploadVercelBlob: better_call.StrictEndpoint<"/media/upload/vercel-blob", {} & {
-        method: "POST";
-        body: better_call.StandardSchemaV1<unknown, unknown>;
-    }, unknown>;
-}, {
-    listAssets: (params?: Parameters<typeof listAssets>[1]) => Promise<AssetListResult>;
-    getAssetById: (id: string) => Promise<Asset | null>;
-    createAsset: (input: Parameters<typeof createAsset>[1]) => Promise<Asset>;
-    updateAsset: (id: string, input: Parameters<typeof updateAsset>[2]) => Promise<Asset | null>;
-    listFolders: (params?: Parameters<typeof listFolders>[1]) => Promise<Folder[]>;
-    getFolderById: (id: string) => Promise<Folder | null>;
-    getFolderByName: (name: string, parentId?: string | null, tenantId?: string) => Promise<Folder | null>;
-    createFolder: (input: Parameters<typeof createFolder>[1]) => Promise<Folder>;
-}>;
-type MediaApiRouter = ReturnType<ReturnType<typeof mediaBackendPlugin>["routes"]>;
-
-/**
- * Internal query key constants for the media plugin.
- * Shared between query-keys.ts (HTTP path) and any SSR/SSG prefetching
- * to prevent key drift between client and server.
- */
-
-/**
- * Discriminator for the asset list cache key.
- */
-interface AssetListDiscriminator {
-    folderId: string | undefined;
-    mimeType: string | undefined;
-    query: string | undefined;
-    limit: number | undefined;
-    offset: number | undefined;
-}
-declare function assetListDiscriminator(params?: AssetListParams): AssetListDiscriminator;
-type FolderListDiscriminator = "all" | "root" | string;
-declare function folderListDiscriminator(parentId?: string | null): FolderListDiscriminator;
-/** Full query key builders — use these with `queryClient.setQueryData()`. */
-declare const MEDIA_QUERY_KEYS: {
-    assetsList: (params?: AssetListParams) => readonly ["mediaAssets", "list", AssetListDiscriminator];
-    assetDetail: (id: string) => readonly ["mediaAssets", "detail", string];
-    foldersList: (parentId?: string | null) => readonly ["mediaFolders", "list", string];
-};
-
-export { MEDIA_QUERY_KEYS as M, listFolders as a, getFolderById as b, getFolderByName as c, createAsset as e, deleteAsset as f, getAssetById as g, createFolder as h, deleteFolder as i, assetListDiscriminator as k, listAssets as l, folderListDiscriminator as m, mediaBackendPlugin as q, updateAsset as u };
-export type { AssetListParams as A, CreateAssetInput as C, FolderListParams as F, UpdateAssetInput as U, AssetListResult as d, CreateFolderInput as j, MediaApiContext as n, MediaBackendHooks as o, MediaBackendConfig as p, MediaApiRouter as r, AssetListDiscriminator as s };