Sentor JS/TS SDK

Official JavaScript/TypeScript SDK for the Sentor API — entity-based sentiment analysis, document clustering, and topic naming.

Stop guessing why ratings drop. Sentor pinpoints exactly how customers feel about specific entities — brands, products, features, competitors — using fine-tuned BERT models trained for aspect-based sentiment analysis.

Table of Contents

• Installation
• Quick Start
• API Reference
  • predict()
  • cluster()
  • generateTopicName()
  • checkHealth()
• Error Handling
• Rate Limits

📦 Installation

npm install sentor-sdk
# or
yarn add sentor-sdk

Get a free API key at dashboard.sentor.app.

🚀 Quick Start

import { SentorClient } from 'sentor-sdk';

const client = new SentorClient('your_api_key');

const results = await client.predict({
    docs: [
        {
            doc_id: 'review-1',
            doc: "Apple's new iPhone is amazing but the price is ridiculous.",
            entities: ['Apple', 'iPhone', 'price'],
        },
    ],
});

for (const item of results.results) {
    console.log(item.doc_id, item.predicted_label);
    for (const es of item.entity_sentiments ?? []) {
        console.log(`  ${es.entity}: ${es.sentiment} (${es.score.toFixed(2)})`);
    }
}

📖 API Reference

predict(input)

Score sentiment toward named entities in one or more documents.

const results = await client.predict({
    docs: [
        {
            doc_id: 'r1',
            doc: "Samsung's camera is great but battery life is poor.",
            entities: ['Samsung', 'camera', 'battery life'],
        },
    ],
    language: 'en', // "en" | "nl", default "en"
});

Response shape:

{
    results: [
        {
            doc_id: 'r1',
            predicted_class: 0,         // 0=negative, 1=neutral, 2=positive
            predicted_label: 'negative',
            probabilities: { negative: 0.72, neutral: 0.18, positive: 0.10 },
            details: [...],             // per-sentence breakdown
            entity_sentiments: [
                { entity: 'Samsung', sentiment: 'neutral', score: 0.61 },
                { entity: 'camera', sentiment: 'positive', score: 0.88 },
                { entity: 'battery life', sentiment: 'negative', score: 0.91 },
            ],
        },
    ],
}

Supported languages: en (English), nl (Dutch)

cluster(input, language?)

Group 5+ documents into thematic clusters using BERTopic + HDBSCAN.

const results = await client.cluster(
    {
        documents: [
            { doc_id: 'r1', text: 'Shipping was incredibly fast.', entities: ['shipping'] },
            // ... at least 5 documents
        ],
    },
    'en'
);

for (const cluster of results.clusters) {
    console.log(cluster.cluster_id, cluster.document_count, cluster.top_words);
}
// cluster_id -1 = outliers that did not fit any topic

generateTopicName(input, language?)

Generate a 3–5 word label for a cluster using an LLM.

const result = await client.generateTopicName(
    {
        cluster_id: 0,
        documents: cluster.documents,
        top_words: cluster.top_words,
        entities: ['BrandName'],
    },
    'en'
);
console.log(result.topic_name); // e.g. "Shipping Delay Complaints"

checkHealth()

const health = await client.checkHealth();
// { status: 'healthy', version: '...', llm_status: 'available' }

⚠️ Error Handling

import { SentorClient, SentorAPIError, RateLimitError, AuthenticationError } from 'sentor-sdk';

const client = new SentorClient('your_api_key');

try {
    const results = await client.predict({ docs: [...] });
} catch (error) {
    if (error instanceof AuthenticationError) {
        console.error('Invalid API key');
    } else if (error instanceof RateLimitError) {
        console.error(`Rate limit hit. Retry after ${error.retryAfter}s`);
    } else if (error instanceof SentorAPIError) {
        console.error(`API error: ${error.message} (${error.code})`);
    }
}

📊 Rate Limits

| Plan | Per Minute | Per Day | Per Month | |------|-----------|---------|-----------| | Free | 5 | 100 | 1,000 | | Starter | 20 | 600 | 5,000 | | Growth | 60 | 3,000 | 25,000 | | Business | 200 | 10,000 | 100,000 | | Enterprise | 500 | 30,000 | 500,000 |

View full pricing →

🔗 Links

• Sentor Dashboard — manage API keys and usage
• API Documentation
• npm Package
• Support