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

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

package/dist/premium/session-manager.js

@@ -0,0 +1,337 @@
+/**
+ * @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 { randomUUID } from 'node:crypto';
+import { findPremiumCapability } from './builtin-plugins.js';
+/**
+ * @description In-memory store of active session plans, keyed by session id.
+ * Not exported — access is mediated through the public functions below.
+ */
+const sessions = new Map();
+/**
+ * @description Hard cap on concurrent session plans to prevent unbounded
+ * memory growth in long-running MCP server processes.
+ *
+ * Default: 10_000 (tuned for a 312GB RAM production server).
+ * Override via `SAP_MCP_PREMIUM_MAX_SESSIONS` env var.
+ */
+const MAX_PREMIUM_SESSION_PLANS = (() => {
+    const raw = process.env.SAP_MCP_PREMIUM_MAX_SESSIONS;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) && parsed > 0 ? Math.trunc(parsed) : 10_000;
+})();
+/**
+ * @name clampInteger
+ * @description Safely clamp an arbitrary numeric value to an integer within [min, max].
+ *
+ * Non-finite values (NaN, Infinity) fall back to `min`. The value is truncated
+ * to an integer before clamping.
+ *
+ * @param value - Raw input (may be float, NaN, or Infinity).
+ * @param min   - Lower bound (inclusive).
+ * @param max   - Upper bound (inclusive).
+ * @returns Integer clamped to [min, max].
+ *
+ * @internal
+ */
+function clampInteger(value, min, max) {
+    if (!Number.isFinite(value))
+        return min;
+    return Math.min(max, Math.max(min, Math.trunc(value)));
+}
+/**
+ * @name pruneExpiredSessions
+ * @description Remove all sessions whose `expiresAt` has passed, then evict
+ * the oldest sessions if the store exceeds `MAX_PREMIUM_SESSION_PLANS`.
+ *
+ * Called on every `createPremiumSessionPlan` and `listPremiumSessions` call
+ * to keep the store bounded without requiring a background timer.
+ *
+ * @internal
+ */
+function pruneExpiredSessions() {
+    const now = Date.now();
+    for (const [sessionId, record] of sessions.entries()) {
+        if (record.status === 'active' || record.status === 'closed')
+            continue;
+        if (new Date(record.expiresAt).getTime() <= now) {
+            sessions.delete(sessionId);
+        }
+    }
+    // Evict oldest entries (Map preserves insertion order) if still over cap.
+    while (sessions.size > MAX_PREMIUM_SESSION_PLANS) {
+        const oldestSessionId = sessions.keys().next().value;
+        if (!oldestSessionId)
+            break;
+        sessions.delete(oldestSessionId);
+    }
+}
+/**
+ * @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 function createPremiumSessionPlan(request) {
+    pruneExpiredSessions();
+    const resolved = findPremiumCapability(request.pluginId, request.capabilityId, request.capabilityType);
+    if (!resolved) {
+        throw new Error(`unknown_premium_capability:${request.pluginId}/${request.capabilityId}`);
+    }
+    const { capability } = resolved;
+    // Clamp buyer-requested values to the capability's allowed bounds.
+    const requestedUnits = clampInteger(request.requestedUnits, capability.pricing.minUnits, capability.pricing.maxUnits);
+    const ttlSeconds = clampInteger(request.ttlSeconds, 60, 3_600);
+    // Calculate estimated price with 6 decimal places of precision.
+    const estimatedPriceUsd = Number((requestedUnits * capability.pricing.unitPriceUsd).toFixed(6));
+    const now = new Date();
+    const expiresAt = new Date(now.getTime() + ttlSeconds * 1000);
+    // Provider readiness: every declared env var must be truthy in process.env.
+    const providerReady = capability.providerEnv.every(envName => Boolean(process.env[envName]));
+    // Status depends on whether the capability needs an external provider.
+    const status = capability.requiresProvider && !providerReady ? 'blocked_requires_provider' : 'pending_payment';
+    // Next-action guidance is the only human-readable instruction the agent gets.
+    const nextAction = capability.requiresProvider && !providerReady
+        ? `Configure provider env vars first: ${capability.providerEnv.join(', ')}. No x402 payment should be attempted until the provider is ready.`
+        : 'Activate this plan through the premium stream/webhook transport once the paid delivery endpoint is enabled. Keep payment receipts bound to this session id.';
+    const record = {
+        ...request,
+        requestedUnits,
+        ttlSeconds,
+        sessionId: `sap-premium-${randomUUID()}`,
+        status,
+        providerReady,
+        createdAt: now.toISOString(),
+        expiresAt: expiresAt.toISOString(),
+        estimatedPriceUsd,
+        nextAction,
+    };
+    sessions.set(record.sessionId, record);
+    return record;
+}
+/**
+ * @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 function getPremiumSession(sessionId) {
+    const record = sessions.get(sessionId);
+    if (!record)
+        return null;
+    // Lazy expiration: update status in-place if TTL has passed.
+    // Active sessions are not expired by TTL — they are closed by the delivery rail.
+    if (record.status !== 'active' && record.status !== 'closed' && record.status !== 'expired') {
+        if (new Date(record.expiresAt).getTime() <= Date.now()) {
+            const expired = { ...record, status: 'expired', nextAction: 'Create a fresh session plan before opening a paid stream or webhook.' };
+            sessions.set(sessionId, expired);
+            return expired;
+        }
+    }
+    return { ...record };
+}
+/**
+ * @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 function listPremiumSessions() {
+    pruneExpiredSessions();
+    return [...sessions.keys()].map(sessionId => getPremiumSession(sessionId)).filter((record) => record !== null);
+}
+/**
+ * @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 function activateSession(sessionId) {
+    const record = sessions.get(sessionId);
+    if (!record) {
+        return {
+            sessionId,
+            status: 'expired',
+            activatedAt: null,
+            receiptBound: false,
+            unitsQuota: 0,
+            reason: 'Session not found. Create a fresh session plan before activation.',
+        };
+    }
+    if (record.status === 'blocked_requires_provider') {
+        return {
+            sessionId,
+            status: 'blocked_requires_provider',
+            activatedAt: null,
+            receiptBound: false,
+            unitsQuota: 0,
+            reason: 'Provider is not ready. Configure provider env vars before activating.',
+        };
+    }
+    if (record.status === 'expired') {
+        return {
+            sessionId,
+            status: 'expired',
+            activatedAt: null,
+            receiptBound: false,
+            unitsQuota: 0,
+            reason: 'Session has expired. Create a fresh session plan.',
+        };
+    }
+    if (record.status === 'active') {
+        return {
+            sessionId,
+            status: 'active',
+            activatedAt: record.createdAt,
+            receiptBound: true,
+            unitsQuota: record.requestedUnits,
+            reason: 'Session is already active.',
+        };
+    }
+    if (record.status === 'closed') {
+        return {
+            sessionId,
+            status: 'closed',
+            activatedAt: null,
+            receiptBound: false,
+            unitsQuota: 0,
+            reason: 'Session has been closed. Create a fresh session plan.',
+        };
+    }
+    // Status is pending_payment — transition to active.
+    const now = new Date().toISOString();
+    const activated = {
+        ...record,
+        status: 'active',
+        nextAction: 'Session is active. Stream/webhook delivery is enabled. Units are metered until quota is reached or the session is closed.',
+    };
+    sessions.set(sessionId, activated);
+    return {
+        sessionId,
+        status: 'active',
+        activatedAt: now,
+        receiptBound: true,
+        unitsQuota: record.requestedUnits,
+        reason: 'Session activated successfully. Delivery rail is enabled.',
+    };
+}
+/**
+ * @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 function closeSession(sessionId, reason) {
+    const record = sessions.get(sessionId);
+    if (!record || record.status !== 'active')
+        return false;
+    const closed = {
+        ...record,
+        status: 'closed',
+        nextAction: `Session closed: ${reason}. Create a fresh session plan to resume delivery.`,
+    };
+    sessions.set(sessionId, closed);
+    return true;
+}
+/**
+ * @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 function decrementSessionQuota(sessionId) {
+    const record = sessions.get(sessionId);
+    if (!record || record.status !== 'active')
+        return -1;
+    const remaining = Math.max(0, record.requestedUnits - 1);
+    const updated = {
+        ...record,
+        requestedUnits: remaining,
+    };
+    sessions.set(sessionId, updated);
+    if (remaining === 0) {
+        closeSession(sessionId, 'Unit quota exhausted.');
+    }
+    return remaining;
+}
+/**
+ * @name clearAllSessions
+ * @description Clear all sessions from the in-memory store.
+ *
+ * Used in tests and during graceful server shutdown.
+ *
+ * @internal
+ */
+export function clearAllSessions() {
+    sessions.clear();
+}
+//# sourceMappingURL=session-manager.js.map

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

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

