@octaverse/sdk

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

Instalação

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:

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

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

const products = await getVisibleProducts();

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

Categorias

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

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

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

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

ProductCategory

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

Inventory

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

Build

# 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