@plyaz/types 1.30.0 → 1.31.1

package/dist/storage/interfaces.d.ts

@@ -4,10 +4,10 @@
  */
 import type { LoggerInterface } from '../logger/types';
 import type { StorageErrorCode } from '../errors/codes';
-import type { ADAPTER_HEALTH_STATUS, ENTITY_TYPE, FILE_ACCESS_LEVEL, FILE_CATEGORY, OUTPUT_FORMAT, PATH_GENERATION_STRATEGY, RETRY_STRATEGY, STORAGE_ADAPTER_TYPE, STORAGE_DEVICE_TYPE, STORAGE_EVENT_TYPE, STORAGE_QUEUE_PRIORITY, STORAGE_RENDERER_TYPE, TEMPLATE_OUTPUT_FORMAT, UPLOAD_STATUS, DOCUMENT_TYPE, MEDIA_ENTITY, STORAGE_VISIBILITY, STORAGE_ENVIRONMENT, BUSINESS_MODEL, ORGANIZATION_TIER, BUCKET_PURPOSE, PATH_STRATEGY, TEMPLATE_VARIABLE_TYPE, TEMPLATE_DOCUMENT_TYPE } from './enums';
+import type { ADAPTER_HEALTH_STATUS, ENTITY_TYPE, FILE_ACCESS_LEVEL, FILE_CATEGORY, OUTPUT_FORMAT, PATH_GENERATION_STRATEGY, RETRY_STRATEGY, STORAGE_ADAPTER_TYPE, STORAGE_DEVICE_TYPE, STORAGE_EVENT_TYPE, STORAGE_QUEUE_PRIORITY, STORAGE_RENDERER_TYPE, TEMPLATE_OUTPUT_FORMAT, UPLOAD_STATUS, DOCUMENT_TYPE, MEDIA_ENTITY, STORAGE_VISIBILITY, STORAGE_ENVIRONMENT, BUSINESS_MODEL, ORGANIZATION_TIER, BUCKET_PURPOSE, PATH_STRATEGY, TEMPLATE_VARIABLE_TYPE, TEMPLATE_DOCUMENT_TYPE, STORAGE_WEBHOOK_EVENT_TYPE } from './enums';
 import type { StorageSoftDeleteMetadata, StorageDeleteComplianceOptions, StorageComplianceConfig, StorageRetentionPolicy } from './compliance';
 import type { PluginRegistryConfig, StorageKnownPluginName, StoragePlugin } from './plugins';
