@cdot65/prisma-airs-sdk 0.13.0 → 0.13.2

package/dist/index.js

@@ -25,11 +25,11 @@ var MAX_REPORT_ID_STR_LENGTH = 40;
 var MAX_AI_PROFILE_NAME_LENGTH = 100;
 var MAX_NUMBER_OF_SCAN_IDS = 5;
 var MAX_NUMBER_OF_REPORT_IDS = 5;
-var MAX_NUMBER_OF_BATCH_SCAN_OBJECTS = 5;
+var MAX_NUMBER_OF_BATCH_SCAN_OBJECTS = 20;
 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.13.0";
+var SDK_VERSION = "0.13.2";
 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";
@@ -129,11 +129,15 @@ var AISecSDKException = class _AISecSDKException extends Error {
   /**
    * @param message - Human-readable error description.
    * @param errorType - Classification of the error.
+   * @param metadata - Optional transport failure metadata.
    */
-  constructor(message, errorType) {
+  constructor(message, errorType, metadata = {}) {
     super(errorType ? `${errorType}:${message}` : message);
     this.name = "AISecSDKException";
     this.errorType = errorType;
+    if (metadata.failureKind !== void 0) this.failureKind = metadata.failureKind;
+    if (metadata.statusCode !== void 0) this.statusCode = metadata.statusCode;
+    if (metadata.retryAfterMs !== void 0) this.retryAfterMs = metadata.retryAfterMs;
     if (Error.captureStackTrace) {
       Error.captureStackTrace(this, _AISecSDKException);
     }
@@ -275,6 +279,59 @@ function extractErrorMessage(body, status) {
     return body ? `API error ${status}: ${body}` : `API error ${status}`;
   }
 }
+function parseRetryAfterHeader(value) {
+  if (value === null) return void 0;
+  const normalized = value.trim();
+  if (/^\d+$/.test(normalized)) {
+    const milliseconds = Number(normalized) * 1e3;
+    return Number.isFinite(milliseconds) ? milliseconds : void 0;
+  }
+  const weekday = "(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun)";
+  const longWeekday = "(?:Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday)";
+  const month = "(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)";
+  const httpDatePatterns = [
+    new RegExp(`^${weekday}, \\d{2} ${month} \\d{4} \\d{2}:\\d{2}:\\d{2} GMT$`),
+    new RegExp(`^${longWeekday}, \\d{2}-${month}-\\d{2} \\d{2}:\\d{2}:\\d{2} GMT$`),
+    new RegExp(`^${weekday} ${month} [ \\d]\\d \\d{2}:\\d{2}:\\d{2} \\d{4}$`)
+  ];
+  if (!httpDatePatterns.some((pattern) => pattern.test(normalized))) return void 0;
+  const timestamp = Date.parse(normalized);
+  if (!Number.isFinite(timestamp)) return void 0;
+  return Math.max(0, timestamp - Date.now());
+}
+function parseRetryAfterBody(body) {
+  try {
+    const parsed = JSON.parse(body);
+    const interval = parsed.retry_after?.interval;
+    const unit = parsed.retry_after?.unit;
+    if (typeof interval !== "number" || !Number.isFinite(interval) || interval < 0)
+      return void 0;
+    if (typeof unit !== "string") return void 0;
+    const unitMultipliers = {
+      ms: 1,
+      msec: 1,
+      msecs: 1,
+      millisecond: 1,
+      milliseconds: 1,
+      s: 1e3,
+      sec: 1e3,
+      secs: 1e3,
+      second: 1e3,
+      seconds: 1e3,
+      m: 6e4,
+      min: 6e4,
+      mins: 6e4,
+      minute: 6e4,
+      minutes: 6e4
+    };
+    const multiplier = unitMultipliers[unit.toLowerCase()];
+    if (multiplier === void 0) return void 0;
+    const milliseconds = interval * multiplier;
+    return Number.isFinite(milliseconds) ? milliseconds : void 0;
+  } catch {
+    return void 0;
+  }
+}
 async function executeWithRetry(opts) {
   const { maxRetries, execute, onRetryableFailure } = opts;
   let lastError;
@@ -291,7 +348,8 @@ async function executeWithRetry(opts) {
       }
       throw new AISecSDKException(
         lastError.message ?? "Network error",
-        "AISEC_CLIENT_SIDE_ERROR" /* CLIENT_SIDE_ERROR */
+        "AISEC_CLIENT_SIDE_ERROR" /* CLIENT_SIDE_ERROR */,
+        { failureKind: "network" }
       );
     }
     if (response.ok) return response;
@@ -308,11 +366,18 @@ async function executeWithRetry(opts) {
     }
     const errorText = await response.text();
     const errorMessage = extractErrorMessage(errorText, response.status);
-    throw new AISecSDKException(errorMessage, classifyErrorType(response.status));
+    const retryAfterHeader = response.headers?.get?.("Retry-After") ?? null;
+    const headerRetryAfterMs = parseRetryAfterHeader(retryAfterHeader);
+    throw new AISecSDKException(errorMessage, classifyErrorType(response.status), {
+      failureKind: "http",
+      statusCode: response.status,
+      retryAfterMs: headerRetryAfterMs ?? parseRetryAfterBody(errorText)
+    });
   }
   throw new AISecSDKException(
     lastError?.message ?? "Max retries exceeded",
-    "AISEC_CLIENT_SIDE_ERROR" /* CLIENT_SIDE_ERROR */
+    "AISEC_CLIENT_SIDE_ERROR" /* CLIENT_SIDE_ERROR */,
+    lastError ? { failureKind: "network" } : {}
   );
 }
 
