feat(contracts): schemas Zod, erro 422 unificado e versionamento v1/v2 para Edge Functions#84
Closed
adm01-debug wants to merge 1 commit into
Closed
feat(contracts): schemas Zod, erro 422 unificado e versionamento v1/v2 para Edge Functions#84adm01-debug wants to merge 1 commit into
adm01-debug wants to merge 1 commit into
Conversation
…2 para Edge Functions
Estabelece camada compartilhada _shared/contracts/ como fonte única de schemas,
exemplos válidos/inválidos e registry de versionamento para 18 Edge Functions
(3 webhooks externos + 15 com validação prévia). Padroniza todas as respostas
de validação para HTTP 422 com shape { code, message, fields[] }, com
mecanismo X-Contract-Version / Deprecation / Sunset exercitado em
product-webhook v1 (deprecated, sunset 2026-08-22) ↔ v2 (stable, price como
objeto {amount,currency}).
Camada nova:
• _shared/contracts/error-response.ts — shape único + helpers 422/400
• _shared/contracts/versioning.ts — resolveContractVersion + deprecation
• _shared/contracts/<endpoint>.contracts.ts (×18) — registry + examples
• _shared/zod-validate.ts evoluído — parseRequestWithContract + 422
17 handlers refatorados para usar parseBodyWithSchema/parseRequestWithContract
(lógica de negócio inalterada; schemas movidos para contracts/).
Testes:
• tests/contract/edge-functions/all-contracts.test.ts — parametrizado via
import.meta.glob, cobre examples + matriz negativa auto-derivada
• error-response.test.ts, versioning.test.ts (v1↔v2 backwards-compat)
• inventory.test.ts — gate de CI exigindo contrato ou allowlist explícita
para toda Edge Function (61 funções na allowlist hoje, dívida explícita)
• Deno colocados: product-webhook/webhook-inbound/webhook-dispatcher
contract_test.ts cobrindo o fluxo Request→Response no runtime Deno
scripts/contract-testing.mjs reescrito para enumerar contratos via filesystem
e reusar examples (DRY contra os schemas).
Documentação: docs/RUNBOOKS/contracts-and-versioning.md + entrada no CHANGELOG
sinalizando BREAKING CHANGE (400→422 + shape novo). Frontend não consome a
forma antiga; verificado via grep.
Resultado: 125 testes de contrato passando (4 arquivos), ESLint baseline com
drift positivo (1 erro eliminado).
https://claude.ai/code/session_01FeMg7gMQAXtfxJDDVV3YVV
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
|
This pull request has been ignored for the connected project Preview Branches by Supabase. |
Owner
Author
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Sumário
Estabelece uma camada compartilhada de contratos para Edge Functions:
supabase/functions/_shared/contracts/<endpoint>.contracts.ts(18 arquivos){ code, message, fields: [{ path, code, message }] }via_shared/contracts/error-response.tsX-Contract-Versioncom headers automáticosDeprecation: true+Sunset: <ISO>(RFC 8594), exercitado emproduct-webhookv1 (deprecated, sunset 2026-08-22) ↔ v2 (stable, price →{amount,currency})Antes (uso heterogêneo):
400 { error: "Validation failed", details: {...fieldErrors} }.Agora:
422 { code: "VALIDATION_FAILED", message, fields: [...] }.Status 400 fica reservado para
INVALID_JSON,MISSING_BODY,UNSUPPORTED_VERSION(input malformado, não validação semântica).Verificado via grep que o frontend não consome a forma antiga (
.details.fieldErrors,error === 'Validation failed').Escopo
17 handlers refatorados (lógica de negócio inalterada; schemas movidos para
_shared/contracts/):product-webhook,webhook-dispatcher,webhook-inbound(envelope),ai-recommendations,visual-search,semantic-search,generate-ad-prompt,categories-api,commemorative-dates,analyze-logo-colors,sync-quote-bitrix,quote-sync,generate-product-seo,materials-api,kit-identity-suggest,dropbox-list,magic-up-score,external-db-inspect,generate-ad-image,rate-limit-check.As demais 61 Edge Functions (sem validação prévia) entram na allowlist
tests/contract/_allowlist/no-contract.json— o inventory gate força que cada adição futura seja decisão deliberada.Testes
tests/contract/edge-functions/):all-contracts.test.tsparametrizado viaimport.meta.glob, validaexamples.valid[]+examples.invalid[](comexpectedPath) + matriz negativa auto-derivada (missing/wrong/empty) por introspecção do ZodObject.versioning.test.ts: resolução de versão, default v1, headers Deprecation/Sunset, UNSUPPORTED_VERSION, backwards-compat v1↔v2.error-response.test.ts: shape único em todas as respostas, coderequiredpara campo ausente, dot-notation para paths (products.0.sku).inventory.test.ts: gate de CI (cada Edge Function tem contrato OU allowlist; sem órfãos; sem conflito).product-webhook/contract_test.ts,webhook-inbound/contract_test.ts,webhook-dispatcher/contract_test.tsexercitando o_shared/zod-validate.tsno runtime Deno real.Resultado: 4 arquivos de teste, 125 testes passando, ~2.5s.
Test plan
npm test -- tests/contract→ 125 passed (4 files){error, details}ou status 400 de validaçãodeno test --no-check --allow-env --allow-net=none supabase/functions/{product-webhook,webhook-inbound,webhook-dispatcher}/contract_test.ts(rodam no workflowci.ymlque já configura Deno 2.x)SUPABASE_URL=... CONTRACT_TEST_TOKEN=... npm run test:contractproduct-webhookv2 em staging com payload real do n8nDocs
docs/RUNBOOKS/contracts-and-versioning.md— fluxo para criar v2, política de Sunset, allowlist, comandosCHANGELOG.mdcom BREAKING destacadohttps://claude.ai/code/session_01FeMg7gMQAXtfxJDDVV3YVV
Generated by Claude Code
Summary by cubic
Camada compartilhada de contratos com
zodpara 18 Edge Functions, erro 422 padronizado e versionamento viaX-Contract-Version(v1/v2 noproduct-webhook) para reduzir divergências e facilitar evolução sem quebras. Inclui gate de inventário no CI para impedir novas funções sem contrato.New Features
_shared/contracts/, aplicados em 17 handlers.{ code, message, fields[] }(+ 400 paraINVALID_JSON,MISSING_BODY,UNSUPPORTED_VERSION).X-Contract-VersioncomDeprecationeSunset;product-webhookv1 deprecated (Sunset 2026-08-22), v2 estável comprice: { amount, currency }.Migration
{error, details}para 422{ code, message, fields[] }.product-webhook: clientes legados devem enviarX-Contract-Version: v1até migrarem para v2; recomendado adotarpricecomo objeto{ amount, currency }.docs/RUNBOOKS/contracts-and-versioning.md.Written for commit cb29762. Summary will update on new commits. Review in cubic