@plyaz/types 1.39.5 → 1.39.7

package/dist/core/frameworks/nextjs-types.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Next.js Framework Types
+ *
+ * Types for @plyaz/core Next.js framework adapters.
+ * Used by route factories and config helpers.
+ */
+import type { NextConfig } from 'next';
+import type { RouteContext, MethodHandlerTypes, HandlersTypeMap } from './route-types';
+import type { CoreInjectedServices } from '../domain/types';
+/**
+ * NextRequest compatible type - uses global Request to avoid version conflicts between packages.
+ * The actual runtime type will be NextRequest from next/server.
+ * This avoids issues where different packages have different Next.js versions installed.
+ */
+export type CoreNextRequestCompat = Request & {
+    nextUrl: URL & {
+        searchParams: URLSearchParams;
+    };
+    cookies: unknown;
+    geo?: unknown;
+    ip?: string;
+};
+/**
+ * Next.js App Router route context shape.
+ * Params are async (Promise) in Next.js 15+ App Router.
+ */
+export interface CoreNextRouteContext<TParams extends Record<string, string> = Record<string, string>> {
+    params: Promise<TParams>;
+}
+/**
+ * Generic handler type for internal factory use.
+ * All type params use defaults (Record<string, string> for params/query, unknown for body/response).
+ */
+export type CoreGenericRouteHandler<TService> = CoreNextJSRouteHandler<TService>;
+/**
+ * Extended route context for Next.js with full type support
+ */
+export interface CoreNextJSRouteContext<TParams extends Record<string, string> = Record<string, string>, TQuery extends Record<string, string> = Record<string, string>, TBody = unknown> extends RouteContext<TParams, TQuery> {
+    /** Parsed request body (for POST/PUT/PATCH) */
+    body: TBody;
+    /** The original Next.js request (compatible type to avoid version conflicts) */
+    request: CoreNextRequestCompat;
+    /** Injected Core services (db, cache, storage, notifications) */
+    services: CoreInjectedServices;
+}
+/**
+ * Extract handler type for a specific method
+ */
+export type CoreGetMethodTypes<TMap extends HandlersTypeMap, TMethod extends keyof HandlersTypeMap> = TMap[TMethod] extends MethodHandlerTypes ? TMap[TMethod] : MethodHandlerTypes;
+/**
+ * Next.js specific handler type with full generics
+ */
+export type CoreNextJSRouteHandler<TService, TParams extends Record<string, string> = Record<string, string>, TQuery extends Record<string, string> = Record<string, string>, TBody = unknown, TResponse = unknown> = (service: TService, ctx: CoreNextJSRouteContext<TParams, TQuery, TBody>) => Promise<TResponse>;
+/**
+ * Configuration for Next.js route factory with full generic support
+ */
+export interface CoreNextJSRouteConfig<TService, THandlerTypes extends HandlersTypeMap = HandlersTypeMap> {
+    /** Service name (registered in ServiceRegistry) or factory function */
+    service: string | (() => Promise<TService>);
+    /** Handlers for each HTTP method with typed params/body/response */
+    handlers: {
+        [K in keyof THandlerTypes & keyof HandlersTypeMap]?: CoreNextJSRouteHandler<TService, CoreGetMethodTypes<THandlerTypes, K>['params'] extends Record<string, string> ? CoreGetMethodTypes<THandlerTypes, K>['params'] : Record<string, string>, CoreGetMethodTypes<THandlerTypes, K>['query'] extends Record<string, string> ? CoreGetMethodTypes<THandlerTypes, K>['query'] : Record<string, string>, CoreGetMethodTypes<THandlerTypes, K>['body'], CoreGetMethodTypes<THandlerTypes, K>['response']>;
+    };
+    /**
+     * Function to get Core (ensures initialization before handling)
+     * If not provided, uses ServiceRegistry directly
+     */
+    getCore?: () => Promise<unknown>;
+    /** Custom success message template */
+    successMessage?: string | ((method: string) => string);
+    /** Error handler source name for logging */
+    errorSource?: string;
+    /**
+     * Whether to inject Core services into context.
+     * @default true
+     */
+    injectServices?: boolean;
+}
+/**
+ * Type for the exported route handlers (uses compatible Request type)
+ */
+export type CoreNextJSRouteExports = {
+    GET?: (request: CoreNextRequestCompat, context?: CoreNextRouteContext) => Promise<Response>;
+    POST?: (request: CoreNextRequestCompat, context?: CoreNextRouteContext) => Promise<Response>;
+    PUT?: (request: CoreNextRequestCompat, context?: CoreNextRouteContext) => Promise<Response>;
+    PATCH?: (request: CoreNextRequestCompat, context?: CoreNextRouteContext) => Promise<Response>;
+    DELETE?: (request: CoreNextRequestCompat, context?: CoreNextRouteContext) => Promise<Response>;
+    OPTIONS?: (request: CoreNextRequestCompat, context?: CoreNextRouteContext) => Promise<Response>;
+    HEAD?: (request: CoreNextRequestCompat, context?: CoreNextRouteContext) => Promise<Response>;
+};
+/**
+ * Options for configuring Plyaz with Next.js
+ */
+export interface CorePlyazNextConfigOptions {
+    /**
+     * Additional server external packages to include
+     */
+    additionalExternalPackages?: string[];
+    /**
+     * Additional webpack client fallbacks
+     */
+    additionalClientFallbacks?: Record<string, false>;
+    /**
+     * Additional webpack client aliases
+     */
+    additionalClientAliases?: Record<string, false>;
+    /**
+     * Whether to disable the default external packages (advanced)
+     * @default false
+     */
+    disableDefaultExternalPackages?: boolean;
+    /**
+     * Whether to disable the default client fallbacks (advanced)
+     * @default false
+     */
+    disableDefaultClientFallbacks?: boolean;
+}
+/**
+ * Type helper for Next.js config with Plyaz types
+ */
+export type CorePlyazNextConfig = NextConfig;

