@plyaz/types 1.25.2 → 1.27.0

package/dist/storage/interfaces.d.ts

@@ -4,8 +4,8 @@
  */
 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 } from './enums';
-import type { StorageSoftDeleteMetadata, StorageDeleteComplianceOptions, StorageComplianceConfig } from './compliance';
+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 { StorageSoftDeleteMetadata, StorageDeleteComplianceOptions, StorageComplianceConfig, StorageRetentionPolicy } from './compliance';
 import type { PluginRegistryConfig, StorageKnownPluginName, StoragePlugin } from './plugins';
 import type { StorageBaseWebhookAdapterConfig, StorageWebhookAdapter, StorageWebhookManagerConfig } from './webhooks';
 /**
@@ -205,6 +205,11 @@ export interface UploadParams {
     excelOptions?: StorageExcelRenderOptions;
     /** Word render options (when outputFormat === 'word') */
     wordOptions?: StorageWordRenderOptions;
+    /**
+     * Validation options for template data
+     * When provided, validates templateData against schema before rendering
+     */
+    validation?: TemplateValidationOptions;
     /** Use queue for this operation (requires queue to be enabled in service config) */
     useQueue?: boolean;
     /** Queue priority (only used if useQueue is true) */
@@ -469,6 +474,64 @@ export interface StorageResolveVariantsOptions {
     /** Generate for all devices (ignores device parameter) */
     allDevices?: boolean;
 }
+/**
+ * Custom validation function type (Zod-like)
+ * Can be a Zod schema, custom validator function, or any object with parse/safeParse
+ */
+export interface CustomValidationSchema {
+    /**
+     * Parse method - throws on validation failure
+     * Compatible with Zod's parse() method
+     */
+    parse?: (data: unknown) => unknown;
+    /**
+     * Safe parse method - returns result object instead of throwing
+     * Compatible with Zod's safeParse() method
+     */
+    safeParse?: (data: unknown) => {
+        success: boolean;
+        data?: unknown;
+        error?: {
+            issues?: Array<{
+                path: (string | number)[];
+                message: string;
+            }>;
+        };
+    };
+    /**
+     * Custom validation function
+     * Returns validation result with errors and coerced values
+     */
+    validate?: (data: Record<string, unknown>) => TemplateVariableValidationResult;
+}
+/**
+ * Validation options for template rendering
+ */
+export interface TemplateValidationOptions {
+    /**
+     * Enable validation (default: true if schema exists in frontmatter)
+     * Set to false to skip validation entirely
+     */
+    enabled?: boolean;
+    /**
+     * Strict mode - throw error if validation fails (default: false)
+     * When false, continues rendering with warnings
+     */
+    strict?: boolean;
+    /**
+     * Custom validation schema (Zod-like)
+     * If provided, uses this instead of frontmatter variables
+     */
+    schema?: CustomValidationSchema;
+    /**
+     * Additional variable definitions to merge with frontmatter
+     */
+    additionalVariables?: TemplateVariableDefinition[];
+    /**
+     * Skip validation for specific fields
+     */
+    skipFields?: string[];
+}
 /**
  * Generate file parameters (to buffer, without uploading)
  */
@@ -485,6 +548,11 @@ export interface GenerateFileParams {
     rendererName?: STORAGE_RENDERER_TYPE | string;
     /** PDF render options */
     pdfOptions?: PDFRenderOptions;
+    /**
+     * Validation options
+     * When provided, validates templateData against schema before rendering
+     */
+    validation?: TemplateValidationOptions;
 }
 /**
  * Generate file to path parameters
@@ -530,6 +598,10 @@ export interface UpdateFileParams {
     skipPlugins?: readonly StorageKnownPluginName[];
     /** Only run these specific plugins for this operation */
     onlyPlugins?: readonly StorageKnownPluginName[];
+    /**
+     * Validation options for template data (if regenerating from template)
+     */
+    validation?: TemplateValidationOptions;
 }
 /**
  * Validation rule
@@ -1412,6 +1484,25 @@ export interface StorageTemplateFrontmatter {
         /** Base spacing unit (e.g., '4mm') */
         spacingUnit?: string;
     };
+    /** Document type (simple, financial, legal, etc.) */
+    documentType?: TEMPLATE_DOCUMENT_TYPE;
+    /** Calculation configuration for financial documents */
+    calculations?: {
+        enabled: boolean;
+        taxField?: string;
+        discountField?: string;
+        shippingField?: string;
+        itemsField?: string;
+    };
+    /** Variable definitions with types and validation */
+    variables?: TemplateVariableDefinition[];
+    /** Variable groups for UI organization */
+    variableGroups?: Array<{
+        name: string;
+        label: string;
+        description?: string;
+        collapsed?: boolean;
+    }>;
     /** Additional custom fields */
     [key: string]: unknown;
 }
