From 26ff5dd756779eaa4d575df75053d6d1d3084bc1 Mon Sep 17 00:00:00 2001
From: Salman Chishti <salmanmkc@GitHub.com>
Date: Thu, 13 Mar 2025 04:47:49 -0700
Subject: [PATCH] update ts docs

---
 src/internal/shared/util.ts | 44 +++++++++++++++++++++++++++++--------
 1 file changed, 35 insertions(+), 9 deletions(-)

diff --git a/src/internal/shared/util.ts b/src/internal/shared/util.ts
index 61f2ab6..e346e63 100644
--- a/src/internal/shared/util.ts
+++ b/src/internal/shared/util.ts
@@ -73,13 +73,23 @@ export function getBackendIdsFromToken(): BackendIds {
 
 /**
  * Masks the `sig` parameter in a URL and sets it as a secret.
- * @param url The URL containing the `sig` parameter.
- * @returns A masked URL where the sig parameter value is replaced with '***' if found,
- *          or the original URL if no sig parameter is present.
+ *
+ * @param url - The URL containing the signature parameter to mask
+ * @remarks
+ * This function attempts to parse the provided URL and identify the 'sig' query parameter.
+ * If found, it registers both the raw and URL-encoded signature values as secrets using
+ * the Actions `setSecret` API, which prevents them from being displayed in logs.
+ *
+ * The function handles errors gracefully if URL parsing fails, logging them as debug messages.
+ *
+ * @example
+ * ```typescript
+ * // Mask a signature in an Azure SAS token URL
+ * maskSigUrl('https://example.blob.core.windows.net/container/file.txt?sig=abc123&se=2023-01-01');
+ * ```
  */
-export function maskSigUrl(url: string): string {
-  if (!url) return url
-
+export function maskSigUrl(url: string): void {
+  if (!url) return
   try {
     const parsedUrl = new URL(url)
     const signature = parsedUrl.searchParams.get('sig')
@@ -88,7 +98,6 @@ export function maskSigUrl(url: string): string {
       setSecret(signature)
       setSecret(encodeURIComponent(signature))
       parsedUrl.searchParams.set('sig', '***')
-      return parsedUrl.toString()
     }
   } catch (error) {
     debug(
@@ -97,11 +106,28 @@ export function maskSigUrl(url: string): string {
       }`
     )
   }
-  return url
 }
 
 /**
- * Masks any URLs containing signature parameters in the provided object
+ * Masks sensitive information in URLs containing signature parameters.
+ * Currently supports masking 'sig' parameters in the 'signed_upload_url'
+ * and 'signed_download_url' properties of the provided object.
+ *
+ * @param body - The object should contain a signature
+ * @remarks
+ * This function extracts URLs from the object properties and calls maskSigUrl
+ * on each one to redact sensitive signature information. The function doesn't
+ * modify the original object; it only marks the signatures as secrets for
+ * logging purposes.
+ *
+ * @example
+ * ```typescript
+ * const responseBody = {
+ *   signed_upload_url: 'https://example.com?sig=abc123',
+ *   signed_download_url: 'https://example.com?sig=def456'
+ * };
+ * maskSecretUrls(responseBody);
+ * ```
  */
 export function maskSecretUrls(body: Record<string, unknown> | null): void {
   if (typeof body !== 'object' || body === null) {