@objectsws/s-portal 0.1.0

package/templates/portal.client.server.ts

@@ -0,0 +1,53 @@
+import crypto from "node:crypto";
+
+const HEARTBEAT_URL = process.env.PORTAL_HEARTBEAT_URL ?? "";
+const WEBHOOK_URL = process.env.PORTAL_WEBHOOK_URL ?? "";
+const CLIENT_ID = process.env.PORTAL_CLIENT_ID ?? "";
+const CLIENT_SECRET = process.env.PORTAL_CLIENT_SECRET ?? "";
+
+function portalHeaders(body: string) {
+  const timestamp = Date.now().toString();
+  const signature = crypto
+    .createHmac("sha256", CLIENT_SECRET)
+    .update(`${timestamp}.${body}`)
+    .digest("hex");
+  return {
+    "content-type": "application/json",
+    "x-portal-client-id": CLIENT_ID,
+    "x-portal-timestamp": timestamp,
+    "x-portal-signature": signature,
+  };
+}
+
+export async function sendPortalHeartbeat(input: {
+  status: "up" | "down" | "degraded" | "unknown";
+  latencyMs?: number;
+  error?: string | null;
+  meta?: Record<string, unknown>;
+}) {
+  if (!HEARTBEAT_URL || !CLIENT_ID || !CLIENT_SECRET) return;
+  const body = JSON.stringify({
+    status: input.status,
+    latencyMs: input.latencyMs,
+    error: input.error ?? null,
+    observedAt: new Date().toISOString(),
+    meta: input.meta ?? {},
+  });
+  await fetch(HEARTBEAT_URL, { method: "POST", headers: portalHeaders(body), body });
+}
+
+export async function sendPortalWebhook(input: {
+  topic: string;
+  shop: string;
+  shopName?: string;
+  payload?: Record<string, unknown>;
+}) {
+  if (!WEBHOOK_URL || !CLIENT_ID || !CLIENT_SECRET) return;
+  const body = JSON.stringify({
+    topic: input.topic,
+    shop: input.shop,
+    shopName: input.shopName ?? null,
+    payload: input.payload ?? {},
+  });
+  await fetch(WEBHOOK_URL, { method: "POST", headers: portalHeaders(body), body });
+}

package/templates/portal.heartbeat.server.ts

@@ -0,0 +1,28 @@
+import { sendPortalHeartbeat } from "./client.server";
+
+let started = false;
+
+/**
+ * Call once from app/entry.server.tsx (or your server entry) on boot.
+ */
+export function startHeartbeatLoop() {
+  if (started) return;
+  started = true;
+  const intervalMs = Number(process.env.HEARTBEAT_INTERVAL_MS || 60_000);
+
+  const tick = async () => {
+    const t0 = Date.now();
+    try {
+      await sendPortalHeartbeat({ status: "up", latencyMs: Date.now() - t0 });
+    } catch (e) {
+      await sendPortalHeartbeat({
+        status: "down",
+        latencyMs: Date.now() - t0,
+        error: e instanceof Error ? e.message : "heartbeat failed",
+      });
+    }
+  };
+
+  void tick();
+  setInterval(() => void tick(), intervalMs);
+}

package/templates/portal.notify.server.ts

@@ -0,0 +1,79 @@
+import { sendPortalWebhook } from "./client.server";
+
+// Call these from your Shopify webhook handlers so merchants appear in the portal.
+
+export async function handleAppInstalled(shop: string, shopName: string, plan?: string) {
+  await sendPortalWebhook({ topic: "APP_INSTALLED", shop, shopName, payload: { plan } });
+}
+
+export async function handleRelationshipInstalled(shop: string, shopName: string, plan?: string) {
+  await sendPortalWebhook({ topic: "RELATIONSHIP_INSTALLED", shop, shopName, payload: { plan } });
+}
+
+export async function handleAppUninstalled(
+  shop: string,
+  shopName: string,
+  phone?: string | null
+) {
+  await sendPortalWebhook({ topic: "APP_UNINSTALLED", shop, shopName, payload: { phone } });
+}
+
+export async function handleRelationshipUninstalled(
+  shop: string,
+  shopName: string,
+  phone?: string | null
+) {
+  await sendPortalWebhook({
+    topic: "RELATIONSHIP_UNINSTALLED",
+    shop,
+    shopName,
+    payload: { phone },
+  });
+}
+
+type SubStatus = "ACTIVE" | "CANCELLED" | "PENDING" | "DECLINED" | "EXPIRED" | "FROZEN";
+
+interface AppSubscription {
+  admin_graphql_api_id: string;
+  status: SubStatus;
+  name: string;
+  plan_handle: string;
+  price: string;
+  interval: string;
+  capped_amount: string;
+}
+
+export async function handleAppSubscriptionUpdate(
+  shop: string,
+  shopName: string,
+  payload: { app_subscription: AppSubscription }
+) {
+  const sub = payload.app_subscription;
+  await sendPortalWebhook({
+    topic: "APP_SUBSCRIPTIONS_UPDATE",
+    shop,
+    shopName,
+    payload: {
+      subscriptionId: sub.admin_graphql_api_id,
+      status: sub.status,
+      planHandle: sub.plan_handle,
+      planName: sub.name,
+      price: sub.price,
+      interval: sub.interval,
+      cappedAmount: sub.capped_amount,
+    },
+  });
+}
+
+export async function handleApproachingCap(
+  shop: string,
+  shopName: string,
+  payload: Record<string, unknown>
+) {
+  await sendPortalWebhook({
+    topic: "APP_SUBSCRIPTIONS_APPROACHING_CAPPED_AMOUNT",
+    shop,
+    shopName,
+    payload,
+  });
+}

