---
title: "Instalação"
description: "Instalação e configuração do Cinderace Core."
---
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. |

```bash
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

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

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

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

`baseUrl` aceita:

```ts
"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:

```ts
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:

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

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

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

## System options

```ts
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

```ts
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

```ts
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](/docs/guias/comecando/) — o caminho completo com o Core.
- [Chamadas](/docs/guias/chamadas/) — assinaturas posicionais e retorno.
- [System options](/docs/guias/system-options/) — cache e tipos.
- [Captcha](/docs/guias/captcha/) — reCAPTCHA, Turnstile e retry.