SDK e CLI

Dois pacotes no npm: @praeko/sdk, para chamar a API do seu código, e @praeko/cli, o comando praeko no terminal.

Instalar

SDK, no seu projeto

npm install @praeko/sdk

yarn add @praeko/sdk

pnpm add @praeko/sdk

bun add @praeko/sdk

CLI, no terminal

npm install -g @praeko/cli

yarn global add @praeko/cli

pnpm add -g @praeko/cli

bun add -g @praeko/cli

npx @praeko/cli --help
pnpm dlx @praeko/cli --help
bunx @praeko/cli --help
yarn dlx @praeko/cli --help   # yarn 2 ou mais novo

O SDK não tem dependências, traz os tipos do TypeScript e roda em Node 22 ou mais novo, Cloudflare Workers, Deno, Bun e no navegador. O CLI é publicado com o SDK embutido: não há nada mais para instalar. O único comando é praeko.

Início rápido do SDK

Crie uma chave de API no painel (ou com praeko key create) e guarde em PRAEKO_KEY. Nunca coloque a chave no código nem no navegador.

import { Praeko } from "@praeko/sdk";
import { uploadFile } from "@praeko/sdk/node"; // só Node: envia o arquivo do disco em partes

const praeko = new Praeko({ url: "https://praeko.app", key: process.env.PRAEKO_KEY });

const video = await uploadFile(praeko, "./video.mp4", { type: "video", onProgress: (done, total) => {} });
const post = await praeko.posts.create({
  title: "Meu vídeo",
  media: { video: video.id },
  texts: { youtube: { title: "Meu vídeo", text: "Descrição do vídeo" } },
  items: [{ network: "youtube", queue: true }],
});
console.log(post.id);

Fora do Node (Workers, navegador), passe um Uint8Array, um Blob ou { size, read(start, n) } para praeko.media.upload(source, { type, name, mime }). O envio escolhe sozinho entre uma requisição só e várias partes, conforme o tamanho. No navegador, na mesma origem do painel, use { cookies: true } no lugar da chave.

Tentativas e repetição segura

// true: o SDK gera um UUID e o reutiliza em todas as tentativas desta chamada
const post = await praeko.posts.create({ title, media: { video: video.id }, texts, items }, { idempotencyKey: true });

// ou escolha a chave, por exemplo a de um job seu
await praeko.webhooks.create({ url: "https://example.com/hooks/praeko", idempotencyKey: `hook-${jobId}` });

Veja as regras do cabeçalho em Repetir uma requisição. Erros viram PraekoError, com status, code (estável, em inglês), message e details:

import { PraekoError } from "@praeko/sdk";
try { await praeko.posts.get("nao-existe"); }
catch (e) { if (e instanceof PraekoError && e.code === "not_found") { /* … */ } else throw e; }

As rotas e os códigos de erro também saem tipados em @praeko/sdk/contract (ROUTES, ERROR_CODES).

Comandos da CLI

Aponte o CLI para o serviço com --server https://praeko.app (ou PRAEKO_SERVER) e dê a chave em PRAEKO_KEY. Nada é enviado, hospedado ou agendado sem --send: sem ele, post só simula. As mensagens da CLI são em inglês (CLI 0.4.0).

export PRAEKO_KEY="praeko_…"
export PRAEKO_SERVER="https://praeko.app"

praeko --version
praeko channels
praeko post ./meu-video --queue          # simula
praeko post ./meu-video --queue --send   # agenda de verdade

Códigos de saída: 0 sucesso; 1 erro (mensagem em inglês no stderr); 2 comando ou argumento inválido (mostra a ajuda). O CLI não repete sozinho: --idempotency-key serve a quem roda o comando de novo, por exemplo num script com tentativas.

Chave e variáveis de ambiente

Sem PRAEKO_KEY, o CLI procura a chave no Chaveiro do macOS (só no Mac) e no arquivo de segredos. No Linux e no Windows valem a variável e o arquivo.

Versões

SemVer. Enquanto a versão for 0.x, uma mudança incompatível pode sair numa versão menor, e todas constam no CHANGELOG.md de cada pacote. O praeko studio entrega ao Praeko Studio (@praeko/studio), instalado à parte.