@useairfoil/producer-shopify 0.2.0 → 0.2.2

package/LICENSE.txt

@@ -0,0 +1,201 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+    Copyright 2026 GNC Labs Limited
+
+    Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+    this file except in compliance with the License. You may obtain a copy of the
+    License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software distributed
+    under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+    CONDITIONS OF ANY KIND, either express or implied. See the License for the
+    specific language governing permissions and limitations under the License.

package/README.md

@@ -1,255 +1,92 @@
-# @useairfoil/producer-shopify
-
-Shopify producer connector for Airfoil Connector Kit.
-
-Current scope:
-
-- entity: `products`
-- event: `cart_events`
-- backfill source: Shopify Admin GraphQL `products` query
-- live source: Shopify webhooks on `/webhooks/shopify`
-
-## Public Exports
-
-- `ShopifyApiClient`
-- `ShopifyConnector`
-- `CartEvent`
-- `CartEventSchema`
-- `CartLineItem`
-- `CartLineItemSchema`
-- `CartWebhookPayload`
-- `CartWebhookPayloadSchema`
-- `Money`
-- `MoneyBag`
-- `MoneyBagSchema`
-- `MoneySchema`
-- `PageInfo`
-- `PageInfoSchema`
-- `Product`
-- `ProductDeleteWebhookPayload`
-- `ProductDeleteWebhookPayloadSchema`
-- `ProductOption`
-- `ProductOptionSchema`
-- `ProductWebhookPayload`
-- `ProductWebhookPayloadSchema`
-- `ProductSchema`
-- `ProductStatus`
-- `ProductStatusSchema`
-- `ProductVariant`
-- `ProductVariantInventoryPolicy`
-- `ProductVariantInventoryPolicySchema`
-- `ProductVariantSchema`
-- `ShopifyNormalize`
-- `WebhookPayload`
-- `WebhookPayloadSchema`
-- manifest subpath: `@useairfoil/producer-shopify/manifest` exports browser-safe connector metadata
-
-Connector config and runtime types are exported from the `ShopifyConnector` namespace.
-
-## Configuration
-
-The sandbox reads connector values from the environment:
-
-```env
-SHOPIFY_SHOP_DOMAIN=your-store.myshopify.com
-SHOPIFY_CLIENT_ID=your-dev-dashboard-app-client-id
-SHOPIFY_CLIENT_SECRET=your-dev-dashboard-app-client-secret
-SHOPIFY_WEBHOOK_SECRET=your-webhook-signing-value
-```
-
-Hosted `start` requires a read-only connector JSON file selected by `AIRFOIL_CONFIG_PATH`; matching environment values override file values per key. The file includes manifest runtime keys such as `SHOPIFY_SHOP_DOMAIN`, `SHOPIFY_CLIENT_ID`, `SHOPIFY_CLIENT_SECRET`, `SHOPIFY_API_VERSION`, and `SHOPIFY_WEBHOOK_SECRET`.
-
-`SHOPIFY_WEBHOOK_SECRET` is the signing value Shopify shows when the merchant creates a webhook under Shopify Admin → Settings → Notifications → Webhooks. It is separate from `SHOPIFY_CLIENT_SECRET`.
-
-Common sandbox/runtime values:
-
-```env
-SHOPIFY_API_VERSION=2026-07
-# SHOPIFY_RESPONSE_MAX_RETRIES=5
-# SHOPIFY_TRANSPORT_MAX_RETRIES=5
-# SHOPIFY_GRAPHQL_MAX_RETRIES=5
-# SHOPIFY_RETRY_BASE_DELAY_MS=200
-# SHOPIFY_GRAPHQL_RETRY_BASE_DELAY_MS=500
-# SHOPIFY_RETRY_AFTER_FALLBACK_SECONDS=1
-# SHOPIFY_REQUEST_TIMEOUT_SECONDS=120
-AIRFOIL_HTTP_PORT=8080
-OTEL_ENABLED=false
-OTEL_SERVICE_NAME=producer-shopify
-# OTEL_SERVICE_VERSION=0.1.0
-# OTEL_RESOURCE_ATTRIBUTES=service.instance.id=team-acme-shopify-primary,airfoil.connector.revision=1,airfoil.team.id=team-acme
-OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
-# OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer <token>,X-Axiom-Dataset=<dataset>
-```
-
-These optional API policy values are loaded with the connector config. Shopify's reported query cost, available budget, restore rate, and `Retry-After` remain authoritative.
-
-Production `start` also requires platform-owned Wings, table, and PostgreSQL state config:
-
-```env
-WINGS_HOST=localhost:7777
-WINGS_NAMESPACE=namespaces/default
-AIRFOIL_TABLE_BINDINGS={"products":"namespaces/default/tables/shopify-products","cart_events":"namespaces/default/tables/shopify-cart-events"}
-AIRFOIL_CONFIG_PATH=/var/run/airfoil/config/config.json
-AIRFOIL_CONNECTOR_INSTANCE_ID=team-acme-shopify-primary
-# AIRFOIL_STATE_TABLE=_airfoil_connectors_state
-POSTGRES_CONNECTION_STRING=postgresql://...
-```
-
-The sandbox uses `Telemetry.layerOtlp(...)` and `Telemetry.layerMetricsConsoleDump()` from Connector Kit. Connector Kit reads `OTEL_ENABLED`, `OTEL_EXPORTER_OTLP_ENDPOINT`, and `OTEL_EXPORTER_OTLP_HEADERS` for OTLP trace/metric export. Effect reads `OTEL_SERVICE_NAME`, `OTEL_SERVICE_VERSION`, and `OTEL_RESOURCE_ATTRIBUTES` for resource metadata. HTTP runtimes expose shallow process health at `GET /health`, metrics at `GET /metrics`, and durable progress or source errors at `GET /status`.
-
-The current product backfill requires `read_products`. Add more Admin API scopes to the app when more resources are enabled.
-
-### Getting Shopify credentials
-
-The merchant follows Shopify's [client-credentials setup](https://shopify.dev/docs/apps/build/dev-dashboard/get-api-access-tokens?lang=node): create a Dev Dashboard app in the same Shopify organization as the store, enable the required Admin API scopes, install it on the store, and give Airfoil:
-
-- the store's `*.myshopify.com` domain
-- the app client ID
-- the app client secret
-
-The connector exchanges those credentials at `/admin/oauth/access_token`. Shopify access tokens normally last 24 hours. The connector keeps the token only in memory and lazily exchanges again after half of the reported lifetime. Pod restarts simply exchange on the first API request. Do not store access tokens in `StateStore` or commit either credential.
-
-Store webhooks remain manual. The merchant creates each required topic in Shopify Admin, points it to the connector's public `/webhooks/shopify` URL, and provides the generated signing value as `SHOPIFY_WEBHOOK_SECRET`.
-
-## ConnectorApp Entrypoint
-
-This connector exposes a single CLI entrypoint in `src/main.ts`:
-
-```bash
-pnpm --filter @useairfoil/producer-shopify run sandbox
-pnpm --filter @useairfoil/producer-shopify run start
-```
-
-`sandbox` runs the real connector with `Publisher.layerConsole`. `start` passes the configured Wings table names to `Publisher.layerWings`.
-
-The CLI assembly lives in `src/main.ts`; production runtime wiring lives in `src/start.ts`; sandbox runtime wiring lives in `src/sandbox.ts`. Port and table bindings use Connector Kit's shared platform keys.
-
-Before provisioning, the dashboard backend passes `ShopifyConnector.ShopifyConnector` and `ShopifyConnector.layerConfig(ShopifyConnector.ShopifyConfigDef.config)` to `ConnectorApp.check(...)`. `products` requests one product ID only, while webhook-only `cart_events` uses a minimal shop identity query that does not require product access.
-
-## Production Image
-
-The build emits a separate `dist/main.js` CLI while keeping it outside the package exports. Build and smoke-test the non-root Node 24 image through Nx:
-
-```bash
-pnpm nx run @useairfoil/producer-shopify:docker:build
-docker run --rm airfoil/producer-shopify:local --help
-```
-
-The image runs `node dist/main.js start`, exposes port `8080`, and contains only the pruned production package. Mount the complete connector JSON file read-only at the path supplied by `AIRFOIL_CONFIG_PATH`; inject the platform-owned values listed above separately. Never bake `.env`, API tokens, webhook secrets, or database credentials into the image. The operator owns Kubernetes readiness and liveness probes against `/health`.
-
-## Minimal ConnectorApp Wiring
-
-The following is local/example wiring. Hosted production uses `RuntimeConfig.layerHosted()`, `StateStore.layerSql()` over `PgClient`, and the Wings publisher as shown by `src/start.ts`; it must not fall back to memory state.
-
-```ts
-import { Publisher, ConnectorApp, StateStore, Telemetry } from "@useairfoil/connector-kit";
-import { Effect, Layer } from "effect";
-import { FetchHttpClient } from "effect/unstable/http";
-
-import { ShopifyConnector } from "@useairfoil/producer-shopify";
-
-const BootstrapLayer = FetchHttpClient.layer;
-
-const ConnectorLayer = ShopifyConnector.layerConfig(ShopifyConnector.ShopifyConfigDef.config).pipe(
-  Layer.provide(BootstrapLayer),
-);
-const TelemetryLayer = Telemetry.layerOtlp({
-  redactedHeaders: ["x-shopify-access-token"],
-}).pipe(Layer.provide(BootstrapLayer));
-
-const program = Effect.gen(function* () {
-  const connector = yield* ShopifyConnector.ShopifyConnector;
-  return yield* ConnectorApp.start(connector, { port: 8080 });
-});
-
-const RuntimeLayer = Layer.mergeAll(
-  StateStore.layerMemory,
-  Publisher.layerConsole,
-  ConnectorLayer,
-  TelemetryLayer,
-);
-
-const runnable = Effect.scoped(program).pipe(Effect.provide(RuntimeLayer));
-
-Effect.runPromise(runnable);
-```
-
-## Webhook Behavior
-
-- webhook path: `POST /webhooks/shopify`
-- expected topic headers include `products/create`, `products/update`, `products/delete`, `carts/create`, and `carts/update`
-- `SHOPIFY_WEBHOOK_SECRET` is required and every request verifies `x-shopify-hmac-sha256` against the raw request body
-- `products/create` and `products/update` publish directly when the webhook contains every variant and its creation time
-- Shopify only includes full details for the first 100 variants; when `variant_gids` shows truncation, or `created_at` is missing, the handler refetches the complete product over GraphQL before publishing
-- product rows expose nested variants as `variants`; backfill and webhook upserts keep this list complete
-- signed `products/delete` webhooks convert Shopify's numeric product ID to a GraphQL product GID and publish a delete mutation using `X-Shopify-Triggered-At` as the version
-- product webhook decoding is strict for the fields required to normalize product rows; if you use Shopify `include_fields`, include the product fields required by `ProductWebhookPayloadSchema`
-- cart webhooks are normalized into the `cart_events` event stream using the documented cart payload fields
-- product upserts are versioned by `updatedAt`; product deletes use `X-Shopify-Triggered-At`
-
-## API Client Layer
-
-`ShopifyApiClient.layer(config)` builds `ShopifyApiClient.ShopifyApiClient` from a raw `ShopifyConfig` value.
-
-The client:
-
-- lazily exchanges the configured client credentials for an access token
-- caches the token in memory until half its reported lifetime
-- authenticates GraphQL calls with `X-Shopify-Access-Token`
-- posts GraphQL operations to `/admin/api/<version>/graphql.json`
-- sends `Accept: application/json` and `Content-Type: application/json`
-- follows product and nested variant pagination through `pageInfo.endCursor`
-
-Use `ShopifyConnector.layer(...)` or `ShopifyConnector.layerConfig(...)` for complete runtime wiring. `ShopifyApiClient.layer(...)` is the lower-level connector-internal layer and also requires `ShopifyAuth`.
-
-## Notes
-
-- the connector uses Shopify Admin GraphQL
-- the API version is pinned through `SHOPIFY_API_VERSION`
-- product backfill paginates both products and their nested variants
-- product row output is GraphQL-native camelCase; Shopify webhook payloads are normalized before publishing
-
-## Testing
-
-- `test/api.vcr.test.ts`: VCR product response and mocked nested-variant pagination
-- `test/auth.test.ts`: client-credentials exchange, safe errors, and request authentication
-- `test/check.test.ts`: selected read-only resource checks
-- `test/rate-limit.test.ts`: HTTP, transport, and GraphQL retry behavior
-- `test/webhook.test.ts`: in-memory webhook flow with HMAC verification
-
-Run:
-
-```bash
-pnpm --filter @useairfoil/producer-shopify run test:ci
-```
-
-To record the API cassette, put real Shopify values in the connector `.env` and run:
-
-```bash
-pnpm --filter @useairfoil/producer-shopify exec dotenvx run \
-  --ignore=MISSING_ENV_FILE \
-  --quiet \
-  -- vitest run test/api.vcr.test.ts
-```
-
-The VCR's auto mode records requests missing from the cassette. Do not set `ACK_DISABLE_VCR`, because that bypasses recording. Token request credentials and response access tokens are replaced with fixed placeholders automatically. Shopify cookies and GraphQL `X-Shopify-Access-Token` headers are removed before the cassette is written.
-
-## Sandbox Tracing
-
-Set `OTEL_ENABLED=true` to export traces and metrics from the sandbox. Metrics are also logged locally by `Telemetry.layerMetricsConsoleDump()`.
-
-The sandbox uses `Telemetry.layerOtlp({ redactedHeaders: ["x-shopify-access-token"] })` so Shopify access tokens are redacted in addition to Connector Kit defaults. See `@useairfoil/connector-kit` for the full telemetry env var list, metric names, and redaction defaults.
-
-For local Jaeger with persistent storage, start it from the traceview package:
+# Shopify producer
+
+This connector backfills Shopify products, customers, orders, and refunds. It
+gets product, cart, customer, order, and refund events at
+`POST /webhooks/shopify`.
+
+## Config
+
+| Variable                 | Required | Default |
+| ------------------------ | -------- | ------- |
+| `SHOPIFY_SHOP_DOMAIN`    | yes      | none    |
+| `SHOPIFY_CLIENT_ID`      | yes      | none    |
+| `SHOPIFY_CLIENT_SECRET`  | yes      | none    |
+| `SHOPIFY_WEBHOOK_SECRET` | yes      | none    |
+
+Use a Shopify app owned by the merchant. The app needs `read_products`,
+`read_customers`, and `read_orders`. Without `read_all_orders`, Shopify returns
+only the last 60 days of orders and their refunds. The webhook secret is not the
+app client secret.
+
+## Setup
+
+Create a [Dev Dashboard app](https://shopify.dev/docs/apps/build/dev-dashboard/get-api-access-tokens?lang=node)
+in the same Shopify organization as the store. Add the scopes above, install the
+app, and use its client ID and client secret.
+
+Request protected customer data access for name, email, phone, and address. The
+config check fails without it.
+
+Create these webhooks in Shopify Admin:
+
+- `products/create`
+- `products/update`
+- `products/delete`
+- `carts/create`
+- `carts/update`
+- `customers/create`
+- `customers/disable`
+- `customers/enable`
+- `customers/update`
+- `customers/delete`
+- `customers/purchasing_summary`
+- `customers_email_marketing_consent/update`
+- `customers_marketing_consent/update`
+- `customer.tags_added`
+- `customer.tags_removed`
+- `orders/create`
+- `orders/updated`
+- `orders/delete`
+- `refunds/create`
+
+Point them to `/webhooks/shopify` and use the webhook signing value as
+`SHOPIFY_WEBHOOK_SECRET`. Pick webhook API version `2026-07`, the one the
+connector uses.
+
+## Data
+
+- Customers, orders, and refunds hold protected customer data such as names,
+  emails, phones, addresses, and notes. Treat these tables as customer data.
+- Current order totals include refunds.
+- Order webhooks are mapped without refetching. If Shopify truncates line items
+  on a very large order, the webhook row can miss lines.
+- A refund row does not mean the payment completed. Check its transaction
+  status.
+- Refunds use `processedAt` for versions. A later settlement can be missed if
+  Shopify keeps the same time.
+- After backfill, updates depend on webhooks. Missed webhook deliveries are not
+  recovered yet.
+
+## Demo data
+
+`pnpm demo --size 128MiB` writes made-up Shopify data without Shopify
+credentials. See the Connector Kit README for the flags and the variables it
+needs.
+
+Each customer has orders, refunds, and sometimes an open cart. Orders and carts
+use a fixed catalog of 10 products, which doesn't grow with the size.
+
+## Local development
 
 ```bash
-pnpm --filter @useairfoil/traceview run jaeger:up
+cd connectors/producer-shopify
+pnpm sandbox
 ```
 
-Then set `OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318` and run the sandbox. After triggering a webhook or backfill, render the trace:
+A hosted run loads connector config from `AIRFOIL_CONFIG_PATH`. It also needs
+the Wings and PostgreSQL variables from the Connector Kit README.
 
 ```bash
-traceview <trace-id> --source jaeger
-# or for Axiom:
-traceview <trace-id> --source axiom
+cd connectors/producer-shopify
+pnpm start
 ```