@objectsws/s-portal 0.1.0

package/dist/index.js

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { detectShopifyApp } from "./detect.js";
+import { discardLocalFiles, readEnvKeys } from "./discard.js";
+import { promptConfirmApp, promptConfirmDiscard, promptCredentials, promptRemoteBaseUrl, } from "./prompts.js";
+import { cliConnect, cliDisconnect, cliWhoami } from "./portalApi.js";
+import { mergeEnvFile, scaffoldPortalFiles } from "./scaffold.js";
+import { normalizeBaseUrl } from "./utils.js";
+const program = new Command();
+program
+    .name("s-portal")
+    .description("Scaffold Apps Portal sync into a Shopify Remix app and register Remote Base URL");
+program
+    .command("connect", { isDefault: true })
+    .description("Scaffold portal files and register Remote Base URL (default)")
+    .option("--portal-url <url>", "Apps Portal base URL")
+    .option("--client-id <id>", "Portal Client Id (portal-{handle})")
+    .option("--client-secret <secret>", "Portal Client Secret")
+    .option("--remote-base-url <url>", "Your deployed Shopify app origin")
+    .option("--force", "Overwrite existing scaffold files without prompting", false)
+    .option("--yes", "Skip interactive confirmations when flags provide values", false)
+    .option("--scaffold-only", "Only scaffold files; do not call portal APIs", false)
+    .action(async (opts) => {
+    try {
+        await runConnect(opts);
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        console.error(`\nError: ${msg}\n`);
+        process.exit(1);
+    }
+});
+program
+    .command("discard")
+    .description("Remove CLI-scaffolded files, strip PORTAL_* from .env, and soft-disconnect from portal")
+    .option("--portal-url <url>", "Apps Portal base URL")
+    .option("--client-id <id>", "Portal Client Id (portal-{handle})")
+    .option("--client-secret <secret>", "Portal Client Secret")
+    .option("--yes", "Skip interactive confirmation", false)
+    .option("--local-only", "Only remove local files; do not call portal APIs", false)
+    .option("--force", "Delete scaffold files even if modified from the original template", false)
+    .action(async (opts) => {
+    try {
+        await runDiscard(opts);
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        console.error(`\nError: ${msg}\n`);
+        process.exit(1);
+    }
+});
+async function runConnect(opts) {
+    console.log("\n@objects/s-portal — Apps Portal connect\n");
+    const detected = detectShopifyApp(process.cwd());
+    console.log(`Detected app root: ${detected.root}`);
+    if (detected.packageName)
+        console.log(`Package: ${detected.packageName}`);
+    const scaffold = await scaffoldPortalFiles(detected.root, { force: opts.force });
+    if (scaffold.written.length) {
+        console.log("\nScaffolded:");
+        for (const f of scaffold.written)
+            console.log(`  + ${f}`);
+    }
+    if (scaffold.skipped.length) {
+        console.log("\nSkipped:");
+        for (const f of scaffold.skipped)
+            console.log(`  · ${f}`);
+    }
+    console.log(`\n${scaffold.entryServerHint}`);
+    if (opts.scaffoldOnly) {
+        console.log("\nScaffold-only mode — done.\n");
+        return;
+    }
+    let portalUrl = opts.portalUrl?.trim();
+    let clientId = opts.clientId?.trim();
+    let clientSecret = opts.clientSecret?.trim();
+    if (!portalUrl || !clientId || !clientSecret) {
+        const prompted = await promptCredentials({ portalUrl, clientId });
+        portalUrl = prompted.portalUrl;
+        clientId = prompted.clientId;
+        clientSecret = prompted.clientSecret;
+    }
+    portalUrl = normalizeBaseUrl(portalUrl);
+    console.log("\nLooking up app on portal…");
+    const whoami = await cliWhoami({ portalUrl, clientId, clientSecret });
+    if (!whoami.ok || !whoami.app) {
+        throw new Error(whoami.error ?? "whoami failed — check Client Id / Secret / Portal URL");
+    }
+    console.log(`\nApp: ${whoami.app.name}`);
+    console.log(`Handle: ${whoami.app.handle}`);
+    console.log(`App Id: ${whoami.app.id}`);
+    if (!opts.yes) {
+        const ok = await promptConfirmApp(whoami.app);
+        if (!ok) {
+            console.log("\nEnd Session — connection cancelled.\n");
+            process.exit(0);
+        }
+    }
+    let remoteBaseUrl = opts.remoteBaseUrl?.trim();
+    if (!remoteBaseUrl) {
+        remoteBaseUrl = await promptRemoteBaseUrl(whoami.connection?.syncBaseUrl ?? undefined);
+    }
+    remoteBaseUrl = normalizeBaseUrl(remoteBaseUrl);
+    const activeCheckUrl = `${remoteBaseUrl}/healthz`;
+    console.log(`Active Check URL: ${activeCheckUrl}`);
+    console.log("\nRegistering with sync engine…");
+    const connected = await cliConnect({
+        portalUrl,
+        clientId,
+        clientSecret,
+        remoteBaseUrl,
+        activeCheckUrl,
+    });
+    if (!connected.ok || !connected.portal) {
+        throw new Error(connected.error ?? "connect failed");
+    }
+    const env = mergeEnvFile(detected.root, {
+        PORTAL_HEARTBEAT_URL: connected.portal.heartbeatUrl,
+        PORTAL_WEBHOOK_URL: connected.portal.webhookUrl,
+        PORTAL_CLIENT_ID: clientId,
+        PORTAL_CLIENT_SECRET: clientSecret,
+        HEARTBEAT_INTERVAL_MS: "60000",
+    });
+    console.log("\nConnected.");
+    console.log(`  syncBaseUrl:     ${connected.syncBaseUrl}`);
+    console.log(`  activeCheckUrl:  ${connected.activeCheckUrl}`);
+    console.log(`  token verified:  ${connected.verified ? "yes" : `no (${connected.verifyError ?? "unreachable"})`}`);
+    console.log(`  env updated:     ${env.path} (${env.updated.join(", ")})`);
+    console.log(`
+Next steps:
+  1. Deploy your app so ${remoteBaseUrl} is reachable.
+  2. Wire portal/notify.server.ts into your Shopify webhook handlers.
+  3. Implement the merchants query TODO in app/routes/api.portal-sync.tsx (id + shop required).
+  4. In the portal, Verify connection / Manual sync.
+`);
+}
+async function runDiscard(opts) {
+    console.log("\n@objects/s-portal — Apps Portal discard\n");
+    const detected = detectShopifyApp(process.cwd());
+    console.log(`Detected app root: ${detected.root}`);
+    if (detected.packageName)
+        console.log(`Package: ${detected.packageName}`);
+    if (!opts.yes) {
+        const ok = await promptConfirmDiscard();
+        if (!ok) {
+            console.log("\nCancelled — nothing discarded.\n");
+            process.exit(0);
+        }
+    }
+    // Soft-disconnect on portal when possible
+    let portalDisconnected = false;
+    let portalWarning = null;
+    if (opts.localOnly) {
+        portalWarning = "Skipped portal disconnect (--local-only).";
+    }
+    else {
+        const fromEnv = readEnvKeys(detected.root, [
+            "PORTAL_HEARTBEAT_URL",
+            "PORTAL_CLIENT_ID",
+            "PORTAL_CLIENT_SECRET",
+        ]);
+        let portalUrl = opts.portalUrl?.trim() ||
+            (fromEnv.PORTAL_HEARTBEAT_URL
+                ? derivePortalOrigin(fromEnv.PORTAL_HEARTBEAT_URL)
+                : undefined);
+        let clientId = opts.clientId?.trim() || fromEnv.PORTAL_CLIENT_ID;
+        let clientSecret = opts.clientSecret?.trim() || fromEnv.PORTAL_CLIENT_SECRET;
+        if ((!portalUrl || !clientId || !clientSecret) && !opts.yes) {
+            const prompted = await promptCredentials({ portalUrl, clientId });
+            portalUrl = prompted.portalUrl;
+            clientId = prompted.clientId;
+            clientSecret = prompted.clientSecret;
+        }
+        if (portalUrl && clientId && clientSecret) {
+            portalUrl = normalizeBaseUrl(portalUrl);
+            console.log("\nSoft-disconnecting from portal…");
+            try {
+                const result = await cliDisconnect({
+                    portalUrl,
+                    clientId,
+                    clientSecret,
+                });
+                if (!result.ok || !result.disconnected) {
+                    portalWarning = result.error ?? "Portal disconnect failed";
+                }
+                else {
+                    portalDisconnected = true;
+                    console.log(`  Disconnected app ${result.appId}`);
+                }
+            }
+            catch (error) {
+                portalWarning =
+                    error instanceof Error ? error.message : "Portal disconnect failed";
+            }
+        }
+        else {
+            portalWarning =
+                "Missing credentials — local files will still be removed; portal disconnect skipped.";
+        }
+    }
+    console.log("\nRemoving local scaffold…");
+    const local = discardLocalFiles(detected.root, { force: opts.force });
+    if (local.removed.length) {
+        console.log("Removed:");
+        for (const f of local.removed)
+            console.log(`  − ${f}`);
+    }
+    if (local.skipped.length) {
+        console.log("Skipped:");
+        for (const f of local.skipped)
+            console.log(`  · ${f}`);
+    }
+    if (local.envStripped.length) {
+        console.log(`Env stripped: ${local.envStripped.join(", ")}`);
+    }
+    if (local.entryHint) {
+        console.log(`Note: ${local.entryHint}`);
+    }
+    console.log("\nDiscarded.");
+    console.log(`  portal disconnect: ${portalDisconnected ? "yes (soft — credentials kept)" : "no"}`);
+    if (portalWarning) {
+        console.log(`  warning: ${portalWarning}`);
+    }
+    console.log("");
+}
+/** Derive portal origin from PORTAL_HEARTBEAT_URL like https://x/api/monitor/heartbeat */
+function derivePortalOrigin(heartbeatUrl) {
+    try {
+        const u = new URL(heartbeatUrl);
+        return `${u.protocol}//${u.host}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+program.parseAsync(process.argv);

package/dist/portalApi.d.ts

@@ -0,0 +1,50 @@
+export type WhoamiResponse = {
+    ok: boolean;
+    error?: string;
+    app?: {
+        id: string;
+        name: string;
+        handle: string;
+    };
+    clientId?: string;
+    connection?: {
+        syncBaseUrl: string | null;
+        isEnabled: boolean;
+    };
+};
+export type ConnectResponse = {
+    ok: boolean;
+    error?: string;
+    appId?: string;
+    syncBaseUrl?: string;
+    activeCheckUrl?: string;
+    verified?: boolean;
+    verifyError?: string;
+    portal?: {
+        heartbeatUrl: string;
+        webhookUrl: string;
+    };
+};
+export type DisconnectResponse = {
+    ok: boolean;
+    error?: string;
+    appId?: string;
+    disconnected?: boolean;
+};
+export declare function cliWhoami(input: {
+    portalUrl: string;
+    clientId: string;
+    clientSecret: string;
+}): Promise<WhoamiResponse>;
+export declare function cliConnect(input: {
+    portalUrl: string;
+    clientId: string;
+    clientSecret: string;
+    remoteBaseUrl: string;
+    activeCheckUrl: string;
+}): Promise<ConnectResponse>;
+export declare function cliDisconnect(input: {
+    portalUrl: string;
+    clientId: string;
+    clientSecret: string;
+}): Promise<DisconnectResponse>;

package/dist/portalApi.js

@@ -0,0 +1,41 @@
+import { normalizeBaseUrl, portalAuthHeaders } from "./utils.js";
+export async function cliWhoami(input) {
+    const base = normalizeBaseUrl(input.portalUrl);
+    const rawBody = "";
+    const headers = portalAuthHeaders(input.clientId, input.clientSecret, rawBody);
+    const res = await fetch(`${base}/api/cli/whoami`, {
+        method: "GET",
+        headers,
+        signal: AbortSignal.timeout(15_000),
+    });
+    return (await res.json());
+}
+export async function cliConnect(input) {
+    const base = normalizeBaseUrl(input.portalUrl);
+    const body = JSON.stringify({
+        remoteBaseUrl: normalizeBaseUrl(input.remoteBaseUrl),
+        activeCheckUrl: normalizeBaseUrl(input.activeCheckUrl),
+        enableSync: true,
+        enableActiveCheck: true,
+    });
+    const headers = portalAuthHeaders(input.clientId, input.clientSecret, body);
+    const res = await fetch(`${base}/api/cli/connect`, {
+        method: "POST",
+        headers,
+        body,
+        signal: AbortSignal.timeout(20_000),
+    });
+    return (await res.json());
+}
+export async function cliDisconnect(input) {
+    const base = normalizeBaseUrl(input.portalUrl);
+    const body = "{}";
+    const headers = portalAuthHeaders(input.clientId, input.clientSecret, body);
+    const res = await fetch(`${base}/api/cli/disconnect`, {
+        method: "POST",
+        headers,
+        body,
+        signal: AbortSignal.timeout(15_000),
+    });
+    return (await res.json());
+}

package/dist/prompts.d.ts

@@ -0,0 +1,19 @@
+export type InteractiveAnswers = {
+    portalUrl: string;
+    clientId: string;
+    clientSecret: string;
+    confirmApp: boolean;
+    remoteBaseUrl: string;
+};
+export declare function promptCredentials(defaults?: {
+    portalUrl?: string;
+    clientId?: string;
+}): Promise<Pick<InteractiveAnswers, "portalUrl" | "clientId" | "clientSecret">>;
+export declare function promptConfirmApp(app: {
+    name: string;
+    id: string;
+    handle: string;
+}): Promise<boolean>;
+export declare function promptRemoteBaseUrl(initial?: string): Promise<string>;
+export declare function promptOverwrite(fileRel: string): Promise<boolean>;
+export declare function promptConfirmDiscard(): Promise<boolean>;

package/dist/prompts.js

@@ -0,0 +1,87 @@
+import prompts from "prompts";
+export async function promptCredentials(defaults) {
+    const res = await prompts([
+        {
+            type: "text",
+            name: "portalUrl",
+            message: "Portal base URL",
+            initial: defaults?.portalUrl ?? "https://",
+            validate: (v) => {
+                try {
+                    const u = new URL(v);
+                    return u.protocol === "http:" || u.protocol === "https:"
+                        ? true
+                        : "Must be http(s) URL";
+                }
+                catch {
+                    return "Must be a valid URL";
+                }
+            },
+        },
+        {
+            type: "text",
+            name: "clientId",
+            message: "Client Id (from portal credentials)",
+            initial: defaults?.clientId ?? "portal-",
+            validate: (v) => (v.trim() ? true : "Required"),
+        },
+        {
+            type: "password",
+            name: "clientSecret",
+            message: "Client Secret (shown once when generated in portal)",
+            validate: (v) => (v.trim() ? true : "Required"),
+        },
+    ], { onCancel: () => process.exit(1) });
+    return {
+        portalUrl: String(res.portalUrl).trim(),
+        clientId: String(res.clientId).trim(),
+        clientSecret: String(res.clientSecret).trim(),
+    };
+}
+export async function promptConfirmApp(app) {
+    const res = await prompts({
+        type: "confirm",
+        name: "ok",
+        message: `Connect to Shopify app "${app.name}" (${app.handle})?\n  App Id: ${app.id}`,
+        initial: true,
+    }, { onCancel: () => process.exit(1) });
+    return Boolean(res.ok);
+}
+export async function promptRemoteBaseUrl(initial) {
+    const res = await prompts({
+        type: "text",
+        name: "remoteBaseUrl",
+        message: "Remote Base URL (your deployed Shopify app origin)",
+        initial: initial ?? "https://",
+        validate: (v) => {
+            try {
+                const u = new URL(v);
+                return u.protocol === "http:" || u.protocol === "https:"
+                    ? true
+                    : "Must be http(s) URL";
+            }
+            catch {
+                return "Must be a valid URL";
+            }
+        },
+    }, { onCancel: () => process.exit(1) });
+    return String(res.remoteBaseUrl).trim();
+}
+export async function promptOverwrite(fileRel) {
+    const res = await prompts({
+        type: "confirm",
+        name: "ok",
+        message: `${fileRel} already exists. Overwrite?`,
+        initial: false,
+    }, { onCancel: () => process.exit(1) });
+    return Boolean(res.ok);
+}
+export async function promptConfirmDiscard() {
+    const res = await prompts({
+        type: "confirm",
+        name: "ok",
+        message: "Discard portal scaffold and soft-disconnect from the portal? (credentials are kept)",
+        initial: false,
+    }, { onCancel: () => process.exit(1) });
+    return Boolean(res.ok);
+}

package/dist/scaffold.d.ts

@@ -0,0 +1,15 @@
+export type ScaffoldResult = {
+    written: string[];
+    skipped: string[];
+    entryServerHint: string;
+};
+/**
+ * Hybrid scaffold: portal/ helpers + thin Remix route stubs.
+ */
+export declare function scaffoldPortalFiles(appRoot: string, opts?: {
+    force?: boolean;
+}): Promise<ScaffoldResult>;
+export declare function mergeEnvFile(appRoot: string, vars: Record<string, string>): {
+    path: string;
+    updated: string[];
+};

package/dist/scaffold.js

@@ -0,0 +1,100 @@
+import fs from "node:fs";
+import path from "node:path";
+import { SCAFFOLD_OWNED_FILES } from "./discard.js";
+import { promptOverwrite } from "./prompts.js";
+import { readTemplate } from "./utils.js";
+async function writeFileSafe(absPath, content, rel, force) {
+    const exists = fs.existsSync(absPath);
+    if (exists && !force) {
+        const ok = await promptOverwrite(rel);
+        if (!ok)
+            return "skipped";
+    }
+    fs.mkdirSync(path.dirname(absPath), { recursive: true });
+    fs.writeFileSync(absPath, content, "utf8");
+    return "written";
+}
+/**
+ * Hybrid scaffold: portal/ helpers + thin Remix route stubs.
+ */
+export async function scaffoldPortalFiles(appRoot, opts = {}) {
+    const force = opts.force ?? false;
+    const written = [];
+    const skipped = [];
+    for (const file of SCAFFOLD_OWNED_FILES) {
+        const abs = path.join(appRoot, file.rel);
+        const content = readTemplate(file.template);
+        const result = await writeFileSafe(abs, content, file.rel, force);
+        if (result === "written")
+            written.push(file.rel);
+        else
+            skipped.push(file.rel);
+    }
+    const entryCandidates = [
+        "app/entry.server.tsx",
+        "app/entry.server.ts",
+        "app/entry.server.jsx",
+    ];
+    let patchedEntry = false;
+    for (const rel of entryCandidates) {
+        const abs = path.join(appRoot, rel);
+        if (!fs.existsSync(abs))
+            continue;
+        let src = fs.readFileSync(abs, "utf8");
+        if (src.includes("startHeartbeatLoop")) {
+            skipped.push(`${rel} (heartbeat already wired)`);
+            patchedEntry = true;
+            break;
+        }
+        const importLine = `import { startHeartbeatLoop } from "../portal/heartbeat.server";\n`;
+        const callLine = `\n// Apps Portal heartbeat (scaffolded by @objects/s-portal)\nstartHeartbeatLoop();\n`;
+        if (!src.includes("portal/heartbeat.server")) {
+            src = importLine + src;
+        }
+        src = src.trimEnd() + callLine;
+        fs.writeFileSync(abs, src, "utf8");
+        written.push(`${rel} (heartbeat loop)`);
+        patchedEntry = true;
+        break;
+    }
+    const entryServerHint = patchedEntry
+        ? "Heartbeat loop wired into entry.server."
+        : [
+            "Could not find app/entry.server.tsx — add this manually:",
+            '  import { startHeartbeatLoop } from "../portal/heartbeat.server";',
+            "  startHeartbeatLoop();",
+        ].join("\n");
+    return { written, skipped, entryServerHint };
+}
+export function mergeEnvFile(appRoot, vars) {
+    const envPath = path.join(appRoot, ".env");
+    let existing = "";
+    if (fs.existsSync(envPath)) {
+        existing = fs.readFileSync(envPath, "utf8");
+    }
+    const lines = existing ? existing.split(/\r?\n/) : [];
+    const updated = [];
+    const keyIndex = new Map();
+    lines.forEach((line, i) => {
+        const m = line.match(/^([A-Z0-9_]+)=/);
+        if (m)
+            keyIndex.set(m[1], i);
+    });
+    for (const [key, value] of Object.entries(vars)) {
+        const escaped = value.includes("\n") || value.includes(" ")
+            ? `"${value.replace(/"/g, '\\"')}"`
+            : value;
+        const line = `${key}=${escaped}`;
+        if (keyIndex.has(key)) {
+            lines[keyIndex.get(key)] = line;
+        }
+        else {
+            if (lines.length && lines[lines.length - 1] !== "")
+                lines.push("");
+            lines.push(line);
+        }
+        updated.push(key);
+    }
+    fs.writeFileSync(envPath, lines.join("\n").replace(/\n+$/, "\n"), "utf8");
+    return { path: envPath, updated };
+}

