Programmatic Usage

Use StringhiveClient when you need to call the Stringhive API from code. Same functionality as the CLI, but as a TypeScript/JavaScript API.

import { StringhiveClient } from 'stringhive'

const client = new StringhiveClient() // reads STRINGHIVE_TOKEN from env automatically

// or pass config directly
const client = new StringhiveClient({
  token: 'your-api-token',
  baseUrl: 'https://www.stringhive.com/api',
})

Set STRINGHIVE_DEBUG=1 in your environment to get full stack traces on errors.

locales()

All locales available on the platform:

const locales = await client.locales()
// [{ code: 'en', name: 'English' }, ...]

hives()

List all hives your token can see:

const hives = await client.hives()
// [{ slug: 'my-app', name: 'My App', locale: 'en' }, ...]

hive()

Stats for a single hive:

const hive = await client.hive('my-app')
// { slug: 'my-app', name: 'My App', locale: 'en', string_count: 1245, translation_count: 3683 }

strings()

Fetch source strings with pagination:

const page = await client.strings('my-app', 2)
// { data: [...], meta: { current_page: 2, last_page: 13, per_page: 100, total: 1245 } }

allStrings()

Convenience method that loops all pages and returns every string at once:

const all = await client.allStrings('my-app')

importStrings()

Push new or updated source strings. Keys not in the payload are left untouched.

await client.importStrings('my-app', {
  strings: [
    { key: 'auth.login', value: 'Login' },
    { key: 'auth.logout', value: 'Logout' },
  ],
})

syncStrings()

Like importStrings(), but also permanently removes strings absent from the payload. The payload represents the complete desired state.

await client.syncStrings('my-app', {
  strings: [...],
  conflict_strategy: 'keep', // or 'clear'
})

importTranslations()

Push translated strings for a specific locale:

await client.importTranslations('my-app', {
  locale: 'fr',
  strings: [{ key: 'auth.login', value: 'Connexion' }],
})

export()

Export translations for a hive. Returns a flat key-value object — does not write to disk.

// One locale
const fr = await client.export('my-app', 'fr', 'json')
// { 'auth.login': 'Connexion', 'auth.logout': 'Déconnexion', ... }

Error handling

Every error maps to a typed exception you can catch:

import {
  AuthenticationException, // 401 — bad or expired token
  ForbiddenException,      // 403 — no permission on this hive
  HiveNotFoundException,   // 404 — that slug doesn't exist
  StringLimitException,    // 422 — hit your plan's string quota
  ValidationException,     // 422 — bad payload
  NetworkException,        // fetch failed entirely
} from 'stringhive'

try {
  await client.importStrings('my-app', { strings })
} catch (err) {
  if (err instanceof StringLimitException) {
    // time to upgrade your plan
  } else if (err instanceof ValidationException) {
    console.error(err.errors) // { field: ['error message'] }
  } else if (err instanceof HiveNotFoundException) {
    // slug typo?
  }
}

The CLI maps these to human-readable messages automatically.