@btst/stack 2.8.1 → 2.9.1

package/dist/shared/stack.BttDsJJn.d.cts

@@ -0,0 +1,109 @@
+/**
+ * Options provided to storage adapters when initiating an upload.
+ */
+interface UploadOptions {
+    filename: string;
+    mimeType: string;
+    size: number;
+    folderId?: string;
+}
+/**
+ * Local storage adapter — backend receives and stores file bytes directly.
+ * Suitable for development and self-hosted deployments.
+ */
+interface DirectStorageAdapter {
+    readonly type: "local";
+    /**
+     * Store the file buffer and return the public URL.
+     */
+    upload(buffer: Buffer, options: UploadOptions): Promise<{
+        url: string;
+    }>;
+    /**
+     * Remove the stored file given its public URL.
+     */
+    delete(url: string): Promise<void>;
+}
+/**
+ * Token returned by the S3 adapter.
+ * The client performs a `PUT` to `payload.uploadUrl` with the file body,
+ * then saves `payload.publicUrl` as the asset URL.
+ */
+interface S3UploadToken {
+    type: "presigned-url";
+    payload: {
+        uploadUrl: string;
+        publicUrl: string;
+        key: string;
+        method: "PUT";
+        headers: Record<string, string>;
+    };
+}
+/**
+ * S3 storage adapter — server issues a short-lived presigned PUT URL;
+ * the browser uploads directly to S3 (or R2 / MinIO).
+ */
+interface S3StorageAdapter {
+    readonly type: "s3";
+    /**
+     * The public base URL prefix for all assets in this bucket
+     * (e.g. `"https://assets.example.com"`). Used by the plugin to
+     * automatically validate client-supplied URLs when no explicit
+     * `allowedUrlPrefixes` are configured.
+     */
+    readonly urlPrefix: string;
+    /**
+     * Generate a presigned PUT URL for direct client upload.
+     */
+    generateUploadToken(options: UploadOptions): Promise<S3UploadToken>;
+    /**
+     * Remove the stored object given its public URL.
+     */
+    delete(url: string): Promise<void>;
+}
+/**
+ * Options returned from onBeforeGenerateToken and passed to Vercel Blob's handleUpload.
+ */
+interface VercelBlobTokenOptions {
+    addRandomSuffix?: boolean;
+    allowedContentTypes?: string[];
+    maximumSizeInBytes?: number;
+}
+/**
+ * Callbacks provided to the Vercel Blob adapter when handling a request.
+ */
+interface VercelBlobHandlerCallbacks {
+    /**
+     * Called before a client token is generated.
+     * Throw to reject the upload (auth gate).
+     * Return options to enforce allowedContentTypes and maximumSizeInBytes at the edge.
+     */
+    onBeforeGenerateToken?: (pathname: string, clientPayload: string | null) => Promise<VercelBlobTokenOptions | void> | VercelBlobTokenOptions | void;
+}
+/**
+ * Vercel Blob storage adapter — uses the `@vercel/blob/client` `handleUpload`
+ * protocol. The same endpoint handles both token generation and upload
+ * completion notifications from Vercel's servers.
+ */
+interface VercelBlobStorageAdapter {
+    readonly type: "vercel-blob";
+    /**
+     * Hostname suffix that all Vercel Blob public URLs end with.
+     * Used by the plugin to automatically validate client-supplied URLs.
+     * Always `".public.blob.vercel-storage.com"`.
+     */
+    readonly urlHostnameSuffix: string;
+    /**
+     * Process a raw request from `@vercel/blob/client`'s `upload()` or from
+     * Vercel Blob's upload-completion webhook. Returns a JSON-serialisable object
+     * that should be sent back as the response body.
+     */
+    handleRequest(request: Request, callbacks: VercelBlobHandlerCallbacks): Promise<unknown>;
+    /**
+     * Remove the stored blob given its public URL.
+     */
+    delete(url: string): Promise<void>;
+}
+type StorageAdapter = DirectStorageAdapter | S3StorageAdapter | VercelBlobStorageAdapter;
+
+export type { DirectStorageAdapter as D, S3StorageAdapter as S, UploadOptions as U, VercelBlobStorageAdapter as V, StorageAdapter as a, S3UploadToken as b, VercelBlobHandlerCallbacks as c };

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

