--- title: "Como começar" description: "Entenda o Cinderace Core, o Captcha e a distribuição Visual em preparação." --- ## 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. | ```text seu storefront / servidor │ └── Cinderace Core ── rotas + tipos + /v1 + browser │ ├── Cinderace Captcha (opcional) ▼ LuckyMaker ``` :::note[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 ```bash 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 ```ts 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: ```ts 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: ```ts 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 ```ts await sdk.auth.signIn({ captcha: "", cpf: "00000000000", password: "senha" }); const session = await sdk.auth.getSession(); ``` O token retornado por `signIn` é salvo automaticamente. A partir daí: ```http Authorization: Bearer ``` No browser, o token fica em `localStorage`. Em SSR/Node, fica em memória. ## 5. Trate erros ```ts 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 ```text 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

Chamadas

System options

Referência