@plyaz/types 1.31.0 → 1.31.1

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

@@ -0,0 +1,6 @@
+/**
+ * Files Domain Types
+ *
+ * Core domain types for files/media service.
+ */
+export { FileTypeSchema, type FileType, type FilesEntity, type FilesFrontendServiceConfig, type FilesDomainServiceConfig, type FilesDatabaseRow, type FilesCreateInput, type MediaVariantsDatabaseRow, type MediaVariantsCreateInput, type SingleUploadEventPayload, type BulkUploadEventPayload, } from './types';

package/dist/core/domain/files/types.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Files Domain Types
+ *
+ * Domain entity, service config, and database row types for files/media.
+ * Store types are in @plyaz/types/store/files.
+ * API types are in @plyaz/types/api/endpoints/files.
+ */
+import type { FileVariant } from '../../../api/endpoints/files/schemas';
+import type { CoreServiceInitConfig } from '../../init';
+import type { CoreInjectedServices } from '../types';
+import type { CoreBaseFrontendServiceConfig } from '../../frontend';
+import type { FilesFrontendStoreData, FilesFrontendStoreSlice } from '../../../store/files';
+import { z } from 'zod';
+/**
+ * File type enum - for categorization in domain
+ */
+export declare const FileTypeSchema: z.ZodEnum<{
+    IMAGE: "IMAGE";
+    VIDEO: "VIDEO";
+    DOCUMENT: "DOCUMENT";
+    AUDIO: "AUDIO";
+    OTHER: "OTHER";
+}>;
+export type FileType = z.infer<typeof FileTypeSchema>;
+/**
+ * Files domain entity - maps from API response + additional domain properties
+ */
+export interface FilesEntity {
+    id: string;
+    key: string;
+    filename: string;
+    mimeType: string;
+    size: number;
+    checksum?: string;
+    url?: string;
+    publicUrl?: string;
+    signedUrl?: string;
+    bucket: string;
+    entityType?: string;
+    entityId?: string;
+    category?: string;
+    uploadedAt: Date;
+    expiresAt?: Date;
+    variants?: Record<string, FileVariant>;
+    type: FileType;
+    isImage: boolean;
+    isVideo: boolean;
+    isDocument: boolean;
+    isAudio: boolean;
+}
+/**
+ * Frontend files service configuration
+ *
+ * Extends both CoreBaseFrontendServiceConfig (for fetchers, storeHandlers)
+ * and CoreServiceInitConfig (for base service options).
+ * Same pattern as ExampleFrontendServiceConfig.
+ */
+export interface FilesFrontendServiceConfig extends CoreBaseFrontendServiceConfig<FilesFrontendStoreData, FilesFrontendStoreSlice>, CoreServiceInitConfig {
+    /** API base path for file endpoints */
+    apiBasePath?: string;
+    /** Auto-fetch files on initialization */
+    autoFetch?: boolean;
+    /** Maximum uploads to track in store */
+    maxUploads?: number;
+    /** Maximum generated files to track in store */
+    maxGenerated?: number;
+    /** Injected services (for testing/manual store injection) */
+    injected?: CoreInjectedServices;
+}
+/**
+ * Backend files service configuration
+ */
+export interface FilesDomainServiceConfig extends CoreServiceInitConfig {
+    enabled?: boolean;
+    throwOnValidationError?: boolean;
+    throwOnRepositoryError?: boolean;
+    emitEvents?: boolean;
+}
+/**
+ * Database row from media table
+ * Used by FilesRepository, mapped to FilesEntity by FilesMapper
+ */
+export interface FilesDatabaseRow {
+    id: string;
+    user_id: string;
+    type: string;
+    filename: string;
+    original_filename: string;
+    mime_type: string;
+    file_size: bigint | number;
+    storage_path: string;
+    cdn_url: string | null;
+    width: number | null;
+    height: number | null;
+    duration: number | null;
+    is_virus_scanned: boolean;
+    virus_scan_result: string | null;
+    metadata: Record<string, unknown> | null;
+    variants: Record<string, unknown> | null;
+    entity_type: string | null;
+    entity_id: string | null;
+    access_level: string | null;
+    created_at: string;
+    updated_at: string;
+    deleted_at: string | null;
+}
+/**
+ * Create input for Files entity (excludes auto-generated fields)
+ * Used internally by repository when creating records from upload responses
+ */
+export type FilesCreateInput = Omit<FilesDatabaseRow, 'id' | 'created_at' | 'updated_at' | 'deleted_at'>;
+/**
+ * Database row from media_variants table
+ * Used by MediaVariantsRepository for normalized variant storage
+ *
+ * Variant names: 'thumbnail', 'mobile', 'desktop', '4k'
+ */
+export interface MediaVariantsDatabaseRow {
+    id: string;
+    media_id: string;
+    variant_name: string;
+    file_path: string;
+    cdn_url: string | null;
+    width: number | null;
+    height: number | null;
+    file_size: number | null;
+    created_at: string;
+}
+/**
+ * Create input for media variant (excludes auto-generated fields)
+ */
+export type MediaVariantsCreateInput = Omit<MediaVariantsDatabaseRow, 'id' | 'created_at'>;
+/**
+ * Event payload for single file upload
+ * Used by files:upload:uploaded event
+ */
+export interface SingleUploadEventPayload {
+    result?: {
+        metadata: {
+            fileId: string;
+            filename: string;
+            mimeType: string;
+            size: number;
+            path: string;
+            entityType?: string;
+            entityId?: string;
+            accessLevel?: string;
+            url?: string;
+            extractedMetadata?: {
+                width?: number;
+                height?: number;
+                duration?: number;
+            };
+            customMetadata?: Record<string, unknown>;
+        };
+        variants?: Record<string, unknown>;
+    };
+}
+/**
+ * Event payload for bulk file upload
+ * Used by files:upload:bulk:uploaded event
+ */
+export interface BulkUploadEventPayload {
+    result?: {
+        results?: SingleUploadEventPayload['result'][];
+    };
+}

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

