@0xmonaco/types 0.7.7 → 0.7.8

package/dist/validation/common.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Common Validation Utilities
+ *
+ * Shared utilities for runtime validation across all SDK modules.
+ * These utilities work with any Zod schema and provide consistent
+ * error handling throughout the SDK.
+ */
+import type { z } from "zod";
+/**
+ * Validation error class for user-friendly error messages.
+ *
+ * Wraps Zod validation errors to provide better error formatting and
+ * structured error access for API consumers. This error is thrown when
+ * validation fails on any SDK parameters.
+ *
+ * **Features:**
+ * - Human-readable error message with field paths
+ * - Access to raw Zod issues for detailed error handling
+ * - Structured error object via `getErrors()` method
+ *
+ * **Example Usage:**
+ * ```typescript
+ * import { validate, PlaceLimitOrderSchema } from '@0xmonaco/types';
+ *
+ * try {
+ *   const validated = validate(PlaceLimitOrderSchema, {
+ *     tradingPairId: "invalid-uuid",
+ *     side: "BUY",
+ *     quantity: "-10", // Invalid: negative
+ *     price: "100"
+ *   });
+ * } catch (error) {
+ *   if (error instanceof ValidationError) {
+ *     // Human-readable message
+ *     console.log(error.message);
+ *     // "Validation failed:
+ *     //   - tradingPairId: Invalid uuid
+ *     //   - quantity: Number must be greater than 0"
+ *
+ *     // Structured errors for form validation
+ *     const errors = error.getErrors();
+ *     console.log(errors);
+ *     // {
+ *     //   "tradingPairId": "Invalid uuid",
+ *     //   "quantity": "Number must be greater than 0"
+ *     // }
+ *
+ *     // Raw Zod issues for advanced handling
+ *     console.log(error.issues);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link validate} - Helper function that throws ValidationError
+ */
+export declare class ValidationError extends Error {
+    /**
+     * Array of Zod validation issues containing detailed error information.
+     * Each issue includes the field path, error code, and message.
+     */
+    readonly issues: z.core.$ZodIssue[];
+    /**
+     * Creates a new ValidationError from a Zod validation error.
+     *
+     * Automatically formats all validation issues into a human-readable
+     * message and stores the raw issues for programmatic access.
+     *
+     * @param zodError - The Zod validation error to wrap
+     *
+     * @example
+     * ```typescript
+     * const result = schema.safeParse(data);
+     * if (!result.success) {
+     *   throw new ValidationError(result.error);
+     * }
+     * ```
+     */
+    constructor(zodError: z.ZodError);
+    /**
+     * Get validation errors as a structured object for easy field-level error display.
+     *
+     * Converts the array of Zod issues into a simple key-value object where
+     * keys are field paths (dot-notation) and values are error messages.
+     * Root-level errors (no path) are stored under the "root" key.
+     *
+     * **Use Cases:**
+     * - Form validation (map errors to input fields)
+     * - API error responses (structured JSON)
+     * - Error aggregation and reporting
+     *
+     * @returns Object mapping field paths to error messages
+     *
+     * @example
+     * ```typescript
+     * // Single field errors
+     * error.getErrors();
+     * // { "price": "Number must be greater than 0" }
+     *
+     * // Multiple field errors
+     * error.getErrors();
+     * // {
+     * //   "tradingPairId": "Invalid uuid",
+     * //   "quantity": "Required",
+     * //   "options.timeInForce": "Invalid enum value"
+     * // }
+     *
+     * // Root-level error (no specific field)
+     * error.getErrors();
+     * // { "root": "At least one field is required" }
+     *
+     * // Use in React form
+     * const errors = validationError.getErrors();
+     * <input error={errors.price} />
+     * ```
+     */
+    getErrors(): Record<string, string>;
+}
+/**
+ * Validates data against a Zod schema and throws user-friendly errors on failure.
+ *
+ * This is a convenience wrapper around Zod's `safeParse` that automatically
+ * throws a {@link ValidationError} with formatted error messages when validation fails.
+ *
+ * **When to Use:**
+ * - Validating user input before API calls
+ * - Runtime type checking for dynamic data
+ * - Ensuring data integrity before processing
+ *
+ * **Error Handling:**
+ * On validation failure, throws {@link ValidationError} which provides:
+ * - Human-readable error message
+ * - Structured errors via `getErrors()`
+ * - Raw Zod issues for advanced handling
+ *
+ * @template T - The expected type after validation
+ * @param schema - Zod schema to validate against
+ * @param data - Data to validate (unknown type for safety)
+ * @returns Validated and typed data
+ * @throws {@link ValidationError} When validation fails
+ *
+ * @example
+ * ```typescript
+ * import { validate, PlaceLimitOrderSchema } from '@0xmonaco/types';
+ *
+ * // Basic validation
+ * try {
+ *   const validatedOrder = validate(PlaceLimitOrderSchema, userInput);
+ *   // validatedOrder is now typed and guaranteed valid
+ *   await sdk.trading.placeLimitOrder(...validatedOrder);
+ * } catch (error) {
+ *   if (error instanceof ValidationError) {
+ *     // Show user-friendly errors
+ *     console.error(error.message);
+ *     const fieldErrors = error.getErrors();
+ *     // Display errors next to form fields
+ *   }
+ * }
+ *
+ * // With custom error handling
+ * function safeValidate<T>(schema: z.ZodSchema<T>, data: unknown) {
+ *   try {
+ *     return { success: true, data: validate(schema, data) };
+ *   } catch (error) {
+ *     if (error instanceof ValidationError) {
+ *       return { success: false, errors: error.getErrors() };
+ *     }
+ *     throw error; // Re-throw unexpected errors
+ *   }
+ * }
+ *
+ * const result = safeValidate(PlaceLimitOrderSchema, input);
+ * if (result.success) {
+ *   // Use result.data
+ * } else {
+ *   // Handle result.errors
+ * }
+ * ```
+ */
+export declare function validate<T>(schema: z.ZodSchema<T>, data: unknown): T;