package/dist/utils.d.ts

@@ -0,0 +1,11 @@
+/** Resolve templates dir both in src (tsx) and dist (published). */
+export declare function templatesDir(): string;
+export declare function readTemplate(name: string): string;
+export declare function hmacHex(secret: string, payload: string): string;
+export declare function normalizeBaseUrl(url: string): string;
+export declare function portalAuthHeaders(clientId: string, clientSecret: string, rawBody: string): {
+    "content-type": string;
+    "x-portal-client-id": string;
+    "x-portal-timestamp": string;
+    "x-portal-signature": string;
+};

package/dist/utils.js

@@ -0,0 +1,36 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/** Resolve templates dir both in src (tsx) and dist (published). */
+export function templatesDir() {
+    const candidates = [
+        path.resolve(__dirname, "../templates"),
+        path.resolve(__dirname, "../../templates"),
+    ];
+    for (const dir of candidates) {
+        if (fs.existsSync(dir))
+            return dir;
+    }
+    throw new Error("Could not find @objects/s-portal templates directory.");
+}
+export function readTemplate(name) {
+    return fs.readFileSync(path.join(templatesDir(), name), "utf8");
+}
+export function hmacHex(secret, payload) {
+    return crypto.createHmac("sha256", secret).update(payload).digest("hex");
+}
+export function normalizeBaseUrl(url) {
+    return url.trim().replace(/\/+$/, "");
+}
+export function portalAuthHeaders(clientId, clientSecret, rawBody) {
+    const timestamp = Date.now().toString();
+    const signature = hmacHex(clientSecret, `${timestamp}.${rawBody}`);
+    return {
+        "content-type": "application/json",
+        "x-portal-client-id": clientId,
+        "x-portal-timestamp": timestamp,
+        "x-portal-signature": signature,
+    };
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@objectsws/s-portal",
+  "version": "0.1.0",
+  "description": "CLI to scaffold Apps Portal sync into a Shopify Remix app and register Remote Base URL",
+  "type": "module",
+  "bin": {
+    "s-portal": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md",
+    "MANUAL_TEST.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "commander": "^13.1.0",
+    "prompts": "^2.4.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "@types/prompts": "^2.4.9",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "keywords": [
+    "shopify",
+    "portal",
+    "sync",
+    "cli"
+  ],
+  "license": "MIT"
+}

