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

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"}

package/dist/premium/activation-manager.js

@@ -0,0 +1,131 @@
+/**
+ * @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 { activateSession } from './session-manager.js';
+import { getPremiumSession } from './session-manager.js';
+/**
+ * @name verifyReceiptFormat
+ * @description Basic structural validation of a payment receipt string.
+ *
+ * This does NOT verify the receipt against the x402/pay.sh facilitator — that
+ * is the caller's responsibility. It only checks that the receipt is a non-empty
+ * string of reasonable length.
+ *
+ * @param receipt - The opaque receipt string from x402/pay.sh settlement.
+ * @returns True if the receipt has a valid structural format.
+ *
+ * @internal
+ */
+function verifyReceiptFormat(receipt) {
+    if (typeof receipt !== 'string')
+        return false;
+    if (receipt.trim().length < 8)
+        return false;
+    if (receipt.length > 2048)
+        return false;
+    return true;
+}
+/**
+ * @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 function activatePremiumSession(request) {
+    if (!verifyReceiptFormat(request.paymentReceipt)) {
+        return {
+            sessionId: request.sessionId,
+            status: 'pending_payment',
+            activatedAt: null,
+            receiptBound: false,
+            unitsQuota: 0,
+            reason: 'Invalid payment receipt format. Ensure the x402/pay.sh receipt is a non-empty string.',
+        };
+    }
+    const session = getPremiumSession(request.sessionId);
+    if (!session) {
+        return {
+            sessionId: request.sessionId,
+            status: 'expired',
+            activatedAt: null,
+            receiptBound: false,
+            unitsQuota: 0,
+            reason: 'Session not found. Create a fresh session plan before activation.',
+        };
+    }
+    if (session.status === 'blocked_requires_provider') {
+        return {
+            sessionId: request.sessionId,
+            status: 'blocked_requires_provider',
+            activatedAt: null,
+            receiptBound: false,
+            unitsQuota: 0,
+            reason: 'Provider is not ready. Configure provider env vars before activating.',
+        };
+    }
+    if (session.status === 'expired') {
+        return {
+            sessionId: request.sessionId,
+            status: 'expired',
+            activatedAt: null,
+            receiptBound: false,
+            unitsQuota: 0,
+            reason: 'Session has expired. Create a fresh session plan.',
+        };
+    }
+    if (session.status === 'active') {
+        return {
+            sessionId: request.sessionId,
+            status: 'active',
+            activatedAt: session.createdAt,
+            receiptBound: true,
+            unitsQuota: session.requestedUnits,
+            reason: 'Session is already active.',
+        };
+    }
+    if (session.status === 'closed') {
+        return {
+            sessionId: request.sessionId,
+            status: 'closed',
+            activatedAt: null,
+            receiptBound: false,
+            unitsQuota: 0,
+            reason: 'Session has been closed. Create a fresh session plan.',
+        };
+    }
+    // Status is pending_payment — activate.
+    const result = activateSession(request.sessionId);
+    return result;
+}
+//# sourceMappingURL=activation-manager.js.map

package/dist/premium/activation-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activation-manager.js","sourceRoot":"","sources":["../../src/premium/activation-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAGzD;;;;;;;;;;;;GAYG;AACH,SAAS,mBAAmB,CAAC,OAAe;IAC1C,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC9C,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI;QAAE,OAAO,KAAK,CAAC;IACxC,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAiC;IACtE,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,CAAC;QACjD,OAAO;YACL,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,MAAM,EAAE,iBAAiB;YACzB,WAAW,EAAE,IAAI;YACjB,YAAY,EAAE,KAAK;YACnB,UAAU,EAAE,CAAC;YACb,MAAM,EAAE,uFAAuF;SAChG,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,iBAAiB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACrD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO;YACL,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,MAAM,EAAE,SAAS;YACjB,WAAW,EAAE,IAAI;YACjB,YAAY,EAAE,KAAK;YACnB,UAAU,EAAE,CAAC;YACb,MAAM,EAAE,mEAAmE;SAC5E,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,KAAK,2BAA2B,EAAE,CAAC;QACnD,OAAO;YACL,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,MAAM,EAAE,2BAA2B;YACnC,WAAW,EAAE,IAAI;YACjB,YAAY,EAAE,KAAK;YACnB,UAAU,EAAE,CAAC;YACb,MAAM,EAAE,uEAAuE;SAChF,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QACjC,OAAO;YACL,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,MAAM,EAAE,SAAS;YACjB,WAAW,EAAE,IAAI;YACjB,YAAY,EAAE,KAAK;YACnB,UAAU,EAAE,CAAC;YACb,MAAM,EAAE,mDAAmD;SAC5D,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAChC,OAAO;YACL,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,MAAM,EAAE,QAAQ;YAChB,WAAW,EAAE,OAAO,CAAC,SAAS;YAC9B,YAAY,EAAE,IAAI;YAClB,UAAU,EAAE,OAAO,CAAC,cAAc;YAClC,MAAM,EAAE,4BAA4B;SACrC,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAChC,OAAO;YACL,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,MAAM,EAAE,QAAQ;YAChB,WAAW,EAAE,IAAI;YACjB,YAAY,EAAE,KAAK;YACnB,UAAU,EAAE,CAAC;YACb,MAAM,EAAE,uDAAuD;SAChE,CAAC;IACJ,CAAC;IAED,wCAAwC;IACxC,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAClD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/premium/builtin-plugins.d.ts

@@ -0,0 +1,143 @@
+/**
+ * @name premium/builtin-plugins
+ * @description Built-in premium plugin definitions and discovery helpers.
+ *
+ * Defines the core built-in public premium plugin shipped with SAP MCP:
+ *   1. `sap-premium-market-data`  — Jupiter quotes, Pyth price ticks, threshold webhooks.
+ *
+ * Additional built-in plugin arrays are imported and merged by `listPremiumPlugins()`:
+ *   - `TRADING_PREMIUM_PLUGINS`             — Trading streams.
+ *   - `MEME_RADAR_PREMIUM_PLUGINS`          — Meme token listing, sentiment, rugpull, volume.
+ *   - `TECH_FUNDAMENTALS_PREMIUM_PLUGINS`   — GitHub activity, TVL changes, tokenomics analysis.
+ *
+ * Also provides discovery helpers (`listPremiumPlugins`, `listPremiumCapabilities`,
+ * `findPremiumCapability`) that merge built-in plugins with privately loaded
+ * manifests, and status helpers (`publicPremiumProviderStatus`,
+ * `premiumPrivatePluginSupport`) used by the remote server and MCP tools.
+ *
+ * @flow
+ *   1. MCP tool `sap_premium_plugin_catalog` → `listPremiumPlugins()` →
+ *      merges built-in + private manifests, filters by visibility, returns clones.
+ *   2. MCP tool `sap_premium_create_session_plan` → `findPremiumCapability()` →
+ *      resolves a specific plugin/capability pair for session planning.
+ *   3. Remote server (`remote/server.ts`) → `publicPremiumProviderStatus()` →
+ *      exposes which provider env vars are configured.
+ *   4. Remote server → `premiumPrivatePluginSupport()` → reports private plugin
+ *      loader configuration and safety contract.
+ *
+ * @module premium/builtin-plugins
+ */
+import type { PremiumCapabilityDefinition, PremiumCapabilityType, PremiumPluginManifest } from './types.js';
+/**
+ * @name BUILTIN_PREMIUM_PLUGINS
+ * @description The built-in public premium plugins shipped with SAP MCP.
+ *
+ * These are always available (no env vars needed for discovery) and serve as
+ * the reference implementations for the premium plugin manifest format.
+ * Additional plugin arrays (`TRADING_PREMIUM_PLUGINS`,
+ * `MEME_RADAR_PREMIUM_PLUGINS`, `TECH_FUNDAMENTALS_PREMIUM_PLUGINS`) are merged
+ * in `listPremiumPlugins()`.
+ *
+ * @type {PremiumPluginManifest[]}
+ *
+ * @usedBy `listPremiumPlugins()` as the base catalog merged with private manifests.
+ */
+export declare const BUILTIN_PREMIUM_PLUGINS: PremiumPluginManifest[];
+/**
+ * @name PremiumPluginListOptions
+ * @description Options controlling which plugins are included in discovery.
+ *
+ * @property includePrivate - When true, `private` and `enterprise` visibility
+ *   plugins are included. Defaults to the value of
+ *   `SAP_MCP_PREMIUM_EXPOSE_PRIVATE_DISCOVERY` env var.
+ */
+export interface PremiumPluginListOptions {
+    includePrivate?: boolean;
+}
+/**
+ * @name listPremiumPlugins
+ * @description Return all discoverable premium plugins (built-in + private).
+ *
+ * Merges `BUILTIN_PREMIUM_PLUGINS` with privately loaded manifests, filters by
+ * visibility (public always; private/enterprise only when `includePrivate` is
+ * true or `SAP_MCP_PREMIUM_EXPOSE_PRIVATE_DISCOVERY=true`), and returns deep
+ * clones to prevent external mutation.
+ *
+ * @param options - Discovery options (see `PremiumPluginListOptions`).
+ * @returns Array of `PremiumPluginManifest` clones.
+ *
+ * @usedBy
+ *   - `premium-tools.ts` → MCP tool `sap_premium_plugin_catalog`.
+ *   - `remote/server.ts` → landing page plugin listing.
+ *   - `listPremiumCapabilities`, `findPremiumCapability` (internally).
+ */
+export declare function listPremiumPlugins(options?: PremiumPluginListOptions): PremiumPluginManifest[];
+/**
+ * @name listPremiumCapabilities
+ * @description Return all capabilities across all discoverable plugins,
+ * optionally filtered by capability type.
+ *
+ * @param type    - Optional filter: `stream`, `webhook`, or `tool`.
+ * @param options - Discovery options (see `PremiumPluginListOptions`).
+ * @returns Array of `PremiumCapabilityDefinition` clones (shallow-copied).
+ *
+ * @usedBy `publicPremiumProviderStatus` (internally), MCP tools.
+ */
+export declare function listPremiumCapabilities(type?: PremiumCapabilityType, options?: PremiumPluginListOptions): PremiumCapabilityDefinition[];
+/**
+ * @name findPremiumCapability
+ * @description Resolve a specific plugin/capability pair by id.
+ *
+ * @param pluginId      - The plugin id to search for.
+ * @param capabilityId  - The capability id within that plugin.
+ * @param type          - Optional capability type filter.
+ * @param options       - Discovery options (see `PremiumPluginListOptions`).
+ * @returns `{ plugin, capability }` if found, otherwise `null`.
+ *
+ * @usedBy `session-manager.ts:createPremiumSessionPlan` → resolves the
+ *   capability for pricing bounds and provider env checks.
+ */
+export declare function findPremiumCapability(pluginId: string, capabilityId: string, type?: PremiumCapabilityType, options?: PremiumPluginListOptions): {
+    plugin: PremiumPluginManifest;
+    capability: PremiumCapabilityDefinition;
+} | null;
+/**
+ * @name publicPremiumProviderStatus
+ * @description Return a map of all provider env var names to their current
+ * readiness state (true/false based on `process.env`).
+ *
+ * Used by the remote server to expose which premium providers are configured
+ * without revealing secret values.
+ *
+ * @returns Record keyed by env var name, value is boolean readiness.
+ *
+ * @usedBy `remote/server.ts` → provider status endpoint.
+ */
+export declare function publicPremiumProviderStatus(): Record<string, boolean>;
+/**
+ * @name premiumPrivatePluginSupport
+ * @description Return a diagnostic object describing the private plugin
+ * loader configuration, loaded/rejected manifest counts, and the safety contract.
+ *
+ * Used by the remote server and MCP tools to report private plugin support
+ * status without exposing any enterprise code or secrets.
+ *
+ * @returns Object with `enabled`, `exposePrivateDiscovery`, `loadedManifestCount`,
+ *   `rejectedManifestCount`, `loaderEnv`, `contract`, and `safety` fields.
+ *
+ * @usedBy `remote/server.ts`, `premium-tools.ts`.
+ */
+export declare function premiumPrivatePluginSupport(): Record<string, unknown>;
+/**
+ * @name premiumAddressField
+ * @description Re-exported reusable Solana address JSON Schema fragment.
+ *
+ * Used by MCP tool definitions that accept a Solana public key argument.
+ */
+export declare const premiumAddressField: {
+    type: string;
+    minLength: number;
+    maxLength: number;
+    description: string;
+};
+//# sourceMappingURL=builtin-plugins.d.ts.map

package/dist/premium/builtin-plugins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin-plugins.d.ts","sourceRoot":"","sources":["../../src/premium/builtin-plugins.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,2BAA2B,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AA+O5G;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,uBAAuB,EAAE,qBAAqB,EAmC1D,CAAC;AAMF;;;;;;;GAOG;AACH,MAAM,WAAW,wBAAwB;IACvC,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAiBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,wBAA6B,GAAG,qBAAqB,EAAE,CAYlG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,CAAC,EAAE,qBAAqB,EAAE,OAAO,GAAE,wBAA6B,GAAG,2BAA2B,EAAE,CAM3I;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,IAAI,CAAC,EAAE,qBAAqB,EAC5B,OAAO,GAAE,wBAA6B,GACrC;IAAE,MAAM,EAAE,qBAAqB,CAAC;IAAC,UAAU,EAAE,2BAA2B,CAAA;CAAE,GAAG,IAAI,CAInF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAGrE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,2BAA2B,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAarE;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;CAAe,CAAC"}