package/templates/routes.api.portal-sync.tsx

@@ -0,0 +1,90 @@
+import crypto from "node:crypto";
+import type { ActionFunctionArgs, LoaderFunctionArgs } from "@remix-run/node";
+import { json } from "@remix-run/node";
+
+const CLIENT_ID = process.env.PORTAL_CLIENT_ID ?? "";
+const CLIENT_SECRET = process.env.PORTAL_CLIENT_SECRET ?? "";
+/** Portal requires remaining TTL ≤ 2 minutes */
+const TOKEN_TTL_MS = 90_000;
+
+const activeTokens = new Map<string, { expiresAt: number }>();
+
+function verifyPortalSyncRequest(headers: Headers, body: string): boolean {
+  const timestamp = headers.get("x-portal-timestamp") ?? "";
+  const nonce = headers.get("x-portal-nonce") ?? "";
+  const signature = headers.get("x-portal-signature") ?? "";
+  const payload = JSON.parse(body || "{}") as { clientId?: string };
+
+  if (!timestamp || !nonce || !signature || payload.clientId !== CLIENT_ID) return false;
+  if (Math.abs(Date.now() - Number(timestamp)) > 120_000) return false;
+
+  const expected = crypto
+    .createHmac("sha256", CLIENT_SECRET)
+    .update(`${timestamp}.${nonce}.${CLIENT_ID}`)
+    .digest("hex");
+
+  const a = Buffer.from(expected, "hex");
+  const b = Buffer.from(signature.toLowerCase(), "hex");
+  return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+
+// POST /api/portal-sync/token
+export async function action({ request }: ActionFunctionArgs) {
+  if (request.method !== "POST") return json({ error: "Method not allowed" }, { status: 405 });
+  const rawBody = await request.text();
+  if (!verifyPortalSyncRequest(request.headers, rawBody)) {
+    return json({ error: "Unauthorized" }, { status: 401 });
+  }
+
+  const token = crypto.randomBytes(32).toString("hex");
+  const expiresAt = new Date(Date.now() + TOKEN_TTL_MS).toISOString();
+  activeTokens.set(token, { expiresAt: Date.now() + TOKEN_TTL_MS });
+  return json({ accessToken: token, expiresAt });
+}
+
+// GET /api/portal-sync/merchants?cursor=<opaque>
+// MerchantRow MUST include: id (string), shop (string)
+export async function loader({ request }: LoaderFunctionArgs) {
+  const auth = request.headers.get("authorization") ?? "";
+  const token = auth.startsWith("Bearer ") ? auth.slice(7) : "";
+  const entry = activeTokens.get(token);
+  if (!entry || Date.now() > entry.expiresAt) {
+    return json({ error: "Unauthorized" }, { status: 401 });
+  }
+
+  const PAGE = 100;
+  const cursor = new URL(request.url).searchParams.get("cursor");
+  const offset = cursor ? Number(Buffer.from(cursor, "base64url").toString()) : 0;
+
+  // TODO: replace with your real ORM query
+  // const rows = await db.select().from(sessions).limit(PAGE).offset(offset);
+  const rows: Array<{
+    id: string;
+    shop: string;
+    name: string | null;
+    email: string | null;
+    appStatus: string;
+    appPlan: string;
+    appName: string;
+    createdAt?: string;
+  }> = [];
+
+  const nextCursor =
+    rows.length === PAGE
+      ? Buffer.from(String(offset + rows.length)).toString("base64url")
+      : null;
+
+  return json({
+    items: rows.map((r) => ({
+      id: r.id,
+      shop: r.shop,
+      name: r.name,
+      email: r.email,
+      appStatus: r.appStatus,
+      appPlan: r.appPlan,
+      appName: r.appName,
+      createdAt: r.createdAt,
+    })),
+    nextCursor,
+  });
+}

package/templates/routes.healthz.ts

@@ -0,0 +1,30 @@
+import type { LoaderFunctionArgs } from "@remix-run/node";
+import { json } from "@remix-run/node";
+
+async function checkReadiness() {
+  // Add any DB / Redis checks you need here
+  return { ok: true, error: null as string | null };
+}
+
+export async function loader(_: LoaderFunctionArgs) {
+  const t0 = Date.now();
+  const { ok, error } = await checkReadiness();
+  if (!ok) {
+    return json(
+      {
+        ok: false,
+        status: "down",
+        latencyMs: Date.now() - t0,
+        error,
+        ts: new Date().toISOString(),
+      },
+      { status: 503 }
+    );
+  }
+  return json({
+    ok: true,
+    status: "up",
+    latencyMs: Date.now() - t0,
+    ts: new Date().toISOString(),
+  });
+}