-import type { StorageBaseWebhookAdapterConfig, StorageWebhookAdapter, StorageWebhookManagerConfig } from './webhooks';
+import type { StorageBaseWebhookAdapterConfig, StorageWebhookAdapter, StorageWebhookManagerConfig, StorageWebhookPayload, StorageWebhookProcessingResult } from './webhooks';
 /**
  * Simplified API client configuration for storage adapters
  * Avoids direct dependency on full ApiConfig to prevent version conflicts
@@ -2575,3 +2575,110 @@ export type StorageTemplateInvoiceTotalArgs = [
     shippingCost?: number | unknown,
     calcType?: string | unknown
 ];
+/**
+ * StorageServiceInstance - Main public API interface
+ *
+ * This interface defines the public contract for StorageService.
+ * The StorageService class in @plyaz/storage implements this interface.
+ *
+ * Used by:
+ * - Core's StorageService wrapper (Proxy-based method forwarding)
+ * - Domain services that need storage operations
+ * - Type-safe dependency injection
+ */
+export interface StorageServiceInstance {
+    /** Upload a file to storage (supports template-based generation) */
+    uploadFile(params: UploadParams): Promise<UploadResult>;
+    /** Upload multiple files with concurrency control */
+    uploadMultipleFiles(files: UploadParams[], options?: {
+        concurrency?: number;
+        useQueue?: boolean;
+        continueOnError?: boolean;
+    }): Promise<UploadResult[]>;
+    /** Download a file from storage */
+    downloadFile(params: DownloadParams): Promise<DownloadResult>;
+    /** Delete a file from storage */
+    deleteFile(params: DeleteParams): Promise<FileDeleteResult>;
+    /** Restore a soft-deleted file */
+    restoreFile(fileId: string): Promise<FileMetadata>;
+    /** Update an existing file */
+    updateFile(params: UpdateFileParams): Promise<UploadResult>;
+    /** Generate a document from template (returns Buffer, no upload) */
+    generateFile(params: GenerateFileParams): Promise<globalThis.Buffer>;
+    /** Generate a document and save to a file path */
+    generateFileToPath(params: GenerateFileToPathParams): Promise<GenerateFileToPathResult>;
+    /** Get a signed URL for temporary access */
+    getSignedUrl(options: PresignedUrlOptions): Promise<PresignedUrlResult>;
+    /** Create a signed URL for direct upload */
+    createSignedUploadUrl(params: StorageSignedUploadUrlParams): Promise<StorageSignedUploadUrlResult>;
+    /** Get public URL for a file */
+    getPublicUrl(params: StoragePublicUrlParams): Promise<string>;
+    /** Move a file within storage */
+    moveFile(params: StorageMoveFileParams): Promise<FileMetadata>;
+    /** Copy a file within storage */
+    copyFile(params: StorageCopyFileParams): Promise<FileMetadata>;
+    /** Replace a file in storage */
+    replaceFile(params: StorageReplaceFileParams): Promise<FileMetadata>;
+    /** List all buckets */
+    listBuckets(adapterName?: string): Promise<StorageListBucketsResult>;
+    /** Get bucket info */
+    getBucket(bucketName: string, adapterName?: string): Promise<StorageBucketInfo>;
+    /** Update bucket configuration */
+    updateBucket(params: StorageUpdateBucketParams, adapterName?: string): Promise<void>;
+    /** Delete multiple buckets */
+    deleteBuckets(bucketNames: string[], adapterName?: string): Promise<{
+        deleted: string[];
+        failed: Array<{
+            bucket: string;
+            error: string;
+            adapter?: string;
+        }>;
+    }>;
+    /** List files in storage */
+    listFiles(params: StorageListFilesParams): Promise<StorageListFilesResult>;
+    /** Get health summary for all adapters */
+    getHealthSummary(): unknown;
+    /** Get event statistics */
+    getEventStatistics(): unknown;
+    /** Check health of all adapters */
+    checkAllAdaptersHealth(): Promise<void>;
+    /** Queue multiple files for bulk upload */
+    queueBulkUpload(files: Array<UploadParams & {
+        priority?: 'high' | 'normal' | 'low';
+    }>): Promise<void>;
+    /** Queue a document generation job */
+    queueDocumentGeneration(options: {
+        templateId: string;
+        data: Record<string, unknown>;
+        outputOptions: Omit<UploadParams, 'file' | 'templateId' | 'templateData'>;
+        priority?: 'high' | 'normal' | 'low';
+    }): Promise<void>;
+    /** Start the queue processor */
+    startQueue(): void;
+    /** Stop the queue processor */
+    stopQueue(): Promise<void>;
+    /** Get queue statistics */
+    getQueueStatistics(): StorageQueueStatistics;
+    /** Get the template engine instance */
+    getTemplateEngine(): unknown;
+    /** Get the compliance manager instance */
+    getComplianceManager(): unknown;
+    /** Check if compliance is enabled */
+    isComplianceEnabled(): boolean;
+    /** Get the webhook manager instance */
+    getWebhookManager(): unknown;
+    /** Check if webhooks are enabled */
+    isWebhooksEnabled(): boolean;
+    /** Register a webhook adapter */
+    registerWebhookAdapter(adapter: StorageWebhookAdapter): void;
+    /** Handle incoming webhook */
+    handleWebhook(providerName: string, eventType: STORAGE_WEBHOOK_EVENT_TYPE | string, payload: StorageWebhookPayload<unknown>): Promise<StorageWebhookProcessingResult>;
+    /** Subscribe to storage events (alias for on) */
+    onEvent(eventType: STORAGE_EVENT_TYPE, handler: (payload: StorageEventPayload) => void | Promise<void>): () => void;
+    /** Subscribe to storage events */
+    on(eventType: STORAGE_EVENT_TYPE, handler: (payload: StorageEventPayload) => void | Promise<void>): () => void;
+    /** Unsubscribe from storage events */
+    off(eventType: STORAGE_EVENT_TYPE, handler: (payload: StorageEventPayload) => void | Promise<void>): void;
+    /** Cleanup and destroy the service */
+    destroy(): Promise<void>;
+}

package/dist/store/files/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Files Store Types
+ *
+ * Store types for files/media domain.
+ */
+export type { FilesStoreItem, GeneratedFileItem, FilesFrontendStoreState, FilesFrontendStoreData, FilesFrontendStoreActions, FilesFrontendStoreSlice, FilesStoreSelectors, } from './types';

