@smartcorehub/localization-sdk

SDK TypeScript para consumir a API de localizacao da SmartCoreHub em projetos Angular, React, Next.js, Node.js e TypeScript puro.

O que este pacote entrega

• Cliente tipado para localizacao
• Autenticacao por header X-Auth-Token
• Tratamento de erros padronizado
• Cache opcional e configuravel
• Integracao Angular via provider e service
• Suporte de locale via header HTTP padrao Accept-Language

Requisitos

• Node.js conforme engines em frontendsdk/LocalizationSdkTypeScript/package.json (e apps Angular consumidores)
• npm 9+

Como instalar o pacote no projeto consumidor

Quando o pacote estiver publicado no npm:

npm install @smartcorehub/localization-sdk

Cenarios de consumo suportados

• TypeScript via npm (ESM/CJS + tipos .d.ts)
• JavaScript puro via npm (ESM/CJS)
• HTML simples via CDN com bundle global window.LocalizationSDK

1) Projetos TypeScript (via npm)

import { createLocalizationClient } from '@smartcorehub/localization-sdk';

const client = createLocalizationClient({
	baseUrl: 'https://api.smartcorehub.io/',
	token: 'SEU_TOKEN',
	locale: 'pt-BR',
	cache: {
		enabled: true,
		ttlMs: 60000
	}
});

const title = await client.getCurrentLanguage('home.title');
console.log(title);

2) Projetos JavaScript puro (via npm)

const { createLocalizationClient, LocalStorageCacheProvider } = require('@smartcorehub/localization-sdk');

const client = createLocalizationClient({
	baseUrl: 'https://api.smartcorehub.io/',
	token: 'SEU_TOKEN',
	cache: {
		enabled: true,
		provider: new LocalStorageCacheProvider(),
		ttlMs: 120000
	}
});

client.listResources()
	.then((resources) => console.log(resources.length))
	.catch((error) => console.error(error));

3) Sites HTML simples via CDN (<script>)

O pacote publica dist/umd/localization-sdk.min.js, consumivel por jsDelivr e unpkg.

<script src="https://cdn.jsdelivr.net/npm/@smartcorehub/localization-sdk/dist/umd/localization-sdk.min.js"></script>
<script>
	const client = window.LocalizationSDK.createClient({
		baseUrl: 'https://api.smartcorehub.io/',
		token: 'SEU_TOKEN',
		cache: {
			enabled: true,
			provider: new window.LocalizationSDK.MemoryCacheProvider(),
			ttlMs: 60000
		}
	});

	client.getCurrentLanguage('home.title')
		.then((value) => console.log(value))
		.catch((error) => console.error(error));
</script>

Opcao equivalente em unpkg:

<script src="https://unpkg.com/@smartcorehub/localization-sdk/dist/umd/localization-sdk.min.js"></script>

Primeiro uso rapido (TypeScript, React, Next.js, Node)

import { createLocalizationClient } from '@smartcorehub/localization-sdk';

const localizationClient = createLocalizationClient({
	baseUrl: 'https://api.smartcorehub.io/',
	token: 'SEU_TOKEN',
	locale: 'pt-BR',
	timeoutMs: 10000,
	cache: {
		enabled: true,
		ttlMs: 60000
	},
	enableLogs: true
});

const current = await localizationClient.getCurrentLanguage('home.title');
const byLanguage = await localizationClient.getByLanguage('home.title', 'pt-BR');
const list = await localizationClient.listResources();

// current e byLanguage retornam string
// list retorna objetos { key, value, language }

API global do build UMD

No bundle UMD (CDN), o SDK e exposto como window.LocalizationSDK com os membros abaixo:

• createClient(options) (alias para createLocalizationClient)
• createLocalizationClient(options)
• XAuthTokenProvider
• MemoryCacheProvider
• LocalStorageCacheProvider
• SessionStorageCacheProvider
• LocalizationError, LocalizationAuthError, LocalizationNetworkError, LocalizationServerError, LocalizationTimeoutError, ResourceNotFoundError

Exemplo com autenticacao explicita via X-Auth-Token provider:

<script src="https://cdn.jsdelivr.net/npm/@smartcorehub/localization-sdk/dist/umd/localization-sdk.min.js"></script>
<script>
	const tokenProvider = new window.LocalizationSDK.XAuthTokenProvider('SEU_TOKEN');

	const client = window.LocalizationSDK.createClient({
		baseUrl: 'https://api.smartcorehub.io/',
		authProvider: tokenProvider,
		cache: { enabled: true }
	});

	client.listResources().then(console.log).catch(console.error);
</script>

Locale via Accept-Language

O SDK envia locale usando o header HTTP padrao Accept-Language.

Ordem de prioridade para definir o locale enviado:

• options.locale por chamada
• locale configurado no createLocalizationClient
• navigator.language no browser (fallback automatico)

Exemplo com locale global:

const client = createLocalizationClient({
	baseUrl: 'https://api.smartcorehub.io/',
	token: 'SEU_TOKEN',
	locale: 'pt-BR'
});

Exemplo com override por chamada:

await client.getCurrentLanguage('home.title', { locale: 'en-US' });

Quando cache.enabled = true:

• a primeira chamada de getCurrentLanguage/getByLanguage usa listResources internamente e guarda em cache
• chamadas seguintes retornam do cache
• invalidateCache(key?) e clearCache() podem ser usados para invalidar/limpar

Quando cache.enabled = false:

• o fluxo segue com chamadas diretas aos endpoints

