improve params schema

Author: andre-j3sus

apps/radar/src/types/radar.ts

@@ -6,9 +6,12 @@ import { z } from 'zod'
 import type { ASNListParams } from 'cloudflare/resources/radar/entities/asns.mjs'
 import type { TrafficAnomalyGetParams } from 'cloudflare/resources/radar/traffic-anomalies.mjs'
 
-export const AsnParam = z.number().positive()
+export const AsnParam = z
+	.number()
+	.positive()
+	.describe('Autonomous System Number (ASN), must be a positive number.')
 
-export const IpParam = z.string().ip()
+export const IpParam = z.string().ip().describe('IPv4 or IPv6 address in standard notation.')
 
 export const DateRangeParam: z.ZodType<TrafficAnomalyGetParams['dateRange']> = z
 	.string()
@@ -17,11 +20,19 @@ export const DateRangeParam: z.ZodType<TrafficAnomalyGetParams['dateRange']> = z
 		/^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$/,
 		'Invalid Date Range'
 	)
+	.describe(
+		"Date range string in the format of 'Xd' or 'Xw', where X is a number of days (1–364) or weeks (1–52), optionally suffixed with 'control'."
+	)
 
-//TODO use ".describe("...")"
+export const DateStartParam: z.ZodType<TrafficAnomalyGetParams['dateStart']> = z
+	.string()
+	.datetime()
+	.describe('Start date in ISO 8601 format (e.g., 2023-04-01T00:00:00Z).')
 
-export const DateStartParam: z.ZodType<TrafficAnomalyGetParams['dateStart']> = z.string().datetime()
-export const DateEndParam: z.ZodType<TrafficAnomalyGetParams['dateEnd']> = z.string().datetime()
+export const DateEndParam: z.ZodType<TrafficAnomalyGetParams['dateEnd']> = z
+	.string()
+	.datetime()
+	.describe('End date in ISO 8601 format (e.g., 2023-04-30T23:59:59Z).')
 
 export const SingleLocationParam: z.ZodType<ASNListParams['location']> = z
 	.string()
@@ -30,7 +41,9 @@ export const SingleLocationParam: z.ZodType<ASNListParams['location']> = z
 			'Invalid location code. Must be a valid alpha-2 location code (two letters, case insensitive).',
 	})
 	.optional()
+	.describe('Optional alpha-2 country code (e.g., "US", "DE").')
 
 export const AsOrderByParam: z.ZodType<ASNListParams['orderBy']> = z
 	.enum(['ASN', 'POPULATION'])
 	.optional()
+	.describe('Optional order by parameter: "ASN" or "POPULATION".')

apps/radar/src/types/url-scanner.ts

@@ -3,4 +3,7 @@
  */
 import { z } from 'zod'
 
-export const UrlParam = z.string().url()
+export const UrlParam = z
+	.string()
+	.url()
+	.describe('A valid URL including protocol (e.g., "https://example.com").')