Instalação

O Cinderace é distribuído em três áreas:

Pacote	Distribuição	Status
@luckymaker/sdk-core	Cinderace Core	Ativo. Rotas, browser, token, carrinho e system options.
@luckymaker/sdk-visual	Cinderace Visual	Em preparação. Ainda não expõe funcionalidades.
@luckymaker/sdk-captcha	Cinderace Captcha	Ativo e opcional.

yarn add @luckymaker/sdk-core

# Opcional
yarn add @luckymaker/sdk-captcha

O pacote antigo @luckymaker/sdk foi substituído por essas distribuições.

Requisitos

• Node.js 20 ou superior
• Um projeto que consiga importar ESM/TypeScript
• A URL da API do tenant (a SDK cuida de HTTPS e /v1)

Cinderace Core

import { LMSdk } from "@luckymaker/sdk-core";

const sdk = new LMSdk({
    baseUrl: "https://api.sualoja.com.br"
});

const session = await sdk.auth.getSession();

baseUrl aceita:

"api.sualoja.com.br"            // vira https://api.sualoja.com.br/v1
"https://api.sualoja.com.br"    // mantém e adiciona /v1
"https://api.sualoja.com.br/v1" // não duplica
"http://localhost:3000"         // HTTP explícito para desenvolvimento

No browser, você também pode usar a instância automática:

import { LMAutoSdk } from "@luckymaker/sdk-core";

const session = await LMAutoSdk.auth.getSession();
const options = await LMAutoSdk.systemOptions.get();

Opções do Core

Opção	Tipo	Para que serve
baseUrl	string	Origem da API. HTTPS e /v1 são completados.
fetch	typeof fetch	Implementação customizada de fetch.
headers	Record<string, string>	Headers enviados em toda requisição.
token	string	Token bearer inicial.
storage	TokenStorage	Onde o token é persistido.
cartUuid	string	Continua um carrinho existente.
cartStorage	CartStorage	Onde o UUID do carrinho é persistido.
systemOptions	SystemOptionsStoreOptions	Contexto, TTL e storage das system options.

Token e carrinho

No browser, o token e o UUID do carrinho ficam em localStorage. Em SSR/Node, ficam em memória.

Você pode trocar o storage:

import { LMSdk, MemoryTokenStorage, MemoryCartStorage } from "@luckymaker/sdk-core";

const sdk = new LMSdk({
    baseUrl: "api.sualoja.com.br",
    storage: new MemoryTokenStorage(),
    cartStorage: new MemoryCartStorage()
});

SSR

Cada request de servidor deve ter sua própria instância. Não compartilhe uma instância entre usuários diferentes.

System options

const options = await sdk.systemOptions.get();

console.log(options.labels?.siteName);
console.log(options.colors?.primary);

O cache usa localStorage no browser e memória no SSR. O TTL padrão é 60 segundos.

Cinderace Captcha

import { GoogleRecaptchaSolver } from "@luckymaker/sdk-captcha";
import { LMSdk } from "@luckymaker/sdk-core";

const sdk = new LMSdk({
    baseUrl: "api.sualoja.com.br",
    captcha: {
        solver: new GoogleRecaptchaSolver()
    }
});

O Captcha é opcional. Sem ele, a SDK apenas propaga o erro de captcha da API.

Cinderace Visual

O pacote @luckymaker/sdk-visual está reservado para a futura camada de frontend e ainda não expõe funcionalidades. Use o Core por enquanto.

Fetch customizado

const sdk = new LMSdk({
    baseUrl: "api.sualoja.com.br",
    fetch: (input, init) => fetch(input, {
        ...init,
        // adicione tracing, timeout ou um proxy aqui
    })
});

Próximo passo

• Como começar — o caminho completo com o Core.
• Chamadas — assinaturas posicionais e retorno.
• System options — cache e tipos.
• Captcha — reCAPTCHA, Turnstile e retry.