npm package: @octaverse-sdk/node
Description: OctaVerse Firestore SDK
Author: otavio sanchez
Latest version: 1.3.0

# @octaverse/sdk

SDK TypeScript para acessar dados do Firestore da OctaVerse — produtos e categorias — de forma tipada e reutilizável.

## Instalação

```bash
npm install @octaverse/sdk
# ou
yarn add @octaverse/sdk
```

> **Peer dependency:** requer `firebase >= 10.0.0`

---

## Configuração

Antes de usar qualquer função do SDK, inicialize-o com as credenciais do seu projeto Firebase:

```ts
import { initSDK } from "@octaverse/sdk";

initSDK({
  apiKey: "...",
  authDomain: "...",
  projectId: "...",
  storageBucket: "...",
  messagingSenderId: "...",
  appId: "...",
});
```

Chame `initSDK` uma única vez na inicialização da sua aplicação. Chamadas subsequentes com o mesmo app são ignoradas.

---

## Produtos

```ts
import {
  getProducts,
  getActiveProducts,
  getVisibleProducts,
  getProduct,
  getProductBySku,
  getProductsByCategory,
} from "@octaverse/sdk";
```

| Função | Descrição |
|---|---|
| `getProducts()` | Retorna todos os produtos, ordenados por `createdAt` desc |
| `getActiveProducts()` | Retorna produtos com `active: true`, ordenados por nome |
| `getVisibleProducts()` | Retorna produtos com `active: true` e `visibleOnSite: true`, ordenados por nome |
| `getProduct(id)` | Retorna um produto pelo ID do documento, ou `null` se não encontrado |
| `getProductBySku(sku)` | Retorna um produto pelo SKU, ou `null` se não encontrado |
| `getProductsByCategory(category)` | Retorna produtos ativos de uma categoria, ordenados por nome |

### Exemplo

```ts
const products = await getVisibleProducts();

const product = await getProductBySku("OCT-001");
if (product) {
  console.log(product.name, product.platforms);
}
```

---

## Categorias

```ts
import {
  getCategories,
  getActiveCategories,
  getCategory,
} from "@octaverse/sdk";
```

| Função | Descrição |
|---|---|
| `getCategories()` | Retorna todas as categorias, ordenadas por nome |
| `getActiveCategories()` | Retorna categorias com `active: true`, ordenadas por nome |
| `getCategory(id)` | Retorna uma categoria pelo ID do documento, ou `null` se não encontrada |

---

## Tipos

### `Product`

```ts
interface Product {
  id?: string;
  name: string;
  sku: string;
  description: string;
  category: string;
  photos: string[];
  weightGrams: number;
  printTimeMinutes: number;
  materialId: string;
  materialName?: string;
  materialUsageGrams: number;
  productionCost: number;
  stlUrl?: string;
  stlFileName?: string;
  stlPath?: string;
  platforms: Partial<Record<Platform, PlatformEntry>>;
  platformFees: Partial<Record<Platform, number>>;
  active: boolean;
  visibleOnSite: boolean;
  createdAt?: Timestamp;
  updatedAt?: Timestamp;
}
```

### `Platform` e `PlatformEntry`

```ts
type Platform = "shopee" | "mercadolivre" | "amazon" | "magalu";

interface PlatformEntry {
  price: number;
  active: boolean;
  url?: string;
}
```

### `ProductCategory`

```ts
interface ProductCategory {
  id?: string;
  name: string;
  description?: string;
  active: boolean;
  createdAt?: Timestamp;
  updatedAt?: Timestamp;
}
```

### `Inventory`

```ts
interface Inventory {
  productId: string;
  productName: string;
  quantityAvailable: number;
  quantityProduced: number;
  quantityReserved: number;
  lowStockThreshold: number;
  isLowStock: boolean;
  lastUpdated?: Timestamp;
}
```

---

## Build

```bash
# build de produção (ESM + CJS + tipos)
npm run build

# modo watch para desenvolvimento
npm run dev
```

Os artefatos gerados ficam em `dist/`:
- `dist/index.js` — CommonJS
- `dist/index.mjs` — ESM
- `dist/index.d.ts` — declarações TypeScript