@adcp/sdk 17.0.0-beta.6 → 17.0.0-beta.7

package/dist/lib/testing/storyboard/required-metric-filters.mjs

@@ -0,0 +1,104 @@
+const CONTAINERS = {
+  viewable_rate: "viewability",
+  viewable_impressions: "viewability",
+  measurable_impressions: "viewability",
+  viewed_seconds: "viewability",
+  quartile_25: "quartile_data",
+  quartile_50: "quartile_data",
+  quartile_75: "quartile_data",
+  quartile_100: "quartile_data"
+};
+const DERIVED_FROM = {
+  ctr: ["clicks", "impressions"],
+  completion_rate: ["completed_views", "impressions"],
+  roas: ["conversion_value", "spend"],
+  cost_per_acquisition: ["spend", "conversions"],
+  cost_per_click: ["spend", "clicks"],
+  cost_per_completed_view: ["spend", "completed_views"],
+  cpm: ["spend", "impressions"],
+  viewable_rate: ["viewable_impressions", "measurable_impressions"]
+};
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function metricAvailable(metric, declared) {
+  if (declared.has(metric)) return true;
+  const container = Object.hasOwn(CONTAINERS, metric) ? CONTAINERS[metric] : void 0;
+  if (container && declared.has(container)) return true;
+  const derivation = Object.hasOwn(DERIVED_FROM, metric) ? DERIVED_FROM[metric] : void 0;
+  return derivation?.every((dependency) => metricAvailable(dependency, declared)) ?? false;
+}
+function vendorMetricMatches(actual, required) {
+  const entry = record(actual);
+  if (!entry || required.metric_id !== void 0 && entry.metric_id !== required.metric_id) return false;
+  const vendor = record(required.vendor);
+  if (!vendor) return true;
+  const actualVendor = record(entry.vendor);
+  if (!actualVendor) return false;
+  return actualVendor.domain === vendor.domain && (vendor.brand_id === void 0 || actualVendor.brand_id === vendor.brand_id);
+}
+const requiredMetricFiltersAssertion = {
+  id: "discovery.required_metric_filters",
+  default: true,
+  description: "Every returned product satisfies all requested standard and vendor metric filters.",
+  onStep(_ctx, step) {
+    if (step.skipped || step.task !== "get_products") return [];
+    const request = record(step.request?.payload);
+    const filters = record(request?.filters);
+    const required = Array.isArray(filters?.required_metrics) ? filters.required_metrics.filter((metric) => typeof metric === "string") : [];
+    const requiredVendors = Array.isArray(filters?.required_vendor_metrics) ? filters.required_vendor_metrics.flatMap((value) => {
+      const entry = record(value);
+      return entry && (typeof entry.metric_id === "string" || typeof record(entry.vendor)?.domain === "string") ? [entry] : [];
+    }) : [];
+    if (required.length === 0 && requiredVendors.length === 0) return [];
+    const raw = record(step.response ?? step.response_record?.payload);
+    const response = Array.isArray(raw?.products) ? raw : record(raw?.data) ?? raw;
+    if (!Array.isArray(response?.products) || response.products.length === 0) return [];
+    const reportingProjectedAway = Array.isArray(request?.fields) && !request.fields.includes("reporting_capabilities");
+    const findings = [];
+    for (const [index, value] of response.products.entries()) {
+      const product = record(value);
+      if (!product) continue;
+      if (reportingProjectedAway && product.reporting_capabilities === void 0) {
+        findings.push({
+          passed: true,
+          status: "not_applicable",
+          step_id: step.step_id,
+          description: `products[${index}]: required metric filter compatibility is unproven because reporting_capabilities was projected away`
+        });
+        continue;
+      }
+      const capabilities = record(product.reporting_capabilities);
+      const declared = /* @__PURE__ */ new Set(["impressions", "spend"]);
+      if (Array.isArray(capabilities?.available_metrics)) {
+        for (const metric of capabilities.available_metrics) if (typeof metric === "string") declared.add(metric);
+      }
+      const missing = required.filter((metric) => !metricAvailable(metric, declared));
+      if (required.length > 0)
+        findings.push({
+          passed: missing.length === 0,
+          step_id: step.step_id,
+          description: `products[${index}] must satisfy every filters.required_metrics entry`,
+          ...missing.length > 0 && {
+            error: `products[${index}] does not declare required metrics ${JSON.stringify(missing)}`
+          }
+        });
+      const vendorMetrics = Array.isArray(capabilities?.vendor_metrics) ? capabilities.vendor_metrics : [];
+      for (const [filterIndex, vendor] of requiredVendors.entries()) {
+        const matched = vendorMetrics.some((actual) => vendorMetricMatches(actual, vendor));
+        findings.push({
+          passed: matched,
+          step_id: step.step_id,
+          description: `products[${index}] must satisfy filters.required_vendor_metrics[${filterIndex}] on one declared vendor metric`,
+          ...!matched && {
+            error: `products[${index}] has no vendor metric matching filters.required_vendor_metrics[${filterIndex}]`
+          }
+        });
+      }
+    }
+    return findings;
+  }
+};
+export {
+  requiredMetricFiltersAssertion
+};

