@varity-labs/sdk 2.0.0-alpha.1

package/dist/core/template-loader.js

@@ -0,0 +1,380 @@
+/**
+ * Template Loader
+ *
+ * Utility for loading and registering built-in templates
+ */
+import { templateRegistry } from './template';
+// Import template JSON files (will be bundled by build tool)
+// Note: In actual implementation, these would be imported as:
+// import isoTemplate from '../../templates/iso.template.json'
+// For now, we'll use a dynamic loading approach
+/**
+ * Load built-in ISO template
+ */
+export function loadISOTemplate() {
+    const template = {
+        type: 'iso',
+        name: 'ISO Merchant Services Dashboard',
+        version: '1.0.0',
+        description: 'Payment processing and merchant management platform for Independent Sales Organizations',
+        contracts: [
+            {
+                name: 'MerchantRegistry',
+                description: 'Merchant registration and management',
+                abi: '../../contracts/abis/iso/MerchantRegistry.json',
+                addresses: {
+                    'arbitrum-sepolia': '',
+                    'arbitrum-l3-testnet': '',
+                    'arbitrum-l3-mainnet': ''
+                },
+                required: true
+            },
+            {
+                name: 'TransactionVault',
+                description: 'Transaction recording and storage',
+                abi: '../../contracts/abis/iso/TransactionVault.json',
+                addresses: {
+                    'arbitrum-sepolia': '',
+                    'arbitrum-l3-testnet': '',
+                    'arbitrum-l3-mainnet': ''
+                },
+                required: true
+            },
+            {
+                name: 'RepPerformance',
+                description: 'Sales representative performance tracking',
+                abi: '../../contracts/abis/iso/RepPerformance.json',
+                addresses: {
+                    'arbitrum-sepolia': '',
+                    'arbitrum-l3-testnet': '',
+                    'arbitrum-l3-mainnet': ''
+                },
+                required: true
+            },
+            {
+                name: 'ResidualCalculator',
+                description: 'Residual income calculation and distribution',
+                abi: '../../contracts/abis/iso/ResidualCalculator.json',
+                addresses: {
+                    'arbitrum-sepolia': '',
+                    'arbitrum-l3-testnet': '',
+                    'arbitrum-l3-mainnet': ''
+                },
+                required: true
+            },
+            {
+                name: 'AccessControlRegistry',
+                description: 'Role-based access control',
+                abi: '../../contracts/abis/iso/AccessControlRegistry.json',
+                addresses: {
+                    'arbitrum-sepolia': '',
+                    'arbitrum-l3-testnet': '',
+                    'arbitrum-l3-mainnet': ''
+                },
+                required: true
+            },
+            {
+                name: 'DataProofRegistry',
+                description: 'Data integrity and ownership proofs',
+                abi: '../../contracts/abis/iso/DataProofRegistry.json',
+                addresses: {
+                    'arbitrum-sepolia': '',
+                    'arbitrum-l3-testnet': '',
+                    'arbitrum-l3-mainnet': ''
+                },
+                required: true
+            }
+        ],
+        entities: [
+            {
+                name: 'merchant',
+                displayName: 'Merchant',
+                description: 'Business registered for payment processing',
+                idField: 'merchantId',
+                displayField: 'businessName',
+                fields: [
+                    {
+                        name: 'merchantId',
+                        label: 'Merchant ID',
+                        type: 'string',
+                        required: true
+                    },
+                    {
+                        name: 'businessName',
+                        label: 'Business Name',
+                        type: 'string',
+                        required: true
+                    },
+                    {
+                        name: 'walletAddress',
+                        label: 'Wallet Address',
+                        type: 'address',
+                        required: true
+                    },
+                    {
+                        name: 'status',
+                        label: 'Status',
+                        type: 'enum',
+                        required: true,
+                        enumValues: ['PENDING', 'ACTIVE', 'SUSPENDED', 'TERMINATED']
+                    },
+                    {
+                        name: 'monthlyVolume',
+                        label: 'Monthly Volume',
+                        type: 'number'
+                    },
+                    {
+                        name: 'onboardedBy',
+                        label: 'Onboarded By',
+                        type: 'address'
+                    }
+                ],
+                endpoints: {
+                    list: '/api/v1/merchants',
+                    get: '/api/v1/merchants/:id',
+                    create: '/api/v1/merchants',
+                    update: '/api/v1/merchants/:id'
+                }
+            },
+            {
+                name: 'transaction',
+                displayName: 'Transaction',
+                description: 'Payment transaction record',
+                idField: 'transactionId',
+                displayField: 'transactionId',
+                fields: [
+                    {
+                        name: 'transactionId',
+                        label: 'Transaction ID',
+                        type: 'string',
+                        required: true
+                    },
+                    {
+                        name: 'merchantId',
+                        label: 'Merchant ID',
+                        type: 'string',
+                        required: true
+                    },
+                    {
+                        name: 'amount',
+                        label: 'Amount',
+                        type: 'number',
+                        required: true
+                    },
+                    {
+                        name: 'type',
+                        label: 'Type',
+                        type: 'enum',
+                        required: true,
+                        enumValues: ['SALE', 'REFUND', 'CHARGEBACK', 'ADJUSTMENT']
+                    },
+                    {
+                        name: 'timestamp',
+                        label: 'Timestamp',
+                        type: 'date',
+                        required: true
+                    }
+                ],
+                endpoints: {
+                    list: '/api/v1/transactions',
+                    get: '/api/v1/transactions/:id',
+                    create: '/api/v1/transactions'
+                }
+            },
+            {
+                name: 'rep',
+                displayName: 'Sales Representative',
+                description: 'Sales representative managing merchants',
+                idField: 'repAddress',
+                displayField: 'repAddress',
+                fields: [
+                    {
+                        name: 'repAddress',
+                        label: 'Rep Address',
+                        type: 'address',
+                        required: true
+                    },
+                    {
+                        name: 'status',
+                        label: 'Status',
+                        type: 'enum',
+                        required: true,
+                        enumValues: ['ACTIVE', 'INACTIVE', 'SUSPENDED']
+                    },
+                    {
+                        name: 'totalMerchants',
+                        label: 'Total Merchants',
+                        type: 'number'
+                    },
+                    {
+                        name: 'totalResiduals',
+                        label: 'Total Residuals',
+                        type: 'number'
+                    }
+                ],
+                endpoints: {
+                    list: '/api/v1/reps',
+                    get: '/api/v1/reps/:address',
+                    create: '/api/v1/reps'
+                }
+            }
+        ],
+        events: [
+            {
+                name: 'merchant.registered',
+                displayName: 'Merchant Registered',
+                description: 'New merchant registered for processing',
+                category: 'merchant'
+            },
+            {
+                name: 'merchant.updated',
+                displayName: 'Merchant Updated',
+                description: 'Merchant information updated',
+                category: 'merchant'
+            },
+            {
+                name: 'merchant.status_changed',
+                displayName: 'Merchant Status Changed',
+                description: 'Merchant status changed (activated, suspended, etc.)',
+                category: 'merchant'
+            },
+            {
+                name: 'transaction.created',
+                displayName: 'Transaction Created',
+                description: 'New transaction recorded',
+                category: 'transaction'
+            },
+            {
+                name: 'transaction.voided',
+                displayName: 'Transaction Voided',
+                description: 'Transaction voided or refunded',
+                category: 'transaction'
+            },
+            {
+                name: 'rep.registered',
+                displayName: 'Rep Registered',
+                description: 'New sales representative registered',
+                category: 'rep'
+            },
+            {
+                name: 'residual.calculated',
+                displayName: 'Residual Calculated',
+                description: 'Monthly residual income calculated',
+                category: 'residual'
+            },
+            {
+                name: 'residual.paid',
+                displayName: 'Residual Paid',
+                description: 'Residual income paid to representative',
+                category: 'residual'
+            }
+        ],
+        metrics: [
+            {
+                name: 'total_merchants',
+                displayName: 'Total Merchants',
+                description: 'Total number of active merchants',
+                type: 'count',
+                source: '/api/v1/analytics/metrics/merchants/count',
+                unit: 'merchants'
+            },
+            {
+                name: 'total_volume',
+                displayName: 'Total Processing Volume',
+                description: 'Total payment processing volume',
+                type: 'sum',
+                source: '/api/v1/analytics/metrics/transactions/volume',
+                unit: 'USD',
+                format: 'currency'
+            },
+            {
+                name: 'avg_transaction_size',
+                displayName: 'Average Transaction Size',
+                description: 'Average transaction amount',
+                type: 'average',
+                source: '/api/v1/analytics/metrics/transactions/avg_size',
+                unit: 'USD',
+                format: 'currency'
+            },
+            {
+                name: 'chargeback_rate',
+                displayName: 'Chargeback Rate',
+                description: 'Percentage of transactions resulting in chargebacks',
+                type: 'percentage',
+                source: '/api/v1/analytics/metrics/transactions/chargeback_rate',
+                unit: '%',
+                format: 'percentage'
+            },
+            {
+                name: 'active_reps',
+                displayName: 'Active Representatives',
+                description: 'Number of active sales representatives',
+                type: 'count',
+                source: '/api/v1/analytics/metrics/reps/active_count',
+                unit: 'reps'
+            }
+        ],
+        dashboards: [
+            {
+                name: 'overview',
+                displayName: 'Overview Dashboard',
+                description: 'High-level metrics and KPIs',
+                defaultTimeRange: 'last_30_days',
+                widgets: [
+                    {
+                        type: 'kpi',
+                        title: 'Total Merchants',
+                        source: 'total_merchants',
+                        size: { width: 3, height: 2 },
+                        position: { x: 0, y: 0 }
+                    },
+                    {
+                        type: 'kpi',
+                        title: 'Processing Volume',
+                        source: 'total_volume',
+                        size: { width: 3, height: 2 },
+                        position: { x: 3, y: 0 }
+                    },
+                    {
+                        type: 'chart',
+                        title: 'Volume Trend',
+                        source: '/api/v1/analytics/trends/volume',
+                        size: { width: 6, height: 4 },
+                        position: { x: 0, y: 2 },
+                        config: { chartType: 'line' }
+                    }
+                ]
+            }
+        ],
+        storage: {
+            customerNamespacePattern: 'customer-iso-{company-id}',
+            encryptionEnabled: true,
+            litProtocolEnabled: true,
+            celestiaDAEnabled: true,
+            zkProofsEnabled: true
+        },
+        api: {
+            basePath: '/api/v1/iso'
+        },
+        features: {
+            analytics: true,
+            forecasting: true,
+            webhooks: true,
+            notifications: true,
+            export: true,
+            cache: true,
+            monitoring: true
+        }
+    };
+    templateRegistry.register(template);
+    return template;
+}
+/**
+ * Load all built-in templates
+ */
+export function loadAllTemplates() {
+    loadISOTemplate();
+    // Future: loadHealthcareTemplate(), loadFinanceTemplate(), loadRetailTemplate()
+}
+// Auto-load templates when module is imported
+loadAllTemplates();

