App Services

packages/app-services/README.md

@repo/app-services

Servicios de cliente para apps. Encapsula casos de uso y acceso a datos para que las páginas y componentes no llamen directamente a Firebase. Usa @repo/firebase-client-adapter y contratos de @repo/schemas. Los errores tipados usan el contrato neutral de @repo/app-errors.

API y ubicación

src/surveys/surveys-service.ts: encuestas.
src/users/: usuarios e invitaciones de usuarios.
src/communities/communities-service.ts: comunidades.
src/auth/auth-service.ts: autenticación.
src/info/: agregado de información del barrio, permisos y errores tipados.
src/types/types.ts: tipos auxiliares del package.

Todos se reexportan desde src/index.ts y se consumen desde @repo/app-services.

Caso de uso Information

src/info/ administra el agregado de información del barrio en communities/{communityId}/info/data. @repo/schemas valida los datos y @repo/constants provee permisos; los adapters de Firestore y Storage permanecen encapsulados en este package.

Área	API pública
Lectura y realtime	`getInfoData`, `subscribeToInfoChanges`
Agregado	`createInfo`, `updateInfoData`
FAQ	`createInfoFaq`, `updateInfoFaq`, `deleteInfoFaq`
Contactos	`createInfoContact`, `updateInfoContact`, `deleteInfoContact`
Normas	`uploadInfoStandards`, `renameInfoStandard`, `deleteInfoStandard`

El servicio valida los payloads y reconstruye el documento agregado mediante transacciones. La primera creación puede inicializar el documento base; editar o borrar ids ausentes produce INFO_NOT_FOUND. El listener valida cada snapshot, normaliza errores y entrega un unsubscribe idempotente.

La subida carga objetos en Storage y luego actualiza metadata. Si una etapa falla, intenta borrar los paths subidos para evitar objetos huérfanos. El borrado resuelve el path desde metadata o URLs antiguas, elimina Storage antes de retirar metadata y tolera que el objeto ya no exista. Es una compensación entre servicios, no una transacción distribuida.

Los códigos se exportan como INFO_ERROR_CODES desde @repo/app-services/info-errors; las operaciones se reexportan desde el barrel principal. La app convierte códigos/kinds a copy local. src/info/info-service.test.ts prueba la lógica del servicio con adapters mockeados, no las Security Rules de Firebase.

Regla de separación

Usar este package para operaciones iniciadas por una app cliente. No importar Firebase SDK directo en componentes: el servicio debe delegar en @repo/firebase-client-adapter. Si una operación requiere Admin SDK o se ejecuta dentro de Cloud Functions, implementarla en @repo/app-function-services.

Contrato de errores

Los servicios resuelven con datos tipados o lanzan AppError desde @repo/app-errors. Cada error debe usar un code estable namespaced, un kind del catálogo compartido y un message técnico seguro. Preservar el error externo en cause; no copiar mensajes de Firebase/SDK al mensaje ni incluir datos sensibles en metadata. Las apps mapean code/kind a copy de producto.

El piloto info ya cumple este contrato. Sus códigos públicos están disponibles desde @repo/app-services/info-errors; otros dominios aún están pendientes de migración y conservan sus contratos existentes hasta abordarse explícitamente.

Como agregar un servicio

Crear src/<dominio>/<dominio>-service.ts.
Reutilizar schemas y tipos de @repo/schemas.
Usar el adapter client para Firestore/Auth/Storage.
Exportar desde src/index.ts.
Agregar o actualizar tests Vitest y documentar el flujo.

Validacion

bash

pnpm --filter @repo/app-services lint
pnpm --filter @repo/app-services type-check
pnpm --filter @repo/app-services build
pnpm --filter @repo/app-services test:run