@ottochain/sdk 0.2.0

package/dist/cjs/types.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * OttoChain Type Aliases
+ *
+ * Semantic type aliases for common primitive types.
+ * These match the wire format used by the metagraph's JSON Logic engine.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidFiberId = exports.isValidAddress = void 0;
+/**
+ * Validate a DAG address format.
+ */
+function isValidAddress(value) {
+    return /^DAG[0-9a-zA-Z]+$/.test(value);
+}
+exports.isValidAddress = isValidAddress;
+/**
+ * Validate a UUID format.
+ */
+function isValidFiberId(value) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);
+}
+exports.isValidFiberId = isValidFiberId;

package/dist/cjs/validation.js

@@ -0,0 +1,312 @@
+"use strict";
+/**
+ * Input Validation with Zod Schemas
+ *
+ * Provides runtime validation for SDK types using Zod.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assert = exports.safeParse = exports.validateKeyPair = exports.validateAddress = exports.validatePublicKey = exports.validatePrivateKey = exports.validate = exports.CompleteContractRequestSchema = exports.AcceptContractRequestSchema = exports.ProposeContractRequestSchema = exports.ContractTermsSchema = exports.PlatformLinkSchema = exports.AgentIdentityRegistrationSchema = exports.TransferParamsSchema = exports.CurrencyTransactionSchema = exports.CurrencyTransactionValueSchema = exports.TransactionReferenceSchema = exports.SignedSchema = exports.SignatureProofSchema = exports.KeyPairSchema = exports.PublicKeySchema = exports.PrivateKeySchema = exports.DagAddressSchema = void 0;
+const zod_1 = require("zod");
+const errors_js_1 = require("./errors.js");
+// ============================================================================
+// Primitive Schemas
+// ============================================================================
+/**
+ * Schema for a hex string of specific length
+ */
+const hexString = (length) => {
+    let schema = zod_1.z.string().regex(/^[0-9a-fA-F]+$/, 'Must be a valid hex string');
+    if (length !== undefined) {
+        schema = schema.length(length, `Must be exactly ${length} characters`);
+    }
+    return schema;
+};
+/**
+ * Schema for a DAG address
+ */
+exports.DagAddressSchema = zod_1.z
+    .string()
+    .regex(/^DAG[0-9][a-zA-Z0-9]{36}$/, 'Must be a valid DAG address');
+// ============================================================================
+// Core Type Schemas
+// ============================================================================
+/**
+ * Schema for a private key (64-character hex string)
+ */
+exports.PrivateKeySchema = hexString(64).describe('Private key in hex format (64 characters)');
+/**
+ * Schema for a public key (128 or 130 character hex string)
+ */
+exports.PublicKeySchema = zod_1.z
+    .string()
+    .regex(/^(04)?[0-9a-fA-F]{128}$/, 'Must be a valid public key (128 or 130 hex chars)')
+    .describe('Public key in hex format (with optional 04 prefix)');
+/**
+ * Schema for a KeyPair
+ */
+exports.KeyPairSchema = zod_1.z.object({
+    /** Private key in hex format */
+    privateKey: exports.PrivateKeySchema,
+    /** Public key in hex format (uncompressed, with 04 prefix) */
+    publicKey: exports.PublicKeySchema,
+    /** DAG address derived from the public key */
+    address: exports.DagAddressSchema,
+});
+/**
+ * Schema for a SignatureProof
+ */
+exports.SignatureProofSchema = zod_1.z.object({
+    /** Public key hex (uncompressed, without 04 prefix) - 128 characters */
+    id: hexString(128),
+    /** DER-encoded ECDSA signature in hex format */
+    signature: hexString(),
+});
+/**
+ * Schema for a Signed object (generic)
+ */
+const SignedSchema = (valueSchema) => zod_1.z.object({
+    value: valueSchema,
+    proofs: zod_1.z.array(exports.SignatureProofSchema).min(1, 'At least one proof is required'),
+});
+exports.SignedSchema = SignedSchema;
+// ============================================================================
+// Transaction Schemas
+// ============================================================================
+/**
+ * Schema for TransactionReference
+ */
+exports.TransactionReferenceSchema = zod_1.z.object({
+    ordinal: zod_1.z.number().int().min(0),
+    hash: zod_1.z.string().min(1),
+});
+/**
+ * Schema for CurrencyTransactionValue
+ */
+exports.CurrencyTransactionValueSchema = zod_1.z.object({
+    source: exports.DagAddressSchema,
+    destination: exports.DagAddressSchema,
+    amount: zod_1.z.number().int().positive('Amount must be positive'),
+    fee: zod_1.z.number().int().min(0).default(0),
+});
+/**
+ * Schema for CurrencyTransaction
+ */
+exports.CurrencyTransactionSchema = zod_1.z.object({
+    value: exports.CurrencyTransactionValueSchema,
+    parent: exports.TransactionReferenceSchema,
+});
+/**
+ * Schema for TransferParams
+ */
+exports.TransferParamsSchema = zod_1.z.object({
+    from: exports.DagAddressSchema,
+    to: exports.DagAddressSchema,
+    amount: zod_1.z.number().positive('Amount must be positive'),
+    fee: zod_1.z.number().min(0).optional().default(0),
+});
+// ============================================================================
+// Identity Schemas
+// ============================================================================
+/**
+ * Schema for AgentIdentity registration
+ */
+exports.AgentIdentityRegistrationSchema = zod_1.z.object({
+    /** Public key in hex format */
+    publicKey: exports.PublicKeySchema,
+    /** Display name for the agent */
+    displayName: zod_1.z.string().min(1).max(64),
+    /** Initial reputation (default: 10) */
+    reputation: zod_1.z.number().int().min(0).optional().default(10),
+});
+/**
+ * Schema for PlatformLink
+ */
+exports.PlatformLinkSchema = zod_1.z.object({
+    platform: zod_1.z.enum(['DISCORD', 'TELEGRAM', 'TWITTER', 'GITHUB', 'CUSTOM']),
+    platformUserId: zod_1.z.string().min(1),
+    platformUsername: zod_1.z.string().min(1),
+    verified: zod_1.z.boolean().optional().default(false),
+});
+// ============================================================================
+// Contract Schemas
+// ============================================================================
+/**
+ * Schema for contract terms (flexible structure)
+ */
+exports.ContractTermsSchema = zod_1.z.record(zod_1.z.unknown());
+/**
+ * Schema for ProposeContractRequest
+ */
+exports.ProposeContractRequestSchema = zod_1.z.object({
+    /** Proposer's DAG address */
+    proposer: exports.DagAddressSchema,
+    /** Counterparty's DAG address */
+    counterparty: exports.DagAddressSchema,
+    /** Contract terms */
+    terms: exports.ContractTermsSchema,
+    /** Human-readable description */
+    description: zod_1.z.string().min(1).max(1000),
+});
+/**
+ * Schema for AcceptContractRequest
+ */
+exports.AcceptContractRequestSchema = zod_1.z.object({
+    /** Contract ID to accept */
+    contractId: zod_1.z.string().min(1),
+    /** Acceptor's DAG address */
+    acceptor: exports.DagAddressSchema,
+});
+/**
+ * Schema for CompleteContractRequest
+ */
+exports.CompleteContractRequestSchema = zod_1.z.object({
+    /** Contract ID to complete */
+    contractId: zod_1.z.string().min(1),
+    /** Completer's DAG address */
+    completer: exports.DagAddressSchema,
+    /** Proof of completion */
+    proof: zod_1.z.string().min(1),
+});
+// ============================================================================
+// Validation Helpers
+// ============================================================================
+/**
+ * Validate data against a Zod schema
+ *
+ * @param schema - Zod schema to validate against
+ * @param data - Data to validate
+ * @param fieldName - Optional field name for error context
+ * @returns Validated and typed data
+ * @throws {ValidationError} If validation fails
+ *
+ * @example
+ * ```typescript
+ * const keyPair = validate(KeyPairSchema, inputData, 'keyPair');
+ * // keyPair is now typed as ValidatedKeyPair
+ * ```
+ */
+function validate(schema, data, fieldName) {
+    const result = schema.safeParse(data);
+    if (!result.success) {
+        const issues = result.error.issues;
+        const firstIssue = issues[0];
+        // Build a helpful error message
+        const path = firstIssue.path.length > 0 ? firstIssue.path.join('.') : fieldName || 'input';
+        const message = `Validation failed for '${path}': ${firstIssue.message}`;
+        throw new errors_js_1.ValidationError(message, {
+            field: path,
+            value: data,
+            details: {
+                issues: issues.map((issue) => ({
+                    path: issue.path.join('.'),
+                    message: issue.message,
+                    code: issue.code,
+                })),
+            },
+        });
+    }
+    return result.data;
+}
+exports.validate = validate;
+/**
+ * Validate a private key
+ *
+ * @param privateKey - Private key to validate
+ * @returns Validated private key
+ * @throws {ValidationError} If validation fails
+ */
+function validatePrivateKey(privateKey) {
+    return validate(exports.PrivateKeySchema, privateKey, 'privateKey');
+}
+exports.validatePrivateKey = validatePrivateKey;
+/**
+ * Validate a public key
+ *
+ * @param publicKey - Public key to validate
+ * @returns Validated public key
+ * @throws {ValidationError} If validation fails
+ */
+function validatePublicKey(publicKey) {
+    return validate(exports.PublicKeySchema, publicKey, 'publicKey');
+}
+exports.validatePublicKey = validatePublicKey;
+/**
+ * Validate a DAG address
+ *
+ * @param address - Address to validate
+ * @returns Validated address
+ * @throws {ValidationError} If validation fails
+ */
+function validateAddress(address) {
+    return validate(exports.DagAddressSchema, address, 'address');
+}
+exports.validateAddress = validateAddress;
+/**
+ * Validate a KeyPair
+ *
+ * @param keyPair - KeyPair to validate
+ * @returns Validated KeyPair
+ * @throws {ValidationError} If validation fails
+ */
+function validateKeyPair(keyPair) {
+    return validate(exports.KeyPairSchema, keyPair, 'keyPair');
+}
+exports.validateKeyPair = validateKeyPair;
+/**
+ * Safe validation that returns a result object instead of throwing
+ *
+ * @param schema - Zod schema to validate against
+ * @param data - Data to validate
+ * @returns Object with success status and data or error
+ *
+ * @example
+ * ```typescript
+ * const result = safeParse(KeyPairSchema, inputData);
+ * if (result.success) {
+ *   console.log(result.data.address);
+ * } else {
+ *   console.log(result.error.message);
+ * }
+ * ```
+ */
+function safeParse(schema, data) {
+    const result = schema.safeParse(data);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    const issues = result.error.issues;
+    const firstIssue = issues[0];
+    const path = firstIssue.path.length > 0 ? firstIssue.path.join('.') : 'input';
+    const message = `Validation failed for '${path}': ${firstIssue.message}`;
+    return {
+        success: false,
+        error: new errors_js_1.ValidationError(message, {
+            field: path,
+            value: data,
+            details: {
+                issues: issues.map((issue) => ({
+                    path: issue.path.join('.'),
+                    message: issue.message,
+                    code: issue.code,
+                })),
+            },
+        }),
+    };
+}
+exports.safeParse = safeParse;
+/**
+ * Assert that a condition is true, throwing ValidationError if not
+ *
+ * @param condition - Condition to check
+ * @param message - Error message if condition is false
+ * @param field - Optional field name for context
+ * @throws {ValidationError} If condition is false
+ */
+function assert(condition, message, field) {
+    if (!condition) {
+        throw new errors_js_1.ValidationError(message, { field });
+    }
+}
+exports.assert = assert;

