fix(listings): improve unexpected error reporting (#117)

* fix listing error reporting

Co-authored-by: Cursor <cursoragent@cursor.com>

* improve listing error traceability

Co-authored-by: Cursor <cursoragent@cursor.com>

* format

* match listing support link colour

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix listing support email links

Co-authored-by: Cursor <cursoragent@cursor.com>

* add support link hover state

Co-authored-by: Cursor <cursoragent@cursor.com>

* harden listing support diagnostics

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: dnywh

README.md

@@ -86,6 +86,9 @@ For local-first Supabase development:
 
 The repo defaults `NEXT_PUBLIC_SUPABASE_URL` to the local stack so development does not need the hosted Peels project. Peels uses ports `54331`–`54334` so it can run beside other local Supabase projects. If `.env.local` still points at hosted Supabase, update it; copying `.env.example` later may not overwrite an existing file.
 
+Keep the local URL, anon key, and service-role key together. Never reuse the
+hosted secret key for local development.
+
 If you need to serve [Supabase edge functions](https://github.com/peels-org/peels/blob/main/supabase/functions) locally, copy `supabase/functions/.env.example` to `supabase/functions/.env`. That file is loaded by `supabase start`. Use `supabase functions serve` only when you want hot reload while editing function code. Production secrets should remain dashboard-managed for now.
 
 For the fuller operational walkthrough, including GitHub/Vercel dashboard setup and fresh-computer bootstrap, see [docs/supabase-local-first.md](./docs/supabase-local-first.md).

docs/supabase-data-architecture.md

@@ -256,8 +256,9 @@ Then run the Storage API cleanup script in dry-run mode:
 npm run media:cleanup-orphans
 ```
 
-For hosted environments, pass the project URL and service-role key explicitly
-and include `--allow-remote`. Deletion requires both `--delete-orphans` and
+For hosted environments, pass the project URL and server-only key explicitly
+and include `--allow-remote`. The newer `sb_secret_...` key is preferred; keep
+the existing `SUPABASE_SERVICE_ROLE_KEY` variable name. Deletion requires both `--delete-orphans` and
 `--confirm-delete-orphans`, plus an explicit `--before` cutoff; this keeps the
 default path inspect-only and protects in-flight uploads whose database
 references have not been written yet.

docs/supabase-local-first.md

@@ -88,9 +88,11 @@ Then make sure `.env.local` has:
 ```bash
 NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54331
 NEXT_PUBLIC_SUPABASE_ANON_KEY=<paste the ANON_KEY value here>
+SUPABASE_SERVICE_ROLE_KEY=<paste the SERVICE_ROLE_KEY value here>
 ```
 
-Do not mix the hosted project URL with the local anon key. That combination fails with `Invalid API key`.
+Use all three values printed by `npm run supabase:env`. Do not mix local and
+hosted URLs or keys.
 
 Finally:
 
@@ -108,6 +110,7 @@ Use this shape in `.env.local` before `npm run test:e2e:prod`:
 NEXT_PUBLIC_SITE_URL=http://127.0.0.1:3000
 NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54331
 NEXT_PUBLIC_SUPABASE_ANON_KEY=<paste the ANON_KEY value from npm run supabase:env>
+SUPABASE_SERVICE_ROLE_KEY=<paste the SERVICE_ROLE_KEY value from npm run supabase:env>
 ```
 
 Recommended sequence:
@@ -116,7 +119,7 @@ Recommended sequence:
 2. Run `npm run supabase:reset`
 3. Run `npm run seed:local-media`
 4. Run `npm run supabase:env`
-5. Paste the printed `ANON_KEY` into `.env.local`
+5. Paste the printed `ANON_KEY` and `SERVICE_ROLE_KEY` into `.env.local`
 6. Run `npm run test:e2e` or `npm run test:e2e:prod`
 
 If `.env.local` still points at `https://mfnaqdyunuafbwukbbyr.supabase.co`, the smoke suite will not see the seeded local listings, demo accounts, or demo chat thread.

e2e/listings.spec.ts

@@ -114,6 +114,55 @@ test("new listing form shows validation feedback when location is missing", asyn
   ).toBeVisible();
 });
 
