@shivnandan/connector-react 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,107 @@
-# Temporary Holding Version
+# @tracepulse/connector-react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Drop-in transaction intelligence, observability, and autonomous AI copilot provider for React and Next.js applications.
+
+[![npm version](https://img.shields.io/badge/npm-v1.0.0-blue.svg)](https://npmjs.com/package/@tracepulse/connector-react)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Overview
+
+`@tracepulse/connector-react` acts as an embeddable dependency for any internal portal, CRM, or e-commerce host application. It injects a floating AI SRE assistant into the host UI that enables support teams and engineers to diagnose payment retries, Kafka milestone failures, and microservice anomalies in real-time.
+
+---
+
+## Installation
+
+```bash
+pnpm add @tracepulse/connector-react
+# or
+npm install @tracepulse/connector-react
+# or
+yarn add @tracepulse/connector-react
+```
+
+---
+
+## Quick Start
+
+### 1. Wrap Your Root Layout or App
+
+```tsx
+import { TracePulseProvider } from "@tracepulse/connector-react";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <TracePulseProvider
+          apiKey="tp_live_9a7bc449e"
+          projectId="airtel-retailer-portal"
+          endpoint="https://tracepulse-api.yourcompany.com"
+          position="bottom-right"
+        >
+          {children}
+        </TracePulseProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+### 2. Programmatic Control (`useTracePulse` Hook)
+
+You can trigger the AI Copilot programmatically from any button or table row in your application:
+
+```tsx
+import { useTracePulse } from "@tracepulse/connector-react";
+
+export function OrderRow({ leadId }: { leadId: string }) {
+  const { openCopilot } = useTracePulse();
+
+  return (
+    <div className="order-row">
+      <span>Lead #{leadId}</span>
+      <button onClick={() => openCopilot(leadId)}>
+        Diagnose with AI Copilot
+      </button>
+    </div>
+  );
+}
+```
+
+---
+
+## Props Reference
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `apiKey` | `string` | **Required** | Project API token for telemetry authentication. |
+| `projectId` | `string` | `"default-project"` | Microservice or tenant namespace identifier. |
+| `endpoint` | `string` | `"http://127.0.0.1:8000"` | Base URL of your TracePulse backend server. |
+| `targetTransactionId` | `string` | `undefined` | Pre-lock AI assistant to a specific `clientTxnId`. |
+| `position` | `"bottom-right" \| "bottom-left"` | `"bottom-right"` | Screen corner docking position. |
+| `floatingButton` | `boolean` | `true` | Set to `false` for headless mode (trigger via `useTracePulse`). |
+| `children` | `ReactNode` | `undefined` | Child components wrapped by the provider. |
+
+---
+
+## Headless Mode (Custom Trigger Button)
+
+If you prefer to design your own trigger button instead of the default floating action button:
+
+```tsx
+<TracePulseProvider
+  apiKey="tp_live_..."
+  floatingButton={false} // Hides default floating button
+>
+  <YourApp />
+</TracePulseProvider>
+```
+
+Then invoke `openCopilot(txnId)` or `toggleCopilot()` from your custom UI.
+
+---
+
+## License
+
+MIT © TracePulse Observability

package/dist/index.d.mts

@@ -0,0 +1,53 @@
+import React from 'react';
+
+interface ChatMessage {
+    id: string;
+    sender: "user" | "copilot";
+    text: string;
+    timestamp: string;
+    transactionId?: string;
+}
+interface TracePulseProviderProps {
+    apiKey: string;
+    projectId?: string;
+    endpoint?: string;
+    targetTransactionId?: string;
+    position?: "bottom-right" | "bottom-left";
+    theme?: "light" | "auto";
+    floatingButton?: boolean;
+    children?: React.ReactNode;
+}
+interface TracePulseContextValue {
+    isOpen: boolean;
+    openCopilot: (transactionId?: string) => void;
+    closeCopilot: () => void;
+    toggleCopilot: () => void;
+    activeTransactionId: string | null;
+    setActiveTransactionId: (id: string | null) => void;
+    sendMessage: (text: string, transactionId?: string) => Promise<string>;
+    messages: ChatMessage[];
+    isLoading: boolean;
+    endpoint: string;
+    apiKey: string;
+}
+
+declare function TracePulseProvider({ apiKey, projectId, endpoint, targetTransactionId, position, theme, floatingButton, children, }: TracePulseProviderProps): React.JSX.Element;
+
+declare const TracePulseContext: React.Context<TracePulseContextValue | null>;
+
+/**
+ * React hook to access TracePulse AI Copilot controls from any child component.
+ *
+ * Example:
+ * ```tsx
+ * import { useTracePulse } from "@tracepulse/connector-react";
+ *
+ * function OrderCard({ leadId }) {
+ *   const { openCopilot } = useTracePulse();
+ *   return <button onClick={() => openCopilot(leadId)}>Investigate with AI</button>;
+ * }
+ * ```
+ */
+declare function useTracePulse(): TracePulseContextValue;
+
+export { type ChatMessage, TracePulseContext, type TracePulseContextValue, TracePulseProvider, type TracePulseProviderProps, TracePulseProvider as default, useTracePulse };

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+import React from 'react';
+
+interface ChatMessage {
+    id: string;
+    sender: "user" | "copilot";
+    text: string;
+    timestamp: string;
+    transactionId?: string;
+}
+interface TracePulseProviderProps {
+    apiKey: string;
+    projectId?: string;
+    endpoint?: string;
+    targetTransactionId?: string;
+    position?: "bottom-right" | "bottom-left";
+    theme?: "light" | "auto";
+    floatingButton?: boolean;
+    children?: React.ReactNode;
+}
+interface TracePulseContextValue {
+    isOpen: boolean;
+    openCopilot: (transactionId?: string) => void;
+    closeCopilot: () => void;
+    toggleCopilot: () => void;
+    activeTransactionId: string | null;
+    setActiveTransactionId: (id: string | null) => void;
+    sendMessage: (text: string, transactionId?: string) => Promise<string>;
+    messages: ChatMessage[];
+    isLoading: boolean;
+    endpoint: string;
+    apiKey: string;
+}
+
+declare function TracePulseProvider({ apiKey, projectId, endpoint, targetTransactionId, position, theme, floatingButton, children, }: TracePulseProviderProps): React.JSX.Element;
+
+declare const TracePulseContext: React.Context<TracePulseContextValue | null>;
+
+/**
+ * React hook to access TracePulse AI Copilot controls from any child component.
+ *
+ * Example:
+ * ```tsx
+ * import { useTracePulse } from "@tracepulse/connector-react";
+ *
+ * function OrderCard({ leadId }) {
+ *   const { openCopilot } = useTracePulse();
+ *   return <button onClick={() => openCopilot(leadId)}>Investigate with AI</button>;
+ * }
+ * ```
+ */
+declare function useTracePulse(): TracePulseContextValue;
+
+export { type ChatMessage, TracePulseContext, type TracePulseContextValue, TracePulseProvider, type TracePulseProviderProps, TracePulseProvider as default, useTracePulse };