@agent-score/commerce 1.0.0

package/dist/core.d.mts

@@ -0,0 +1,252 @@
+interface AgentIdentity {
+    address?: string;
+    operatorToken?: string;
+}
+/**
+ * Session metadata returned from `POST /v1/sessions`. Surfaced to the `onBeforeSession`
+ * hook so merchants can correlate an AgentScore session with their own resume token
+ * (e.g. a pending-order id).
+ */
+interface SessionMetadata {
+    session_id: string;
+    verify_url: string;
+    poll_secret: string;
+    poll_url: string;
+    expires_at?: string;
+}
+/**
+ * Configuration for auto-creating a verification session when no identity is present.
+ *
+ * The static `context` / `productName` options are sent on every session request. For
+ * per-request context (e.g. the specific product the agent was trying to buy), pass
+ * a `getSessionOptions` callback that returns dynamic values; its return is merged
+ * over the static defaults.
+ *
+ * `onBeforeSession` is a side-effect hook that runs after the session is minted but
+ * before the 403 is built. Use it to pre-create a reservation/draft/pending-order
+ * row in your DB so agents can resume via a merchant-specific id. Return value is
+ * merged into `DenialReason.extra`, so it surfaces in both the default 403 body and
+ * in a custom `onDenied` handler.
+ */
+interface CreateSessionOnMissing<TCtx = unknown> {
+    apiKey: string;
+    baseUrl?: string;
+    context?: string;
+    productName?: string;
+    /** Per-request override of `context` / `productName`. Invoked with the framework context. */
+    getSessionOptions?: (ctx: TCtx) => Promise<{
+        context?: string;
+        productName?: string;
+    }> | {
+        context?: string;
+        productName?: string;
+    };
+    /** Side-effect hook that runs after the session is minted. Return value is merged
+     *  into `DenialReason.extra` so custom `onDenied` handlers can include merchant-specific
+     *  fields (e.g. `order_id`) in the 403 response. Hook errors are logged and swallowed —
+     *  a failing side effect should not block the 403 from reaching the agent. */
+    onBeforeSession?: (ctx: TCtx, session: SessionMetadata) => Promise<Record<string, unknown>> | Record<string, unknown>;
+}
+interface AgentScoreCoreOptions {
+    /** AgentScore API key. Required. */
+    apiKey: string;
+    /** Require KYC verification. */
+    requireKyc?: boolean;
+    /** Require operator to be clear of sanctions. */
+    requireSanctionsClear?: boolean;
+    /** Minimum operator age bracket (18 or 21). */
+    minAge?: number;
+    /** List of blocked jurisdictions (blocklist). */
+    blockedJurisdictions?: string[];
+    /** List of allowed jurisdictions (allowlist — only these pass). */
+    allowedJurisdictions?: string[];
+    /** If true, allow the request through when the API is unreachable. Defaults to false. */
+    failOpen?: boolean;
+    /** How long to cache results, in seconds. Defaults to 300. */
+    cacheSeconds?: number;
+    /** AgentScore API base URL. Defaults to "https://api.agentscore.sh". */
+    baseUrl?: string;
+    /** Optional chain to filter scoring to. */
+    chain?: string;
+    /** Prepended to the default User-Agent as `"{userAgent} (@agent-score/commerce@{version})"`. Use to attribute API calls to your app. */
+    userAgent?: string;
+    /** When set and no identity is found, create a verification session instead of denying immediately. */
+    createSessionOnMissing?: CreateSessionOnMissing;
+}
+type DenialCode = 'wallet_not_trusted' | 'missing_identity' | 'api_error' | 'payment_required' | 'identity_verification_required' | 'wallet_signer_mismatch' | 'wallet_auth_requires_wallet_signing' | 'token_expired' | 'invalid_credential';
+/**
+ * Cross-merchant pattern hint emitted on bootstrap denials and session-create responses.
+ * LLM-hosted agents should persist this to long-term memory so future AgentScore encounters skip
+ * the cold-start session flow. Contents are the pattern, not secrets.
+ */
+interface AgentMemoryHint {
+    save_for_future_agentscore_gates: true;
+    pattern_summary: string;
+    quickstart: string;
+    identity_check_endpoint: string;
+    list_wallets_endpoint?: string;
+    identity_paths: {
+        wallet: string;
+        operator_token: string;
+    };
+    bootstrap: string;
+    do_not_persist_in_memory: string[];
+    persist_in_credential_store: string[];
+}
+interface DenialReason {
+    code: DenialCode;
+    /** Human-readable explanation. When omitted, `denialReasonToBody` substitutes a per-code default. */
+    message?: string;
+    decision?: string;
+    reasons?: string[];
+    verify_url?: string;
+    session_id?: string;
+    poll_secret?: string;
+    poll_url?: string;
+    agent_instructions?: string;
+    /** Cross-merchant memory hint. Emitted on bootstrap denials only by default. */
+    agent_memory?: AgentMemoryHint;
+    /** Full assess response when the denial came from `/v1/assess`. Lets consumers access fields
+     *  not promoted to first-class DenialReason properties (e.g., `policy_result`). Undefined for
+     *  denials that did not originate from an assess call (missing_identity, api_error,
+     *  payment_required, identity_verification_required). */
+    data?: AgentScoreData;
+    /** Extra fields returned from the `createSessionOnMissing.onBeforeSession` hook. Merged
+     *  into the default 403 body; custom `onDenied` handlers can spread these into their own
+     *  response shape (e.g. to include a merchant-minted `order_id`). */
+    extra?: Record<string, unknown>;
+    /** Operator id resolved from `X-Wallet-Address`. */
+    claimed_operator?: string;
+    /** Operator id the actual payment signer resolves to. `null` when the signer wallet isn't
+     *  linked to any operator (treat as a different identity). */
+    actual_signer_operator?: string | null;
+    /** The wallet the agent claimed via header. Echoed back for self-correction. */
+    expected_signer?: string;
+    /** The wallet that actually signed the payment. */
+    actual_signer?: string;
+    /** Wallets the claimed operator could sign with (if enumerable). Present when non-empty. */
+    linked_wallets?: string[];
+}
+interface AgentScoreData {
+    decision: string | null;
+    decision_reasons: string[];
+    identity_method?: string;
+    operator_verification?: {
+        level: string;
+        operator_type: string | null;
+        verified_at: string | null;
+    };
+    /** Account-level KYC facts that apply to every operator under the same account.
+     *  Populated when the API returns account_verification (post-KYC operator). */
+    account_verification?: {
+        kyc_level?: string;
+        sanctions_clear?: boolean;
+        age_bracket?: string;
+        jurisdiction?: string;
+        verified_at?: string | null;
+    };
+    resolved_operator?: string | null;
+    /** Wallets linked to the same operator as the resolved identity. Capped at 100 entries
+     *  by the API. Useful for advertising in 402 challenges so wallet-auth agents know which
+     *  alt-signers will satisfy `wallet_signer_mismatch`. */
+    linked_wallets?: string[];
+    verify_url?: string;
+    policy_result?: {
+        all_passed: boolean;
+        checks: Array<{
+            rule: string;
+            passed: boolean;
+            required?: unknown;
+            actual?: unknown;
+        }>;
+    } | null;
+}
+/**
+ * Outcome from `AgentScoreCore.evaluate()`. Adapters map this to framework-specific responses.
+ *
+ * - `{ kind: 'allow', data }` — the request passed the policy. `data` is present on a normal
+ *   allow; `undefined` when fail-open short-circuited (identity missing, API unreachable,
+ *   timeout, or 402 paid-tier required).
+ * - `{ kind: 'deny', reason }` — the request was denied. Adapters should render a 403 with the
+ *   reason, or invoke the caller's custom denial handler.
+ */
+type EvaluateOutcome = {
+    kind: 'allow';
+    data?: AgentScoreData;
+} | {
+    kind: 'deny';
+    reason: DenialReason;
+};
+interface CaptureWalletOptions {
+    /** Operator credential (`opc_...`) that the agent authenticated with. */
+    operatorToken: string;
+    /** Signer wallet recovered from the payment payload. */
+    walletAddress: string;
+    /** Key-derivation family — `"evm"` for any EVM chain, `"solana"` for Solana. */
+    network: 'evm' | 'solana';
+    /** Optional stable key for the logical payment (e.g., payment intent id, tx hash). When the
+     *  same key is seen again for the same (credential, wallet, network), the server no-ops —
+     *  prevents agent retries from inflating transaction_count. */
+    idempotencyKey?: string;
+}
+interface VerifyWalletSignerMatchOptions {
+    /** The wallet claimed via `X-Wallet-Address`. */
+    claimedWallet: string;
+    /** The signer wallet recovered from the payment credential. `null` means the rail carries
+     *  no wallet signer (SPT, card) — the helper returns `wallet_auth_requires_wallet_signing`. */
+    signer: string | null;
+    /** Network of the signer. EVM covers every EVM chain; `solana` lives in its own namespace. */
+    network?: 'evm' | 'solana';
+}
+type VerifyWalletSignerResult = {
+    kind: 'pass';
+    claimedOperator: string | null;
+    signerOperator: string | null;
+} | {
+    kind: 'wallet_signer_mismatch';
+    claimedOperator: string | null;
+    actualSignerOperator: string | null;
+    expectedSigner: string;
+    actualSigner: string;
+    linkedWallets: string[];
+    /** JSON-encoded action copy (action + steps + user_message). Spread into the 403 body
+     *  verbatim so agents get a concrete recovery path inside the denial response itself. */
+    agentInstructions: string;
+} | {
+    kind: 'wallet_auth_requires_wallet_signing';
+    claimedWallet: string;
+    agentInstructions: string;
+} | {
+    kind: 'api_error';
+    claimedWallet: string;
+};
+interface AgentScoreCore {
+    /**
+     * Evaluate the request's identity against the configured policy.
+     * @param identity - extracted identity (wallet address and/or operator token)
+     * @param ctx - optional framework-specific context (Hono c, Express req, etc.) passed
+     *   through to `createSessionOnMissing` hooks. Opaque to core.
+     */
+    evaluate(identity: AgentIdentity | undefined, ctx?: unknown): Promise<EvaluateOutcome>;
+    /** Report a wallet seen paying under an operator credential. Fire-and-forget; silently
+     *  swallows non-fatal errors because capture is informational, not on the critical path. */
+    captureWallet(options: CaptureWalletOptions): Promise<void>;
+    /**
+     * Verify the payment signer resolves to the same operator as the claimed `X-Wallet-Address`.
+     *
+     * Returns `pass` when the signer is linked to the same operator as the claimed wallet
+     * (byte-equal wallets pass trivially; other wallets linked to the same operator also pass —
+     * multi-wallet agents work without ergonomic pain). Returns `wallet_signer_mismatch` when
+     * the signer resolves to a different (or no) operator. Returns `wallet_auth_requires_wallet_signing`
+     * when the signer is `null` (SPT, card — rails that carry no wallet signature).
+     *
+     * Call this AFTER the gate evaluates (so the claimed wallet's operator is cached) and
+     * AFTER the payment credential is parsed (so the signer is known). Merchants should call
+     * it before settling payment.
+     */
+    verifyWalletSignerMatch(options: VerifyWalletSignerMatchOptions): Promise<VerifyWalletSignerResult>;
+}
+declare function buildAgentMemoryHint(): AgentMemoryHint;
+declare function createAgentScoreCore(options: AgentScoreCoreOptions): AgentScoreCore;
+
+export { type AgentIdentity, type AgentMemoryHint, type AgentScoreCore, type AgentScoreCoreOptions, type AgentScoreData, type CaptureWalletOptions, type CreateSessionOnMissing, type DenialCode, type DenialReason, type EvaluateOutcome, type SessionMetadata, type VerifyWalletSignerMatchOptions, type VerifyWalletSignerResult, buildAgentMemoryHint, createAgentScoreCore };

