Dobre a página. A gente guarda. https://orelhudo.rda.run
  • TypeScript 94.9%
  • CSS 4.1%
  • Makefile 0.5%
  • HTML 0.5%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Rodrigo de Avila 6e5ede9e82
links: controles da lista na mesma linha do título
Ficava uma faixa vazia entre o título e a lista. Os chips de filtro só
ocupam uma linha quando existe algum filtro ativo.
2026-11-13 16:17:33 -03:00
.serena coleções: opção de excluir os links junto com a coleção 2026-09-28 15:22:10 -03:00
migrations api: destaques do texto legível, com nota opcional 2026-11-13 15:57:32 -03:00
public pwa: manifesto com share_target para dobrar pelo compartilhar do celular 2026-11-13 15:57:32 -03:00
src links: controles da lista na mesma linha do título 2026-11-13 16:17:33 -03:00
test test: cobre ordenação, números, prévia, tags em lote e destaques 2026-11-13 15:57:32 -03:00
worker api: destaques do texto legível, com nota opcional 2026-11-13 15:57:32 -03:00
.dev.vars.example api, ui: sugestão de tags por IA no modal de dobrar uma página 2026-09-30 19:08:04 -03:00
.gitignore Commit inicial 2026-09-26 18:27:25 -03:00
CLAUDE.md docs: novas rotas, destaques, busca rápida e armadilhas do iframe do legível 2026-11-13 15:57:32 -03:00
index.html pwa: manifesto com share_target para dobrar pelo compartilhar do celular 2026-11-13 15:57:32 -03:00
Makefile Commit inicial 2026-09-26 18:27:25 -03:00
package-lock.json archive, ui: arquivo legível em Markdown, formatado ou como código 2026-10-07 11:41:05 -03:00
package.json archive, ui: arquivo legível em Markdown, formatado ou como código 2026-10-07 11:41:05 -03:00
README.md docs: novas rotas, destaques, busca rápida e armadilhas do iframe do legível 2026-11-13 15:57:32 -03:00
tsconfig.json Commit inicial 2026-09-26 18:27:25 -03:00
vite.config.ts Commit inicial 2026-09-26 18:27:25 -03:00
vitest.config.ts Commit inicial 2026-09-26 18:27:25 -03:00
worker-configuration.d.ts api, ui: sugestão de tags por IA no modal de dobrar uma página 2026-09-30 19:08:04 -03:00
wrangler.jsonc api, ui: sugestão de tags por IA no modal de dobrar uma página 2026-09-30 19:08:04 -03:00

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 HTMLRewriter nativo 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 parcial e o cron horário tenta de novo (até 3 tentativas, ARCHIVE_CRON_BATCH links 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

  1. Crie .env.production a partir de .dev.vars.example, com DEV_FAKE_OIDC=0, o provedor OIDC real e APP_URL.
  2. No provedor OIDC, registre o callback <APP_URL>/auth/callback.
  3. 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.