@@ -0,0 +1,109 @@
+/**
+ * Options provided to storage adapters when initiating an upload.
+ */
+interface UploadOptions {
+    filename: string;
+    mimeType: string;
+    size: number;
+    folderId?: string;
+}
+/**
+ * Local storage adapter — backend receives and stores file bytes directly.
+ * Suitable for development and self-hosted deployments.
+ */
+interface DirectStorageAdapter {
+    readonly type: "local";
+    /**
+     * Store the file buffer and return the public URL.
+     */
+    upload(buffer: Buffer, options: UploadOptions): Promise<{
+        url: string;
+    }>;
+    /**
+     * Remove the stored file given its public URL.
+     */
+    delete(url: string): Promise<void>;
+}
+/**
+ * Token returned by the S3 adapter.
+ * The client performs a `PUT` to `payload.uploadUrl` with the file body,
+ * then saves `payload.publicUrl` as the asset URL.
+ */
+interface S3UploadToken {
+    type: "presigned-url";
+    payload: {
+        uploadUrl: string;
+        publicUrl: string;
+        key: string;
+        method: "PUT";
+        headers: Record<string, string>;
+    };
+}
+/**
+ * S3 storage adapter — server issues a short-lived presigned PUT URL;
+ * the browser uploads directly to S3 (or R2 / MinIO).
+ */
+interface S3StorageAdapter {
+    readonly type: "s3";
+    /**
+     * The public base URL prefix for all assets in this bucket
+     * (e.g. `"https://assets.example.com"`). Used by the plugin to
+     * automatically validate client-supplied URLs when no explicit
+     * `allowedUrlPrefixes` are configured.
+     */
+    readonly urlPrefix: string;
+    /**
+     * Generate a presigned PUT URL for direct client upload.
+     */
+    generateUploadToken(options: UploadOptions): Promise<S3UploadToken>;
+    /**
+     * Remove the stored object given its public URL.
+     */
+    delete(url: string): Promise<void>;
+}
+/**
+ * Options returned from onBeforeGenerateToken and passed to Vercel Blob's handleUpload.
+ */
+interface VercelBlobTokenOptions {
+    addRandomSuffix?: boolean;
+    allowedContentTypes?: string[];
+    maximumSizeInBytes?: number;
+}
+/**
+ * Callbacks provided to the Vercel Blob adapter when handling a request.
+ */
+interface VercelBlobHandlerCallbacks {
+    /**
+     * Called before a client token is generated.
+     * Throw to reject the upload (auth gate).
+     * Return options to enforce allowedContentTypes and maximumSizeInBytes at the edge.
+     */
+    onBeforeGenerateToken?: (pathname: string, clientPayload: string | null) => Promise<VercelBlobTokenOptions | void> | VercelBlobTokenOptions | void;
+}
+/**
+ * Vercel Blob storage adapter — uses the `@vercel/blob/client` `handleUpload`
+ * protocol. The same endpoint handles both token generation and upload
+ * completion notifications from Vercel's servers.
+ */
+interface VercelBlobStorageAdapter {
+    readonly type: "vercel-blob";
+    /**
+     * Hostname suffix that all Vercel Blob public URLs end with.
+     * Used by the plugin to automatically validate client-supplied URLs.
+     * Always `".public.blob.vercel-storage.com"`.
+     */
+    readonly urlHostnameSuffix: string;
+    /**
+     * Process a raw request from `@vercel/blob/client`'s `upload()` or from
+     * Vercel Blob's upload-completion webhook. Returns a JSON-serialisable object
+     * that should be sent back as the response body.
+     */
+    handleRequest(request: Request, callbacks: VercelBlobHandlerCallbacks): Promise<unknown>;
+    /**
+     * Remove the stored blob given its public URL.
+     */
+    delete(url: string): Promise<void>;
+}
+type StorageAdapter = DirectStorageAdapter | S3StorageAdapter | VercelBlobStorageAdapter;
+
+export type { DirectStorageAdapter as D, S3StorageAdapter as S, UploadOptions as U, VercelBlobStorageAdapter as V, StorageAdapter as a, S3UploadToken as b, VercelBlobHandlerCallbacks as c };