package/dist/core.d.ts

@@ -0,0 +1,252 @@
+interface AgentIdentity {
+    address?: string;
+    operatorToken?: string;
+}
+/**
+ * Session metadata returned from `POST /v1/sessions`. Surfaced to the `onBeforeSession`
+ * hook so merchants can correlate an AgentScore session with their own resume token
+ * (e.g. a pending-order id).
+ */
+interface SessionMetadata {
+    session_id: string;
+    verify_url: string;
+    poll_secret: string;
+    poll_url: string;
+    expires_at?: string;
+}
+/**
+ * Configuration for auto-creating a verification session when no identity is present.
+ *
+ * The static `context` / `productName` options are sent on every session request. For
+ * per-request context (e.g. the specific product the agent was trying to buy), pass
+ * a `getSessionOptions` callback that returns dynamic values; its return is merged
+ * over the static defaults.
+ *
+ * `onBeforeSession` is a side-effect hook that runs after the session is minted but
+ * before the 403 is built. Use it to pre-create a reservation/draft/pending-order
+ * row in your DB so agents can resume via a merchant-specific id. Return value is
+ * merged into `DenialReason.extra`, so it surfaces in both the default 403 body and
+ * in a custom `onDenied` handler.
+ */
+interface CreateSessionOnMissing<TCtx = unknown> {
+    apiKey: string;
+    baseUrl?: string;
+    context?: string;
+    productName?: string;
+    /** Per-request override of `context` / `productName`. Invoked with the framework context. */
+    getSessionOptions?: (ctx: TCtx) => Promise<{
+        context?: string;
+        productName?: string;
+    }> | {
+        context?: string;
+        productName?: string;
+    };
+    /** Side-effect hook that runs after the session is minted. Return value is merged
+     *  into `DenialReason.extra` so custom `onDenied` handlers can include merchant-specific
+     *  fields (e.g. `order_id`) in the 403 response. Hook errors are logged and swallowed —
+     *  a failing side effect should not block the 403 from reaching the agent. */
+    onBeforeSession?: (ctx: TCtx, session: SessionMetadata) => Promise<Record<string, unknown>> | Record<string, unknown>;
+}
+interface AgentScoreCoreOptions {
+    /** AgentScore API key. Required. */
+    apiKey: string;
+    /** Require KYC verification. */
+    requireKyc?: boolean;
+    /** Require operator to be clear of sanctions. */
+    requireSanctionsClear?: boolean;
+    /** Minimum operator age bracket (18 or 21). */
+    minAge?: number;
+    /** List of blocked jurisdictions (blocklist). */
+    blockedJurisdictions?: string[];
+    /** List of allowed jurisdictions (allowlist — only these pass). */
+    allowedJurisdictions?: string[];
+    /** If true, allow the request through when the API is unreachable. Defaults to false. */
+    failOpen?: boolean;
+    /** How long to cache results, in seconds. Defaults to 300. */
+    cacheSeconds?: number;
+    /** AgentScore API base URL. Defaults to "https://api.agentscore.sh". */
+    baseUrl?: string;
+    /** Optional chain to filter scoring to. */
+    chain?: string;
+    /** Prepended to the default User-Agent as `"{userAgent} (@agent-score/commerce@{version})"`. Use to attribute API calls to your app. */
+    userAgent?: string;
+    /** When set and no identity is found, create a verification session instead of denying immediately. */
+    createSessionOnMissing?: CreateSessionOnMissing;
+}
+type DenialCode = 'wallet_not_trusted' | 'missing_identity' | 'api_error' | 'payment_required' | 'identity_verification_required' | 'wallet_signer_mismatch' | 'wallet_auth_requires_wallet_signing' | 'token_expired' | 'invalid_credential';
+/**
+ * Cross-merchant pattern hint emitted on bootstrap denials and session-create responses.
+ * LLM-hosted agents should persist this to long-term memory so future AgentScore encounters skip
+ * the cold-start session flow. Contents are the pattern, not secrets.
+ */
+interface AgentMemoryHint {
+    save_for_future_agentscore_gates: true;
+    pattern_summary: string;
+    quickstart: string;
+    identity_check_endpoint: string;
+    list_wallets_endpoint?: string;
+    identity_paths: {
+        wallet: string;
+        operator_token: string;
+    };
+    bootstrap: string;
+    do_not_persist_in_memory: string[];
+    persist_in_credential_store: string[];
+}
+interface DenialReason {
+    code: DenialCode;
+    /** Human-readable explanation. When omitted, `denialReasonToBody` substitutes a per-code default. */
+    message?: string;
+    decision?: string;
+    reasons?: string[];
+    verify_url?: string;
+    session_id?: string;
+    poll_secret?: string;
+    poll_url?: string;
+    agent_instructions?: string;
+    /** Cross-merchant memory hint. Emitted on bootstrap denials only by default. */
+    agent_memory?: AgentMemoryHint;
+    /** Full assess response when the denial came from `/v1/assess`. Lets consumers access fields
+     *  not promoted to first-class DenialReason properties (e.g., `policy_result`). Undefined for
+     *  denials that did not originate from an assess call (missing_identity, api_error,
+     *  payment_required, identity_verification_required). */
+    data?: AgentScoreData;
+    /** Extra fields returned from the `createSessionOnMissing.onBeforeSession` hook. Merged
+     *  into the default 403 body; custom `onDenied` handlers can spread these into their own
+     *  response shape (e.g. to include a merchant-minted `order_id`). */
+    extra?: Record<string, unknown>;
+    /** Operator id resolved from `X-Wallet-Address`. */
+    claimed_operator?: string;
+    /** Operator id the actual payment signer resolves to. `null` when the signer wallet isn't
+     *  linked to any operator (treat as a different identity). */
+    actual_signer_operator?: string | null;
+    /** The wallet the agent claimed via header. Echoed back for self-correction. */
+    expected_signer?: string;
+    /** The wallet that actually signed the payment. */
+    actual_signer?: string;
+    /** Wallets the claimed operator could sign with (if enumerable). Present when non-empty. */
+    linked_wallets?: string[];
+}
+interface AgentScoreData {
+    decision: string | null;
+    decision_reasons: string[];
+    identity_method?: string;
+    operator_verification?: {
+        level: string;
+        operator_type: string | null;
+        verified_at: string | null;
+    };
+    /** Account-level KYC facts that apply to every operator under the same account.
+     *  Populated when the API returns account_verification (post-KYC operator). */
+    account_verification?: {
+        kyc_level?: string;
+        sanctions_clear?: boolean;
+        age_bracket?: string;
+        jurisdiction?: string;
+        verified_at?: string | null;
+    };
+    resolved_operator?: string | null;
+    /** Wallets linked to the same operator as the resolved identity. Capped at 100 entries
+     *  by the API. Useful for advertising in 402 challenges so wallet-auth agents know which
+     *  alt-signers will satisfy `wallet_signer_mismatch`. */
+    linked_wallets?: string[];
+    verify_url?: string;
+    policy_result?: {
+        all_passed: boolean;
+        checks: Array<{
+            rule: string;
+            passed: boolean;
+            required?: unknown;
+            actual?: unknown;
+        }>;
+    } | null;
+}
+/**
+ * Outcome from `AgentScoreCore.evaluate()`. Adapters map this to framework-specific responses.
+ *
+ * - `{ kind: 'allow', data }` — the request passed the policy. `data` is present on a normal
+ *   allow; `undefined` when fail-open short-circuited (identity missing, API unreachable,
+ *   timeout, or 402 paid-tier required).
+ * - `{ kind: 'deny', reason }` — the request was denied. Adapters should render a 403 with the
+ *   reason, or invoke the caller's custom denial handler.
+ */
+type EvaluateOutcome = {
+    kind: 'allow';
+    data?: AgentScoreData;
+} | {
+    kind: 'deny';
+    reason: DenialReason;
+};
+interface CaptureWalletOptions {
+    /** Operator credential (`opc_...`) that the agent authenticated with. */
+    operatorToken: string;
+    /** Signer wallet recovered from the payment payload. */
+    walletAddress: string;
+    /** Key-derivation family — `"evm"` for any EVM chain, `"solana"` for Solana. */
+    network: 'evm' | 'solana';
+    /** Optional stable key for the logical payment (e.g., payment intent id, tx hash). When the
+     *  same key is seen again for the same (credential, wallet, network), the server no-ops —
+     *  prevents agent retries from inflating transaction_count. */
+    idempotencyKey?: string;
+}
+interface VerifyWalletSignerMatchOptions {
+    /** The wallet claimed via `X-Wallet-Address`. */
+    claimedWallet: string;
+    /** The signer wallet recovered from the payment credential. `null` means the rail carries
+     *  no wallet signer (SPT, card) — the helper returns `wallet_auth_requires_wallet_signing`. */
+    signer: string | null;
+    /** Network of the signer. EVM covers every EVM chain; `solana` lives in its own namespace. */
+    network?: 'evm' | 'solana';
+}
+type VerifyWalletSignerResult = {
+    kind: 'pass';
+    claimedOperator: string | null;
+    signerOperator: string | null;
+} | {
+    kind: 'wallet_signer_mismatch';
+    claimedOperator: string | null;
+    actualSignerOperator: string | null;
+    expectedSigner: string;
+    actualSigner: string;
+    linkedWallets: string[];
+    /** JSON-encoded action copy (action + steps + user_message). Spread into the 403 body
+     *  verbatim so agents get a concrete recovery path inside the denial response itself. */
+    agentInstructions: string;
+} | {
+    kind: 'wallet_auth_requires_wallet_signing';
+    claimedWallet: string;
+    agentInstructions: string;
+} | {
+    kind: 'api_error';
+    claimedWallet: string;
+};
+interface AgentScoreCore {
+    /**
+     * Evaluate the request's identity against the configured policy.
+     * @param identity - extracted identity (wallet address and/or operator token)
+     * @param ctx - optional framework-specific context (Hono c, Express req, etc.) passed
+     *   through to `createSessionOnMissing` hooks. Opaque to core.
+     */
+    evaluate(identity: AgentIdentity | undefined, ctx?: unknown): Promise<EvaluateOutcome>;
+    /** Report a wallet seen paying under an operator credential. Fire-and-forget; silently
+     *  swallows non-fatal errors because capture is informational, not on the critical path. */
+    captureWallet(options: CaptureWalletOptions): Promise<void>;
+    /**
+     * Verify the payment signer resolves to the same operator as the claimed `X-Wallet-Address`.
+     *
+     * Returns `pass` when the signer is linked to the same operator as the claimed wallet
+     * (byte-equal wallets pass trivially; other wallets linked to the same operator also pass —
+     * multi-wallet agents work without ergonomic pain). Returns `wallet_signer_mismatch` when
+     * the signer resolves to a different (or no) operator. Returns `wallet_auth_requires_wallet_signing`
+     * when the signer is `null` (SPT, card — rails that carry no wallet signature).
+     *
+     * Call this AFTER the gate evaluates (so the claimed wallet's operator is cached) and
+     * AFTER the payment credential is parsed (so the signer is known). Merchants should call
+     * it before settling payment.
+     */
+    verifyWalletSignerMatch(options: VerifyWalletSignerMatchOptions): Promise<VerifyWalletSignerResult>;
+}
+declare function buildAgentMemoryHint(): AgentMemoryHint;
+declare function createAgentScoreCore(options: AgentScoreCoreOptions): AgentScoreCore;
+
+export { type AgentIdentity, type AgentMemoryHint, type AgentScoreCore, type AgentScoreCoreOptions, type AgentScoreData, type CaptureWalletOptions, type CreateSessionOnMissing, type DenialCode, type DenialReason, type EvaluateOutcome, type SessionMetadata, type VerifyWalletSignerMatchOptions, type VerifyWalletSignerResult, buildAgentMemoryHint, createAgentScoreCore };