Sendcore

Build me a private Shopify campaign sender for one store I already own. Not a SaaS, not multi-tenant, no signup. Requirements:

- Node 22 + Fastify + better-sqlite3, server-rendered HTML, no client framework.
- Read the store with a Shopify custom app Admin API token I create myself
  (read_products, read_customers, read_orders); no OAuth, no App Store install flow.
- Send through one bulk email provider with my API key and my already-authenticated
  sending domain; both in .env, ship a .env.example.
- SQLite tables: contacts (email, consent state, source, created_at), products cached
  from Shopify, campaigns (subject, body_html, status, sent_at), and sends
  (contact_id, campaign_id, status, error).
- Every contact carries an explicit consent state. Never send to an unsubscribed or
  unconsented contact, and prove that with a test.
- Every email gets a working one-click unsubscribe link plus List-Unsubscribe
  headers, backed by a signed token and honoured immediately.
- The composer is a plain HTML textarea plus a product picker that inserts image,
  title, price, and link from the synced cache. Render with inline styles and a
  table layout so it survives Gmail and Outlook; no external stylesheets or web fonts.
- Always send a test to myself first, and require a typed confirmation of the
  recipient count before any real send.
- Send in batches with retry and backoff, one send row per recipient, so a crash
  resumes instead of double-sending. Report delivered and failed from the sends
  table only; do not invent open or click tracking.
- CSV import and export for contacts so the data is never trapped in the app.
- Tests: the consent gate, the unsubscribe token, batch resume, and one end-to-end
  campaign against a mocked provider.
- README states what this is not: no deliverability operations, no bounce or
  complaint processing, no App Store distribution, no billing. Say plainly that real
  volume from a cold domain lands in spam, and warmup is now the reader's job.

# AGENTS.md — Build guide for Sendcore

## Project scope
Build a private Shopify app that syncs your products and customers, composes an HTML campaign with a product block, and sends it to a consented segment through your own email provider key.

Catalogue verdict: no. The editor is the copyable part. A coding agent will happily build a private Shopify app that pulls your products, composes an HTML campaign and sends it with your own provider key, and for one store that is genuinely useful. What does not fall out of a one-shot is everything that makes it a product a merchant can run a business on: a listed App Store app with OAuth, mandatory GDPR data webhooks and billing that lands on the merchant's own Shopify invoice, per-tenant domain authentication with the DNS handholding it needs, and the consent, suppression and bounce records that keep sending both legal and delivered. Worth saying plainly: Sendcore is small and recent, with no audience network and no proprietary dataset to hide behind. It survives on platform surface, compliance plumbing and the unglamorous backlog that only real merchant sending reveals, which is a narrower moat than Klaviyo's and an honest one.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- Node.js 22
- SQLite
- Shopify custom app Admin API token (read_products, read_customers, read_orders)
- Bulk email provider key in .env
- A sending domain you control, with SPF and DKIM already verified

## Stack and architecture
- Node 22 + Fastify + better-sqlite3, server-rendered HTML, no client framework.
- Model subscribers, consent records, campaigns, delivery attempts, and suppression state; keep stable source IDs and timestamps.
- Interface for this Shopify + WooCommerce email marketing workflow: a focused Shopify + WooCommerce email marketing input, review, and export interface.

## Security and data integrity
- SQLite tables: contacts (email, consent state, source, created_at), products cached from Shopify, campaigns (subject, body_html, status, sent_at), and sends (contact_id, campaign_id, status, error).
- Validate imported records and file paths; keep user data within the storage location named in the prompt.
- State the practical limit: App Store distribution: OAuth install, app review and the mandatory GDPR data webhooks.

## Agent implementation rules
- Project rule, data: Model subscribers, consent records, campaigns, delivery attempts, and suppression state; keep stable source IDs and timestamps.
- Project rule, behavior: Send through one bulk email provider with my API key and my already-authenticated sending domain; both in .env, ship a .env.example.
- Project rule, recovery: SQLite tables: contacts (email, consent state, source, created_at), products cached from Shopify, campaigns (subject, body_html, status, sent_at), and sends (contact_id, campaign_id, status, error).

