@open-captable-protocol/canton 0.2.145 → 0.2.147

package/dist/utils/validation.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Centralized input validation utilities for OCF operations.
+ *
+ * These utilities provide consistent, actionable error messages and
+ * reduce duplicated validation logic across the codebase.
+ *
+ * @example
+ *   ```typescript
+ *   import { validateRequiredString, validateRequiredNumeric, ValidationError } from './validation';
+ *
+ *   function createStakeholder(params: CreateStakeholderParams) {
+ *     validateRequiredString(params.data.id, 'stakeholder.id');
+ *     validateRequiredString(params.data.name.legal_name, 'stakeholder.name.legal_name');
+ *     // ...
+ *   }
+ *   ```
+ */
+/**
+ * Custom error class for validation failures.
+ * Includes the field path for easier debugging.
+ */
+export declare class ValidationError extends Error {
+    /** The field path that failed validation (e.g., "stakeholder.name.legal_name") */
+    readonly fieldPath: string;
+    /** The expected type or format */
+    readonly expected: string;
+    /** The actual value received (stringified for display) */
+    readonly received: string;
+    constructor(fieldPath: string, expected: string, received: unknown);
+}
+/**
+ * Validate that a value is a non-empty string.
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages (e.g., "stakeholder.id")
+ * @throws {ValidationError} if the value is not a non-empty string
+ */
+export declare function validateRequiredString(value: unknown, fieldPath: string): asserts value is string;
+/**
+ * Validate that a value is a string or undefined/null.
+ * Returns the string or null for DAML optional fields.
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @returns The string value or null
+ * @throws {ValidationError} if the value is not a string, undefined, or null
+ */
+export declare function validateOptionalString(value: unknown, fieldPath: string): string | null;
+/**
+ * Validate that a value is a valid numeric (number or numeric string).
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @throws {ValidationError} if the value is not a valid numeric
+ */
+export declare function validateRequiredNumeric(value: unknown, fieldPath: string): asserts value is string | number;
+/**
+ * Validate and convert a numeric value to string for DAML.
+ * Returns null for undefined/null values.
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @returns The numeric value as a string, or null
+ */
+export declare function validateOptionalNumeric(value: unknown, fieldPath: string): string | null;
+/**
+ * Validate that a numeric value is within a range (inclusive).
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @param min - Minimum allowed value
+ * @param max - Maximum allowed value
+ * @throws {ValidationError} if the value is outside the range
+ */
+export declare function validateNumericRange(value: number | string, fieldPath: string, min: number, max: number): void;
+/**
+ * Validate that a numeric value is positive (> 0).
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @throws {ValidationError} if the value is not positive
+ */
+export declare function validatePositiveNumeric(value: number | string, fieldPath: string): void;
+/**
+ * Validate that a numeric value is non-negative (>= 0).
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @throws {ValidationError} if the value is negative
+ */
+export declare function validateNonNegativeNumeric(value: number | string, fieldPath: string): void;
+/**
+ * Validate that a value is a valid ISO date string (YYYY-MM-DD).
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @throws {ValidationError} if the value is not a valid ISO date string
+ */
+export declare function validateRequiredDate(value: unknown, fieldPath: string): asserts value is string;
+/**
+ * Validate that a value is a valid ISO date string or undefined/null.
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @returns The date string or null
+ */
+export declare function validateOptionalDate(value: unknown, fieldPath: string): string | null;
+/**
+ * Validate that a value is one of the allowed enum values.
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @param allowedValues - Array of allowed values
+ * @throws {ValidationError} if the value is not in the allowed list
+ */
+export declare function validateEnum<T extends string>(value: unknown, fieldPath: string, allowedValues: readonly T[]): asserts value is T;
+/**
+ * Validate an optional enum value.
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @param allowedValues - Array of allowed values
+ * @returns The value or null
+ */
+export declare function validateOptionalEnum<T extends string>(value: unknown, fieldPath: string, allowedValues: readonly T[]): T | null;
+/**
+ * Validate that a value is a non-empty array.
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @throws {ValidationError} if the value is not a non-empty array
+ */
+export declare function validateRequiredArray<T>(value: unknown, fieldPath: string): asserts value is T[];
+/**
+ * Validate an optional array (can be undefined/null or array with items).
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @returns The array or null
+ */
+export declare function validateOptionalArray<T>(value: unknown, fieldPath: string): T[] | null;
+/**
+ * Validate that a value is a non-null object.
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @throws {ValidationError} if the value is not a non-null object
+ */
+export declare function validateRequiredObject(value: unknown, fieldPath: string): asserts value is Record<string, unknown>;
+/**
+ * Validate an optional object.
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @returns The object or null
+ */
+export declare function validateOptionalObject(value: unknown, fieldPath: string): Record<string, unknown> | null;
+/**
+ * Monetary object structure for validation.
+ */
+export interface ValidatedMonetary {
+    amount: string;
+    currency: string;
+}
+/**
+ * Validate that a value is a valid Monetary object.
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @throws {ValidationError} if the value is not a valid Monetary object
+ */
+export declare function validateRequiredMonetary(value: unknown, fieldPath: string): asserts value is ValidatedMonetary;
+/**
+ * Validate an optional Monetary object.
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @returns The validated monetary object or null
+ */
+export declare function validateOptionalMonetary(value: unknown, fieldPath: string): ValidatedMonetary | null;
+/**
+ * Validate that a value is a valid Canton contract ID.
+ * Contract IDs are typically in format: hexdigits:hexdigits or just hexdigits.
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @throws {ValidationError} if the value is not a valid contract ID
+ */
+export declare function validateContractId(value: unknown, fieldPath: string): asserts value is string;
+/**
+ * Validate that a value is a valid Canton party ID.
+ * Party IDs typically follow the format: identifier::fingerprint
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @throws {ValidationError} if the value is not a valid party ID
+ */
+export declare function validatePartyId(value: unknown, fieldPath: string): asserts value is string;
+/**
+ * Validate all items in an array using a validator function.
+ *
+ * @param items - The array of items to validate
+ * @param fieldPath - Base path for error messages
+ * @param itemValidator - Function to validate each item
+ */
+export declare function validateArrayItems<T>(items: unknown[], fieldPath: string, itemValidator: (item: unknown, itemPath: string) => asserts item is T): asserts items is T[];
+/**
+ * Create a composite validator that runs multiple validations.
+ *
+ * @example
+ *   ```typescript
+ *   const validateStakeholder = createValidator<OcfStakeholder>(
+ *     (value, path) => {
+ *       validateRequiredString(value.id, `${path}.id`);
+ *       validateRequiredObject(value.name, `${path}.name`);
+ *       validateRequiredString(value.name?.legal_name, `${path}.name.legal_name`);
+ *       validateEnum(value.stakeholder_type, `${path}.stakeholder_type`, ['INDIVIDUAL', 'INSTITUTION']);
+ *     }
+ *   );
+ *
+ *   validateStakeholder(data, 'stakeholder');
+ *   ```
+ */
+export declare function createValidator<T>(validatorFn: (value: Record<string, unknown>, fieldPath: string) => void): (value: unknown, fieldPath: string) => asserts value is T;
+//# sourceMappingURL=validation.d.ts.map

