@oobe-protocol-labs/sap-mcp-server 0.9.16 → 0.9.20

package/dist/policy/permission-checks.js

@@ -1,8 +1,24 @@
 /**
- * Permission checks
+ * @name policy/permission-checks
+ * @description Permission validation utilities for SAP MCP tool calls.
+ *
+ * Provides functions to check whether a given permission or tool name
+ * is allowed by the server configuration's `allowedTools` list.
+ *
+ * @module policy/permission-checks
  */
 /**
- * Check if permission is allowed
+ * @name checkPermission
+ * @description Check if a specific permission is allowed by the configuration.
+ *
+ * When `allowedTools` is `'all'`, every permission is allowed. Otherwise the
+ * permission must appear in the `allowedTools` array.
+ *
+ * @param config - The SAP MCP server configuration.
+ * @param permission - The permission string to check.
+ * @returns An object with `allowed` flag and optional `reason` string.
+ *
+ * @usedBy `checkToolAllowed`
  */
 export function checkPermission(config, permission) {
     // Check if allowed tools is 'all'
@@ -19,7 +35,17 @@ export function checkPermission(config, permission) {
     };
 }
 /**
- * Check if tool is allowed
+ * @name checkToolAllowed
+ * @description Check if a tool is allowed by mapping its name to a permission.
+ *
+ * Extracts the action and category from the tool name, maps them to a
+ * `SapPermission` string, then delegates to `checkPermission`.
+ *
+ * @param config - The SAP MCP server configuration.
+ * @param toolName - The tool name to check (e.g., `sap_get_agent`).
+ * @returns An object with `allowed` flag and optional `reason` string.
+ *
+ * @usedBy `policy-engine.ts:PolicyEngine`
  */
 export function checkToolAllowed(config, toolName) {
     if (config.allowedTools === 'all') {

package/dist/policy/permission-checks.js.map

@@ -1 +1 @@
-{"version":3,"file":"permission-checks.js","sourceRoot":"","sources":["../../src/policy/permission-checks.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;GAEG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAoB,EACpB,UAAyB;IAEzB,kCAAkC;IAClC,IAAI,MAAM,CAAC,YAAY,KAAK,KAAK,EAAE,CAAC;QAClC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3B,CAAC;IAED,yCAAyC;IACzC,IAAI,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QAC7C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3B,CAAC;IAED,OAAO;QACL,OAAO,EAAE,KAAK;QACd,MAAM,EAAE,cAAc,UAAU,+BAA+B;KAChE,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAoB,EACpB,QAAgB;IAEhB,IAAI,MAAM,CAAC,YAAY,KAAK,KAAK,EAAE,CAAC;QAClC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3B,CAAC;IAED,2EAA2E;IAC3E,MAAM,UAAU,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IAElD,OAAO,eAAe,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAC7C,CAAC;AAED;;GAEG;AACH,SAAS,oBAAoB,CAAC,QAAgB;IAC5C,6FAA6F;IAC7F,MAAM,WAAW,GAAG,QAAQ,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAEjD,uEAAuE;IACvE,MAAM,aAAa,GAAG,QAAQ,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IACnD,MAAM,QAAQ,GAAG,aAAa,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAEvD,uCAAuC;IACvC,MAAM,WAAW,GAA2B;QAC1C,UAAU,EAAE,UAAU;QACtB,UAAU,EAAE,UAAU;QACtB,YAAY,EAAE,YAAY;QAC1B,SAAS,EAAE,UAAU;QACrB,YAAY,EAAE,YAAY;QAC1B,QAAQ,EAAE,QAAQ;QAClB,aAAa,EAAE,aAAa;QAC5B,MAAM,EAAE,UAAU;QAClB,WAAW,EAAE,UAAU;QACvB,WAAW,EAAE,YAAY;KAC1B,CAAC;IAEF,MAAM,kBAAkB,GAAG,WAAW,CAAC,QAAQ,CAAC,IAAI,UAAU,CAAC;IAC/D,MAAM,OAAO,GAAG,CAAC,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IACrK,MAAM,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;IAElD,OAAO,GAAG,kBAAkB,IAAI,cAAc,EAAmB,CAAC;AACpE,CAAC"}
+{"version":3,"file":"permission-checks.js","sourceRoot":"","sources":["../../src/policy/permission-checks.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAoB,EACpB,UAAyB;IAEzB,kCAAkC;IAClC,IAAI,MAAM,CAAC,YAAY,KAAK,KAAK,EAAE,CAAC;QAClC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3B,CAAC;IAED,yCAAyC;IACzC,IAAI,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QAC7C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3B,CAAC;IAED,OAAO;QACL,OAAO,EAAE,KAAK;QACd,MAAM,EAAE,cAAc,UAAU,+BAA+B;KAChE,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAoB,EACpB,QAAgB;IAEhB,IAAI,MAAM,CAAC,YAAY,KAAK,KAAK,EAAE,CAAC;QAClC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3B,CAAC;IAED,2EAA2E;IAC3E,MAAM,UAAU,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IAElD,OAAO,eAAe,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAC7C,CAAC;AAED;;GAEG;AACH,SAAS,oBAAoB,CAAC,QAAgB;IAC5C,6FAA6F;IAC7F,MAAM,WAAW,GAAG,QAAQ,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAEjD,uEAAuE;IACvE,MAAM,aAAa,GAAG,QAAQ,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IACnD,MAAM,QAAQ,GAAG,aAAa,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAEvD,uCAAuC;IACvC,MAAM,WAAW,GAA2B;QAC1C,UAAU,EAAE,UAAU;QACtB,UAAU,EAAE,UAAU;QACtB,YAAY,EAAE,YAAY;QAC1B,SAAS,EAAE,UAAU;QACrB,YAAY,EAAE,YAAY;QAC1B,QAAQ,EAAE,QAAQ;QAClB,aAAa,EAAE,aAAa;QAC5B,MAAM,EAAE,UAAU;QAClB,WAAW,EAAE,UAAU;QACvB,WAAW,EAAE,YAAY;KAC1B,CAAC;IAEF,MAAM,kBAAkB,GAAG,WAAW,CAAC,QAAQ,CAAC,IAAI,UAAU,CAAC;IAC/D,MAAM,OAAO,GAAG,CAAC,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IACrK,MAAM,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;IAElD,OAAO,GAAG,kBAAkB,IAAI,cAAc,EAAmB,CAAC;AACpE,CAAC"}

package/dist/policy/policy-engine.d.ts

@@ -1,5 +1,12 @@
 /**
- * Policy engine for enforcing permissions and limits
+ * @name policy/policy-engine
+ * @description High-level policy engine for enforcing permissions and spend limits.
+ *
+ * Wraps the local and hybrid policy engines, loads default policies, and
+ * provides a unified API for permission validation, spend-limit checks,
+ * and runtime diagnostics.
+ *
+ * @module policy/policy-engine
  */
 import type { SapMcpConfig, SapPolicy, SapPermission } from '../core/types.js';
 interface PermissionContext {
@@ -11,7 +18,20 @@ interface PermissionContext {
     user?: string;
 }
 /**
- * Policy engine class
+ * @name PolicyEngine
+ * @description High-level policy engine combining default policies, config-based limits, and hybrid enforcement.
+ *
+ * Loads default policies at construction time, creates a `HybridPolicyEngine`
+ * when configured, and exposes permission validation, spend-limit checks,
+ * policy CRUD, and runtime status diagnostics.
+ *
+ * @method validatePermissions  — Validate a list of permission strings against the allowed-tools config.
+ * @method checkPermission       — Check whether a single permission and optional context is allowed.
+ * @method getRuntimeStatus      — Return current hybrid/Bento policy status for diagnostics.
+ * @method getPolicy             — Retrieve a registered policy by id.
+ * @method addPolicy             — Register a custom policy.
+ *
+ * @usedBy `server.ts`, `core/context.ts`
  */
 export declare class PolicyEngine {
     private config;

package/dist/policy/policy-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"policy-engine.d.ts","sourceRoot":"","sources":["../../src/policy/policy-engine.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAO/E,UAAU,iBAAiB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,kBAAkB,CAA4B;gBAE1C,MAAM,EAAE,YAAY;IAiBhC;;OAEG;IACG,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QACxD,KAAK,EAAE,OAAO,CAAC;QACf,WAAW,EAAE,aAAa,EAAE,CAAC;QAC7B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;KACnB,CAAC;IAmBF;;OAEG;IACG,eAAe,CACnB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAqCjD;;OAEG;IACH,gBAAgB,IAAI;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,eAAe,EAAE,OAAO,CAAC;QACzB,cAAc,EAAE,OAAO,CAAC;QACxB,iBAAiB,EAAE,OAAO,CAAC;KAC5B;IAaD,OAAO,CAAC,wBAAwB;YAqClB,iBAAiB;IAwB/B;;OAEG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAIlD;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI;CAInC"}
+{"version":3,"file":"policy-engine.d.ts","sourceRoot":"","sources":["../../src/policy/policy-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAO/E,UAAU,iBAAiB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,kBAAkB,CAA4B;gBAE1C,MAAM,EAAE,YAAY;IAiBhC;;OAEG;IACG,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QACxD,KAAK,EAAE,OAAO,CAAC;QACf,WAAW,EAAE,aAAa,EAAE,CAAC;QAC7B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;KACnB,CAAC;IAmBF;;OAEG;IACG,eAAe,CACnB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAqCjD;;OAEG;IACH,gBAAgB,IAAI;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,eAAe,EAAE,OAAO,CAAC;QACzB,cAAc,EAAE,OAAO,CAAC;QACxB,iBAAiB,EAAE,OAAO,CAAC;KAC5B;IAaD,OAAO,CAAC,wBAAwB;YAqClB,iBAAiB;IAwB/B;;OAEG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAIlD;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI;CAInC"}

package/dist/policy/policy-engine.js

@@ -1,12 +1,32 @@
 /**
- * Policy engine for enforcing permissions and limits
+ * @name policy/policy-engine
+ * @description High-level policy engine for enforcing permissions and spend limits.
+ *
+ * Wraps the local and hybrid policy engines, loads default policies, and
+ * provides a unified API for permission validation, spend-limit checks,
+ * and runtime diagnostics.
+ *
+ * @module policy/policy-engine
  */
 import { logger } from '../core/logger.js';
 import { defaultPolicies } from './default-policies.js';
 import { HybridPolicyEngine } from './hybrid-policy-engine.js';
 const LAMPORTS_PER_SOL = 1_000_000_000;
 /**
- * Policy engine class
+ * @name PolicyEngine
+ * @description High-level policy engine combining default policies, config-based limits, and hybrid enforcement.
+ *
+ * Loads default policies at construction time, creates a `HybridPolicyEngine`
+ * when configured, and exposes permission validation, spend-limit checks,
+ * policy CRUD, and runtime status diagnostics.
+ *
+ * @method validatePermissions  — Validate a list of permission strings against the allowed-tools config.
+ * @method checkPermission       — Check whether a single permission and optional context is allowed.
+ * @method getRuntimeStatus      — Return current hybrid/Bento policy status for diagnostics.
+ * @method getPolicy             — Retrieve a registered policy by id.
+ * @method addPolicy             — Register a custom policy.
+ *
+ * @usedBy `server.ts`, `core/context.ts`
  */
 export class PolicyEngine {
     config;

package/dist/policy/policy-engine.js.map

@@ -1 +1 @@
-{"version":3,"file":"policy-engine.js","sourceRoot":"","sources":["../../src/policy/policy-engine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"policy-engine.js","sourceRoot":"","sources":["../../src/policy/policy-engine.ts"],"names":[],"mappings":"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"}

package/dist/policy/policy-types.d.ts

@@ -1,9 +1,28 @@
 /**
- * Policy type definitions
+ * @name policy/policy-types
+ * @description Core type definitions for the SAP MCP policy engine.
+ *
+ * Defines the shapes for policies, policy rules, evaluation results,
+ * and policy evaluation context. These types are consumed by the local
+ * policy engine, default-policies module, and the higher-level policy engine.
+ *
+ * @module policy/policy-types
  */
 import type { SapPermission, SapRiskLevel } from '../core/types.js';
 /**
- * Policy definition
+ * @name Policy
+ * @description A named policy with an ordered set of rules.
+ *
+ * Each policy has a unique id, a human-readable name and description,
+ * an array of rules to evaluate, and an enabled flag.
+ *
+ * @property id          — Unique policy identifier.
+ * @property name        — Human-readable policy name.
+ * @property description — Short description of the policy's purpose.
+ * @property rules       — Ordered list of rules to evaluate.
+ * @property enabled     — Whether the policy is active.
+ *
+ * @usedBy `default-policies.ts`, `policy-engine.ts:PolicyEngine`
  */
 export interface Policy {
     id: string;
@@ -13,7 +32,21 @@ export interface Policy {
     enabled: boolean;
 }
 /**
- * Policy rule
+ * @name PolicyRule
+ * @description A single rule within a policy.
+ *
+ * A rule has a condition expression, an action to take when the condition
+ * matches, and optional constraints on tools, permissions, amounts, and risk levels.
+ *
+ * @property id           — Unique rule identifier within the policy.
+ * @property condition    — Expression string evaluated against the policy context.
+ * @property action       — Action to take: `allow`, `deny`, or `require_approval`.
+ * @property tools        — Optional list of tool names this rule applies to.
+ * @property permissions  — Optional list of permissions this rule applies to.
+ * @property maxAmountSol — Optional maximum transaction amount in SOL.
+ * @property riskLevel    — Optional risk level this rule applies to.
+ *
+ * @usedBy `Policy.rules`, `default-policies.ts`
  */
 export interface PolicyRule {
     id: string;
@@ -25,7 +58,15 @@ export interface PolicyRule {
     riskLevel?: SapRiskLevel;
 }
 /**
- * Policy evaluation result
+ * @name PolicyResult
+ * @description Result of evaluating a policy against a request.
+ *
+ * @property allowed          — Whether the operation is permitted.
+ * @property reason           — Optional human-readable explanation.
+ * @property requiresApproval — Whether human approval is needed before proceeding.
+ * @property riskLevel        — Optional risk level associated with the operation.
+ *
+ * @usedBy `policy-engine.ts:PolicyEngine`
  */
 export interface PolicyResult {
     allowed: boolean;
@@ -34,7 +75,16 @@ export interface PolicyResult {
     riskLevel?: SapRiskLevel;
 }
 /**
- * Policy context
+ * @name PolicyContext
+ * @description Context passed to the policy engine for evaluation.
+ *
+ * @property toolName   — Name of the tool being called.
+ * @property permission — Permission required by the tool.
+ * @property amountSol  — Optional transaction amount in SOL.
+ * @property riskLevel  — Optional pre-computed risk level.
+ * @property sessionId  — Optional session identifier for correlation.
+ *
+ * @usedBy `policy-engine.ts:PolicyEngine`
  */
 export interface PolicyContext {
     toolName: string;

package/dist/policy/policy-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"policy-types.d.ts","sourceRoot":"","sources":["../../src/policy/policy-types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEpE;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,kBAAkB,CAAC;IAC9C,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,CAAC,EAAE,aAAa,EAAE,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,YAAY,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,SAAS,CAAC,EAAE,YAAY,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,aAAa,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,YAAY,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}
+{"version":3,"file":"policy-types.d.ts","sourceRoot":"","sources":["../../src/policy/policy-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEpE;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,kBAAkB,CAAC;IAC9C,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,CAAC,EAAE,aAAa,EAAE,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,YAAY,CAAC;CAC1B;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,SAAS,CAAC,EAAE,YAAY,CAAC;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,aAAa,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,YAAY,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}

package/dist/policy/policy-types.js

@@ -1,5 +1,12 @@
 /**
- * Policy type definitions
+ * @name policy/policy-types
+ * @description Core type definitions for the SAP MCP policy engine.
+ *
+ * Defines the shapes for policies, policy rules, evaluation results,
+ * and policy evaluation context. These types are consumed by the local
+ * policy engine, default-policies module, and the higher-level policy engine.
+ *
+ * @module policy/policy-types
  */
 export {};
 //# sourceMappingURL=policy-types.js.map

package/dist/policy/policy-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"policy-types.js","sourceRoot":"","sources":["../../src/policy/policy-types.ts"],"names":[],"mappings":"AAAA;;GAEG"}
+{"version":3,"file":"policy-types.js","sourceRoot":"","sources":["../../src/policy/policy-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/policy/risk-level.d.ts

@@ -1,9 +1,29 @@
 /**
- * Risk level calculation
+ * @name policy/risk-level
+ * @description Risk level calculation utilities for SAP MCP transactions.
+ *
+ * Provides functions to compute a `SapRiskLevel` from transaction parameters
+ * and determine whether a given risk level requires human approval.
+ *
+ * @module policy/risk-level
  */
 import type { SapRiskLevel } from '../core/types.js';
 /**
- * Calculate risk level for a transaction
+ * @name calculateRiskLevel
+ * @description Calculate risk level for a transaction based on amount and operation type.
+ *
+ * Evaluates the transaction amount, whether it is a write operation, and whether
+ * it targets a known program to produce a graduated risk level from `safe` to `critical`.
+ * Write operations elevate risk by one tier; known operations reduce risk by one tier.
+ *
+ * @param params - Transaction parameters including amount, write flag, known flag, and tool name.
+ * @param params.amountSol - Transaction amount in SOL.
+ * @param params.isWriteOperation - Whether the operation mutates on-chain state.
+ * @param params.isKnownOperation - Whether the target program is in the known set.
+ * @param params.toolName - Name of the tool invoking the transaction.
+ * @returns A `SapRiskLevel` string: `safe`, `low`, `medium`, `high`, or `critical`.
+ *
+ * @usedBy `policy-engine.ts:PolicyEngine.checkPermission`
  */
 export declare function calculateRiskLevel(params: {
     amountSol: number;
@@ -12,7 +32,16 @@ export declare function calculateRiskLevel(params: {
     toolName: string;
 }): SapRiskLevel;
 /**
- * Check if risk level requires approval
+ * @name requiresApproval
+ * @description Check if a risk level requires human approval before execution.
+ *
+ * Returns `true` when the risk level is `high` or `critical`, indicating
+ * that the operation should be escalated for manual review.
+ *
+ * @param riskLevel - The risk level to evaluate.
+ * @returns `true` if the risk level is `high` or `critical`; otherwise `false`.
+ *
+ * @usedBy `policy-engine.ts:PolicyEngine.checkPermission`
  */
 export declare function requiresApproval(riskLevel: SapRiskLevel): boolean;
 //# sourceMappingURL=risk-level.d.ts.map

package/dist/policy/risk-level.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"risk-level.d.ts","sourceRoot":"","sources":["../../src/policy/risk-level.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,YAAY,CAgCf;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,YAAY,GAAG,OAAO,CAEjE"}
+{"version":3,"file":"risk-level.d.ts","sourceRoot":"","sources":["../../src/policy/risk-level.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,YAAY,CAgCf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,YAAY,GAAG,OAAO,CAEjE"}

package/dist/policy/risk-level.js

@@ -1,8 +1,28 @@
 /**
- * Risk level calculation
+ * @name policy/risk-level
+ * @description Risk level calculation utilities for SAP MCP transactions.
+ *
+ * Provides functions to compute a `SapRiskLevel` from transaction parameters
+ * and determine whether a given risk level requires human approval.
+ *
+ * @module policy/risk-level
  */
 /**
- * Calculate risk level for a transaction
+ * @name calculateRiskLevel
+ * @description Calculate risk level for a transaction based on amount and operation type.
+ *
+ * Evaluates the transaction amount, whether it is a write operation, and whether
+ * it targets a known program to produce a graduated risk level from `safe` to `critical`.
+ * Write operations elevate risk by one tier; known operations reduce risk by one tier.
+ *
+ * @param params - Transaction parameters including amount, write flag, known flag, and tool name.
+ * @param params.amountSol - Transaction amount in SOL.
+ * @param params.isWriteOperation - Whether the operation mutates on-chain state.
+ * @param params.isKnownOperation - Whether the target program is in the known set.
+ * @param params.toolName - Name of the tool invoking the transaction.
+ * @returns A `SapRiskLevel` string: `safe`, `low`, `medium`, `high`, or `critical`.
+ *
+ * @usedBy `policy-engine.ts:PolicyEngine.checkPermission`
  */
 export function calculateRiskLevel(params) {
     const { amountSol, isWriteOperation, isKnownOperation } = params;
@@ -38,7 +58,16 @@ export function calculateRiskLevel(params) {
     return risk;
 }
 /**
- * Check if risk level requires approval
+ * @name requiresApproval
+ * @description Check if a risk level requires human approval before execution.
+ *
+ * Returns `true` when the risk level is `high` or `critical`, indicating
+ * that the operation should be escalated for manual review.
+ *
+ * @param riskLevel - The risk level to evaluate.
+ * @returns `true` if the risk level is `high` or `critical`; otherwise `false`.
+ *
+ * @usedBy `policy-engine.ts:PolicyEngine.checkPermission`
  */
 export function requiresApproval(riskLevel) {
     return riskLevel === 'high' || riskLevel === 'critical';

package/dist/policy/risk-level.js.map

@@ -1 +1 @@
-{"version":3,"file":"risk-level.js","sourceRoot":"","sources":["../../src/policy/risk-level.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAKlC;IACC,MAAM,EAAE,SAAS,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,GAAG,MAAM,CAAC;IAEjE,wBAAwB;IACxB,IAAI,IAAI,GAAiB,MAAM,CAAC;IAChC,IAAI,SAAS,KAAK,CAAC,EAAE,CAAC;QACpB,IAAI,GAAG,MAAM,CAAC;IAChB,CAAC;SAAM,IAAI,SAAS,GAAG,GAAG,EAAE,CAAC;QAC3B,IAAI,GAAG,KAAK,CAAC;IACf,CAAC;SAAM,IAAI,SAAS,GAAG,GAAG,EAAE,CAAC;QAC3B,IAAI,GAAG,QAAQ,CAAC;IAClB,CAAC;SAAM,IAAI,SAAS,GAAG,IAAI,EAAE,CAAC;QAC5B,IAAI,GAAG,MAAM,CAAC;IAChB,CAAC;SAAM,CAAC;QACN,IAAI,GAAG,UAAU,CAAC;IACpB,CAAC;IAED,qCAAqC;IACrC,IAAI,gBAAgB,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACxC,IAAI,GAAG,KAAK,CAAC;IACf,CAAC;IAED,qCAAqC;IACrC,IAAI,gBAAgB,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACxC,MAAM,MAAM,GAAmB,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;QAC7E,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;YACrB,IAAI,GAAG,MAAM,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAuB;IACtD,OAAO,SAAS,KAAK,MAAM,IAAI,SAAS,KAAK,UAAU,CAAC;AAC1D,CAAC"}
+{"version":3,"file":"risk-level.js","sourceRoot":"","sources":["../../src/policy/risk-level.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAKlC;IACC,MAAM,EAAE,SAAS,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,GAAG,MAAM,CAAC;IAEjE,wBAAwB;IACxB,IAAI,IAAI,GAAiB,MAAM,CAAC;IAChC,IAAI,SAAS,KAAK,CAAC,EAAE,CAAC;QACpB,IAAI,GAAG,MAAM,CAAC;IAChB,CAAC;SAAM,IAAI,SAAS,GAAG,GAAG,EAAE,CAAC;QAC3B,IAAI,GAAG,KAAK,CAAC;IACf,CAAC;SAAM,IAAI,SAAS,GAAG,GAAG,EAAE,CAAC;QAC3B,IAAI,GAAG,QAAQ,CAAC;IAClB,CAAC;SAAM,IAAI,SAAS,GAAG,IAAI,EAAE,CAAC;QAC5B,IAAI,GAAG,MAAM,CAAC;IAChB,CAAC;SAAM,CAAC;QACN,IAAI,GAAG,UAAU,CAAC;IACpB,CAAC;IAED,qCAAqC;IACrC,IAAI,gBAAgB,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACxC,IAAI,GAAG,KAAK,CAAC;IACf,CAAC;IAED,qCAAqC;IACrC,IAAI,gBAAgB,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACxC,MAAM,MAAM,GAAmB,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;QAC7E,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;YACrB,IAAI,GAAG,MAAM,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAuB;IACtD,OAAO,SAAS,KAAK,MAAM,IAAI,SAAS,KAAK,UAAU,CAAC;AAC1D,CAAC"}

package/dist/policy/spending-limits.d.ts

@@ -1,9 +1,26 @@
 /**
- * Spending limits enforcement
+ * @name policy/spending-limits
+ * @description Spending limit enforcement utilities for SAP MCP transactions.
+ *
+ * Provides functions to validate transaction amounts against configured maximums
+ * and approval thresholds, and to derive a risk level from the transaction amount.
+ *
+ * @module policy/spending-limits
  */
 import type { SapMcpConfig } from '../core/types.js';
 /**
- * Check if amount is within spending limits
+ * @name checkSpendingLimit
+ * @description Check if a transaction amount is within configured spending limits.
+ *
+ * Compares the amount against `maxTxValueSol` (hard ceiling) and
+ * `requireApprovalAboveSol` (approval threshold). Returns a result object
+ * indicating whether the transaction is allowed, requires approval, or is blocked.
+ *
+ * @param config - The SAP MCP server configuration containing spending limits.
+ * @param amountSol - The transaction amount in SOL to validate.
+ * @returns An object with `allowed` flag, optional `reason` string, and optional `requiresApproval` flag.
+ *
+ * @usedBy `policy-engine.ts:PolicyEngine.checkPermission`
  */
 export declare function checkSpendingLimit(config: SapMcpConfig, amountSol: number): {
     allowed: boolean;
@@ -11,7 +28,16 @@ export declare function checkSpendingLimit(config: SapMcpConfig, amountSol: numb
     requiresApproval?: boolean;
 };
 /**
- * Calculate risk level based on amount
+ * @name calculateRiskLevel
+ * @description Calculate risk level based solely on transaction amount in SOL.
+ *
+ * Maps amount thresholds to risk tiers: 0 SOL is `safe`, <0.1 is `low`,
+ * <1.0 is `medium`, <10.0 is `high`, and 10.0+ is `critical`.
+ *
+ * @param amountSol - The transaction amount in SOL.
+ * @returns A risk level string: `safe`, `low`, `medium`, `high`, or `critical`.
+ *
+ * @usedBy `spending-limits.ts:checkSpendingLimit`
  */
 export declare function calculateRiskLevel(amountSol: number): 'safe' | 'low' | 'medium' | 'high' | 'critical';
 //# sourceMappingURL=spending-limits.d.ts.map

package/dist/policy/spending-limits.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spending-limits.d.ts","sourceRoot":"","sources":["../../src/policy/spending-limits.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,GAChB;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAE,CAoBnE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAMrG"}
+{"version":3,"file":"spending-limits.d.ts","sourceRoot":"","sources":["../../src/policy/spending-limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,GAChB;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAE,CAoBnE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAMrG"}

package/dist/policy/spending-limits.js

@@ -1,8 +1,25 @@
 /**
- * Spending limits enforcement
+ * @name policy/spending-limits
+ * @description Spending limit enforcement utilities for SAP MCP transactions.
+ *
+ * Provides functions to validate transaction amounts against configured maximums
+ * and approval thresholds, and to derive a risk level from the transaction amount.
+ *
+ * @module policy/spending-limits
  */
 /**
- * Check if amount is within spending limits
+ * @name checkSpendingLimit
+ * @description Check if a transaction amount is within configured spending limits.
+ *
+ * Compares the amount against `maxTxValueSol` (hard ceiling) and
+ * `requireApprovalAboveSol` (approval threshold). Returns a result object
+ * indicating whether the transaction is allowed, requires approval, or is blocked.
+ *
+ * @param config - The SAP MCP server configuration containing spending limits.
+ * @param amountSol - The transaction amount in SOL to validate.
+ * @returns An object with `allowed` flag, optional `reason` string, and optional `requiresApproval` flag.
+ *
+ * @usedBy `policy-engine.ts:PolicyEngine.checkPermission`
  */
 export function checkSpendingLimit(config, amountSol) {
     // Check max transaction limit
@@ -24,7 +41,16 @@ export function checkSpendingLimit(config, amountSol) {
     return { allowed: true };
 }
 /**
- * Calculate risk level based on amount
+ * @name calculateRiskLevel
+ * @description Calculate risk level based solely on transaction amount in SOL.
+ *
+ * Maps amount thresholds to risk tiers: 0 SOL is `safe`, <0.1 is `low`,
+ * <1.0 is `medium`, <10.0 is `high`, and 10.0+ is `critical`.
+ *
+ * @param amountSol - The transaction amount in SOL.
+ * @returns A risk level string: `safe`, `low`, `medium`, `high`, or `critical`.
+ *
+ * @usedBy `spending-limits.ts:checkSpendingLimit`
  */
 export function calculateRiskLevel(amountSol) {
     if (amountSol === 0)

package/dist/policy/spending-limits.js.map

@@ -1 +1 @@
-{"version":3,"file":"spending-limits.js","sourceRoot":"","sources":["../../src/policy/spending-limits.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAoB,EACpB,SAAiB;IAEjB,8BAA8B;IAC9B,MAAM,aAAa,GAAG,MAAM,CAAC,aAAa,CAAC;IAC3C,IAAI,SAAS,GAAG,aAAa,EAAE,CAAC;QAC9B,OAAO;YACL,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,UAAU,SAAS,0CAA0C,aAAa,MAAM;SACzF,CAAC;IACJ,CAAC;IAED,gCAAgC;IAChC,IAAI,SAAS,GAAG,MAAM,CAAC,uBAAuB,EAAE,CAAC;QAC/C,OAAO;YACL,OAAO,EAAE,KAAK;YACd,gBAAgB,EAAE,IAAI;YACtB,MAAM,EAAE,UAAU,SAAS,sCAAsC,MAAM,CAAC,uBAAuB,OAAO;SACvG,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC3B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAAiB;IAClD,IAAI,SAAS,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC;IACnC,IAAI,SAAS,GAAG,GAAG;QAAE,OAAO,KAAK,CAAC;IAClC,IAAI,SAAS,GAAG,GAAG;QAAE,OAAO,QAAQ,CAAC;IACrC,IAAI,SAAS,GAAG,IAAI;QAAE,OAAO,MAAM,CAAC;IACpC,OAAO,UAAU,CAAC;AACpB,CAAC"}
+{"version":3,"file":"spending-limits.js","sourceRoot":"","sources":["../../src/policy/spending-limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAoB,EACpB,SAAiB;IAEjB,8BAA8B;IAC9B,MAAM,aAAa,GAAG,MAAM,CAAC,aAAa,CAAC;IAC3C,IAAI,SAAS,GAAG,aAAa,EAAE,CAAC;QAC9B,OAAO;YACL,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,UAAU,SAAS,0CAA0C,aAAa,MAAM;SACzF,CAAC;IACJ,CAAC;IAED,gCAAgC;IAChC,IAAI,SAAS,GAAG,MAAM,CAAC,uBAAuB,EAAE,CAAC;QAC/C,OAAO;YACL,OAAO,EAAE,KAAK;YACd,gBAAgB,EAAE,IAAI;YACtB,MAAM,EAAE,UAAU,SAAS,sCAAsC,MAAM,CAAC,uBAAuB,OAAO;SACvG,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAAiB;IAClD,IAAI,SAAS,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC;IACnC,IAAI,SAAS,GAAG,GAAG;QAAE,OAAO,KAAK,CAAC;IAClC,IAAI,SAAS,GAAG,GAAG;QAAE,OAAO,QAAQ,CAAC;IACrC,IAAI,SAAS,GAAG,IAAI;QAAE,OAAO,MAAM,CAAC;IACpC,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/premium/activation-manager.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @name premium/activation-manager
+ * @description Session activation manager for x402/pay.sh receipt binding.
+ *
+ * After a buyer creates a session plan (status `pending_payment`) and settles
+ * the x402/pay.sh challenge on the delivery rail, the activation manager
+ * verifies the receipt and transitions the session to `active`.
+ *
+ * The activation manager is deliberately decoupled from the x402 facilitator:
+ * it accepts an opaque `paymentReceipt` string that the caller (HTTP endpoint
+ * or MCP tool) has already verified against the x402/pay.sh rail. This keeps
+ * the premium layer testable without a live facilitator.
+ *
+ * @flow
+ *   1. Buyer settles x402 challenge → receives `paymentReceipt` string.
+ *   2. Buyer calls `POST /premium/activate` or MCP tool `sap_premium_activate_session`.
+ *   3. → `activateSession()` verifies the session is in `pending_payment` status.
+ *   4. → Transitions session to `active` via `session-manager.activateSession()`.
+ *   5. → Returns `PremiumActivationResult` with `unitsQuota` and `activatedAt`.
+ *   6. Stream broker / webhook engine check `status=active` before delivering.
+ *
+ * @module premium/activation-manager
+ */
+import type { PremiumActivationRequest, PremiumActivationResult } from './types.js';
+/**
+ * @name activatePremiumSession
+ * @description Activate a pending premium session with a payment receipt.
+ *
+ * Steps:
+ *   1. Validate the receipt format (non-empty, reasonable length).
+ *   2. Look up the session via `getPremiumSession`.
+ *   3. Check the session is in `pending_payment` status.
+ *   4. Call `activateSession` to transition to `active`.
+ *   5. Return `PremiumActivationResult`.
+ *
+ * @param request - Activation request with session id and payment receipt.
+ * @returns `PremiumActivationResult` with `status=active` on success.
+ *
+ * @usedBy `premium-tools.ts` → MCP tool `sap_premium_activate_session`,
+ *   `remote/server.ts` → `POST /premium/activate`
+ */
+export declare function activatePremiumSession(request: PremiumActivationRequest): PremiumActivationResult;
+//# sourceMappingURL=activation-manager.d.ts.map

package/dist/premium/activation-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activation-manager.d.ts","sourceRoot":"","sources":["../../src/premium/activation-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,KAAK,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAsBpF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,wBAAwB,GAAG,uBAAuB,CAuEjG"}