@oobe-protocol-labs/sap-mcp-server 0.9.1 → 0.9.3

package/dist/premium/provider-bridge.js

@@ -0,0 +1,349 @@
+/**
+ * @name premium/provider-bridge
+ * @description Dynamic loader and connection manager for premium provider adapters.
+ *
+ * Provider adapters live in the private subrepo (`sap-mcp-premium-private/providers/`).
+ * The public server loads them dynamically only when `SAP_MCP_ENABLE_PREMIUM_PLUGINS=true`
+ * and the corresponding provider env vars are configured.
+ *
+ * The bridge maintains a registry of active adapters keyed by `pluginId:capabilityId`,
+ * handles connect/disconnect lifecycle, and exposes health status to the metrics
+ * and monitoring layer.
+ *
+ * Security: adapters are loaded from the configured `SAP_MCP_PLUGIN_DIR` only.
+ * No code is ever loaded from MCP tool input or user-supplied JSON.
+ *
+ * @flow
+ *   1. `stream-broker.ts` / `webhook-engine.ts` need events for a capability.
+ *   2. → `getProviderAdapter(pluginId, capabilityId)` returns the adapter.
+ *   3. If not loaded, `loadProviderAdapter()` dynamically imports from the
+ *      private subrepo providers directory.
+ *   4. Adapter `connect()` is called once, then `subscribe()` returns an
+ *      async iterable of events.
+ *   5. `disconnectAllProviders()` is called on graceful shutdown.
+ *
+ * @module premium/provider-bridge
+ */
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { findPremiumCapability } from './builtin-plugins.js';
+import { privatePremiumPluginsEnabled } from './private-manifest-loader.js';
+/**
+ * @description Registry of active provider adapters keyed by `pluginId:capabilityId`.
+ */
+const adapterRegistry = new Map();
+/**
+ * @description Registry of load failures keyed by `pluginId:capabilityId`.
+ * Records the error message for each adapter that was attempted but failed to load.
+ * Used by `getAllProviderHealth()` to surface load failures in metrics.
+ */
+const loadFailureRegistry = new Map();
+/**
+ * @name adapterKey
+ * @description Build the registry key for a plugin/capability pair.
+ *
+ * @param pluginId     - The premium plugin id.
+ * @param capabilityId - The capability id within the plugin.
+ * @returns The registry key string.
+ *
+ * @internal
+ */
+function adapterKey(pluginId, capabilityId) {
+    return `${pluginId}:${capabilityId}`;
+}
+/**
+ * @name configuredPluginDir
+ * @description Resolve the configured plugin directory from `SAP_MCP_PLUGIN_DIR`.
+ *
+ * @returns The absolute resolved path, or `null` if the env var is unset/empty.
+ *
+ * @internal
+ */
+function configuredPluginDir() {
+    const raw = process.env.SAP_MCP_PLUGIN_DIR;
+    if (!raw || !raw.trim())
+        return null;
+    return resolve(raw.trim());
+}
+/**
+ * @name loadProviderAdapter
+ * @description Dynamically load a provider adapter from the private subrepo.
+ *
+ * The adapter module must be located at:
+ *   `<SAP_MCP_PLUGIN_DIR>/providers/<pluginId>/<capabilityId>.js`
+ * (or `.ts` if running via tsx/ts-node).
+ *
+ * The module must export a default factory function that returns a
+ * `PremiumProviderAdapter`:
+ *
+ * ```ts
+ * export default function createAdapter(): PremiumProviderAdapter { ... }
+ * ```
+ *
+ * @param pluginId     - The premium plugin id.
+ * @param capabilityId - The capability id within the plugin.
+ * @returns The loaded and connected `PremiumProviderAdapter`, or `null` if
+ *   private plugins are disabled, the dir is not configured, or the module
+ *   is not found.
+ *
+ * @usedBy `getProviderAdapter`
+ */
+export async function loadProviderAdapter(pluginId, capabilityId) {
+    const key = adapterKey(pluginId, capabilityId);
+    if (!privatePremiumPluginsEnabled()) {
+        loadFailureRegistry.set(key, 'SAP_MCP_ENABLE_PREMIUM_PLUGINS is not set to true or 1.');
+        return null;
+    }
+    const pluginDir = configuredPluginDir();
+    if (!pluginDir) {
+        loadFailureRegistry.set(key, 'SAP_MCP_PLUGIN_DIR is not configured.');
+        return null;
+    }
+    // Resolve the capability to check it exists and get provider env requirements.
+    const resolved = findPremiumCapability(pluginId, capabilityId);
+    if (!resolved) {
+        loadFailureRegistry.set(key, `Capability ${pluginId}:${capabilityId} not found in plugin catalog.`);
+        return null;
+    }
+    // Check that all required provider env vars are set.
+    const missingEnv = resolved.capability.providerEnv.filter(envName => !process.env[envName]);
+    if (missingEnv.length > 0) {
+        loadFailureRegistry.set(key, `Missing required env vars: ${missingEnv.join(', ')}`);
+        return null;
+    }
+    const existing = adapterRegistry.get(key);
+    if (existing)
+        return existing;
+    // Try .js first (built), then .ts (dev).
+    const jsPath = join(pluginDir, 'providers', pluginId, `${capabilityId}.js`);
+    const tsPath = join(pluginDir, 'providers', pluginId, `${capabilityId}.ts`);
+    let modulePath = null;
+    if (existsSync(jsPath)) {
+        modulePath = jsPath;
+    }
+    else if (existsSync(tsPath)) {
+        modulePath = tsPath;
+    }
+    else {
+        loadFailureRegistry.set(key, `Provider file not found at ${jsPath} (or .ts). Run 'npx tsc' in the subrepo to compile providers.`);
+        return null;
+    }
+    try {
+        const moduleUrl = pathToFileURL(modulePath).href;
+        const imported = await import(moduleUrl);
+        if (typeof imported.default !== 'function') {
+            const msg = `Adapter module ${modulePath} has no default export function.`;
+            loadFailureRegistry.set(key, msg);
+            console.warn(`[provider-bridge] ${msg}`);
+            return null;
+        }
+        const adapter = imported.default();
+        if (!adapter || typeof adapter.connect !== 'function') {
+            const msg = `Adapter factory for ${modulePath} returned invalid adapter (missing connect).`;
+            loadFailureRegistry.set(key, msg);
+            console.warn(`[provider-bridge] ${msg}`);
+            return null;
+        }
+        await adapter.connect();
+        adapterRegistry.set(key, adapter);
+        loadFailureRegistry.delete(key);
+        return adapter;
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        const fullMsg = `Failed to load provider adapter from ${modulePath}: ${msg}`;
+        loadFailureRegistry.set(key, fullMsg);
+        console.error(`[provider-bridge] ${fullMsg}`);
+        return null;
+    }
+}
+/**
+ * @name getProviderAdapter
+ * @description Get or load a provider adapter for a plugin/capability pair.
+ *
+ * If the adapter is already in the registry, returns it directly.
+ * Otherwise, attempts to load it from the private subrepo.
+ *
+ * @param pluginId     - The premium plugin id.
+ * @param capabilityId - The capability id within the plugin.
+ * @returns The `PremiumProviderAdapter`, or `null` if not available.
+ *
+ * @usedBy `stream-broker.ts`, `webhook-engine.ts`
+ */
+export async function getProviderAdapter(pluginId, capabilityId) {
+    const key = adapterKey(pluginId, capabilityId);
+    const existing = adapterRegistry.get(key);
+    if (existing)
+        return existing;
+    return loadProviderAdapter(pluginId, capabilityId);
+}
+/**
+ * @name getProviderHealth
+ * @description Get health status for a specific provider adapter.
+ *
+ * @param pluginId     - The premium plugin id.
+ * @param capabilityId - The capability id within the plugin.
+ * @returns `ProviderHealth` if the adapter is loaded, otherwise a default unhealthy status.
+ *
+ * @usedBy `metrics.ts`
+ */
+export async function getProviderHealth(pluginId, capabilityId) {
+    const adapter = adapterRegistry.get(adapterKey(pluginId, capabilityId));
+    if (!adapter) {
+        return { healthy: false, lastError: 'Adapter not loaded.' };
+    }
+    try {
+        return await adapter.health();
+    }
+    catch (error) {
+        return {
+            healthy: false,
+            lastError: error instanceof Error ? error.message : 'Unknown provider health error.',
+        };
+    }
+}
+/**
+ * @name getAllProviderHealth
+ * @description Get health status for all configured provider adapters.
+ *
+ * Proactively attempts to load every capability whose `providerEnv` vars are
+ * all set, then reports health for each. Capabilities that fail to load get
+ * an unhealthy entry with the failure reason in `lastError`.
+ *
+ * This ensures `providerHealth` is never `{}` when providers are configured —
+ * the agent can always see WHY a provider is not loading.
+ *
+ * @returns Record keyed by `pluginId:capabilityId` → `ProviderHealth`.
+ *
+ * @usedBy `metrics.ts`
+ */
+export async function getAllProviderHealth() {
+    const results = {};
+    // Import here to avoid circular dependency at module load time.
+    const { listPremiumPlugins } = await import('./builtin-plugins.js');
+    const plugins = listPremiumPlugins();
+    for (const plugin of plugins) {
+        for (const cap of plugin.capabilities) {
+            if (!cap.requiresProvider)
+                continue;
+            const key = adapterKey(plugin.id, cap.id);
+            // Skip if env vars are not configured — not a failure, just not ready.
+            const missingEnv = cap.providerEnv.filter(envName => !process.env[envName]);
+            if (missingEnv.length > 0)
+                continue;
+            // Env is configured — attempt to load (no-op if already loaded).
+            const adapter = await loadProviderAdapter(plugin.id, cap.id);
+            if (adapter) {
+                try {
+                    results[key] = await adapter.health();
+                }
+                catch (error) {
+                    results[key] = {
+                        healthy: false,
+                        lastError: error instanceof Error ? error.message : 'Unknown provider health error.',
+                    };
+                }
+            }
+            else {
+                // Load failed — surface the failure reason from the registry.
+                const failureReason = loadFailureRegistry.get(key) ?? 'Adapter failed to load for unknown reason.';
+                results[key] = {
+                    healthy: false,
+                    lastError: failureReason,
+                };
+            }
+        }
+    }
+    return results;
+}
+/**
+ * @name subscribeToProvider
+ * @description Subscribe to events from a provider adapter with filters.
+ *
+ * Convenience wrapper that loads the adapter and returns the async iterable.
+ *
+ * @param pluginId     - The premium plugin id.
+ * @param capabilityId - The capability id within the plugin.
+ * @param filters      — Filter object passed to the adapter's `subscribe()`.
+ * @returns Async iterable of `ProviderEvent`, or `null` if the adapter is not available.
+ *
+ * @usedBy `stream-broker.ts`, `webhook-engine.ts`
+ */
+export async function subscribeToProvider(pluginId, capabilityId, filters) {
+    const adapter = await getProviderAdapter(pluginId, capabilityId);
+    if (!adapter) {
+        const key = adapterKey(pluginId, capabilityId);
+        const failureReason = loadFailureRegistry.get(key) ?? 'unknown reason';
+        console.error(`[provider-bridge] subscribeToProvider: adapter not available for ${key}: ${failureReason}`);
+        return null;
+    }
+    return adapter.subscribe(filters);
+}
+/**
+ * @name disconnectAllProviders
+ * @description Disconnect all loaded provider adapters gracefully.
+ *
+ * Called during server shutdown to clean up connections.
+ *
+ * @usedBy `remote/server.ts` shutdown handler
+ */
+export async function disconnectAllProviders() {
+    for (const [key, adapter] of adapterRegistry.entries()) {
+        try {
+            await adapter.disconnect();
+        }
+        catch {
+            // Best-effort disconnect — ignore errors during shutdown.
+        }
+        adapterRegistry.delete(key);
+    }
+}
+/**
+ * @name preloadPremiumProviders
+ * @description Eagerly load and connect all configured provider adapters at startup.
+ *
+ * Called by the remote server during `start()` — before the HTTP listener
+ * accepts requests. This ensures providers are running when the first agent
+ * session arrives, eliminates cold-start latency, and surfaces configuration
+ * errors immediately in the startup logs.
+ *
+ * Iterates every capability that requires a provider, checks env readiness,
+ * and attempts to load + connect each adapter. Failures are logged but do not
+ * block server startup — the server starts regardless, and `providerHealth`
+ * will report the failure reason when queried.
+ *
+ * @usedBy `remote/server.ts:start()` — after premium memory manager init.
+ */
+export async function preloadPremiumProviders() {
+    const { listPremiumPlugins } = await import('./builtin-plugins.js');
+    const plugins = listPremiumPlugins();
+    let loaded = 0;
+    let failed = 0;
+    let skipped = 0;
+    for (const plugin of plugins) {
+        for (const cap of plugin.capabilities) {
+            if (!cap.requiresProvider)
+                continue;
+            // Skip if env vars are not configured.
+            const missingEnv = cap.providerEnv.filter(envName => !process.env[envName]);
+            if (missingEnv.length > 0) {
+                skipped++;
+                continue;
+            }
+            const key = adapterKey(plugin.id, cap.id);
+            const adapter = await loadProviderAdapter(plugin.id, cap.id);
+            if (adapter) {
+                loaded++;
+                console.log(`[provider-bridge] Preloaded ${key} — healthy`);
+            }
+            else {
+                failed++;
+                const reason = loadFailureRegistry.get(key) ?? 'unknown reason';
+                console.error(`[provider-bridge] Failed to preload ${key} — ${reason}`);
+            }
+        }
+    }
+    console.log(`[provider-bridge] Preload complete: ${loaded} loaded, ${failed} failed, ${skipped} skipped (env not configured).`);
+}
+//# sourceMappingURL=provider-bridge.js.map

