Epic: Build the reusable EmailBuilder.js admin editor package

[patoperpetua]

Objective

Create @singleton-sd/post-kit-editor, a reusable React package that lets each PoC/admin application edit its own Git-backed email templates visually using EmailBuilder.js while enforcing PostKit's template format, variables, preview model, and validation rules.

Context

Each consumer owns its templates in its own repository. PostKit should not provide one central CMS for all tenants.

Instead, each PoC/admin app embeds the shared editor package and saves the resulting source files into that application's repository/workflow, similar in spirit to Decap CMS.

Required technology

• React
• TypeScript
• @usewaypoint/email-builder / EmailBuilder.js
• package published to npm as @singleton-sd/post-kit-editor
• shared contracts/schemas from @singleton-sd/post-kit-types
• compiler/preview utilities from @singleton-sd/post-kit-compiler where appropriate
• styling/theming must be consumer-friendly and avoid hard dependency on one application's theme

Responsibilities

The editor package should standardise:

• EmailBuilder document format
• template metadata
• supported variable syntax
• variable catalogue display
• preview/test data
• validation
• serialization/deserialization
• local preview
• test-email trigger integration contract

It should not own GitHub credentials or hardcode how a consumer persists files. Persistence must be provided through callbacks/adapters so the consumer decides how to save to its own repository.

Desired integration

Conceptually:

<EmailTemplateEditor
  template={template}
  availableVariables={variables}
  onSave={saveTemplateToConsumerRepo}
  onSendTest={sendTestEmail}
/>

The final API may differ, but must remain reusable across PoCs.

Template UX

Provide a useful admin editing flow for:

• name/key/description
• subject template
• EmailBuilder visual canvas
• available variables with copy/insert affordances
• preview data editor
• rendered preview
• validation state
• Save
• Send test email

Variables

The editor should make variables explicit and discoverable, e.g.:

Available variables
- First name      {{firstName}}
- Reset URL       {{resetUrl}}
- Company name    {{branding.companyName}}

Do not rely on users memorising template variable names.

The editor should validate against the template's declared variable catalogue and preview data before save/test where possible.

Persistence boundary

The editor must return/source the same Git-backed files expected by the template compiler:

template.json
metadata.json
preview.json

Do not store templates in a PostKit database.

Do not make direct writes to the PostKit repo. The consumer repository owns its own templates.

Test-send boundary

The package may expose a callback/action for test sending, but authenticated PostKit requests should happen through a trusted server-side consumer path. Never require a permanent PostKit API secret in browser JavaScript.

Compatibility

The package must be straightforward to embed in the same React-based admin patterns used by poc-plattform-kit and its derived PoCs.

Avoid coupling the package to a specific router or application shell.

Work

• Create packages/post-kit-editor.
• Integrate EmailBuilder.js.
• Define reusable editor props/API.
• Load/serialize PostKit template sources.
• Add metadata and subject editing.
• Add variable catalogue UI.
• Add preview-data editing.
• Add local rendered preview.
• Add validation feedback.
• Add Save adapter/callback model.
• Add Send Test adapter/callback model.
• Add accessibility and loading/error states.
• Add component/unit tests.
• Add a minimal example integration.
• Configure public npm publication.

Agent implementation notes

Inspect current React/package/component conventions in singleton-sd/poc-plattform-kit before implementation. Reuse conventions where appropriate, but keep this package generic enough to install into other React applications.

EmailBuilder.js JSON is the editable source of truth. Never try to reconstruct the builder document from compiled HTML.

Do not implement runtime sending logic in this package.

Acceptance criteria

• A PoC admin can install the npm package and visually edit an email template.
• Existing template.json, metadata.json, and preview.json can be loaded and saved without losing information.
• Variables are visible and validated.
• A preview can be generated with sample data.
• Save behavior is supplied by the consumer, allowing Git-backed persistence.
• Test-send behavior does not expose long-lived PostKit credentials to the browser.
• Package is framework-shell agnostic, independently buildable/testable, and publishable to npm.