package/dist/utils/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"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"}

package/dist/utils/validation.js

@@ -0,0 +1,401 @@
+"use strict";
+/**
+ * Centralized input validation utilities for OCF operations.
+ *
+ * These utilities provide consistent, actionable error messages and
+ * reduce duplicated validation logic across the codebase.
+ *
+ * @example
+ *   ```typescript
+ *   import { validateRequiredString, validateRequiredNumeric, ValidationError } from './validation';
+ *
+ *   function createStakeholder(params: CreateStakeholderParams) {
+ *     validateRequiredString(params.data.id, 'stakeholder.id');
+ *     validateRequiredString(params.data.name.legal_name, 'stakeholder.name.legal_name');
+ *     // ...
+ *   }
+ *   ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValidationError = void 0;
+exports.validateRequiredString = validateRequiredString;
+exports.validateOptionalString = validateOptionalString;
+exports.validateRequiredNumeric = validateRequiredNumeric;
+exports.validateOptionalNumeric = validateOptionalNumeric;
+exports.validateNumericRange = validateNumericRange;
+exports.validatePositiveNumeric = validatePositiveNumeric;
+exports.validateNonNegativeNumeric = validateNonNegativeNumeric;
+exports.validateRequiredDate = validateRequiredDate;
+exports.validateOptionalDate = validateOptionalDate;
+exports.validateEnum = validateEnum;
+exports.validateOptionalEnum = validateOptionalEnum;
+exports.validateRequiredArray = validateRequiredArray;
+exports.validateOptionalArray = validateOptionalArray;
+exports.validateRequiredObject = validateRequiredObject;
+exports.validateOptionalObject = validateOptionalObject;
+exports.validateRequiredMonetary = validateRequiredMonetary;
+exports.validateOptionalMonetary = validateOptionalMonetary;
+exports.validateContractId = validateContractId;
+exports.validatePartyId = validatePartyId;
+exports.validateArrayItems = validateArrayItems;
+exports.createValidator = createValidator;
+/**
+ * Custom error class for validation failures.
+ * Includes the field path for easier debugging.
+ */
+class ValidationError extends Error {
+    constructor(fieldPath, expected, received) {
+        const receivedStr = received === undefined ? 'undefined' : received === null ? 'null' : JSON.stringify(received);
+        const message = `Validation failed for '${fieldPath}': expected ${expected}, received ${receivedStr}`;
+        super(message);
+        this.name = 'ValidationError';
+        this.fieldPath = fieldPath;
+        this.expected = expected;
+        this.received = receivedStr;
+    }
+}
+exports.ValidationError = ValidationError;
+// ===== String Validation =====
+/**
+ * Validate that a value is a non-empty string.
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages (e.g., "stakeholder.id")
+ * @throws {ValidationError} if the value is not a non-empty string
+ */
+function validateRequiredString(value, fieldPath) {
+    if (typeof value !== 'string') {
+        throw new ValidationError(fieldPath, 'non-empty string', value);
+    }
+    if (value.length === 0) {
+        throw new ValidationError(fieldPath, 'non-empty string', '""');
+    }
+}
+/**
+ * Validate that a value is a string or undefined/null.
+ * Returns the string or null for DAML optional fields.
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @returns The string value or null
+ * @throws {ValidationError} if the value is not a string, undefined, or null
+ */
+function validateOptionalString(value, fieldPath) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (typeof value !== 'string') {
+        throw new ValidationError(fieldPath, 'string, undefined, or null', value);
+    }
+    return value.length > 0 ? value : null;
+}
+// ===== Numeric Validation =====
+/**
+ * Validate that a value is a valid numeric (number or numeric string).
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @throws {ValidationError} if the value is not a valid numeric
+ */
+function validateRequiredNumeric(value, fieldPath) {
+    if (typeof value === 'number') {
+        if (Number.isNaN(value)) {
+            throw new ValidationError(fieldPath, 'valid number', 'NaN');
+        }
+        return;
+    }
+    if (typeof value === 'string') {
+        if (value.length === 0) {
+            throw new ValidationError(fieldPath, 'non-empty numeric string', '""');
+        }
+        const num = Number(value);
+        if (Number.isNaN(num)) {
+            throw new ValidationError(fieldPath, 'valid numeric string', value);
+        }
+        return;
+    }
+    throw new ValidationError(fieldPath, 'number or numeric string', value);
+}
+/**
+ * Validate and convert a numeric value to string for DAML.
+ * Returns null for undefined/null values.
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @returns The numeric value as a string, or null
+ */
+function validateOptionalNumeric(value, fieldPath) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    validateRequiredNumeric(value, fieldPath);
+    return typeof value === 'number' ? value.toString() : value;
+}
+/**
+ * Validate that a numeric value is within a range (inclusive).
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @param min - Minimum allowed value
+ * @param max - Maximum allowed value
+ * @throws {ValidationError} if the value is outside the range
+ */
+function validateNumericRange(value, fieldPath, min, max) {
+    const num = typeof value === 'string' ? Number(value) : value;
+    if (num < min || num > max) {
+        throw new ValidationError(fieldPath, `number between ${min} and ${max}`, num);
+    }
+}
+/**
+ * Validate that a numeric value is positive (> 0).
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @throws {ValidationError} if the value is not positive
+ */
+function validatePositiveNumeric(value, fieldPath) {
+    const num = typeof value === 'string' ? Number(value) : value;
+    if (num <= 0) {
+        throw new ValidationError(fieldPath, 'positive number (> 0)', num);
+    }
+}
+/**
+ * Validate that a numeric value is non-negative (>= 0).
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @throws {ValidationError} if the value is negative
+ */
+function validateNonNegativeNumeric(value, fieldPath) {
+    const num = typeof value === 'string' ? Number(value) : value;
+    if (num < 0) {
+        throw new ValidationError(fieldPath, 'non-negative number (>= 0)', num);
+    }
+}
+// ===== Date Validation =====
+/**
+ * Validate that a value is a valid ISO date string (YYYY-MM-DD).
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @throws {ValidationError} if the value is not a valid ISO date string
+ */
+function validateRequiredDate(value, fieldPath) {
+    if (typeof value !== 'string') {
+        throw new ValidationError(fieldPath, 'ISO date string (YYYY-MM-DD)', value);
+    }
+    const match = /^\d{4}-\d{2}-\d{2}$/.exec(value);
+    if (!match) {
+        throw new ValidationError(fieldPath, 'ISO date string (YYYY-MM-DD)', value);
+    }
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        throw new ValidationError(fieldPath, 'valid date', value);
+    }
+}
+/**
+ * Validate that a value is a valid ISO date string or undefined/null.
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @returns The date string or null
+ */
+function validateOptionalDate(value, fieldPath) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    validateRequiredDate(value, fieldPath);
+    return value;
+}
+// ===== Enum Validation =====
+/**
+ * Validate that a value is one of the allowed enum values.
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @param allowedValues - Array of allowed values
+ * @throws {ValidationError} if the value is not in the allowed list
+ */
+function validateEnum(value, fieldPath, allowedValues) {
+    if (typeof value !== 'string') {
+        throw new ValidationError(fieldPath, `one of: ${allowedValues.join(', ')}`, value);
+    }
+    if (!allowedValues.includes(value)) {
+        throw new ValidationError(fieldPath, `one of: ${allowedValues.join(', ')}`, value);
+    }
+}
+/**
+ * Validate an optional enum value.
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @param allowedValues - Array of allowed values
+ * @returns The value or null
+ */
+function validateOptionalEnum(value, fieldPath, allowedValues) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    validateEnum(value, fieldPath, allowedValues);
+    return value;
+}
+// ===== Array Validation =====
+/**
+ * Validate that a value is a non-empty array.
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @throws {ValidationError} if the value is not a non-empty array
+ */
+function validateRequiredArray(value, fieldPath) {
+    if (!Array.isArray(value)) {
+        throw new ValidationError(fieldPath, 'non-empty array', value);
+    }
+    if (value.length === 0) {
+        throw new ValidationError(fieldPath, 'non-empty array', '[]');
+    }
+}
+/**
+ * Validate an optional array (can be undefined/null or array with items).
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @returns The array or null
+ */
+function validateOptionalArray(value, fieldPath) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (!Array.isArray(value)) {
+        throw new ValidationError(fieldPath, 'array, undefined, or null', value);
+    }
+    return value.length > 0 ? value : null;
+}
+// ===== Object Validation =====
+/**
+ * Validate that a value is a non-null object.
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @throws {ValidationError} if the value is not a non-null object
+ */
+function validateRequiredObject(value, fieldPath) {
+    if (typeof value !== 'object' || value === null) {
+        throw new ValidationError(fieldPath, 'non-null object', value);
+    }
+}
+/**
+ * Validate an optional object.
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @returns The object or null
+ */
+function validateOptionalObject(value, fieldPath) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    validateRequiredObject(value, fieldPath);
+    return value;
+}
+/**
+ * Validate that a value is a valid Monetary object.
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @throws {ValidationError} if the value is not a valid Monetary object
+ */
+function validateRequiredMonetary(value, fieldPath) {
+    validateRequiredObject(value, fieldPath);
+    const obj = value;
+    validateRequiredNumeric(obj.amount, `${fieldPath}.amount`);
+    validateRequiredString(obj.currency, `${fieldPath}.currency`);
+}
+/**
+ * Validate an optional Monetary object.
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @returns The validated monetary object or null
+ */
+function validateOptionalMonetary(value, fieldPath) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    validateRequiredMonetary(value, fieldPath);
+    const obj = value;
+    return {
+        amount: typeof obj.amount === 'number' ? obj.amount.toString() : obj.amount,
+        currency: obj.currency,
+    };
+}
+// ===== Contract ID Validation =====
+/**
+ * Validate that a value is a valid Canton contract ID.
+ * Contract IDs are typically in format: hexdigits:hexdigits or just hexdigits.
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @throws {ValidationError} if the value is not a valid contract ID
+ */
+function validateContractId(value, fieldPath) {
+    validateRequiredString(value, fieldPath);
+    // Contract IDs should be non-empty strings; the exact format is flexible
+    // but they should not contain whitespace
+    if (/\s/.test(value)) {
+        throw new ValidationError(fieldPath, 'contract ID without whitespace', value);
+    }
+}
+// ===== Party ID Validation =====
+/**
+ * Validate that a value is a valid Canton party ID.
+ * Party IDs typically follow the format: identifier::fingerprint
+ *
+ * @param value - The value to validate
+ * @param fieldPath - Dot-notation path for error messages
+ * @throws {ValidationError} if the value is not a valid party ID
+ */
+function validatePartyId(value, fieldPath) {
+    validateRequiredString(value, fieldPath);
+    // Basic validation - party IDs should not contain whitespace
+    if (/\s/.test(value)) {
+        throw new ValidationError(fieldPath, 'party ID without whitespace', value);
+    }
+}
+// ===== Composite Validators =====
+/**
+ * Validate all items in an array using a validator function.
+ *
+ * @param items - The array of items to validate
+ * @param fieldPath - Base path for error messages
+ * @param itemValidator - Function to validate each item
+ */
+function validateArrayItems(items, fieldPath, itemValidator) {
+    for (let i = 0; i < items.length; i++) {
+        itemValidator(items[i], `${fieldPath}[${i}]`);
+    }
+}
+/**
+ * Create a composite validator that runs multiple validations.
+ *
+ * @example
+ *   ```typescript
+ *   const validateStakeholder = createValidator<OcfStakeholder>(
+ *     (value, path) => {
+ *       validateRequiredString(value.id, `${path}.id`);
+ *       validateRequiredObject(value.name, `${path}.name`);
+ *       validateRequiredString(value.name?.legal_name, `${path}.name.legal_name`);
+ *       validateEnum(value.stakeholder_type, `${path}.stakeholder_type`, ['INDIVIDUAL', 'INSTITUTION']);
+ *     }
+ *   );
+ *
+ *   validateStakeholder(data, 'stakeholder');
+ *   ```
+ */
+function createValidator(validatorFn) {
+    return (value, fieldPath) => {
+        validateRequiredObject(value, fieldPath);
+        validatorFn(value, fieldPath);
+    };
+}
+//# sourceMappingURL=validation.js.map

package/dist/utils/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-captable-protocol/canton",
-  "version": "0.2.145",
+  "version": "0.2.147",
   "description": "A TypeScript SDK for interacting with the Open CapTable Protocol (OCP) Factory contract on Canton blockchain",
   "license": "MIT",
   "main": "dist/index.js",