package/dist/validation/common.js

@@ -0,0 +1,199 @@
+/**
+ * Common Validation Utilities
+ *
+ * Shared utilities for runtime validation across all SDK modules.
+ * These utilities work with any Zod schema and provide consistent
+ * error handling throughout the SDK.
+ */
+/**
+ * Validation error class for user-friendly error messages.
+ *
+ * Wraps Zod validation errors to provide better error formatting and
+ * structured error access for API consumers. This error is thrown when
+ * validation fails on any SDK parameters.
+ *
+ * **Features:**
+ * - Human-readable error message with field paths
+ * - Access to raw Zod issues for detailed error handling
+ * - Structured error object via `getErrors()` method
+ *
+ * **Example Usage:**
+ * ```typescript
+ * import { validate, PlaceLimitOrderSchema } from '@0xmonaco/types';
+ *
+ * try {
+ *   const validated = validate(PlaceLimitOrderSchema, {
+ *     tradingPairId: "invalid-uuid",
+ *     side: "BUY",
+ *     quantity: "-10", // Invalid: negative
+ *     price: "100"
+ *   });
+ * } catch (error) {
+ *   if (error instanceof ValidationError) {
+ *     // Human-readable message
+ *     console.log(error.message);
+ *     // "Validation failed:
+ *     //   - tradingPairId: Invalid uuid
+ *     //   - quantity: Number must be greater than 0"
+ *
+ *     // Structured errors for form validation
+ *     const errors = error.getErrors();
+ *     console.log(errors);
+ *     // {
+ *     //   "tradingPairId": "Invalid uuid",
+ *     //   "quantity": "Number must be greater than 0"
+ *     // }
+ *
+ *     // Raw Zod issues for advanced handling
+ *     console.log(error.issues);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link validate} - Helper function that throws ValidationError
+ */
+export class ValidationError extends Error {
+    /**
+     * Array of Zod validation issues containing detailed error information.
+     * Each issue includes the field path, error code, and message.
+     */
+    issues;
+    /**
+     * Creates a new ValidationError from a Zod validation error.
+     *
+     * Automatically formats all validation issues into a human-readable
+     * message and stores the raw issues for programmatic access.
+     *
+     * @param zodError - The Zod validation error to wrap
+     *
+     * @example
+     * ```typescript
+     * const result = schema.safeParse(data);
+     * if (!result.success) {
+     *   throw new ValidationError(result.error);
+     * }
+     * ```
+     */
+    constructor(zodError) {
+        const messages = zodError.issues.map((issue) => {
+            const path = issue.path.join(".");
+            return `${path ? `${path}: ` : ""}${issue.message}`;
+        });
+        super(`Validation failed:\n  - ${messages.join("\n  - ")}`);
+        this.name = "ValidationError";
+        this.issues = zodError.issues;
+    }
+    /**
+     * Get validation errors as a structured object for easy field-level error display.
+     *
+     * Converts the array of Zod issues into a simple key-value object where
+     * keys are field paths (dot-notation) and values are error messages.
+     * Root-level errors (no path) are stored under the "root" key.
+     *
+     * **Use Cases:**
+     * - Form validation (map errors to input fields)
+     * - API error responses (structured JSON)
+     * - Error aggregation and reporting
+     *
+     * @returns Object mapping field paths to error messages
+     *
+     * @example
+     * ```typescript
+     * // Single field errors
+     * error.getErrors();
+     * // { "price": "Number must be greater than 0" }
+     *
+     * // Multiple field errors
+     * error.getErrors();
+     * // {
+     * //   "tradingPairId": "Invalid uuid",
+     * //   "quantity": "Required",
+     * //   "options.timeInForce": "Invalid enum value"
+     * // }
+     *
+     * // Root-level error (no specific field)
+     * error.getErrors();
+     * // { "root": "At least one field is required" }
+     *
+     * // Use in React form
+     * const errors = validationError.getErrors();
+     * <input error={errors.price} />
+     * ```
+     */
+    getErrors() {
+        const errors = {};
+        for (const issue of this.issues) {
+            const path = issue.path.join(".");
+            errors[path || "root"] = issue.message;
+        }
+        return errors;
+    }
+}
+/**
+ * Validates data against a Zod schema and throws user-friendly errors on failure.
+ *
+ * This is a convenience wrapper around Zod's `safeParse` that automatically
+ * throws a {@link ValidationError} with formatted error messages when validation fails.
+ *
+ * **When to Use:**
+ * - Validating user input before API calls
+ * - Runtime type checking for dynamic data
+ * - Ensuring data integrity before processing
+ *
+ * **Error Handling:**
+ * On validation failure, throws {@link ValidationError} which provides:
+ * - Human-readable error message
+ * - Structured errors via `getErrors()`
+ * - Raw Zod issues for advanced handling
+ *
+ * @template T - The expected type after validation
+ * @param schema - Zod schema to validate against
+ * @param data - Data to validate (unknown type for safety)
+ * @returns Validated and typed data
+ * @throws {@link ValidationError} When validation fails
+ *
+ * @example
+ * ```typescript
+ * import { validate, PlaceLimitOrderSchema } from '@0xmonaco/types';
+ *
+ * // Basic validation
+ * try {
+ *   const validatedOrder = validate(PlaceLimitOrderSchema, userInput);
+ *   // validatedOrder is now typed and guaranteed valid
+ *   await sdk.trading.placeLimitOrder(...validatedOrder);
+ * } catch (error) {
+ *   if (error instanceof ValidationError) {
+ *     // Show user-friendly errors
+ *     console.error(error.message);
+ *     const fieldErrors = error.getErrors();
+ *     // Display errors next to form fields
+ *   }
+ * }
+ *
+ * // With custom error handling
+ * function safeValidate<T>(schema: z.ZodSchema<T>, data: unknown) {
+ *   try {
+ *     return { success: true, data: validate(schema, data) };
+ *   } catch (error) {
+ *     if (error instanceof ValidationError) {
+ *       return { success: false, errors: error.getErrors() };
+ *     }
+ *     throw error; // Re-throw unexpected errors
+ *   }
+ * }
+ *
+ * const result = safeValidate(PlaceLimitOrderSchema, input);
+ * if (result.success) {
+ *   // Use result.data
+ * } else {
+ *   // Handle result.errors
+ * }
+ * ```
+ */
+export function validate(schema, data) {
+    const result = schema.safeParse(data);
+    if (!result.success) {
+        throw new ValidationError(result.error);
+    }
+    return result.data;
+}