package/dist/errors.d.ts

@@ -0,0 +1,221 @@
+/**
+ * Custom Error Classes for OttoChain SDK
+ *
+ * Provides structured error handling with error codes and causes.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Error codes for OttoChain SDK errors
+ */
+export declare enum ErrorCode {
+    /** Unknown or unclassified error */
+    UNKNOWN = "UNKNOWN",
+    /** Network/HTTP connection failure */
+    NETWORK_ERROR = "NETWORK_ERROR",
+    /** Request timeout */
+    NETWORK_TIMEOUT = "NETWORK_TIMEOUT",
+    /** Input validation failed */
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    /** Invalid private key format */
+    INVALID_PRIVATE_KEY = "INVALID_PRIVATE_KEY",
+    /** Invalid public key format */
+    INVALID_PUBLIC_KEY = "INVALID_PUBLIC_KEY",
+    /** Invalid DAG address format */
+    INVALID_ADDRESS = "INVALID_ADDRESS",
+    /** Signature creation failed */
+    SIGNING_ERROR = "SIGNING_ERROR",
+    /** Signature verification failed */
+    VERIFICATION_ERROR = "VERIFICATION_ERROR",
+    /** Transaction rejected by network */
+    TRANSACTION_REJECTED = "TRANSACTION_REJECTED",
+    /** Transaction not found */
+    TRANSACTION_NOT_FOUND = "TRANSACTION_NOT_FOUND",
+    /** Invalid transaction format */
+    INVALID_TRANSACTION = "INVALID_TRANSACTION"
+}
+/**
+ * Base error class for all OttoChain SDK errors
+ *
+ * Provides consistent error structure with:
+ * - Error code for programmatic handling
+ * - Human-readable message
+ * - Optional cause for error chaining
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await signTransaction(data, invalidKey);
+ * } catch (error) {
+ *   if (error instanceof OttoChainError) {
+ *     console.log(error.code);    // 'INVALID_PRIVATE_KEY'
+ *     console.log(error.message); // 'Invalid private key format'
+ *   }
+ * }
+ * ```
+ */
+export declare class OttoChainError extends Error {
+    /** Error code for programmatic handling */
+    readonly code: ErrorCode;
+    /** Original error that caused this error */
+    readonly cause?: Error;
+    constructor(code: ErrorCode, message: string, cause?: Error);
+    /**
+     * Create a string representation of the error
+     */
+    toString(): string;
+    /**
+     * Convert error to a plain object for logging/serialization
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Error thrown when network operations fail
+ *
+ * Covers HTTP failures, connection errors, and timeouts.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.postTransaction(signed);
+ * } catch (error) {
+ *   if (error instanceof NetworkError) {
+ *     console.log(error.statusCode); // 503
+ *     console.log(error.responseBody); // '{"error": "Service unavailable"}'
+ *   }
+ * }
+ * ```
+ */
+export declare class NetworkError extends OttoChainError {
+    /** HTTP status code if applicable */
+    readonly statusCode?: number;
+    /** Response body if available */
+    readonly responseBody?: string;
+    constructor(message: string, statusCode?: number, responseBody?: string, cause?: Error);
+    /**
+     * Create a timeout error
+     */
+    static timeout(timeoutMs: number): NetworkError;
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Error thrown when input validation fails
+ *
+ * Used when function parameters don't meet expected format or constraints.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const keyPair = keyPairFromPrivateKey('invalid');
+ * } catch (error) {
+ *   if (error instanceof ValidationError) {
+ *     console.log(error.field); // 'privateKey'
+ *     console.log(error.value); // 'invalid'
+ *   }
+ * }
+ * ```
+ */
+export declare class ValidationError extends OttoChainError {
+    /** Field that failed validation */
+    readonly field?: string;
+    /** Value that failed validation (sanitized) */
+    readonly value?: unknown;
+    /** Validation details/constraints */
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, options?: {
+        field?: string;
+        value?: unknown;
+        details?: Record<string, unknown>;
+        cause?: Error;
+    });
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Error thrown when cryptographic signing operations fail
+ *
+ * Covers key derivation, signature creation, and related crypto operations.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const signature = await signHash(hash, privateKey);
+ * } catch (error) {
+ *   if (error instanceof SigningError) {
+ *     console.log(error.operation); // 'sign'
+ *   }
+ * }
+ * ```
+ */
+export declare class SigningError extends OttoChainError {
+    /** The operation that failed */
+    readonly operation?: string;
+    constructor(message: string, options?: {
+        operation?: string;
+        cause?: Error;
+    });
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Error thrown when transaction operations fail
+ *
+ * Used when transactions are rejected, not found, or invalid.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.postTransaction(signed);
+ * } catch (error) {
+ *   if (error instanceof TransactionError) {
+ *     console.log(error.transactionHash); // 'abc123...'
+ *     console.log(error.rejectionReason); // 'Insufficient balance'
+ *   }
+ * }
+ * ```
+ */
+export declare class TransactionError extends OttoChainError {
+    /** Transaction hash if available */
+    readonly transactionHash?: string;
+    /** Reason for rejection if available */
+    readonly rejectionReason?: string;
+    constructor(code: ErrorCode, message: string, options?: {
+        transactionHash?: string;
+        rejectionReason?: string;
+        cause?: Error;
+    });
+    /**
+     * Create a transaction rejected error
+     */
+    static rejected(reason: string, transactionHash?: string): TransactionError;
+    /**
+     * Create a transaction not found error
+     */
+    static notFound(transactionHash: string): TransactionError;
+    /**
+     * Create an invalid transaction error
+     */
+    static invalid(message: string, cause?: Error): TransactionError;
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Check if an error is an OttoChain error with a specific code
+ *
+ * @param error - Error to check
+ * @param code - Error code to match
+ * @returns True if error matches the code
+ *
+ * @example
+ * ```typescript
+ * if (isErrorCode(error, ErrorCode.NETWORK_TIMEOUT)) {
+ *   // Retry the request
+ * }
+ * ```
+ */
+export declare function isErrorCode(error: unknown, code: ErrorCode): boolean;
+/**
+ * Wrap an unknown error in an OttoChainError
+ *
+ * @param error - Error to wrap
+ * @param defaultMessage - Default message if error has no message
+ * @returns OttoChainError wrapping the original error
+ */
+export declare function wrapError(error: unknown, defaultMessage?: string): OttoChainError;