## Optional agent skills and references
No installable skill is listed for this guide; use the project rules and the stack documentation.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate this Shopify + WooCommerce email marketing operation with sample or user-owned data: Send through one bulk email provider with my API key and my already-authenticated sending domain; both in .env, ship a .env.example.
- Show a concrete result or export: CSV import and export for contacts so the data is never trapped in the app.
- State the practical limit: App Store distribution: OAuth install, app review and the mandatory GDPR data webhooks.

## Engineering roadmap
1. Phase 1, architecture and data: Node 22 + Fastify + better-sqlite3, server-rendered HTML, no client framework. Model subscribers, consent records, campaigns, delivery attempts, and suppression state; keep stable source IDs and timestamps.
2. Phase 2, implement: Send through one bulk email provider with my API key and my already-authenticated sending domain; both in .env, ship a .env.example.
3. Phase 3, implement: SQLite tables: contacts (email, consent state, source, created_at), products cached from Shopify, campaigns (subject, body_html, status, sent_at), and sends (contact_id, campaign_id, status, error).
4. Phase 4, review and output: Send in batches with retry and backoff, one send row per recipient, so a crash resumes instead of double-sending. Report delivered and failed from the sends table only; do not invent open or click tracking. CSV import and export for contacts so the data is never trapped in the app.
5. Phase 5, recovery and acceptance: SQLite tables: contacts (email, consent state, source, created_at), products cached from Shopify, campaigns (subject, body_html, status, sent_at), and sends (contact_id, campaign_id, status, error). Verify this invariant with a saved fixture: Unsubscribed or bounced addresses must stay suppressed; retrying an ambiguous provider response cannot silently send twice. State the practical limit: App Store distribution: OAuth install, app review and the mandatory GDPR data webhooks.

## Paid-product capabilities outside this build
- App Store distribution: OAuth install, app review and the mandatory GDPR data webhooks
- billing that appears on the merchant's own Shopify invoice instead of a separate card
- domain authentication onboarding and per-tenant sender reputation
- bounce, complaint and suppression handling
- order-level revenue attribution and automations that fire on real store events

## Implementation prompt
Build me a private Shopify campaign sender for one store I already own. Not a SaaS, not multi-tenant, no signup. Requirements:

- Node 22 + Fastify + better-sqlite3, server-rendered HTML, no client framework.
- Read the store with a Shopify custom app Admin API token I create myself
  (read_products, read_customers, read_orders); no OAuth, no App Store install flow.
- Send through one bulk email provider with my API key and my already-authenticated
  sending domain; both in .env, ship a .env.example.
- SQLite tables: contacts (email, consent state, source, created_at), products cached
  from Shopify, campaigns (subject, body_html, status, sent_at), and sends
  (contact_id, campaign_id, status, error).
- Every contact carries an explicit consent state. Never send to an unsubscribed or
  unconsented contact, and prove that with a test.
- Every email gets a working one-click unsubscribe link plus List-Unsubscribe
  headers, backed by a signed token and honoured immediately.
- The composer is a plain HTML textarea plus a product picker that inserts image,
  title, price, and link from the synced cache. Render with inline styles and a
  table layout so it survives Gmail and Outlook; no external stylesheets or web fonts.
- Always send a test to myself first, and require a typed confirmation of the
  recipient count before any real send.
- Send in batches with retry and backoff, one send row per recipient, so a crash
  resumes instead of double-sending. Report delivered and failed from the sends
  table only; do not invent open or click tracking.
- CSV import and export for contacts so the data is never trapped in the app.
- Tests: the consent gate, the unsubscribe token, batch resume, and one end-to-end
  campaign against a mocked provider.
- README states what this is not: no deliverability operations, no bounce or
  complaint processing, no App Store distribution, no billing. Say plainly that real
  volume from a cold domain lands in spam, and warmup is now the reader's job.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.