Buy Me a Kilo

Una alcancía de viaje anónima. Una sola valija de 23 kilos, una sola persona, y un contador que sube. Cada aporte llena un kilo y devuelve un sticker al azar de una colección de doce.

No es una plataforma. Hay una sola valija y no es de nadie más.

Reglas que el código tiene que sostener

1. No se guarda ningún dato de quien aporta. El webhook de Ko-fi manda nombre, mail, mensaje y dirección de envío: se descartan en el parseo y no se loguean nunca, ni en consola. Lo único que persiste son contadores enteros agregados.
2. La colección vive en el localStorage de cada persona. Sin cuentas, sin login, sin tabla de usuarios.
3. Sin cookies de terceros ni analytics con cookies.
4. El contador es real. Si KV se cae se muestra el último valor conocido, no un número inventado.
5. La capa de economía no puede llegar al cliente. Montos, comisiones y metas internas viven solo en api/. Ninguna de esas env vars lleva prefijo VITE_, y npm run check:leak corre en cada build para verificarlo.

Correr el proyecto

npm install
npm run dev        # http://localhost:5173  (y /open.html para la revelación)
npm run build      # tsc + vite build + check-leak
npm run typecheck

npm run dev alcanza para ver las tres pantallas sin Redis ni vercel dev: un plugin de Vite (mockApi en vite.config.ts) contesta /api/kilos y /api/share, y sirve /open sin extensión igual que en producción. Solo corre en vite dev, así que no existe en el build.

Los estados se fuerzan desde la URL:

URL	Qué muestra
/	214 kg totales, 6 de la semana
/?over	semana en 14: la valija en OVERWEIGHT, perdiendo por abajo
/?kg=12	por debajo del umbral: sin número grande, solo la barra
/?kg=1204&week=3	cualquier combinación
/open	tira un sticker al azar y corre la coreografía
/open?sticker=sticker_12	fuerza uno: sirve para la rara, la maldita y el duplicado

Entrando dos veces a la misma ?sticker= sale el estado de duplicado. Para volver a empezar con la colección vacía: localStorage.clear() en la consola.

npm run dev:host expone el server en la red local, para abrirlo desde el teléfono y revisar el fold en un 360 de verdad.

Las funciones de api/ corren en Vercel. vercel dev las levanta de verdad contra KV cuando haga falta probar el webhook.

Estructura

index.html / open.html      dos entries, sin router: /open no carga el JS del hero
api/kofi-webhook.ts         POST de Ko-fi -> contadores
api/kilos.ts                GET publico, devuelve { total, week } y nada mas
api/stats.ts                dashboard privado, 404 sin key
api/share.ts                contador de tarjetas generadas
api/_lib/economy.ts         precios, comisiones y metas. SOLO SERVIDOR.
src/config/tiers.ts         los cuatro tiers, sin precios
src/config/stickers.ts      los doce stickers y los pesos de rareza
src/config/goals.ts         WEEKLY_GOAL_KG y COUNTER_THRESHOLD_KG
src/copy.ts                 todo el texto
src/lib/shareCard.ts        la tarjeta 1080x1350, compuesta en canvas
scripts/check-leak.mjs      falla el build si la economia se filtro a dist/
public/                     las quince ilustraciones, servidas estaticas

Variables de entorno

Todas se leen con acceso estático desde api/_lib/env.ts. En el runtime edge de Vercel process.env.NOMBRE se resuelve en el build y process.env[variable] no es confiable: una comisión leída por índice cae al default sin avisar y el dashboard miente en silencio. Si agregás una variable nueva, sumala a ese archivo o no va a llegar a la función.

Copiá .env.example y cargalas en Vercel. Ninguna lleva prefijo VITE_.

Las mínimas para que funcione: KOFI_VERIFICATION_TOKEN, KV_REST_API_URL, KV_REST_API_TOKEN y STATS_SECRET.

Si agregás una variable de servidor nueva, sumala a ECONOMY_ENV en scripts/check-leak.mjs: es la lista contra la que el build verifica que nadie le puso prefijo VITE_. Las VITE_VERCEL_* que inyecta Vercel están excluidas a propósito, son públicas por diseño y no tienen nada nuestro adentro.

Cómo se aporta

Un solo botón a ko-fi.com/buymeakilo, donde la persona elige el monto. Los cuatro items de tienda se eliminaron: un botón que ya funciona vale más que una escalera perfecta que no existe, y crearlos venía trabando el lanzamiento. La escalera puede volver.

Los precios ahora se muestran, así que check-leak dejó de tratarlos como fuga. Lo que sigue sin poder llegar al bundle son las comisiones, los pisos semanales, TARGET_PEOPLE y los tokens.

Nada físico, nunca. No se manda nada por correo, así que el pie es literalmente cierto para todos y no hay envío que descontar del neto. El webhook sigue descartando el campo shipping si alguna vez llegara.

La escala: gramos

Una sola valija de 23 kilos para este viaje. La unidad interna son gramos, porque un aporte no llena un kilo: lo llenan entre muchos. Un kilo son unas 220 personas, y eso es el chiste, dicho en voz alta en el hero.

Con montos libres la conversión es proporcional: GRAMS_PER_DOLLAR = 0.6, con un mínimo de un gramo. Cinco dólares son tres gramos, y el copy se deriva de la constante en vez de estar escrito a mano: si cambia, la frase se corrige sola. Vive en src/config/suitcase.ts porque los precios ya no son un dato reservado, y el webhook importa esa misma función.

Todo lo que se ve sale de un único número, en api/_lib/journey.ts:

personas que aportaron
  -> gramos que suman sus tiers
    -> gramos totales (+ SEED_GRAMS)
      -> percentFull = gramos / 23000
        -> altura del relleno, barra, kilos y porcentaje en pantalla

Nada derivado se guarda, así que el nivel dibujado y el porcentaje no se pueden desincronizar. Si alguna vez no coinciden, es un bug.

La clave de KV es total_grams y no reusa total_kilos, que quedó con otra unidad. Las personas siguen saliendo de count_contrib_total, que ya se escribía.

This is the beginning of the README. Read the rest at the original. Read the full README ↗