@beweco/utils

Utility library for phone number validation and Tolgee localization management.

Installation

npm install @beweco/utils-js

Usage

Phone Validation

import { validatePhone } from '@beweco/utils-js';

// Validate a Chilean mobile number
const { isValid, formattedNumber, error } = validatePhone('912345678');
if (isValid) {
  console.log(formattedNumber); // '+56912345678'
} else {
  console.log(error);
}

// Validate with different country code
const result = validatePhone('912345678', '+1');

Tolgee Localization

import { 
  getAllKeysTolgee, 
  downloadTranslations, 
  uploadOnlyNewKeysToTolgee, 
  uploadToTolgee,
  getAvailableLanguages 
} from '@beweco/utils-js';

// Configuration
const config = {
  apiKey: 'your-tolgee-api-key',
  projectId: 'your-project-id',
  baseUrl: 'https://app.tolgee.io' // optional, defaults to this value
};

// Get all available languages
const languages = await getAvailableLanguages(config);

// Get all keys from project
const keys = await getAllKeysTolgee(config);

// Download all translations
const translations = await downloadTranslations(config);

// Upload new keys only
const uploadResult = await uploadOnlyNewKeysToTolgee({
  ...config,
  language: 'es-AR',
  namespace: 'common',
  data: {
    'welcome': 'Bienvenido',
    'hello': 'Hola'
  }
});

// Upload all keys (including duplicates)
const uploadAllResult = await uploadToTolgee({
  ...config,
  language: 'es-AR',
  namespace: 'common',
  data: {
    'welcome': 'Bienvenido',
    'hello': 'Hola'
  }
});

API Reference

Phone Validation

validatePhone(phone: string, countryCode?: string): PhoneValidationResult

Validates and formats a phone number.

Parameters:

• phone - The phone number to validate
• countryCode - Optional country code (default: '+56' for Chile)

Returns: PhoneValidationResult

interface PhoneValidationResult {
  isValid: boolean;
  formattedNumber?: string;
  error?: string;
}

Validation Rules:

• Must be a mobile number (starts with 9)
• Must be 9 digits long (excluding country code)
• Can be provided with or without country code
• Automatically formats to international format (e.g., '+56912345678')

Tolgee Localization

Types

interface TolgeeConfig {
  apiKey: string;
  projectId: string;
  baseUrl?: string;
}

interface Language {
  tag: string;
  name: string;
  originalName: string;
}

interface TranslationData {
  [key: string]: string;
}

interface DownloadTranslationsResult {
  languages: Language[];
  translations: {
    [language: string]: {
      [namespace: string]: {
        [key: string]: string;
      };
    };
  };
}

interface UploadResult {
  uploaded?: number;
  [key: string]: unknown;
}

Functions

getAvailableLanguages(config: TolgeeConfig): Promise<Language[]>

Gets all available languages in the Tolgee project.

getAllKeysTolgee(config: TolgeeConfig): Promise<string[]>

Gets all keys from the Tolgee project with pagination support.

downloadTranslations(config: TolgeeConfig & { namespace?: string }): Promise

Downloads all translations organized by language and namespace.

Parameters:

• config - Tolgee configuration
• namespace - Optional namespace filter

uploadOnlyNewKeysToTolgee(config: TolgeeConfig & { language: string; namespace: string; data: TranslationData }): Promise

Uploads only new keys that don't exist in the project.

Parameters:

• config - Tolgee configuration
• language - Target language (e.g., 'es-AR')
• namespace - Namespace (e.g., 'common')
• data - Translation data object

uploadToTolgee(config: TolgeeConfig & { language: string; namespace: string; data: TranslationData }): Promise

Uploads all keys without checking for duplicates.

Parameters:

• config - Tolgee configuration
• language - Target language (e.g., 'es-AR')
• namespace - Namespace (e.g., 'common')
• data - Translation data object

Constants

const DEFAULT_BASE_URL = 'https://app.tolgee.io';
const DEFAULT_PAGE_SIZE = 1000;

HTTP client

createHttpClient(baseURL, options) returns an axios instance that unwraps response.data. Failed requests do not reject: they resolve with error.response.data (the gateway error envelope, or undefined when no response is received, e.g. network error or timeout).

401 handling:

• A 401 triggers a token refresh against refreshPath and retries the original request with the new access token. Concurrent 401s share a single refresh.
• A 401 whose envelope has error.code (or top-level message) equal to access_denied is an account access denial (e.g. an expired free trial), not an expired token: it is returned as-is, with no refresh and no retry.
• onAuthError is called only when the refresh endpoint rejects the credentials (any 4xx). On network errors, timeouts and 5xx the reactive refresh retries once and keeps the session.

Voice recording core (@beweco/utils-js/voice)

Framework-agnostic (no React, no UI framework) core for batch voice recording with MediaRecorder. It is a separate subpath export on purpose — consumers who only need to record audio should not pull in axios, cookies or locale handling.

import { createVoiceRecorder, toTranscriptionFormData } from '@beweco/utils-js/voice';

const recorder = createVoiceRecorder();
const unsubscribe = recorder.subscribe(() => {
  // re-read recorder.state / recorder.stream (e.g. from useSyncExternalStore)
});

const result = await recorder.start(); // "ok" | "denied" | "unavailable" | "unsupported" | "busy"
// ... later
const blob = await recorder.stop(); // Blob | null
if (blob) {
  const formData = toTranscriptionFormData(blob); // File "audio.<ext>" under field "audio"
}

recorder.dispose(); // release the microphone for good (e.g. on unmount)

This module only owns the recording primitive: it does not transcribe, upload, debounce clicks or invalidate stale starts across multiple calls to start() on a screen. The React hook, the record button and the HTTP adapter that talks to a transcription service live in each consuming app.

Level meter for a decorative waveform (Web Audio; returns 0 without it):

import { createAudioLevelMeter } from '@beweco/utils-js/voice';

const meter = createAudioLevelMeter(recorder.stream!); // after start() === "ok"
const level = meter.getLevel(); // RMS 0..1, read it from your own rAF loop
meter.dispose(); // disconnects and closes the AudioContext; idempotent

Note: the exports field in package.json restricts imports to @beweco/utils-js and @beweco/utils-js/voice — deep paths like @beweco/utils-js/dist/... no longer resolve. No current consumer uses them.

Development

Prerequisites

• Node.js >= 24
• npm

Important: This project requires Node.js version 24 or later. You can use .nvmrc file with:

nvm use

Available Scripts

• npm run clean - Removes the dist directory
• npm run build - Compiles TypeScript code
• npm test - Runs Jest tests
• npm run lint - Runs ESLint
• npm run dev - Runs TypeScript compiler in watch mode

Publishing

This package uses automated publishing to NPM through GitHub Actions.

Manual Release

1. Go to Actions → Publish NPM in GitHub
2. Click Run workflow
3. Select version bump type:
   • patch: Bug fixes (0.0.11 → 0.0.12)
   • minor: New features (0.0.11 → 0.1.0)
   • major: Breaking changes (0.0.11 → 1.0.0)

The workflow will automatically:

• Run tests and build
• Bump version in package.json
• Create git tag and commit
• Publish to NPM
• Push changes back to repository

First-time Setup

Repository admins need to configure the "production" environment with NPM_TOKEN. See .github/DEPLOYMENT.md for detailed instructions.

Contributing

1. Create a new branch from main
2. Make your changes
3. Write/update tests if necessary
4. Run linting and tests: npm run lint && npm test
5. Create a pull request
6. After merge, use GitHub Actions to publish new version

License

MIT