- TypeScript 94.9%
- CSS 4.1%
- Makefile 0.5%
- HTML 0.5%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
Ficava uma faixa vazia entre o título e a lista. Os chips de filtro só ocupam uma linha quando existe algum filtro ativo. |
||
| .serena | ||
| migrations | ||
| public | ||
| src | ||
| test | ||
| worker | ||
| .dev.vars.example | ||
| .gitignore | ||
| CLAUDE.md | ||
| index.html | ||
| Makefile | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
| tsconfig.json | ||
| vite.config.ts | ||
| vitest.config.ts | ||
| worker-configuration.d.ts | ||
| wrangler.jsonc | ||
Orelhudo
Dobre a página. A gente guarda.
Agregador de links (bookmarks) no estilo do Linkwarden, rodando inteiro na Cloudflare dentro do free tier.
- Coleções aninhadas, tags, links fixados, busca full-text (inclusive no conteúdo arquivado)
- Arquivamento automático de cada link: versão legível em Markdown (formatada ou como código), screenshot e PDF
- Coleções públicas por link (somente leitura, sem login)
- API REST pública com tokens Bearer
- Login via OIDC (qualquer provedor compatível)
- Importação e exportação no formato HTML de favoritos (navegadores e Linkwarden)
- UI em React com kumo, vestida com o Orelhudo Design System (Claude Design): papel e tinta, índigo, marca-texto, Young Serif e Literata, tema claro/escuro
Serviços Cloudflare usados (free tier)
| Serviço | Uso | Limite do plano free |
|---|---|---|
| Workers + Static Assets | API (Hono) e SPA | 100k req/dia, 10 ms de CPU por invocação; assets grátis |
| D1 | dados e busca (FTS5) | 5 GB, 5M leituras/dia, 100k escritas/dia |
| R2 | arquivos (Markdown legível, JPEG, PDF) | 10 GB (a conta precisa de cartão cadastrado para ativar o R2) |
| Queues | fila de arquivamento | 10k operações/dia (cerca de 3 por link) |
| Browser Run | screenshot e PDF | 10 min/dia, 3 browsers simultâneos |
| Cron Trigger | reprocessa arquivamentos pendentes | grátis |
Decisões tomadas por causa desses limites:
- A extração do texto legível usa o
HTMLRewriternativo do Workers (custo de CPU quase zero) em vez de Readability, que estouraria os 10 ms. - A fila processa um link por vez; se a cota do Browser Run acabar, o link fica
parciale o cron horário tenta de novo (até 3 tentativas,ARCHIVE_CRON_BATCHlinks por execução). - Links importados não entram na fila: o cron arquiva aos poucos.
- A importação insere tudo com poucas queries (
json_each), cabendo no limite de queries por invocação. - Sessão em cookie assinado (HMAC), sem KV nem escrita no banco por login.
Rodar localmente
Requisitos: Node 22+, make, openssl.
make run
Na primeira vez, instala as dependências, cria .dev.vars a partir de .dev.vars.example (com SESSION_SECRET aleatório), aplica as migrations no D1 local e sobe o Vite em http://localhost:5173.
O .dev.vars gerado vem com DEV_FAKE_OIDC=1: um provedor OIDC falso embutido que aceita qualquer e-mail. Ele só responde em localhost/127.0.0.1. Para testar com um provedor real localmente, defina DEV_FAKE_OIDC=0 e preencha as variáveis OIDC_*.
D1, R2, fila e Browser Run são simulados localmente pelo wrangler (o Browser Run baixa um Chrome na primeira captura). Os dados ficam em .wrangler/state.
Outros alvos: make test, make typecheck, make build, make types (regenera os tipos após mudar bindings).
Configuração (env vars)
Toda a configuração vem de variáveis de ambiente; o wrangler.jsonc só declara bindings, sem IDs de conta. Referência completa e comentada em .dev.vars.example.
| Variável | Obrigatória | Padrão | Descrição |
|---|---|---|---|
SESSION_SECRET |
sim | Chave HMAC do cookie de sessão (32+ caracteres) | |
OIDC_ISSUER |
sim* | URL do issuer (discovery em /.well-known/openid-configuration) |
|
OIDC_CLIENT_ID |
sim* | Client ID | |
OIDC_CLIENT_SECRET |
não | Vazio = cliente público (só PKCE) | |
OIDC_SCOPES |
não | openid email profile |
|
OIDC_PROVIDER_NAME |
não | SSO |
Nome no botão da tela de login ("Continuar com ...") |
APP_URL |
não | origem da requisição | Base do redirect <APP_URL>/auth/callback |
SESSION_TTL_DAYS |
não | 30 |
|
ALLOWED_EMAILS |
não | Lista separada por vírgula; vazio = qualquer usuário do IdP | |
ALLOWED_DOMAINS |
não | Idem, por domínio do e-mail | |
DEV_FAKE_OIDC |
não | 0 |
Provedor falso de desenvolvimento |
ARCHIVE_SCREENSHOT |
não | true |
|
ARCHIVE_PDF |
não | true |
|
ARCHIVE_CRON_BATCH |
não | 4 |
Links reenfileirados por execução do cron (0 desliga) |
ARCHIVE_MAX_BYTES |
não | 10000000 |
Tamanho máximo de cada arquivo no R2 |
AI_MODEL |
não | @cf/google/gemma-4-26b-a4b-it |
Modelo do Workers AI que sugere tags no modal |
* Dispensadas quando DEV_FAKE_OIDC=1.
Deploy
- Crie
.env.productiona partir de.dev.vars.example, comDEV_FAKE_OIDC=0, o provedor OIDC real eAPP_URL. - No provedor OIDC, registre o callback
<APP_URL>/auth/callback. - Rode:
make deploy
O deploy faz o build, envia as variáveis de .env.production como secrets do Worker (wrangler deploy --secrets-file) e aplica as migrations no D1 remoto. Na primeira vez o wrangler cria automaticamente o banco D1, o bucket R2 e a fila.
Importar do Linkwarden
Em Configurações > Importar de outro serviço, escolha "Linkwarden", informe o endereço da instância e a chave de API (Linkwarden: Settings > Access Tokens).
- Vêm coleções (com hierarquia), links, tags, descrições e datas. Links fixados e os arquivos gerados pelo Linkwarden não são copiados; o Orelhudo refaz as cópias aos poucos, pelo cron.
- Sem chave, só as coleções públicas (descobertas testando IDs em lotes); as que têm pai privado ficam na raiz.
- Pode importar de novo quando quiser: URLs já salvas são ignoradas e coleções com mesmo nome e mesmo pai são reaproveitadas.
- O navegador conduz a importação e o Worker só repassa uma página da API do Linkwarden por chamada (
POST /api/v1/import/linkwarden), para caber nos limites do plano free. A chave não é gravada.
API
Base: /api/v1. Autenticação por Authorization: Bearer <token> (crie tokens em Configurações) ou pelo cookie de sessão da UI. Respostas e corpos em JSON.
| Método e rota | Descrição |
|---|---|
GET /me |
Usuário atual |
GET /links?q=&collection=&tag=&pinned=1&status=&sort=&cursor=&limit= |
Lista. q busca em título, descrição, URL e texto arquivado, e também pelo nome exato de uma tag; com q, cada link traz snippet (trecho do texto, com o termo entre \u0002 e \u0003). collection inclui subcoleções (none = sem coleção); status filtra pela situação da cópia (ok, partial, pending, failed); sort é recent (padrão), oldest ou title. Paginação por next_cursor; a primeira página traz total |
GET /stats |
Números da biblioteca: { links, pinned, uncollected } |
POST /links/preview |
{ url }: título, descrição e imagem da página, e existing se ela já está guardada |
GET /links/:id/highlights · POST /links/:id/highlights · DELETE /highlights/:id |
Destaques do texto legível: { text, note? } |
POST /links |
Cria: { url, title?, description?, collection_id?, tags?, pinned? } |
GET /links/:id |
Detalhe |
PATCH /links/:id |
Atualiza qualquer campo acima; tags substitui a lista |
DELETE /links/:id |
Remove o link e seus arquivos |
POST /links/bulk |
Ação em lote: { ids, action: "delete" }, { ids, action: "move", collection_id } (null tira da coleção) ou { ids, action: "tag" | "untag", tags } |
GET /links/duplicates |
Grupos de links com o mesmo endereço (ignorando a barra final): [{ url, links }] |
POST /links/merge |
Resolve um grupo: { keep, collection_id, tags }. O link keep fica com seus arquivos e recebe coleção e tags; os outros com o mesmo endereço são apagados |
POST /links/:id/archive |
Refaz o arquivamento |
GET /links/:id/archives/:kind |
Arquivo (readable em Markdown, screenshot, pdf) |
GET /collections |
Lista (plana, com parent_id e link_count) |
POST /collections |
{ name, description?, parent_id?, public? } |
PATCH /collections/:id |
Mesmos campos; public: true gera public_slug |
DELETE /collections/:id |
Remove a coleção e subcoleções; os links ficam sem coleção. Com ?links=1, apaga também os links (e arquivos) |
GET /tags · PATCH /tags/:id · DELETE /tags/:id |
Tags (renomear com { name }) |
GET /tokens · POST /tokens · DELETE /tokens/:id |
Tokens ({ name, expires_in_days? }); o token só aparece na criação |
POST /import |
Corpo text/html (ou multipart campo file) no formato de favoritos, até 5 MB. Ignora URLs já salvas e reaproveita coleções existentes; responde { collections, links, skipped } |
POST /import/linkwarden |
Passo da importação do Linkwarden: { url, token?, op: "collections" | "links", from?, collectionId?, cursor? } |
GET /export |
Tudo em HTML de favoritos |
GET /public/collections/:slug |
Coleção pública, sem autenticação |
GET /health |
Health check sem autenticação: { ok: true } se o Worker e o D1 respondem, 503 se o D1 falhar |
Exemplo:
curl -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" \
-d '{"url":"https://example.com","tags":["exemplo"]}' https://seu-app/api/v1/links
Estrutura
worker/ Worker (Hono): api.ts, auth.ts (OIDC + sessão), fake-oidc.ts, archive.ts (fila/cron), bookmarks.ts
src/ SPA React + kumo: App.tsx (layout/sidebar), ui.tsx (componentes comuns), brand.tsx (logo), pages/
src/design/ Tokens do Orelhudo Design System e o mapeamento dos tokens do kumo (orelhudo.css), arte do login
migrations/ Schema D1 (inclui FTS5 e triggers)
test/ Testes de integração no runtime do Workers (vitest + @cloudflare/vitest-plugin)
Fora do escopo por enquanto
Colaboração entre usuários em coleções, arquivos de links em coleções públicas, rate limit da API.