@supportbridge/sdk 0.8.1

package/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+## 0.8.1
+
+- Versioned the embedded chat resource URI so MCP hosts refresh the redesigned UI instead of reusing a cached pre-0.8 chat document.
+
+## 0.8.0
+
+- Redesigned the embedded support chat with distinct customer/support messages, representative identity, compact mode, quieter system activity, unread indicators, multiline composing, delivery feedback, and responsive styling.
+- Replaced technical Slack identifiers in the customer-facing header with human-readable presence and conversation status.
+- Added explicit close and reopen states, including a control-plane reopen endpoint and MCP App tool.
+- Improved ticket-detail privacy by moving the conversation identifier into an optional details menu.
+
+## 0.7.0
+
+- Added `require_acknowledgement`, a non-blocking policy action that returns business data while appending a visible, consent-safe assistance offer.
+- Added explicit pending offer metadata and control-plane lifecycle persistence for pending, presented, accepted, declined, and expired offers.
+- Added the acknowledgement action to the dashboard and natural-language policy compiler.
+- Preserved the existing metadata-only offer and blocking decision modes for backward compatibility.
+- Added optional Slack notifications for new live-help chats and new customer messages in existing chats.
+
+## 0.6.0
+
+- Added representative availability as a control-plane policy eligibility condition.
+- Added the mock Sarah representative with Available, Away, and Offline dashboard presence.
+- Added `request_assistance` for accepted sales and customer-success assistance offers.
+- Automatically assigns accepted assistance requests to the policy's representative.
+
+# 0.5.0
+
+- Added the canonical SupportBridge policy schema, approved field/action registries, deterministic validation and evaluation, nested Boolean conditions, explanations, conflict analysis, decision traces, dry runs, event-loop prevention, and idempotent action execution.
+- Added a vendor-neutral NLP provider contract and deterministic fake compiler for local development and tests.
+- Added approval, immutable version, disable, rollback, diff, test-case, and audit lifecycle primitives.
+- Added the embedded Claude policy-builder MCP App with AI/manual authoring modes, canonical preview, validation, and read-only simulation.
+
+## 0.4.0
+
+- Ported the MCP App lifecycle, metadata, session shape, and UI behavior from the known-working `ballyhoogroup/supportbridge` connector.
+- Added the proven `open_support_chat`, `support_get_messages`, `support_send_message`, and `support_end_session` contract.
+- Added preferred-frame resource metadata and the working inline display capability handshake.
+- Added a compatibility fixture and conformance assertions to prevent drift from the working connector.
+- Connected the proven chat lifecycle to the external multi-tenant control plane.
+
+## 0.3.1
+
+- Added a model-visible, MCP-App-linked `talk_to_support` tool.
+- Added reopening of an existing ticket by ID so a missing or scrolled-away widget can be rendered again.
+- Ensured new and reopened chats return the state required by the embedded app.
+
+## 0.3.0
+
+- Added one-call installation for the official TypeScript MCP SDK.
+- Added automatic support-tool, MCP App resource, chat-handler, policy-sync, and shutdown registration.
+- Added a single shared identity resolver and automatic recent-tool ticket briefs.
+- Added installation capability telemetry, dashboard connection status, and `supportbridge doctor`.
+
+## 0.2.0
+
+- Added a portable MCP App resource for embedded SupportBridge live chat.
+- Added ticket creation to `accept_support_offer` when a control-plane client is supplied.
+- Added app-only chat refresh and message handlers with a text fallback for non-App hosts.
+
+## 0.1.0
+
+- Added framework-neutral tool-call instrumentation and MCP result adaptation.
+- Added sanitized, bounded telemetry with buffered HTTP delivery.
+- Added argument-match and repeated-failure support triggers.
+- Added blocking support offers with accept, dismiss, and reset state.
+- Added optional agent and model spans with async trace propagation.
+- Added pluggable telemetry transports and trigger-state stores.
+- Added remote policy synchronization and support-chat control-plane client.
+- Added a tenant-scoped vendor control plane with Live Streams, Visitor 360, chat, and policy management.
+

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2026 SupportBridge
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,326 @@
+# SupportBridge SDK
+
+`@supportbridge/sdk` is the external, production-oriented SDK for adding tool-call telemetry, optional agent telemetry, configurable support triggers, deterministic operational policies, and MCP-compatible support experiences to software-company MCP servers.
+
+This package is independent from the internal SupportBridge demo. It does not import the demo server, dashboard, database, or test-user implementation.
+
+## What the first release provides
+
+- Framework-neutral MCP tool instrumentation
+- Tool name, timing, outcome, request correlation, sanitized arguments, and bounded result summaries
+- Optional agent-run and model-call spans
+- Async-local trace propagation from agent runs into MCP tool events
+- Immediate or non-blocking support-offer triggers
+- Repeated-failure triggers
+- Per-user, per-workspace, per-trace, or always-on trigger scopes
+- Accept, dismiss, and explicit reset decisions
+- Default secret redaction and payload-size limits
+- Batched asynchronous HTTP delivery with bounded retries
+- Queue overflow protection and fail-open behavior
+- Pluggable telemetry transport and trigger-state storage
+- Canonical, versioned policy schema with nested AND/OR/NOT conditions
+- Approved field and action registries with tenant-reference validation
+- Deterministic evaluation, traces, dry runs, conflict detection, and idempotent execution
+- Vendor-neutral natural-language compiler interface and deterministic local fake provider
+- Approval, immutable-version, rollback, and audit lifecycle primitives
+- An interactive MCP policy-builder app for Claude
+
+## Install
+
+During local development:
+
+```bash
+npm install ./supportbridge-sdk
+```
+
+After publishing:
+
+```bash
+npm install @supportbridge/sdk
+```
+
+Node.js 20 or newer is required.
+
+## Recommended one-call MCP installation
+
+For the official TypeScript MCP SDK, one call installs remote policy synchronization, support decisions, the UI-linked `talk_to_support` tool, the embedded chat app, app-only chat handlers, capability reporting, and graceful shutdown behavior:
+
+```ts
+import { SupportBridge } from "@supportbridge/sdk";
+
+const support = SupportBridge.install(server, {
+  source: "acme-mcp",
+  apiKey: process.env.SUPPORTBRIDGE_API_KEY!,
+  identify: context => ({
+    userId: context.authInfo.subject,
+    workspaceId: context.authInfo.workspaceId,
+    traits: { customer: context.authInfo.organizationName }
+  })
+});
+```
+
+Use the returned installer to wrap each business tool while keeping the same identity resolver:
+
+```ts
+server.tool(
+  "search_companies",
+  searchSchema,
+  support.instrumentTool("search_companies", searchCompanies)
+);
+```
+
+The wrapper captures bounded telemetry, enforces downloaded support triggers before execution, and retains recent sanitized failures for automatic ticket context. The installation also registers `open_policy_builder` and its embedded interactive app. No support tools or UI resources need to be registered manually.
+
+## Deterministic policy engine
+
+Natural language is never executable. A `PolicyNlpProvider` can propose a `CanonicalPolicy`, then deterministic code validates approved fields, operators, events, action parameters, and workspace-scoped references before simulation or publication.
+
+```ts
+import {
+  FakePolicyNlpProvider,
+  PolicyEngine,
+  PolicyRegistry,
+  validatePolicy
+} from "@supportbridge/sdk";
+
+const provider = new FakePolicyNlpProvider();
+const draft = await provider.compile({
+  prompt: "Route urgent enterprise billing conversations to Finance.",
+  workspaceId: "acme",
+  actorId: "admin_123",
+  references: { financeTeamId: "team_finance" }
+});
+
+const registry = new PolicyRegistry();
+const validation = validatePolicy(draft.policy, { registry });
+if (!validation.valid) throw new Error("Review the validation errors");
+
+const decision = new PolicyEngine(registry).evaluate(
+  [{ ...draft.policy, enabled: true, state: "dry_run" }],
+  { type: "conversation.created" },
+  { customer: { plan: "enterprise" }, conversation: { priority: "urgent" }, message: { classification: "billing" } },
+  { now: new Date(), eventId: "evt_1", correlationId: "corr_1", workspaceId: "acme" }
+);
+```
+
+Evaluation produces a decision plan; it never performs actions. Pass a plan to `executeDecisionPlan` with your authorized executor and durable `IdempotencyStore`. See [the policy engine guide](docs/policy-engine.md) for registries, lifecycle, simulations, and production adapters.
+
+If the embedded widget is missing or has scrolled out of view, the model calls `open_support_chat` with the existing `session_id`. Both `talk_to_support` and `open_support_chat` use the exact UI metadata and conversation lifecycle ported from the known-working SupportBridge connector. The embedded app uses `support_get_messages`, `support_send_message`, and `support_end_session` for the live conversation.
+
+Availability-gated sales and customer-success policies can assign an offer to a representative in the control plane. Eligible offers are published only while that representative is available. After the user agrees, the model calls `request_assistance`; the resulting live conversation is automatically assigned to the configured representative.
+
+Verify an installation with:
+
+```bash
+npx supportbridge doctor
+```
+
+Set `SUPPORTBRIDGE_URL` and `SUPPORTBRIDGE_API_KEY` first. The command checks health, authentication, policy retrieval, telemetry ingestion, and the packaged MCP App capability. The vendor dashboard reports the MCP source, installed SDK version, capabilities, and last-seen connection state.
+
+## Capture an MCP tool
+
+```ts
+import { SupportBridgeClient, instrumentMcpTool } from "@supportbridge/sdk";
+
+const supportbridge = new SupportBridgeClient({
+  source: "acme-mcp",
+  endpoint: "https://api.supportbridge.example",
+  apiKey: process.env.SUPPORTBRIDGE_API_KEY!,
+  triggers: [{
+    id: "climate-tech-concierge",
+    kind: "argument_match",
+    toolName: "list_companies",
+    path: "industry",
+    operator: "equals",
+    value: "Climate Tech",
+    action: "block_and_offer",
+    oncePer: "user"
+  }]
+});
+
+const listCompanies = instrumentMcpTool(
+  supportbridge,
+  "list_companies",
+  async args => ({
+    content: [{ type: "text", text: "Company results" }],
+    structuredContent: { count: 12 }
+  }),
+  {
+    identify: (_args, context) => ({
+      userId: context.auth.subject,
+      workspaceId: context.auth.workspaceId
+    })
+  }
+);
+```
+
+When the blocking trigger matches, the vendor handler is not executed. The MCP result contains:
+
+```json
+{
+  "isError": true,
+  "structuredContent": {
+    "support_available": true,
+    "support_offer_blocking": true,
+    "support_trigger_id": "climate-tech-concierge",
+    "accept_tool": "accept_support_offer",
+    "decline_tool": "dismiss_support_offer",
+    "retry_original_request_after_response": true
+  }
+}
+```
+
+For a visible offer that does not withhold the business result, use `action: "require_acknowledgement"`. The SDK preserves the original `content` and `structuredContent`, appends a transparent `LIVE ASSISTANCE AVAILABLE` content block, and includes pending offer state plus the consent-gated accept and decline tool names. This is the recommended cross-host mode when an ordinary metadata-only offer may be omitted by the model.
+
+Register the handlers returned by `supportDecisionTools` as MCP tools. After a user dismisses an offer, the original request can be retried without looping. Call `resetSupport` to make that trigger eligible again.
+
+## Embedded support chat (MCP App)
+
+`accept_support_offer` can create a durable ticket and open an inline chat in hosts that support the MCP Apps extension. Create the app kit and attach its metadata to the registered accept tool:
+
+```ts
+import {
+  createSupportChatApp,
+  supportDecisionTools
+} from "@supportbridge/sdk";
+
+const supportApp = createSupportChatApp(controlPlane);
+const decisions = supportDecisionTools(
+  supportbridge,
+  context => identifyUser(context),
+  { controlPlane, appMeta: supportApp.toolMeta }
+);
+```
+
+The MCP server must register these pieces using its framework:
+
+- `accept_support_offer`, with `supportApp.toolMeta` on the **tool definition**.
+- `dismiss_support_offer` as a normal model-visible tool.
+- `get_support_chat` and `send_support_message` from `supportApp.tools`, with app-only visibility.
+- A resource at `supportApp.resourceUri` whose read callback returns `supportApp.resourceContents()` and whose MIME type is `supportApp.mimeType`.
+
+For the official TypeScript MCP Apps SDK, use `registerAppTool` and `registerAppResource` from `@modelcontextprotocol/ext-apps/server`. The critical registration shape is:
+
+```ts
+registerAppTool(server, "accept_support_offer", {
+  description: "Open the human support conversation after the user consents.",
+  inputSchema: acceptSchema,
+  _meta: supportApp.toolMeta
+}, decisions.accept_support_offer);
+
+registerAppTool(server, "get_support_chat", {
+  inputSchema: getChatSchema,
+  _meta: { ui: { resourceUri: supportApp.resourceUri, visibility: ["app"] } }
+}, supportApp.tools.get_support_chat);
+
+registerAppTool(server, "send_support_message", {
+  inputSchema: sendMessageSchema,
+  _meta: { ui: { resourceUri: supportApp.resourceUri, visibility: ["app"] } }
+}, supportApp.tools.send_support_message);
+
+registerAppResource(server, "SupportBridge chat", supportApp.resourceUri, {
+  mimeType: supportApp.mimeType,
+  _meta: supportApp.resourceMeta
+}, async () => supportApp.resourceContents());
+```
+
+The HTML uses the standard `text/html;profile=mcp-app` resource type and MCP Apps JSON-RPC bridge. It receives the ticket ID from the accept-tool result, polls the ticket, and sends user messages through app-only MCP tools. Hosts without MCP Apps support continue to receive the ordinary text result.
+
+## Direct tool instrumentation
+
+For frameworks with custom middleware:
+
+```ts
+const result = await supportbridge.instrumentTool(
+  {
+    toolName: "search_companies",
+    arguments: { query: "fintech" },
+    identity: { userId: "user_34892", workspaceId: "acme" }
+  },
+  () => searchCompanies("fintech")
+);
+```
+
+The return value is discriminated by `kind`:
+
+- `result`: the vendor tool executed and `value` contains its result.
+- `support_offer`: execution was paused and `offer` contains the support decision payload.
+
+## Agent telemetry
+
+```ts
+import { traceAgentRun } from "@supportbridge/sdk";
+
+await traceAgentRun(
+  supportbridge,
+  {
+    agentName: "research-agent",
+    identity: { userId: "user_34892", workspaceId: "acme" }
+  },
+  async span => {
+    const startedAt = performance.now();
+    const response = await callYourModel();
+    span.recordModelCall({
+      provider: "your-provider",
+      model: "your-model",
+      startedAt,
+      inputTokens: response.usage.input,
+      outputTokens: response.usage.output
+    });
+    return response;
+  }
+);
+```
+
+Tool calls made inside `traceAgentRun` automatically inherit its trace and run identifiers through `AsyncLocalStorage`.
+
+## Privacy defaults
+
+The SDK captures sanitized tool arguments and bounded result summaries. It does **not** capture prompts or model responses unless `captureAgentContent` is explicitly enabled.
+
+Recognized credential fields are replaced with `[REDACTED]`. Payload depth, strings, arrays, and object keys are bounded before they enter the telemetry queue.
+
+```ts
+privacy: {
+  captureToolArguments: true,
+  captureToolResponses: true,
+  captureAgentContent: false,
+  sensitiveKeys: ["customer_access_code"],
+  maxStringLength: 1000
+}
+```
+
+Software companies should still document telemetry collection, obtain any required consent, and avoid sending regulated or unnecessary data.
+
+## Reliability model
+
+Telemetry is delivered outside the tool execution path. Delivery uses batches, timeouts, bounded exponential retries, and a maximum queue size. If SupportBridge is unavailable, vendor tools continue to operate and telemetry is dropped after the configured retry limit.
+
+Call `flush()` before short-lived processes exit and `close()` during graceful shutdown:
+
+```ts
+process.once("SIGTERM", () => void supportbridge.close());
+```
+
+## Trigger-state storage
+
+The default `MemoryTriggerStateStore` is appropriate for local development and a single process. Production vendors should supply a `TriggerStateStore` backed by Redis, PostgreSQL, or the SupportBridge control plane so decisions remain consistent across instances.
+
+## Development
+
+From this directory:
+
+```bash
+npm run check
+npm test
+npm run build
+```
+
+The package intentionally has no runtime dependency on a particular MCP or agent framework. Framework-specific adapters can be added as separate packages without changing the core telemetry contract.
+
+See [the telemetry contract](docs/telemetry-contract.md) for backend ingestion details and [the security guide](SECURITY.md) before a production deployment.
+
+## Hosted control plane
+
+The repository also contains the first vendor-facing control plane in [`control-plane`](control-plane). It provides tenant-authenticated telemetry ingestion, SDK policy distribution, support conversations, and a live-visitor console with Visitor 360 context. See its [deployment and integration guide](control-plane/README.md).
+