package/dist/core/frameworks/route-types.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Route Handler Types
+ *
+ * Framework-agnostic types for route handlers used by @plyaz/core framework adapters.
+ * These types are used by Next.js, Express, and NestJS route factories.
+ */
+export type { HttpMethod } from '../../api/config/types';
+/**
+ * Base route context interface (framework-agnostic)
+ */
+export interface RouteContext<TParams = Record<string, string>, TQuery = Record<string, string>> {
+    /** Route parameters (e.g., from /users/:id -> { id: string }) */
+    params: TParams;
+    /** Query string parameters */
+    query: TQuery;
+    /** Request headers */
+    headers: Record<string, string | undefined>;
+    /** HTTP method */
+    method: string;
+    /** Original request object (framework-specific) */
+    request: unknown;
+}
+/**
+ * Handler function signature for route operations
+ */
+export type RouteHandler<TService, TResult = unknown> = (service: TService, ctx: RouteContext) => Promise<TResult>;
+/**
+ * Configuration for a route with multiple HTTP method handlers
+ */
+export interface RouteHandlerConfig<TService> {
+    /** Service name (registered in ServiceRegistry) or factory function */
+    service: string | (() => Promise<TService>);
+    /** Handlers for each HTTP method */
+    handlers: {
+        GET?: RouteHandler<TService>;
+        POST?: RouteHandler<TService>;
+        PUT?: RouteHandler<TService>;
+        PATCH?: RouteHandler<TService>;
+        DELETE?: RouteHandler<TService>;
+        OPTIONS?: RouteHandler<TService>;
+        HEAD?: RouteHandler<TService>;
+    };
+    /** Custom success message template (default: 'Operation successful') */
+    successMessage?: string | ((method: string) => string);
+}
+/**
+ * Handler type definitions per HTTP method
+ */
+export interface MethodHandlerTypes {
+    params?: Record<string, string>;
+    query?: Record<string, string>;
+    body?: unknown;
+    response?: unknown;
+}
+/**
+ * Handler types map for all HTTP methods
+ */
+export interface HandlersTypeMap {
+    GET?: MethodHandlerTypes;
+    POST?: MethodHandlerTypes;
+    PUT?: MethodHandlerTypes;
+    PATCH?: MethodHandlerTypes;
+    DELETE?: MethodHandlerTypes;
+    OPTIONS?: MethodHandlerTypes;
+    HEAD?: MethodHandlerTypes;
+}
+/**
+ * Default success messages by HTTP method
+ */
+export declare const DEFAULT_SUCCESS_MESSAGES: Record<string, string>;

