satyamark-react 0.0.12 → 0.0.14

package/README.md

@@ -2,53 +2,33 @@
 
 > Real-time content verification library for React applications
 
-SatyaMark is a React library that provides real-time verification for text and image content through AI-powered fact-checking and deepfake detection. Display transparent trust signals directly in your UI to help users distinguish between reliable and unreliable information.
-
-![npm downloads](https://img.shields.io/npm/dt/satyamark-react)
-[![npm version](https://badge.fury.io/js/satyamark-react.svg)](https://www.npmjs.com/package/satyamark-react)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-
-## Features
-
-- ✅ **Real-time verification** of text content through fact-checking APIs
-- 🤖 **AI-generated media detection** for images
-- 🔄 **Live status updates** via WebSocket connection
-- 🎨 **Automatic UI injection** with verification marks
-- ⚡ **Lightweight integration** - minimal code required
-- 🔗 **Interactive results** - click through to detailed evidence
-- 📱 **Framework agnostic** - works with any React setup
-
-## Table of Contents
-
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Core Concepts](#core-concepts)
-- [API Reference](#api-reference)
-- [Usage Examples](#usage-examples)
-- [Best Practices](#best-practices)
-- [Verification Marks](#verification-marks)
-- [Troubleshooting](#troubleshooting)
-- [Limitations](#limitations)
-- [Contributing](#contributing)
+SatyaMark is a React library that provides real-time verification for
+text and image content through AI-powered fact-checking and deepfake
+detection. It injects transparent trust signals directly into your UI so
+users can distinguish between reliable and unreliable information.
 
-## Installation
+![npm downloads](https://img.shields.io/npm/dt/satyamark-react) [![npm
+version](https://badge.fury.io/js/satyamark-react.svg)](https://www.npmjs.com/package/satyamark-react)
+[![License:
+MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+------------------------------------------------------------------------
 
-Install via npm:
+## Installation
 
-```bash
+``` bash
 npm install satyamark-react
 ```
 
-**Peer Dependencies:**
-- React 18+ (compatible with React 19)
+**Peer Dependency:** React 18+
+
+------------------------------------------------------------------------
 
 ## Quick Start
 
 ### 1. Initialize Connection
 
-Call `init()` once when your app loads to establish the WebSocket connection:
-
-```tsx
+``` tsx
 import { useEffect } from "react";
 import { init } from "satyamark-react";
 
@@ -56,7 +36,7 @@ function App() {
   useEffect(() => {
     init({
       app_id: "your-app-id",
-      user_id: "unique-user-id",
+      user_id: "unique-user-id", // Use stable unique user id
     });
   }, []);
 
@@ -64,323 +44,148 @@ function App() {
 }
 ```
 
-### 2. Create a Verified Component
+### Optional: onConnected
 
-```tsx
-import { useRef, useEffect, useState } from "react";
-import { process, registerStatus } from "satyamark-react";
+`onConnected` notifies when the connection state changes.
 
-function PostCard({ post }) {
-  const contentRef = useRef(null);
-  const [jobId, setJobId] = useState(null);
+Callback receives:
+
+    {
+      app_id: string;
+      user_id: string;
+    }
+
+If disconnected or closed, it receives `null`.
 
-  // Process content after render
+``` tsx
+import { useEffect } from "react";
+import { init, onConnected } from "satyamark-react";
+
+function App() {
   useEffect(() => {
-    if (!contentRef.current) return;
+    init({
+      app_id: "my-app",
+      user_id: "user_123",
+    });
 
-    process(contentRef.current, post.id)
-      .then(setJobId)
-      .catch(console.error);
-  }, [post.id]);
+    const unsubscribe = onConnected((connection) => {
+      if (connection) {
+        console.log("Connected:", connection.app_id, connection.user_id);
+      } else {
+        console.log("Disconnected");
+      }
+    });
+
+    return unsubscribe;
+  }, []);
+
+  return <YourApp />;
+}
+```
+
+### 2. Process a Content Element
+
+``` tsx
+import { useRef, useEffect } from "react";
+import { process } from "satyamark-react";
+
+function PostCard({ post }) {
+  const ref = useRef(null);
 
-  // Register status display
   useEffect(() => {
-    if (!jobId || !contentRef.current) return;
-    registerStatus(jobId, contentRef.current);
-  }, [jobId]);
+    if (!ref.current) return;
+    process(ref.current, post.id);
+  }, [post.id]);
 
   return (
-    <div ref={contentRef}>
+    <div ref={ref}>
       <p>{post.text}</p>
-      {post.image && <img src={post.image} alt="Post" />}
-      
-      {/* Verification mark appears here */}
+      {post.image && <img src={post.image} alt="" />}
+
       <div data-satyamark-status-container />
     </div>
   );
 }
 ```
 
-That's it! The verification mark will automatically appear and update.
+You can style the `data-satyamark-status-container` element according to
+your UI requirements.
+
+------------------------------------------------------------------------
 
 ## Core Concepts
 
 SatyaMark consists of three core modules that work together:
 
-### 1. Connection Layer (`satyamark_connect`)
-
-Manages the WebSocket connection to the verification server.
+### 1. Connection Layer
 
-- Authenticates with your `app_id` and `user_id`
-- Maintains persistent connection
-- Handles incoming verification results
-- Supports connection callbacks
+-   Authenticates with your `app_id` and `user_id`
+-   Maintains persistent WebSocket connection
+-   Handles incoming verification results
 
-### 2. Processing Layer (`satyamark_process`)
+### 2. Processing Layer
 
-Extracts content from rendered DOM elements for verification.
+-   Walks the DOM tree to extract visible text
+-   Finds and validates images
+-   Sends content to verification service
+-   Internally tracks verification jobs
 
-- Walks the DOM tree to extract all visible text
-- Finds and validates images
-- Sends content to verification service
-- Returns a unique `jobId` for tracking
+### 3. Status Layer
 
-### 3. Status Layer (`satyamark_status_controller`)
-
-Manages visual display of verification status.
-
-- Injects verification icons into your UI
-- Updates status in real-time
-- Provides tooltips on hover
-- Makes icons clickable for detailed results
+-   Automatically injects verification icons into your UI
+-   Updates status in real-time
+-   Provides tooltips on hover
+-   Makes icons clickable for detailed results
 
 ### Lifecycle Flow
 
-```
-1. init()          → Establish connection
-2. render          → Display content normally
-3. process()       → Extract and send for verification
-4. registerStatus() → Attach status display
-5. Auto-update     → Marks appear and update automatically
-```
+    1. init()      → Establish connection
+    2. render      → Display content normally
+    3. process()   → Extract content & auto-inject verification status
+
+All retries, result handling, and UI updates are managed internally.
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/DhirajKarangale/SatyaMark/main/Assets/NpmCover/NpmCover_1.png" alt="SatyaMark Architecture" width="100%" />
 </p>
 
-## API Reference
-
-### Connection API
-
-#### `init(connectionData, options?)`
-
-Establishes WebSocket connection to the SatyaMark server.
-
-**Parameters:**
-- `connectionData` (SatyaMarkConnectionData) - **Required**
-  - `app_id` (string): Your application's unique identifier
-  - `user_id` (string): Current user's unique identifier
-- `options` (object) - Optional
-  - `onConnected` (function): Callback when connection succeeds
-
-**Returns:** `void`
-
-**Example:**
-```tsx
-init({
-  app_id: "my-social-app",
-  user_id: "user_12345",
-});
-```
-
-#### `onConnected(callback)`
-
-Register a callback for when the connection is established.
-
-**Parameters:**
-- `callback` (ConnectedCallback): Function receiving connection data
-
-**Returns:** `void`
-
-**Example:**
-```tsx
-onConnected((data) => {
-  console.log("Connected:", data);
-});
-```
-
-#### `onReceive(callback)`
-
-Subscribe to incoming verification updates. Used internally by status controller.
-
-**Parameters:**
-- `callback` (ReceiveCallback): Function receiving verification data
-
-**Returns:** Unsubscribe function
-
----
-
-### Processing API
-
-#### `process(divRef, dataId)`
-
-Extracts content from a DOM element and submits for verification.
-
-**Parameters:**
-- `divRef` (HTMLDivElement): The DOM element containing content
-- `dataId` (string): Unique identifier for this content (e.g., post ID)
-
-**Returns:** `Promise<string>` - Resolves with `jobId` for tracking
-
-**Throws:**
-- `"Invalid root element"` - if divRef is null/undefined
-- `"dataId is required"` - if dataId is empty
-- `"No valid text or image found"` - if element has no content
-- `"Extracted text is too short"` - if text is less than 3 characters
+------------------------------------------------------------------------
 
-**Example:**
-```tsx
-process(ref.current, "post_123")
-  .then((jobId) => registerStatus(jobId, ref.current))
-  .catch((error) => console.error(error.message));
-```
-
----
-
-### Status API
-
-#### `registerStatus(jobId, rootElement, options?)`
-
-Registers a DOM element to display verification status.
-
-**Parameters:**
-- `jobId` (string): Job ID returned from `process()`
-- `rootElement` (HTMLElement): Element containing status container
-- `options` (StatusOptions) - Optional
-  - `iconSize` (number): Icon size in pixels (default: 20)
-
-**Returns:** `void`
-
-**Requirements:**
-- Root element must contain a child with `data-satyamark-status-container` attribute
-
-**Example:**
-```tsx
-registerStatus(jobId, contentRef.current, {
-  iconSize: 24,
-});
-```
-
-**HTML Structure:**
-```tsx
-<div ref={contentRef}>
-  {/* Your content */}
-  <div data-satyamark-status-container />
-</div>
-```
-
-## Usage Examples
-
-### Basic Setup
-
-```tsx
-import { useEffect } from "react";
-import { init, onConnected } from "satyamark-react";
-
-function App() {
-  useEffect(() => {
-    init({
-      app_id: "my-app",
-      user_id: getCurrentUserId(),
-    });
-
-    onConnected((data) => {
-      console.log("SatyaMark connected:", data);
-    });
-  }, []);
-
-  return <div>{/* Your app */}</div>;
-}
-```
-
-### Complete Component with Error Handling
+## API Reference
 
-```tsx
-import { useRef, useEffect, useState } from "react";
-import { process, registerStatus } from "satyamark-react";
+### 1. init(connectionData)
 
-function VerifiedPost({ post }) {
-  const contentRef = useRef(null);
-  const [status, setStatus] = useState("idle");
-  const [error, setError] = useState("");
+  Establishes WebSocket connection.
 
-  useEffect(() => {
-    if (!contentRef.current) return;
-
-    setStatus("processing");
-
-    process(contentRef.current, post.id)
-      .then((jobId) => {
-        setStatus("success");
-        registerStatus(jobId, contentRef.current);
-      })
-      .catch((err) => {
-        setStatus("error");
-        setError(err.message);
-      });
-  }, [post.id]);
+  **Parameters**
 
-  return (
-    <div ref={contentRef} className="post-card">
-      <div className="content">
-        <p>{post.text}</p>
-        {post.image && <img src={post.image} alt="" />}
-      </div>
-
-      {status === "success" && (
-        <div data-satyamark-status-container />
-      )}
-
-      {status === "error" && (
-        <div className="error-badge">{error}</div>
-      )}
-    </div>
-  );
-}
-```
-
-### List of Posts
-
-```tsx
-function PostFeed({ posts }) {
-  return (
-    <div className="feed">
-      {posts.map((post) => (
-        <VerifiedPost key={post.id} post={post} />
-      ))}
-    </div>
-  );
-}
-```
+  -   `app_id: string` — Unique identifier for your application
+  -   `user_id: string` — Unique identifier for the current user
 
-### Custom Icon Size
+### 2. onConnected(callback)
 
-```tsx
-useEffect(() => {
-  if (!jobId || !ref.current) return;
+  Listens for connection state changes.
 
-  registerStatus(jobId, ref.current, {
-    iconSize: 32, // Larger icon
-  });
-}, [jobId]);
-```
+  Callback receives:
 
-## Best Practices
+      {
+        app_id: string;
+        user_id: string;
+      }
 
-### ✅ Do
+  Returns `null` if disconnected.
 
-- **Initialize once** at app startup in your root component
-- **Use unique dataIds** for each piece of content (post ID, comment ID, etc.)
-- **Process after render** - ensure content exists in DOM before calling `process()`
-- **Handle errors gracefully** - short or empty content will throw errors
-- **Use refs correctly** - pass actual DOM elements, not null
-- **Test with real content** - minimum 3 characters or valid image required
+### 3. process(rootElement, dataId)
 
-### ❌ Don't
+  Extracts text and images from a DOM element and submits them for
+  verification.
 
-- **Don't call init() multiple times** - creates duplicate connections
-- **Don't process before render** - ref.current will be null
-- **Don't reuse dataIds** - each content piece needs unique identifier
-- **Don't forget status container** - `data-satyamark-status-container` is required
-- **Don't manually update icons** - library handles it automatically
-- **Don't process empty content** - ensure content exists first
+  **Parameters**
 
-### ⚡ Performance Tips
+  -   `rootElement: HTMLElement` — DOM element containing the content
+  -   `dataId: string` — Unique identifier for this specific content item
 
-- **Debounce rapid updates** - don't re-process on every keystroke
-- **Process only visible content** - use Intersection Observer for long lists
-- **Cache jobIds** - avoid re-processing identical content
-- **Lazy load verification** - process when content enters viewport
+------------------------------------------------------------------------
 
 ## Verification Marks
 
@@ -400,71 +205,79 @@ SatyaMark displays different marks based on verification results:
 
 **Interactive:** After verification completes, clicking the mark opens a detailed results page with sources and evidence.
 
-## Troubleshooting
+------------------------------------------------------------------------
 
-### "Invalid root element"
+## Best Practices
 
-**Cause:** Calling `process()` with null/undefined ref.
+### Do
 
-**Solution:** Check ref exists before processing:
-```tsx
-if (!contentRef.current) return;
-process(contentRef.current, post.id);
-```
+-   Initialize `init()` once in your root App component
+-   Use a unique and stable `user_id` when calling `init()`
+-   Use a stable and unique `dataId` for each content item (database IDs recommended)
+-   Call `process()` only after the element is mounted
+-   Include `data-satyamark-status-container` where you want status displayed
+-   Style the `data-satyamark-status-container` element as per your UI requirements
+-   Optionally use `onConnected()` if your UI depends on connection readiness
+-   Let SatyaMark manage verification lifecycle and retries internally
 
-### "No valid text or image found"
+### Don't
 
-**Cause:** Element contains no extractable content or all images fail to load.
+-   Don't call `init()` multiple times or in multiple components
+-   Don't use random or changing `user_id` values for the same user session
+-   Don't use random or changing `dataId` values for the same content
+-   Don't manually retry `process()` in loops
+-   Don't call `process()` before the element exists in the DOM
 
-**Solution:** Ensure content has visible text (3+ chars) or valid image URLs.
+### Performance Tips
 
-### Status icon not appearing
+-   **Debounce Input Changes** - Avoid re-processing content on every keystroke
+-   **Process Visible Content Only** - Use Intersection Observer for large feeds
+-   **Prevent Re-Render Loops** - Ensure process() isn’t triggered repeatedly by state updates
+-   **Use Stable Content Identifiers** - Prevent duplicate or unnecessary verification calls
 
-**Cause:** Missing `data-satyamark-status-container` or `registerStatus()` not called.
+------------------------------------------------------------------------
 
-**Solution:** Add status container and call `registerStatus()` with correct jobId:
-```tsx
-<div data-satyamark-status-container />
-// ...
-registerStatus(jobId, contentRef.current);
-```
+## Troubleshooting
 
-### Connection fails or times out
+### 1. Invalid root element
 
-**Cause:** Network issues, invalid credentials, or server unavailable.
+  **Cause:** Calling `process()` with null/undefined ref.
 
-**Solution:** Check console for WebSocket errors. Verify `app_id` and `user_id` are correct.
+  **Solution:** Check ref exists before processing:
+  ```tsx
+  if (!contentRef.current) return;
+  process(contentRef.current, post.id);
+  ```
 
-### Multiple verification requests
+### 2. No valid text or image found
 
-**Cause:** useEffect dependency array causing re-renders.
+  **Cause:** Element contains no extractable content or all images fail to load.
 
-**Solution:** Use stable identifiers in dependency array:
-```tsx
-useEffect(() => {
-  // Process logic
-}, [post.id]); // Stable dependency
-```
+  **Solution:** Ensure content has visible text (3+ chars) or valid image URLs.
 
-### Verification stuck on "Pending"
+### 3. Status icon not appearing
 
-**Cause:** Server processing or jobId mismatch.
+  **Cause:** Missing `data-satyamark-status-container` or `process()` not executed.
 
-**Solution:** Verification can take 5-30 seconds. Ensure jobId is correctly passed to `registerStatus()`.
+  **Solution:** Ensure:
 
-## Limitations
+    - `init()` was called
+    - `process()` ran after the element mounted
+    - `data-satyamark-status-container` exists inside the processed element
 
-SatyaMark is actively developed. Current limitations:
+### 4. Connection fails or times out
 
-- **Minimum content:** Text must be at least 3 characters
-- **Single image:** Only first valid image is processed per element
-- **No offline support:** Requires active WebSocket connection
-- **No local caching:** Content sent to server every time (caching planned)
-- **Single connection:** Multiple tabs share connection state
-- **Limited retry logic:** Manual refresh required if connection drops
-- **No client rate limiting:** Apps should implement own throttling
+  **Cause:** Network issues, invalid credentials, or server unavailable.
 
-These are being addressed in future releases. Check the [GitHub repository](https://github.com/DhirajKarangale/SatyaMark) for updates.
+  **Solution:** Check console for WebSocket errors. Verify `app_id` and `user_id` are correct.
+
+### 5. Verification stuck on "Pending"
+
+  **Cause:** Server processing delay.
+
+  **Solution:** Verification can take a few seconds to a few minutes depending on content complexity and system load.
+
+------------------------------------------------------------------------
 
 ## Contributing
 
@@ -486,10 +299,8 @@ SatyaMark is fully open-source and welcomes contributions!
 
 All contributions are reviewed for alignment with SatyaMark's principles: transparency, evidence-based verification, and accessibility.
 
-## License
-
-MIT © SatyaMark Contributors
+------------------------------------------------------------------------
 
----
+## License
 
-**Need help?** Open an issue on [GitHub](https://github.com/DhirajKarangale/SatyaMark) or check the [live demo](https://satyamark.vercel.app) for examples.
+MIT © SatyaMark Contributors

package/dist/index.d.ts

@@ -1,22 +1,15 @@
-type SatyaMarkConnectionData = {
+type ConnectionContext$1 = {
     app_id: string;
     user_id: string;
 };
-type ConnectedCallback = (data: SatyaMarkConnectionData) => void;
-type ReceiveCallback = (data: any) => void;
-declare function onReceive(cb: ReceiveCallback): () => void;
-declare function onConnected(cb: ConnectedCallback): void;
-declare function init(connectionData: SatyaMarkConnectionData, options?: {
-    onConnected?: ConnectedCallback;
-}): Promise<void>;
-declare function sendData(text: string, image_url: string, dataId: string): string | undefined;
-declare function receiveData(data: any): void;
+declare function init(newContext: ConnectionContext$1): Promise<void>;
 
-declare function process(divRef: HTMLDivElement, dataId: string): Promise<string | undefined>;
-
-type StatusOptions = {
-    iconSize?: number;
+type ConnectionContext = {
+    app_id: string;
+    user_id: string;
 };
-declare function registerStatus(jobId: string, rootElement: HTMLElement, options?: StatusOptions): void;
+declare function onConnected(cb: (context: ConnectionContext | null) => void): () => void;
+
+declare function process(containerRef: HTMLDivElement, dataId: string): void;
 
-export { SatyaMarkConnectionData, init, onConnected, onReceive, process, receiveData, registerStatus, sendData };
+export { init, onConnected, process };