langsys-js-typescript 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,428 @@
+/**
+ * Tiny framework-agnostic reactive value holder — our replacement for a
+ * Svelte `Writable<T>`. The shape is deliberately similar so the mental
+ * model is identical: subscribe/set/update/get.
+ *
+ * Usage:
+ *   const locale = createSignal('en-us');
+ *   locale.subscribe((v) => console.log('locale is now', v));
+ *   locale.set('fr-fr');
+ *   locale.get();       // 'fr-fr'
+ *
+ * Subscribe is called synchronously with the current value on registration
+ * (same semantics as a Svelte store).
+ */
+type Subscriber<T> = (value: T) => void;
+type Unsubscriber = () => void;
+type Updater<T> = (value: T) => T;
+interface Signal<T> {
+    /** Register a subscriber; it's called immediately with the current value. Returns an unsubscribe function. */
+    subscribe(run: Subscriber<T>): Unsubscriber;
+    /** Set the value and notify subscribers. */
+    set(value: T): void;
+    /** Update the value via a function and notify subscribers. */
+    update(fn: Updater<T>): void;
+    /** Read the current value without subscribing. */
+    get(): T;
+}
+declare function createSignal<T>(initial: T): Signal<T>;
+/** Synchronously read a Signal's value. Mirrors svelte's `get(store)`. */
+declare function getValue<T>(signal: Signal<T>): T;
+
+/**
+ * Lightweight debug logger. Styled in browsers (via %c), plain text in Node.
+ * Replaces the pre-existing `echo` module from the Svelte SDK with a simpler,
+ * SSR-safe equivalent.
+ */
+declare class Logger {
+    debugEnabled: boolean;
+    constructor(debugEnabled?: boolean);
+    log(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+declare const logger: Logger;
+
+interface iDirectToken {
+    token: string;
+    trans: string | null;
+}
+interface iDirectTokenTranslations {
+    __DirectToken__?: iDirectToken;
+}
+type iTranslations = iDirectTokenTranslations & {
+    __category__: string;
+    __symbol__: string;
+    [key: string]: string;
+};
+type iCategories = {
+    [key: string]: iTranslations;
+    __uncategorized__: iTranslations;
+};
+
+interface iLangsysInitConfig {
+    /** The ID (UUID) of the project created in Langsys */
+    projectid: string;
+    /** The API key associated with the project */
+    key: string;
+    /**
+     * A reactive holder for the user's selected locale. Accepts any object
+     * with `subscribe`, `set`, and `get` methods (our `Signal<string>` works
+     * out of the box). Use `createSignal('en-us')` if you have nothing of your own.
+     */
+    UserLocaleStore: Signal<string>;
+    /**
+     * Base language/locale for the source strings in your code.
+     * @default 'en'
+     */
+    baseLocale?: string;
+    /**
+     * Enable debug console messages.
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Emulate Langsys failure to load (for testing error handling).
+     * @default false
+     */
+    emulateFailureToLoad?: boolean;
+    /**
+     * Token creation behavior during SSR.
+     * @default 'client'
+     */
+    ssrTokenStrategy?: 'client' | 'server' | 'auto';
+    /**
+     * Pre-fetched translation data to bypass the initial API call.
+     * Useful for SSR scenarios to avoid duplicate fetches.
+     */
+    initialTranslations?: iCategories;
+    /** Locale that `initialTranslations` corresponds to. */
+    initialTranslationsLocale?: string;
+}
+interface iLangsysConfig {
+    projectid: string;
+    key: string;
+    sUserLocale: Signal<string>;
+    baseLocale: string;
+    debug?: boolean;
+    /** Permission level of the API key, set automatically after successful authorization. */
+    key_type?: 'read' | 'write';
+    /**
+     * Token creation behavior during SSR.
+     * - 'client': queue tokens for client-side sending (default)
+     * - 'server': send tokens immediately from server
+     * - 'auto':   send from server if few tokens, queue otherwise
+     * @default 'client'
+     */
+    ssrTokenStrategy?: 'client' | 'server' | 'auto';
+}
+
+/**
+ * Translation function type machinery.
+ *
+ * The big trick here is `ExtractParamKeys` — a recursive template-literal
+ * type that pulls placeholder names out of a phrase at compile time, so
+ * `t('Cat', 'Hello, {name}!', { name: 'Sarah' })` is type-checked: passing
+ * an object without `name`, or with a key not in the phrase, is a TS error.
+ */
+/** Allowed value types for interpolation. Mirrors what ICU MessageFormat will accept. */
+type ParamPrimitive = string | number | Date | boolean;
+/**
+ * Pull placeholder names out of a phrase.
+ * @example
+ *   ExtractParamKeys<"Hello, {name}!">        // "name"
+ *   ExtractParamKeys<"{first} and {last}">    // "first" | "last"
+ *   ExtractParamKeys<"no placeholders here">  // never
+ */
+type ExtractParamKeys<S extends string> = S extends `${string}{${infer K}}${infer Rest}` ? K | ExtractParamKeys<Rest> : never;
+/** Build the params object type required for a given phrase. */
+type ParamsFor<S extends string> = {
+    [K in ExtractParamKeys<S>]: ParamPrimitive;
+};
+/**
+ * Rest-tuple for the optional params argument.
+ * Empty when the phrase has no placeholders → 3rd arg is forbidden.
+ * Required tuple when the phrase has placeholders → 3rd arg must be passed.
+ */
+type TArgs<P extends string> = [ExtractParamKeys<P>] extends [never] ? [] : [params: ParamsFor<P>];
+/** Loose params type — used inside generic stores where the phrase isn't a known literal. */
+type TranslationParams = Record<string, ParamPrimitive>;
+/** The translation function signature. */
+interface TFunction {
+    <P extends string>(category: string, phrase: P, ...args: TArgs<P>): string;
+}
+
+/**
+ * Lifecycle for app translations:
+ *  - on-miss: any `t(cat, phrase)` whose phrase isn't in the catalog is
+ *    queued as a "missing token" and (with write keys) flushed to the API.
+ *  - locale changes trigger `change()` which fetches and replaces.
+ *  - consumers can `subscribe(fn)` to react to translation snapshots.
+ *  - frameworks subscribe to `tSignal` (which re-emits a fresh `TFunction`
+ *    every time translations or the loaded locale change) so reactive
+ *    templates re-render automatically.
+ */
+declare class Translations {
+    private config;
+    private locale;
+    private lastLoaded;
+    private missingTokens;
+    private timer;
+    private flushScheduled;
+    private isFirstClientRun;
+    debug: Logger;
+    /** Reactive holder for the current translation function. Re-emits on every catalog/locale change. */
+    tSignal: Signal<TFunction>;
+    constructor(config: iLangsysConfig);
+    /** Current translation function. Reads fresh state on every call. */
+    get t(): TFunction;
+    /** Subscribe to translation snapshot changes. Fires immediately with the current value. */
+    subscribe(run: (value: iCategories) => void): Unsubscriber;
+    /**
+     * Content-block-keyed lookup used by the DOM `Translate` class.
+     * Returns the per-token translation inside a content block, or `null` if
+     * either the content block or the inner token is missing. Never registers
+     * a missing token — the DOM class manages its own lifecycle via content blocks.
+     */
+    lookupContent(category: string, customId: string, token: string): string | null;
+    private buildTFn;
+    private missingToken;
+    private scheduleTokenFlush;
+    setup(config: iLangsysConfig): void;
+    /**
+     * React to a user-locale change. Fetches translations if we haven't
+     * loaded this locale within the last 60s (or if forced).
+     */
+    change(locale: string, force?: boolean, skipFetch?: boolean): Promise<boolean>;
+    private updateTokens;
+    private getTranslations;
+}
+
+interface HttpResponse {
+    status: number;
+    statusText: string;
+    url: string;
+    data: string;
+}
+interface ResponseObject {
+    status: boolean;
+    page?: number;
+    page_count?: number;
+    records_per_page?: number;
+    data?: object[] | object;
+    errors?: string[];
+    http?: HttpResponse;
+}
+
+interface iCountry {
+    label: string;
+    code: string;
+}
+type iCountryList = iCountry[];
+interface iCountryDialCode {
+    /** ISO 3166-1 alpha-2 country code (e.g., "US", "CA", "GB") */
+    country_code: string;
+    /** International dialing code with + prefix (e.g., "+1", "+44", "+33") */
+    dial_code: string;
+    /** Localized country name in the requested locale */
+    name: string;
+}
+
+interface iCurrency {
+    code: string;
+    name: string;
+    symbol: string;
+    symbol_native: string;
+    decimal_digits: number;
+    rounding: number;
+    name_plural?: string;
+}
+type iCurrencyList = iCurrency[];
+
+interface iLocaleFlat {
+    code: string;
+    name: string;
+}
+interface iLocaleData {
+    /** The locale code */
+    code: string;
+    /** Full locale name */
+    locale_name: string;
+    /** Language name only */
+    lang_name: string;
+}
+type iLanguageName = string;
+/** `{ LanguageName: [{code, name}, ...] }` */
+type iLocaleDefault = Record<iLanguageName, iLocaleFlat[]>;
+
+declare class LangsysAppClass {
+    private config;
+    Translations: Translations;
+    translationsLoadingPromise: Promise<unknown>;
+    private locales;
+    private countries;
+    private countriesLocale;
+    private dialCodes;
+    private dialCodesLocale;
+    private currencies;
+    private currenciesLocale;
+    debug: Logger;
+    constructor();
+    /** Current translation function. Reads fresh state on every call. */
+    get t(): TFunction;
+    refresh(): Promise<boolean>;
+    /**
+     * Initialize Langsys. Configuration must include at least `projectid`,
+     * `key`, and `UserLocaleStore` (any Signal<string>).
+     */
+    init(initConfig: iLangsysInitConfig): Promise<ResponseObject>;
+    getDialCodes(inLocale?: string): Promise<iCountryDialCode[]>;
+    getCurrencies(inLocale?: string): Promise<iCurrencyList>;
+    getCountries(inLocale?: string): Promise<iCountryList>;
+    getCountryName(forCountryCode: string, inLocale?: string): Promise<string>;
+    getCurrencyName(forCurrencyCode: string, inLocale?: string): Promise<string>;
+    getLocalesFormat(format?: '' | 'flat' | 'data', inLocale?: string): Promise<iLocaleDefault | iLocaleFlat[] | iLocaleData[]>;
+    getLocalesFlat(inLocale?: string): Promise<iLocaleFlat[]>;
+    getLocalesData(inLocale?: string, forceRefresh?: boolean): Promise<iLocaleData[]>;
+    getLocales(inLocale?: string): Promise<iLocaleDefault>;
+    getLocaleNameWithLookup(forLocale: string, shortName?: boolean, inLocale?: string): Promise<string>;
+    getLocaleName(forLocale: string, shortName?: boolean, inLocale?: string): string;
+    /** @deprecated use `getLocaleNameWithLookup` or `getLocaleName` */
+    getLanguageName(forLocale: string, shortName?: boolean, inLocale?: string): Promise<string>;
+    /**
+     * Detects the end-user's preferred locale.
+     *
+     * - In browsers, uses `navigator.languages` with fallback to `navigator.language`.
+     * - In SSR environments, parses the `Accept-Language` header.
+     */
+    detectPreferredLocale(acceptLanguageHeader?: string | null, supportedLocales?: string[]): string | false;
+    private getUserLanguagePreferences;
+    private parseAcceptLanguageHeader;
+    private findBestLocaleMatch;
+    private normalizeLocale;
+    private getLanguageCode;
+}
+declare const LangsysApp: LangsysAppClass;
+
+/** Options for the `Translate` class. Matches the Svelte component's props. */
+interface TranslateOptions {
+    /** Optional category under which tokens are registered. Helps translators disambiguate. */
+    category?: string;
+    /** Optional stable id for the content block. If omitted, we hash category+tokens. */
+    custom_id?: string;
+    /** Optional human-readable label shown in the Translation Manager. */
+    label?: string;
+}
+/**
+ * Wrap a DOM element and manage translation for its contents.
+ *
+ *   const el = document.querySelector('#hero');
+ *   new Translate(el, { category: 'Home' });
+ *
+ * The first-pass tokenizes text nodes and translatable attributes; if the
+ * content is a single text run, it's treated as a plain token. For HTML
+ * content, a "content block" is registered so translators see the content
+ * with the same visual structure users see.
+ *
+ * Call `.destroy()` to stop reacting to locale changes.
+ */
+declare class Translate {
+    private element;
+    private options;
+    private contentClone;
+    private tokens;
+    private parseComplete;
+    private isTokenizing;
+    private lastTranslatedLocale;
+    private custom_id;
+    private unsubscribeLocale;
+    constructor(element: HTMLElement, options?: TranslateOptions);
+    /** Stop reacting to locale changes. Safe to call multiple times. */
+    destroy(): void;
+    private translateUpdate;
+    private tokenizeContent;
+    private handleContentBlock;
+    private tokenize;
+    private tokenizeAttributes;
+    private findNode;
+    private translate;
+    private getTranslation;
+    private translateAttributes;
+    private translateAttribute;
+    private generateCustomId;
+    private applyStylesToNode;
+}
+
+declare class LangsysAppAPIClass {
+    private apiurl;
+    config: iLangsysConfig;
+    private headers;
+    constructor();
+    setup(config: iLangsysConfig): void;
+    /** Optional hook to point the client at a different API host. */
+    setBaseUrl(url: string): void;
+    validate(config: iLangsysConfig): Promise<ResponseObject>;
+    getTranslations(locale: string): Promise<ResponseObject>;
+    post(path: string, data?: Record<string, unknown>): Promise<ResponseObject>;
+    get(path: string, data?: Record<string, unknown>): Promise<ResponseObject>;
+    delete(path: string, data?: Record<string, unknown>): Promise<ResponseObject>;
+    patch(path: string, data?: Record<string, unknown>): Promise<ResponseObject>;
+    put(path: string, data?: Record<string, unknown>): Promise<ResponseObject>;
+    private send;
+}
+declare const LangsysAppAPI: LangsysAppAPIClass;
+
+/**
+ * Create a Signal whose value is persisted to localStorage (when available).
+ * Falls back to in-memory behavior during SSR or when storage is unavailable
+ * or quota-exceeded. Stored value is JSON-encoded.
+ */
+declare function persist<T>(key: string, initial: T): Signal<T>;
+
+interface iContentBlock {
+    custom_id: string;
+    category: string;
+    content: string;
+    label?: string;
+    tokens: string[];
+}
+
+declare const sTranslations: Signal<iCategories>;
+declare const currentlyLoadedLocale: Signal<string>;
+declare const contentBlocks: Signal<iContentBlock[]>;
+
+declare const isEmpty: (data: unknown) => boolean;
+declare function md5(inputString: string): string;
+
+/**
+ * Substitute `{name}`-style placeholders in a translated string with values
+ * from `params`. Unknown placeholders are left untouched so missing data is
+ * visible to the developer rather than silently rendering empty strings.
+ *
+ * Dates are serialized to ISO 8601; everything else goes through `String()`.
+ * Designed as a forward-compatible stop-gap until ICU MessageFormat is wired
+ * in for plurals/select/date formatting.
+ */
+declare function interpolate(template: string, params: Record<string, unknown>): string;
+
+interface iProject {
+    id: string;
+    owner_id: string;
+    title: string;
+    description: string;
+    base_locale: string;
+    organization_id: string;
+    organization_name: string;
+    target_locales: string[];
+    default_locales: string[];
+    settings: unknown;
+    admin: string[];
+    last_activity: string;
+    totals: unknown;
+    visitor_locale: string;
+}
+
+declare const t: TFunction;
+declare const tSignal: Signal<TFunction>;
+
+export { type ExtractParamKeys, LangsysApp, LangsysAppAPI, Logger, type ParamPrimitive, type ParamsFor, type Signal, type Subscriber, type TArgs, type TFunction, Translate, type TranslateOptions, type TranslationParams, Translations, type Unsubscriber, type Updater, contentBlocks, createSignal, currentlyLoadedLocale, getValue, type iCategories, type iContentBlock, type iCountry, type iCountryDialCode, type iCountryList, type iCurrency, type iCurrencyList, type iLangsysConfig, type iLangsysInitConfig, type ResponseObject as iLangsysResponse, type iLanguageName, type iLocaleData, type iLocaleDefault, type iLocaleFlat, type iProject, type iTranslations, interpolate, isEmpty, logger, md5, persist, sTranslations, t, tSignal };