@@ -2,5 +2,6 @@
  * Core Domain Types
  * Type definitions for @plyaz/core domain services
  */
-export type { CoreBaseDomainServiceInterface, CoreEventSubscribable, CoreProviderSubscribable, CoreValidationResult, CoreValidatorConfig, CoreBaseValidatorInstance, CoreBaseMapperInstance, CoreBaseDomainServiceConfig, CoreBaseBackendServiceConfig, CoreMapperClass, CoreValidatorClass, CoreBaseServiceConfig, CoreInjectedServices, } from './types';
+export type { EmptyDTO, CoreDeleteOptions, CoreBaseDomainServiceInterface, CoreEventSubscribable, CoreProviderSubscribable, CoreValidationResult, CoreValidatorConfig, CoreBaseValidatorInstance, CoreBaseMapperInstance, CoreBaseDomainServiceConfig, CoreBaseBackendServiceConfig, CoreMapperClass, CoreValidatorClass, CoreBaseServiceConfig, CoreInjectedServices, } from './types';
 export type { CrudCacheOptions, CrudTransactionOptions, CrudOperationOptions, } from './crud';
+export * from './files';

package/dist/core/domain/types.d.ts

@@ -8,6 +8,20 @@ import type { ValidationIssue, InternalValidationSchema } from '../../errors';
 import type { FeatureFlagValue } from '../../features';
 import type { CoreServiceRuntime } from '../modules';
 import type { ApiClientOptions } from '../../api';
+/**
+ * Empty DTO type for operations that don't require validation.
+ * Use when a service/validator doesn't need a specific DTO for an operation.
+ */
+export interface EmptyDTO {
+}
+/**
+ * Standard delete options for domain services.
+ * Supports soft delete (mark as deleted) or hard delete (permanent removal).
+ */
+export interface CoreDeleteOptions {
+    /** If true, performs soft delete (sets deleted_at). If false, permanently removes. */
+    soft?: boolean;
+}
 /**
  * Base interface for all domain services.
  *

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

@@ -19,4 +19,4 @@
  */
 export { CoreEventScope, SystemEventAction, EntityEventAction, ValidationEventAction, SanitizationEventAction, ApiEventAction, CacheEventAction, AuthEventAction, DatabaseEventAction, FeatureFlagEventAction, StoreEventAction, StorageEventAction, NotificationEventAction, CORE_EVENTS, } from './enums';
 export type { CoreEventScopeType, SystemEventType, EntityEventType, ValidationEventType, SanitizationEventType, ApiEventType, CacheEventType, AuthEventType, DatabaseEventType, FeatureFlagEventType, StoreEventType, CoreEventType, } from './enums';
