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

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

@@ -0,0 +1,165 @@
+/**
+ * @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 premiumProviderLoaderStatus
+ * @description Return diagnostic info about the private plugin loader configuration.
+ *
+ * Reports whether private plugins are enabled, whether the plugin directory is
+ * configured and exists, and how many manifests were loaded/rejected. This
+ * complements `publicPremiumProviderStatus()` (which only checks env var
+ * readiness) by exposing the loader state that determines whether provider
+ * adapters can actually be loaded.
+ *
+ * @returns Object with `enabled`, `pluginDirConfigured`, `pluginDirExists`,
+ *   `loadedManifestCount`, and `rejectedManifestCount` fields.
+ *
+ * @usedBy `remote/server.ts` → provider status endpoint, `premium-tools.ts`.
+ */
+export declare function premiumProviderLoaderStatus(): {
+    enabled: boolean;
+    pluginDirConfigured: boolean;
+    pluginDirExists: boolean;
+    loadedManifestCount: number;
+    rejectedManifestCount: number;
+};
+/**
+ * @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;AAiP5G;;;;;;;;;;;;;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;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,2BAA2B,IAAI;IAC7C,OAAO,EAAE,OAAO,CAAC;IACjB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,eAAe,EAAE,OAAO,CAAC;IACzB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,qBAAqB,EAAE,MAAM,CAAC;CAC/B,CAUA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,2BAA2B,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAarE;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;CAAe,CAAC"}

package/dist/premium/builtin-plugins.js

@@ -0,0 +1,422 @@
+/**
+ * @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 { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadPrivatePremiumPluginManifests, loadPrivatePremiumPluginReport, premiumDiscoveryIncludesPrivate, } from './private-manifest-loader.js';
+import { TRADING_PREMIUM_PLUGINS } from './trading-capabilities.js';
+import { MEME_RADAR_PREMIUM_PLUGINS } from './meme-radar-capabilities.js';
+import { TECH_FUNDAMENTALS_PREMIUM_PLUGINS } from './tech-fundamentals-capabilities.js';
+/* -------------------------------------------------------------------------- */
+/* Shared JSON Schema fragments                                               */
+/* -------------------------------------------------------------------------- */
+/**
+ * @description Reusable Solana address field schema. Enforces base58 length
+ * bounds and explicitly forbids keypair bytes. Exported as `premiumAddressField`
+ * for reuse by MCP tool definitions.
+ */
+const addressField = {
+    type: 'string',
+    minLength: 32,
+    maxLength: 64,
+    description: 'Solana wallet, mint, program, or account public key in base58 form. Do not pass keypair bytes.',
+};
+/**
+ * @description Input schema for stream capabilities. Requires a stable
+ * `subscriptionKey` for de-duplication and allows free-form `filters`.
+ */
+const streamInputSchema = {
+    type: 'object',
+    required: ['subscriptionKey'],
+    properties: {
+        subscriptionKey: {
+            type: 'string',
+            minLength: 3,
+            description: 'Stable subscription key chosen by the agent runtime so duplicate opens can be de-duplicated.',
+        },
+        filters: {
+            type: 'object',
+            additionalProperties: true,
+            description: 'Narrow filters such as mint, wallet, protocol, agentId, capability, priceFeedId, or threshold.',
+        },
+    },
+    additionalProperties: false,
+};
+/**
+ * @description Output schema for stream capabilities. Each event carries a
+ * stable id, type, ISO timestamp, and a versioned provider-specific payload.
+ */
+const streamOutputSchema = {
+    type: 'object',
+    required: ['eventId', 'eventType', 'observedAt', 'payload'],
+    properties: {
+        eventId: {
+            type: 'string',
+            description: 'Stable event id suitable for idempotent processing and replay detection.',
+        },
+        eventType: {
+            type: 'string',
+            description: 'Premium stream event type emitted by this capability.',
+        },
+        observedAt: {
+            type: 'string',
+            format: 'date-time',
+            description: 'ISO timestamp when SAP MCP observed or emitted the event.',
+        },
+        payload: {
+            type: 'object',
+            additionalProperties: true,
+            description: 'Provider-specific event payload. Schemas are versioned per premium plugin manifest.',
+        },
+    },
+    additionalProperties: false,
+};
+/**
+ * @description Input schema for webhook capabilities. Requires an HTTPS
+ * `targetUrl` (localhost/private networks rejected by providers) and a
+ * non-empty `events` array. Optional `signingPublicKey` for signature verification.
+ */
+const webhookInputSchema = {
+    type: 'object',
+    required: ['targetUrl', 'events'],
+    properties: {
+        targetUrl: {
+            type: 'string',
+            format: 'uri',
+            description: 'HTTPS webhook target owned by the buyer. Localhost and private network URLs are rejected by providers.',
+        },
+        events: {
+            type: 'array',
+            minItems: 1,
+            items: { type: 'string', description: 'Event id listed in the capability delivery contract.' },
+            description: 'Exact event ids to deliver to this webhook subscription.',
+        },
+        signingPublicKey: {
+            type: 'string',
+            description: 'Optional public key used by the consumer to verify webhook signatures.',
+        },
+    },
+    additionalProperties: false,
+};
+/**
+ * @description Output schema for webhook deliveries. Includes a delivery id,
+ * event type, timestamp, provider signature, and versioned payload.
+ */
+const webhookOutputSchema = {
+    type: 'object',
+    required: ['deliveryId', 'eventType', 'deliveredAt', 'signature', 'payload'],
+    properties: {
+        deliveryId: { type: 'string', description: 'Idempotent webhook delivery id.' },
+        eventType: { type: 'string', description: 'Delivered premium event type.' },
+        deliveredAt: { type: 'string', format: 'date-time', description: 'ISO timestamp for delivery attempt.' },
+        signature: { type: 'string', description: 'Provider signature over deliveryId, deliveredAt, and payload.' },
+        payload: { type: 'object', additionalProperties: true, description: 'Versioned event payload.' },
+    },
+    additionalProperties: false,
+};
+/* -------------------------------------------------------------------------- */
+/* Capability factory helpers                                                 */
+/* -------------------------------------------------------------------------- */
+/**
+ * @name streamCapability
+ * @description Factory for building a `stream`-type premium capability definition.
+ *
+ * Sets status to `requires-provider` when any env vars are declared, otherwise
+ * `planned`. Uses `x402-per-minute` pricing with 1–120 minute bounds and
+ * MCP streamable HTTP transport with 750ms latency target and 300s replay window.
+ *
+ * @param id            - Capability id (e.g. `jupiter.quote.delta`).
+ * @param title         - Human-readable label.
+ * @param description   - Agent-facing description with payment boundary.
+ * @param events        - Event ids this stream can emit.
+ * @param unitPriceUsd  - Price per minute in USD.
+ * @param providerEnv   - Env var names required for provider readiness.
+ * @returns A complete `PremiumCapabilityDefinition` with type `stream`.
+ *
+ * @internal
+ */
+function streamCapability(id, title, description, events, unitPriceUsd, providerEnv) {
+    return {
+        id,
+        type: 'stream',
+        title,
+        description,
+        status: providerEnv.length > 0 ? 'requires-provider' : 'planned',
+        requiresProvider: providerEnv.length > 0,
+        providerEnv,
+        inputSchema: streamInputSchema,
+        outputSchema: streamOutputSchema,
+        pricing: {
+            tier: 'premium-stream',
+            model: 'x402-per-minute',
+            unit: 'minute',
+            unitPriceUsd,
+            minUnits: 1,
+            maxUnits: 120,
+            settlement: 'x402',
+        },
+        delivery: {
+            transport: 'mcp-streamable-http',
+            events,
+            latencyTargetMs: 750,
+            replayWindowSeconds: 300,
+        },
+    };
+}
+/**
+ * @name webhookCapability
+ * @description Factory for building a `webhook`-type premium capability definition.
+ *
+ * Sets status to `requires-provider` when any env vars are declared, otherwise
+ * `planned`. Uses `x402-per-event` pricing with 10–100 000 event bounds and
+ * webhook HTTP transport with 1500ms latency target and 900s replay window.
+ *
+ * @param id            - Capability id (e.g. `price.threshold.crossed`).
+ * @param title         - Human-readable label.
+ * @param description   - Agent-facing description with payment boundary.
+ * @param events        - Event ids this webhook can deliver.
+ * @param unitPriceUsd  - Price per event in USD.
+ * @param providerEnv   - Env var names required for provider readiness.
+ * @returns A complete `PremiumCapabilityDefinition` with type `webhook`.
+ *
+ * @internal
+ */
+function webhookCapability(id, title, description, events, unitPriceUsd, providerEnv) {
+    return {
+        id,
+        type: 'webhook',
+        title,
+        description,
+        status: providerEnv.length > 0 ? 'requires-provider' : 'planned',
+        requiresProvider: providerEnv.length > 0,
+        providerEnv,
+        inputSchema: webhookInputSchema,
+        outputSchema: webhookOutputSchema,
+        pricing: {
+            tier: 'premium-webhook',
+            model: 'x402-per-event',
+            unit: 'event',
+            unitPriceUsd,
+            minUnits: 10,
+            maxUnits: 100_000,
+            settlement: 'x402',
+        },
+        delivery: {
+            transport: 'webhook-http',
+            events,
+            latencyTargetMs: 1_500,
+            replayWindowSeconds: 900,
+        },
+    };
+}
+/* -------------------------------------------------------------------------- */
+/* Built-in plugin catalog                                                    */
+/* -------------------------------------------------------------------------- */
+/**
+ * @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 const BUILTIN_PREMIUM_PLUGINS = [
+    {
+        id: 'sap-premium-market-data',
+        version: '0.1.0',
+        title: 'SAP Premium Market Data',
+        description: 'Paid low-latency market stream contracts for quotes, prices, route changes, and threshold events.',
+        publisher: 'OOBE Protocol',
+        visibility: 'public',
+        capabilities: [
+            streamCapability('jupiter.quote.delta', 'Jupiter quote delta stream', 'Streams quote deltas for exact mints and amounts so agents can react without repeated broad polling.', ['quote.delta', 'route.changed', 'price.impact.changed'], 0.01, ['SAP_MCP_PREMIUM_JUPITER_STREAM_URL']),
+            streamCapability('pyth.price.tick', 'Pyth price tick stream', 'Streams price ticks for explicit Pyth feed ids with bounded replay and x402 metering.', ['price.tick', 'confidence.changed', 'feed.stale'], 0.0075, ['SAP_MCP_PREMIUM_PYTH_STREAM_URL']),
+            webhookCapability('price.threshold.crossed', 'Price threshold webhook', 'Delivers signed HTTPS callbacks when configured mint/feed thresholds cross.', ['price.threshold.crossed'], 0.0005, ['SAP_MCP_PREMIUM_WEBHOOK_SIGNER']),
+        ],
+    },
+];
+/**
+ * @name clonePlugin
+ * @description Deep-clone a plugin manifest via JSON serialization.
+ *
+ * Ensures callers cannot mutate the internal built-in or loaded manifest objects.
+ *
+ * @param plugin - The manifest to clone.
+ * @returns A deep copy of the manifest.
+ *
+ * @internal
+ */
+function clonePlugin(plugin) {
+    return JSON.parse(JSON.stringify(plugin));
+}
+/**
+ * @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 function listPremiumPlugins(options = {}) {
+    const includePrivate = options.includePrivate ?? premiumDiscoveryIncludesPrivate();
+    const plugins = [
+        ...BUILTIN_PREMIUM_PLUGINS,
+        ...TRADING_PREMIUM_PLUGINS,
+        ...MEME_RADAR_PREMIUM_PLUGINS,
+        ...TECH_FUNDAMENTALS_PREMIUM_PLUGINS,
+        ...loadPrivatePremiumPluginManifests(),
+    ];
+    return plugins
+        .filter(plugin => plugin.visibility === 'public' || includePrivate)
+        .map(clonePlugin);
+}
+/**
+ * @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 function listPremiumCapabilities(type, options = {}) {
+    return listPremiumPlugins(options).flatMap(plugin => plugin.capabilities
+        .filter(capability => !type || capability.type === type)
+        .map(capability => ({ ...capability })));
+}
+/**
+ * @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 function findPremiumCapability(pluginId, capabilityId, type, options = {}) {
+    const plugin = listPremiumPlugins(options).find(candidate => candidate.id === pluginId);
+    const capability = plugin?.capabilities.find(candidate => candidate.id === capabilityId && (!type || candidate.type === type));
+    return plugin && capability ? { plugin, capability } : 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 function publicPremiumProviderStatus() {
+    const envNames = new Set(listPremiumCapabilities().flatMap(capability => capability.providerEnv));
+    return Object.fromEntries([...envNames].sort().map(name => [name, Boolean(process.env[name])]));
+}
+/**
+ * @name premiumProviderLoaderStatus
+ * @description Return diagnostic info about the private plugin loader configuration.
+ *
+ * Reports whether private plugins are enabled, whether the plugin directory is
+ * configured and exists, and how many manifests were loaded/rejected. This
+ * complements `publicPremiumProviderStatus()` (which only checks env var
+ * readiness) by exposing the loader state that determines whether provider
+ * adapters can actually be loaded.
+ *
+ * @returns Object with `enabled`, `pluginDirConfigured`, `pluginDirExists`,
+ *   `loadedManifestCount`, and `rejectedManifestCount` fields.
+ *
+ * @usedBy `remote/server.ts` → provider status endpoint, `premium-tools.ts`.
+ */
+export function premiumProviderLoaderStatus() {
+    const report = loadPrivatePremiumPluginReport();
+    const pluginDir = process.env.SAP_MCP_PLUGIN_DIR;
+    return {
+        enabled: report.enabled,
+        pluginDirConfigured: report.pluginDirConfigured,
+        pluginDirExists: pluginDir !== undefined && pluginDir.trim() !== '' && existsSync(resolve(pluginDir)),
+        loadedManifestCount: report.loadedManifests.length,
+        rejectedManifestCount: report.rejectedManifests.length,
+    };
+}
+/**
+ * @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 function premiumPrivatePluginSupport() {
+    const privateReport = loadPrivatePremiumPluginReport();
+    return {
+        enabled: process.env.SAP_MCP_ENABLE_PREMIUM_PLUGINS === 'true',
+        exposePrivateDiscovery: premiumDiscoveryIncludesPrivate(),
+        loadedManifestCount: privateReport.loadedManifests.length,
+        rejectedManifestCount: privateReport.rejectedManifests.length,
+        loaderEnv: ['SAP_MCP_ENABLE_PREMIUM_PLUGINS', 'SAP_MCP_PLUGIN_DIR', 'SAP_MCP_PREMIUM_EXPOSE_PRIVATE_DISCOVERY'],
+        contract: 'Private premium plugins must ship a manifest that passes sap_premium_validate_plugin_manifest. The public SAP MCP repo only exposes the contract; enterprise plugin code and provider secrets stay outside the open repo.',
+        safety: 'Plugin manifests are data only. SAP MCP does not execute plugin code from user input, and provider secrets are never exposed through public metadata.',
+    };
+}
+/**
+ * @name premiumAddressField
+ * @description Re-exported reusable Solana address JSON Schema fragment.
+ *
+ * Used by MCP tool definitions that accept a Solana public key argument.
+ */
+export const premiumAddressField = addressField;
+//# sourceMappingURL=builtin-plugins.js.map

