pixellint 0.40.0 → 0.42.0

package/README.md

@@ -57,6 +57,7 @@ finding.targets[0];       // { component: "whole_url", start: 0, end: 46, ... }
 | --- | --- |
 | `validate(artifact, options?)` | The full validation summary |
 | `validateMany(document)` | Document report for extracted artifacts |
+| `validateSessions(request, options?)` | Explicit ad-session findings, document report and relationship coverage |
 | `isOk(summary)` | `false` when any error-severity finding is present |
 | `rulepacks()` | Every rulepack with its evidence level |
 | `vendors()` | The vendor endpoint directory |
@@ -76,6 +77,14 @@ The capture binds payload checks to the destination and adds method and header
 contracts. See [the HTTP capture schema](https://github.com/aleksUIX/pixellint/blob/main/docs/HTTP_REQUEST_SCHEMA.md)
 for representation limits and repeated fields.
 
+`validateSessions` accepts the [session schema](https://github.com/aleksUIX/pixellint/blob/main/docs/SESSION_SCHEMA.md)
+as an object or raw JSON string. The caller supplies actual session membership
+using original zero-based artifact indexes. Options include `at` as a safe
+integer Unix clock, `rulepacks` and `exceptRulepacks`. The initial IAS UVP
+profile checks external-ID consistency and uniqueness. Inspect both
+`report.summary.errors` and `report.coverage` when deciding whether the observed
+relationships were fully evaluated.
+
 `vast` takes a tracking URL extracted from VAST and enables the IAB VAST
 macro-name checks. It does not accept a VAST XML document.
 

package/index.cjs

@@ -35,6 +35,7 @@ function isOk(summary) {
 module.exports = {
   validate,
   validateMany,
+  validateSessions,
   importHar,
   validateHar,
   isOk,
@@ -43,3 +44,17 @@ module.exports = {
   vendorForHost: (host) => wasm.vendor_for_host(host),
   version: () => wasm.version(),
 };
+
+/** Validate caller-declared ad sessions. Grouping is never inferred. */
+function validateSessions(request, options = {}) {
+  if (!options || typeof options !== "object" || Array.isArray(options)) throw new TypeError("Session options must be an object");
+  for (const key of Object.keys(options)) {
+    if (!["at", "rulepacks", "exceptRulepacks"].includes(key)) throw new TypeError(`Unknown session option: ${key}`);
+  }
+  if (Object.hasOwn(options, "at") && !Number.isSafeInteger(options.at)) throw new TypeError("Session clock must be safe integer Unix seconds");
+  const wire = {};
+  if (Object.hasOwn(options, "at")) wire.at = options.at;
+  if (Object.hasOwn(options, "rulepacks")) wire.rulepacks = options.rulepacks;
+  if (Object.hasOwn(options, "exceptRulepacks")) wire.except_rulepacks = options.exceptRulepacks;
+  return wasm.validate_sessions(typeof request === "string" ? request : JSON.stringify(request), JSON.stringify(wire));
+}

package/index.d.ts

@@ -221,3 +221,19 @@ export function importHar(har: string | object, options?: HarOptions): HarImport
 
 /** Validate local HAR requests at their recorded clocks. Missing clocks require an explicit at override. */
 export function validateHar(har: string | object, options?: HarValidateOptions): HarReport;
+
+export interface SessionGroup { session_id: string; artifact_indexes: number[]; }
+export interface SessionRequest { document: DocumentRequest; sessions: SessionGroup[]; }
+export type SessionRuleKind = "consistent_parameter" | "unique_parameter_across_sessions";
+export type SessionEvaluationStatus = "evaluated" | "partially_evaluated" | "not_evaluated";
+export type SessionSkipReason = "pack_not_selected" | "unsupported_artifact" | "invalid_url" | "endpoint_mismatch" | "missing_parameter" | "empty_parameter" | "installation_placeholder" | "unresolved_macro" | "conflicting_values" | "invalid_percent_encoding" | "invalid_utf8";
+export interface SessionQuerySpan { component: "query_param"; name: string; value: string; start: number; end: number; }
+export interface SessionArtifactTarget { artifact_index: number; artifact_id: string; session_id: string; query_spans: SessionQuerySpan[]; occurrences: ArtifactOccurrence[]; }
+export interface SessionFinding extends Omit<Violation, "targets"> { plugin_id: string; detected_vendor: string | null; session_ids: string[]; targets: SessionArtifactTarget[]; }
+export interface SessionSkippedArtifact { artifact_index: number; artifact_id: string; session_id: string; reason: SessionSkipReason; occurrences: ArtifactOccurrence[]; }
+export interface SessionCheckCoverage { plugin_id: string; code: string; kind: SessionRuleKind; session_ids: string[]; status: SessionEvaluationStatus; participants_total: number; compared_total: number; reason?: "insufficient_observations"; skipped: SessionSkippedArtifact[]; }
+export interface SessionCoverage { status: SessionEvaluationStatus; sessions_total: number; grouped_artifacts: number; ungrouped_artifact_indexes: number[]; profiles_total: number; checks_evaluated: number; checks_partially_evaluated: number; checks_not_evaluated: number; }
+export interface SessionReport { document: DocumentReport; summary: FindingCounts; relationship_summary: FindingCounts; findings: SessionFinding[]; checks: SessionCheckCoverage[]; coverage: SessionCoverage; }
+export interface SessionValidateOptions { at?: number; rulepacks?: string[]; exceptRulepacks?: string[]; }
+/** Explicit grouping only. Show coverage with combined finding counts. */
+export function validateSessions(request: SessionRequest | string, options?: SessionValidateOptions): SessionReport;

package/index.mjs

@@ -72,3 +72,17 @@ export function isOk(summary) {
     report.violations.every((violation) => violation.severity !== "error"),
   );
 }
+
+/** Validate caller-declared ad sessions. Grouping is never inferred. */
+export function validateSessions(request, options = {}) {
+  if (!options || typeof options !== "object" || Array.isArray(options)) throw new TypeError("Session options must be an object");
+  for (const key of Object.keys(options)) {
+    if (!["at", "rulepacks", "exceptRulepacks"].includes(key)) throw new TypeError(`Unknown session option: ${key}`);
+  }
+  if (Object.hasOwn(options, "at") && !Number.isSafeInteger(options.at)) throw new TypeError("Session clock must be safe integer Unix seconds");
+  const wire = {};
+  if (Object.hasOwn(options, "at")) wire.at = options.at;
+  if (Object.hasOwn(options, "rulepacks")) wire.rulepacks = options.rulepacks;
+  if (Object.hasOwn(options, "exceptRulepacks")) wire.except_rulepacks = options.exceptRulepacks;
+  return wasm.validate_sessions(typeof request === "string" ? request : JSON.stringify(request), JSON.stringify(wire));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixellint",
-  "version": "0.40.0",
+  "version": "0.42.0",
   "description": "Validator for pixels, postbacks, conversion API payloads, and tracking URLs: Meta CAPI, Facebook pixel, GTM, and vendor rulepacks",
   "license": "Apache-2.0",
   "author": "Aleks <aleks@vastlint.org>",

package/wasm/pixellint.d.ts

@@ -28,6 +28,11 @@ export function validate_har(har_json: string, header_policy: string, reference_
  */
 export function validate_many(document_json: string): any;
 
+/**
+ * Validate explicitly grouped URL rows with optional clock and pack selection.
+ */
+export function validate_sessions(session_json: string, options_json?: string | null): any;
+
 /**
  * Validates a URL artifact with default options, the common case.
  */

package/wasm/pixellint.js

@@ -95,6 +95,25 @@ function validate_many(document_json) {
 }
 exports.validate_many = validate_many;
 
+/**
+ * Validate explicitly grouped URL rows with optional clock and pack selection.
+ * @param {string} session_json
+ * @param {string | null} [options_json]
+ * @returns {any}
+ */
+function validate_sessions(session_json, options_json) {
+    const ptr0 = passStringToWasm0(session_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    var ptr1 = isLikeNone(options_json) ? 0 : passStringToWasm0(options_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    var len1 = WASM_VECTOR_LEN;
+    const ret = wasm.validate_sessions(ptr0, len0, ptr1, len1);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+exports.validate_sessions = validate_sessions;
+
 /**
  * Validates a URL artifact with default options, the common case.
  * @param {string} artifact
@@ -190,7 +209,7 @@ function __wbg_get_imports() {
             const ret = new Object();
             return ret;
         },
-        __wbg_now_5e729ff042c6a974: function() {
+        __wbg_now_cff8dc08ed8d60a6: function() {
             const ret = Date.now();
             return ret;
         },

package/wasm/pixellint_bg.wasm.d.ts

@@ -6,6 +6,7 @@ export const rulepacks: () => [number, number, number];
 export const validate: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => [number, number, number];
 export const validate_har: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
 export const validate_many: (a: number, b: number) => [number, number, number];
+export const validate_sessions: (a: number, b: number, c: number, d: number) => [number, number, number];
 export const validate_url: (a: number, b: number) => [number, number, number];
 export const vendor_for_host: (a: number, b: number) => [number, number, number];
 export const vendors: () => [number, number, number];