types:ref: update jsdocs for targetUrl property in error response schemas

- Moved the targetUrl property to a consistent position in BaseErrorResponseSchema, LinksErrorResponseSchema, and ReadResponseBaseSchema to enhance clarity.
- Updated documentation and examples to reflect the changes, ensuring better understanding of the error response structure for developers.

Author: lumpinif

packages/types/src/common/response-schemas.ts

@@ -14,8 +14,8 @@ import * as z from 'zod/v4';
  * ```typescript
  * const errorResponse = {
  *   success: false,
- *   targetUrl: 'https://example.com/article',
  *   requestUrl: 'https://example.com/article#fragment',
+ *   targetUrl: 'https://example.com/article',
  *   timestamp: '2024-01-15T10:30:00.000Z'
  *   error: 'Failed to fetch: 404 Not Found',
  * };
@@ -28,11 +28,6 @@ export const BaseErrorResponseSchema = z
       description: 'Indicates that the operation failed',
       examples: [false],
     }),
-    /* The URL that was being processed when the error occurred */
-    targetUrl: z.string().meta({
-      description: 'The URL that was being processed when the error occurred',
-      examples: ['https://example.com/article'],
-    }),
     /* The URL, raw url, that was requested to be processed and might be different from the target url */
     requestUrl: z
       .string()
@@ -42,6 +37,11 @@ export const BaseErrorResponseSchema = z
           'The URL, raw url, that was requested to be processed and might be different from the target url',
         examples: ['https://example.com/article#fragment'],
       }),
+    /* The URL that was being processed when the error occurred */
+    targetUrl: z.string().meta({
+      description: 'The URL that was being processed when the error occurred',
+      examples: ['https://example.com/article'],
+    }),
     /* ISO timestamp when the error occurred */
     timestamp: z.string().meta({
       description: 'ISO timestamp when the error occurred',

packages/types/src/routers/links/types.ts

@@ -875,6 +875,7 @@ export const LinksErrorResponseSchema = BaseErrorResponseSchema.extend({
   examples: [
     {
       success: false,
+      requestUrl: 'https://example.com/article#fragment',
       targetUrl: 'https://example.com',
       timestamp: '2024-01-15T10:30:00.000Z',
       error: 'Failed to fetch: 404 Not Found',
@@ -1062,8 +1063,8 @@ export type LinksSuccessResponse = z.infer<typeof LinksSuccessResponseSchema>;
  * Contains information about what went wrong.
  *
  * @property success - Whether the operation was successful
- * @property targetUrl - The URL that was requested to be scraped
  * @property [requestUrl] - URL, raw url, that was requested to be processed and might be different from the target url
+ * @property targetUrl - The URL that was requested to be scraped
  * @property timestamp - ISO timestamp when the request was processed
  * @property error - Error message describing what went wrong
  * @property tree - Partial site map tree if available
@@ -1072,8 +1073,8 @@ export type LinksSuccessResponse = z.infer<typeof LinksSuccessResponseSchema>;
  * ```typescript
  * const errorResponse: LinksErrorResponse = {
  *   success: false,
- *   targetUrl: "https://example.com",
  *   requestUrl: "https://example.com/article#fragment",
+ *   targetUrl: "https://example.com",
  *   timestamp: "2025-04-02T14:28:23.000Z",
  *   error: "Failed to connect to the server"
  * };

packages/types/src/routers/read/types.ts

@@ -218,8 +218,8 @@ export const ReadResponseBaseSchema = z.object({
  *
  * @property {false} success - Always false for error responses
  * @property {string} error - Error message describing what went wrong
- * @property {string} targetUrl - URL that was being processed when error occurred
  * @property {string} [requestUrl] - URL, raw url, that was requested to be processed and might be different from the target url
+ * @property {string} targetUrl - URL that was being processed when error occurred
  * @property {string} timestamp - ISO timestamp when the error occurred
  *
  * @see {@link BaseErrorResponseSchema} for base error response structure
@@ -229,8 +229,8 @@ export const ReadResponseBaseSchema = z.object({
  * {
  *   success: false,
  *   error: 'Failed to fetch URL',
- *   targetUrl: 'https://example.com/article',
  *   requestUrl: 'https://example.com/article#fragment', // optional
+ *   targetUrl: 'https://example.com/article',
  *   timestamp: '2025-09-12T10:30:00.000Z'
  * }
  * ```
@@ -452,17 +452,17 @@ export type ReadResponseBase = z.infer<typeof ReadResponseBaseSchema>;
  *
  * @property {false} success - Always false for error responses
  * @property {string} error - Error message describing what went wrong
- * @property {string} targetUrl - URL that was being processed when error occurred
  * @property {string} [requestUrl] - URL, raw url, that was requested to be processed and might be different from the target url
+ * @property {string} targetUrl - URL that was being processed when error occurred
  * @property {string} timestamp - ISO timestamp when the error occurred
  *
  * @example
  * ```typescript
  * const errorResponse: ReadErrorResponse = {
  *   success: false,
  *   error: 'Failed to fetch URL',
- *   targetUrl: 'https://example.com/article',
  *   requestUrl: 'https://example.com/article#fragment', // optional
+ *   targetUrl: 'https://example.com/article',
  *   timestamp: '2025-09-12T10:30:00.000Z'
  * };
  * ```