termo_core 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,73 @@
-# Temporary Holding Version
+# termo_core (TypeScript)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Todos os clientes da Termotubos num pacote só, para **frontend e backend**: TypeScript puro, só `fetch`, `interface` e `type`, **sem nenhuma dependência**. Cada serviço é um módulo e cada rota da API é uma função gerada a partir do `openapi.json` do serviço, com o mesmo nome do crate Rust [`termo_core`](https://crates.io/crates/termo_core).
+
+```bash
+npm install termo_core --save-exact
+```
+
+Fixe sempre a versão exata (`"termo_core": "0.1.5"`, sem `^` nem `~`). Cada mudança de contrato do sandbox é publicada subindo só o último número, inclusive quando quebra código. Para atualizar, troque a versão de propósito e confira se compila.
+
+## Ambiente
+
+No backend (Node 20+, Bun, Deno), o endereço de cada serviço vem da variável `AMBIENTE` (`LOCALHOST`, `SANDBOX` ou `PRODUCTION`). No navegador não existe `process.env`, então fixe o ambiente uma vez ao subir o app:
+
+```ts
+import { definir_ambiente_atual_pelo_codigo } from "termo_core";
+
+definir_ambiente_atual_pelo_codigo(import.meta.env.VITE_AMBIENTE); // "SANDBOX"
+```
+
+Sem ambiente, a primeira chamada lança `termo_core: defina a variável AMBIENTE...`: nunca cai em PRODUCTION por engano.
+
+## Chamando uma rota
+
+```ts
+import { CredencialDeAcesso, ErroAoChamarServico } from "termo_core";
+import { buscar_pelo_id_usuario, buscar_paginador_usuario, type Usuario } from "termo_core/auth";
+
+const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
+
+const usuario: Usuario = await buscar_pelo_id_usuario(credencial_de_acesso, id);
+const pagina = await buscar_paginador_usuario(credencial_de_acesso, { pagina: 1 });
+
+try {
+  await buscar_pelo_id_usuario(credencial_de_acesso, id, { sinal_de_cancelamento: controlador.signal });
+} catch (erro) {
+  if (erro instanceof ErroAoChamarServico && erro.servico_nao_encontrou_o_registro()) {
+    // 404
+  }
+}
+```
+
+- Cada serviço tem o próprio caminho de importação (`termo_core/auth`, `termo_core/bucket`...), bom para o bundle do frontend. Também dá para usar `import { auth } from "termo_core"` e chamar `auth.buscar_pelo_id_usuario(...)`.
+- Ordem dos argumentos: credencial (só nas rotas que exigem login), parâmetros do caminho, `parametros` (consulta e cabeçalho), corpo, e por último `opcoes_da_chamada` (`sinal_de_cancelamento`, `tempo_limite_em_milissegundos`, padrão 30 s).
+- Os campos das `interface` têm o nome exato do JSON. Datas, UUIDs e decimais chegam como `string`, como vêm na resposta.
+- Rotas sem corpo na resposta devolvem `Promise<void>`; rotas que devolvem arquivo devolvem `Promise<Uint8Array>`; upload `multipart` recebe um `FormData`.
+- Todo erro vem como `ErroAoChamarServico`, com `tipo`, `status_http`, `mensagem_de_erro` (o campo `erro` da resposta) e `vale_tentar_de_novo()`. O cancelamento pelo `sinal_de_cancelamento` chega como o `AbortError` do próprio `fetch`.
+
+## Token do aplicativo (só backend)
+
+```ts
+import { definir_segredo_do_app, token_do_aplicativo } from "termo_core";
+
+definir_segredo_do_app(segredo_guardado_no_banco); // ou a variável SEGREDO_DO_APP_GERADO_NO_TERMO_AUTH
+const credencial_de_acesso = await token_do_aplicativo();
+```
+
+Troca o segredo por um JWT curto em `POST {TermoAuth}/token_de_app`, guarda em cache e só renova quando falta menos de 60 s para `expira_em`. Nunca use no navegador: o segredo do app não pode ir para o frontend.
+
+## Eventos do TermoWebhook
+
+```ts
+import { webhook } from "termo_core";
+
+type Dados = webhook.eventos.termo_auth.ColaboradorCriadoV1; // dados do evento
+const evento = webhook.eventos.termo_auth.ColaboradorCriadoV1; // { aplicativo, tipo, versao }
+```
+
+Só os contratos. Publicar e receber eventos (assinatura Ed25519, fila no Postgres) existem no crate Rust.
+
+## Gerado
+
+Este pacote é gerado pelo `gerador` do repositório [TermoCore](https://github.com/OrgTermotubos/TermoCore) (`cargo run -p gerador`). Só a pasta `base/` é feita à mão, menos `base/servicos.ts`.

package/dist/ai/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Cliente tipado da API do TermoAI, gerado a partir do `openapi.json` do serviço.
+ */
+export * from "./tipos.js";
+export * from "./rotas.js";
+export { CredencialDeAcesso, ErroAoChamarServico } from "../base/index.js";

package/dist/ai/index.js

@@ -0,0 +1,7 @@
+// Gerado pelo gerador do TermoCore (`cargo run -p gerador`). Não edite à mão: a próxima geração sobrescreve.
+/**
+ * Cliente tipado da API do TermoAI, gerado a partir do `openapi.json` do serviço.
+ */
+export * from "./tipos.js";
+export * from "./rotas.js";
+export { CredencialDeAcesso, ErroAoChamarServico } from "../base/index.js";