Cloud Functions

Todas as Functions abaixo são exportadas por functions/index.js. A maior parte usa southamerica-east1.

Ofertas e curadoria

Function	Tipo	Autorização	Responsabilidade
getOfferFeed	callable	autenticado	Elegibilidade, geofiltro, ranking e diversidade do feed regular.
curateOffer	callable	Super Admin	Aprovar, rejeitar, pedir ajustes e alterar tier.
createOfferAsAdmin	callable	Super Admin	Criar oferta em nome de partner preservando autoria.
deleteOffer	callable	regras próprias	Deleção controlada com contexto de auditoria.
onOfferWritten	Firestore trigger	sistema	Criar audit log de mudanças em ofertas.

Cupons e operação

Function	Tipo	Autorização	Responsabilidade
createCouponRedemption	callable	autenticado	Geração atual de cupom, cooldown, Premium/referral e reserva de quota.
activateCoupon	callable	dono do cupom	active → waiting_checkin.
cancelCheckin	callable	dono do cupom	Retorna check-in para active sem liberar a reserva.
cancelCoupon	callable	dono do cupom	Cancela e libera vaga reservada.
markCouponAsUsed	callable	partner owner	Marca uso e converte reserva em uso.
confirmCheckin	callable	sessão de garçom	Confirma check-in e atualiza oferta/cupom em transaction.
generateCoupon	callable	—	Endpoint legado; atualmente falha para forçar o fluxo novo.
expireCoupons	scheduler	sistema	Expira cupons e libera reservas.
resetTrendingProducts	scheduler	sistema	Zera contadores de trending diariamente.

validateGeofence continua exportada por compatibilidade, mas usa a coleção legada coupons; não é o caminho primário de coupon_redemptions.

Campanhas

createCampaign, updateCampaign, changeCampaignStatus, joinCampaign, withdrawCampaignParticipation, submitCampaignOffer, closeExpiredCampaigns e autoTransitionCampaigns.

As três primeiras são administrativas; os fluxos de partner resolvem propriedade do partner no backend antes da mutação.

Garçom e dashboard

• loginWaiter: autentica email + hash do PIN e cria waiter_sessions por 24 h;
• getDashboardStats: calcula métricas de partner/store para janelas de 1, 7 ou 30 dias.

Referral

• submitReferralCode: registra e, quando possível, processa a indicação;
• referralEngine: trigger de phone_verified em update;
• onUserCreatedWithPhoneVerified: cobre criação já validada.

Premium / Stripe

• createStripeCheckoutSession;
• createStripePortalSession;
• stripeWebhook.

Secrets são injetados pelo runtime; nunca devem ser enviados pelo cliente.

Conta e operação

• deleteUserAccount: orquestra limpeza da conta e integração com assinatura quando aplicável;
• getSchedulerSettings / updateSchedulerSettings: Super Admin gerencia throttle operacional dos schedulers.

Tratamento de erros

Callables usam HttpsError. Códigos recorrentes:

• unauthenticated: sessão Firebase ausente;
• permission-denied: papel/propriedade/sessão inválida;
• invalid-argument: payload inválido;
• failed-precondition: estado incompatível;
• already-exists: duplicidade de fluxo;
• resource-exhausted: quota de cupons atingida;
• not-found: entidade necessária inexistente.

Preserve códigos e details.reason ao adicionar tratamento na UI; não reduza tudo a uma mensagem genérica.