package/dist/premium/provider-bridge.js.map

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

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

@@ -0,0 +1,125 @@
+/**
+ * @name premium/session-manager
+ * @description In-memory lifecycle manager for premium session plans.
+ *
+ * When an agent calls `sap_premium_create_session_plan` (via `premium-tools.ts`),
+ * this module resolves the requested capability, clamps units/TTL to the
+ * capability's pricing bounds, checks provider env readiness, calculates the
+ * estimated USD price, and stores the resulting `PremiumSessionRecord` in an
+ * in-memory `Map` keyed by session id.
+ *
+ * Session lifecycle states:
+ *
+ *   pending_payment → active → closed
+ *   pending_payment → expired (if TTL passes before activation)
+ *   blocked_requires_provider (if provider env vars are not set)
+ *
+ * Sessions auto-expire after their TTL and are pruned on every create/list
+ * call. A hard cap of 1 000 concurrent session plans prevents unbounded growth.
+ *
+ * @flow
+ *   1. MCP tool `sap_premium_session_start` → `createPremiumSessionPlan()`.
+ *   2. MCP tool `sap_premium_activate_session` → `activateSession()`.
+ *   3. MCP tool `sap_premium_close_session` → `closeSession()`.
+ *   4. MCP tool `sap_premium_session_status` → `getPremiumSession()` / `listPremiumSessions()`.
+ *
+ * @module premium/session-manager
+ */
+import type { PremiumActivationResult, PremiumSessionRecord, PremiumSessionRequest } from './types.js';
+/**
+ * @name createPremiumSessionPlan
+ * @description Create and store a premium session plan for a buyer request.
+ *
+ * Resolution steps:
+ *   1. Prune expired/overflow sessions from the store.
+ *   2. Look up the capability via `findPremiumCapability` (builtin + private).
+ *   3. Clamp `requestedUnits` to [minUnits, maxUnits] and `ttlSeconds` to [60, 3600].
+ *   4. Compute `estimatedPriceUsd = requestedUnits × unitPriceUsd`.
+ *   5. Check whether all `providerEnv` vars are set in `process.env`.
+ *   6. Set status to `blocked_requires_provider` if provider is not ready,
+ *      otherwise `pending_payment`.
+ *   7. Generate a `sap-premium-<uuid>` session id, store, and return the record.
+ *
+ * @param request - Buyer-provided session request (plugin, capability, units, TTL).
+ * @returns The stored `PremiumSessionRecord` with server-generated fields.
+ * @throws {Error} If the plugin/capability pair is not found in the catalog.
+ *
+ * @usedBy `premium-tools.ts` → MCP tool `sap_premium_session_start`
+ */
+export declare function createPremiumSessionPlan(request: PremiumSessionRequest): PremiumSessionRecord;
+/**
+ * @name getPremiumSession
+ * @description Retrieve a session plan by id, lazily marking it as expired.
+ *
+ * If the session's `expiresAt` has passed and it is not already marked
+ * `expired`, the stored record is updated in place and the expired version
+ * is returned. A shallow copy is always returned to prevent external mutation
+ * of the internal store.
+ *
+ * @param sessionId - The session id returned by `createPremiumSessionPlan`.
+ * @returns The session record, or `null` if not found.
+ *
+ * @usedBy `premium-tools.ts` → MCP tool `sap_premium_session_status`
+ */
+export declare function getPremiumSession(sessionId: string): PremiumSessionRecord | null;
+/**
+ * @name listPremiumSessions
+ * @description List all non-null session plans after pruning expired entries.
+ *
+ * @returns Array of all current session records (including lazily-expired ones).
+ *
+ * @usedBy `premium-tools.ts` → MCP tool `sap_premium_session_status`
+ */
+export declare function listPremiumSessions(): PremiumSessionRecord[];
+/**
+ * @name activateSession
+ * @description Transition a session from `pending_payment` to `active`.
+ *
+ * Called by the activation manager after the x402/pay.sh receipt has been
+ * verified. The session's `nextAction` is updated to reflect the active state.
+ * If the session is not in `pending_payment` status, activation is rejected.
+ *
+ * @param sessionId - The session id to activate.
+ * @returns The activation result with `status=active` on success, or the
+ *   blocking status on failure.
+ *
+ * @usedBy `activation-manager.ts:activateSession`
+ */
+export declare function activateSession(sessionId: string): PremiumActivationResult;
+/**
+ * @name closeSession
+ * @description Transition an active session to `closed`.
+ *
+ * Called by the delivery rail when the unit quota is reached, when the buyer
+ * explicitly closes the session, or when the server shuts down gracefully.
+ *
+ * @param sessionId - The session id to close.
+ * @param reason    - Human-readable reason for closure.
+ * @returns True if the session was closed, false if it was not found or not active.
+ *
+ * @usedBy `stream-broker.ts`, `webhook-engine.ts`, `premium-tools.ts`
+ */
+export declare function closeSession(sessionId: string, reason: string): boolean;
+/**
+ * @name decrementSessionQuota
+ * @description Decrement the remaining units quota for an active session.
+ *
+ * Called by the stream broker / webhook engine after each delivered event.
+ * When the quota reaches zero, the session is automatically closed.
+ *
+ * @param sessionId - The active session id.
+ * @returns The remaining units after decrement, or -1 if the session is not active.
+ *
+ * @usedBy `stream-broker.ts`, `webhook-engine.ts`
+ */
+export declare function decrementSessionQuota(sessionId: string): number;
+/**
+ * @name clearAllSessions
+ * @description Clear all sessions from the in-memory store.
+ *
+ * Used in tests and during graceful server shutdown.
+ *
+ * @internal
+ */
+export declare function clearAllSessions(): void;
+//# sourceMappingURL=session-manager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../../src/premium/session-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,OAAO,KAAK,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAmEvG;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,qBAAqB,GAAG,oBAAoB,CA6C7F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAehF;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,IAAI,oBAAoB,EAAE,CAG5D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,uBAAuB,CA0E1E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAWvE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAgB/D;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC"}