package/dist/core/hooks/files/delete.d.ts

@@ -0,0 +1,20 @@
+/**
+ * File Delete Hook Types
+ *
+ * Types for useFileDelete hook.
+ */
+/**
+ * Return type for useFileDelete hook
+ *
+ * Provides file deletion operations.
+ */
+export interface CoreFileDeleteResult {
+    /** Delete a file by ID */
+    deleteFile: (fileId: string) => Promise<void>;
+    /** Delete multiple files by IDs */
+    deleteMultiple: (fileIds: string[], options?: {
+        soft?: boolean;
+    }) => Promise<unknown>;
+    /** Whether currently deleting */
+    isDeleting: boolean;
+}

package/dist/core/hooks/files/download.d.ts

@@ -0,0 +1,36 @@
+/**
+ * File Download Hook Types
+ *
+ * Types for useFileDownload hook.
+ */
+/**
+ * Options for useFileDownload hook
+ *
+ * Note: Progress is tracked via streams (useDownloadProgress, useOverallDownloadProgress).
+ * Errors propagate to global error handling (error boundaries, global error store).
+ * Results are returned from the Promise - no callbacks needed.
+ */
+export interface CoreFileDownloadOptions {
+    /** Auto-trigger browser download when complete (default: true) */
+    autoDownload?: boolean;
+    /** Custom filename for download */
+    filename?: string;
+}
+/**
+ * Return type for useFileDownload hook
+ *
+ * Note: Errors propagate through global error handling (error boundaries,
+ * global error alert store). Results are returned from the Promise.
+ */
+export interface CoreFileDownloadResult {
+    /** Download a file by ID */
+    download: (fileId: string, options?: CoreFileDownloadOptions) => Promise<Blob | null>;
+    /** Whether currently downloading */
+    isDownloading: boolean;
+    /** Current download ID (if any) */
+    currentFileId: string | null;
+    /** Current progress percentage */
+    progress: number;
+    /** Cancel current download */
+    cancel: () => void;
+}

package/dist/core/hooks/files/file.d.ts

@@ -0,0 +1,21 @@
+/**
+ * File Hook Types
+ *
+ * Types for useFile hook (metadata operations).
+ */
+/**
+ * Return type for useFile hook
+ *
+ * Provides file metadata operations (read-only).
+ */
+export interface CoreFileResult {
+    /** Fetch file metadata by ID */
+    fetchById: (fileId: string) => Promise<unknown>;
+    /** Get signed URL for a file */
+    getSignedUrl: (fileId: string) => Promise<{
+        url: string;
+        expiresAt: string;
+    }>;
+    /** Check if a file exists */
+    exists: (fileId: string) => Promise<boolean>;
+}

package/dist/core/hooks/files/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * File Hooks Types
+ *
+ * Types for file-related hooks in @plyaz/core.
+ */
+export type { CoreFileOperationType, CoreFileOperationStatus, CoreFileProgressItem, CoreAllFileProgressOptions, CoreAllFileProgressResult, } from './progress';
+export type { CoreFileDownloadOptions, CoreFileDownloadResult } from './download';
+export type { CoreFileUploadOptions, CoreTemplateUploadOptions, CoreGenerateOptions, CoreBulkTemplateUploadOptions, CoreFileUploadResult, } from './upload';
+export type { CoreFileResult } from './file';
+export type { CoreFileDeleteResult } from './delete';

