@prys/seed 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prys
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,94 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @prys/seed
+
+Backfill for the [Prys](https://prys.io) **Customer CRM**: fills in shop details (Shopify plan, country, store age,
+store contacts) for the stores that installed your Shopify app before you added the Prys identify call.
+
+It runs on your side, with your app's own Shopify client. Your access tokens never leave your server; Prys receives
+only the answer to the same shop query as the Customer CRM's step 1 snippet.
+
+```bash
+npx @prys/seed --key=<your Prys key>
+```
+
+Your key is in Prys > Customer CRM > Enrichment (step 1, "Show key").
+
+## What it does
+
+1. Loads `./app/shopify.server` (the Shopify React Router / Remix template's `shopifyApp()` file, `.ts` or `.js`),
+   so your own session storage and token handling are used.
+2. Asks Prys which stores have your app installed (`GET /installs`).
+3. Looks up your app's offline session for each store. Stores without one are skipped; they fill in when the merchant
+   next opens your app (your step 1 call).
+4. Shows the counts and a sample, then asks:
+
+   ```
+     › loading ./app/shopify.server (your own Shopify config)
+     › asking Prys which stores are installed: 8,240
+     › 8,102 have an offline session your app can use
+     › 138 have none yet; they fill in as they open the app
+     › sample: hyperspeed-shop, fable-books, tide-swim
+
+     ? Read these 8,102 with your app's client and send to Prys? (y/N)
+   ```
+
+   **Nothing is read from Shopify or sent to Prys until you answer `y`.** Enter alone means No.
+5. For each store it calls `unauthenticated.admin(shop)`, so your library loads, decrypts and refreshes the token exactly
+   as your app does, runs the step 1 shop query and sends the `data` objects to Prys in batches of 200
+   (`POST /identify/bulk`), printing what Prys received, stored and rejected per batch:
+
+   ```
+     › batch 1: received 200, stored 198, rejected 2 (not_installed 1, dev_store 1)
+   ```
+
+Rejections are normal: `not_installed` (Prys's Partner data shows the store uninstalled), `dev_store` (development
+stores are kept out of the CRM). "Already sent in the last 24 h" means Prys has that store fresh from your step 1 call.
+
+## Where to run it
+
+From your app's project folder, on a machine where your app runs or can reach the same session storage: the same
+environment variables your app needs (`SHOPIFY_API_KEY`, `SHOPIFY_API_SECRET`, `SHOPIFY_APP_URL`, `SCOPES`, your
+database address) and after `npm install`. A `.env` file in the folder is read for any variable that is not already set.
+
+Your `shopify.server` file must export `unauthenticated` and `sessionStorage`, as the template does:
+
+```ts
+export const unauthenticated = shopify.unauthenticated;
+export const sessionStorage = shopify.sessionStorage;
+```
+
+## Options
+
+| Option | |
+|---|---|
+| `--key=<key>` | Your app's Prys key. Or set `PRYS_KEY` (keeps it out of your shell history). |
+| `--base-url=<url>` | Prys API address. Default `https://admin.prys.io/api/v1`. Plain `http://` only for localhost. |
+| `--config=<path>` | Your `shopifyApp()` file, if it is not `./app/shopify.server.{ts,js}`. |
+| `--concurrency=<n>` | Stores read at once, 1 to 20 (default 4). Each store has its own Shopify limit. |
+| `--help`, `--version` | |
+
+Prys allows 600 calls a minute per key; when it answers `rate_limited` the CLI waits as told and sends the same batch
+again. The key is never printed.
+
+## Other frameworks
+
+Node / Express, Laravel, Rails and other backends: Prys > Customer CRM > Enrichment > step 2 shows a short script
+for each, using the same two calls (`GET /installs`, `POST /identify/bulk`).
+
+## Requirements
+
+Node.js 18.18 or newer. TypeScript config files are loaded with [tsx](https://tsx.is) (installed with this package).
+
+## Development
+
+```bash
+npm install
+npm test
+npm run check-query -- <front-end-crm>/app/src/sections/Dashboards/CustomerCrm/Enrichment/snippetTemplates.ts
+```
+
+`npm test` runs the CLI against a stub Prys server and a fake Shopify app (TypeScript and JavaScript
+`shopify.server`). `check-query` fails when the shop query here and the CRM screen's step 1 query drift apart.
+
+## License
+
+MIT

package/bin/prys-seed.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { run } from "../src/cli.js";
+import { redact } from "../src/prys.js";
+
+const argv = process.argv.slice(2);
+const keyArg = argv.find((a) => a.startsWith("--key="))?.slice(6) ?? (argv.includes("--key") ? argv[argv.indexOf("--key") + 1] : "") ?? "";
+const scrub = (text) => [keyArg, process.env.PRYS_KEY].filter((k) => k && k.length > 3).reduce((t, k) => redact(t, k), String(text));
+
+// Exit on its own when nothing is left; the app's own modules (database clients, Redis) may keep the process alive,
+// so a short unref'd timer ends it then. (An immediate process.exit() right after reading a piped stdin can trip a
+// libuv assertion on Windows.)
+function finish(code) {
+  process.exitCode = code;
+  try {
+    process.stdin.destroy();
+  } catch {
+    // stdin already closed
+  }
+  setTimeout(() => process.exit(code), 200).unref();
+}
+
+run(argv).then(finish, (err) => {
+  process.stderr.write(`  ✖ Unexpected failure: ${scrub(err?.message ?? err)}\n`);
+  finish(1);
+});

package/package.json

@@ -1,6 +1,38 @@
-{
-  "name": "@prys/seed",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@prys/seed",
+  "version": "1.0.0",
+  "description": "Backfill Prys Customer CRM: reads your installed stores' shop details with your Shopify app's own client and sends them to Prys.",
+  "keywords": [
+    "prys",
+    "shopify",
+    "shopify-app",
+    "crm",
+    "backfill"
+  ],
+  "homepage": "https://prys.io",
+  "license": "MIT",
+  "author": "Prys <connect@prys.io>",
+  "type": "module",
+  "bin": {
+    "prys-seed": "bin/prys-seed.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "check-query": "node scripts/check-query.js"
+  },
+  "dependencies": {
+    "tsx": "^4.20.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/app.js

@@ -0,0 +1,94 @@
+// Loads the app's own Shopify config (the Shopify React Router / Remix template's app/shopify.server.{ts,js}), so the
+// backfill uses the app's own session storage and token handling: unauthenticated.admin(shop) loads, decrypts and
+// refreshes the offline token exactly as the app does.
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+export const CONFIG_CANDIDATES = [
+  "app/shopify.server.ts",
+  "app/shopify.server.js",
+  "app/shopify.server.mts",
+  "app/shopify.server.mjs",
+  "app/shopify.server.tsx",
+  "app/shopify.server.jsx",
+];
+
+export class AppConfigError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AppConfigError";
+  }
+}
+
+export function findConfig(cwd, explicit) {
+  if (explicit) {
+    const file = path.resolve(cwd, explicit);
+    if (!existsSync(file)) throw new AppConfigError(`--config file not found: ${explicit}`);
+    return file;
+  }
+  for (const candidate of CONFIG_CANDIDATES) {
+    const file = path.join(cwd, candidate);
+    if (existsSync(file)) return file;
+  }
+  throw new AppConfigError(
+    "No app/shopify.server.ts or .js here. Run this from your Shopify app's project folder (React Router / Remix template), " +
+      "or pass --config=<path to the file that calls shopifyApp()>.",
+  );
+}
+
+/** Reads KEY=VALUE lines from .env into process.env without overriding what is already set (the host's values win). */
+export function loadDotEnv(cwd) {
+  const file = path.join(cwd, ".env");
+  if (!existsSync(file)) return false;
+  for (const line of readFileSync(file, "utf8").split(/\r?\n/)) {
+    const m = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/);
+    if (!m || m[1] in process.env) continue;
+    let value = m[2];
+    if (/^(['"]).*\1$/.test(value)) value = value.slice(1, -1);
+    else value = value.replace(/\s+#.*$/, "");
+    process.env[m[1]] = value;
+  }
+  return true;
+}
+
+function pick(mod, name) {
+  return mod?.[name] ?? mod?.default?.[name] ?? mod?.default?.default?.[name];
+}
+
+/** Imports the config (TypeScript through tsx, so extensionless and `~/` imports resolve as in the app) and checks it. */
+export async function loadApp({ cwd = process.cwd(), config } = {}) {
+  const file = findConfig(cwd, config);
+  loadDotEnv(cwd);
+  let mod;
+  try {
+    const { tsImport } = await import("tsx/esm/api");
+    mod = await tsImport(pathToFileURL(file).href, { parentURL: import.meta.url });
+  } catch (err) {
+    throw new AppConfigError(
+      `Could not load ${path.relative(cwd, file) || file}: ${err?.message ?? err}\n` +
+        "  Run it where your app runs (same folder, same environment variables: SHOPIFY_API_KEY, SHOPIFY_API_SECRET, " +
+        "SHOPIFY_APP_URL, SCOPES, your database address), after npm install.",
+    );
+  }
+  const unauthenticated = pick(mod, "unauthenticated");
+  const sessionStorage = pick(mod, "sessionStorage");
+  if (typeof unauthenticated?.admin !== "function") {
+    throw new AppConfigError(`${path.basename(file)} does not export unauthenticated (export const unauthenticated = shopify.unauthenticated;)`);
+  }
+  if (typeof sessionStorage?.loadSession !== "function") {
+    throw new AppConfigError(`${path.basename(file)} does not export sessionStorage (export const sessionStorage = shopify.sessionStorage;)`);
+  }
+  return { file, unauthenticated, sessionStorage };
+}
+
+/** The app's offline session for a shop (Shopify's offline id is `offline_<shop>`), or null. */
+export async function findOfflineSession(sessionStorage, shop) {
+  const session = await sessionStorage.loadSession(`offline_${shop}`);
+  if (session?.accessToken) return session;
+  if (typeof sessionStorage.findSessionsByShop === "function") {
+    const sessions = (await sessionStorage.findSessionsByShop(shop)) ?? [];
+    return sessions.find((s) => s && !s.isOnline && s.accessToken) ?? null;
+  }
+  return null;
+}

package/src/cli.js

@@ -0,0 +1,246 @@
+// npx @prys/seed --key=<your Prys key>
+// Customer CRM, Enrichment step 2 "Backfill existing customers" (React Router / Remix tab). Nothing leaves the server
+// before the person running it answers y.
+import { readFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { AppConfigError, findOfflineSession, loadApp } from "./app.js";
+import { mapLimit, sleep as realSleep } from "./pool.js";
+import { BULK_MAX, DEFAULT_BASE_URL, PrysError, createPrys, redact } from "./prys.js";
+import { readFailure, readShop } from "./read.js";
+
+const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+
+const HELP = `Usage: npx @prys/seed --key=<your Prys key> [options]
+
+Run it from your Shopify app's project folder (React Router / Remix template), where the app runs.
+It asks Prys which stores have your app installed, reads each store's shop details with your app's own
+client (unauthenticated.admin), and, after you answer y, sends them to Prys in batches of ${BULK_MAX}.
+
+Options:
+  --key=<key>          Your app's Prys key (Customer CRM > Enrichment). Or set PRYS_KEY.
+  --base-url=<url>     Prys API address (default ${DEFAULT_BASE_URL}).
+  --config=<path>      Your shopifyApp() file (default ./app/shopify.server.ts or .js).
+  --concurrency=<n>    Stores read at once (default 4, max 20).
+  -h, --help           This text.
+  -v, --version        The version.
+`;
+
+const fmt = (n) => Number(n).toLocaleString("en-US");
+const shortName = (domain) => domain.replace(/\.myshopify\.com$/, "");
+// Prys counts a shop it identified in the last 24 h as sent without writing it again (IN-2): received - stored - rejected.
+const recentNote = (n) => (n > 0 ? `; ${fmt(n)} already sent in the last 24 h` : "");
+const tally = (map, key) => map.set(key, (map.get(key) ?? 0) + 1);
+const listTally = (map) =>
+  [...map.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .map(([k, v]) => `${k} ${fmt(v)}`)
+    .join(", ");
+
+/** One y/N question; anything but y or yes (or a closed input) is No. */
+export function ask(stdin, stdout, question) {
+  return new Promise((resolve) => {
+    stdout.write(question);
+    let buffer = "";
+    const done = (answer) => {
+      stdin.off("data", onData);
+      stdin.off("end", onEnd);
+      if (typeof stdin.pause === "function") stdin.pause();
+      // A terminal echoes the answer and the Enter; a piped answer does not, so end the question's line here.
+      if (!stdin.isTTY) stdout.write(`${answer.trim()}\n`);
+      resolve(/^\s*(y|yes)\s*$/i.test(answer));
+    };
+    const onData = (chunk) => {
+      buffer += chunk.toString();
+      const nl = buffer.indexOf("\n");
+      if (nl >= 0) done(buffer.slice(0, nl));
+    };
+    const onEnd = () => done(buffer);
+    stdin.on("data", onData);
+    stdin.on("end", onEnd);
+    if (typeof stdin.resume === "function") stdin.resume();
+  });
+}
+
+export async function run(argv, io = {}) {
+  const {
+    cwd = process.cwd(),
+    env = process.env,
+    stdin = process.stdin,
+    stdout = process.stdout,
+    stderr = process.stderr,
+    fetchImpl = globalThis.fetch,
+    sleep = realSleep,
+    load = loadApp,
+  } = io;
+  let key = null;
+  const say = (line = "") => stdout.write(`${line ? `  › ${redact(line, key)}` : ""}\n`);
+  const fail = (line) => {
+    stderr.write(`  ✖ ${redact(line, key)}\n`);
+    return 1;
+  };
+
+  let args;
+  try {
+    args = parseArgs({
+      args: argv,
+      options: {
+        key: { type: "string" },
+        "base-url": { type: "string" },
+        config: { type: "string" },
+        concurrency: { type: "string" },
+        help: { type: "boolean", short: "h" },
+        version: { type: "boolean", short: "v" },
+      },
+      strict: true,
+    }).values;
+  } catch (err) {
+    // parseArgs may quote the bad argument; it may hold the key (e.g. -key=...), so never echo it.
+    return fail(`${String(err.message).replace(/'[^']*'/g, "'…'")}\n${HELP}`);
+  }
+  if (args.help) {
+    stdout.write(HELP);
+    return 0;
+  }
+  if (args.version) {
+    stdout.write(`${VERSION}\n`);
+    return 0;
+  }
+  key = (args.key || env.PRYS_KEY || "").trim();
+  if (!key) return fail(`Missing --key (your app's Prys key, from Customer CRM > Enrichment).\n${HELP}`);
+  if (/\s/.test(key)) return fail("--key has a space in it; copy the key again.");
+  const concurrency = args.concurrency === undefined ? 4 : Number(args.concurrency);
+  if (!Number.isInteger(concurrency) || concurrency < 1 || concurrency > 20) return fail("--concurrency must be a whole number from 1 to 20");
+
+  let prys;
+  try {
+    prys = createPrys({
+      baseUrl: args["base-url"] || env.PRYS_BASE_URL || DEFAULT_BASE_URL,
+      key,
+      fetchImpl,
+      sleep,
+      onWait: (seconds, why) => say(`Prys: ${why}; waiting ${fmt(seconds)} s`),
+    });
+  } catch (err) {
+    return fail(err.message);
+  }
+
+  // 1. The app's own Shopify config.
+  let app;
+  try {
+    const shown = args.config ? args.config : "./app/shopify.server";
+    say(`loading ${shown} (your own Shopify config)`);
+    app = await load({ cwd, config: args.config });
+  } catch (err) {
+    return fail(err instanceof AppConfigError ? err.message : `Could not load your Shopify config: ${err?.message ?? err}`);
+  }
+
+  // 2. Which stores Prys sees installed.
+  let installs;
+  try {
+    installs = await prys.installs();
+  } catch (err) {
+    return fail(err instanceof PrysError ? err.message : `Could not ask Prys: ${err?.message ?? err}`);
+  }
+  say(`asking Prys which stores are installed: ${fmt(installs.domains.length)}${prys.base === DEFAULT_BASE_URL ? "" : ` (${prys.base})`}`);
+  if (installs.domains.length === 0) {
+    say("Prys lists no installed stores for this app yet. Nothing to send.");
+    return 0;
+  }
+
+  // 3. Which of them the app holds an offline session for. Nothing is read from Shopify yet.
+  const withSession = [];
+  let lookupErrors = 0;
+  await mapLimit(installs.domains, 10, async (shop) => {
+    try {
+      if (await findOfflineSession(app.sessionStorage, shop)) withSession.push(shop);
+    } catch {
+      lookupErrors++;
+    }
+  });
+  const has = new Set(withSession);
+  const ordered = installs.domains.filter((d) => has.has(d));
+  const without = installs.domains.length - ordered.length;
+  say(`${fmt(ordered.length)} have an offline session your app can use`);
+  if (without > 0) say(`${fmt(without)} have none yet; they fill in as they open the app`);
+  if (lookupErrors > 0) say(`${fmt(lookupErrors)} could not be looked up in your session storage (counted as none)`);
+  if (ordered.length === 0) {
+    say("No store to read. Nothing was sent.");
+    return 0;
+  }
+  say(`sample: ${ordered.slice(0, 3).map(shortName).join(", ")}`);
+  say();
+
+  // 4. The person's yes.
+  const yes = await ask(stdin, stdout, `  ? Read these ${fmt(ordered.length)} with your app's client and send to Prys? (y/N) `);
+  if (!yes) {
+    say("Nothing was read or sent.");
+    return 0;
+  }
+
+  // 5. Read with the app's client, send in batches of 200.
+  const readFailures = new Map();
+  const rejectedReasons = new Map();
+  const totals = { read: 0, received: 0, stored: 0, rejected: 0, batches: 0, sent: 0 };
+  let buffer = [];
+  let chain = Promise.resolve();
+  let fatal = null;
+
+  const send = async (batch) => {
+    const n = ++totals.batches;
+    const r = await prys.identifyBulk(batch);
+    totals.sent++;
+    totals.received += r.received;
+    totals.stored += r.stored;
+    totals.rejected += r.rejected.length;
+    const reasons = new Map();
+    for (const rej of r.rejected) {
+      tally(reasons, rej?.reason ?? "unknown");
+      tally(rejectedReasons, rej?.reason ?? "unknown");
+    }
+    say(
+      `batch ${fmt(n)}: received ${fmt(r.received)}, stored ${fmt(r.stored)}, rejected ${fmt(r.rejected.length)}` +
+        (reasons.size ? ` (${listTally(reasons)})` : "") +
+        recentNote(r.received - r.stored - r.rejected.length),
+    );
+  };
+  const flush = (all) => {
+    while (buffer.length >= BULK_MAX || (all && buffer.length > 0)) {
+      const batch = buffer.splice(0, BULK_MAX);
+      chain = chain.then(() => (fatal ? undefined : send(batch))).catch((err) => {
+        fatal = fatal ?? err;
+      });
+    }
+    return chain;
+  };
+
+  await mapLimit(ordered, concurrency, async (shop) => {
+    if (fatal) return;
+    try {
+      const data = await readShop(app.unauthenticated, shop);
+      totals.read++;
+      buffer.push(data);
+    } catch (err) {
+      tally(readFailures, readFailure(err));
+      return;
+    }
+    await flush(false);
+  });
+  await flush(true);
+
+  const failedReads = [...readFailures.values()].reduce((a, b) => a + b, 0);
+  if (fatal) {
+    say(`stopped after ${fmt(totals.sent)} batch${totals.sent === 1 ? "" : "es"}: Prys received ${fmt(totals.received)}, stored ${fmt(totals.stored)}`);
+    return fail(fatal instanceof PrysError ? fatal.message : `Sending to Prys failed: ${fatal?.message ?? fatal}`);
+  }
+  say();
+  say(`read ${fmt(totals.read)} of ${fmt(ordered.length)} stores` + (failedReads ? `; ${fmt(failedReads)} could not be read (${listTally(readFailures)})` : ""));
+  say(
+    `Prys received ${fmt(totals.received)}, stored ${fmt(totals.stored)}, rejected ${fmt(totals.rejected)}` +
+      (rejectedReasons.size ? ` (${listTally(rejectedReasons)})` : "") +
+      recentNote(totals.received - totals.stored - totals.rejected),
+  );
+  say("done. The Customer CRM fills in as Prys processes them; the rest fill in as merchants open your app.");
+  return 0;
+}
+
+export const helpText = HELP;

package/src/pool.js

@@ -0,0 +1,15 @@
+/** Runs `fn` over `items` with at most `limit` calls at once, keeping the input order in the result. */
+export async function mapLimit(items, limit, fn) {
+  const results = new Array(items.length);
+  let next = 0;
+  const worker = async () => {
+    while (next < items.length) {
+      const i = next++;
+      results[i] = await fn(items[i], i);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, worker));
+  return results;
+}
+
+export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

package/src/prys.js

@@ -0,0 +1,152 @@
+// The Prys public ingest API, as the Customer CRM contract writes it (CONTRACT 3.2):
+//   IN-3  GET  <base>/installs        -> InstallsResult      { count, domains }
+//   IN-2  POST <base>/identify/bulk   BulkIdentifyBody { shops: [...] } (max 200) -> BulkIdentifyResult { received, stored, rejected }
+// Every answer is the Prys API envelope { status, errors, response }; errors is { code: [messages] }.
+// The three routes share 600 calls a minute per key; over it Prys answers 429 `rate_limited` with response.retryAfter (seconds).
+import { sleep as realSleep } from "./pool.js";
+
+export const DEFAULT_BASE_URL = "https://admin.prys.io/api/v1";
+export const BULK_MAX = 200;
+export const CLIENT_NAME = "node";
+
+const LOCAL_HOST = /^(localhost|127\.0\.0\.1|\[::1\]|.+\.localhost|.+\.test)$/i;
+
+export class PrysError extends Error {
+  constructor(message, { status = 0, code = null } = {}) {
+    super(message);
+    this.name = "PrysError";
+    this.status = status;
+    this.code = code;
+  }
+}
+
+/** Checks and normalises --base-url. The key travels in a header, so plain http is allowed only for a local Prys. */
+export function normaliseBaseUrl(raw) {
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new PrysError(`--base-url is not an address: ${raw}`);
+  }
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && LOCAL_HOST.test(url.hostname))) {
+    throw new PrysError(`--base-url must start with https:// (plain http only for localhost): ${url.origin}`);
+  }
+  if (url.search || url.hash) throw new PrysError("--base-url must not carry ? or #");
+  return url.href.replace(/\/+$/, "");
+}
+
+/** Removes the key from any text before it is printed. */
+export function redact(text, key) {
+  if (!key) return String(text);
+  return String(text).split(key).join("***");
+}
+
+function firstError(errors) {
+  if (!errors || typeof errors !== "object") return { code: null, message: null };
+  const code = Object.keys(errors)[0] ?? null;
+  const value = code ? errors[code] : null;
+  const message = Array.isArray(value) ? value[0] : typeof value === "string" ? value : null;
+  return { code, message };
+}
+
+export function createPrys({ baseUrl = DEFAULT_BASE_URL, key, fetchImpl = globalThis.fetch, sleep = realSleep, onWait = () => {} }) {
+  if (!key) throw new PrysError("Missing --key");
+  const base = normaliseBaseUrl(baseUrl);
+
+  async function once(method, path, body) {
+    let res;
+    try {
+      res = await fetchImpl(`${base}${path}`, {
+        method,
+        headers: {
+          Accept: "application/json",
+          Authorization: `Bearer ${key}`,
+          "X-Prys-Client": CLIENT_NAME,
+          ...(body ? { "Content-Type": "application/json" } : {}),
+        },
+        body: body ? JSON.stringify(body) : undefined,
+      });
+    } catch (err) {
+      return { network: true, message: redact(err?.cause?.code || err?.message || "network error", key) };
+    }
+    const text = await res.text();
+    let json = null;
+    try {
+      json = text ? JSON.parse(text) : null;
+    } catch {
+      json = null;
+    }
+    const envelope = json && typeof json === "object" && "response" in json ? json : null;
+    const data = envelope ? envelope.response : json;
+    const { code, message } = firstError(envelope?.errors ?? json?.errors);
+    const headerWait = Number(res.headers.get("retry-after"));
+    const bodyWait = Number(data?.retryAfter);
+    const retryAfter = bodyWait > 0 ? bodyWait : headerWait > 0 ? headerWait : 60;
+    return { status: res.status, data, code, message: message ? redact(message, key) : null, retryAfter };
+  }
+
+  /** One call with the waits the contract asks for: 429 -> wait retryAfter; network error or 5xx (not 503) -> back off. */
+  async function call(method, path, body) {
+    let rateWaits = 0;
+    let failures = 0;
+    for (;;) {
+      const r = await once(method, path, body);
+      if (r.network || (r.status >= 500 && r.status !== 503)) {
+        failures++;
+        if (failures > 3) {
+          throw new PrysError(`Prys did not answer ${method} ${path} (${r.network ? r.message : `HTTP ${r.status}`}). Try again later.`, {
+            status: r.status ?? 0,
+          });
+        }
+        const seconds = 5 * 3 ** (failures - 1);
+        onWait(seconds, r.network ? r.message : `HTTP ${r.status}`);
+        await sleep(seconds * 1000);
+        continue;
+      }
+      if (r.status === 429) {
+        rateWaits++;
+        if (rateWaits > 10) throw new PrysError("Prys kept answering rate_limited. Try again in a few minutes.", { status: 429, code: "rate_limited" });
+        onWait(r.retryAfter, "rate_limited (600 calls a minute per key)");
+        await sleep(r.retryAfter * 1000);
+        continue;
+      }
+      if (r.status === 401) {
+        throw new PrysError("Prys did not accept this key. Copy it again from Customer CRM > Enrichment (it may have been rotated or revoked).", {
+          status: 401,
+          code: r.code ?? "apiKey",
+        });
+      }
+      if (r.status === 503) {
+        throw new PrysError(r.message ?? "Prys is not ready for a backfill of this app yet. Try again later.", { status: 503, code: r.code });
+      }
+      if (r.status < 200 || r.status >= 300) {
+        throw new PrysError(`Prys refused ${method} ${path}: HTTP ${r.status}${r.code ? ` ${r.code}` : ""}${r.message ? ` (${r.message})` : ""}`, {
+          status: r.status,
+          code: r.code,
+        });
+      }
+      return r.data;
+    }
+  }
+
+  return {
+    base,
+    /** IN-3: the app's current installs (myshopify domains). */
+    async installs() {
+      const data = await call("GET", "/installs");
+      if (!data || !Array.isArray(data.domains)) throw new PrysError("Prys answered /installs without a domains list.");
+      const domains = [...new Set(data.domains.filter((d) => typeof d === "string" && d.trim()).map((d) => d.trim().toLowerCase()))];
+      return { count: Number.isFinite(data.count) ? data.count : domains.length, domains };
+    },
+    /** IN-2: up to 200 GraphQL `data` objects. */
+    async identifyBulk(shops) {
+      if (shops.length > BULK_MAX) throw new PrysError(`At most ${BULK_MAX} shops a call`);
+      const data = await call("POST", "/identify/bulk", { shops });
+      return {
+        received: Number(data?.received ?? 0),
+        stored: Number(data?.stored ?? 0),
+        rejected: Array.isArray(data?.rejected) ? data.rejected : [],
+      };
+    },
+  };
+}

package/src/query.js

@@ -0,0 +1,19 @@
+// The Customer CRM step 1 query ("Send the shop object once a day"), field for field. Source of truth: front-end-crm
+// app/src/sections/Dashboards/CustomerCrm/Enrichment/snippetTemplates.ts, `call` step. `npm run check-query -- <that file>`
+// fails when the two drift apart.
+export const SHOP_QUERY = `{
+    shop {
+      id name myshopifyDomain email contactEmail shopOwnerName
+      currencyCode ianaTimezone createdAt
+      plan { publicDisplayName shopifyPlus partnerDevelopment }
+      billingAddress { countryCodeV2 country }
+      primaryDomain { host }
+    }
+    currentAppInstallation {
+      activeSubscriptions {
+        name currentPeriodEnd
+        lineItems { plan { pricingDetails { ... on AppUsagePricing {
+          cappedAmount { amount } balanceUsed { amount } } } } }
+      }
+    }
+  }`;

package/src/read.js

@@ -0,0 +1,37 @@
+import { SHOP_QUERY } from "./query.js";
+
+/** A short, token-free reason for a store the app's client could not read. */
+export function readFailure(err) {
+  const status = err?.response?.code ?? err?.response?.status ?? err?.status;
+  if (status === 401 || status === 403) return `HTTP ${status} (token no longer valid; the store may have uninstalled)`;
+  if (status === 402) return "HTTP 402 (store frozen or unpaid)";
+  if (status === 404) return "HTTP 404 (store not found)";
+  if (status === 423) return "HTTP 423 (store locked)";
+  if (status === 429) return "HTTP 429 (Shopify throttled the store)";
+  if (status) return `HTTP ${status}`;
+  if (err?.name === "SessionNotFoundError") return "no offline session";
+  if (err?.name === "GraphqlQueryError") return "GraphQL error";
+  return err?.name && err.name !== "Error" ? err.name : "could not read";
+}
+
+/** Runs the step 1 query with the app's own client; returns the GraphQL `data` object ({shop, currentAppInstallation}). */
+export async function readShop(unauthenticated, shop) {
+  const { admin } = await unauthenticated.admin(shop);
+  let body;
+  try {
+    const res = await admin.graphql(SHOP_QUERY, { tries: 3 });
+    body = typeof res?.json === "function" ? await res.json() : res;
+  } catch (err) {
+    // GraphqlQueryError carries the partial body; keep it when Shopify still sent the shop.
+    const partial = err?.body?.data;
+    if (partial?.shop) return partial;
+    throw err;
+  }
+  const data = body?.data;
+  if (!data?.shop) {
+    const err = new Error("no shop in the answer");
+    err.name = body?.errors ? "GraphqlQueryError" : "EmptyAnswer";
+    throw err;
+  }
+  return data;
+}