@verbadev/js 0.1.0

package/README.md

@@ -0,0 +1,265 @@
+# @verbadev/js
+
+Official JavaScript SDK for [Verba](https://verba.dev) - Translation Management System.
+
+## Installation
+
+```bash
+npm install @verbadev/js
+```
+
+## Quick Start
+
+```typescript
+import { Verba } from '@verbadev/js'
+
+const verba = new Verba({
+  projectId: 'your-project-id',
+  publicKey: 'pk_your-public-key',
+})
+
+// Get a translation
+const text = verba.t('welcome.message')
+```
+
+## Configuration
+
+```typescript
+const verba = new Verba({
+  projectId: string,   // Required - Your project ID from the dashboard
+  publicKey: string,   // Required - Your public key (safe for client-side)
+  locale?: string,     // Optional - defaults to auto-detection from browser
+  baseUrl?: string,    // Optional - API base URL (default: 'https://verba.dev')
+})
+```
+
+## Locale Auto-Detection
+
+By default, the SDK automatically detects the user's locale from the browser (`navigator.language`) and matches it against your project's available locales.
+
+```typescript
+// Auto-detect (default behavior)
+const verba = new Verba({ projectId, publicKey })
+
+// Explicit auto-detect
+const verba = new Verba({ projectId, publicKey, locale: 'auto' })
+
+// Override with specific locale
+const verba = new Verba({ projectId, publicKey, locale: 'es' })
+```
+
+**Matching logic:**
+1. Exact match (e.g., `en-US` → `en-US`)
+2. Base language match (e.g., `en-US` → `en`)
+3. Falls back to project's default locale if no match
+
+## API Reference
+
+### `verba.t(key, defaultValue?, params?)`
+
+Get a translation for the current locale with optional interpolation.
+
+```typescript
+// Basic usage
+verba.t('welcome.message')
+
+// With default value (auto-creates missing keys)
+verba.t('greeting', 'Hello!')
+
+// With interpolation params
+verba.t('greeting', { name: 'Łukasz' })
+// 'Hello, {name}!' → 'Hello, Łukasz!'
+
+// With both default value and params
+verba.t('greeting', 'Hello, {name}!', { name: 'Łukasz' })
+```
+
+**Flexible signature:**
+- `t(key)` - just the key
+- `t(key, defaultValue)` - with fallback string
+- `t(key, params)` - with interpolation params (object)
+- `t(key, defaultValue, params)` - with both
+
+**Parameters:**
+- `key` (string) - The translation key
+- `defaultValue` (string, optional) - Fallback value if key doesn't exist
+- `params` (object, optional) - Values to interpolate into `{placeholder}` tokens
+
+**Returns:** The translated string with interpolation applied.
+
+**Auto-creation:** When you call `t()` with a `defaultValue` and the key doesn't exist, the SDK automatically:
+1. Returns the `defaultValue` immediately
+2. Creates the key in Verba in the background
+3. Triggers AI translation to all your project's locales
+
+This enables a powerful workflow where you can write code first and translations are created on-the-fly.
+
+### `verba.setLocale(locale)`
+
+Change the active locale.
+
+```typescript
+verba.setLocale('es')
+const text = verba.t('welcome.message') // Returns Spanish translation
+```
+
+### `verba.getLocale()`
+
+Get the current locale.
+
+```typescript
+const locale = verba.getLocale() // 'en'
+```
+
+### `verba.getLocales()`
+
+Get all available locales for the project.
+
+```typescript
+const locales = verba.getLocales() // ['en', 'es', 'fr']
+```
+
+### `verba.getDefaultLocale()`
+
+Get the project's default locale.
+
+```typescript
+const defaultLocale = verba.getDefaultLocale() // 'en'
+```
+
+### `verba.ready()`
+
+Wait for translations to be loaded. Useful if you need to ensure translations are available before rendering.
+
+```typescript
+await verba.ready()
+// Translations are now loaded
+```
+
+## How It Works
+
+1. **Initialization**: When you create a `Verba` instance, it immediately fetches all translations from the API.
+
+2. **Caching**: Translations are cached in memory. The SDK uses ETags for efficient cache validation.
+
+3. **Synchronous Access**: After initialization, `t()` calls are synchronous and instant.
+
+4. **Auto-creation**: Missing keys with default values are created in the background without blocking your app.
+
+## Framework Examples
+
+### React
+
+```tsx
+import { Verba } from '@verbadev/js'
+import { createContext, useContext, useState, useEffect } from 'react'
+
+const verba = new Verba({
+  projectId: 'your-project-id',
+  publicKey: 'pk_your-public-key',
+})
+
+const VerbaContext = createContext(verba)
+
+export function VerbaProvider({ children }: { children: React.ReactNode }) {
+  const [, forceUpdate] = useState(0)
+
+  useEffect(() => {
+    verba.ready().then(() => forceUpdate(1))
+  }, [])
+
+  return (
+    <VerbaContext.Provider value={verba}>
+      {children}
+    </VerbaContext.Provider>
+  )
+}
+
+export function useTranslation() {
+  const verba = useContext(VerbaContext)
+  return {
+    t: verba.t.bind(verba),
+    setLocale: (locale: string) => verba.setLocale(locale),
+    locale: verba.getLocale(),
+  }
+}
+
+// Usage:
+// const { t } = useTranslation()
+// t('greeting', 'Hello, {name}!', { name: 'World' })
+```
+
+### Next.js (App Router)
+
+```tsx
+// lib/verba.ts
+import { Verba } from '@verbadev/js'
+
+export const verba = new Verba({
+  projectId: 'your-project-id',
+  publicKey: 'pk_your-public-key',
+})
+
+// components/LocaleSwitcher.tsx
+'use client'
+import { verba } from '@/lib/verba'
+
+export function LocaleSwitcher() {
+  return (
+    <select onChange={(e) => verba.setLocale(e.target.value)}>
+      {verba.getLocales().map((locale) => (
+        <option key={locale} value={locale}>{locale}</option>
+      ))}
+    </select>
+  )
+}
+```
+
+### Vue
+
+```vue
+<script setup>
+import { Verba } from '@verbadev/js'
+import { ref, onMounted } from 'vue'
+
+const verba = new Verba({
+  projectId: 'your-project-id',
+  publicKey: 'pk_your-public-key',
+})
+
+const ready = ref(false)
+
+onMounted(async () => {
+  await verba.ready()
+  ready.value = true
+})
+
+const t = (key, defaultValue) => verba.t(key, defaultValue)
+</script>
+
+<template>
+  <div v-if="ready">
+    <h1>{{ t('welcome.title', 'Welcome!') }}</h1>
+  </div>
+</template>
+```
+
+## TypeScript
+
+The SDK is written in TypeScript and includes full type definitions.
+
+```typescript
+import { Verba, VerbaConfig } from '@verbadev/js'
+
+const config: VerbaConfig = {
+  projectId: 'your-project-id',
+  publicKey: 'pk_your-public-key',
+  locale: 'en',
+}
+
+const verba = new Verba(config)
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,84 @@
+interface VerbaConfig {
+    projectId: string;
+    publicKey: string;
+    /**
+     * Locale to use.
+     * - If omitted or 'auto': auto-detects from browser (navigator.language)
+     * - If specified: uses the exact locale provided
+     */
+    locale?: string | 'auto';
+    baseUrl?: string;
+}
+interface TranslationsResponse {
+    version: number;
+    defaultLocale: string;
+    locales: string[];
+    translations: Record<string, Record<string, string>>;
+}
+interface CreateKeyResponse {
+    created: boolean;
+    key: string;
+    translations: Record<string, string>;
+}
+interface CachedTranslations {
+    version: number;
+    defaultLocale: string;
+    locales: string[];
+    data: Record<string, Record<string, string>>;
+}
+
+declare class Verba {
+    private projectId;
+    private publicKey;
+    private baseUrl;
+    private locale;
+    private autoDetect;
+    private cache;
+    private fetchPromise;
+    private pendingKeys;
+    constructor(config: VerbaConfig);
+    /**
+     * Set the current locale.
+     */
+    setLocale(locale: string): void;
+    /**
+     * Get the current locale.
+     */
+    getLocale(): string;
+    /**
+     * Get list of available locales.
+     */
+    getLocales(): string[];
+    /**
+     * Get the default locale.
+     */
+    getDefaultLocale(): string | null;
+    /**
+     * Get a translation for a key.
+     *
+     * @param key - The translation key
+     * @param defaultValueOrParams - Either a default value string, or params object for interpolation
+     * @param params - Params object for interpolation (when defaultValue is also provided)
+     *
+     * @example
+     * verba.t('greeting')                           // just key
+     * verba.t('greeting', 'Hello!')                 // with fallback
+     * verba.t('greeting', { name: 'World' })        // with params
+     * verba.t('greeting', 'Hello, {name}!', { name: 'World' })  // both
+     */
+    t(key: string, defaultValueOrParams?: string | Record<string, string | number>, params?: Record<string, string | number>): string;
+    /**
+     * Interpolate params into a string.
+     * Replaces {key} with the corresponding value from params.
+     */
+    private interpolate;
+    /**
+     * Wait for translations to be loaded.
+     * Call this if you need to ensure translations are ready.
+     */
+    ready(): Promise<void>;
+    private fetchTranslations;
+    private createKeyInBackground;
+}
+
+export { type CachedTranslations, type CreateKeyResponse, type TranslationsResponse, Verba, type VerbaConfig };

package/dist/index.d.ts

@@ -0,0 +1,84 @@
+interface VerbaConfig {
+    projectId: string;
+    publicKey: string;
+    /**
+     * Locale to use.
+     * - If omitted or 'auto': auto-detects from browser (navigator.language)
+     * - If specified: uses the exact locale provided
+     */
+    locale?: string | 'auto';
+    baseUrl?: string;
+}
+interface TranslationsResponse {
+    version: number;
+    defaultLocale: string;
+    locales: string[];
+    translations: Record<string, Record<string, string>>;
+}
+interface CreateKeyResponse {
+    created: boolean;
+    key: string;
+    translations: Record<string, string>;
+}
+interface CachedTranslations {
+    version: number;
+    defaultLocale: string;
+    locales: string[];
+    data: Record<string, Record<string, string>>;
+}
+
+declare class Verba {
+    private projectId;
+    private publicKey;
+    private baseUrl;
+    private locale;
+    private autoDetect;
+    private cache;
+    private fetchPromise;
+    private pendingKeys;
+    constructor(config: VerbaConfig);
+    /**
+     * Set the current locale.
+     */
+    setLocale(locale: string): void;
+    /**
+     * Get the current locale.
+     */
+    getLocale(): string;
+    /**
+     * Get list of available locales.
+     */
+    getLocales(): string[];
+    /**
+     * Get the default locale.
+     */
+    getDefaultLocale(): string | null;
+    /**
+     * Get a translation for a key.
+     *
+     * @param key - The translation key
+     * @param defaultValueOrParams - Either a default value string, or params object for interpolation
+     * @param params - Params object for interpolation (when defaultValue is also provided)
+     *
+     * @example
+     * verba.t('greeting')                           // just key
+     * verba.t('greeting', 'Hello!')                 // with fallback
+     * verba.t('greeting', { name: 'World' })        // with params
+     * verba.t('greeting', 'Hello, {name}!', { name: 'World' })  // both
+     */
+    t(key: string, defaultValueOrParams?: string | Record<string, string | number>, params?: Record<string, string | number>): string;
+    /**
+     * Interpolate params into a string.
+     * Replaces {key} with the corresponding value from params.
+     */
+    private interpolate;
+    /**
+     * Wait for translations to be loaded.
+     * Call this if you need to ensure translations are ready.
+     */
+    ready(): Promise<void>;
+    private fetchTranslations;
+    private createKeyInBackground;
+}
+
+export { type CachedTranslations, type CreateKeyResponse, type TranslationsResponse, Verba, type VerbaConfig };

package/dist/index.js

@@ -0,0 +1 @@
+"use strict";var l=Object.defineProperty;var h=Object.getOwnPropertyDescriptor;var u=Object.getOwnPropertyNames;var d=Object.prototype.hasOwnProperty;var g=(n,e)=>{for(var s in e)l(n,s,{get:e[s],enumerable:!0})},p=(n,e,s,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let t of u(e))!d.call(n,t)&&t!==s&&l(n,t,{get:()=>e[t],enumerable:!(r=h(e,t))||r.enumerable});return n};var f=n=>p(l({},"__esModule",{value:!0}),n);var m={};g(m,{Verba:()=>o});module.exports=f(m);var y="https://verba.dev";function b(){return typeof navigator>"u"?null:(navigator.languages??[navigator.language])[0]??null}function v(n,e){if(e.includes(n))return n;let s=n.split("-")[0];if(e.includes(s))return s;let r=e.find(t=>t.startsWith(s+"-"));return r||null}var o=class{constructor(e){this.cache=null;this.fetchPromise=null;this.pendingKeys=new Set;this.projectId=e.projectId,this.publicKey=e.publicKey,this.baseUrl=e.baseUrl??y,this.autoDetect=e.locale===void 0||e.locale==="auto",this.autoDetect?this.locale=b()??"en":this.locale=e.locale,this.fetchPromise=this.fetchTranslations()}setLocale(e){this.locale=e}getLocale(){return this.locale}getLocales(){return this.cache?.locales??[]}getDefaultLocale(){return this.cache?.defaultLocale??null}t(e,s,r){let t,i;typeof s=="string"?(t=s,i=r):typeof s=="object"&&(i=s);let a;if(!this.cache)t!==void 0&&this.createKeyInBackground(e,t),a=t??e;else{let c=this.cache.data[e];c?a=c[this.locale]??c[this.cache.defaultLocale]??t??e:(t!==void 0&&this.createKeyInBackground(e,t),a=t??e)}return i&&(a=this.interpolate(a,i)),a}interpolate(e,s){return e.replace(/\{(\w+)\}/g,(r,t)=>s[t]!==void 0?String(s[t]):r)}async ready(){this.fetchPromise&&await this.fetchPromise}async fetchTranslations(){let e=`${this.baseUrl}/api/sdk/${this.projectId}/translations`,s={"X-Public-Key":this.publicKey};this.cache&&(s["If-None-Match"]=String(this.cache.version));try{let r=await fetch(e,{headers:s});if(r.status===304&&this.cache)return this.cache;if(!r.ok)throw new Error(`Failed to fetch translations: ${r.status}`);let t=await r.json();if(this.cache={version:t.version,defaultLocale:t.defaultLocale,locales:t.locales,data:t.translations},this.autoDetect){let i=v(this.locale,t.locales);this.locale=i??t.defaultLocale}return this.cache}catch(r){throw console.error("[Verba] Failed to fetch translations:",r),r}}async createKeyInBackground(e,s){if(!this.pendingKeys.has(e)){this.pendingKeys.add(e);try{let r=`${this.baseUrl}/api/sdk/${this.projectId}/keys`,t=await fetch(r,{method:"POST",headers:{"Content-Type":"application/json","X-Public-Key":this.publicKey},body:JSON.stringify({key:e,defaultValue:s})});if(!t.ok){let a=await t.json().catch(()=>({}));console.error("[Verba] Failed to create key:",a.error??t.status);return}let i=await t.json();this.cache&&i.translations&&(this.cache.data[e]=i.translations)}catch(r){console.error("[Verba] Failed to create key:",r)}finally{this.pendingKeys.delete(e)}}}};0&&(module.exports={Verba});

package/dist/index.mjs

@@ -0,0 +1 @@
+var l="https://verba.dev";function h(){return typeof navigator>"u"?null:(navigator.languages??[navigator.language])[0]??null}function u(a,e){if(e.includes(a))return a;let r=a.split("-")[0];if(e.includes(r))return r;let s=e.find(t=>t.startsWith(r+"-"));return s||null}var c=class{constructor(e){this.cache=null;this.fetchPromise=null;this.pendingKeys=new Set;this.projectId=e.projectId,this.publicKey=e.publicKey,this.baseUrl=e.baseUrl??l,this.autoDetect=e.locale===void 0||e.locale==="auto",this.autoDetect?this.locale=h()??"en":this.locale=e.locale,this.fetchPromise=this.fetchTranslations()}setLocale(e){this.locale=e}getLocale(){return this.locale}getLocales(){return this.cache?.locales??[]}getDefaultLocale(){return this.cache?.defaultLocale??null}t(e,r,s){let t,n;typeof r=="string"?(t=r,n=s):typeof r=="object"&&(n=r);let i;if(!this.cache)t!==void 0&&this.createKeyInBackground(e,t),i=t??e;else{let o=this.cache.data[e];o?i=o[this.locale]??o[this.cache.defaultLocale]??t??e:(t!==void 0&&this.createKeyInBackground(e,t),i=t??e)}return n&&(i=this.interpolate(i,n)),i}interpolate(e,r){return e.replace(/\{(\w+)\}/g,(s,t)=>r[t]!==void 0?String(r[t]):s)}async ready(){this.fetchPromise&&await this.fetchPromise}async fetchTranslations(){let e=`${this.baseUrl}/api/sdk/${this.projectId}/translations`,r={"X-Public-Key":this.publicKey};this.cache&&(r["If-None-Match"]=String(this.cache.version));try{let s=await fetch(e,{headers:r});if(s.status===304&&this.cache)return this.cache;if(!s.ok)throw new Error(`Failed to fetch translations: ${s.status}`);let t=await s.json();if(this.cache={version:t.version,defaultLocale:t.defaultLocale,locales:t.locales,data:t.translations},this.autoDetect){let n=u(this.locale,t.locales);this.locale=n??t.defaultLocale}return this.cache}catch(s){throw console.error("[Verba] Failed to fetch translations:",s),s}}async createKeyInBackground(e,r){if(!this.pendingKeys.has(e)){this.pendingKeys.add(e);try{let s=`${this.baseUrl}/api/sdk/${this.projectId}/keys`,t=await fetch(s,{method:"POST",headers:{"Content-Type":"application/json","X-Public-Key":this.publicKey},body:JSON.stringify({key:e,defaultValue:r})});if(!t.ok){let i=await t.json().catch(()=>({}));console.error("[Verba] Failed to create key:",i.error??t.status);return}let n=await t.json();this.cache&&n.translations&&(this.cache.data[e]=n.translations)}catch(s){console.error("[Verba] Failed to create key:",s)}finally{this.pendingKeys.delete(e)}}}};export{c as Verba};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@verbadev/js",
+  "version": "0.1.0",
+  "description": "JavaScript SDK for Verba Translation Management System",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "verba",
+    "translations",
+    "i18n",
+    "localization",
+    "l10n"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": ""
+  }
+}