![\"Tuteliq\"](\"./assets/logo.png\"){kind=logo}
\n\n \n
\n Official TypeScript/JavaScript SDK for the Tuteliq API
\n AI-powered child safety, fraud detection, and content moderation for modern applications\n
\n ![\"npm](\"https://img.shields.io/npm/v/@tuteliq/sdk.svg\")
\n ![\"npm](\"https://img.shields.io/npm/dm/@tuteliq/sdk.svg\")
\n ![\"license\"](\"https://img.shields.io/npm/l/@tuteliq/sdk.svg\")
\n ![\"build](\"https://img.shields.io/github/actions/workflow/status/Tuteliq/node/ci.yml\")
![\"bundle](\"https://img.shields.io/bundlephobia/minzip/@tuteliq/sdk\")
\n Documentation β’\n Dashboard β’\n Trust β’\n Discord β’\n Twitter\n
\n\n---\n\n## Overview\n\nTuteliq provides AI-powered content analysis to help protect children and vulnerable users in digital environments. This SDK makes it easy to integrate Tuteliq's capabilities into your Node.js, browser, or edge runtime applications.\n\n### Key Features\n\n- **Bullying Detection** β Identify verbal abuse, exclusion, and harassment patterns\n- **Grooming Risk Analysis** β Detect predatory behavior across conversation threads\n- **Unsafe Content Detection** β Flag self-harm, violence, hate speech, and age-inappropriate content\n- **Social Engineering Detection** β Detect pretexting, urgency fabrication, trust exploitation, and authority impersonation\n- **App Fraud Detection** β Identify fake investment platforms, phishing apps, subscription traps, and malicious links\n- **Romance Scam Detection** β Detect love-bombing, financial requests, and identity deception\n- **Mule Recruitment Detection** β Identify money mule recruitment and laundering facilitation\n- **Gambling Harm Detection** β Detect chasing losses, concealment behavior, and gambling-related distress\n- **Coercive Control Detection** β Identify isolation tactics, financial control, monitoring, and threats\n- **Vulnerability Exploitation Detection** β Detect targeting of the elderly, disabled, or emotionally vulnerable\n- **Radicalisation Detection** β Identify extremist rhetoric, us-vs-them framing, and ideological grooming\n- **Multi-Endpoint Analysis** β Run multiple detection types on a single piece of content in one call\n- **Voice Analysis** β Transcribe audio and run safety analysis on the transcript with timestamped segments\n- **Image Analysis** β Visual safety classification with OCR text extraction and text safety analysis\n- **Video Analysis** β Analyze video files for safety concerns via key frame extraction\n- **Document Analysis** β Upload PDFs for per-page multi-endpoint safety detection with chain-of-custody hashing\n- **Emotional State Analysis** β Understand emotional signals and concerning trends\n- **Action Guidance** β Generate age-appropriate response recommendations\n- **Incident Reports** β Create professional summaries for review\n- **Synthetic Content Detection** β Multi-signal forensic detection of AI-generated text, images, audio, and video\n- **Synthetic Image Forensics** β 6-signal pipeline: vision AI, EXIF metadata, pixel statistics, C2PA Content Credentials, watermark detection, perceptual hashing\n- **Synthetic Audio Forensics** β Transcript analysis + mel spectrogram vision + quantitative audio statistics\n- **Synthetic Video Forensics** β Temporal face consistency, lip-sync correlation, per-frame vision, spectral audio\n- **Synthetic Profiling** β Account-level 30-day rolling window with trend detection\n- **Age Verification** β Session-based age verification with document capture and liveness detection\n- **Identity Verification** β Session-based identity verification with face matching, document authentication, MRZ validation, barcode reading, and 45-country document number validation\n\n### Why Tuteliq?\n\n| Feature | Description |\n|---------|-------------|\n| **Privacy-First** | Stateless analysis, no mandatory data storage |\n| **Human-in-the-Loop** | Designed to assist, not replace, human judgment |\n| **Clear Rationale** | Every decision includes explainable reasoning |\n| **Safe Defaults** | Conservative escalation, no automated responses to children |\n\n---\n\n## Installation\n\n```bash\n# npm\nnpm install @tuteliq/sdk\n\n# yarn\nyarn add @tuteliq/sdk\n\n# pnpm\npnpm add @tuteliq/sdk\n\n# bun\nbun add @tuteliq/sdk\n```\n\n### Requirements\n\n- Node.js 18+ (or any runtime with `fetch` support)\n- TypeScript 4.7+ (optional, for type definitions)\n\n---\n\n## Quick Start\n\n```typescript\nimport { Tuteliq } from '@tuteliq/sdk'\n\nconst tuteliq = new Tuteliq(process.env.TUTELIQ_API_KEY)\n\n// Quick safety analysis\nconst result = await tuteliq.analyze(\"User message to analyze\")\n\nif (result.risk_level !== 'safe') {\n console.log('Risk detected:', result.risk_level)\n console.log('Summary:', result.summary)\n console.log('Action:', result.recommended_action)\n}\n```\n\n---\n\n## API Reference\n\n### Initialization\n\n```typescript\nimport { Tuteliq } from '@tuteliq/sdk'\n\n// Simple\nconst tuteliq = new Tuteliq('your-api-key')\n\n// With options\nconst tuteliq = new Tuteliq('your-api-key', {\n timeout: 30000, // Request timeout in ms (default: 30 seconds)\n retries: 3, // Retry attempts for transient failures (default: 3)\n retryDelay: 1000, // Initial retry delay in ms (default: 1000)\n})\n```\n\n---\n\n### Common Parameters\n\n#### Tracking Fields\n\nAll detection methods accept optional tracking fields for correlation, multi-tenant routing, and custom metadata:\n\n```typescript\nconst result = await tuteliq.detectBullying({\n content: \"Nobody likes you, just leave\",\n context: 'chat',\n\n // Optional tracking fields β echoed back in the response and included in webhooks\n external_id: 'msg_abc123', // Your unique identifier for correlation\n customer_id: 'cust_xyz789', // Your end-customer ID (B2B2C / multi-tenant)\n metadata: { channel: 'discord' } // Arbitrary key-value pairs\n})\n\n// Echoed back in response\nconsole.log(result.external_id) // 'msg_abc123'\nconsole.log(result.customer_id) // 'cust_xyz789'\nconsole.log(result.metadata) // { channel: 'discord' }\n```\n\n| Field | Type | Max Length | Description |\n|-------|------|-----------|-------------|\n| `external_id` | `string?` | 255 | Your internal identifier (message ID, content ID, etc.) |\n| `customer_id` | `string?` | 255 | Your end-customer identifier for multi-tenant / B2B2C scenarios |\n| `metadata` | `object?` | β | Custom key-value pairs stored with the detection result |\n\nThese fields are:\n- **Echoed** in the API response for easy matching\n- **Included** in webhook payloads, enabling you to route alerts to the correct customer from a single webhook endpoint\n- **Stored** with the incident in Firestore for audit trail\n\n#### Support Threshold\n\nAll detection methods accept an optional `supportThreshold` parameter that controls when crisis support resources are included in the response:\n\n```typescript\nconst result = await tuteliq.detectUnsafe({\n content: \"I don't want to be here anymore\",\n supportThreshold: 'medium' // 'low' | 'medium' | 'high' (default) | 'critical'\n})\n\n// When severity meets or exceeds the threshold, result.support will contain:\n// - helpline phone numbers (region-aware)\n// - crisis text lines\n// - relevant web resources\n```\n\n> **Note:** `critical` severity always includes support resources regardless of the threshold setting.\n\n---\n\n### Safety Detection\n\n#### `detectBullying(input)`\n\nDetects bullying and harassment in text content.\n\n```typescript\nconst result = await tuteliq.detectBullying({\n content: \"Nobody likes you, just leave\",\n context: 'chat' // or { ageGroup: '11-13', relationship: 'classmates' }\n})\n\nconsole.log(result.is_bullying) // true\nconsole.log(result.severity) // 'medium' | 'high' | 'critical'\nconsole.log(result.bullying_type) // ['exclusion', 'verbal_abuse']\nconsole.log(result.confidence) // 0.92\nconsole.log(result.risk_score) // 0.75\nconsole.log(result.rationale) // \"Direct exclusion language...\"\nconsole.log(result.recommended_action) // 'flag_for_review'\nconsole.log(result.action_detail) // \"Route to a moderator within the hour.\"\n```\n\n`recommended_action` is the field to branch on. It is one of `none`, `monitor`,\n`flag_for_review`, `block` or `immediate_intervention`, ordered weakest to\nstrongest, and is stable across releases. Prefer it over `is_bullying`, which\nfires on monitor-only cases too:\n\n```typescript\nimport { isActionable } from '@tuteliq/sdk'\n\nif (isActionable(result.recommended_action)) {\n // flag_for_review or stronger β a human should see this\n}\n```\n\n#### `detectGrooming(input)`\n\nAnalyzes conversation threads for grooming patterns.\n\n```typescript\nconst result = await tuteliq.detectGrooming({\n messages: [\n { role: 'adult', content: \"This is our special secret\" },\n { role: 'child', content: \"Ok I won't tell anyone\" }\n ],\n childAge: 12\n})\n\nconsole.log(result.grooming_risk) // 'none' | 'low' | 'medium' | 'high' | 'critical'\nconsole.log(result.flags) // ['secrecy', 'isolation', 'trust_building']\nconsole.log(result.confidence) // 0.89\nconsole.log(result.risk_score) // 0.85\nconsole.log(result.rationale) // \"Multiple grooming indicators...\"\nconsole.log(result.recommended_action) // 'immediate_intervention'\n\n// Per-message breakdown (optional, returned on conversation-aware endpoints)\nif (result.message_analysis) {\n for (const m of result.message_analysis) {\n console.log(`Message ${m.message_index}: risk=${m.risk_score}, flags=${m.flags}, summary=${m.summary}`)\n }\n}\n```\n\n#### `detectUnsafe(input)`\n\nIdentifies potentially dangerous or harmful content.\n\n```typescript\nconst result = await tuteliq.detectUnsafe({\n content: \"I don't want to be here anymore\"\n})\n\nconsole.log(result.unsafe) // true\nconsole.log(result.categories) // ['self_harm', 'crisis']\nconsole.log(result.severity) // 'critical'\nconsole.log(result.risk_score) // 0.9\nconsole.log(result.rationale) // \"Expression of suicidal ideation...\"\nconsole.log(result.recommended_action) // 'immediate_intervention'\n```\n\n#### `analyze(content)`\n\nQuick combined analysis β runs bullying and unsafe detection in parallel.\n\n> **Note**: This method fires one API call per detection type included (default: 2 calls for bullying + unsafe). Each call counts against your monthly quota. Use `include` to run only the checks you need.\n\n```typescript\n// Simple string input (costs 2 API calls: bullying + unsafe)\nconst result = await tuteliq.analyze(\"Message to check\")\n\n// With options β run only bullying (costs 1 API call)\nconst result = await tuteliq.analyze({\n content: \"Message to check\",\n context: 'social_media',\n include: ['bullying', 'unsafe'] // Select which checks to run\n})\n\nconsole.log(result.risk_level) // 'safe' | 'low' | 'medium' | 'high' | 'critical'\nconsole.log(result.risk_score) // 0.0 - 1.0\nconsole.log(result.summary) // \"Bullying detected (medium). Unsafe content: self_harm\"\nconsole.log(result.bullying) // Full bullying result (if included)\nconsole.log(result.unsafe) // Full unsafe result (if included)\nconsole.log(result.recommended_action) // Combined recommendation\n```\n\n---\n\n### Fraud & Harm Detection\n\nAll fraud and harm detection methods share the same `DetectionInput` and return a unified `DetectionResult`:\n\n```typescript\nimport type { DetectionInput, DetectionResult } from '@tuteliq/sdk'\n```\n\n**Input:**\n\n```typescript\n{\n content: string, // Text content to analyze\n context?: ContextInput, // Optional analysis context\n includeEvidence?: boolean, // Include evidence excerpts\n supportThreshold?: 'low' | 'medium' | 'high' | 'critical', // Crisis support threshold\n external_id?: string, // Tracking ID\n customer_id?: string, // Customer ID\n metadata?: Record{warning}
}\n \n