package/dist/validation/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Validation Schemas
+ *
+ * Runtime validation using Zod for all SDK inputs.
+ * Catches errors before making API calls.
+ *
+ * **Shared Utilities:**
+ * - {@link ValidationError} - User-friendly validation error class
+ * - {@link validate} - Helper function for schema validation
+ *
+ * **Schema Modules:**
+ * - Trading schemas (orders, trading pairs)
+ * - Vault schemas (deposits, withdrawals)
+ * - Market schemas (trading pairs, candlesticks)
+ */
+export * from "./common.js";
+export * from "./margin-accounts.js";
+export * from "./market.js";
+export * from "./positions.js";
+export * from "./profile.js";
+export * from "./trading.js";
+export * from "./vault.js";

package/dist/validation/index.js

@@ -0,0 +1,24 @@
+/**
+ * Validation Schemas
+ *
+ * Runtime validation using Zod for all SDK inputs.
+ * Catches errors before making API calls.
+ *
+ * **Shared Utilities:**
+ * - {@link ValidationError} - User-friendly validation error class
+ * - {@link validate} - Helper function for schema validation
+ *
+ * **Schema Modules:**
+ * - Trading schemas (orders, trading pairs)
+ * - Vault schemas (deposits, withdrawals)
+ * - Market schemas (trading pairs, candlesticks)
+ */
+// Export validation utilities
+export * from "./common.js";
+export * from "./margin-accounts.js";
+export * from "./market.js";
+export * from "./positions.js";
+// Export module-specific schemas
+export * from "./profile.js";
+export * from "./trading.js";
+export * from "./vault.js";