package/dist/store/files/types.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Files Store Types
+ *
+ * Store state, actions, and slice types for files/media.
+ * Domain types are in @plyaz/types/core/domain/files.
+ * API types are in @plyaz/types/api/endpoints/files.
+ */
+import type { CoreBaseFrontendStore } from '../../core/frontend';
+import type { FilesEntity, FileType } from '../../core/domain/files';
+/**
+ * Serializable store item for files
+ */
+export interface FilesStoreItem {
+    id: string;
+    key: string;
+    filename: string;
+    mimeType: string;
+    size: number;
+    url?: string;
+    publicUrl?: string;
+    bucket: string;
+    entityType?: string;
+    entityId?: string;
+    category?: string;
+    uploadedAt: string;
+    type: FileType;
+    isImage: boolean;
+    isVideo: boolean;
+    isDocument: boolean;
+    isAudio: boolean;
+}
+/**
+ * Generated document item (not uploaded to storage)
+ */
+export interface GeneratedFileItem {
+    id: string;
+    templateId: string;
+    buffer: string;
+    size: number;
+    mimeType: string;
+    filename: string;
+    generatedAt: string;
+}
+/**
+ * Files store state
+ */
+export interface FilesFrontendStoreState {
+    filesList: FilesEntity[];
+    uploadsList: FilesEntity[];
+    generatedFilesList: GeneratedFileItem[];
+    lastUpload: FilesEntity | null;
+    lastGenerated: GeneratedFileItem | null;
+    filesCount: number;
+    uploadsCount: number;
+    isLoading: boolean;
+    isUploading: boolean;
+    isGenerating: boolean;
+}
+/**
+ * Files store data for setData()
+ */
+export interface FilesFrontendStoreData {
+    filesList: FilesEntity[];
+    uploadsList?: FilesEntity[];
+    generatedFilesList?: GeneratedFileItem[];
+    lastUpload?: FilesEntity | null;
+    lastGenerated?: GeneratedFileItem | null;
+}
+/**
+ * Files store actions
+ *
+ * Note: No update action since there's no update endpoint in the API.
+ * Files are immutable once uploaded - only metadata changes via storage service.
+ */
+export interface FilesFrontendStoreActions extends CoreBaseFrontendStore<FilesFrontendStoreData> {
+    addFile: (file: FilesEntity) => void;
+    removeFile: (id: string) => void;
+    clearFiles: () => void;
+    addUpload: (upload: FilesEntity) => void;
+    removeUpload: (id: string) => void;
+    clearUploads: () => void;
+    addGenerated: (file: GeneratedFileItem) => void;
+    removeGenerated: (id: string) => void;
+    clearGenerated: () => void;
+    setLoading: (isLoading: boolean) => void;
+    setUploading: (isUploading: boolean) => void;
+    setGenerating: (isGenerating: boolean) => void;
+    reset: () => void;
+}
+/**
+ * Complete files store slice
+ */
+export interface FilesFrontendStoreSlice extends FilesFrontendStoreState, FilesFrontendStoreActions {
+}
+export interface FilesStoreSelectors {
+    selectFiles: (state: FilesFrontendStoreState) => FilesEntity[];
+    selectUploads: (state: FilesFrontendStoreState) => FilesEntity[];
+    selectGenerated: (state: FilesFrontendStoreState) => GeneratedFileItem[];
+    selectLastUpload: (state: FilesFrontendStoreState) => FilesEntity | null;
+    selectLastGenerated: (state: FilesFrontendStoreState) => GeneratedFileItem | null;
+    selectIsLoading: (state: FilesFrontendStoreState) => boolean;
+    selectIsUploading: (state: FilesFrontendStoreState) => boolean;
+    selectFilesCount: (state: FilesFrontendStoreState) => number;
+    selectUploadsCount: (state: FilesFrontendStoreState) => number;
+    selectFileById: (state: FilesFrontendStoreState, id: string) => FilesEntity | undefined;
+    selectFilesByType: (state: FilesFrontendStoreState, type: FileType) => FilesEntity[];
+}

package/dist/store/index.d.ts

@@ -1,3 +1,4 @@
 export type * from './types';
 export { STORE_KEYS, ALL_STORE_KEYS } from './keys';
 export type { StoreKey } from './keys';
+export type * from './files';

package/dist/store/types.d.ts

@@ -9,6 +9,7 @@
 import type { SerializedError, ErrorStoreActions, ErrorStoreSlice } from '../errors/store';
 import type { FeatureFlagStoreState, FeatureFlagStoreSlice } from '../features/feature-flag/store.types';
 import type { ExampleFrontendStoreSlice } from '../examples';
+import type { FilesFrontendStoreSlice } from './files/types';
 /**
  * Configuration for creating an error store.
  */
@@ -85,6 +86,8 @@ export interface RootStoreSlice {
     featureFlags: FeatureFlagStoreSlice;
     /** Example domain slice */
     example: ExampleFrontendStoreSlice;
+    /** Files/media domain slice */
+    files: FilesFrontendStoreSlice;
 }
 /**
  * Type-safe store registry interface.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plyaz/types",
-  "version": "1.30.0",
+  "version": "1.31.1",
   "author": "Redeemer Pace",
   "license": "ISC",
   "description": "Provides shared TypeScript types and schema utilities for validation and parsing in the @playz ecosystem.",