package/dist/lib/testing/storyboard/runner.js

@@ -1145,6 +1145,7 @@ function buildPhaseCapabilitySkippedSteps(storyboard, phase, detail, context) {
 }
 const REQUIREMENT_TO_SKIP_REASON = {
   controller: "missing_test_controller",
+  collect_product_pages_runner: "requirement_unmet",
   seeded_state: "requirement_unmet",
   real_wire: "requirement_unmet",
   webhook_receiver: "requirement_unmet",
@@ -1278,6 +1279,8 @@ async function checkRequires(requires, storyboard, options, profile, precomputed
       continue;
     }
     switch (requirement) {
+      case "collect_product_pages_runner":
+        break;
       case "controller": {
         if (!options.agentTools) continue;
         if (!options.agentTools.includes("comply_test_controller")) {
@@ -3511,6 +3514,11 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
       }
       assignment ??= dispatch.nextFor(step);
       const stepExecutionState = buildExecutionState(assignment.agentUrl, assignment.profile);
+      stepExecutionState.onCollectedProductPage = async (page, pageIndex) => {
+        const observed = await applyStepAssertions(step, page, assertions, assertionContexts, pageIndex);
+        assertionResults.push(...observed);
+        if (observed.some((assertion) => !assertion.passed)) assertionsFailed = true;
+      };
       if (routingContext) {
         let probes = routedPriorProbes.get(assignment.instanceIndex);
         if (!probes) {
@@ -3628,45 +3636,10 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
       }
       stepResults.push(result2);
       priorStepResults.set(step.id, result2);
-      const schemaInvalidResponse = result2.validations.some(
-        (v) => v.check === "response_schema" && (0, import_validations.validationFailsStep)(v)
-      );
-      const rateLimitTripNotApplicable = result2.skipped === true && result2.skip_reason === "rate_limit_not_triggered";
-      for (const spec of assertions) {
-        if (!spec.onStep) continue;
-        if ((0, import_assertions.stepDisablesAssertion)(step.invariants, spec.id)) continue;
-        if (schemaInvalidResponse) {
-          result2.validations.push({
-            check: "assertion",
-            passed: true,
-            description: `${spec.id}: skipped \u2014 response failed schema validation (adcp-client#1709)`
-          });
-          continue;
-        }
-        const raw = await spec.onStep(assertionContexts.get(spec.id), {
-          ...result2,
-          context: withoutProtectedCaptures(result2.context ?? {})
-        });
-        for (const r of raw) {
-          const full = { ...r, assertion_id: spec.id, scope: "step", step_id: step.id };
-          assertionResults.push(full);
-          if (!rateLimitTripNotApplicable) {
-            result2.validations.push({
-              check: "assertion",
-              passed: r.passed,
-              description: `${spec.id}: ${r.description}`,
-              ...r.error !== void 0 && { error: r.error }
-            });
-          }
-          if (r.hint) {
-            const existing = result2.hints ?? [];
-            result2.hints = [...existing, r.hint];
-          }
-          if (!r.passed) {
-            if (!rateLimitTripNotApplicable) result2.passed = false;
-            assertionsFailed = true;
-          }
-        }
+      if (!result2.product_page_collection) {
+        const observedAssertions = await applyStepAssertions(step, result2, assertions, assertionContexts);
+        assertionResults.push(...observedAssertions);
+        if (observedAssertions.some((assertion) => !assertion.passed)) assertionsFailed = true;
       }
       if (step.task === "protected_resource_metadata") {
         if (result2.skipped && result2.skip_reason === "oauth_not_advertised") {
@@ -4848,6 +4821,18 @@ async function runStoryboardStepBody(agentUrl, storyboard, stepId, options) {
         }
       }
     }
+    if (found.step.collect_product_pages) {
+      const pageAssertions = (0, import_assertions.resolveAssertions)(storyboard.invariants);
+      const pageContexts = /* @__PURE__ */ new Map();
+      for (const spec of pageAssertions) {
+        const assertionContext = { storyboard, agentUrl, options, state: {} };
+        pageContexts.set(spec.id, assertionContext);
+        if (spec.onStart) await spec.onStart(assertionContext);
+      }
+      runState.onCollectedProductPage = async (page, pageIndex) => {
+        await applyStepAssertions(found.step, page, pageAssertions, pageContexts, pageIndex);
+      };
+    }
     const result = prerequisiteFailure ?? await executeStep(client, found.step, storyboard.id, found.phaseId, context, allSteps, options, runState);
     if (!result.skipped && result.passed && found.step.contributes_to) {
       if (evalContributesIf(found.step.contributes_if, /* @__PURE__ */ new Map())) {
@@ -4866,6 +4851,82 @@ async function runStoryboardStepBody(agentUrl, storyboard, stepId, options) {
     ]);
   }
 }
+async function applyStepAssertions(step, result, assertions, assertionContexts, pageIndex) {
+  const findings = [];
+  const schemaInvalid = result.validations.some((v) => v.check === "response_schema" && (0, import_validations.validationFailsStep)(v));
+  const rateSkip = result.skipped === true && result.skip_reason === "rate_limit_not_triggered";
+  for (const spec of assertions) {
+    if (!spec.onStep || (0, import_assertions.stepDisablesAssertion)(step.invariants, spec.id)) continue;
+    if (schemaInvalid) {
+      result.validations.push({
+        check: "assertion",
+        passed: true,
+        description: `${spec.id}: skipped \u2014 response failed schema validation (adcp-client#1709)`
+      });
+      continue;
+    }
+    const raw = await spec.onStep(assertionContexts.get(spec.id), {
+      ...result,
+      context: withoutProtectedCaptures(result.context ?? {})
+    });
+    for (const observed of raw) {
+      const description = `${pageIndex === void 0 ? "" : `[physical page ${pageIndex}] `}${observed.description}`;
+      findings.push({ ...observed, description, assertion_id: spec.id, scope: "step", step_id: step.id });
+      if (!rateSkip)
+        result.validations.push({
+          check: "assertion",
+          passed: observed.passed,
+          description: `${spec.id}: ${description}`,
+          ...observed.error !== void 0 && { error: observed.error },
+          ...pageIndex !== void 0 && !observed.passed && { request: result.request, response: result.response_record ?? null }
+        });
+      if (observed.hint) result.hints = [...result.hints ?? [], observed.hint];
+      if (!observed.passed && !rateSkip) result.passed = false;
+    }
+  }
+  return findings;
+}
+function productPageStepResult(step, phaseId, context, page, schemaVersion) {
+  const failedSchema = page.schemaFailure;
+  return {
+    step_id: step.id,
+    phase_id: phaseId,
+    task: "get_products",
+    title: step.title,
+    passed: page.schema_validated && page.result?.success === true,
+    duration_ms: page.response?.duration_ms ?? 0,
+    request: page.request,
+    ...page.response && { response_record: page.response },
+    response: (0, import_redact_secrets.redactSecrets)(page.result?.data),
+    extraction: page.extraction,
+    context,
+    validations: failedSchema ? [
+      {
+        check: "response_schema",
+        passed: false,
+        description: `Physical product page ${page.page_index} satisfies the get_products response schema`,
+        error: failedSchema.detail,
+        json_pointer: null,
+        expected: failedSchema.schema_id,
+        actual: "schema_validation_failed",
+        schema_id: failedSchema.schema_id,
+        schema_url: failedSchema.schema_url,
+        request: page.request,
+        response: page.response,
+        strict: { valid: false, variant: "sync" }
+      }
+    ] : page.schema_validated ? [
+      {
+        check: "response_schema",
+        passed: true,
+        description: `Physical product page ${page.page_index} satisfies the get_products response schema`,
+        schema_id: `/schemas/${schemaVersion}/media-buy/get-products-response.json`,
+        schema_url: `https://adcontextprotocol.org/schemas/${schemaVersion}/media-buy/get-products-response.json`,
+        ...page.strict_schema_validated && { strict: { valid: true, variant: "sync" } }
+      }
+    ] : []
+  };
+}
 function unresolvedStepContextVars(step, request, context, runState) {
   const unavailableInputs = (step.context_inputs ?? []).filter(
     (input) => !Object.hasOwn(context, input.key) && (runState.capabilityUnavailableContextKeys?.has(input.key) === true || runState.missingPrerequisiteContextKeys?.has(input.key) === true)
@@ -5318,6 +5379,34 @@ async function executeStep(client, step, storyboardId, phaseId, context, allStep
     };
   }
   const useRawProbe = rawProbeHeaders !== void 0 && !useSdkAuthOverride;
+  if (step.collect_product_pages && (useRawProbe || request.buying_mode !== "wholesale" || Object.hasOwn(request, "idempotency_key") || request.pagination !== null && typeof request.pagination === "object" && "cursor" in request.pagination || ["if_none_match", "if_wholesale_feed_version", "if_pricing_version"].some((field) => request[field] !== void 0))) {
+    const detail = "collect_product_pages requires fresh unkeyed reads and an unconditional wholesale first page through the official SDK client";
+    return {
+      step_id: step.id,
+      phase_id: phaseId,
+      task: step.task,
+      title: step.title,
+      passed: false,
+      duration_ms: 0,
+      context,
+      extraction: { path: "none" },
+      error: detail,
+      validations: [
+        {
+          check: "product_page_collection",
+          passed: false,
+          description: detail,
+          json_pointer: null,
+          expected: "unkeyed unconditional wholesale query",
+          actual: (0, import_redact_secrets.redactSecrets)(request),
+          schema_id: null,
+          schema_url: null,
+          request: null,
+          response: null
+        }
+      ]
+    };
+  }
   const stepClient = () => authOverrideClient ?? client;
   let taskResult;
   let stepResult;
@@ -5327,6 +5416,10 @@ async function executeStep(client, step, storyboardId, phaseId, context, allStep
   let requestUrl;
   let a2aEnvelope;
   let crossResponses;
+  let productPageCollection;
+  let collectedPageValidations = [];
+  let actualCollectedResponse;
+  let collectedRequestRecord;
   if (step.parallel_dispatch && !useRawProbe) {
     const contractsInScope = new Set(options.contracts ?? []);
     if (!contractsInScope.has(import_parallel_dispatch.PARALLEL_DISPATCH_CONTRACT)) {
@@ -5495,7 +5588,96 @@ async function executeStep(client, step, storyboardId, phaseId, context, allStep
   } else {
     const captureA2a = options.protocol === "a2a";
     let a2aCaptures;
-    if (step.parallel_dispatch) {
+    if (step.collect_product_pages) {
+      const started = Date.now();
+      const pages = [];
+      const pageValidations = [];
+      let pagesPassed = true;
+      const collection = await (0, import_seeding.collectWholesaleProductPages)(stepClient(), options, request, {
+        retainRestartEvidence: true,
+        dispatch: (pageRequest) => (0, import_task_map.executeStoryboardTask)(stepClient(), effectiveStep.task, pageRequest, {
+          skipIdempotencyAutoInject: testsIdempotencyKeyOmission,
+          skipAccountValidation: testsMissingAccount,
+          skipRequestValidation: testsSchemaInvalidRequest,
+          preserveGovernedPayload: governedRequest,
+          responseProjection,
+          mediaBuyLifecycleCompatibility: options.mediaBuyLifecycleCompatibility,
+          signal: options.signal
+        }),
+        onPage: async (observation) => {
+          const physical = productPageStepResult(
+            step,
+            phaseId,
+            context,
+            observation,
+            options._serverAdcpVersion ?? options.adcpVersion ?? import_version.ADCP_VERSION
+          );
+          await runState.onCollectedProductPage?.(physical, observation.page_index);
+          pagesPassed &&= physical.passed;
+          pageValidations.push(...physical.validations);
+          const page = {
+            page_index: observation.page_index,
+            restart_count: observation.restart_count,
+            request: observation.request,
+            response: observation.response,
+            extraction: observation.extraction,
+            schema_validated: observation.schema_validated
+          };
+          if (pages.length >= 16 && page.response) {
+            page.response = {
+              ...page.response,
+              payload: {
+                response_not_retained: "Physical page was checked; response evidence exceeded the 16-page retention budget."
+              }
+            };
+          }
+          pages.push(page);
+        }
+      });
+      if (options.signal?.aborted) options.signal.throwIfAborted();
+      const logical = collection.ok ? {
+        ...collection.catalog.firstPage.result.data,
+        products: collection.catalog.products,
+        ...collection.catalog.errors.length > 0 && { errors: collection.catalog.errors }
+      } : void 0;
+      if (logical) delete logical.pagination;
+      productPageCollection = {
+        complete: collection.ok,
+        page_count: pages.length,
+        restart_count: pages.reduce((maximum, page) => Math.max(maximum, page.restart_count), 0),
+        pages,
+        ...logical && { logical_response: (0, import_redact_secrets.redactSecrets)(logical) }
+      };
+      collectedRequestRecord = collection.ok ? collection.catalog.firstPage.request : collection.exchange?.request;
+      const observedResponse = collection.ok ? collection.catalog.firstPage.response : collection.exchange?.response;
+      responseRecord = observedResponse ?? void 0;
+      actualCollectedResponse = collection.ok ? collection.catalog.firstPage.result.data : collection.exchange?.response?.payload;
+      taskResult = collection.ok ? { ...collection.catalog.firstPage.result, data: logical } : {
+        success: false,
+        error: collection.error.replace(/^fixture discovery/, "Product page collection")
+      };
+      stepResult = {
+        duration_ms: Date.now() - started,
+        passed: collection.ok && pagesPassed,
+        ...!collection.ok && { error: collection.error.replace(/^fixture discovery/, "Product page collection") }
+      };
+      collectedPageValidations = pageValidations;
+      if (!collection.ok && !pageValidations.some((validation) => (0, import_validations.validationFailsStep)(validation))) {
+        collectedPageValidations.push({
+          check: "product_page_collection",
+          passed: false,
+          description: "Wholesale collection completes one stable, duplicate-free feed",
+          error: collection.error,
+          json_pointer: null,
+          expected: "a complete stable wholesale collection",
+          actual: collection.error,
+          schema_id: null,
+          schema_url: null,
+          ...collection.exchange?.request && { request: collection.exchange.request },
+          response: collection.exchange?.response ?? null
+        });
+      }
+    } else if (step.parallel_dispatch) {
       const started = Date.now();
       crossResponses = await (0, import_parallel_dispatch.runParallelDispatches)(stepClient(), effectiveStep.task, request, {
         spec: step.parallel_dispatch,
@@ -5583,7 +5765,7 @@ async function executeStep(client, step, storyboardId, phaseId, context, allStep
   const requestRecord = {
     transport: options.protocol === "a2a" ? "a2a" : "mcp",
     operation: effectiveStep.task,
-    payload: (0, import_redact_secrets.redactSecrets)(request),
+    payload: collectedRequestRecord?.payload ?? (0, import_redact_secrets.redactSecrets)(request),
     ...effectiveRequestUrl ? { url: (0, import_oauth_metadata_graph.redactOAuthUrlForOutput)(effectiveRequestUrl) } : {}
   };
   const inputSchemaStripNotices = collectInputSchemaFieldStripNotices(
@@ -5771,9 +5953,9 @@ async function executeStep(client, step, storyboardId, phaseId, context, allStep
     success: true,
     data: schemaValidationError.data
   } : void 0);
-  let validations = [];
+  let validations = [...collectedPageValidations];
   if (step.validations?.length && (validationTaskResult || httpResult)) {
-    const resolvedValidations = step.validations.map((v) => {
+    const resolvedValidations = step.validations.filter((v) => !productPageCollection || v.check !== "response_schema").map((v) => {
       const resolved = { ...v };
       if (resolved.value !== void 0) {
         resolved.value = (0, import_context.injectContext)({ __v: resolved.value }, context, runState.runnerVars).__v;
@@ -5830,9 +6012,11 @@ async function executeStep(client, step, storyboardId, phaseId, context, allStep
         };
       })()
     };
-    validations = (0, import_validations.runValidations)(
-      resolvedValidations.filter((validation) => validation.check !== "property_list_reference"),
-      vctx
+    validations.push(
+      ...(0, import_validations.runValidations)(
+        resolvedValidations.filter((validation) => validation.check !== "property_list_reference"),
+        vctx
+      )
     );
     for (const validation of resolvedValidations.filter((validation2) => validation2.check === "property_list_reference")) {
       const result = effectiveStep.task !== "create_property_list" || !validationTaskResult?.success ? {
@@ -6102,6 +6286,14 @@ async function executeStep(client, step, storyboardId, phaseId, context, allStep
       }
     }
   }
+  if (productPageCollection) {
+    for (const validation of validations) {
+      if (collectedPageValidations.includes(validation)) continue;
+      if (validation.json_pointer)
+        validation.json_pointer = `/product_page_collection/logical_response${validation.json_pointer}`;
+      validation.description = `[logical product collection] ${validation.description ?? validation.check}`;
+    }
+  }
   if (protectedViolations.length > 0) validations.push(...protectedViolations);
   const allValidationsPassedFinal = validations.every((v) => !(0, import_validations.validationFailsStep)(v));
   const stepFailed = !(passed && allValidationsPassedFinal);
@@ -6131,7 +6323,8 @@ async function executeStep(client, step, storyboardId, phaseId, context, allStep
     // Legacy `response` field (new code reads `response_record`).
     // Redact in case a downstream consumer still keys off it; the
     // modern `response_record.payload` path is already redacted.
-    response: (0, import_redact_secrets.redactSecrets)(taskResult?.data),
+    response: (0, import_redact_secrets.redactSecrets)(productPageCollection ? actualCollectedResponse : taskResult?.data),
+    ...productPageCollection && { product_page_collection: productPageCollection },
     validations,
     // NOT projected here: the full runner threads this map from step to
     // step, so stripping the reserved namespace would break the very
@@ -6155,7 +6348,10 @@ async function executeStep(client, step, storyboardId, phaseId, context, allStep
     next,
     request: requestRecord,
     ...responseRecord && { response_record: responseRecord },
-    extraction: extractionFromTaskResult(taskResult),
+    extraction: productPageCollection ? {
+      path: "none",
+      note: "Authored checks and context use product_page_collection.logical_response; response_record remains an actual physical page."
+    } : extractionFromTaskResult(taskResult),
     ...inputSchemaStripNotices.length > 0 && { notices: inputSchemaStripNotices },
     ...hints.length > 0 && { hints }
   };