package/dist/shared/stack.BttDsJJn.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Options provided to storage adapters when initiating an upload.
+ */
+interface UploadOptions {
+    filename: string;
+    mimeType: string;
+    size: number;
+    folderId?: string;
+}
+/**
+ * Local storage adapter — backend receives and stores file bytes directly.
+ * Suitable for development and self-hosted deployments.
+ */
+interface DirectStorageAdapter {
+    readonly type: "local";
+    /**
+     * Store the file buffer and return the public URL.
+     */
+    upload(buffer: Buffer, options: UploadOptions): Promise<{
+        url: string;
+    }>;
+    /**
+     * Remove the stored file given its public URL.
+     */
+    delete(url: string): Promise<void>;
+}
+/**
+ * Token returned by the S3 adapter.
+ * The client performs a `PUT` to `payload.uploadUrl` with the file body,
+ * then saves `payload.publicUrl` as the asset URL.
+ */
+interface S3UploadToken {
+    type: "presigned-url";
+    payload: {
+        uploadUrl: string;
+        publicUrl: string;
+        key: string;
+        method: "PUT";
+        headers: Record<string, string>;
+    };
+}
+/**
+ * S3 storage adapter — server issues a short-lived presigned PUT URL;
+ * the browser uploads directly to S3 (or R2 / MinIO).
+ */
+interface S3StorageAdapter {
+    readonly type: "s3";
+    /**
+     * The public base URL prefix for all assets in this bucket
+     * (e.g. `"https://assets.example.com"`). Used by the plugin to
+     * automatically validate client-supplied URLs when no explicit
+     * `allowedUrlPrefixes` are configured.
+     */
+    readonly urlPrefix: string;
+    /**
+     * Generate a presigned PUT URL for direct client upload.
+     */
+    generateUploadToken(options: UploadOptions): Promise<S3UploadToken>;
+    /**
+     * Remove the stored object given its public URL.
+     */
+    delete(url: string): Promise<void>;
+}
+/**
+ * Options returned from onBeforeGenerateToken and passed to Vercel Blob's handleUpload.
+ */
+interface VercelBlobTokenOptions {
+    addRandomSuffix?: boolean;
+    allowedContentTypes?: string[];
+    maximumSizeInBytes?: number;
+}
+/**
+ * Callbacks provided to the Vercel Blob adapter when handling a request.
+ */
+interface VercelBlobHandlerCallbacks {
+    /**
+     * Called before a client token is generated.
+     * Throw to reject the upload (auth gate).
+     * Return options to enforce allowedContentTypes and maximumSizeInBytes at the edge.
+     */
+    onBeforeGenerateToken?: (pathname: string, clientPayload: string | null) => Promise<VercelBlobTokenOptions | void> | VercelBlobTokenOptions | void;
+}
+/**
+ * Vercel Blob storage adapter — uses the `@vercel/blob/client` `handleUpload`
+ * protocol. The same endpoint handles both token generation and upload
+ * completion notifications from Vercel's servers.
+ */
+interface VercelBlobStorageAdapter {
+    readonly type: "vercel-blob";
+    /**
+     * Hostname suffix that all Vercel Blob public URLs end with.
+     * Used by the plugin to automatically validate client-supplied URLs.
+     * Always `".public.blob.vercel-storage.com"`.
+     */
+    readonly urlHostnameSuffix: string;
+    /**
+     * Process a raw request from `@vercel/blob/client`'s `upload()` or from
+     * Vercel Blob's upload-completion webhook. Returns a JSON-serialisable object
+     * that should be sent back as the response body.
+     */
+    handleRequest(request: Request, callbacks: VercelBlobHandlerCallbacks): Promise<unknown>;
+    /**
+     * Remove the stored blob given its public URL.
+     */
+    delete(url: string): Promise<void>;
+}
+type StorageAdapter = DirectStorageAdapter | S3StorageAdapter | VercelBlobStorageAdapter;
+
+export type { DirectStorageAdapter as D, S3StorageAdapter as S, UploadOptions as U, VercelBlobStorageAdapter as V, StorageAdapter as a, S3UploadToken as b, VercelBlobHandlerCallbacks as c };

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

@@ -0,0 +1,63 @@
+import { DBAdapter } from '@btst/db';
+import { A as Asset, F as Folder } from './stack.CLcnSF_b.mjs';
+
+/**
+ * Parameters for filtering and paginating the asset list.
+ */
+interface AssetListParams {
+    folderId?: string;
+    mimeType?: string;
+    query?: string;
+    offset?: number;
+    limit?: number;
+}
+/**
+ * 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;
+}
+/**
+ * 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>;
+
+export { listFolders as a, getFolderById as b, getAssetById as g, listAssets as l };
+export type { AssetListParams as A, FolderListParams as F, AssetListResult as c };

package/dist/shared/stack.CAni8dnD.d.cts

@@ -0,0 +1,63 @@
+import { DBAdapter } from '@btst/db';
+import { A as Asset, F as Folder } from './stack.CLcnSF_b.cjs';
+
+/**
+ * Parameters for filtering and paginating the asset list.
+ */
+interface AssetListParams {
+    folderId?: string;
+    mimeType?: string;
+    query?: string;
+    offset?: number;
+    limit?: number;
+}
+/**
+ * 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;
+}
+/**
+ * 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>;
+
+export { listFolders as a, getFolderById as b, getAssetById as g, listAssets as l };
+export type { AssetListParams as A, FolderListParams as F, AssetListResult as c };