doc: add jsdoc to schema

Author: oscarwroche

packages/bridge-controller/src/utils/validators.ts

@@ -195,32 +195,121 @@ const RefuelDataSchema = StepSchema;
 // Allow digit strings for amounts/validTo for flexibility across providers
 const DigitStringOrNumberSchema = union([TruthyDigitStringSchema, number()]);
 
-// Intent support (e.g., CoW Swap EIP-712 order signing)
+/**
+ * Identifier of the intent protocol used for order creation and submission.
+ *
+ * Examples:
+ * - CoW Swap
+ * - Other EIP-712–based intent protocols
+ */
 const IntentProtocolSchema = string;
 
+/**
+ * Schema for an intent-based order used for EIP-712 signing and submission.
+ *
+ * This represents the minimal subset of fields required by intent-based
+ * protocols (e.g. CoW Swap) to build, sign, and submit an order.
+ */
 export const IntentOrderSchema = type({
-  // EIP-712 Order fields (subset required for signing/submission)
+  /**
+   * Address of the token being sold.
+   */
   sellToken: HexAddressSchema,
+
+  /**
+   * Address of the token being bought.
+   */
   buyToken: HexAddressSchema,
+
+  /**
+   * Optional receiver of the bought tokens.
+   * If omitted, defaults to the signer / order owner.
+   */
   receiver: optional(HexAddressSchema),
+
+  /**
+   * Order expiration time.
+   *
+   * Can be provided as a UNIX timestamp in seconds, either as a number
+   * or as a digit string, depending on provider requirements.
+   */
   validTo: DigitStringOrNumberSchema,
+
+  /**
+   * Arbitrary application-specific data attached to the order.
+   */
   appData: string(),
+
+  /**
+   * Hash of the `appData` field, used for EIP-712 signing.
+   */
   appDataHash: HexStringSchema,
+
+  /**
+   * Fee amount paid for order execution, expressed as a digit string.
+   */
   feeAmount: TruthyDigitStringSchema,
+
+  /**
+   * Order kind.
+   *
+   * - `sell`: exact sell amount, variable buy amount
+   * - `buy`: exact buy amount, variable sell amount
+   */
   kind: enums(['sell', 'buy']),
+
+  /**
+   * Whether the order can be partially filled.
+   */
   partiallyFillable: boolean(),
-  // One of these is required by CoW depending on kind; we keep both optional here and rely on backend validation
+
+  /**
+   * Exact amount of the sell token.
+   *
+   * Required for `sell` orders.
+   */
   sellAmount: optional(TruthyDigitStringSchema),
+
+  /**
+   * Exact amount of the buy token.
+   *
+   * Required for `buy` orders.
+   */
   buyAmount: optional(TruthyDigitStringSchema),
-  // Optional owner/from for convenience when building domain/message
+
+  /**
+   * Optional order owner / sender address.
+   *
+   * Provided for convenience when building the EIP-712 domain and message.
+   */
   from: optional(HexAddressSchema),
 });
 
+/**
+ * Schema representing an intent submission payload.
+ *
+ * Wraps the intent order along with protocol and optional routing metadata
+ * required by the backend or relayer infrastructure.
+ */
 export const IntentSchema = type({
+  /**
+   * Identifier of the intent protocol used to interpret the order.
+   */
   protocol: IntentProtocolSchema,
+
+  /**
+   * The intent order to be signed and submitted.
+   */
   order: IntentOrderSchema,
-  // Optional metadata to aid submission/routing
+
+  /**
+   * Optional settlement contract address used for execution.
+   */
   settlementContract: optional(HexAddressSchema),
+
+  /**
+   * Optional relayer address responsible for order submission.
+   */
   relayer: optional(HexAddressSchema),
 });