unchained/saleor-core-extensions
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ebe97f67144cccc77691a5d25776d3d770a2eef7
saleor-core-extensions/ROADMAP.md
T

8.3 KiB
Raw Blame History

Core-Extensions Email Service - Roadmap

Current Status ✅

  • Order Created: Working perfectly (customer name, phone, all languages)
  • Order Fulfilled: Working but shows email instead of customer name
  • Order Cancelled: Working but shows email instead of customer name
  • All webhooks firing: ✅ Emails sent via Resend
  • Multi-language support: ✅ Working (tested all 4 languages - SR, EN, DE, FR)
  • Admin notifications: ✅ Both admins receiving emails

PHASE 1: Fix Broken Things (Priority)

1.1 Fix Customer Name in Fulfilled/Cancelled Emails

Problem: Fulfilled and Cancelled webhooks receive partial data from Saleor (no shippingAddress.firstName, no languageCode)

Solution: Query Saleor API when these webhooks fire to get full order details

Files to modify:

  • src/pages/api/webhooks/order-fulfilled.ts
  • src/pages/api/webhooks/order-cancelled.ts

Tasks:

  • Add GraphQL query to fetch full order data including shippingAddress and languageCode
  • Update email template functions to use complete order data
  • Test with real fulfillments and cancellations

Effort: Medium
Impact: High (fixes broken UX)

1.2 Fix Environment Variables Usage

Problem: Hardcoded values in webhook files override env vars

Current:

const ADMIN_EMAILS = ["me@hytham.me", "tamara@hytham.me"];
from: "Manoon Oils <support@mail.manoonoils.com>"

Should be:

const ADMIN_EMAILS = process.env.ADMIN_EMAILS?.split(",") || [];
from: `${process.env.FROM_NAME} <${process.env.FROM_EMAIL}>`

Files to modify:

  • src/pages/api/webhooks/order-created.ts
  • src/pages/api/webhooks/order-fulfilled.ts
  • src/pages/api/webhooks/order-cancelled.ts

Tasks:

  • Replace hardcoded ADMIN_EMAILS with env var
  • Replace hardcoded from addresses with env vars
  • Update .env.example with all required variables
  • Document env vars in README

Effort: Low
Impact: Medium (first step toward reusability)

1.3 Fix Resend Daily Quota Issue

Problem: Multiple emails per order (3 customer + 6 admin = 9 emails per order)

Solutions to consider:

  1. Batch admin emails (send one email with multiple recipients)
  2. Add option to disable admin emails for testing
  3. Use BCC for admin emails

Tasks:

  • Change admin email sending to use single email with multiple recipients or BCC
  • Add DISABLE_ADMIN_EMAILS env var for testing
  • Consider batching order confirmations

Effort: Low
Impact: High (saves quota)

PHASE 2: Make It Reusable (Foundation)

2.1 Extract Brand Configuration to Env Vars

Problem: 20+ hardcoded Manoon Oils references

Files to modify:

  • src/lib/email-templates/order-created.ts
  • src/lib/email-templates/order-shipped.ts
  • src/lib/email-templates/order-cancelled.ts

New env vars needed:

COMPANY_NAME=Manoon Oils
LOGO_URL=https://minio-api.nodecrew.me/...
SITE_URL=https://manoonoils.com
DASHBOARD_URL=https://dashboard.manoonoils.com
TRACKING_URL_TEMPLATE=https://track.manoonoils.com/{trackingNumber}
SUPPORT_EMAIL=support@manoonoils.com

Tasks:

  • Replace all hardcoded company names
  • Replace all hardcoded URLs
  • Replace logo URL
  • Update all email templates

Effort: Medium
Impact: High (enables reusability)

2.2 Unify Email Template System

Problem: Two competing systems (React Email vs Handlebars)

Decision needed:

  • Option A: Stick with Handlebars (simpler, already working)
  • Option B: Migrate to React Email (type-safe, better for complex layouts)
  • Option C: Support both (more complex)

