@cdot65/prisma-airs-sdk 0.2.0 → 0.2.1

package/dist/index.js

@@ -23,7 +23,7 @@ var MAX_NUMBER_OF_BATCH_SCAN_OBJECTS = 5;
 var MAX_CONNECTION_POOL_SIZE = 100;
 var MAX_NUMBER_OF_RETRIES = 5;
 var HTTP_FORCE_RETRY_STATUS_CODES = [500, 502, 503, 504];
-var SDK_VERSION = "0.1.2";
+var SDK_VERSION = "0.2.1";
 var USER_AGENT = `PAN-AIRS/${SDK_VERSION}-typescript-sdk`;
 var DEFAULT_MGMT_ENDPOINT = "https://api.sase.paloaltonetworks.com/aisec";
 var DEFAULT_TOKEN_ENDPOINT = "https://auth.apps.paloaltonetworks.com/oauth2/access_token";
@@ -54,6 +54,10 @@ var ErrorType = /* @__PURE__ */ ((ErrorType2) => {
 })(ErrorType || {});
 var AISecSDKException = class _AISecSDKException extends Error {
   errorType;
+  /**
+   * @param message - Human-readable error description.
+   * @param errorType - Classification of the error.
+   */
   constructor(message, errorType) {
     super(errorType ? `${errorType}:${message}` : message);
     this.name = "AISecSDKException";
@@ -135,6 +139,68 @@ function init(opts = {}) {
   globalConfiguration.init(opts);
 }
 
+// src/http-retry.ts
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function backoffDelay(attempt) {
+  return Math.pow(2, attempt) * 1e3;
+}
+function isRetryableStatus(status) {
+  return HTTP_FORCE_RETRY_STATUS_CODES.includes(status);
+}
+function classifyErrorType(status) {
+  return status >= 500 ? "AISEC_SERVER_SIDE_ERROR" /* SERVER_SIDE_ERROR */ : "AISEC_CLIENT_SIDE_ERROR" /* CLIENT_SIDE_ERROR */;
+}
+function extractErrorMessage(body, status) {
+  try {
+    const parsed = JSON.parse(body);
+    return parsed.error_message ?? parsed.message ?? parsed.error?.message ?? `API error ${status}`;
+  } catch {
+    return body ? `API error ${status}: ${body}` : `API error ${status}`;
+  }
+}
+async function executeWithRetry(opts) {
+  const { maxRetries, execute, onRetryableFailure } = opts;
+  let lastError;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    let response;
+    try {
+      response = await execute(attempt);
+    } catch (err) {
+      if (err instanceof AISecSDKException) throw err;
+      lastError = err;
+      if (attempt < maxRetries) {
+        await sleep(backoffDelay(attempt));
+        continue;
+      }
+      throw new AISecSDKException(
+        lastError.message ?? "Network error",
+        "AISEC_CLIENT_SIDE_ERROR" /* CLIENT_SIDE_ERROR */
+      );
+    }
+    if (response.ok) return response;
+    if (onRetryableFailure) {
+      const handled = await onRetryableFailure(response, attempt);
+      if (handled) {
+        attempt--;
+        continue;
+      }
+    }
+    if (isRetryableStatus(response.status) && attempt < maxRetries) {
+      await sleep(backoffDelay(attempt));
+      continue;
+    }
+    const errorText = await response.text();
+    const errorMessage = extractErrorMessage(errorText, response.status);
+    throw new AISecSDKException(errorMessage, classifyErrorType(response.status));
+  }
+  throw new AISecSDKException(
+    lastError?.message ?? "Max retries exceeded",
+    "AISEC_CLIENT_SIDE_ERROR" /* CLIENT_SIDE_ERROR */
+  );
+}
+
 // src/utils.ts
 import { createHmac } from "crypto";
 var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -160,9 +226,6 @@ function buildHeaders() {
   }
   return headers;
 }
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
 async function httpRequest(opts) {
   if (!globalConfiguration.initialized) {
     throw new AISecSDKException(
@@ -185,48 +248,27 @@ async function httpRequest(opts) {
       headers[PAYLOAD_HASH] = generatePayloadHash(bodyStr, globalConfiguration.apiKey);
     }
   }
-  const maxRetries = globalConfiguration.numRetries;
-  let lastError;
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    try {
-      const response = await fetch(url.toString(), {
-        method: opts.method,
-        headers,
-        body: bodyStr
-      });
-      if (response.ok) {
-        const data = await response.json();
-        return { status: response.status, data };
-      }
-      if (HTTP_FORCE_RETRY_STATUS_CODES.includes(response.status) && attempt < maxRetries) {
-        await sleep(Math.pow(2, attempt) * 1e3);
-        continue;
-      }
-      let errorMessage;
-      try {
-        const errorBody = await response.json();
-        errorMessage = errorBody.message ?? errorBody.error?.message ?? `API error ${response.status}`;
-      } catch {
-        errorMessage = `API error ${response.status}`;
-      }
-      const errorType = response.status >= 500 ? "AISEC_SERVER_SIDE_ERROR" /* SERVER_SIDE_ERROR */ : "AISEC_CLIENT_SIDE_ERROR" /* CLIENT_SIDE_ERROR */;
-      throw new AISecSDKException(errorMessage, errorType);
-    } catch (err) {
-      if (err instanceof AISecSDKException) {
-        throw err;
-      }
-      lastError = err;
-      if (attempt < maxRetries) {
-        await sleep(Math.pow(2, attempt) * 1e3);
-        continue;
-      }
-    }
-  }
-  throw new AISecSDKException(lastError?.message ?? "Network error", "AISEC_CLIENT_SIDE_ERROR" /* CLIENT_SIDE_ERROR */);
+  const response = await executeWithRetry({
+    maxRetries: globalConfiguration.numRetries,
+    execute: () => fetch(url.toString(), {
+      method: opts.method,
+      headers,
+      body: bodyStr
+    })
+  });
+  const data = await response.json();
+  return { status: response.status, data };
 }
 
 // src/scan/scanner.ts
 var Scanner = class {
+  /**
+   * Perform a synchronous content scan.
+   * @param aiProfile - AI security profile to scan against.
+   * @param content - Content to scan.
+   * @param opts - Optional transaction/session IDs and metadata.
+   * @returns Scan response with verdict, action, and detection details.
+   */
   async syncScan(aiProfile, content, opts = {}) {
     if (opts.trId && opts.trId.length > MAX_TRANSACTION_ID_STR_LENGTH) {
       throw new AISecSDKException(
@@ -254,6 +296,11 @@ var Scanner = class {
     });
     return res.data;
   }
+  /**
+   * Submit content for asynchronous scanning.
+   * @param scanObjects - Array of scan objects (1–5 items).
+   * @returns Response containing scan IDs for later querying.
+   */
   async asyncScan(scanObjects) {
     if (scanObjects.length < 1) {
       throw new AISecSDKException(
@@ -274,6 +321,11 @@ var Scanner = class {
     });
     return res.data;
   }
+  /**
+   * Query scan results by scan IDs.
+   * @param scanIds - Array of scan UUIDs (1–5 items).
+   * @returns Array of scan results with status and response data.
+   */
   async queryByScanIds(scanIds) {
     if (scanIds.length < 1) {
       throw new AISecSDKException(
@@ -299,6 +351,11 @@ var Scanner = class {
     });
     return res.data;
   }
+  /**
+   * Query detailed threat reports by report IDs.
+   * @param reportIds - Array of report IDs (1–5 items).
+   * @returns Array of threat scan reports with detection details.
+   */
   async queryByReportIds(reportIds) {
     if (reportIds.length < 1) {
       throw new AISecSDKException(
@@ -410,6 +467,7 @@ var Content = class _Content {
   set toolEvent(value) {
     this._toolEvent = value;
   }
+  /** Total byte length of all text content fields. */
   get length() {
     let total = 0;
     if (this._prompt) total += Buffer.byteLength(this._prompt);
@@ -419,6 +477,7 @@ var Content = class _Content {
     if (this._codeResponse) total += Buffer.byteLength(this._codeResponse);
     return total;
   }
+  /** Serialize to the API request format. */
   toJSON() {
     const obj = {};
     if (this._prompt !== void 0) obj.prompt = this._prompt;
@@ -429,6 +488,10 @@ var Content = class _Content {
     if (this._toolEvent !== void 0) obj.tool_event = this._toolEvent;
     return obj;
   }
+  /**
+   * Create a Content instance from an API response object.
+   * @param json - Scan request contents inner object.
+   */
   static fromJSON(json) {
     return new _Content({
       prompt: json.prompt,
@@ -439,6 +502,10 @@ var Content = class _Content {
       toolEvent: json.tool_event
     });
   }
+  /**
+   * Load content from a JSON file.
+   * @param filePath - Path to JSON file containing scan request contents.
+   */
   static fromJSONFile(filePath) {
     const raw = readFileSync(filePath, "utf-8");
     const parsed = JSON.parse(raw);
@@ -446,6 +513,23 @@ var Content = class _Content {
   }
 };
 
+// src/models/enums.ts
+var Verdict = {
+  BENIGN: "benign",
+  MALICIOUS: "malicious",
+  UNKNOWN: "unknown"
+};
+var Action = {
+  ALLOW: "allow",
+  BLOCK: "block",
+  ALERT: "alert"
+};
+var Category = {
+  BENIGN: "benign",
+  MALICIOUS: "malicious",
+  UNKNOWN: "unknown"
+};
+
 // src/models/ai-profile.ts
 import { z } from "zod";
 var AiProfileSchema = z.object({
@@ -816,6 +900,10 @@ var OAuthClient = class {
     this.tsgId = opts.tsgId;
     this.tokenEndpoint = opts.tokenEndpoint ?? DEFAULT_TOKEN_ENDPOINT;
   }
+  /**
+   * Get a valid access token, refreshing if needed.
+   * @returns Bearer access token string.
+   */
   async getToken() {
     if (this.accessToken && Date.now() < this.expiresAt - TOKEN_BUFFER_MS) {
       return this.accessToken;
@@ -828,6 +916,7 @@ var OAuthClient = class {
     });
     return this.pendingFetch;
   }
+  /** Clear the cached token, forcing a fresh fetch on next call. */
   clearToken() {
     this.accessToken = null;
     this.expiresAt = 0;
@@ -872,76 +961,43 @@ var OAuthClient = class {
 };
 
 // src/management/management-http-client.ts
-function sleep2(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-function extractError(body, status) {
-  try {
-    const parsed = JSON.parse(body);
-    return parsed.error_message ?? parsed.message ?? `API error ${status}: ${body}`;
-  } catch {
-    return body ? `API error ${status}: ${body}` : `API error ${status}`;
-  }
-}
 async function managementHttpRequest(opts) {
   const { method, baseUrl, path, body, params, oauthClient, numRetries } = opts;
   let hadTokenRefresh = false;
-  for (let attempt = 0; attempt <= numRetries; attempt++) {
-    const token = await oauthClient.getToken();
-    const stripped = baseUrl.replace(/\/+$/, "");
-    const url = new URL(`${stripped}${path}`);
-    if (params) {
-      for (const [key, value] of Object.entries(params)) {
-        url.searchParams.set(key, value);
+  const response = await executeWithRetry({
+    maxRetries: numRetries,
+    execute: async () => {
+      const token = await oauthClient.getToken();
+      const stripped = baseUrl.replace(/\/+$/, "");
+      const url = new URL(`${stripped}${path}`);
+      if (params) {
+        for (const [key, value] of Object.entries(params)) {
+          url.searchParams.set(key, value);
+        }
       }
-    }
-    const headers = {
-      Authorization: `Bearer ${token}`,
-      "User-Agent": USER_AGENT
-    };
-    let bodyStr;
-    if (body !== void 0) {
-      headers["Content-Type"] = "application/json";
-      bodyStr = JSON.stringify(body);
-    }
-    let response;
-    try {
-      response = await fetch(url.toString(), {
-        method,
-        headers,
-        body: bodyStr
-      });
-    } catch (err) {
-      if (attempt < numRetries) {
-        await sleep2(Math.pow(2, attempt) * 1e3);
-        continue;
+      const headers = {
+        Authorization: `Bearer ${token}`,
+        "User-Agent": USER_AGENT
+      };
+      let bodyStr;
+      if (body !== void 0) {
+        headers["Content-Type"] = "application/json";
+        bodyStr = JSON.stringify(body);
       }
-      throw new AISecSDKException(
-        err.message ?? "Network error",
-        "AISEC_CLIENT_SIDE_ERROR" /* CLIENT_SIDE_ERROR */
-      );
-    }
-    if (response.ok) {
-      const text = await response.text();
-      const data = text ? JSON.parse(text) : {};
-      return { status: response.status, data };
-    }
-    if (response.status === 401 && !hadTokenRefresh) {
-      hadTokenRefresh = true;
-      oauthClient.clearToken();
-      attempt--;
-      continue;
-    }
-    if (HTTP_FORCE_RETRY_STATUS_CODES.includes(response.status) && attempt < numRetries) {
-      await sleep2(Math.pow(2, attempt) * 1e3);
-      continue;
+      return fetch(url.toString(), { method, headers, body: bodyStr });
+    },
+    onRetryableFailure: async (response2) => {
+      if (response2.status === 401 && !hadTokenRefresh) {
+        hadTokenRefresh = true;
+        oauthClient.clearToken();
+        return true;
+      }
+      return false;
     }
-    const errorText = await response.text();
-    const errorMessage = extractError(errorText, response.status);
-    const errorType = response.status >= 500 ? "AISEC_SERVER_SIDE_ERROR" /* SERVER_SIDE_ERROR */ : "AISEC_CLIENT_SIDE_ERROR" /* CLIENT_SIDE_ERROR */;
-    throw new AISecSDKException(errorMessage, errorType);
-  }
-  throw new AISecSDKException("Max retries exceeded", "AISEC_CLIENT_SIDE_ERROR" /* CLIENT_SIDE_ERROR */);
+  });
+  const text = await response.text();
+  const data = text ? JSON.parse(text) : {};
+  return { status: response.status, data };
 }
 
 // src/management/profiles.ts
@@ -956,6 +1012,11 @@ var ProfilesClient = class {
     this.tsgId = opts.tsgId;
     this.numRetries = opts.numRetries;
   }
+  /**
+   * Create a new security profile.
+   * @param request - Profile configuration.
+   * @returns The created security profile.
+   */
   async create(request) {
     const res = await managementHttpRequest({
       method: "POST",
@@ -967,6 +1028,11 @@ var ProfilesClient = class {
     });
     return res.data;
   }
+  /**
+   * List security profiles for the TSG.
+   * @param opts - Pagination options.
+   * @returns Paginated list of security profiles.
+   */
   async list(opts) {
     const params = {
       offset: String(opts?.offset ?? 0),
@@ -982,6 +1048,12 @@ var ProfilesClient = class {
     });
     return res.data;
   }
+  /**
+   * Update an existing security profile.
+   * @param profileId - UUID of the profile to update.
+   * @param request - Updated profile configuration.
+   * @returns The updated security profile.
+   */
   async update(profileId, request) {
     if (!isValidUuid(profileId)) {
       throw new AISecSDKException(
@@ -999,6 +1071,11 @@ var ProfilesClient = class {
     });
     return res.data;
   }
+  /**
+   * Delete a security profile.
+   * @param profileId - UUID of the profile to delete.
+   * @returns Deletion confirmation message.
+   */
   async delete(profileId) {
     if (!isValidUuid(profileId)) {
       throw new AISecSDKException(
@@ -1029,6 +1106,11 @@ var TopicsClient = class {
     this.tsgId = opts.tsgId;
     this.numRetries = opts.numRetries;
   }
+  /**
+   * Create a new custom topic.
+   * @param request - Topic definition with name, description, and examples.
+   * @returns The created custom topic.
+   */
   async create(request) {
     const res = await managementHttpRequest({
       method: "POST",
@@ -1040,6 +1122,11 @@ var TopicsClient = class {
     });
     return res.data;
   }
+  /**
+   * List custom topics for the TSG.
+   * @param opts - Pagination options.
+   * @returns Paginated list of custom topics.
+   */
   async list(opts) {
     const params = {
       offset: String(opts?.offset ?? 0),
@@ -1055,6 +1142,12 @@ var TopicsClient = class {
     });
     return res.data;
   }
+  /**
+   * Update an existing custom topic.
+   * @param topicId - UUID of the topic to update.
+   * @param request - Updated topic definition.
+   * @returns The updated custom topic.
+   */
   async update(topicId, request) {
     if (!isValidUuid(topicId)) {
       throw new AISecSDKException(
@@ -1072,6 +1165,11 @@ var TopicsClient = class {
     });
     return res.data;
   }
+  /**
+   * Delete a custom topic. Fails if topic is referenced by a profile.
+   * @param topicId - UUID of the topic to delete.
+   * @returns Deletion confirmation message.
+   */
   async delete(topicId) {
     if (!isValidUuid(topicId)) {
       throw new AISecSDKException(
@@ -1088,6 +1186,11 @@ var TopicsClient = class {
     });
     return res.data;
   }
+  /**
+   * Force-delete a custom topic, removing it from any referencing profiles.
+   * @param topicId - UUID of the topic to force-delete.
+   * @returns Deletion confirmation message.
+   */
   async forceDelete(topicId) {
     if (!isValidUuid(topicId)) {
       throw new AISecSDKException(
@@ -1164,11 +1267,13 @@ export {
   AI_SEC_API_KEY,
   AI_SEC_API_TOKEN,
   ASYNC_SCAN_PATH,
+  Action,
   AgentMetaSchema,
   AiProfileSchema,
   AsyncScanObjectSchema,
   AsyncScanResponseSchema,
   BEARER,
+  Category,
   Content,
   CreateCustomTopicRequestSchema,
   CreateSecurityProfileRequestSchema,
@@ -1245,6 +1350,7 @@ export {
   TopicsClient,
   USER_AGENT,
   UrlfEntrySchema,
+  Verdict,
   globalConfiguration,
   init
 };