@@ -2277,3 +2368,210 @@ export interface StorageChunkUploadPartResult {
     /** ETag from upload */
     ETag: string;
 }
+/**
+ * Validation rule for template variables
+ * Supports regex patterns, min/max values, and custom validators
+ */
+export interface TemplateVariableValidation {
+    /** Whether the variable is required */
+    required?: boolean;
+    /** Regex pattern for string validation */
+    pattern?: string;
+    /** Human-readable pattern description */
+    patternMessage?: string;
+    /** Minimum value (for numbers) or minimum length (for strings) */
+    min?: number;
+    /** Maximum value (for numbers) or maximum length (for strings) */
+    max?: number;
+    /** Minimum length for strings */
+    minLength?: number;
+    /** Maximum length for strings */
+    maxLength?: number;
+    /** Allowed values (for select/multiselect) */
+    enum?: string[];
+    /** Date format (for date type, e.g., 'YYYY-MM-DD') */
+    dateFormat?: string;
+    /** Minimum date (for date type) */
+    minDate?: string;
+    /** Maximum date (for date type) */
+    maxDate?: string;
+    /** Custom error message */
+    errorMessage?: string;
+}
+/**
+ * Definition for a template variable
+ * Specifies type, validation rules, and display information
+ */
+export interface TemplateVariableDefinition {
+    /** Variable name (matches {{variableName}} in template) */
+    name: string;
+    /** Variable type */
+    type: TEMPLATE_VARIABLE_TYPE;
+    /** Human-readable label for UI */
+    label?: string;
+    /** Description/help text */
+    description?: string;
+    /** Default value */
+    defaultValue?: unknown;
+    /** Placeholder text for input */
+    placeholder?: string;
+    /** Validation rules (optional) */
+    validation?: TemplateVariableValidation;
+    /** For ARRAY type: definition of array item structure */
+    items?: TemplateVariableDefinition;
+    /** For OBJECT type: nested variable definitions */
+    properties?: TemplateVariableDefinition[];
+    /** For SELECT/MULTISELECT: list of options */
+    options?: Array<{
+        label: string;
+        value: string;
+    }>;
+    /** Group name for organizing variables in UI */
+    group?: string;
+    /** Display order within group */
+    order?: number;
+    /** Whether this variable is hidden from editor UI */
+    hidden?: boolean;
+    /** Whether this variable is read-only in editor */
+    readOnly?: boolean;
+    /** Conditional visibility expression (e.g., "documentType === 'financial'") */
+    showIf?: string;
+}
+/**
+ * Template variable validation result
+ */
+export interface TemplateVariableValidationResult {
+    /** Whether validation passed */
+    valid: boolean;
+    /** Validation errors (variable name -> error messages) */
+    errors: Record<string, string[]>;
+    /** Warnings (non-blocking issues) */
+    warnings?: Record<string, string[]>;
+    /** Coerced/transformed values (after type coercion) */
+    coercedValues?: Record<string, unknown>;
+}
+/**
+ * Extended template frontmatter with variable definitions
+ */
+export interface TemplateVariablesFrontmatter {
+    /** Document type (simple, financial, legal, etc.) */
+    documentType?: TEMPLATE_DOCUMENT_TYPE;
+    /** Whether calculations are enabled */
+    calculations?: {
+        enabled: boolean;
+        taxField?: string;
+        discountField?: string;
+        shippingField?: string;
+        itemsField?: string;
+    };
+    /** Variable definitions */
+    variables?: TemplateVariableDefinition[];
+    /** Variable groups for UI organization */
+    variableGroups?: Array<{
+        name: string;
+        label: string;
+        description?: string;
+        collapsed?: boolean;
+    }>;
+}
+/**
+ * Extended render result with validation information
+ */
+export interface StorageTemplateRenderResultWithValidation extends StorageTemplateRenderResult {
+    /** Validation result if validation was performed */
+    validationResult?: TemplateVariableValidationResult;
+}
+/**
+ * Result from template data validation
+ * @internal Used by TemplateEngine.validateTemplateData
+ */
+export interface StorageTemplateValidationDataResult {
+    /** Data to use for rendering (may be coerced) */
+    renderData: Record<string, unknown>;
+    /** Validation result if validation was performed */
+    validationResult?: TemplateVariableValidationResult;
+}
+/**
+ * Options for rendering a template to HTML
+ * @internal Used by TemplateEngine.renderTemplateToHtml
+ */
+export interface StorageTemplateRenderToHtmlOptions {
+    /** Cache key for compiled template lookup */
+    cacheKey: string;
+    /** Loaded template entry with frontmatter and body */
+    templateEntry: StorageTemplateCacheEntry;
+    /** Data to render (may be coerced from validation) */
+    renderData: Record<string, unknown>;
+    /** Original data before validation/coercion */
+    originalData: Record<string, unknown>;
+    /** Locale for rendering */
+    locale: string;
+}
+/**
+ * Options for building template upload metadata
+ * @internal Used by StorageService.buildTemplateMetadata
+ */
+export interface StorageTemplateBuildMetadataOptions {
+    /** Original upload parameters */
+    params: UploadParams;
+    /** Generated document buffer */
+    documentBuffer: globalThis.Buffer;
+    /** Renderer that was used */
+    renderer: {
+        name: string;
+        type: string;
+    };
+    /** Locale used for generation */
+    locale: string;
+    /** Output format */
+    outputFormat: OUTPUT_FORMAT;
+    /** Compliance info if applicable */
+    complianceInfo?: StorageRetentionPolicy;
+}
+/**
+ * Result from type coercion during validation
+ * @internal Used by TemplateEngine validation methods
+ */
+export interface StorageTemplateTypeCoercionResult {
+    /** The coerced value (may be same as input if no coercion needed) */
+    coercedValue: unknown;
+    /** Type-related errors */
+    typeErrors: string[];
+    /** Type-related warnings (non-blocking) */
+    typeWarnings: string[];
+}
+/**
+ * Invoice line item for calculation helpers
+ */
+export interface StorageTemplateInvoiceLineItem {
+    /** Quantity of items */
+    quantity: number;
+    /** Unit price per item */
+    unitPrice: number;
+}
+/**
+ * Options for invoice total calculation helper
+ */
+export interface StorageTemplateInvoiceTotalOptions {
+    /** Array of invoice line items */
+    items: StorageTemplateInvoiceLineItem[];
+    /** Tax rate as percentage (0-100) */
+    taxRate?: number;
+    /** Discount percentage (0-100) */
+    discountPercent?: number;
+    /** Shipping cost */
+    shippingCost?: number;
+    /** Calculation type: 'subtotal', 'discount', 'tax', or 'total' */
+    calcType?: 'subtotal' | 'discount' | 'tax' | 'total';
+}
+/**
+ * Handlebars helper arguments for invoiceTotal
+ * Handlebars passes arguments positionally, so we need to parse them
+ */
+export type StorageTemplateInvoiceTotalArgs = [
+    items: StorageTemplateInvoiceLineItem[] | unknown,
+    taxRate?: number | unknown,
+    discountPercent?: number | unknown,
+    shippingCost?: number | unknown,
+    calcType?: string | unknown
+];