package/dist/validation/margin-accounts.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Margin Account API Validation Schemas
+ */
+import { z } from "zod";
+export declare const ListMarginAccountsSchema: z.ZodObject<{
+    page: z.ZodOptional<z.ZodNumber>;
+    page_size: z.ZodOptional<z.ZodNumber>;
+    state: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const CreateMarginAccountSchema: z.ZodOptional<z.ZodObject<{
+    label: z.ZodOptional<z.ZodString>;
+    collateralAsset: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+export declare const GetMarginAccountSummarySchema: z.ZodObject<{
+    marginAccountId: z.ZodUUID;
+}, z.core.$strip>;
+export declare const GetAvailableCollateralSchema: z.ZodOptional<z.ZodObject<{
+    asset: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+export declare const TransferCollateralSchema: z.ZodObject<{
+    marginAccountId: z.ZodUUID;
+    request: z.ZodObject<{
+        asset: z.ZodString;
+        amount: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const GetMarginAccountMovementsSchema: z.ZodObject<{
+    page: z.ZodOptional<z.ZodNumber>;
+    page_size: z.ZodOptional<z.ZodNumber>;
+    marginAccountId: z.ZodUUID;
+    movement_type: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const SimulateOrderRiskSchema: z.ZodObject<{
+    marginAccountId: z.ZodUUID;
+    request: z.ZodObject<{
+        tradingPairId: z.ZodUUID;
+        side: z.ZodEnum<{
+            BUY: "BUY";
+            SELL: "SELL";
+        }>;
+        positionSide: z.ZodEnum<{
+            LONG: "LONG";
+            SHORT: "SHORT";
+            NONE: "NONE";
+        }>;
+        orderType: z.ZodEnum<{
+            LIMIT: "LIMIT";
+            MARKET: "MARKET";
+        }>;
+        price: z.ZodOptional<z.ZodString>;
+        quantity: z.ZodString;
+        leverage: z.ZodString;
+        reduceOnly: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+}, z.core.$strip>;

package/dist/validation/margin-accounts.js

@@ -0,0 +1,59 @@
+/**
+ * Margin Account API Validation Schemas
+ */
+import { z } from "zod";
+import { OrderSideSchema, OrderTypeSchema, PositionSideSchema, PositiveDecimalStringSchema, UUIDSchema } from "./trading";
+const PaginationSchema = z.object({
+    page: z.number().int().min(1, "Page must be at least 1").optional(),
+    page_size: z.number().int().min(1, "Page size must be at least 1").max(100, "Page size cannot exceed 100").optional(),
+});
+export const ListMarginAccountsSchema = PaginationSchema.extend({
+    state: z.string().trim().min(1, "State cannot be empty").optional(),
+});
+export const CreateMarginAccountSchema = z
+    .object({
+    label: z.string().trim().min(1, "Label cannot be empty").optional(),
+    collateralAsset: z.string().trim().min(1, "Collateral asset cannot be empty").optional(),
+})
+    .optional();
+export const GetMarginAccountSummarySchema = z.object({
+    marginAccountId: UUIDSchema,
+});
+export const GetAvailableCollateralSchema = z
+    .object({
+    asset: z.string().trim().min(1, "Asset cannot be empty").optional(),
+})
+    .optional();
+export const TransferCollateralSchema = z.object({
+    marginAccountId: UUIDSchema,
+    request: z.object({
+        asset: z.string().trim().min(1, "Asset cannot be empty"),
+        amount: PositiveDecimalStringSchema,
+    }),
+});
+export const GetMarginAccountMovementsSchema = PaginationSchema.extend({
+    marginAccountId: UUIDSchema,
+    movement_type: z.string().trim().min(1, "Movement type cannot be empty").optional(),
+});
+export const SimulateOrderRiskSchema = z
+    .object({
+    marginAccountId: UUIDSchema,
+    request: z.object({
+        tradingPairId: UUIDSchema,
+        side: OrderSideSchema,
+        positionSide: PositionSideSchema,
+        orderType: OrderTypeSchema,
+        price: PositiveDecimalStringSchema.optional(),
+        quantity: PositiveDecimalStringSchema,
+        leverage: PositiveDecimalStringSchema,
+        reduceOnly: z.boolean().optional(),
+    }),
+})
+    .refine((data) => data.request.orderType !== "LIMIT" || data.request.price !== undefined, {
+    message: "price is required for LIMIT risk simulations",
+    path: ["request", "price"],
+})
+    .refine((data) => data.request.orderType !== "MARKET" || data.request.price === undefined, {
+    message: "price must not be provided for MARKET risk simulations",
+    path: ["request", "price"],
+});