package/SECURITY.md

@@ -0,0 +1,26 @@
+# Security and privacy
+
+SupportBridge telemetry may contain customer context. Integrators are responsible for choosing what they collect and for meeting their own disclosure, consent, retention, and regulatory obligations.
+
+## Safe defaults
+
+- Prompt and model-response capture is disabled by default.
+- Common credential fields and bearer tokens are redacted before queueing.
+- Strings, arrays, object keys, and nesting depth are bounded.
+- Telemetry delivery is fail-open and never intentionally exposes the configured API key in an event.
+- The SDK has no runtime dependencies.
+
+Redaction is defense in depth, not a substitute for minimizing data at the integration boundary. Do not pass credentials or regulated data in tool arguments when it is avoidable. Add product-specific field names to `privacy.sensitiveKeys`.
+
+## Deployment recommendations
+
+- Send telemetry only to a TLS endpoint you control or trust.
+- Load the SupportBridge API key from a secret manager and rotate it regularly.
+- Use a durable `TriggerStateStore` in multi-instance deployments.
+- Apply least-privilege access and retention controls to the telemetry backend.
+- Review custom result summarizers; they run before the SDK sanitizer.
+- Call `close()` during graceful shutdown to flush queued events.
+
+## Reporting a vulnerability
+
+Do not include secrets, customer data, or exploit details in a public issue. Contact the package maintainer through the private security channel configured for the SupportBridge project. A public reporting address will be added before registry publication.