package/templates/portal.README.md

@@ -0,0 +1,29 @@
+# Apps Portal sync (scaffolded by `@objects/s-portal`)
+
+## Files
+
+| Path | Role |
+|------|------|
+| `portal/client.server.ts` | HMAC client — heartbeat + webhook sender |
+| `portal/heartbeat.server.ts` | `startHeartbeatLoop()` for server boot |
+| `portal/notify.server.ts` | Helpers to forward Shopify webhooks to the portal |
+| `app/routes/healthz.ts` | Active check target (`GET /healthz`) |
+| `app/routes/api.portal-sync.tsx` | Token + merchants pull API for the portal |
+
+## Wire-up checklist
+
+1. **Env** — set by the CLI after connect (`PORTAL_*` vars).
+2. **Heartbeat** — add to the bottom of `app/entry.server.tsx`:
+
+```ts
+import { startHeartbeatLoop } from "../portal/heartbeat.server";
+startHeartbeatLoop();
+```
+
+3. **Webhooks** — from your Shopify handlers, call helpers in `portal/notify.server.ts`
+   (e.g. `handleAppInstalled`, `handleAppUninstalled`, `handleAppSubscriptionUpdate`).
+
+4. **Merchants pull** — implement the TODO query in `app/routes/api.portal-sync.tsx`.
+   Each row **must** include `id` and `shop`.
+
+5. In the portal UI, use **Verify connection** / **Manual sync** after deploy.