@plyaz/types 1.39.6 → 1.39.7

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

@@ -0,0 +1,94 @@
+/**
+ * Express Framework Types
+ *
+ * Types for Express route factory in @plyaz/core/frameworks/express.
+ */
+import type { RouteContext, HandlersTypeMap, MethodHandlerTypes } from './route-types';
+import type { CoreInjectedServices } from '../domain/types';
+/**
+ * Minimal Express Request interface for compatibility
+ * Avoids direct dependency on @types/express
+ */
+export interface CoreExpressRequest {
+    params: Record<string, string>;
+    query: Record<string, string | string[] | undefined>;
+    body: unknown;
+    headers: Record<string, string | string[] | undefined>;
+    method: string;
+    path: string;
+    url: string;
+    originalUrl: string;
+    get(name: string): string | undefined;
+}
+/**
+ * Minimal Express Response interface for compatibility
+ */
+export interface CoreExpressResponse {
+    status(code: number): this;
+    json(data: unknown): this;
+    send(data?: unknown): this;
+    set(name: string, value: string): this;
+    setHeader(name: string, value: string): this;
+    end(): void;
+}
+/**
+ * Minimal Express NextFunction interface
+ */
+export type CoreExpressNextFunction = (err?: unknown) => void;
+/**
+ * Express-specific route context
+ */
+export interface CoreExpressRouteContext<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 */
+    body: TBody;
+    /** Express request object */
+    req: CoreExpressRequest;
+    /** Express response object */
+    res: CoreExpressResponse;
+    /** Injected Core services (when injectServices is true) */
+    services?: CoreInjectedServices;
+}
+/**
+ * Express route handler function type
+ */
+export type CoreExpressRouteHandler<TService, TResult = unknown, TTypes extends MethodHandlerTypes = MethodHandlerTypes> = (service: TService, ctx: CoreExpressRouteContext<TTypes['params'] extends Record<string, string> ? TTypes['params'] : Record<string, string>, TTypes['query'] extends Record<string, string> ? TTypes['query'] : Record<string, string>, TTypes['body']>) => Promise<TResult>;
+/**
+ * Configuration for Express route factory
+ */
+export interface CoreExpressRouteConfig<TService, THandlerTypes extends HandlersTypeMap = HandlersTypeMap> {
+    /** Service name (registered in ServiceRegistry) or factory function */
+    service: string | (() => Promise<TService>);
+    /** Handlers for each HTTP method */
+    handlers: {
+        [K in keyof THandlerTypes & keyof HandlersTypeMap]?: CoreExpressRouteHandler<TService, THandlerTypes[K] extends {
+            response: infer R;
+        } ? R : unknown, THandlerTypes[K] extends MethodHandlerTypes ? THandlerTypes[K] : MethodHandlerTypes>;
+    };
+    /** Function to get Core instance (for service resolution) */
+    getCore?: () => Promise<unknown>;
+    /** Custom success message or function */
+    successMessage?: string | ((method: string) => string);
+    /** Error source identifier for error handling */
+    errorSource?: string;
+    /** Whether to inject Core services into context (default: false) */
+    injectServices?: boolean;
+}
+/**
+ * Express middleware function type
+ */
+export type CoreExpressMiddleware = (req: CoreExpressRequest, res: CoreExpressResponse, next: CoreExpressNextFunction) => void | Promise<void>;
+/**
+ * Return type from createExpressRoute
+ */
+export interface CoreExpressRouteExports {
+    /** Express router middleware for all configured methods */
+    handler: CoreExpressMiddleware;
+    /** Individual method handlers (for manual mounting) */
+    GET?: CoreExpressMiddleware;
+    POST?: CoreExpressMiddleware;
+    PUT?: CoreExpressMiddleware;
+    PATCH?: CoreExpressMiddleware;
+    DELETE?: CoreExpressMiddleware;
+    OPTIONS?: CoreExpressMiddleware;
+    HEAD?: CoreExpressMiddleware;
+}

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

@@ -0,0 +1,34 @@
+/**
+ * File Operation Types
+ *
+ * Types for file operation utilities (browser and Node.js).
+ * Used by @plyaz/core and @plyaz/storage packages.
+ */
+/**
+ * Parsed file key components
+ */
+export interface ParsedFileKey {
+    /** The entity type (e.g., 'user', 'organization') */
+    entityType?: string;
+    /** The entity ID */
+    entityId?: string;
+    /** The file category (e.g., 'documents', 'images') */
+    category?: string;
+    /** The filename with extension */
+    filename?: string;
+    /** The full original key */
+    raw: string;
+}
+/**
+ * Common MIME types and their extensions
+ */
+export declare const MIME_TYPE_EXTENSIONS: Record<string, string>;
+/**
+ * File size units
+ */
+export declare const FILE_SIZE_UNITS: readonly ["Bytes", "KB", "MB", "GB", "TB", "PB"];
+export type FileSizeUnit = (typeof FILE_SIZE_UNITS)[number];
+/**
+ * Multipliers for file size units
+ */
+export declare const FILE_SIZE_MULTIPLIERS: Record<string, number>;

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

@@ -0,0 +1,12 @@
+/**
+ * Framework Types
+ *
+ * Types for @plyaz/core framework adapters (Next.js, Express, NestJS).
+ * Used by route factories and file operation utilities.
+ */
+export type { RouteContext, RouteHandler, RouteHandlerConfig, MethodHandlerTypes, HandlersTypeMap, HttpMethod, } from './route-types';
+export { DEFAULT_SUCCESS_MESSAGES } from './route-types';
+export type { CoreNextRequestCompat, CoreNextRouteContext, CoreGenericRouteHandler, CoreNextJSRouteContext, CoreGetMethodTypes, CoreNextJSRouteHandler, CoreNextJSRouteConfig, CoreNextJSRouteExports, CorePlyazNextConfigOptions, CorePlyazNextConfig, } from './nextjs-types';
+export type { CoreExpressRequest, CoreExpressResponse, CoreExpressNextFunction, CoreExpressRouteContext, CoreExpressRouteHandler, CoreExpressRouteConfig, CoreExpressMiddleware, CoreExpressRouteExports, } from './express-types';
+export type { ParsedFileKey, FileSizeUnit } from './file-types';
+export { MIME_TYPE_EXTENSIONS, FILE_SIZE_UNITS, FILE_SIZE_MULTIPLIERS } from './file-types';

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';