5b2207a397
Some checks failed
CI / Lint, Unit & Integration Tests (push) Has been cancelled
Also fixes the [events] gate that was blocking ALL extension generation
(discovered while starting this phase).
- shopify.app.toml: this org appears enrolled in Shopify's "Next
Generation Events" developer preview, which the CLI now treats as a
REQUIRED top-level [events] section even though nothing in this app
actually uses it (real webhook handling is entirely classic [webhooks],
unaffected). Iteratively discovered the required shape from the CLI's
own field-by-field validation errors, then found the real docs (Events
is optional/developer-preview, api_version pinned to "unstable") to
confirm rather than keep guessing. Added a functionally-inert
[[events.subscription]] placeholder + a stub handler
(webhooks.events.placeholder.tsx) solely to satisfy the gate.
- app/services/availability-request.server.ts +
app/services/hold-request.server.ts: extracted the resolution logic that
used to live directly in apps.scheduling.availability.tsx/hold.tsx into
shared functions. This is what actually makes "same capacity pool feeds
every surface" (CLAUDE.md) true by construction rather than by
convention — the storefront, POS, and checkout routes now call the exact
same code, not three copies that could quietly drift apart.
- extensions/pos-datetime (generated via `shopify app generate extension
--template=pos_smart_grid` — pos_action's flavor requirement contradicted
the CLI's own global --flavor validator, so smart_grid was used instead):
a home-screen tile opening a modal where staff pick method -> date -> time
against the same availability/hold endpoints (pos.scheduling.*.tsx,
session-token authenticated), writing the same dd_* cart properties via
CartApi.addCartProperties — booking.server.ts needed zero changes to
handle POS-originated orders. Several API-shape guesses (toast isError
option, ChoiceList's `value`/`label` props, a nonexistent
action.dismissModal(), shopify.cart.cart.current) were wrong and caught
by typechecking directly against @shopify/ui-extensions' own bundled
.d.ts files (`npm run typecheck:pos`, now also in CI) — none of this was
verified against a live POS session, which isn't possible in this
environment.
- extensions/checkout-datetime (generated via `--template=checkout_ui`):
the Plus-only native picker in checkout itself
(purchase.checkout.block.render) plus a Thank You confirmation block
(purchase.thank-you.block.render). Went looking for an order-status
target too ("all plans show confirmed slot on thank-you/order-status" is
the Phase 7 accept criterion) and confirmed via the installed package's
own type definitions that purchase.order-status.block.render does not
exist in this API version — checkout UI extensions' thank-you/order-status
surfaces are Plus-only regardless. The actual "all plans" mechanism is
extensions/datetime-widget/blocks/order-confirmation.liquid — a new Theme
App Extension block reading order.note_attributes, which works on every
plan since it's plain Liquid, not checkout extensibility.
Both new UI extensions share one real unverified assumption, called out in
code comments: process.env.APP_URL is expected to be substituted at build
time by the Shopify CLI to the app's backend origin, since these run in a
different origin than the app and need an absolute URL, unlike the
storefront widget's relative /apps/scheduling/* path. Needs confirming
against a live dev session.
Verified: lint, typecheck (root + both new extensions'
`npm run typecheck:pos`/`typecheck:checkout`, all now in CI), 102 unit +
18 integration tests (unchanged — this phase didn't touch pure business
logic, only added thin auth wrappers around already-tested services), both
admin/widget builds.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
115 lines
6.2 KiB
Markdown
115 lines
6.2 KiB
Markdown
# Delivery Date & Time
|
|
|
|
Shopify app: scheduling for Shipping / Local Delivery / Store Pickup, with
|
|
date-time slots, capacity intelligence, and **all-plan checkout enforcement**
|
|
via Cart/Checkout Validation Functions.
|
|
|
|
Read **[PRODUCT_STRATEGY.md](./PRODUCT_STRATEGY.md)** (why) and
|
|
**[IMPLEMENTATION_PLAN.md](./IMPLEMENTATION_PLAN.md)** (how, phased build
|
|
order) before making changes. [CLAUDE.md](./CLAUDE.md) holds the
|
|
non-negotiables for AI-assisted work in this repo.
|
|
|
|
## Getting started
|
|
|
|
```sh
|
|
npm install
|
|
cp .env.example .env # fill in Shopify app credentials after linking
|
|
docker compose up -d # local Postgres (5433) + Redis (6380)
|
|
npx prisma migrate dev
|
|
npm run dev # shopify app dev — requires `shopify auth login` first
|
|
```
|
|
|
|
Dev uses Postgres, same as prod, since the schema relies on Prisma enums and
|
|
(from Phase 5 on) array fields that SQLite can't express. `npm run worker`
|
|
runs the BullMQ worker (jobs/worker.ts) once Phase 4 makes it do anything.
|
|
|
|
## Commands
|
|
|
|
| Command | Purpose |
|
|
|---|---|
|
|
| `npm run dev` | `shopify app dev` — local dev against a dev store |
|
|
| `npm test` | Vitest unit tests |
|
|
| `npm run test:e2e` | Playwright E2E |
|
|
| `npm run lint` / `npm run typecheck` | ESLint / `tsc --noEmit` |
|
|
| `npx prisma migrate dev` | DB migrations |
|
|
| `npm run deploy` | `shopify app deploy` — deploy extensions/functions |
|
|
| `npm run worker` | BullMQ worker (hold-expiry, notifications) |
|
|
| `npm run test:integration` | Redis/Postgres-backed tests (slot-hold concurrency, booking flow) — needs `docker compose up -d` |
|
|
| `npm run test:functions` | Real WASM build + `function-runner` tests for both Shopify Functions, against fixtures |
|
|
| `npm run typegen:functions` | Regenerate `extensions/*/generated/api.ts` from each Function's `schema.graphql` + `.graphql` query (also runs automatically before `npm run typecheck`) |
|
|
|
|
## Before public launch
|
|
|
|
The 3 mandatory GDPR compliance webhooks (`customers/data_request`,
|
|
`customers/redact`, `shop/redact`) are commented out in `shopify.app.toml`
|
|
— Shopify refuses to push them until the org requests and is granted
|
|
**Protected customer data access** in the Partner Dashboard (Apps → this
|
|
app → API access → Protected customer data), which is a manual
|
|
questionnaire/approval step. The handlers already exist and are fully
|
|
wired (`app/routes/webhooks.customers.*.tsx`, `webhooks.shop.redact.tsx`) —
|
|
once that access is granted, uncomment the three `[[webhooks.subscriptions]]`
|
|
blocks near the bottom of the webhooks section. **Required before any
|
|
public launch or Built-for-Shopify submission** — don't ship without it.
|
|
|
|
## Status
|
|
|
|
Phase 0 (scaffold & CI) through Phase 7 (POS + Checkout UI extensions) are
|
|
complete — that's the full v1 launch scope per §8 of
|
|
`PRODUCT_STRATEGY.md`/§6 of `IMPLEMENTATION_PLAN.md`. Phase 8 (billing +
|
|
Built-for-Shopify hardening) is next; Phases 9-10 (v1.x fast-follow, v2) are
|
|
explicitly separate post-launch milestones in the plan, not part of v1.
|
|
|
|
**Every scheduling surface calls the same two service functions**
|
|
(`app/services/availability-request.server.ts`,
|
|
`app/services/hold-request.server.ts`) — the storefront widget (app-proxy
|
|
auth), POS (`extensions/pos-datetime`, session-token auth), and Plus
|
|
checkout (`extensions/checkout-datetime`, session-token auth) each have
|
|
their own thin route wrapper but share the exact same resolution logic and
|
|
Redis-backed capacity pool, so a slot booked from any one of them is
|
|
unavailable on the other two. `extensions/checkout-datetime`'s Thank You
|
|
block and `extensions/datetime-widget`'s new `order-confirmation.liquid`
|
|
block both show the confirmed slot after checkout — the Liquid block is
|
|
what actually satisfies "all plans," since Checkout UI Extensions'
|
|
thank-you/order-status targets are Plus-only; there's no
|
|
`purchase.order-status.block.render` target in this API version (verified
|
|
against `@shopify/ui-extensions`' own type definitions — an early guess
|
|
based on the target name pattern was wrong).
|
|
|
|
**Unverified without a live device/store to test against** (noted in-code
|
|
where relevant): `pos-datetime` and `checkout-datetime` both assume
|
|
`process.env.APP_URL` is substituted at build time to the app's backend
|
|
origin, and neither extension's actual runtime behavior has been exercised
|
|
outside of typechecking against `@shopify/ui-extensions`' bundled types
|
|
(which did catch several wrong API-shape guesses during development).
|
|
|
|
Phase 5's Google Maps / geocoding features (pickup-location map in the
|
|
widget, radius-zone eligibility, address auto-geocoding on Save Location)
|
|
are only live if `GOOGLE_MAPS_API_KEY` is set — either as an env var for
|
|
server-side geocoding, or as the "Google Maps API key" block setting in the
|
|
theme editor for the storefront map. Without a key, everything else in
|
|
Phase 5 (postal-code zones, distance-band rates, delivery-density
|
|
thresholds) still works — those don't need Maps at all.
|
|
|
|
The storefront widget's TypeScript source lives in `widget-src/datetime-widget/`,
|
|
**not** inside `extensions/datetime-widget/` — a Theme App Extension's
|
|
directory may only contain `assets`, `blocks`, `snippets`, and `locales`
|
|
(the CLI hard-rejects anything else, e.g. a `src/` folder, with "Only
|
|
assets, blocks, snippets, locales directories are allowed"). Editing the
|
|
widget? Run `npm run build:widget` to bundle it into
|
|
`extensions/datetime-widget/assets/datetime-widget.js` — it also runs
|
|
automatically before `npm run dev` / `npm run deploy`.
|
|
|
|
**Functions are JavaScript, not Rust** (`extensions/validation-slot/`,
|
|
`extensions/delivery-customization/`) — no Rust toolchain was available in
|
|
the environment that built Phase 4, and `IMPLEMENTATION_PLAN.md` §1
|
|
explicitly allows JS as a fallback. Both were generated with
|
|
`shopify app generate extension` (once a real Partner login was available)
|
|
and their business logic (`src/evaluate.js` in each) is verified two ways:
|
|
plain Vitest unit tests at the repo root (`npm test`) and real
|
|
`function-runner` fixture tests that compile actual WASM
|
|
(`npm run test:functions`, also in CI). `extensions/*/generated/` and
|
|
`extensions/*/dist/` aren't committed (matching the CLI's own
|
|
`.gitignore` for these extensions) — `npm run typegen:functions`
|
|
regenerates the types from the committed `schema.graphql`, and building
|
|
runs automatically as part of `npm run dev` / `test:functions`.
|