-export type { CoreEvent, CoreCrudOperation, CoreValidationStartedPayload, CoreValidationSuccessPayload, CoreValidationFailedPayload, CoreSanitizationStartedPayload, CoreSanitizationSuccessPayload, CoreSanitizationFailedPayload, CoreEntityCreatedPayload, CoreEntityUpdatedPayload, CoreEntityPatchedPayload, CoreEntityDeletedPayload, CoreEntityCreatingPayload, CoreEntityUpdatingPayload, CoreEntityPatchingPayload, CoreEntityDeletingPayload, CoreEntityErrorPayload, CoreEntityCompletePayload, CoreBulkCreatedPayload, CoreBulkDeletedPayload, CoreSystemInitializedPayload, CoreSystemReadyPayload, CoreSystemShutdownPayload, CoreSystemErrorPayload, CoreSystemWarningPayload, CoreApiRequestStartPayload, CoreApiRequestSuccessPayload, CoreApiRequestErrorPayload, CoreApiRetryPayload, CoreApiTimeoutPayload, CoreCacheHitPayload, CoreCacheMissPayload, CoreCacheSetPayload, CoreCacheDeletePayload, CoreCacheClearPayload, CoreCacheExpiredPayload, CoreCacheErrorPayload, CoreDatabaseConnectedPayload, CoreDatabaseDisconnectedPayload, CoreDatabaseQueryPayload, CoreDatabaseErrorPayload, CoreDatabaseTransactionStartPayload, CoreDatabaseTransactionCommitPayload, CoreDatabaseTransactionRollbackPayload, CoreAuthLoginPayload, CoreAuthLogoutPayload, CoreAuthTokenRefreshPayload, CoreAuthSessionExpiredPayload, CoreAuthUnauthorizedPayload, CoreFeatureFlagChangedPayload, CoreFeatureFlagEvaluatedPayload, CoreFeatureFlagRefreshedPayload, CoreStoreUpdatedPayload, CoreStoreResetPayload, CoreStoreHydratedPayload, CoreStorageUploadedPayload, CoreStorageDownloadedPayload, CoreStorageDeletedPayload, CoreStorageErrorPayload, CoreStorageHealthCheckPayload, CoreNotificationSentPayload, CoreNotificationFailedPayload, CoreNotificationDeliveredPayload, CoreNotificationOpenedPayload, CoreNotificationClickedPayload, CoreNotificationErrorPayload, CoreNotificationHealthCheckPayload, CoreEventPayloadMap, } from './payloads';
+export type { CoreEvent, CoreCrudOperation, CoreValidationStartedPayload, CoreValidationSuccessPayload, CoreValidationFailedPayload, CoreSanitizationStartedPayload, CoreSanitizationSuccessPayload, CoreSanitizationFailedPayload, CoreEntityCreatedPayload, CoreEntityUpdatedPayload, CoreEntityPatchedPayload, CoreEntityDeletedPayload, CoreEntityCreatingPayload, CoreEntityUpdatingPayload, CoreEntityPatchingPayload, CoreEntityDeletingPayload, CoreEntityErrorPayload, CoreEntityCompletePayload, CoreBulkCreatedPayload, CoreBulkDeletedPayload, CoreSystemInitializedPayload, CoreSystemReadyPayload, CoreSystemShutdownPayload, CoreSystemErrorPayload, CoreSystemWarningPayload, CoreApiRequestStartPayload, CoreApiRequestSuccessPayload, CoreApiRequestErrorPayload, CoreApiRetryPayload, CoreApiTimeoutPayload, CoreCacheHitPayload, CoreCacheMissPayload, CoreCacheSetPayload, CoreCacheDeletePayload, CoreCacheClearPayload, CoreCacheExpiredPayload, CoreCacheErrorPayload, CoreDatabaseConnectedPayload, CoreDatabaseDisconnectedPayload, CoreDatabaseQueryPayload, CoreDatabaseErrorPayload, CoreDatabaseTransactionStartPayload, CoreDatabaseTransactionCommitPayload, CoreDatabaseTransactionRollbackPayload, CoreAuthLoginPayload, CoreAuthLogoutPayload, CoreAuthTokenRefreshPayload, CoreAuthSessionExpiredPayload, CoreAuthUnauthorizedPayload, CoreFeatureFlagChangedPayload, CoreFeatureFlagEvaluatedPayload, CoreFeatureFlagRefreshedPayload, CoreStoreUpdatedPayload, CoreStoreResetPayload, CoreStoreHydratedPayload, CoreOperationRequestPayload, CoreOperationResultPayload, CoreOperationErrorPayload, CoreStorageUploadedPayload, CoreStorageDownloadedPayload, CoreStorageDeletedPayload, CoreStorageErrorPayload, CoreStorageHealthCheckPayload, CoreNotificationSentPayload, CoreNotificationFailedPayload, CoreNotificationDeliveredPayload, CoreNotificationOpenedPayload, CoreNotificationClickedPayload, CoreNotificationErrorPayload, CoreNotificationHealthCheckPayload, CoreEventPayloadMap, EventPersistenceConfig, DomainPersistenceConfig, } from './payloads';

package/dist/core/events/payloads.d.ts

@@ -505,6 +505,27 @@ export interface CoreStorageHealthCheckPayload {
         healthy: boolean;
     }[];
 }
+/**
+ * Generic payload for operation request events (e.g., upload:uploading, email:sending)
+ * Used by domain services for storage/notification operations.
+ */
+export interface CoreOperationRequestPayload<TRequest = unknown> {
+    request: TRequest;
+}
+/**
+ * Generic payload for operation result events (e.g., upload:uploaded, email:sent)
+ * Used by domain services for storage/notification operations.
+ */
+export interface CoreOperationResultPayload<TResult = unknown> {
+    result: TResult;
+}
+/**
+ * Generic payload for operation error events (e.g., upload:error, email:error)
+ * Used by domain services for storage/notification operations.
+ */
+export interface CoreOperationErrorPayload {
+    error: unknown;
+}
 /**
  * Payload for notification:sent events
  */
@@ -658,3 +679,62 @@ export interface CoreEventPayloadMap {
     [CORE_EVENTS.NOTIFICATION.ERROR]: CoreNotificationErrorPayload;
     [CORE_EVENTS.NOTIFICATION.HEALTH_CHECK]: CoreNotificationHealthCheckPayload;
 }