package/dist/core/hooks/files/progress.d.ts

@@ -0,0 +1,68 @@
+/**
+ * File Progress Hook Types
+ *
+ * Types for useAllFileProgress and useHasActiveFileOperations hooks.
+ */
+/**
+ * Operation type for file progress tracking
+ */
+export type CoreFileOperationType = 'upload' | 'download' | 'generate';
+/**
+ * Status for file operations
+ */
+export type CoreFileOperationStatus = 'pending' | 'uploading' | 'downloading' | 'processing' | 'generating' | 'completed' | 'failed' | 'cancelled';
+/**
+ * Unified file progress item from useAllFileProgress hook.
+ * Normalizes upload, download, and generate progress into a single format.
+ */
+export interface CoreFileProgressItem {
+    /** Unique identifier (fileId for upload/download, templateId for generate) */
+    id: string;
+    /** Type of operation */
+    type: CoreFileOperationType;
+    /** Progress percentage (0-100) */
+    percentage: number;
+    /** Bytes loaded (for upload/download) */
+    loaded: number;
+    /** Total bytes (for upload/download) */
+    total: number;
+    /** Current status */
+    status: CoreFileOperationStatus;
+    /** Filename if available */
+    filename?: string;
+    /** Error message if failed */
+    error?: string;
+    /** Timestamp when operation started */
+    startedAt?: string;
+}
+/**
+ * Options for useAllFileProgress hook
+ */
+export interface CoreAllFileProgressOptions {
+    /** Filter to only show progress for specific IDs */
+    filterByIds?: string[];
+    /** Include completed operations (default: false) */
+    includeCompleted?: boolean;
+    /** Include failed operations (default: true) */
+    includeFailed?: boolean;
+    /** Filter by operation type */
+    types?: CoreFileOperationType[];
+}
+/**
+ * Return type for useAllFileProgress hook
+ */
+export interface CoreAllFileProgressResult {
+    /** All active progress items */
+    items: CoreFileProgressItem[];
+    /** Count by operation type */
+    counts: {
+        upload: number;
+        download: number;
+        generate: number;
+        total: number;
+    };
+    /** Whether any operations are active */
+    hasActive: boolean;
+    /** Overall progress percentage across all operations */
+    overallPercentage: number;
+}

package/dist/core/hooks/files/upload.d.ts