package/dist/premium/stream-broker.d.ts

@@ -0,0 +1,98 @@
+/**
+ * @name premium/stream-broker
+ * @description SSE stream broker for premium real-time event delivery.
+ *
+ * After a session is activated (`status=active`), the stream broker opens a
+ * provider subscription, enriches each event with session metadata, stores it
+ * in the event store for replay, and delivers it to the buyer via SSE
+ * (Server-Sent Events) over the `/premium/stream/:sessionId` HTTP endpoint.
+ *
+ * The broker enforces:
+ *   - Unit quota: stops delivery when `requestedUnits` reaches zero.
+ *   - Session status: only delivers for `status=active` sessions.
+ *   - Event idempotency: deduplicates via `eventId` in the event store.
+ *   - Graceful shutdown: closes all active streams on disconnect.
+ *
+ * @flow
+ *   1. Buyer calls `GET /premium/stream/:sessionId` with `Accept: text/event-stream`.
+ *   2. → `startStream()` validates session is active, loads provider adapter.
+ *   3. → Provider `subscribe()` returns async iterable of `ProviderEvent`.
+ *   4. → For each event: enrich with session metadata, `appendEvent()`, write SSE.
+ *   5. → `decrementSessionQuota()` after each event; auto-close at zero.
+ *   6. Client disconnects or quota exhausted → `stopStream()`.
+ *
+ * @module premium/stream-broker
+ */
+import type { PremiumStreamSubscription, ProviderEvent } from './types.js';
+/**
+ * @name startStream
+ * @description Start a premium stream subscription for an active session.
+ *
+ * @param sessionId      - The activated premium session id.
+ * @param subscriptionKey - De-duplication key from the stream input schema.
+ * @param filters        - Narrow filters for the provider subscription.
+ * @returns The `PremiumStreamSubscription` if successful, or `null` if the
+ *   session is not active or the provider is not available.
+ *
+ * @usedBy `remote/server.ts` → `GET /premium/stream/:sessionId`
+ */
+export declare function startStream(sessionId: string, subscriptionKey: string, filters: Record<string, unknown>): Promise<PremiumStreamSubscription | null>;
+/**
+ * @name streamEvents
+ * @description Async generator that yields enriched premium events for a session.
+ *
+ * This is the core delivery loop. It:
+ *   1. Loads the provider adapter for the session's plugin/capability.
+ *   2. Subscribes with the session's filters.
+ *   3. For each provider event: enriches with session metadata, appends to the
+ *      event store, decrements the unit quota, and yields the enriched event.
+ *   4. Stops when the quota reaches zero, the provider iterable ends, or the
+ *      stream is cancelled via `stopStream()`.
+ *
+ * @param sessionId - The active session id.
+ * @returns Async generator yielding `ProviderEvent` enriched with session metadata.
+ *
+ * @usedBy `remote/server.ts` → SSE response writer
+ */
+export declare function streamEvents(sessionId: string): AsyncGenerator<ProviderEvent, void, unknown>;
+/**
+ * @name stopStream
+ * @description Stop an active stream subscription.
+ *
+ * Aborts the provider async iterable and marks the subscription as inactive.
+ * The session is not closed — the buyer can resume with a replay query.
+ *
+ * @param sessionId - The session id to stop streaming for.
+ *
+ * @usedBy `remote/server.ts` → client disconnect handler
+ */
+export declare function stopStream(sessionId: string): void;
+/**
+ * @name replayEvents
+ * @description Replay past events for a session within the replay window.
+ *
+ * Used when a client reconnects and needs to catch up on events missed
+ * during the disconnection period.
+ *
+ * @param sessionId - The session id to replay events for.
+ * @param since     - Optional ISO timestamp; only events after this are returned.
+ * @returns Array of `ProviderEvent` records from the event store.
+ *
+ * @usedBy `remote/server.ts` → SSE replay before live stream
+ */
+export declare function replayEvents(sessionId: string, since?: string): ProviderEvent[];
+/**
+ * @name getActiveStreamCount
+ * @description Return the number of currently active stream subscriptions.
+ *
+ * @usedBy `metrics.ts`
+ */
+export declare function getActiveStreamCount(): number;
+/**
+ * @name stopAllStreams
+ * @description Stop all active streams. Called during graceful shutdown.
+ *
+ * @usedBy `remote/server.ts` shutdown handler
+ */
+export declare function stopAllStreams(): void;
+//# sourceMappingURL=stream-broker.d.ts.map

package/dist/premium/stream-broker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-broker.d.ts","sourceRoot":"","sources":["../../src/premium/stream-broker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,yBAAyB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAgB3E;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,CAC/B,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC,CAqB3C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAuB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAAC,aAAa,EAAE,IAAI,EAAE,OAAO,CAAC,CAmDnG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAYlD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,aAAa,EAAE,CAO/E;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAIrC"}