package/dist/premium/builtin-plugins.js.map

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

package/dist/premium/event-store.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @name premium/event-store
+ * @description In-memory event store for premium event replay and idempotency.
+ *
+ * Every event delivered through the stream broker or webhook engine is recorded
+ * here. The store supports:
+ *   - append with `eventId` deduplication (idempotency)
+ *   - query by session, event type, or time window
+ *   - automatic eviction of events past their replay window
+ *
+ * @flow
+ *   1. `stream-broker.ts` / `webhook-engine.ts` deliver an event →
+ *      `appendEvent()` stores it (dedup by `eventId`).
+ *   2. `stream-broker.ts` reconnects a client → `getEvents()` replays past
+ *      events within the replay window.
+ *   3. Pruning runs on every append/query to evict events past their
+ *      `replayWindowSeconds` per capability.
+ *
+ * @module premium/event-store
+ */
+import type { PremiumEventQuery, PremiumEventRecord } from './types.js';
+/**
+ * @name appendEvent
+ * @description Append a premium event to the store with idempotency.
+ *
+ * If an event with the same `eventId` already exists, it is not duplicated.
+ * The store is pruned after each append.
+ *
+ * @param record - The event record to append.
+ * @returns True if the event was newly inserted, false if it was a duplicate.
+ *
+ * @usedBy `stream-broker.ts`, `webhook-engine.ts`
+ */
+export declare function appendEvent(record: PremiumEventRecord): boolean;
+/**
+ * @name getEvents
+ * @description Query events from the store with optional filters.
+ *
+ * @param query - Filter criteria (sessionId, eventType, since, limit).
+ * @returns Array of matching event records, ordered by `deliveredAt` ascending.
+ *
+ * @usedBy `stream-broker.ts` (replay), `premium-tools.ts` (audit)
+ */
+export declare function getEvents(query?: PremiumEventQuery): PremiumEventRecord[];
+/**
+ * @name getEventCount
+ * @description Return the total number of stored events.
+ *
+ * @usedBy `metrics.ts`
+ */
+export declare function getEventCount(): number;
+/**
+ * @name clearAllEvents
+ * @description Clear all events from the store.
+ *
+ * Used in tests and during graceful server shutdown.
+ *
+ * @internal
+ */
+export declare function clearAllEvents(): void;
+//# sourceMappingURL=event-store.d.ts.map

package/dist/premium/event-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-store.d.ts","sourceRoot":"","sources":["../../src/premium/event-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAoBxE;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAM/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,KAAK,GAAE,iBAAsB,GAAG,kBAAkB,EAAE,CAc7E;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AA+BD;;;;;;;GAOG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAErC"}