package/dist/core/template.d.ts

@@ -0,0 +1,321 @@
+/**
+ * Template Configuration System
+ *
+ * Defines the schema and types for Varity templates (ISO, Healthcare, Finance, Retail, etc.)
+ * Enables dynamic SDK configuration based on template selection
+ */
+import type { Network } from './types';
+/**
+ * Available template types
+ */
+export type TemplateType = 'iso' | 'healthcare' | 'finance' | 'retail' | 'custom';
+/**
+ * Contract configuration for a template
+ */
+export interface TemplateContract {
+    /** Contract name */
+    name: string;
+    /** Contract description */
+    description?: string;
+    /** ABI file path or inline ABI */
+    abi: string | any[];
+    /** Contract address (per network) */
+    addresses: Partial<Record<Network, string>>;
+    /** Whether contract is required for template */
+    required?: boolean;
+}
+/**
+ * Entity configuration (e.g., Merchant, Patient, Customer)
+ */
+export interface TemplateEntity {
+    /** Entity name */
+    name: string;
+    /** Display name */
+    displayName: string;
+    /** Entity description */
+    description?: string;
+    /** Primary identifier field */
+    idField: string;
+    /** Display field for entity */
+    displayField: string;
+    /** Available fields */
+    fields: EntityField[];
+    /** API endpoints for entity CRUD */
+    endpoints?: {
+        list?: string;
+        get?: string;
+        create?: string;
+        update?: string;
+        delete?: string;
+    };
+    /** Contract mapping configuration (optional - defaults to standard patterns) */
+    contractMapping?: {
+        /** Contract name (defaults to '{Entity}Registry') */
+        contractName?: string;
+        /** Function names for CRUD operations */
+        functions?: {
+            /** Create function (defaults to 'create{Entity}') */
+            create?: string;
+            /** Get/Read function (defaults to 'get{Entity}') */
+            get?: string;
+            /** Get all/List function (defaults to 'getAll{Entity}s') */
+            getAll?: string;
+            /** Update function (defaults to 'update{Entity}') */
+            update?: string;
+            /** Delete function (defaults to 'delete{Entity}') */
+            delete?: string;
+            /** Count function (defaults to 'get{Entity}Count') */
+            count?: string;
+        };
+        /** Field mappings (if contract field names differ from entity field names) */
+        fieldMappings?: Record<string, string>;
+    };
+}
+/**
+ * Entity field types - Universal support for all industries
+ */
+export type EntityFieldType = 'string' | 'number' | 'boolean' | 'enum' | 'array' | 'object' | 'currency' | 'decimal' | 'percentage' | 'date' | 'time' | 'datetime' | 'duration' | 'email' | 'phone' | 'url' | 'address' | 'ssn' | 'tax-id' | 'medical-code' | 'sku' | 'barcode' | 'rich-text' | 'markdown' | 'json' | 'file' | 'image' | 'document' | 'lookup' | 'multi-select' | 'coordinates' | 'color' | 'ip-address';
+/**
+ * Entity field definition
+ */
+export interface EntityField {
+    /** Field name */
+    name: string;
+    /** Display label */
+    label: string;
+    /** Field type */
+    type: EntityFieldType;
+    /** Whether field is required */
+    required?: boolean;
+    /** Field description */
+    description?: string;
+    /** Enum values (if type is enum or multi-select) */
+    enumValues?: string[];
+    /** Lookup configuration (if type is lookup) */
+    lookupConfig?: {
+        entity: string;
+        displayField: string;
+        valueField: string;
+    };
+    /** Validation rules */
+    validation?: {
+        min?: number;
+        max?: number;
+        minLength?: number;
+        maxLength?: number;
+        pattern?: string;
+        precision?: number;
+        fileTypes?: string[];
+        maxFileSize?: number;
+        custom?: string;
+    };
+    /** Default value */
+    defaultValue?: any;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Help text */
+    helperText?: string;
+}
+/**
+ * Event configuration for webhooks and notifications
+ */
+export interface TemplateEvent {
+    /** Event name */
+    name: string;
+    /** Display name */
+    displayName: string;
+    /** Event description */
+    description?: string;
+    /** Event category */
+    category: string;
+    /** Payload schema */
+    payloadSchema?: Record<string, any>;
+}
+/**
+ * Metric configuration for analytics
+ */
+export interface TemplateMetric {
+    /** Metric name */
+    name: string;
+    /** Display name */
+    displayName: string;
+    /** Metric description */
+    description?: string;
+    /** Metric type */
+    type: 'count' | 'sum' | 'average' | 'percentage' | 'rate';
+    /** Data source (API endpoint or query) */
+    source: string;
+    /** Aggregation function */
+    aggregation?: string;
+    /** Unit of measurement */
+    unit?: string;
+    /** Format for display */
+    format?: string;
+}
+/**
+ * Dashboard configuration
+ */
+export interface TemplateDashboard {
+    /** Dashboard name */
+    name: string;
+    /** Display name */
+    displayName: string;
+    /** Dashboard description */
+    description?: string;
+    /** Widgets to display */
+    widgets: DashboardWidget[];
+    /** Default time range */
+    defaultTimeRange?: string;
+}
+/**
+ * Dashboard widget configuration
+ */
+export interface DashboardWidget {
+    /** Widget type */
+    type: 'kpi' | 'chart' | 'table' | 'map' | 'list' | 'custom';
+    /** Widget title */
+    title: string;
+    /** Data source (metric name or API endpoint) */
+    source: string;
+    /** Widget size (grid units) */
+    size?: {
+        width: number;
+        height: number;
+    };
+    /** Widget position */
+    position?: {
+        x: number;
+        y: number;
+    };
+    /** Widget configuration */
+    config?: Record<string, any>;
+}
+/**
+ * Storage layer configuration for template
+ */
+export interface TemplateStorageConfig {
+    /** Varity internal namespace */
+    varityNamespace?: string;
+    /** Industry RAG namespace */
+    industryNamespace?: string;
+    /** Customer data namespace pattern */
+    customerNamespacePattern: string;
+    /** Encryption enabled */
+    encryptionEnabled: boolean;
+    /** Lit Protocol access conditions */
+    litProtocolEnabled: boolean;
+    /** Celestia DA enabled */
+    celestiaDAEnabled: boolean;
+    /** ZK proofs enabled */
+    zkProofsEnabled: boolean;
+}
+/**
+ * Complete template configuration
+ */
+export interface TemplateConfig {
+    /** Template type identifier */
+    type: TemplateType;
+    /** Template name */
+    name: string;
+    /** Template version */
+    version: string;
+    /** Template description */
+    description?: string;
+    /** Smart contracts for this template */
+    contracts: TemplateContract[];
+    /** Entities (data models) */
+    entities: TemplateEntity[];
+    /** Available events */
+    events: TemplateEvent[];
+    /** Available metrics */
+    metrics: TemplateMetric[];
+    /** Dashboard configurations */
+    dashboards?: TemplateDashboard[];
+    /** Storage configuration */
+    storage: TemplateStorageConfig;
+    /** API configuration */
+    api?: {
+        /** Base path for template APIs */
+        basePath: string;
+        /** Custom endpoints */
+        customEndpoints?: Record<string, string>;
+    };
+    /** Feature flags */
+    features?: {
+        analytics?: boolean;
+        forecasting?: boolean;
+        webhooks?: boolean;
+        notifications?: boolean;
+        export?: boolean;
+        cache?: boolean;
+        monitoring?: boolean;
+    };
+    /** Custom configuration */
+    custom?: Record<string, any>;
+}
+/**
+ * Template registry for loading and managing templates
+ */
+export declare class TemplateRegistry {
+    private templates;
+    /**
+     * Register a template configuration
+     */
+    register(config: TemplateConfig): void;
+    /**
+     * Get template configuration by type
+     */
+    get(type: TemplateType): TemplateConfig | undefined;
+    /**
+     * Check if template is registered
+     */
+    has(type: TemplateType): boolean;
+    /**
+     * List all registered templates
+     */
+    list(): TemplateConfig[];
+    /**
+     * Load template from JSON
+     */
+    loadFromJSON(json: string): TemplateConfig;
+    /**
+     * Load template from URL
+     */
+    loadFromURL(url: string): Promise<TemplateConfig>;
+}
+/**
+ * Global template registry instance
+ */
+export declare const templateRegistry: TemplateRegistry;
+/**
+ * Validate template configuration
+ */
+export declare function validateTemplate(config: TemplateConfig): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Get contract ABI by name from template
+ */
+export declare function getContractABI(template: TemplateConfig, contractName: string): any[] | null;
+/**
+ * Get contract address for network
+ */
+export declare function getContractAddress(template: TemplateConfig, contractName: string, network: Network): string | null;
+/**
+ * Get entity configuration by name
+ */
+export declare function getEntity(template: TemplateConfig, entityName: string): TemplateEntity | null;
+/**
+ * Get metric configuration by name
+ */
+export declare function getMetric(template: TemplateConfig, metricName: string): TemplateMetric | null;
+/**
+ * Get event configuration by name
+ */
+export declare function getEvent(template: TemplateConfig, eventName: string): TemplateEvent | null;
+/**
+ * Merge template configuration with overrides
+ */
+export declare function mergeTemplateConfig(base: TemplateConfig, overrides: Partial<TemplateConfig>): TemplateConfig;
+//# sourceMappingURL=template.d.ts.map