@nawalabs/sdk

Official TypeScript SDK for the NAWA API — Arabic-first AI comment classification.

Install

npm install @nawalabs/sdk

Quickstart

import Nawa from '@nawalabs/sdk';

const nawa = new Nawa({ apiKey: 'nawa_live_sk_xxx' });

const { data, error } = await nawa.classify({ text: "متى الجزء الثاني؟" });
console.log(data.dialect);    // "gulf"
console.log(data.sentiment);  // "neutral"
console.log(data.suggested_reply.text); // "قريب إن شاء الله! 🙏"

NAWA is the only API that detects Gulf, Egyptian, Levantine, and MSA Arabic dialects.

Configuration

const nawa = new Nawa({
  apiKey: 'nawa_live_sk_xxx',         // required
  baseUrl: 'https://api.trynawa.com', // default
  maxRetries: 2,                       // default
  timeout: 30000,                      // 30s default
  throwOnError: false,                 // default — use { data, error }
});

Methods

Classify

const { data, error } = await nawa.classify({
  text: "متى الجزء الثاني؟",
  context: { video_title: "Dubai Vlog" },
  provider: "claude", // optional: force provider
});

Translate

const { data, error } = await nawa.translate({
  text: 'Hello, how are you?',
  target: 'ar',
  dialect: 'gulf',
  tone: 'casual',
});
console.log(data.translated_text); // "هلا، كيف حالك؟"

Detect

const { data, error } = await nawa.detect({ text: 'وش رايكم بالمحتوى الجديد؟' });
console.log(data.language);  // "ar"
console.log(data.dialect);   // "gulf"
console.log(data.script);    // "arabic"

Moderate

const { data, error } = await nawa.moderate({
  text: 'هذا محتوى رائع جدا',
  strictness: 'medium',
});
console.log(data.is_safe);  // true
console.log(data.verdict);  // "safe"

Rubric Classify

const { data, error } = await nawa.rubric.classify({
  text: "أحتاج مساعدة في طلبي رقم ١٢٣٤",
  rubric: {
    categories: [
      { name: "support", description: "Customer support requests" },
      { name: "billing", description: "Billing questions" },
    ],
    multi_label: true,
    confidence_threshold: 0.6,
  },
});

Reply

const { data, error } = await nawa.comments.reply({
  text: "هذا المنتج سيء جداً ولا أنصح به",
  tone: "professional",
  max_length: 500,
});

Feedback (free)

const { data, error } = await nawa.feedback.create({
  classificationId: "cls_nw_a1b2c3d4e5f6",
  rating: "incorrect",
  correctedIntent: ["question"],
  correctedSentiment: "neutral",
  comment: "This was a question, not praise",
});

Webhooks

// Create
const { data, error } = await nawa.webhooks.create({
  url: "https://example.com/webhook",
  events: ["classification.completed", "credits.low"],
});

// List
const { data: list } = await nawa.webhooks.list();

// Delete
await nawa.webhooks.delete("webhook-uuid");

Error Handling

const { data, error } = await nawa.classify({ text: "test" });

if (error) {
  console.error(error.message);       // Human-readable error
  console.error(error.code);          // Machine-readable code
  console.error(error.status);        // HTTP status
  console.error(error.suggestedAction); // What to do next
  return;
}

// Use data safely
console.log(data.dialect);

Exception Mode

import Nawa, { NawaAuthError, NawaRateLimitError } from '@nawalabs/sdk';

const nawa = new Nawa({ apiKey: 'xxx', throwOnError: true });

try {
  const { data } = await nawa.classify({ text: "test" });
} catch (err) {
  if (err instanceof NawaRateLimitError) {
    console.log(`Retry after ${err.retryAfter}s`);
  } else if (err instanceof NawaAuthError) {
    console.log('Check your API key');
  }
}

Webhook Signature Verification

import Nawa from '@nawalabs/sdk';

const nawa = new Nawa({ apiKey: 'xxx' });

const isValid = await nawa.webhooks.verify(
  rawBody,
  {
    'webhook-id': req.headers['webhook-id'],
    'webhook-timestamp': req.headers['webhook-timestamp'],
    'webhook-signature': req.headers['webhook-signature'],
  },
  process.env.NAWA_WEBHOOK_SECRET!,
  { tolerance: 300 }, // 5 min (default)
);

Docs

Full API reference: developers.trynawa.com