@@ -445,6 +510,7 @@ var PromptDetectedSchema = z.object({
   injection: z.boolean().optional(),
   toxic_content: z.boolean().optional(),
   malicious_code: z.boolean().optional(),
+  source_code: z.boolean().optional(),
   agent: z.boolean().optional(),
   topic_violation: z.boolean().optional()
 }).passthrough();
@@ -749,6 +815,16 @@ var ThreatScanReportSchema = z14.object({
 }).passthrough();
 
 // src/scan/scanner.ts
+function resolveNumRetries(opts) {
+  const numRetries = opts.numRetries ?? globalConfiguration.numRetries;
+  if (!Number.isFinite(numRetries) || !Number.isInteger(numRetries) || numRetries < 0 || numRetries > MAX_NUMBER_OF_RETRIES) {
+    throw new AISecSDKException(
+      `numRetries must be a finite integer between 0 and ${MAX_NUMBER_OF_RETRIES}`,
+      "AISEC_USER_REQUEST_PAYLOAD_ERROR" /* USER_REQUEST_PAYLOAD_ERROR */
+    );
+  }
+  return numRetries;
+}
 var Scanner = class {
   /**
    * @internal
@@ -769,7 +845,7 @@ 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.
+   * @param opts - Optional transaction/session IDs, metadata, and per-call retry override.
    * @returns Scan response with verdict, action, and detection details.
    * @example
    * ```ts
@@ -788,6 +864,7 @@ var Scanner = class {
    * ```
    */
   async syncScan(aiProfile, content, opts = {}) {
+    const numRetries = resolveNumRetries(opts);
     if (opts.trId && opts.trId.length > MAX_TRANSACTION_ID_STR_LENGTH) {
       throw new AISecSDKException(
         `trId exceeds max length of ${MAX_TRANSACTION_ID_STR_LENGTH}`,
@@ -814,33 +891,52 @@ var Scanner = class {
       body,
       responseSchema: ScanResponseSchema,
       auth: this.buildAuth(),
-      numRetries: globalConfiguration.numRetries
+      numRetries
     });
   }
   /**
-   * Submit content for asynchronous scanning.
-   * @param scanObjects - Array of scan objects (1–5 items).
-   * @returns Response containing scan IDs for later querying.
+   * Submit one batch of content for asynchronous scanning.
+   *
+   * The call accepts 1–20 request objects and returns one batch receipt. A batch `scan_id` can fan
+   * out to several unordered result rows. Correlate each row by `(scan_id, req_id)`, never array
+   * position or `scan_id` alone. The SDK preserves the server's row order and cardinality.
+   *
+   * Setting `numRetries: 0` guarantees one SDK fetch attempt, but cannot guarantee exactly-once
+   * server submission after an ambiguous network or 5xx failure.
+   * @param scanObjects - Array of scan objects (1–20 items), each with its own `req_id`.
+   * @param opts - Optional per-call retry override.
+   * @returns One batch receipt containing the shared scan ID for later querying.
    * @example
    * ```ts
    * import { init, Scanner } from '@cdot65/prisma-airs-sdk';
    * init();
    * const scanner = new Scanner();
    *
-   * const result = await scanner.asyncScan([
-   *   {
-   *     req_id: 1,
-   *     scan_req: {
-   *       ai_profile: { profile_name: 'my-profile' },
-   *       contents: [{ prompt: 'Tell me about machine learning.' }],
+   * const receipt = await scanner.asyncScan(
+   *   [
+   *     {
+   *       req_id: 1,
+   *       scan_req: {
+   *         ai_profile: { profile_name: 'my-profile' },
+   *         contents: [{ prompt: 'Tell me about machine learning.' }],
+   *       },
    *     },
-   *   },
-   * ]);
-   * // result =>
+   *     {
+   *       req_id: 2,
+   *       scan_req: {
+   *         ai_profile: { profile_name: 'my-profile' },
+   *         contents: [{ prompt: 'What are neural networks?' }],
+   *       },
+   *     },
+   *   ],
+   *   { numRetries: 0 },
+   * );
+   * // receipt =>
    * // { received: '2024-01-01T00:00:00Z', scan_id: '550e...' }
    * ```
    */
-  async asyncScan(scanObjects) {
+  async asyncScan(scanObjects, opts = {}) {
+    const numRetries = resolveNumRetries(opts);
     if (scanObjects.length < 1) {
       throw new AISecSDKException(
         "At least 1 scan object is required",
@@ -860,13 +956,17 @@ var Scanner = class {
       body: scanObjects,
       responseSchema: AsyncScanResponseSchema,
       auth: this.buildAuth(),
-      numRetries: globalConfiguration.numRetries
+      numRetries
     });
   }
   /**
    * Query scan results by scan IDs.
+   *
+   * One scan ID can return several unordered rows. Correlate them using `(scan_id, req_id)`. The
+   * SDK does not sort, deduplicate, or collapse the response.
    * @param scanIds - Array of scan UUIDs (1–5 items).
-   * @returns Array of scan results with status and response data.
+   * @param opts - Optional per-call retry override.
+   * @returns Every scan-result row in server order, with status and response data.
    * @example
    * ```ts
    * import { init, Scanner } from '@cdot65/prisma-airs-sdk';
@@ -876,12 +976,14 @@ var Scanner = class {
    * const results = await scanner.queryByScanIds([
    *   '550e8400-e29b-41d4-a716-446655440000',
    * ]);
-   * // results =>
-   * // [{ scan_id: '550e8400-e29b-41d4-a716-446655440000', status: 'complete',
-   * //    result: { category: 'benign', action: 'allow', ... } }]
+   * // A single scan ID may produce multiple rows, for example req_id 2 then req_id 1.
+   * for (const row of results) {
+   *   console.log(`${row.scan_id}:${row.req_id}`, row.status, row.result?.action);
+   * }
    * ```
    */
-  async queryByScanIds(scanIds) {
+  async queryByScanIds(scanIds, opts = {}) {
+    const numRetries = resolveNumRetries(opts);
     if (scanIds.length < 1) {
       throw new AISecSDKException(
         "At least 1 scan_id is required",
@@ -906,13 +1008,17 @@ var Scanner = class {
       params: { scan_ids: scanIds.join(",") },
       responseSchema: z15.array(ScanIdResultSchema),
       auth: this.buildAuth(),
-      numRetries: globalConfiguration.numRetries
+      numRetries
     });
   }
   /**
    * Query detailed threat reports by report IDs.
+   *
+   * One report ID can return several rows. Correlate them using `(report_id, req_id)`. The SDK
+   * preserves server order and cardinality without sorting or deduplicating.
    * @param reportIds - Array of report IDs (1–5 items).
-   * @returns Array of threat scan reports with detection details.
+   * @param opts - Optional per-call retry override.
+   * @returns Every report row in server order, with detection details.
    * @example
    * ```ts
    * import { init, Scanner } from '@cdot65/prisma-airs-sdk';
@@ -920,12 +1026,13 @@ var Scanner = class {
    * const scanner = new Scanner();
    *
    * const reports = await scanner.queryByReportIds(['R000...']);
-   * // reports =>
-   * // [{ report_id: 'R000...', scan_id: '550e...',
-   * //    detection_results: [{ detection_service: 'pi', verdict: 'benign', action: 'allow' }] }]
+   * for (const report of reports) {
+   *   console.log(`${report.report_id}:${report.req_id}`, report.detection_results);
+   * }
    * ```
    */
-  async queryByReportIds(reportIds) {
+  async queryByReportIds(reportIds, opts = {}) {
+    const numRetries = resolveNumRetries(opts);
     if (reportIds.length < 1) {
       throw new AISecSDKException(
         "At least 1 report_id is required",
@@ -945,7 +1052,7 @@ var Scanner = class {
       params: { report_ids: reportIds.join(",") },
       responseSchema: z15.array(ThreatScanReportSchema),
       auth: this.buildAuth(),
-      numRetries: globalConfiguration.numRetries
+      numRetries
     });
   }
 };