package/dist/agent.d.ts

@@ -0,0 +1,9 @@
+import type { SupportBridgeClient } from "./client.js";
+import type { AgentRunOptions, ModelCallOptions } from "./types.js";
+export interface AgentRunSpan {
+    readonly traceId: string;
+    readonly runId: string;
+    recordModelCall(options: ModelCallOptions): void;
+}
+export declare function traceAgentRun<T>(client: SupportBridgeClient, options: AgentRunOptions, operation: (span: AgentRunSpan) => Promise<T> | T): Promise<T>;
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,KAAK,EAAiB,eAAe,EAAkB,gBAAgB,EAAgB,MAAM,YAAY,CAAC;AAEjH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAClD;AAED,wBAAsB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,mBAAmB,EAAE,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAmC3J"}

package/dist/agent.js

@@ -0,0 +1,73 @@
+import { randomUUID } from "node:crypto";
+import { currentTraceContext, runWithTrace } from "./context.js";
+import { errorDetails, sanitize, sanitizeText } from "./sanitize.js";
+export async function traceAgentRun(client, options, operation) {
+    const parent = currentTraceContext();
+    const traceId = options.traceId ?? parent?.traceId ?? randomUUID();
+    const runId = options.runId ?? randomUUID();
+    const spanId = randomUUID();
+    const startedAt = performance.now();
+    const identity = options.identity ?? parent?.identity;
+    const context = {
+        traceId, runId, parentSpanId: spanId,
+        ...(identity ? { identity } : {})
+    };
+    const started = {
+        ...eventBase(client, options, traceId, runId, spanId), type: "agent_run", agentName: options.agentName, phase: "started"
+    };
+    client.recordTelemetry(started);
+    const span = {
+        traceId, runId,
+        recordModelCall: model => recordModelCall(client, model, context, spanId)
+    };
+    try {
+        const result = await runWithTrace(context, () => operation(span));
+        client.recordTelemetry({
+            ...eventBase(client, options, traceId, runId, spanId), type: "agent_run", agentName: options.agentName,
+            phase: "completed", outcome: "success", durationMs: elapsed(startedAt)
+        });
+        return result;
+    }
+    catch (error) {
+        const details = errorDetails(error);
+        client.recordTelemetry({
+            ...eventBase(client, options, traceId, runId, spanId), type: "agent_run", agentName: options.agentName,
+            phase: "completed", outcome: "error", durationMs: elapsed(startedAt),
+            ...(details.errorCode ? { errorCode: details.errorCode } : {}), errorMessage: details.errorMessage
+        });
+        throw error;
+    }
+}
+function recordModelCall(client, options, context, parentSpanId) {
+    const details = options.error ? errorDetails(options.error) : undefined;
+    const outcome = details ? (/timeout|timed out/i.test(details.errorMessage) ? "timeout" : "error") : "success";
+    const event = {
+        ...client.baseEvent({
+            ...(context.identity ? { identity: context.identity } : {}), traceId: context.traceId,
+            ...(context.runId ? { runId: context.runId } : {}), spanId: randomUUID(), parentSpanId
+        }),
+        type: "model_call", provider: options.provider, model: options.model, outcome,
+        durationMs: elapsed(options.startedAt ?? performance.now()),
+        ...(options.inputTokens !== undefined ? { inputTokens: options.inputTokens } : {}),
+        ...(options.outputTokens !== undefined ? { outputTokens: options.outputTokens } : {}),
+        ...(options.costUsd !== undefined ? { costUsd: options.costUsd } : {}),
+        ...(client.privacy.captureAgentContent && options.prompt !== undefined ? { prompt: sanitize(options.prompt, client.privacy) } : {}),
+        ...(client.privacy.captureAgentContent && options.response !== undefined ? { response: sanitize(options.response, client.privacy) } : {}),
+        ...(details?.errorCode ? { errorCode: details.errorCode } : {}),
+        ...(details?.errorMessage ? { errorMessage: sanitizeText(details.errorMessage, client.privacy) } : {}),
+        ...(options.attributes ? { attributes: sanitize(options.attributes, client.privacy) } : {})
+    };
+    client.recordTelemetry(event);
+}
+function eventBase(client, options, traceId, runId, spanId) {
+    return {
+        ...client.baseEvent({
+            ...(options.identity ? { identity: options.identity } : {}), traceId, runId, spanId
+        }),
+        ...(options.attributes ? { attributes: sanitize(options.attributes, client.privacy) } : {})
+    };
+}
+function elapsed(startedAt) {
+    return Math.max(0, Math.round((performance.now() - startedAt) * 100) / 100);
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAUrE,MAAM,CAAC,KAAK,UAAU,aAAa,CAAI,MAA2B,EAAE,OAAwB,EAAE,SAAiD;IAC7I,MAAM,MAAM,GAAG,mBAAmB,EAAE,CAAC;IACrC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,MAAM,EAAE,OAAO,IAAI,UAAU,EAAE,CAAC;IACnE,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,EAAE,CAAC;IAC5C,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IACpC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,MAAM,EAAE,QAAQ,CAAC;IACtD,MAAM,OAAO,GAAiB;QAC5B,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM;QACpC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAClC,CAAC;IACF,MAAM,OAAO,GAAkB;QAC7B,GAAG,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,KAAK,EAAE,SAAS;KACzH,CAAC;IACF,MAAM,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;IAChC,MAAM,IAAI,GAAiB;QACzB,OAAO,EAAE,KAAK;QACd,eAAe,EAAE,KAAK,CAAC,EAAE,CAAC,eAAe,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC;KAC1E,CAAC;IACF,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;QAClE,MAAM,CAAC,eAAe,CAAC;YACrB,GAAG,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS;YACtG,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,CAAC,SAAS,CAAC;SACvE,CAAC,CAAC;QACH,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;QACpC,MAAM,CAAC,eAAe,CAAC;YACrB,GAAG,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS;YACtG,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,CAAC,SAAS,CAAC;YACpE,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY;SACnG,CAAC,CAAC;QACH,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,eAAe,CAAC,MAA2B,EAAE,OAAyB,EAAE,OAAqB,EAAE,YAAoB;IAC1H,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACxE,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,oBAAoB,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC9G,MAAM,KAAK,GAAmB;QAC5B,GAAG,MAAM,CAAC,SAAS,CAAC;YAClB,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO;YACrF,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,YAAY;SACvF,CAAC;QACF,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,OAAO;QAC7E,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,SAAS,IAAI,WAAW,CAAC,GAAG,EAAE,CAAC;QAC3D,GAAG,CAAC,OAAO,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClF,GAAG,CAAC,OAAO,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrF,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtE,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,mBAAmB,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,mBAAmB,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzI,GAAG,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7D,GAAG,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,YAAY,CAAC,OAAO,CAAC,YAAY,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtG,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,QAAQ,CAAC,OAAO,CAAC,UAAU,EAAE,MAAM,CAAC,OAAO,CAAmD,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChJ,CAAC;IACF,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;AAChC,CAAC;AAED,SAAS,SAAS,CAAC,MAA2B,EAAE,OAAwB,EAAE,OAAe,EAAE,KAAa,EAAE,MAAc;IACtH,OAAO;QACL,GAAG,MAAM,CAAC,SAAS,CAAC;YAClB,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM;SACpF,CAAC;QACF,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,QAAQ,CAAC,OAAO,CAAC,UAAU,EAAE,MAAM,CAAC,OAAO,CAAmD,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9I,CAAC;AACJ,CAAC;AAED,SAAS,OAAO,CAAC,SAAiB;IAChC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC;AAC9E,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,68 @@
+import { type TriggerStateStore } from "./state.js";
+import { TriggerEngine } from "./triggers.js";
+import { type BufferedTransportOptions, type HttpTransportOptions, type TelemetryTransport } from "./transport.js";
+import type { InstrumentedToolResult, JsonValue, PrivacyOptions, ResolvedPrivacyOptions, SupportBrief, SupportDecision, SupportIdentity, SupportOffer, SupportTrigger, TelemetryEvent, TelemetryEventBase, ToolInvocation, ToolOutcome } from "./types.js";
+import type { PolicyDecisionPlan, PolicyEvaluationContext } from "./policy.js";
+export interface SupportBridgeClientOptions {
+    source: string;
+    environment?: string;
+    serviceVersion?: string;
+    endpoint?: string;
+    apiKey?: string;
+    transport?: TelemetryTransport;
+    http?: Omit<HttpTransportOptions, "endpoint" | "apiKey">;
+    buffer?: BufferedTransportOptions;
+    privacy?: PrivacyOptions;
+    triggers?: SupportTrigger[];
+    triggerState?: TriggerStateStore;
+    summarizeResult?: (result: unknown) => unknown;
+}
+export interface InstrumentToolOptions<TResult> {
+    summarizeResult?: (result: TResult) => unknown;
+    classifyResult?: (result: TResult) => ToolOutcome;
+}
+export declare class SupportBridgeToolError extends Error {
+    readonly supportOffer?: SupportOffer;
+    readonly original: unknown;
+    constructor(original: unknown, supportOffer?: SupportOffer);
+}
+export declare class SupportBridgeClient {
+    readonly privacy: ResolvedPrivacyOptions;
+    readonly triggers: TriggerEngine;
+    private readonly delivery;
+    private readonly source;
+    private readonly environment;
+    private readonly serviceVersion;
+    private readonly defaultSummarizer;
+    private readonly recentTools;
+    constructor(options: SupportBridgeClientOptions);
+    instrumentTool<TArguments, TResult>(invocation: ToolInvocation<TArguments>, handler: () => Promise<TResult> | TResult, options?: InstrumentToolOptions<TResult>): Promise<InstrumentedToolResult<TResult>>;
+    wrapTool<TArguments, TResult>(toolName: string, handler: (args: TArguments) => Promise<TResult> | TResult, identify: (args: TArguments) => SupportIdentity | undefined, options?: InstrumentToolOptions<TResult>): (args: TArguments) => Promise<InstrumentedToolResult<TResult>>;
+    decideSupport(triggerId: string, identity: SupportIdentity | undefined, decision: SupportDecision, traceId?: string): Promise<void>;
+    resetSupport(triggerId: string, identity: SupportIdentity | undefined, traceId?: string): Promise<void>;
+    markSupportPresented(triggerId: string, identity: SupportIdentity | undefined, traceId?: string): void;
+    markSupportExpired(triggerId: string, identity: SupportIdentity | undefined, traceId?: string): void;
+    replaceTriggers(triggers: readonly SupportTrigger[]): void;
+    recordTelemetry(event: TelemetryEvent): void;
+    recordDiagnostic(code: "installation_verified" | "doctor_check", message: string, capabilities?: Record<string, JsonValue>): void;
+    recordPolicyEvaluation(plan: PolicyDecisionPlan, context: PolicyEvaluationContext, identity?: SupportIdentity): void;
+    buildSupportBrief(identity: SupportIdentity, fallbackIssue?: string): SupportBrief;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    get pendingTelemetryCount(): number;
+    baseEvent(fields?: {
+        identity?: SupportIdentity;
+        traceId?: string;
+        runId?: string;
+        spanId?: string;
+        parentSpanId?: string;
+    }): TelemetryEventBase;
+    private normalizeInvocation;
+    private captureTool;
+    private captureSupportDecision;
+    private eventBase;
+    private summarize;
+    private telemetryIdentity;
+    private telemetryAttributes;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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