Tapra TypeScript SDK

Official TypeScript client for the Tapra API: Tunisian Arabic / French / English code-switching transcription, speech, translation, and Arabizi ↔ Arabic conversion. ESM, Node.js 22+ and modern browsers, no runtime dependencies.

import { TapraClient, Tapra } from '@tapra/sdk';

const client = new TapraClient(); // https://api.tapra.tn; apiKey defaults to TAPRA_API_KEY

const transcript = await client.transcriptions.create({ file: audioFile, timestamps: 'word' });
await client.script.convert({ text: '3lech 7abit l9anoun?', direction: 'ZI2AR' });

// Translations are currently offline (the endpoint returns an error until Tapra-Translate is back).
for await (const event of await client.translations.createStream({ input: 'عندي برشا خدمة', target: 'French' })) {
  process.stdout.write(event.delta ?? '');
}

Pass baseUrl to target another host, such as a local model host.

Errors are typed (Tapra.PaymentRequiredError for HTTP 402, …) and carry body.error.type. Pass { idempotencyKey } as request options to retry metered requests safely, and call .withRawResponse() to read x-tapra-cost-tnd.

Realtime transcription

import { connectRealtime } from '@tapra/sdk';

const session = await connectRealtime({ language: 'ar-AR' }); // wss://api.tapra.tn
session.on('partial', (event) => render(event.text));
session.sendAudio(pcmChunk); // mono pcm_s16le, 16 kHz
const final = await session.stop();

The key is sent as the tapra-auth.<key> WebSocket subprotocol, never in the URL. In a browser, pass a short-lived session token as apiKey, not a permanent key.

Prices

Tapra charges and invoices in TND only. The SDK does not hardcode any price: it reads the same live price list the website and the meter use.

import { fetchTapraPrices, estimateCostTnd } from '@tapra/sdk';

const prices = await fetchTapraPrices(); // GET https://www.tapra.tn/api/pricing, no key needed

estimateCostTnd(prices, 'tts', 1200); // 0.24 TND — 1,200 characters

estimateCostMicroTnd returns the exact integer amount the meter charges, including the per-request minimum for text products.

Development

src/ is generated by Fern from openapi/tapra-api.json; do not edit it by hand. lib/ (package entry, realtime helper, price list) is hand-written. Tests: sdks/tests/typescript.

Command line

The package ships a tapra command (npm install -g @tapra/sdk, or npx -p @tapra/sdk tapra ...). Same commands as the Python package's:

tapra auth login                               # checks the key, then saves it
tapra transcribe call.mp3                      # Derja + French + English, speakers labelled
tapra transcribe video.mp4 --format srt -o subs.srt   # any audio/video; long files are split (needs ffmpeg)
tapra stream --partials                        # live from the microphone (ffmpeg), Ctrl+C to stop
tapra speak "حبيت نتلقاو demain" --voice zeineb -o hello.wav
tapra flip "3lech 7abit l9anoun?"               # -> علاش حبيت القانون؟
tapra translate "chnowa el jaw?" --to French
tapra balance                                  # also: models, voices, pricing, languages, health

In a terminal, paid commands show the estimated cost and your balance and ask first (-y skips, --max-cost 0.5 sets a limit). They print the exact cost and balance on stderr when done; --json prints the full response and --dry-run shows the request without sending it. Exit codes: 0 ok, 1 error, 2 bad usage, 3 missing or invalid key, 4 balance too low. Full reference: https://www.tapra.tn/cli