+test("unexpected listing errors offer a traceable support email", async ({
+  page,
+}) => {
+  await page.setExtraHTTPHeaders({
+    "x-peels-e2e-listing-error": "unexpected",
+  });
+  await signIn(page, {
+    email: HOST_EMAIL,
+    redirectTo:
+      "/profile/listings/new/business?token=test-secret#private-fragment",
+  });
+  await mockMapTilerGeocoding(page);
+
+  await page.locator("#name").fill("Temporary support email test");
+  await page
+    .locator("#description")
+    .fill("A test-only description for the support email flow.");
+  await page.locator("#country").selectOption("AU");
+  const searchInput = page.getByTestId("listing-location-search-input");
+  await searchInput.fill("Newtown");
+  await page.getByRole("option", { name: /Newtown/ }).click();
+  await page.locator('input[name="legal_agreement"]').check();
+  await page.getByTestId("listing-write-submit").click();
+
+  const alert = page.locator("aside[role='alert']");
+  await expect(alert).toContainText("An unexpected error occurred.");
+  const emailLink = alert.getByRole("link", { name: "email us" });
+  await expect(emailLink).toBeVisible();
+
+  const href = await emailLink.getAttribute("href");
+  expect(href).not.toBeNull();
+  expect(href).not.toContain("+");
+  expect(href).toContain("%20");
+  const emailUrl = new URL(href ?? "");
+  expect(emailUrl.protocol).toBe("mailto:");
+  expect(emailUrl.searchParams.get("subject")).toBe(
+    "Problem creating a Peels listing"
+  );
+  expect(emailUrl.searchParams.get("body")).toMatch(
+    /Error reference: listing-[0-9a-f-]+/
+  );
+  expect(emailUrl.searchParams.get("body")).toContain("Listing type: business");
+  expect(emailUrl.searchParams.get("body")).toContain(
+    "/profile/listings/new/business"
+  );
+  expect(emailUrl.searchParams.get("body")).not.toContain("test-secret");
+  expect(emailUrl.searchParams.get("body")).not.toContain("private-fragment");
+});
+
 test("listing location search picks a geocoding result", async ({ page }) => {
   await signIn(page, {
     email: HOST_EMAIL,

messages/de.json

@@ -118,6 +118,9 @@
     "updateFirstNameFailed": "Entschuldigung, wir konnten deinen Vornamen nicht aktualisieren.",
     "updateNewsletterFailed": "Entschuldigung, wir konnten deine Newsletter-Einstellung nicht aktualisieren.",
     "unexpected": "Ein unerwarteter Fehler ist aufgetreten. Bitte versuche es später erneut.",
+    "unexpectedContact": "Wenn das weiterhin passiert, <contact>schreib uns eine E-Mail</contact>.",
+    "unexpectedEmailSubject": "Problem beim Erstellen eines Peels-Eintrags",
+    "unexpectedEmailBody": "Beim Speichern eines Peels-Eintrags ist ein Fehler aufgetreten.\n\nFehlerreferenz: {reference}\nSeite: {pageUrl}\nEintragstyp: {listingType}\nZeit: {timestamp}\n\nBitte ergänze unten weitere hilfreiche Angaben. Gib keine Passwörter oder andere vertrauliche Informationen an.",
     "validationSummary": "Bitte behebe {count, plural, one {den obigen Fehler} other {die obigen Fehler}} und versuche es erneut.",
     "verificationChallenge": "Bitte schließe die Verifizierung ab.",
     "verificationFailed": "Die Verifizierung ist fehlgeschlagen. Bitte versuche es erneut.",
@@ -459,7 +462,7 @@
       "showOnMap": "Diesen Eintrag auf der Karte anzeigen",
       "hideFromMap": "Diesen Eintrag von der Karte ausblenden",
       "adminHint": "Nur für Admins sichtbare Steuerelemente für diesen Eintrag.",
-      "stubSettings": "Stub-Einstellungen",
+      "stubSettings": "Präsentation",
       "regularListing": "Dies ist ein regulärer Eintrag, der dir gehört",
       "stubListing": "Dieser Eintrag ist ein Stub, den andere beanspruchen können",
       "stubActiveHint": "Dieser Eintrag enthält keine deiner Kontaktinformationen. Andere können ihn als eigenen Eintrag beanspruchen und übernehmen.",

messages/en.json

@@ -118,6 +118,9 @@
     "updateFirstNameFailed": "Sorry, we couldn’t update your first name.",
     "updateNewsletterFailed": "Sorry, we couldn’t update your newsletter preference.",
     "unexpected": "An unexpected error occurred. Please try again later.",
+    "unexpectedContact": "If this keeps happening, <contact>email us</contact>.",
+    "unexpectedEmailSubject": "Problem creating a Peels listing",
+    "unexpectedEmailBody": "I encountered an error while saving a Peels listing.\n\nError reference: {reference}\nPage: {pageUrl}\nListing type: {listingType}\nTime: {timestamp}\n\nPlease add any other helpful details below. Do not include passwords or other sensitive information.",
     "validationSummary": "Please fix the above error{count, plural, one {} other {s}} and then try again.",
     "verificationChallenge": "Please complete the verification challenge.",
     "verificationFailed": "Verification failed. Please try again.",
@@ -459,7 +462,7 @@
       "showOnMap": "Show this listing on the map",
       "hideFromMap": "Hide this listing from the map",
       "adminHint": "Admin-only controls for this listing.",
-      "stubSettings": "Stub settings",
+      "stubSettings": "Presentation",
       "regularListing": "This is a regular listing owned by you",
       "stubListing": "This listing is a stub that others can claim",
       "stubActiveHint": "This listing will not contain your contact information. Others can claim it as their own and take it over.",

messages/es.json

@@ -118,6 +118,9 @@
     "updateFirstNameFailed": "Lo sentimos, no pudimos actualizar tu nombre.",
     "updateNewsletterFailed": "Lo sentimos, no pudimos actualizar tu preferencia del boletín.",
     "unexpected": "Ocurrió un error inesperado. Inténtalo de nuevo más tarde.",
+    "unexpectedContact": "Si sigue ocurriendo, <contact>envíanos un correo</contact>.",
+    "unexpectedEmailSubject": "Problema al crear un anuncio en Peels",
+    "unexpectedEmailBody": "Se produjo un error al guardar un anuncio en Peels.\n\nReferencia del error: {reference}\nPágina: {pageUrl}\nTipo de anuncio: {listingType}\nHora: {timestamp}\n\nAñade cualquier otro detalle útil a continuación. No incluyas contraseñas ni otra información confidencial.",
     "validationSummary": "Corrige {count, plural, one {el error anterior} other {los errores anteriores}} y vuelve a intentarlo.",
     "verificationChallenge": "Completa la verificación.",
     "verificationFailed": "La verificación falló. Inténtalo de nuevo.",
@@ -459,7 +462,7 @@
       "showOnMap": "Mostrar este anuncio en el mapa",
       "hideFromMap": "Ocultar este anuncio del mapa",
       "adminHint": "Controles solo para administradores de este anuncio.",
-      "stubSettings": "Configuración de ficha preliminar",
+      "stubSettings": "Presentación",
       "regularListing": "Este es un anuncio normal de tu propiedad",
       "stubListing": "Este anuncio es una ficha preliminar que otras personas pueden reclamar",
       "stubActiveHint": "Este anuncio no contendrá tu información de contacto. Otras personas pueden reclamarlo como propio y hacerse cargo.",

messages/fr.json

@@ -118,6 +118,9 @@
     "updateFirstNameFailed": "Désolé, nous n’avons pas pu mettre à jour votre prénom.",
     "updateNewsletterFailed": "Désolé, nous n’avons pas pu mettre à jour votre préférence d’infolettre.",
     "unexpected": "Une erreur inattendue s’est produite. Veuillez réessayer plus tard.",
+    "unexpectedContact": "Si le problème persiste, <contact>envoyez-nous un e-mail</contact>.",
+    "unexpectedEmailSubject": "Problème lors de la création d’une annonce Peels",
+    "unexpectedEmailBody": "Une erreur s’est produite lors de l’enregistrement d’une annonce Peels.\n\nRéférence de l’erreur : {reference}\nPage : {pageUrl}\nType d’annonce : {listingType}\nHeure : {timestamp}\n\nAjoutez ci-dessous tout autre détail utile. N’indiquez aucun mot de passe ni aucune autre information sensible.",
     "validationSummary": "Veuillez corriger {count, plural, one {l’erreur ci-dessus} other {les erreurs ci-dessus}} puis réessayer.",
     "verificationChallenge": "Veuillez terminer la vérification de sécurité.",
     "verificationFailed": "La vérification a échoué. Veuillez réessayer.",
@@ -459,7 +462,7 @@
       "showOnMap": "Afficher cette annonce sur la carte",
       "hideFromMap": "Masquer cette annonce de la carte",
       "adminHint": "Contrôles réservés à l’administration pour cette annonce.",
-      "stubSettings": "Paramètres du brouillon",
+      "stubSettings": "Présentation",
       "regularListing": "Ceci est une annonce normale créée par vous",
       "stubListing": "Cette annonce est un brouillon que d’autres personnes peuvent revendiquer",
       "stubActiveHint": "Cette annonce ne contiendra pas vos coordonnées. D’autres personnes pourront la revendiquer et la reprendre.",

messages/pt-BR.json

@@ -118,6 +118,9 @@
     "updateFirstNameFailed": "Desculpe, não foi possível atualizar o seu nome.",
     "updateNewsletterFailed": "Desculpe, não foi possível atualizar a sua preferência do boletim.",
     "unexpected": "Ocorreu um erro inesperado. Tente novamente mais tarde.",
+    "unexpectedContact": "Se isso continuar acontecendo, <contact>envie-nos um e-mail</contact>.",
+    "unexpectedEmailSubject": "Problema ao criar um anúncio no Peels",
+    "unexpectedEmailBody": "Ocorreu um erro ao salvar um anúncio no Peels.\n\nReferência do erro: {reference}\nPágina: {pageUrl}\nTipo de anúncio: {listingType}\nHorário: {timestamp}\n\nAdicione abaixo qualquer outro detalhe útil. Não inclua senhas nem outras informações confidenciais.",
     "validationSummary": "Corrija {count, plural, one {o erro acima} other {os erros acima}} e tente novamente.",
     "verificationChallenge": "Conclua a verificação de segurança.",
     "verificationFailed": "A verificação falhou. Tente novamente.",
@@ -459,7 +462,7 @@
       "showOnMap": "Mostrar este anúncio no mapa",
       "hideFromMap": "Ocultar este anúncio do mapa",
       "adminHint": "Controles apenas para admin deste anúncio.",
-      "stubSettings": "Configurações de rascunho",
+      "stubSettings": "Apresentação",
       "regularListing": "Este é um anúncio normal criado por você",
       "stubListing": "Este anúncio é um rascunho que outras pessoas podem reivindicar",
       "stubActiveHint": "Este anúncio não mostrará as suas informações de contato. Outras pessoas podem reivindicá-lo e assumir o controle.",

playwright.config.ts

@@ -13,6 +13,9 @@ export default defineConfig({
     ? {
         ...sharedWebServer,
         command: `npm run dev -- --hostname ${playwrightHost} --port ${playwrightPort}`,
+        env: {
+          PEELS_E2E: "1",
+        },
       }
     : undefined,
 });