@@ -0,0 +1,97 @@
+/**
+ * File Upload Hook Types
+ *
+ * Types for useFileUpload hook.
+ * Uses Pick to extend from existing API types where applicable.
+ */
+import type { UploadFileRequest, GenerateDocumentRequest } from '../../../api';
+/**
+ * Options for useFileUpload hook - direct file upload
+ *
+ * Note: Progress is tracked via streams (useUploadProgress, useOverallUploadProgress).
+ * Errors propagate to global error handling (error boundaries, global error store).
+ * Results are returned from the Promise - no callbacks needed.
+ */
+export interface CoreFileUploadOptions {
+    /** Entity type for file organization */
+    entityType?: string;
+    /** Entity ID for file organization */
+    entityId?: string;
+    /** File category */
+    category?: string;
+    /** Whether file is public */
+    isPublic?: boolean;
+}
+/**
+ * Options for template-based upload (generate document and upload to storage)
+ * Extended from UploadFileRequest API type for consistency.
+ */
+export interface CoreTemplateUploadOptions extends Required<Pick<UploadFileRequest, 'templateId'>>, Pick<UploadFileRequest, 'templateData' | 'outputFormat' | 'locale' | 'pdfOptions'> {
+    /** Entity type for file organization (default: 'default') */
+    entityType?: string;
+    /** Entity ID for file organization (default: 'default') */
+    entityId?: string;
+    /** File category (default: 'documents') */
+    category?: string;
+}
+/**
+ * Options for generate-only (returns buffer, no upload)
+ * Extended from GenerateDocumentRequest API type for consistency.
+ */
+export interface CoreGenerateOptions extends Required<Pick<GenerateDocumentRequest, 'templateId'>>, Pick<GenerateDocumentRequest, 'templateData' | 'outputFormat' | 'locale' | 'pdfOptions'> {
+    /** Custom renderer name (optional) */
+    rendererName?: string;
+    /** Validation options */
+    validation?: {
+        enabled?: boolean;
+        strict?: boolean;
+    };
+}
+/**
+ * Options for bulk template upload (generate multiple documents and upload)
+ */
+export interface CoreBulkTemplateUploadOptions {
+    /** Array of template upload configs */
+    files: Array<CoreTemplateUploadOptions & {
+        /** Custom filename for this file */
+        filename?: string;
+        /** Custom mimeType override */
+        mimeType?: string;
+    }>;
+    /** Bulk upload options */
+    options?: {
+        /** Max concurrent uploads (default: 2) */
+        concurrency?: number;
+        /** Continue on error (default: true) */
+        continueOnError?: boolean;
+    };
+}
+/**
+ * Return type for useFileUpload hook
+ *
+ * Note: Errors propagate through global error handling (error boundaries,
+ * global error alert store). Results are returned from the Promise.
+ */
+export interface CoreFileUploadResult {
+    /** Upload a file directly */
+    upload: (file: File, options?: CoreFileUploadOptions) => Promise<unknown>;
+    /** Upload multiple files directly */
+    uploadMultiple: (files: File[], options?: CoreFileUploadOptions) => Promise<unknown[]>;
+    /** Generate document from template and upload to storage */
+    uploadFromTemplate: (options: CoreTemplateUploadOptions) => Promise<unknown>;
+    /** Generate multiple documents from templates and upload to storage */
+    uploadMultipleFromTemplate: (options: CoreBulkTemplateUploadOptions) => Promise<unknown[]>;
+    /** Generate document from template (no upload - returns buffer for client download) */
+    generate: (options: CoreGenerateOptions) => Promise<{
+        buffer: string;
+        size: number;
+    }>;
+    /** Whether currently uploading/generating */
+    isUploading: boolean;
+    /** Current upload IDs */
+    currentFileIds: string[];
+    /** Current progress percentage (overall for bulk) */
+    progress: number;
+    /** Cancel current uploads */
+    cancel: () => void;
+}

package/dist/core/hooks/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Core Hooks Types
+ *
+ * Types for composite hooks in @plyaz/core.
+ * Organized by domain (files, etc.).
+ */
+export type { CoreFileOperationType, CoreFileOperationStatus, CoreFileProgressItem, CoreAllFileProgressOptions, CoreAllFileProgressResult, CoreFileDownloadOptions, CoreFileDownloadResult, CoreFileUploadOptions, CoreTemplateUploadOptions, CoreGenerateOptions, CoreBulkTemplateUploadOptions, CoreFileUploadResult, CoreFileResult, CoreFileDeleteResult, } from './files';

package/dist/core/index.cjs

@@ -534,6 +534,55 @@ var SERVICE_KEYS = {
 };
 var ALL_SERVICE_KEYS = Object.values(SERVICE_KEYS);
 
