feat: add route builder to APIClient and add docblocks

Author: thetutlage

index.ts

@@ -44,9 +44,15 @@ export function pluginAdonisJS(app: ApplicationService, options?: { baseURL: str
     /**
      * Extend "@japa/api-client" plugin
      */
-    if ((await canImport('@japa/api-client')) && app.container.hasBinding('encryption')) {
+    if (
+      (await canImport('@japa/api-client')) &&
+      app.container.hasAllBindings(['encryption', 'router'])
+    ) {
       const { extendApiClient } = await import('./src/extend_api_client.js')
-      extendApiClient(new CookieClient(await app.container.make(Encryption)))
+      extendApiClient(
+        new CookieClient(await app.container.make(Encryption)),
+        await app.container.make('router')
+      )
     }
 
     /**

package.json

@@ -39,7 +39,7 @@
     "@adonisjs/eslint-config": "^3.0.0-next.5",
     "@adonisjs/prettier-config": "^1.4.5",
     "@adonisjs/tsconfig": "^2.0.0-next.3",
-    "@japa/api-client": "^3.2.0",
+    "@japa/api-client": "^3.2.1",
     "@japa/assert": "^4.2.0",
     "@japa/browser-client": "^2.3.0",
     "@japa/runner": "^5.0.0",

src/extend_api_client.ts

@@ -7,11 +7,12 @@
  * file that was distributed with this source code.
  */
 
-import { type CookieClient } from '@adonisjs/core/http'
+import { type Router, type CookieClient } from '@adonisjs/core/http'
 import { ApiClient, ApiRequest } from '@japa/api-client'
 
 import './types/extended.js'
 import debug from './debug.ts'
+import { createURL } from '@adonisjs/core/helpers/http'
 
 /**
  * Extends the "@japa/api-client" plugin with AdonisJS-specific cookie methods.
@@ -21,15 +22,38 @@ import debug from './debug.ts'
  * cookies using the AdonisJS cookie client.
  *
  * @param cookieClient - The AdonisJS cookie client instance for cookie operations
+ * @param router - The AdonisJS router instance for route building
  *
  * @example
  * ```js
- * extendApiClient(app.container.use('cookie'))
+ * extendApiClient(app.container.use('cookie'), app.container.use('router'))
  * ```
  */
-export function extendApiClient(cookieClient: CookieClient) {
+export function extendApiClient(cookieClient: CookieClient, router: Router) {
   debug('extending @japa/api-client with adonisjs specific methods')
 
+  /**
+   * Sets up route builder for generating URLs from named routes.
+   *
+   * This allows API client requests to use route names instead of hardcoded URLs.
+   *
+   * @param name - The route name to find
+   * @param params - Route parameters for URL generation
+   *
+   * @example
+   * ```js
+   * client.get('users.show', { id: 1 })
+   * // Resolves to: GET /users/1
+   * ```
+   */
+  ApiClient.setRouteBuilder((name, params) => {
+    const route = router.findOrFail(name)
+    return {
+      url: createURL(route.pattern, route.tokens, router.qs.stringify, params),
+      method: route.methods[0],
+    }
+  })
+
   /**
    * Cookie serializer for handling AdonisJS cookies in API responses.
    *
@@ -46,6 +70,12 @@ export function extendApiClient(cookieClient: CookieClient) {
      *
      * @param _ - Cookie key (unused)
      * @param value - Cookie value to prepare
+     *
+     * @example
+     * ```js
+     * prepare('session', 'signed-value')
+     * // Returns: 'signed-value'
+     * ```
      */
     prepare(_: string, value: any) {
       return value
@@ -59,6 +89,12 @@ export function extendApiClient(cookieClient: CookieClient) {
      *
      * @param key - The cookie name
      * @param value - The raw cookie value from server response
+     *
+     * @example
+     * ```js
+     * process('session', 's:encrypted-value')
+     * // Returns: original decrypted value
+     * ```
      */
     process(key: string, value: any) {
       if (!value) {
@@ -69,7 +105,18 @@ export function extendApiClient(cookieClient: CookieClient) {
   })
 
   /**
-   * Send a signed cookie during the API request
+   * Sends a signed cookie during the API request.
+   *
+   * This macro method signs the cookie value using the AdonisJS cookie client
+   * and adds it to the request's cookie jar.
+   *
+   * @param key - The cookie name
+   * @param value - The cookie value to sign
+   *
+   * @example
+   * ```js
+   * client.get('/dashboard').withCookie('user_id', 123)
+   * ```
    */
   ApiRequest.macro('withCookie', function (this: ApiRequest, key: string, value: any) {
     const signedValue = cookieClient.sign(key, value)
@@ -79,12 +126,33 @@ export function extendApiClient(cookieClient: CookieClient) {
 
     return this
   })
+
+  /**
+   * Deprecated alias for withCookie.
+   *
+   * @deprecated Use withCookie instead
+   * @see withCookie
+   *
+   * @param key - The cookie name
+   * @param value - The cookie value to sign
+   */
   ApiRequest.macro('cookie', function (this: ApiRequest, key: string, value: any) {
     return this.withCookie(key, value)
   })
 
   /**
-   * Send an encrypted cookie during the API request
+   * Sends an encrypted cookie during the API request.
+   *
+   * This macro method encrypts the cookie value using the AdonisJS cookie client
+   * and adds it to the request's cookie jar.
+   *
+   * @param key - The cookie name
+   * @param value - The cookie value to encrypt
+   *
+   * @example
+   * ```js
+   * client.post('/login').withEncryptedCookie('session_data', { userId: 1 })
+   * ```
    */
   ApiRequest.macro('withEncryptedCookie', function (this: ApiRequest, key: string, value: any) {
     const encryptedValue = cookieClient.encrypt(key, value)
@@ -95,6 +163,15 @@ export function extendApiClient(cookieClient: CookieClient) {
     return this
   })
 
+  /**
+   * Deprecated alias for withEncryptedCookie.
+   *
+   * @deprecated Use withEncryptedCookie instead
+   * @see withEncryptedCookie
+   *
+   * @param key - The cookie name
+   * @param value - The cookie value to encrypt
+   */
   ApiRequest.macro('encryptedCookie', function (this: ApiRequest, key: string, value: any) {
     return this.withEncryptedCookie(key, value)
   })

src/extend_browser_client.ts

@@ -23,6 +23,12 @@ import debug from './debug.ts'
  *
  * @param defaultDomain - The default domain to use for cookies
  * @param options - Optional cookie options to merge with defaults
+ *
+ * @example
+ * ```js
+ * normalizeCookieOptions('localhost', { httpOnly: true })
+ * // Returns: { domain: 'localhost', path: '/', httpOnly: true }
+ * ```
  */
 function normalizeCookieOptions(defaultDomain?: string, options?: CookieOptions): CookieOptions {
   return Object.assign(
@@ -42,6 +48,15 @@ function normalizeCookieOptions(defaultDomain?: string, options?: CookieOptions)
  * if decoding fails.
  *
  * @param value - The cookie value to decode
+ *
+ * @example
+ * ```js
+ * tryDecode('hello%20world')
+ * // Returns: 'hello world'
+ *
+ * tryDecode('invalid%')
+ * // Returns: 'invalid%' (original value due to decode error)
+ * ```
  */
 function tryDecode(value: string) {
   try {

src/extend_context.ts

@@ -39,6 +39,11 @@ export function extendContext(router: Router, repl: Repl) {
    * allowing for interactive debugging during test execution.
    *
    * @param context - Optional context object to make available in the REPL
+   *
+   * @example
+   * ```js
+   * await startRepl({ user: currentUser, app })
+   * ```
    */
   function startRepl(context?: Record<any, any>) {
     return new Promise<void>((resolve) => {