+/**
+ * Event configuration for persistence
+ * Defines how to extract and validate items from event payloads
+ *
+ * @typeParam TPayload - Event payload type
+ * @typeParam TItem - Item type extracted from payload
+ */
+export interface EventPersistenceConfig<TPayload = unknown, TItem = unknown> {
+    /** Extract item(s) from event payload */
+    extractPayload: (payload: TPayload) => TItem | TItem[] | undefined;
+    /** Whether this event contains multiple items */
+    isBulk: boolean;
+    /** Optional: validate item before persisting */
+    validate?: (item: TItem) => boolean;
+}
+/**
+ * Domain persistence handler configuration
+ * Used by BackendEventPersistenceHandler to register event-to-DB persistence
+ *
+ * @typeParam TRepository - Repository type for database operations
+ * @typeParam TMapper - Mapper type for transforming items to DB rows
+ * @typeParam TItem - Item type extracted from event payload
+ * @typeParam TDbRow - Database row type
+ *
+ * @example
+ * ```typescript
+ * BackendEventPersistenceHandler.register<
+ *   FilesRepository,
+ *   FilesMapper,
+ *   UploadResultItem,
+ *   Partial<FilesDatabaseRow>
+ * >({
+ *   domain: 'files',
+ *   events: { ... },
+ *   loadDependencies: async () => ({ repository, mapper }),
+ *   mapToDbRow: (mapper, item) => mapper.eventPayloadToDbRow(item),
+ *   createRecord: async (repo, row) => repo.create(row),
+ * });
+ * ```
+ */
+export interface DomainPersistenceConfig<TRepository = unknown, TMapper = unknown, TItem = unknown, TDbRow = unknown> {
+    /** Domain name (e.g., 'files', 'notifications') */
+    domain: string;
+    /** Event configurations keyed by event name */
+    events: Record<string, EventPersistenceConfig<unknown, TItem>>;
+    /** Load repository and mapper (async to avoid circular deps) */
+    loadDependencies: () => Promise<{
+        repository: TRepository;
+        mapper: TMapper;
+    }>;
+    /** Map item to database row using mapper */
+    mapToDbRow: (mapper: TMapper, item: TItem) => TDbRow;
+    /** Create record in repository */
+    createRecord: (repository: TRepository, dbRow: TDbRow) => Promise<unknown>;
+    /** Optional: get unique key for deduplication logging */
+    getUniqueKey?: (item: TItem) => string;
+    /** Enable verbose logging */
+    verbose?: boolean;
+}

package/dist/core/services/types.d.ts

@@ -5,8 +5,8 @@
 import type { DrizzleConfig, SupabaseConfig, SqlConfig, SoftDeleteConfig, DBCacheConfig, AuditConfig, DBEncryptionConfig } from '../../db';
 import type { ReactNode } from 'react';
 import type { ApiClientOptions } from '../../api/client';