+// src/core/frameworks/route-types.ts
+var DEFAULT_SUCCESS_MESSAGES = {
+  GET: "Retrieved successfully",
+  POST: "Created successfully",
+  PUT: "Updated successfully",
+  PATCH: "Updated successfully",
+  DELETE: "Deleted successfully",
+  OPTIONS: "Options retrieved",
+  HEAD: "Head retrieved"
+};
+
+// src/core/frameworks/file-types.ts
+var MIME_TYPE_EXTENSIONS = {
+  "application/pdf": "pdf",
+  "application/msword": "doc",
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document": "docx",
+  "application/vnd.ms-excel": "xls",
+  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": "xlsx",
+  "application/vnd.ms-powerpoint": "ppt",
+  "application/vnd.openxmlformats-officedocument.presentationml.presentation": "pptx",
+  "application/json": "json",
+  "application/xml": "xml",
+  "application/zip": "zip",
+  "text/plain": "txt",
+  "text/html": "html",
+  "text/css": "css",
+  "text/csv": "csv",
+  "image/png": "png",
+  "image/jpeg": "jpg",
+  "image/gif": "gif",
+  "image/webp": "webp",
+  "image/svg+xml": "svg",
+  "audio/mpeg": "mp3",
+  "audio/wav": "wav",
+  "video/mp4": "mp4",
+  "video/webm": "webm"
+};
+var FILE_SIZE_UNITS = ["Bytes", "KB", "MB", "GB", "TB", "PB"];
+var BYTES_PER_KB = 1024;
+var FILE_SIZE_MULTIPLIERS = {
+  B: 1,
+  KB: BYTES_PER_KB,
+  MB: BYTES_PER_KB * BYTES_PER_KB,
+  GB: BYTES_PER_KB * BYTES_PER_KB * BYTES_PER_KB,
+  TB: BYTES_PER_KB * BYTES_PER_KB * BYTES_PER_KB * BYTES_PER_KB,
+  PB: BYTES_PER_KB * BYTES_PER_KB * BYTES_PER_KB * BYTES_PER_KB * BYTES_PER_KB,
+  BYTES: 1
+};
+
 exports.ALL_SERVICE_KEYS = ALL_SERVICE_KEYS;
 exports.APP_CONTEXTS = APP_CONTEXTS;
 exports.ApiEventAction = ApiEventAction;
@@ -545,6 +594,7 @@ exports.CoreEventScope = CoreEventScope;
 exports.CreateFilesSchema = CreateFilesSchema;
 exports.CreateMediaVariantSchema = CreateMediaVariantSchema;
 exports.DATABASE_FIELDS = DATABASE_FIELDS;
+exports.DEFAULT_SUCCESS_MESSAGES = DEFAULT_SUCCESS_MESSAGES;
 exports.DatabaseEventAction = DatabaseEventAction;
 exports.EVALUATION_REASONS = EVALUATION_REASONS;
 exports.EntityEventAction = EntityEventAction;
@@ -563,11 +613,14 @@ exports.FILES_STREAM_MESSAGE_TYPE = FILES_STREAM_MESSAGE_TYPE;
 exports.FILES_STREAM_PROGRESS_STATUS = FILES_STREAM_PROGRESS_STATUS;
 exports.FILES_STREAM_SUBTYPE = FILES_STREAM_SUBTYPE;
 exports.FILE_ACCESS_LEVELS = FILE_ACCESS_LEVELS;
+exports.FILE_SIZE_MULTIPLIERS = FILE_SIZE_MULTIPLIERS;
+exports.FILE_SIZE_UNITS = FILE_SIZE_UNITS;
 exports.FILE_TYPES = FILE_TYPES;
 exports.FRONTEND_RUNTIMES = FRONTEND_RUNTIMES;
 exports.FeatureFlagEventAction = FeatureFlagEventAction;
 exports.FileTypeSchema = FileTypeSchema;
 exports.FilesDatabaseRowSchema = FilesDatabaseRowSchema;
+exports.MIME_TYPE_EXTENSIONS = MIME_TYPE_EXTENSIONS;
 exports.MediaAccessLevelSchema = MediaAccessLevelSchema;
 exports.MediaTypeSchema = MediaTypeSchema;
 exports.MediaVariantsDatabaseRowSchema = MediaVariantsDatabaseRowSchema;