@agent-score/commerce 1.8.0 → 2.0.0

package/dist/identity/policy.d.ts

@@ -1,5 +1,5 @@
 import { DenialReason, AgentScoreCoreOptions } from '../core.js';
-import '../signer-CFVQsWjL.js';
+import '../signer-3FAit11j.js';
 
 /**
  * Per-product / per-tier compliance policy helpers.
@@ -19,7 +19,7 @@ import '../signer-CFVQsWjL.js';
  * This module ships three primitives:
  *
  * 1. {@link PolicyBlock} — the typed shape.
- * 2. {@link buildGateOptionsFromPolicy} — translate a block into the options object the
+ * 2. {@link buildGateFromPolicy} — translate a block into the options object the
  *    per-framework `agentscoreGate(...)` accepts. Returns `null` when the policy
  *    has no enforcement (treat as "no gate; anonymous OK").
  * 3. {@link runGateWithEnforcement} — wrap a per-framework middleware in the
@@ -72,7 +72,7 @@ interface GateResult {
  * when the policy varies per resource (e.g. per product). Each adapter's gate
  * is cheap to instantiate.
  */
-declare function buildGateOptionsFromPolicy(policy: PolicyBlock | null | undefined, base: {
+declare function buildGateFromPolicy(policy: PolicyBlock | null | undefined, base: {
     apiKey: string;
     baseUrl?: string;
 }): AgentScoreCoreOptions | null;
@@ -111,5 +111,42 @@ declare function shippingCountryAllowed(country: string, policy: PolicyBlock | n
  * {@link shippingCountryAllowed} independently.
  */
 declare function shippingStateAllowed(state: string, country: string, policy: PolicyBlock | null | undefined): boolean;
+/**
+ * Throw {@link CheckoutValidationError} when shipping isn't allowed by the policy.
+ *
+ * One-call replacement for the
+ *
+ *     if (!shippingCountryAllowed(...)) throw new CheckoutValidationError(...);
+ *     if (!shippingStateAllowed(...))   throw new CheckoutValidationError(...);
+ *
+ * boilerplate every goods merchant writes in their `preValidate` hook.
+ *
+ * `policy` is a {@link PolicyBlock} (or `null`/`undefined`); NULL policy means
+ * "ship anywhere" and the function is a no-op. The reason a location is
+ * excluded is **merchant-defined**: it might be regulatory (regulated goods
+ * + state allowlist), operational (no fulfillment partner), or commercial
+ * (fragility, fraud-rate-by-region, etc.) — the helper doesn't assume.
+ *
+ * `productName` is the user-facing item name surfaced in the error message
+ * ("Cannot ship 'Wine 2020' to NY ..."). Omit for a generic message.
+ *
+ * `errorCode` and `errorAction` let merchants override the canonical denial
+ * codes if their consumer agents expect different shapes.
+ *
+ * `countryMessage` / `stateMessage` override the default messages verbatim
+ * (use these when the default phrasing isn't right for your consumer agents
+ * — e.g. you want to surface the regulatory reason explicitly, or you want
+ * the message in a different language).
+ */
+declare function validateShippingAgainstPolicy(opts: {
+    country: string;
+    state: string;
+    policy: PolicyBlock | null | undefined;
+    productName?: string;
+    errorCode?: string;
+    errorAction?: string;
+    countryMessage?: string;
+    stateMessage?: string;
+}): void;
 
-export { type EnforcementMode, type GateResult, type IdentityStatus, type PolicyBlock, buildGateOptionsFromPolicy, runGateWithEnforcement, shippingCountryAllowed, shippingStateAllowed };
+export { type EnforcementMode, type GateResult, type IdentityStatus, type PolicyBlock, buildGateFromPolicy, runGateWithEnforcement, shippingCountryAllowed, shippingStateAllowed, validateShippingAgainstPolicy };