@knowttl/checkpoint-axi 0.1.3 → 0.1.4

package/dist/src/catalogue.d.ts

@@ -1,9 +1,15 @@
+export declare const FILTER_OPERATORS: readonly ["is", "contains", "startsWith", "isEmpty", "isNot", "notContains", "isNotEmpty", "greaterThan", "lessThan"];
 export declare const DESCRIPTION = "Inspect Check Point Email Security through compact, guarded AXI commands";
 export declare const SETUP_GUIDANCE = "Run checkpoint-axi config path; configure a region, clientId and clientSecret env/file SecretRef";
 export declare const TASK_WAIT_GUIDANCE: string;
 export declare const DETAIL_EXPANSION_GUIDANCE: string;
 export declare const EMAIL_PAYLOAD_ATTRIBUTES: string[];
 export declare const EMAIL_FILTER_GUIDANCE: string;
+export declare const EVENT_STATES: readonly ["new", "detected", "pending", "remediated", "dismissed", "exception"];
+export declare const LIST_ROW_FIELDS: {
+    readonly "email search": readonly ["id", "subject", "state", "verdict"];
+    readonly "event list": readonly ["id", "type", "state", "severity"];
+};
 export declare const catalogue: {
     readonly "email download": {
         readonly description: "Download an email to a new private file with profile opt-in, a 50 MiB cap and mandatory SHA-256 verification; scopes and email hash availability are unverified (guide pages 131-132)";
@@ -189,10 +195,12 @@ export declare const catalogue: {
     readonly "event list": {
         readonly description: "List security events with bounded scroll continuation (API guide pages 37-42)";
         readonly flags: {
+            readonly fields: `Comma-separated row fields: ${string}; or top-level events,count,total,complete,reason,cursor,expansion,help; default all`;
             readonly saas: "Comma-separated SaaS overrides; default selected profile saas or office365_emails";
             readonly "event-types": "Comma-separated event types; default unfiltered";
-            readonly "event-states": "Comma-separated event states; default unfiltered";
-            readonly severities: "Comma-separated severities; default unfiltered";
+            readonly "event-states": `Comma-separated event states: ${string}; default unfiltered`;
+            readonly states: "Alias for --event-states; cannot combine with --event-states";
+            readonly severities: "Nonempty comma-separated severity strings; vendor documents no fixed severity list; unrecognised severities can return an empty result; default unfiltered";
             readonly "event-ids": "Comma-separated event IDs; default unfiltered";
             readonly "confidence-indicator": "Confidence indicator selector; default unfiltered";
             readonly description: "Description selector; default unfiltered";
@@ -206,7 +214,6 @@ export declare const catalogue: {
             readonly cursor: string;
             readonly config: string;
             readonly profile: string;
-            readonly fields: string;
             readonly full: string;
             readonly help: string;
         };
@@ -250,11 +257,11 @@ export declare const catalogue: {
             readonly limit: string;
             readonly all: string;
             readonly cursor: string;
+            readonly fields: `Comma-separated row fields: ${string}; or top-level emails,count,total,complete,reason,cursor,expansion,help; default all`;
             readonly saas: "SaaS override; default selected profile saas or office365_emails";
             readonly "saas-entity": "Optional SaaS entity type selector";
             readonly config: string;
             readonly profile: string;
-            readonly fields: string;
             readonly full: string;
             readonly help: string;
         };

package/dist/src/catalogue.js

@@ -1,4 +1,5 @@
 import { exceptionFamilies } from "./exceptions.js";
+export const FILTER_OPERATORS = ["is", "contains", "startsWith", "isEmpty", "isNot", "notContains", "isNotEmpty", "greaterThan", "lessThan"];
 export const DESCRIPTION = "Inspect Check Point Email Security through compact, guarded AXI commands";
 export const SETUP_GUIDANCE = "Run checkpoint-axi config path; configure a region, clientId and clientSecret env/file SecretRef";
 export const TASK_WAIT_GUIDANCE = "Task show reads once by default; use task show <id> --wait --timeout 30 for bounded read-only polling.\n"
@@ -20,7 +21,9 @@ export const EMAIL_PAYLOAD_ATTRIBUTES = ["subject", "fromEmail", "attachmentCoun
 export const EMAIL_FILTER_GUIDANCE = "saasAttrName is a field path, not a closed enum (guide pages 19-20). Documented examples: "
     + EMAIL_PAYLOAD_ATTRIBUTES.slice(0, 3).join(", ") + ". Other documented email payload paths (pages 15-16, 24-25): "
     + EMAIL_PAYLOAD_ATTRIBUTES.slice(3).join(", ")
-    + ". saasAttrOp: is, contains, startsWith, isEmpty, isNot, notContains, isNotEmpty, greaterThan, lessThan. The guide defines operators globally, without a per-field compatibility matrix; examples pair fromEmail with is and attachmentCount with greaterThan. saasAttrValue is a string.";
+    + `. saasAttrOp: ${FILTER_OPERATORS.join(", ")}. The guide defines operators globally, without a per-field compatibility matrix; examples pair fromEmail with is and attachmentCount with greaterThan. saasAttrValue is a string.`;
+export const EVENT_STATES = ["new", "detected", "pending", "remediated", "dismissed", "exception"];
+export const LIST_ROW_FIELDS = { "email search": ["id", "subject", "state", "verdict"], "event list": ["id", "type", "state", "severity"] };
 const common = {
     config: "Config path; default CHECKPOINT_AXI_CONFIG or platform path",
     profile: "Profile name; default CHECKPOINT_AXI_PROFILE, env profile, config default, or sole profile",
@@ -91,10 +94,12 @@ export const catalogue = {
         flags: { ...common, type: exceptionType, items: "Click-time item route instead of list route; default false" },
         examples: ["checkpoint-axi exception show phishing-block <id>", "checkpoint-axi exception show url <value> --type allow-url", "checkpoint-axi exception show click-time <id> --items --full"] },
     "event list": { description: "List security events with bounded scroll continuation (API guide pages 37-42)", flags: { ...common, ...paging, ...expansion,
+            fields: `Comma-separated row fields: ${LIST_ROW_FIELDS["event list"].join(",")}; or top-level events,count,total,complete,reason,cursor,expansion,help; default all`,
             saas: "Comma-separated SaaS overrides; default selected profile saas or office365_emails",
             "event-types": "Comma-separated event types; default unfiltered",
-            "event-states": "Comma-separated event states; default unfiltered",
-            severities: "Comma-separated severities; default unfiltered",
+            "event-states": `Comma-separated event states: ${EVENT_STATES.join(", ")}; default unfiltered`,
+            states: "Alias for --event-states; cannot combine with --event-states",
+            severities: "Nonempty comma-separated severity strings; vendor documents no fixed severity list; unrecognised severities can return an empty result; default unfiltered",
             "event-ids": "Comma-separated event IDs; default unfiltered",
             "confidence-indicator": "Confidence indicator selector; default unfiltered",
             description: "Description selector; default unfiltered",
@@ -108,6 +113,7 @@ export const catalogue = {
             "wait-requests": "Total HTTP request cap including auth and retries; default 10, range 2-10; requires --wait",
         }, examples: ["checkpoint-axi task show <id>", "checkpoint-axi task show <id> --wait --timeout 30 --fields task,wait,help", "checkpoint-axi task show <id> --full"] },
     "email search": { description: "Search emails with a bounded date window and scroll continuation (API guide pages 18-27)", flags: { ...common,
+            fields: `Comma-separated row fields: ${LIST_ROW_FIELDS["email search"].join(",")}; or top-level emails,count,total,complete,reason,cursor,expansion,help; default all`,
             saas: "SaaS override; default selected profile saas or office365_emails",
             "saas-entity": "Optional SaaS entity type selector",
             ...paging, ...expansion,

package/dist/src/local-commands.js

@@ -1,7 +1,7 @@
 import { AxiError } from "axi-sdk-js";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
-import { catalogue, DESCRIPTION, help, SETUP_GUIDANCE } from "./catalogue.js";
+import { catalogue, DESCRIPTION, help, LIST_ROW_FIELDS, SETUP_GUIDANCE } from "./catalogue.js";
 import { doctor } from "./doctor.js";
 import { readCommand } from "./reads.js";
 import { exceptionCommand } from "./exceptions.js";
@@ -61,9 +61,14 @@ export async function localCommand(argv, store, transport) {
         available.splice(0, available.length, "outcome", "preview", "auditId", "tasks", "response", "responseSchema", "help");
     if (isDownload)
         available.splice(0, available.length, "path", "size", "sha256");
-    const fields = flags.get("--fields")?.split(",") ?? available;
-    if (fields.some((field) => !available.includes(field)) || new Set(fields).size !== fields.length)
-        usage();
+    const rowFields = name === "email search" || name === "event list" ? LIST_ROW_FIELDS[name] : [];
+    const requested = flags.get("--fields")?.split(",") ?? available;
+    const columns = requested.filter((field) => rowFields.includes(field));
+    if (requested.some((field) => !available.includes(field) && !rowFields.includes(field)) || new Set(requested).size !== requested.length
+        || (columns.length > 0 && columns.length !== requested.length)) {
+        usage(`Invalid --fields; valid top-level fields: ${available.join(",")}${rowFields.length ? `; valid row fields: ${rowFields.join(",")}` : ""}`);
+    }
+    const fields = columns.length ? available : requested;
     const config = flags.get("--config");
     let result;
     if (isDownload)
@@ -105,6 +110,10 @@ export async function localCommand(argv, store, transport) {
             description: DESCRIPTION, status, profiles: listed.profiles, count: listed.count,
             help: [SETUP_GUIDANCE, "Run checkpoint-axi auth status to validate local credentials", "Run checkpoint-axi profile list to inspect configured profiles"] };
     }
+    if (columns.length) {
+        const key = name === "event list" ? "events" : "emails";
+        result[key] = result[key].map((row) => Object.fromEntries(columns.map((field) => [field, row[field]])));
+    }
     let truncated = false;
     const preview = (value) => {
         if (typeof value === "string" && value.length > 500 && !flags.has("--full")) {

package/dist/src/reads.js

@@ -5,19 +5,20 @@ import { z } from "zod";
 import { REGIONS } from "./regions.js";
 import { gateway, READ_LIMITS } from "./transport.js";
 import { responseInvalid } from "./response-invalid.js";
+import { EVENT_STATES, FILTER_OPERATORS } from "./catalogue.js";
 const day = 86_400_000;
 const timestamp = z.iso.datetime({ offset: true });
 const filters = z.array(z.strictObject({ saasAttrName: z.string().min(1),
-    saasAttrOp: z.enum(["is", "contains", "startsWith", "isEmpty", "isNot", "notContains", "isNotEmpty", "greaterThan", "lessThan"]),
+    saasAttrOp: z.enum(FILTER_OPERATORS),
     saasAttrValue: z.string() }));
 const continuation = z.strictObject({ version: z.literal(1), binding: z.string(), start: timestamp, end: timestamp,
     scroll: z.string().optional(), offset: z.number().int().nonnegative(), replayRisk: z.literal(true).optional() });
 // The guide's prose/table (pp.11,14) says security-result array; its JSON examples use an object.
 const securityResults = z.object({ combinedVerdict: z.unknown().optional() }).passthrough();
 // Entity schemas and SaaS-specific payloads: guide pages 11-15 and 21-24.
-const entity = z.object({ entityInfo: z.object({ entityId: z.string().min(1), entityActionState: z.string().optional() }).passthrough(),
+const entity = z.object({ entityInfo: z.object({ entityId: z.string().min(1), entityActionState: z.string().nullish().transform((value) => value ?? "unactioned") }).passthrough(),
     entityPayload: z.object({ subject: z.string().optional() }).passthrough(),
-    entitySecurityResults: z.union([securityResults, z.array(z.object({}).passthrough())]).optional(),
+    entitySecurityResults: z.union([securityResults, z.array(securityResults)]).optional(),
 }).passthrough();
 // Event and task fields: guide pages 31-32, 35-36 and 40-41.
 const event = z.object({ eventId: z.string().min(1), type: z.string(), state: z.string(), severity: z.string() }).passthrough();
@@ -68,7 +69,7 @@ export async function readCommand(name, id, flags, store, transport) {
         }
         const parsed = filters.safeParse(raw);
         if (!parsed.success)
-            invalid("--filter must contain saasAttrName, a documented saasAttrOp and saasAttrValue");
+            invalid(`--filter must contain saasAttrName, saasAttrValue and saasAttrOp from: ${FILTER_OPERATORS.join(", ")}`);
         extended = parsed.data;
     }
     let cursor;
@@ -96,12 +97,19 @@ export async function readCommand(name, id, flags, store, transport) {
         if (flags.has(flag) && !flags.get(flag).trim())
             invalid(`${flag} must not be blank`);
     const eventSelectors = {};
+    if (flags.has("--states")) {
+        if (flags.has("--event-states"))
+            invalid("Use either --states or --event-states");
+        flags.set("--event-states", flags.get("--states"));
+    }
     for (const [flag, key] of [["event-types", "eventTypes"], ["event-states", "eventStates"], ["severities", "severities"], ["event-ids", "eventIds"], ["saas", "saas"]]) {
         if (!isEvent || !flags.has(`--${flag}`))
             continue;
         const values = flags.get(`--${flag}`).split(",").map((value) => value.trim());
         if (values.some((value) => !value))
-            invalid(`--${flag} must contain nonempty comma-separated values`);
+            invalid(`--${flag} must contain nonempty comma-separated ${flag === "severities" ? "severity strings" : "values"}`);
+        if (flag === "event-states" && values.some((value) => !EVENT_STATES.includes(value)))
+            invalid(`--event-states/--states must contain: ${EVENT_STATES.join(", ")}`);
         eventSelectors[key] = values;
     }
     for (const [flag, key] of [["confidence-indicator", "confidenceIndicator"], ["description", "description"]]) {
@@ -217,7 +225,9 @@ export async function readCommand(name, id, flags, store, transport) {
             }
             const value = entity.parse(record);
             return { id: value.entityInfo.entityId, subject: value.entityPayload.subject ?? "",
-                state: value.entityInfo.entityActionState ?? "", verdict: Array.isArray(value.entitySecurityResults) ? null : value.entitySecurityResults?.combinedVerdict ?? null };
+                state: value.entityInfo.entityActionState, verdict: Array.isArray(value.entitySecurityResults)
+                    ? value.entitySecurityResults.find((result) => result.combinedVerdict != null)?.combinedVerdict ?? null
+                    : value.entitySecurityResults?.combinedVerdict ?? null };
         }));
         offset += rows.length;
         if (offset < page.records.length) {

package/dist/src/transport.js

@@ -179,6 +179,12 @@ export function gateway(profile, credentials, redactor, dependencies = {}, mutat
                 throw failure("AUTH_FAILED", "API rejected authentication after one re-exchange");
             if (response.status === 429)
                 throw failure("RATE_LIMITED", "API rate limit remains after two read retries");
+            if (response.status === 404)
+                throw new AxiError("Requested resource was not found", "NOT_FOUND", ["Check the requested ID"]);
+            if (response.status === 422 && query.body === undefined) {
+                const id = decodeURIComponent(query.path.slice(query.path.lastIndexOf("/") + 1));
+                throw new AxiError(`API rejected requested ID ${id} (HTTP 422)`, "VALIDATION_ERROR", ["Check the requested ID and its format"]);
+            }
             if (response.status < 200 || response.status >= 300)
                 throw failure("HTTP_ERROR", `Regional API returned HTTP ${response.status}`);
             return decodePage(response.value, /^\/(sectools|sectool-exceptions)\//.test(query.path));

package/docs/agent-guide.md

@@ -97,7 +97,8 @@ checkpoint-axi email search --limit 5 --expand --expand-limit 3 --expand-request
 checkpoint-axi event list --limit 5 --expand --fields events,count,complete,cursor,expansion
 ```
 
---fields selects top-level output keys, not nested row columns: request emails or events together with count,total,complete,reason,cursor for lists, and email,event,task or exception for details.
+--fields selects top-level output keys: request emails or events together with count,total,complete,reason,cursor for lists, and email,event,task or exception for details.
+Email search also accepts row fields id,subject,state,verdict; event list accepts id,type,state,severity, retaining pagination metadata when selecting row fields.
 Email rows contain id,subject,state,verdict; event rows contain id,type,state,severity; documented exception rows contain id,sender,subject,comment.
 TOON strings preview at 500 characters; --full expands strings after redaction, while cursors are never truncated.
 

package/docs/commands.md

@@ -187,7 +187,7 @@ Search emails with a bounded date window and scroll continuation (API guide page
 |---|---|
 | `--config` | Config path; default CHECKPOINT_AXI_CONFIG or platform path |
 | `--profile` | Profile name; default CHECKPOINT_AXI_PROFILE, env profile, config default, or sole profile |
-| `--fields` | Comma-separated output fields; default all |
+| `--fields` | Comma-separated row fields: id,subject,state,verdict; or top-level emails,count,total,complete,reason,cursor,expansion,help; default all |
 | `--full` | Show full strings instead of 500-character previews; default false |
 | `--help` | Show concise command help; default false |
 | `--saas` | SaaS override; default selected profile saas or office365_emails |
@@ -255,7 +255,7 @@ List security events with bounded scroll continuation (API guide pages 37-42)
 |---|---|
 | `--config` | Config path; default CHECKPOINT_AXI_CONFIG or platform path |
 | `--profile` | Profile name; default CHECKPOINT_AXI_PROFILE, env profile, config default, or sole profile |
-| `--fields` | Comma-separated output fields; default all |
+| `--fields` | Comma-separated row fields: id,type,state,severity; or top-level events,count,total,complete,reason,cursor,expansion,help; default all |
 | `--full` | Show full strings instead of 500-character previews; default false |
 | `--help` | Show concise command help; default false |
 | `--start-date` | ISO timestamp with timezone; default 24 hours before end-date; maximum window 31 days |
@@ -268,8 +268,9 @@ List security events with bounded scroll continuation (API guide pages 37-42)
 | `--expand-requests` | Total HTTP request cap including auth, list pages, detail and retries; default 10, range 2-10; requires --expand |
 | `--saas` | Comma-separated SaaS overrides; default selected profile saas or office365_emails |
 | `--event-types` | Comma-separated event types; default unfiltered |
-| `--event-states` | Comma-separated event states; default unfiltered |
-| `--severities` | Comma-separated severities; default unfiltered |
+| `--event-states` | Comma-separated event states: new, detected, pending, remediated, dismissed, exception; default unfiltered |
+| `--states` | Alias for --event-states; cannot combine with --event-states |
+| `--severities` | Nonempty comma-separated severity strings; vendor documents no fixed severity list; unrecognised severities can return an empty result; default unfiltered |
 | `--event-ids` | Comma-separated event IDs; default unfiltered |
 | `--confidence-indicator` | Confidence indicator selector; default unfiltered |
 | `--description` | Description selector; default unfiltered |

package/docs/reads.md

@@ -20,6 +20,7 @@ Read sessions allow at most 10 HTTP requests; write sessions allow at most 44.
 Both are bounded by 8 MiB of JSON response bytes and 60 seconds, including auth, re-exchange, read retries and delays.
 Download bodies have a separate 50 MiB cap per response within the same request/time budgets.
 Reads retry HTTP 429 at most twice, honoring numeric or HTTP-date `Retry-After` within that budget.
+HTTP 404 reads return `NOT_FOUND`; HTTP 422 detail reads return `VALIDATION_ERROR` and identify the requested ID without printing server response data.
 Exception reads and writes share separate 1 request/second Anti-Phishing and 10 requests/second other-exception spacers.
 
 ## Email reads
@@ -43,11 +44,11 @@ Cursor strings are never truncated; email text is redacted before 500-character
 See [downloads](downloads.md) for private file output.
 
 The vendor PDF describes `entitySecurityResults` as an array in its prose/table (pages 11 and 14), while its JSON examples use an object.
-Both documented forms are accepted; detail preserves them, and search reports `verdict: null` for an array because no combined verdict object is documented there.
-Other response constraints remain unchanged.
+Both forms are accepted; search uses `combinedVerdict` from the object or the first array entry containing one, and reports `verdict: null` when none is available.
+Null or missing `entityActionState` within `entityInfo` is rendered as `unactioned` in search and detail.
 `RESPONSE_INVALID` diagnostics for these reads name failing JSON paths and received types, including `missing`, without response values.
 Non-identifier path keys appear as `<key>`.
-These diagnostics support owner commissioning; the actual failing fields behind TD-049's live unfiltered-search and spam-detail failures remain unverified.
+The reported unfiltered-search and spam-detail failures identified null action states; synthetic clean and spam fixtures exercise that shape offline.
 
 ## Event and task reads
 
@@ -70,10 +71,17 @@ Failures before any snapshot and non-budget read failures remain structured erro
 Use `--fields task,wait,help` to retain wait metadata and recovery guidance when projecting output.
 Waiting only repeats the existing task status GET; it never invokes an available action, downloads a file or resubmits the original mutation.
 Event list accepts comma-separated `--event-types`, `--event-states`, `--severities`, `--event-ids` and `--saas`, plus `--confidence-indicator` and `--description` text selectors.
+`--states` is an alias for `--event-states`; use one of these flags per command.
+States must be `new`, `detected`, `pending`, `remediated`, `dismissed` or `exception`, as defined by the vendor Swagger 1.50 `EventState` schema.
+The vendor Swagger defines severities as an array of strings with no format, min/max constraints or fixed severity list, so the CLI validates nonempty comma-separated severity strings.
+Unrecognised severities can return an empty result.
 SaaS defaults to the selected profile's value or `office365_emails`; other event selectors default to unfiltered.
 Event list uses the same date windows, row and transport budgets, bound continuation and honest page replay flags as [email search](reads.md#email-reads).
 Repeat all original event selectors with `--cursor`; the cursor preserves the original date window.
 Event and task text is redacted before 500-character previews; use `--full` for full strings and `--fields` to select top-level fields.
+Email search also accepts row fields `id,subject,state,verdict`; event list accepts `id,type,state,severity`.
+For example, `email search --fields id,subject` narrows each email row while retaining pagination metadata.
+Existing top-level projections such as `--fields emails,count,cursor` remain supported; mixed row and top-level selections are rejected, and errors list both valid sets.
 For writes, see [event actions](writes.md#event-actions).
 These reads are verified offline with synthetic fixtures; authentication, token lifetime and live API behavior require manual verification.
 
@@ -103,6 +111,7 @@ Budget and per-item failures also include a safe error `code`; raw upstream erro
 Budget exhaustion stops further detail attempts; an individual HTTP, response-validation or other read failure records that item and continues within the caps.
 List `complete`, `reason` and `cursor` still describe pagination; `complete` inside `expansion` independently describes whether every returned row was expanded.
 With `--fields`, include `expansion` alongside `emails` or `events` so omissions remain visible.
+Row field selections retain expansion metadata but omit each row's `detail`; use a top-level projection to inspect expanded payloads.
 Expansion performs no writes, actions, downloads, cross-resource pivots or task waiting.
 
 ## Exception reads

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowttl/checkpoint-axi",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Inspect Check Point Email Security through compact, guarded AXI commands",
   "license": "MIT",
   "type": "module",