Como começar

O que é o Cinderace

O Cinderace é o serviço que entrega a SDK do LuckyMaker. A SDK também é conhecida como LuckyMaker SDK e, na forma curta, LM SDK.

Ele é dividido em três áreas:

Área	Pacote	Status
Cinderace Core	@luckymaker/sdk-core	Ativo. Rotas, browser, token, carrinho e system options.
Cinderace Visual	@luckymaker/sdk-visual	Em preparação. Ainda não expõe funcionalidades.
Cinderace Captcha	@luckymaker/sdk-captcha	Ativo. reCAPTCHA, Turnstile e detecção automática.

seu storefront / servidor
   │
   └── Cinderace Core  ── rotas + tipos + /v1 + browser
                              │
                              ├── Cinderace Captcha (opcional)
                              ▼
                         LuckyMaker

Storefront, não backend

A SDK expõe a superfície pública de storefront. Rotas internas de admin, webhooks e gateways ficam fora do manifesto.

Qual instância usar

Cenário	Use
Browser na mesma origem da API	LMAutoSdk
Browser com API em outro host	new LMSdk({ baseUrl })
SSR/Node, uma instância por request	new LMSdk({ baseUrl })
Job, CLI ou integração sem DOM	new LMSdk({ baseUrl })

1. Instale

yarn add @luckymaker/sdk-core

# Opcional
yarn add @luckymaker/sdk-captcha

O @luckymaker/sdk-visual existe como reserva, mas ainda está vazio.

2. Crie a instância

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

const sdk = new LMSdk({
    // Pode ser só o domínio; HTTPS e /v1 são completados.
    baseUrl: "api.sualoja.com.br"
});

No browser, a instância automática usa a origem da página:

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

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

3. Valide a conexão

Antes de autenticar, faça uma chamada pública:

const cep = await sdk.address.getCep("86036260");
const raffles = await sdk.raffles.listActive();

Se essas chamadas respondem, a baseUrl, o HTTPS e o /v1 estão corretos. Se derem 404, confira o host e o caminho da API.

4. Autentique o usuário

await sdk.auth.signIn({
    captcha: "<token-do-captcha>",
    cpf: "00000000000",
    password: "senha"
});

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

O token retornado por signIn é salvo automaticamente. A partir daí:

Authorization: Bearer <token>

No browser, o token fica em localStorage. Em SSR/Node, fica em memória.

5. Trate erros

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

try {
    await sdk.auth.signIn({ captcha, cpf, password });
} catch (error) {
    if (error instanceof LMSdkError) {
        console.error(error.status, error.code, error.body);
    }
}

6. Siga o fluxo da loja

raffles.listActive()
  -> cart.addItems()
  -> offers.getOffers()
  -> cart.previewIssues()
  -> purchase.createPurchase()
  -> orders.getOrder()

O que acontece por baixo

Comportamento	Detalhe
HTTPS	api.sualoja.com.br vira https://api.sualoja.com.br.
Versão	/v1 é adicionado se ainda não estiver na URL.
Tenant	A baseUrl pode incluir um prefixo como /api.
Token	setsAuthToken salva; clearsAuthToken remove.
Storage	localStorage no browser; memória no SSR.
Carrinho	UUID criado, salvo e reutilizado pela SDK.
Erros	Respostas fora de 2xx viram LMSdkError.
System options	sdk.systemOptions, com cache e tipos.

Próximos passos

Instalação e opções

Opções da instância, storage do token e system options.

Chamadas

Assinaturas posicionais, query, body, settings e erros.

System options

Configurações da loja com cache e tipos no Core.

Referência

Todos os 25 namespaces com assinaturas e exemplos.