-import type { StorageServiceConfig } from '../../storage';
-import type { NotificationServiceConfig } from '../../notifications';
+import type { StorageServiceConfig, StorageServiceInstance } from '../../storage';
+import type { NotificationServiceConfig, NotificationServiceInstance } from '../../notifications';
 import type { CacheStrategyType } from '../../features';
 import type { BackendErrorStore, BackendErrorStoreConfig, HttpErrorHandlerConfig } from '../../errors/middleware';
 export interface CoreCacheConfig {
@@ -575,16 +575,26 @@ export interface CoreCacheManagerInstance {
 /**
  * Core's StorageService instance interface
  * Returned by Core.storage and StorageService.getInstance()
+ *
+ * This is a wrapper around the actual StorageServiceInstance.
+ * Use getStorage() to access the underlying storage service with all methods.
  */
 export interface CoreStorageServiceInstance {
+    /** Get the underlying storage service (Proxy-based method forwarding) */
+    getStorage(): StorageServiceInstance;
     /** Close/cleanup the storage service */
     close(): Promise<void>;
 }
 /**
  * Core's NotificationService instance interface
  * Returned by Core.notifications - wraps the actual @plyaz/notifications service
+ *
+ * This is a wrapper around the actual NotificationServiceInstance.
+ * Use getNotifications() to access the underlying notification service with all methods.
  */
 export interface CoreNotificationServiceInstance {
+    /** Get the underlying notification service (Proxy-based method forwarding) */
+    getNotifications(): NotificationServiceInstance;
     /** Close/cleanup the notification service */
     close(): Promise<void>;
 }

package/dist/db/databaseAdapter.d.ts

@@ -137,14 +137,14 @@ export interface DatabaseAdapterType {
      * @param options - Query options including filters, sorting, and pagination
      * @returns Promise resolving to DatabaseResult containing paginated data
      */
-    findMany<T extends Record<string, unknown>>(table: string, options?: QueryOptions<T>): Promise<DatabaseResult<PaginatedResult<T>>>;
+    findMany<T extends object>(table: string, options?: QueryOptions<T>): Promise<DatabaseResult<PaginatedResult<T>>>;
     /**
      * Create a new record
      * @param table - Table name
      * @param data - Record data to create
      * @returns Promise resolving to DatabaseResult containing the created record
      */
-    create<T extends Record<string, unknown>>(table: string, data: T): Promise<DatabaseResult<T>>;
+    create<T extends object>(table: string, data: T): Promise<DatabaseResult<T>>;
     /**
      * Update an existing record
      * @param table - Table name
@@ -179,7 +179,7 @@ export interface DatabaseAdapterType {
      * @param filter - Filter conditions
      * @returns Promise resolving to DatabaseResult containing the count
      */
-    count<T extends Record<string, unknown> = Record<string, unknown>>(table: string, filter?: Filter<T>): Promise<DatabaseResult<number>>;
+    count<T extends object = object>(table: string, filter?: Filter<T>): Promise<DatabaseResult<number>>;
     /**
      * Perform health check on the database connection
      * @returns Promise resolving to DatabaseResult containing health status

package/dist/db/databaseService.d.ts

@@ -91,7 +91,7 @@ export interface DatabaseServiceInterface {
      * @param config - Optional per-operation configuration overrides
      * @returns Promise resolving to the record or null
      */
-    get<T extends Record<string, unknown>>(table: TableName, id: string, config?: OperationConfig): Promise<DatabaseResult<T | null>>;
+    get<T extends object>(table: TableName, id: string, config?: OperationConfig): Promise<DatabaseResult<T | null>>;
     /**
      * List records with optional filtering, sorting, and pagination
      * @param table - Table name
@@ -99,7 +99,7 @@ export interface DatabaseServiceInterface {
      * @param config - Optional per-operation configuration overrides
      * @returns Promise resolving to paginated results
      */
-    list<T extends Record<string, unknown>>(table: TableName, options?: QueryOptions<T>, config?: OperationConfig): Promise<DatabaseResult<PaginatedResult<T>>>;
+    list<T extends object>(table: TableName, options?: QueryOptions<T>, config?: OperationConfig): Promise<DatabaseResult<PaginatedResult<T>>>;
     /**
      * Create a new record
      * @param table - Table name
@@ -107,7 +107,7 @@ export interface DatabaseServiceInterface {
      * @param config - Optional per-operation configuration overrides
      * @returns Promise resolving to the created record
      */
-    create<T extends Record<string, unknown>>(table: TableName, input: CreateInput<T>, config?: OperationConfig): Promise<DatabaseResult<T>>;
+    create<T extends object>(table: TableName, input: CreateInput<T>, config?: OperationConfig): Promise<DatabaseResult<T>>;
     /**
      * Update an existing record
      * @param table - Table name
@@ -116,7 +116,7 @@ export interface DatabaseServiceInterface {
      * @param config - Optional per-operation configuration overrides
      * @returns Promise resolving to the updated record
      */
-    update<T extends Record<string, unknown>>(table: TableName, id: string, input: UpdateInput<T>, config?: OperationConfig): Promise<DatabaseResult<T>>;
+    update<T extends object>(table: TableName, id: string, input: UpdateInput<T>, config?: OperationConfig): Promise<DatabaseResult<T>>;
     /**
      * Delete a record
      * @param table - Table name
@@ -132,7 +132,7 @@ export interface DatabaseServiceInterface {
      * @param config - Optional per-operation configuration overrides
      * @returns Promise resolving to array of created records
      */
-    batchCreate<T extends Record<string, unknown>>(table: TableName, inputs: CreateInput<T>[], config?: OperationConfig): Promise<DatabaseResult<T[]>>;
+    batchCreate<T extends object>(table: TableName, inputs: CreateInput<T>[], config?: OperationConfig): Promise<DatabaseResult<T[]>>;
     /**
      * Update multiple records in a batch
      * @param table - Table name
@@ -140,7 +140,7 @@ export interface DatabaseServiceInterface {
      * @param config - Optional per-operation configuration overrides
      * @returns Promise resolving to array of updated records
      */
-    batchUpdate<T extends Record<string, unknown>>(table: TableName, updates: BatchUpdate<T>[], config?: OperationConfig): Promise<DatabaseResult<T[]>>;
+    batchUpdate<T extends object>(table: TableName, updates: BatchUpdate<T>[], config?: OperationConfig): Promise<DatabaseResult<T[]>>;
     /**
      * Delete multiple records in a batch
      * @param table - Table name
@@ -156,7 +156,7 @@ export interface DatabaseServiceInterface {
      * @param config - Optional per-operation configuration overrides
      * @returns Promise resolving to paginated results
      */
-    query<T extends Record<string, unknown>>(table: TableName, query: QueryOptions<T>, config?: OperationConfig): Promise<DatabaseResult<PaginatedResult<T>>>;
+    query<T extends object>(table: TableName, query: QueryOptions<T>, config?: OperationConfig): Promise<DatabaseResult<PaginatedResult<T>>>;
     /**
      * Count records matching a filter
      * @param table - Table name
@@ -164,7 +164,7 @@ export interface DatabaseServiceInterface {
      * @param config - Optional per-operation configuration overrides
      * @returns Promise resolving to the count
      */
-    count<T extends Record<string, unknown> = Record<string, unknown>>(table: TableName, filter?: Filter<T>, config?: OperationConfig): Promise<DatabaseResult<number>>;
+    count<T extends object = object>(table: TableName, filter?: Filter<T>, config?: OperationConfig): Promise<DatabaseResult<number>>;
     /**
      * Find a single record by filter conditions
      * @param table - Table name
@@ -172,7 +172,7 @@ export interface DatabaseServiceInterface {
      * @param config - Optional per-operation configuration overrides
      * @returns Promise resolving to the first matching record or null
      */
-    findOne<T extends Record<string, unknown>>(table: TableName, filter: Filter<T>, config?: OperationConfig): Promise<DatabaseResult<T | null>>;
+    findOne<T extends object>(table: TableName, filter: Filter<T>, config?: OperationConfig): Promise<DatabaseResult<T | null>>;
     /**
      * Soft delete a record (logical deletion)
      * @param table - Table name

package/dist/examples/index.d.ts

@@ -14,4 +14,4 @@
  * ```
  */
 export { CreateExampleSchema, UpdateExampleSchema, PatchExampleSchema, QueryExampleSchema, DeleteExampleSchema, ExampleResponseSchema, ExampleListResponseSchema, } from './schemas';
-export type { CreateExampleDTO, UpdateExampleDTO, PatchExampleDTO, QueryExampleDTO, DeleteExampleDTO, ExampleResponseDTO, ExampleListResponseDTO, ExampleEntity, ExampleStoreItem, ExampleStoreState, ExampleCreatedPayload, ExampleUpdatedPayload, ExampleDeletedPayload, ExampleValidationFailedPayload, ExampleFrontendStoreData, ExampleFrontendStoreState, ExampleFrontendStoreActions, ExampleFrontendStoreSlice, ExampleFrontendServiceConfig, ExampleFrontendEventType, ExampleUser, ExampleDomainServiceConfig, } from './types';
+export type { CreateExampleDTO, UpdateExampleDTO, PatchExampleDTO, QueryExampleDTO, DeleteExampleDTO, ExampleResponseDTO, ExampleListResponseDTO, ExampleEntity, ExampleStoreItem, ExampleStoreState, ExampleCreatedPayload, ExampleUpdatedPayload, ExampleDeletedPayload, ExampleValidationFailedPayload, ExampleFrontendStoreData, ExampleFrontendStoreState, ExampleFrontendStoreActions, ExampleFrontendStoreSlice, ExampleFrontendServiceConfig, ExampleFrontendEventType, ExampleUser, ExampleDomainServiceConfig, ExampleGenerateDocumentDTO, ExampleGenerateDocumentResult, ExampleUploadFileDTO, ExampleUploadFileResult, ExampleSendEmailDTO, ExampleSendEmailResult, } from './types';

package/dist/examples/types.d.ts

@@ -165,6 +165,69 @@ export interface ExampleUser extends Record<string, unknown> {
     updated_at?: string;
     deleted_at?: string | null;
 }
+import type { GenerateFileParams, UploadParams, UploadResult } from '../storage';
+import type { SendEmailParams, NotificationResult, NotificationResponse } from '../notifications';
+/**
+ * DTO for generating a document (NO upload) using storage template engine.
+ * Re-exports GenerateFileParams from @plyaz/types/storage.
+ *
+ * Uses storage.generateFile() which:
+ * 1. Loads template from templates/{locale}/{category}/{templateId}.md
+ * 2. Renders with Handlebars + templateData
+ * 3. Converts to PDF/DOCX/XLSX
+ * 4. Returns Buffer (caller handles the buffer)
+ */
+export type ExampleGenerateDocumentDTO = GenerateFileParams;
+/**
+ * Result of document generation (Buffer-based, no URL).
+ * This is specific to the example service's JSON response format.
+ */
+export interface ExampleGenerateDocumentResult {
+    /** Generated document buffer (base64 encoded for JSON transport) */
+    buffer: string;
+    /** File size in bytes */
+    size: number;
+}
+/**
+ * DTO for generating AND uploading a document using storage template engine.
+ * Re-exports UploadParams from @plyaz/types/storage.
+ *
+ * Uses storage.uploadFile() with templateId which:
+ * 1. Loads template from templates/{locale}/{category}/{templateId}.md
+ * 2. Renders with Handlebars + templateData
+ * 3. Converts to PDF/DOCX/XLSX
+ * 4. Uploads to storage (R2/Supabase)
+ * 5. Returns URL
+ *
+ * NOTE: In production, generated documents should be linked to entities via
+ * a media table with foreign keys (e.g., campaign_id -> media.entity_id).
+ */
+export type ExampleUploadFileDTO = UploadParams;
+/**
+ * Result of file upload (with URL).
+ * Re-exports UploadResult from @plyaz/types/storage.
+ */
+export type ExampleUploadFileResult = UploadResult;
+/**
+ * DTO for sending an email using notification templates.
+ * Re-exports SendEmailParams from @plyaz/types/notifications.
+ *
+ * Uses notifications.sendEmail() which:
+ * 1. Loads template from templates/{locale}/email/{templateId}.md
+ * 2. Parses frontmatter (subject, layout, etc.)
+ * 3. Renders Markdown to HTML with templateData
+ * 4. Inlines CSS for email clients
+ * 5. Sends via configured provider (Infobip/SendGrid)
+ *
+ * NOTE: In production, sent emails should be tracked in a notifications
+ * table with foreign keys (e.g., campaign_id -> notifications.entity_id).
+ */
+export type ExampleSendEmailDTO = SendEmailParams;
+/**
+ * Result of sending an email.
+ * Uses NotificationResult<NotificationResponse> from @plyaz/types/notifications.
+ */
+export type ExampleSendEmailResult = NotificationResult<NotificationResponse>;
 /**
  * Example Domain Service Configuration
  */

package/dist/index.d.ts

@@ -1,12 +1,12 @@
 export * from './auth';
 export type * from './common';
 export * from './core';
+export type * from './store';
 export type * from './entities';
 export * from './errors';
 export * from './events';
 export * from './http/constants';
 export * from './locale/types';
-export type * from './store';
 export type * from './ui';
 export * from './web3';
 export type * from './translations';

package/dist/storage/index.d.ts

@@ -3,7 +3,7 @@
  * @module @plyaz/types/storage
  */
 export { ADAPTER_HEALTH_STATUS, ENTITY_TYPE, FILE_ACCESS_LEVEL, FILE_CATEGORY, FILE_VALIDATION_ERROR, MEDIA_VARIANT_TYPE, OUTPUT_FORMAT, PATH_GENERATION_STRATEGY, STORAGE_RENDERER_TYPE, RETRY_STRATEGY, STORAGE_ADAPTER_TYPE, STORAGE_EVENT_TYPE, STORAGE_QUEUE_PRIORITY, TEMPLATE_OUTPUT_FORMAT, DOCUMENT_TYPE, MEDIA_ENTITY, STORAGE_VISIBILITY, STORAGE_ENVIRONMENT, BUSINESS_MODEL, ORGANIZATION_TIER, BUCKET_PURPOSE, PATH_STRATEGY, UPLOAD_STATUS, STORAGE_JURISDICTION, STORAGE_REGULATORY_FRAMEWORK, STORAGE_PLUGIN_TYPE, STORAGE_WEBHOOK_EVENT_TYPE, STORAGE_OPERATION, STORAGE_SIGNATURE_METHOD, STORAGE_DEVICE_TYPE, STORAGE_VARIANT_NAME, TEMPLATE_VARIABLE_TYPE, TEMPLATE_DOCUMENT_TYPE, } from './enums';
-export type { AdapterHealthCheck, BaseStorageAdapterConfig, BucketConfiguration, BucketRouterConfig, CompliancePathOptions, CloudflareR2Config, CorsConfig, CustomAdapterConfig, DeleteParams, DownloadParams, DownloadResult, FileDeleteResult, FileMetadata, FileValidationResult, GeneralPathOptions, MediaPathOptions, MediaProcessingOptions, MockAdapterConfig, PathGenerationConfig, PDFRenderOptions, PresignedUrlOptions, PresignedUrlResult, StorageExcelRenderOptions, StorageWordRenderOptions, StorageFileOperationType, StorageQueueProcessFunction, StorageQueuedOperation, QueueItem, StorageQueueStatistics, RetentionPolicy, RoutingCondition, RoutingDecision, RoutingRule, ShareLinkConfig, StorageApiClientConfig, StorageCategory, StorageComplianceRule, StorageEventPayload, StorageEventHandlers, StorageLayoutConfig, StorageRenderOptions, StorageRendererAdapterConfig, StorageRendererHealthCheck, StorageRenderResult, StorageResult, StorageQueueConfig, StorageRetryConfig, StorageServiceConfig, StorageTemplateCacheEntry, StorageTemplateEngineConfig, StorageTemplateFrontmatter, StorageTemplateRenderResult, StorageTranslationService, SupabaseStorageConfig, TemplateConfig, TemplateService, UploadParams, UploadProgressEvent, UploadResult, ValidationRule, MultipartUploadPart, BucketDeletionResult, BucketPurposeValidationRules, StorageValidationConfig, StorageAdapterRegistryConfig, StorageEventManagerConfig, StorageQueueProcessorConfig, StorageComplianceManagerConfig, StorageRendererRegistryConfig, StorageLayoutEngineConfig, StorageAppliedLayout, StorageTranslationServiceConfig, FileSystemTemplateServiceConfig, StorageDocxTemplaterRendererConfig, StorageWordDocumentData, StoragePlaywrightRendererConfig, StoragePDFKitRendererConfig, StoragePDFKitDocumentData, StorageExcelJSRendererConfig, StorageExcelData, StoragePuppeteerRendererConfig, StorageMediaProcessingWebhookConfig, StorageRetryOptions, StorageHashPathOptions, StorageEntityPathOptions, StorageDatePathOptions, StorageCategoryPathOptions, StorageFlatPathOptions, StorageTemplateVariables, StorageSignedUrlOptions, StorageVerificationResult, StorageEventCallback, StoragePathHashAlgorithm, StorageHashAlgorithm, StorageSignedUrlPermission, StorageAdapterCapability, StorageVariantConfig, StoragePresetConfig, StorageResolvedVariant, StoragePresetManagerConfig, StorageResolveVariantsOptions, StorageBucketDeletionResult, StorageChunkExtractionResult, StorageChunkUploadPartResult, StorageBucketInfo, StorageCopyFileParams, StorageListBucketsResult, StorageListFilesParams, StorageListFilesResult, StorageMoveFileParams, StoragePublicUrlParams, StorageReplaceFileParams, StorageSignedUploadUrlParams, StorageSignedUploadUrlResult, StorageUpdateBucketParams, GenerateFileParams, GenerateFileToPathParams, GenerateFileToPathResult, UpdateFileParams, TemplateVariableValidation, TemplateVariableDefinition, TemplateVariableValidationResult, TemplateVariablesFrontmatter, CustomValidationSchema, TemplateValidationOptions, StorageTemplateRenderResultWithValidation, StorageTemplateValidationDataResult, StorageTemplateRenderToHtmlOptions, StorageTemplateBuildMetadataOptions, StorageTemplateTypeCoercionResult, StorageTemplateInvoiceLineItem, StorageTemplateInvoiceTotalOptions, StorageTemplateInvoiceTotalArgs, } from './interfaces';
+export type { AdapterHealthCheck, BaseStorageAdapterConfig, BucketConfiguration, BucketRouterConfig, CompliancePathOptions, CloudflareR2Config, CorsConfig, CustomAdapterConfig, DeleteParams, DownloadParams, DownloadResult, FileDeleteResult, FileMetadata, FileValidationResult, GeneralPathOptions, MediaPathOptions, MediaProcessingOptions, MockAdapterConfig, PathGenerationConfig, PDFRenderOptions, PresignedUrlOptions, PresignedUrlResult, StorageExcelRenderOptions, StorageWordRenderOptions, StorageFileOperationType, StorageQueueProcessFunction, StorageQueuedOperation, QueueItem, StorageQueueStatistics, RetentionPolicy, RoutingCondition, RoutingDecision, RoutingRule, ShareLinkConfig, StorageApiClientConfig, StorageCategory, StorageComplianceRule, StorageEventPayload, StorageEventHandlers, StorageLayoutConfig, StorageRenderOptions, StorageRendererAdapterConfig, StorageRendererHealthCheck, StorageRenderResult, StorageResult, StorageQueueConfig, StorageRetryConfig, StorageServiceConfig, StorageTemplateCacheEntry, StorageTemplateEngineConfig, StorageTemplateFrontmatter, StorageTemplateRenderResult, StorageTranslationService, SupabaseStorageConfig, TemplateConfig, TemplateService, UploadParams, UploadProgressEvent, UploadResult, ValidationRule, MultipartUploadPart, BucketDeletionResult, BucketPurposeValidationRules, StorageValidationConfig, StorageAdapterRegistryConfig, StorageEventManagerConfig, StorageQueueProcessorConfig, StorageComplianceManagerConfig, StorageRendererRegistryConfig, StorageLayoutEngineConfig, StorageAppliedLayout, StorageTranslationServiceConfig, FileSystemTemplateServiceConfig, StorageDocxTemplaterRendererConfig, StorageWordDocumentData, StoragePlaywrightRendererConfig, StoragePDFKitRendererConfig, StoragePDFKitDocumentData, StorageExcelJSRendererConfig, StorageExcelData, StoragePuppeteerRendererConfig, StorageMediaProcessingWebhookConfig, StorageRetryOptions, StorageHashPathOptions, StorageEntityPathOptions, StorageDatePathOptions, StorageCategoryPathOptions, StorageFlatPathOptions, StorageTemplateVariables, StorageSignedUrlOptions, StorageVerificationResult, StorageEventCallback, StoragePathHashAlgorithm, StorageHashAlgorithm, StorageSignedUrlPermission, StorageAdapterCapability, StorageVariantConfig, StoragePresetConfig, StorageResolvedVariant, StoragePresetManagerConfig, StorageResolveVariantsOptions, StorageBucketDeletionResult, StorageChunkExtractionResult, StorageChunkUploadPartResult, StorageBucketInfo, StorageCopyFileParams, StorageListBucketsResult, StorageListFilesParams, StorageListFilesResult, StorageMoveFileParams, StoragePublicUrlParams, StorageReplaceFileParams, StorageSignedUploadUrlParams, StorageSignedUploadUrlResult, StorageUpdateBucketParams, GenerateFileParams, GenerateFileToPathParams, GenerateFileToPathResult, UpdateFileParams, TemplateVariableValidation, TemplateVariableDefinition, TemplateVariableValidationResult, TemplateVariablesFrontmatter, CustomValidationSchema, TemplateValidationOptions, StorageTemplateRenderResultWithValidation, StorageTemplateValidationDataResult, StorageTemplateRenderToHtmlOptions, StorageTemplateBuildMetadataOptions, StorageTemplateTypeCoercionResult, StorageTemplateInvoiceLineItem, StorageTemplateInvoiceTotalOptions, StorageTemplateInvoiceTotalArgs, StorageServiceInstance, } from './interfaces';
 export { STORAGE_EVENT_HANDLER_MAPPING, STORAGE_EVENT_TYPE_TO_HANDLER_NAME, WEBHOOK_EVENT_TYPE_MAPPING, } from './event-handler-mapping';
 export type { StorageEventHandlerName, MappedStorageEventType } from './event-handler-mapping';
 export type { StorageRetentionPolicyType, StorageRetentionStrategy, StorageImmutabilityStrategy, StorageDeletionReason, StorageRetentionPolicy, StorageComplianceConfig, StorageComplianceCheckResult, StorageDeleteComplianceOptions, StorageBulkDeleteResult, StorageComplianceEventMetadata, StorageSoftDeleteMetadata, StorageJurisdictionContext, } from './compliance';