package/dist/storage/schemas.d.ts

@@ -222,3 +222,173 @@ export declare const SupabaseWebhookPayloadSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type SupabaseWebhookPayload = z.infer<typeof SupabaseWebhookPayloadSchema>;
 export type SupabaseStorageObject = z.infer<typeof SupabaseStorageObjectSchema>;
+/**
+ * ============================================================================
+ * Template Variable Schemas
+ * ============================================================================
+ * Validation schemas for template variable definitions
+ */
+/**
+ * Template variable types enum for schema validation
+ */
+export declare enum TEMPLATE_VARIABLE_TYPE_SCHEMA {
+    STRING = "string",
+    NUMBER = "number",
+    BOOLEAN = "boolean",
+    DATE = "date",
+    EMAIL = "email",
+    PHONE = "phone",
+    URL = "url",
+    CURRENCY = "currency",
+    PERCENTAGE = "percentage",
+    ARRAY = "array",
+    OBJECT = "object",
+    RICHTEXT = "richtext",
+    IMAGE = "image",
+    SELECT = "select",
+    MULTISELECT = "multiselect"
+}
+/**
+ * Template document types enum for schema validation
+ */
+export declare enum TEMPLATE_DOCUMENT_TYPE_SCHEMA {
+    SIMPLE = "simple",
+    FINANCIAL = "financial",
+    LEGAL = "legal",
+    REPORT = "report",
+    FORM = "form",
+    LETTER = "letter",
+    CERTIFICATE = "certificate"
+}
+/**
+ * Template variable validation schema
+ */
+export declare const TemplateVariableValidationSchema: z.ZodObject<{
+    required: z.ZodOptional<z.ZodBoolean>;
+    pattern: z.ZodOptional<z.ZodString>;
+    patternMessage: z.ZodOptional<z.ZodString>;
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    minLength: z.ZodOptional<z.ZodNumber>;
+    maxLength: z.ZodOptional<z.ZodNumber>;
+    enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    dateFormat: z.ZodOptional<z.ZodString>;
+    minDate: z.ZodOptional<z.ZodString>;
+    maxDate: z.ZodOptional<z.ZodString>;
+    errorMessage: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type TemplateVariableValidationType = z.infer<typeof TemplateVariableValidationSchema>;
+/**
+ * Template variable option schema (for select/multiselect)
+ */
+export declare const TemplateVariableOptionSchema: z.ZodObject<{
+    label: z.ZodString;
+    value: z.ZodString;
+}, z.core.$strip>;
+export type TemplateVariableOptionType = z.infer<typeof TemplateVariableOptionSchema>;
+/**
+ * Template variable definition schema (with recursive properties support)
+ * Note: Due to Zod limitations with recursive types, we use z.lazy()
+ */
+export declare const TemplateVariableDefinitionSchema: z.ZodType<{
+    name: string;
+    type: TEMPLATE_VARIABLE_TYPE_SCHEMA;
+    label?: string;
+    description?: string;
+    defaultValue?: unknown;
+    placeholder?: string;
+    validation?: TemplateVariableValidationType;
+    items?: unknown;
+    properties?: unknown[];
+    options?: TemplateVariableOptionType[];
+    group?: string;
+    order?: number;
+    hidden?: boolean;
+    readOnly?: boolean;
+    showIf?: string;
+}>;
+export type TemplateVariableDefinitionType = z.infer<typeof TemplateVariableDefinitionSchema>;
+/**
+ * Variable group schema for UI organization
+ */
+export declare const TemplateVariableGroupSchema: z.ZodObject<{
+    name: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    collapsed: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type TemplateVariableGroupType = z.infer<typeof TemplateVariableGroupSchema>;
+/**
+ * Calculations configuration schema
+ */
+export declare const TemplateCalculationsConfigSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    taxField: z.ZodOptional<z.ZodString>;
+    discountField: z.ZodOptional<z.ZodString>;
+    shippingField: z.ZodOptional<z.ZodString>;
+    itemsField: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type TemplateCalculationsConfigType = z.infer<typeof TemplateCalculationsConfigSchema>;
+/**
+ * Extended template frontmatter schema with variable definitions
+ */
+export declare const TemplateVariablesFrontmatterSchema: z.ZodObject<{
+    documentType: z.ZodOptional<z.ZodEnum<typeof TEMPLATE_DOCUMENT_TYPE_SCHEMA>>;
+    calculations: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        taxField: z.ZodOptional<z.ZodString>;
+        discountField: z.ZodOptional<z.ZodString>;
+        shippingField: z.ZodOptional<z.ZodString>;
+        itemsField: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    variables: z.ZodOptional<z.ZodArray<z.ZodType<{
+        name: string;
+        type: TEMPLATE_VARIABLE_TYPE_SCHEMA;
+        label?: string;
+        description?: string;
+        defaultValue?: unknown;
+        placeholder?: string;
+        validation?: TemplateVariableValidationType;
+        items?: unknown;
+        properties?: unknown[];
+        options?: TemplateVariableOptionType[];
+        group?: string;
+        order?: number;
+        hidden?: boolean;
+        readOnly?: boolean;
+        showIf?: string;
+    }, unknown, z.core.$ZodTypeInternals<{
+        name: string;
+        type: TEMPLATE_VARIABLE_TYPE_SCHEMA;
+        label?: string;
+        description?: string;
+        defaultValue?: unknown;
+        placeholder?: string;
+        validation?: TemplateVariableValidationType;
+        items?: unknown;
+        properties?: unknown[];
+        options?: TemplateVariableOptionType[];
+        group?: string;
+        order?: number;
+        hidden?: boolean;
+        readOnly?: boolean;
+        showIf?: string;
+    }, unknown>>>>;
+    variableGroups: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        collapsed: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type TemplateVariablesFrontmatterType = z.infer<typeof TemplateVariablesFrontmatterSchema>;
+/**
+ * Validation result schema
+ */
+export declare const TemplateVariableValidationResultSchema: z.ZodObject<{
+    valid: z.ZodBoolean;
+    errors: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
+    warnings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+    coercedValues: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type TemplateVariableValidationResultType = z.infer<typeof TemplateVariableValidationResultSchema>;

package/package.json

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