Recommendation: Stick with Handlebars for now (it's working), document the React Email files as "future improvement"

Tasks:

  • Document the two systems in README
  • Remove unused React Email code OR move to separate folder
  • Keep Handlebars as primary system

Effort: Low
Impact: Low (cleanup)

PHASE 3: Advanced Features

3.1 Configuration via Saleor Metadata

Problem: Currently requires code changes to customize

Solution: Store configuration in Saleor's app metadata

Benefits:

  • No code changes needed for new stores
  • Configurable via Saleor dashboard
  • Single deployment serves multiple stores

Files to modify:

  • Add configuration service
  • Modify all webhook handlers to fetch config
  • Add settings UI in app

Tasks:

  • Create configuration interface
  • Add GraphQL queries to fetch config from Saleor metadata
  • Update webhook handlers to use dynamic config
  • Create settings page in app
  • Cache configuration to avoid API calls on every webhook

Effort: High
Impact: High (true multi-tenancy)

3.2 Add Email Preview/Test Feature

Problem: Hard to test email templates without creating real orders

Solution: Add API endpoint to preview/test emails

Tasks:

  • Create /api/test-email endpoint
  • Allow sending test emails to any address
  • Include sample order data for preview
  • Add to app UI for easy testing

Effort: Medium
Impact: Medium (developer experience)

3.3 Phone Number Validation

Problem: Phone validation failing for some formats (GB numbers rejected)

Solution: Make phone optional OR improve validation

Tasks:

  • Investigate Saleor's phone validation
  • Either fix validation or make phone optional in templates
  • Update GraphQL fragments if needed

Effort: Low
Impact: Low (edge case)

PHASE 4: Documentation & Deployment

4.1 Comprehensive README

Sections needed:

  • Installation instructions
  • Environment variables reference
  • Webhook configuration guide
  • Testing instructions
  • Troubleshooting

4.2 Docker Compose for Development

  • Local Saleor instance for testing
  • Easy development setup

4.3 CI/CD Pipeline

  • Automated testing
  • Automated deployment
  • Version tagging

🎯 Recommended Order of Work

Next (Do First):

  1. Fix Customer Name in Fulfilled/Cancelled - Broken UX, high impact
  2. Fix Env Var Usage - Quick win, enables reusability
  3. Fix Quota Issue - Save money immediately

Then:

  1. Extract Brand Config - Makes it reusable
  2. Documentation - Helps with future work

Later:

  1. Saleor Metadata Config - True multi-tenancy
  2. Email Preview Feature - Nice to have
  3. Advanced Features - When needed

Architecture Notes

Current Hardcoded Values

Brand/Company Identity:

  • Company name: "ManoonOils" (12+ instances)
  • Logo URL: MinIO URL to Manoon logo
  • Support email: support@manoonoils.com

URLs:

Email Addresses:

Two Email Systems

  1. React Email (/src/emails/*.tsx)

    • Type-safe React components
    • Currently unused in webhooks
    • Good for complex layouts

  2. Handlebars (/src/lib/email-templates/*.ts)

    • Simple string templates
    • Currently used by webhooks
    • Easy to customize with translations

Recommendation: Stick with Handlebars for production use

Webhook Data Inconsistency

Saleor sends different data for different events:

  • ORDER_CREATED: Full order data ✅
  • ORDER_FULFILLED: Partial data (missing shippingAddress details, languageCode) ❌
  • ORDER_CANCELLED: Partial data (missing shippingAddress details, languageCode) ❌

Fix: Query Saleor API in fulfilled/cancelled webhooks to fetch complete order data

Environment Variables Reference

Current (Working):

RESEND_API_KEY=           # Required - Resend API key

Needed (Not implemented):

ADMIN_EMAILS=             # Comma-separated admin emails
FROM_EMAIL=               # Sender email address
FROM_NAME=                # Sender display name
COMPANY_NAME=             # Company/brand name
LOGO_URL=                 # URL to logo image
SITE_URL=                 # Customer-facing storefront URL
DASHBOARD_URL=            # Admin dashboard URL
TRACKING_URL_TEMPLATE=    # Tracking URL with {trackingNumber} placeholder
SUPPORT_EMAIL=            # Support email shown in templates
DISABLE_ADMIN_EMAILS=     # Set to "true" to disable admin notifications

Last Updated: March 28, 2026

Reference in New Issue View Git Blame Copy Permalink