@cdot65/prisma-airs-sdk 0.2.0 → 0.2.1

package/dist/index.cjs

@@ -25,11 +25,13 @@ __export(index_exports, {
   AI_SEC_API_KEY: () => AI_SEC_API_KEY,
   AI_SEC_API_TOKEN: () => AI_SEC_API_TOKEN,
   ASYNC_SCAN_PATH: () => ASYNC_SCAN_PATH,
+  Action: () => Action,
   AgentMetaSchema: () => AgentMetaSchema,
   AiProfileSchema: () => AiProfileSchema,
   AsyncScanObjectSchema: () => AsyncScanObjectSchema,
   AsyncScanResponseSchema: () => AsyncScanResponseSchema,
   BEARER: () => BEARER,
+  Category: () => Category,
   Content: () => Content,
   CreateCustomTopicRequestSchema: () => CreateCustomTopicRequestSchema,
   CreateSecurityProfileRequestSchema: () => CreateSecurityProfileRequestSchema,
@@ -106,6 +108,7 @@ __export(index_exports, {
   TopicsClient: () => TopicsClient,
   USER_AGENT: () => USER_AGENT,
   UrlfEntrySchema: () => UrlfEntrySchema,
+  Verdict: () => Verdict,
   globalConfiguration: () => globalConfiguration,
   init: () => init
 });
@@ -136,7 +139,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";
@@ -167,6 +170,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";
@@ -248,6 +255,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
 var import_node_crypto = require("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;
@@ -273,9 +342,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(
@@ -298,48 +364,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(
@@ -367,6 +412,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(
@@ -387,6 +437,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(
@@ -412,6 +467,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(
@@ -523,6 +583,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);
@@ -532,6 +593,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;
@@ -542,6 +604,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,
@@ -552,6 +618,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 = (0, import_node_fs.readFileSync)(filePath, "utf-8");
     const parsed = JSON.parse(raw);
@@ -559,6 +629,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
 var import_zod = require("zod");
 var AiProfileSchema = import_zod.z.object({
@@ -929,6 +1016,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;
@@ -941,6 +1032,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;
@@ -985,76 +1077,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
@@ -1069,6 +1128,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",
@@ -1080,6 +1144,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),
@@ -1095,6 +1164,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(
@@ -1112,6 +1187,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(
@@ -1142,6 +1222,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",
@@ -1153,6 +1238,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),
@@ -1168,6 +1258,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(
@@ -1185,6 +1281,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(
@@ -1201,6 +1302,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(
@@ -1278,11 +1384,13 @@ var ManagementClient = class {
   AI_SEC_API_KEY,
   AI_SEC_API_TOKEN,
   ASYNC_SCAN_PATH,
+  Action,
   AgentMetaSchema,
   AiProfileSchema,
   AsyncScanObjectSchema,
   AsyncScanResponseSchema,
   BEARER,
+  Category,
   Content,
   CreateCustomTopicRequestSchema,
   CreateSecurityProfileRequestSchema,
@@ -1359,6 +1467,7 @@ var ManagementClient = class {
   TopicsClient,
   USER_AGENT,
   UrlfEntrySchema,
+  Verdict,
   globalConfiguration,
   init
 });