Integracao com Angular

Forma validada e recomendada (mesma usada no exampleangular): facade com createLocalizationClient.

import { Injectable } from '@angular/core';
import { from, Observable } from 'rxjs';
import { createLocalizationClient, LocalizationListResource } from '@smartcorehub/localization-sdk';

@Injectable({ providedIn: 'root' })
export class LocalizationFacadeService {
	private readonly client = createLocalizationClient({
		baseUrl: 'https://api.smartcorehub.io/',
		token: 'SEU_TOKEN',
		cache: { enabled: false },
		enableLogs: true
	});

	getCurrentLanguage(resourceKey: string): Observable<string> {
		return from(this.client.getCurrentLanguage(resourceKey));
	}

	getByLanguage(resourceKey: string, languageKey: string): Observable<string> {
		return from(this.client.getByLanguage(resourceKey, languageKey));
	}

	listResources(): Observable<readonly LocalizationListResource[]> {
		return from(this.client.listResources());
	}
}

Forma com provider Angular (opcional)

Modo alternativo: integracao via provider Angular (provideLocalization + LocalizationService).

Integracao com React

import { useEffect, useState } from 'react';
import { createLocalizationClient } from '@smartcorehub/localization-sdk';

const client = createLocalizationClient({
	baseUrl: 'https://api.smartcorehub.io/',
	token: 'SEU_TOKEN'
});

export function HomeTitle() {
	const [title, setTitle] = useState('');

	useEffect(() => {
		client.getCurrentLanguage('home.title').then((value) => {
			setTitle(value);
		});
	}, []);

	return <h1>{title}</h1>;
}

Contrato de retorno

• getCurrentLanguage(resourceKey): retorna string
• getByLanguage(resourceKey, languageKey): retorna string
• listResources(): retorna LocalizationListResource[]
• invalidateCache(key?): invalida uma chave especifica ou todas as entradas
• clearCache(): limpa todo o cache configurado

export interface LocalizationListResource {
	key: string;
	value: string;
	language: string;
}

Integracao com Next.js

Uso recomendado em Server Components, Route Handlers ou Server Actions.

import { createLocalizationClient } from '@smartcorehub/localization-sdk';

export async function getHomeTitle() {
	const client = createLocalizationClient({
		baseUrl: process.env.LOCALIZATION_API_URL ?? '',
		token: process.env.LOCALIZATION_API_TOKEN ?? ''
	});

	return client.getCurrentLanguage('home.title');
}

Tratamento de erros

O SDK mapeia erros HTTP para classes especificas:

• LocalizationAuthError para 401 e 403
• ResourceNotFoundError para 404
• LocalizationServerError para 5xx
• LocalizationTimeoutError para timeout
• LocalizationNetworkError para erros de rede

import {
	LocalizationAuthError,
	ResourceNotFoundError
} from '@smartcorehub/localization-sdk';

try {
	await localizationClient.getCurrentLanguage('home.title');
} catch (error) {
	if (error instanceof LocalizationAuthError) {
		console.error('Token invalido ou sem permissao');
	}

	if (error instanceof ResourceNotFoundError) {
		console.error('Recurso nao encontrado');
	}
}

Cache configuravel

Quando cache.enabled = true, o provider padrao e MemoryCacheProvider.

import {
	createLocalizationClient,
	MemoryCacheProvider,
	LocalStorageCacheProvider,
	SessionStorageCacheProvider
} from '@smartcorehub/localization-sdk';

const client = createLocalizationClient({
	baseUrl: 'https://api.smartcorehub.io/',
	token: 'SEU_TOKEN',
	cache: {
		enabled: true,
		provider: new MemoryCacheProvider(),
		ttlMs: 120000
	}
});

const localStorageClient = createLocalizationClient({
	baseUrl: 'https://api.smartcorehub.io/',
	token: 'SEU_TOKEN',
	cache: {
		enabled: true,
		provider: new LocalStorageCacheProvider()
	}
});

const sessionStorageClient = createLocalizationClient({
	baseUrl: 'https://api.smartcorehub.io/',
	token: 'SEU_TOKEN',
	cache: {
		enabled: true,
		provider: new SessionStorageCacheProvider()
	}
});

Logging opcional

O SDK nao gera logs por padrao. Para habilitar, passe enableLogs: true no createLocalizationClient.

import { createLocalizationClient } from '@smartcorehub/localization-sdk';

const client = createLocalizationClient({
	baseUrl: 'https://api.smartcorehub.io/',
	token: 'SEU_TOKEN',
	enableLogs: true
});

Quando ativo, o SDK escreve trilhas em console.debug, console.info e console.error para facilitar o rastreio de requests, cache, sucesso e excecoes mapeadas.

Documentacao tecnica para desenvolvimento

Para build, testes automatizados, smoke test e validacao de pacote publicado, consulte:

• SDK-DEVELOPMENT-TESTING.md
• MANUAL-TESTING.md
• DEVELOPMENT-GUIDE.md

Licensing / Licenciamento

English

This project is provided for non-commercial use. Commercial use requires prior authorization from SmartCoreHub through a valid commercial license purchase or an active service contract. See the LICENSE file in this project for full terms.

Portugues (PT-BR)

Este projeto e fornecido para uso nao comercial. O uso comercial exige autorizacao previa da SmartCoreHub, por meio de aquisicao de licenca comercial valida ou contrato de servico ativo. Consulte o arquivo LICENSE deste projeto para os termos completos.