nextly 0.0.1 → 0.0.2-alpha.1

package/dist/_dts-chunks/media.d-DjDOZo4B.d.ts

@@ -0,0 +1,117 @@
+import { z } from 'zod';
+
+/**
+ * Media Types and Schemas
+ *
+ * Type-safe definitions for media management with Zod validation
+ */
+
+/**
+ * Metadata for a single generated image size variant.
+ * Stored in the media.sizes JSONB field, keyed by size name.
+ */
+interface ImageSizeVariant {
+    url: string;
+    path: string;
+    width: number;
+    height: number;
+    filesize: number;
+    mimeType: string;
+    filename: string;
+}
+declare const MediaSchema: z.ZodObject<{
+    id: z.ZodString;
+    filename: z.ZodString;
+    originalFilename: z.ZodString;
+    mimeType: z.ZodString;
+    size: z.ZodNumber;
+    width: z.ZodNullable<z.ZodNumber>;
+    height: z.ZodNullable<z.ZodNumber>;
+    duration: z.ZodNullable<z.ZodNumber>;
+    url: z.ZodString;
+    thumbnailUrl: z.ZodNullable<z.ZodString>;
+    focalX: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    focalY: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    sizes: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodObject<{
+        url: z.ZodString;
+        path: z.ZodString;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        filesize: z.ZodNumber;
+        mimeType: z.ZodString;
+        filename: z.ZodString;
+    }, z.core.$strip>>>>;
+    altText: z.ZodNullable<z.ZodString>;
+    caption: z.ZodNullable<z.ZodString>;
+    tags: z.ZodNullable<z.ZodArray<z.ZodString>>;
+    folderId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    uploadedBy: z.ZodNullable<z.ZodString>;
+    uploadedAt: z.ZodDate;
+    updatedAt: z.ZodDate;
+}, z.core.$strip>;
+type Media = z.infer<typeof MediaSchema>;
+declare const UploadMediaInputSchema: z.ZodObject<{
+    file: z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>;
+    filename: z.ZodString;
+    mimeType: z.ZodString;
+    size: z.ZodNumber;
+    uploadedBy: z.ZodNullable<z.ZodString>;
+    folderId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type UploadMediaInput = z.infer<typeof UploadMediaInputSchema>;
+declare const UpdateMediaInputSchema: z.ZodObject<{
+    altText: z.ZodOptional<z.ZodString>;
+    caption: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    focalX: z.ZodOptional<z.ZodNumber>;
+    focalY: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type UpdateMediaInput = z.infer<typeof UpdateMediaInputSchema>;
+declare const MediaParamsSchema: z.ZodObject<{
+    page: z.ZodDefault<z.ZodNumber>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    search: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodEnum<{
+        video: "video";
+        image: "image";
+        audio: "audio";
+        document: "document";
+        other: "other";
+    }>>;
+    folderId: z.ZodOptional<z.ZodString>;
+    sortBy: z.ZodDefault<z.ZodEnum<{
+        filename: "filename";
+        size: "size";
+        uploadedAt: "uploadedAt";
+    }>>;
+    sortOrder: z.ZodDefault<z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+}, z.core.$strip>;
+type MediaParams = z.infer<typeof MediaParamsSchema>;
+interface MediaListResponse {
+    success: boolean;
+    statusCode: number;
+    message: string;
+    data: Media[] | null;
+    meta?: {
+        total: number;
+        page: number;
+        limit: number;
+        totalPages: number;
+    };
+}
+interface MediaResponse {
+    success: boolean;
+    statusCode: number;
+    message: string;
+    data: Media | null;
+}
+interface DeleteMediaResponse {
+    success: boolean;
+    statusCode: number;
+    message: string;
+}
+
+export type { DeleteMediaResponse as D, ImageSizeVariant as I, Media as M, UploadMediaInput as U, MediaParams as a, MediaListResponse as b, MediaResponse as c, UpdateMediaInput as d };

package/dist/_dts-chunks/on-error.d-CHIKWNxd.d.ts

@@ -0,0 +1,38 @@
+import { NextlyError } from '../errors/index.d.ts';
+
+/**
+ * Observability hook fired by withErrorHandler / withAction / instrumentation
+ * after a NextlyError has been classified and logged.
+ *
+ * Intended for plugging Sentry, Datadog, Better Stack, or OpenTelemetry. The
+ * hook receives the NextlyError plus a discriminated context describing the
+ * boundary that caught it.
+ *
+ * Hook implementations run in try/catch so a failing hook never poisons the
+ * response or action result.
+ */
+type OnErrorHook = (err: NextlyError, ctx: {
+    kind: "route-handler";
+    requestId: string;
+    route?: string;
+    method?: string;
+    request: Request;
+} | {
+    kind: "server-action";
+    requestId: string;
+} | {
+    kind: "framework";
+    requestId: string;
+}) => void | Promise<void>;
+/**
+ * Register a process-wide onError hook. Typically called inside
+ * `createNextlyInstrumentation({ onError })` from the developer's
+ * `app/instrumentation.ts`. A per-call hook on `withErrorHandler` /
+ * `withAction` runs before this one for that boundary.
+ */
+declare function setGlobalOnError(hook: OnErrorHook | undefined): void;
+/** The currently registered global onError hook (or undefined). */
+declare function getGlobalOnError(): OnErrorHook | undefined;
+
+export { getGlobalOnError as g, setGlobalOnError as s };
+export type { OnErrorHook as O };

package/dist/_dts-chunks/storage.d-BUhQ2we_.d.ts

@@ -0,0 +1,404 @@
+import { S as StoragePlugin, I as IStorageAdapter, C as CollectionStorageConfig, U as UploadOptions, c as UploadResult, B as BulkDeleteResult, d as ClientUploadData } from './image-processor.d-OO1PmMrv.d.ts';
+
+/**
+ * Unified Media Storage Manager
+ *
+ * Manages storage adapters and routes uploads to appropriate backends
+ * based on collection configuration. Supports:
+ * - AWS S3 / Cloudflare R2 / MinIO (via @nextlyhq/storage-s3)
+ * - Vercel Blob (via @nextlyhq/storage-vercel-blob)
+ * - Collection-specific storage routing
+ *
+ * @example With Vercel Blob storage (configured in nextly.config.ts)
+ * ```typescript
+ * import { vercelBlobStorage } from '@nextlyhq/storage-vercel-blob';
+ *
+ * export default defineConfig({
+ *   storage: [
+ *     vercelBlobStorage({
+ *       collections: { media: true }
+ *     })
+ *   ]
+ * });
+ * ```
+ *
+ * @example With S3 storage (configured in nextly.config.ts)
+ * ```typescript
+ * import { s3Storage } from '@nextlyhq/storage-s3';
+ *
+ * export default defineConfig({
+ *   storage: [
+ *     s3Storage({
+ *       bucket: process.env.S3_BUCKET!,
+ *       region: process.env.AWS_REGION!,
+ *       collections: {
+ *         media: true,
+ *         'private-docs': {
+ *           prefix: 'private/',
+ *           signedDownloads: true,
+ *           clientUploads: true
+ *         }
+ *       }
+ *     })
+ *   ]
+ * });
+ * ```
+ */
+
+/**
+ * Configuration for MediaStorage initialization.
+ */
+interface MediaStorageConfig {
+    /**
+     * Storage plugins from config.
+     * Each plugin provides an adapter for specific collections.
+     *
+     * @example
+     * ```typescript
+     * plugins: [
+     *   s3Storage({ bucket: '...', collections: { media: true } }),
+     *   vercelBlobStorage({ collections: { videos: true } })
+     * ]
+     * ```
+     */
+    plugins?: StoragePlugin[];
+    /**
+     * Local storage configuration.
+     * Used as the default fallback when no cloud plugins are configured.
+     *
+     * @example
+     * ```typescript
+     * local: {
+     *   uploadDir: './public/uploads',
+     *   publicPath: '/uploads',
+     * }
+     * ```
+     */
+    local?: {
+        /** Directory to store uploaded files (default: ./public/uploads) */
+        uploadDir?: string;
+        /** URL path prefix for serving files (default: /uploads) */
+        publicPath?: string;
+    };
+}
+/**
+ * Unified Media Storage Manager.
+ *
+ * Routes uploads to appropriate storage backends based on collection
+ * configuration. Supports plugin-based storage adapters for cloud
+ * providers (S3, Vercel Blob) with collection-specific routing.
+ *
+ * Features:
+ * - Plugin-based cloud storage (S3, Vercel Blob)
+ * - Collection-specific routing
+ * - Client-side upload URL generation
+ * - Signed download URLs
+ */
+declare class MediaStorage {
+    /** Registered storage plugins by name */
+    private plugins;
+    /** Storage adapter per collection */
+    private collectionAdapters;
+    /** Storage configuration per collection */
+    private collectionConfigs;
+    /** Local storage adapter (always available as fallback) */
+    private localAdapter;
+    /**
+     * Create a new MediaStorage instance.
+     *
+     * @param config - Optional configuration for storage initialization
+     */
+    constructor(config?: MediaStorageConfig);
+    /**
+     * Register a storage plugin.
+     *
+     * Plugins provide storage adapters for specific collections.
+     * When a collection is registered with a plugin, uploads for that
+     * collection will be routed to the plugin's adapter.
+     *
+     * @param plugin - The storage plugin to register
+     *
+     * @example
+     * ```typescript
+     * const storage = new MediaStorage();
+     *
+     * storage.registerPlugin(s3Storage({
+     *   bucket: 'my-bucket',
+     *   region: 'us-east-1',
+     *   collections: {
+     *     media: true,
+     *     'private-docs': { prefix: 'private/' }
+     *   }
+     * }));
+     * ```
+     */
+    registerPlugin(plugin: StoragePlugin): void;
+    /**
+     * Check if any storage adapter is configured.
+     *
+     * @returns True if at least one storage plugin is registered
+     */
+    hasAdapter(): boolean;
+    /**
+     * Get the storage adapter if available, or null if not configured.
+     *
+     * Unlike getAdapter(), this method does not throw an error if no storage
+     * is configured. Useful for optional storage scenarios.
+     *
+     * @param collection - The collection slug (optional)
+     * @returns The storage adapter instance, or null if not configured
+     */
+    getAdapterOrNull(collection?: string): IStorageAdapter | null;
+    /**
+     * Get the storage adapter for a specific collection.
+     *
+     * If a plugin is configured for the collection, returns the plugin's adapter.
+     * Otherwise, returns the default adapter (first registered plugin).
+     *
+     * @param collection - The collection slug (optional)
+     * @returns The appropriate storage adapter
+     * @throws Error if no storage plugin is configured
+     */
+    getAdapterForCollection(collection?: string): IStorageAdapter;
+    /**
+     * Get configuration for a specific collection.
+     *
+     * @param collection - The collection slug
+     * @returns The collection's storage configuration, or undefined
+     */
+    getCollectionConfig(collection: string): CollectionStorageConfig | undefined;
+    /**
+     * Upload file to appropriate storage based on collection.
+     *
+     * Routes the upload to the correct adapter based on collection
+     * configuration. Applies collection-specific prefix if configured.
+     *
+     * @param buffer - The file buffer to upload
+     * @param options - Upload options including filename, mimeType, collection
+     * @returns Upload result with URL and path
+     *
+     * @example
+     * ```typescript
+     * const result = await storage.upload(buffer, {
+     *   filename: 'photo.jpg',
+     *   mimeType: 'image/jpeg',
+     *   collection: 'media'
+     * });
+     * console.log(result.url); // Public URL
+     * console.log(result.path); // Storage path for deletion
+     * ```
+     */
+    upload(buffer: Buffer, options: UploadOptions): Promise<UploadResult>;
+    /**
+     * Delete file from storage.
+     *
+     * Determines correct adapter based on collection.
+     *
+     * @param filePath - The storage path/key of the file
+     * @param collection - The collection slug (optional, for routing)
+     */
+    delete(filePath: string, collection?: string): Promise<void>;
+    /**
+     * Bulk delete files from storage.
+     * Uses adapter's native bulkDelete if available, otherwise falls back to
+     * sequential individual deletes in chunks of 10.
+     */
+    bulkDelete(filePaths: string[], collection?: string): Promise<BulkDeleteResult>;
+    /**
+     * Check if file exists in storage.
+     *
+     * @param filePath - The storage path/key to check
+     * @param collection - The collection slug (optional, for routing)
+     * @returns True if file exists
+     */
+    exists(filePath: string, collection?: string): Promise<boolean>;
+    /**
+     * Get public URL for file.
+     *
+     * @param filePath - The storage path/key
+     * @param collection - The collection slug (optional, for routing)
+     * @returns Public URL to access the file
+     */
+    getPublicUrl(filePath: string, collection?: string): string;
+    /**
+     * Get storage type for a collection.
+     *
+     * @param collection - The collection slug (optional)
+     * @returns Storage type identifier ('s3', 'vercel-blob')
+     */
+    getStorageType(collection?: string): string;
+    /**
+     * Check if collection supports client-side uploads.
+     *
+     * Client-side uploads allow direct-to-storage uploads, bypassing
+     * the server. This is essential for serverless platforms with
+     * request body size limits (e.g., Vercel's 4.5MB limit).
+     *
+     * @param collection - The collection slug
+     * @returns True if client uploads are enabled and supported
+     */
+    supportsClientUploads(collection: string): boolean;
+    /**
+     * Get client upload URL for direct-to-storage uploads.
+     *
+     * Generates a pre-signed URL that allows the client to upload
+     * directly to the storage backend, bypassing the server.
+     *
+     * Only available if:
+     * 1. Collection is configured with `clientUploads: true`
+     * 2. The storage adapter supports client uploads
+     *
+     * @param filename - Original filename
+     * @param mimeType - File MIME type
+     * @param collection - Collection slug
+     * @returns Client upload data, or null if not supported
+     *
+     * @example
+     * ```typescript
+     * // Server-side: generate upload URL
+     * const uploadData = await storage.getClientUploadUrl(
+     *   'photo.jpg',
+     *   'image/jpeg',
+     *   'media'
+     * );
+     *
+     * // Client-side: upload directly to storage
+     * await fetch(uploadData.uploadUrl, {
+     *   method: uploadData.method,
+     *   headers: uploadData.headers,
+     *   body: file
+     * });
+     * ```
+     */
+    getClientUploadUrl(filename: string, mimeType: string, collection: string): Promise<ClientUploadData | null>;
+    /**
+     * Check if collection supports signed download URLs.
+     *
+     * @param collection - The collection slug
+     * @returns True if signed downloads are enabled and supported
+     */
+    supportsSignedDownloads(collection: string): boolean;
+    /**
+     * Get signed download URL for secure file access.
+     *
+     * Generates a time-limited signed URL for accessing files in
+     * private storage buckets. Only works if:
+     * 1. Collection is configured with `signedDownloads: true`
+     * 2. The storage adapter supports signed URLs
+     *
+     * @param filePath - Storage path/key of the file
+     * @param collection - Collection slug
+     * @param expiresIn - URL expiry time in seconds (optional)
+     * @returns Signed URL, or null if not supported
+     *
+     * @example
+     * ```typescript
+     * const signedUrl = await storage.getSignedDownloadUrl(
+     *   'private/doc.pdf',
+     *   'private-docs',
+     *   3600 // 1 hour
+     * );
+     * ```
+     */
+    getSignedDownloadUrl(filePath: string, collection: string, expiresIn?: number): Promise<string | null>;
+    /**
+     * Get the default storage adapter.
+     *
+     * @returns The default storage adapter (first registered plugin)
+     * @throws Error if no storage plugin is configured
+     */
+    getDefaultAdapter(): IStorageAdapter;
+    /**
+     * Get list of registered plugins.
+     *
+     * @returns Array of registered storage plugins
+     */
+    getPlugins(): StoragePlugin[];
+    /**
+     * Get the underlying storage adapter for a collection.
+     *
+     * Useful for passing to registerServices() which requires IStorageAdapter.
+     *
+     * @param collection - The collection slug (optional)
+     * @returns The storage adapter instance
+     */
+    getAdapter(collection?: string): IStorageAdapter;
+    /**
+     * Check if a collection has a configured storage adapter.
+     *
+     * @param collection - The collection slug
+     * @returns True if a plugin is configured for this collection
+     */
+    hasCollectionAdapter(collection: string): boolean;
+    /**
+     * Get list of collections with configured storage.
+     *
+     * @returns Array of collection slugs that have plugin storage
+     */
+    getConfiguredCollections(): string[];
+    /**
+     * Check if any storage plugin is configured.
+     *
+     * @returns True if at least one storage plugin is registered
+     */
+    hasPlugins(): boolean;
+}
+/**
+ * Initialize the global MediaStorage instance with plugins.
+ *
+ * Called during Nextly initialization to set up storage with
+ * configured plugins from nextly.config.ts.
+ *
+ * @param config - Storage configuration with plugins
+ * @returns The initialized MediaStorage instance
+ *
+ * @example
+ * ```typescript
+ * // In Nextly initialization
+ * import { initializeMediaStorage } from 'nextly/storage';
+ *
+ * const storage = initializeMediaStorage({
+ *   plugins: config.storage, // From nextly.config.ts
+ * });
+ * ```
+ */
+declare function initializeMediaStorage(config?: MediaStorageConfig): MediaStorage;
+/**
+ * Get the global MediaStorage instance.
+ *
+ * Returns the initialized MediaStorage singleton. If not yet initialized,
+ * creates a new instance without plugins (which will throw errors on upload).
+ *
+ * @returns The MediaStorage instance
+ *
+ * @example
+ * ```typescript
+ * import { getMediaStorage } from 'nextly/storage';
+ *
+ * const storage = getMediaStorage();
+ * const result = await storage.upload(buffer, {
+ *   filename: 'photo.jpg',
+ *   mimeType: 'image/jpeg',
+ *   collection: 'media'
+ * });
+ * ```
+ */
+declare function getMediaStorage(): MediaStorage;
+/**
+ * Reset storage singleton.
+ *
+ * Clears the cached MediaStorage instance. Useful for testing
+ * or when re-initializing with different configuration.
+ *
+ * @example
+ * ```typescript
+ * // In tests
+ * beforeEach(() => {
+ *   resetMediaStorage();
+ * });
+ * ```
+ */
+declare function resetMediaStorage(): void;
+
+export { MediaStorage as M, getMediaStorage as g, initializeMediaStorage as i, resetMediaStorage as r };
+export type { MediaStorageConfig as a };