create-shopify-firebase-app 1.0.0

package/templates/functions/src/admin-api.ts

@@ -0,0 +1,116 @@
+import { Router, Request, Response } from "express";
+import fetch from "node-fetch";
+import { verifySessionToken } from "./verify-token";
+import { getAccessToken } from "./auth";
+
+export const adminApiRouter = Router();
+
+// All admin routes require session token verification
+adminApiRouter.use(verifySessionToken);
+
+// ─── Get shop info ───────────────────────────────────────────────────────
+adminApiRouter.get("/shop", async (req: Request, res: Response) => {
+  const shop = (req as any).shopDomain;
+  const accessToken = await getAccessToken(shop);
+
+  if (!accessToken) {
+    res.status(401).json({ error: "Shop not authenticated" });
+    return;
+  }
+
+  try {
+    const response = await fetch(
+      `https://${shop}/admin/api/2025-04/graphql.json`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-Shopify-Access-Token": accessToken,
+        },
+        body: JSON.stringify({
+          query: `{ shop { name email myshopifyDomain plan { displayName } } }`,
+        }),
+      },
+    );
+
+    const data = (await response.json()) as any;
+    res.json({ shop: data.data?.shop });
+  } catch (err: any) {
+    console.error("Shop info error:", err);
+    res.status(500).json({ error: err.message });
+  }
+});
+
+// ─── Search products (example) ───────────────────────────────────────────
+adminApiRouter.get("/products/search", async (req: Request, res: Response) => {
+  const shop = (req as any).shopDomain;
+  const query = (req.query.q as string) || "";
+  const accessToken = await getAccessToken(shop);
+
+  if (!accessToken) {
+    res.status(401).json({ error: "Shop not authenticated" });
+    return;
+  }
+
+  try {
+    const response = await fetch(
+      `https://${shop}/admin/api/2025-04/graphql.json`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-Shopify-Access-Token": accessToken,
+        },
+        body: JSON.stringify({
+          query: `
+            query SearchProducts($query: String!) {
+              products(first: 10, query: $query) {
+                edges {
+                  node {
+                    id
+                    title
+                    handle
+                    status
+                    featuredImage { url }
+                    variants(first: 1) {
+                      edges { node { id price } }
+                    }
+                    priceRangeV2 {
+                      minVariantPrice { amount currencyCode }
+                    }
+                  }
+                }
+              }
+            }
+          `,
+          variables: { query },
+        }),
+      },
+    );
+
+    const data = (await response.json()) as any;
+    const products = (data.data?.products?.edges || []).map((edge: any) => ({
+      id: edge.node.id,
+      title: edge.node.title,
+      handle: edge.node.handle,
+      status: edge.node.status,
+      image: edge.node.featuredImage?.url || null,
+      variantId: edge.node.variants.edges[0]?.node.id || null,
+      price: edge.node.priceRangeV2?.minVariantPrice?.amount,
+      currency: edge.node.priceRangeV2?.minVariantPrice?.currencyCode,
+    }));
+
+    res.json({ products });
+  } catch (err: any) {
+    console.error("Product search error:", err);
+    res.status(500).json({ error: err.message });
+  }
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// Add your admin API routes below.
+// All routes are protected by session token verification.
+//
+//   const shop = (req as any).shopDomain;
+//   const accessToken = await getAccessToken(shop);
+// ──────────────────────────────────────────────────────────────────────────

package/templates/functions/src/auth.ts

@@ -0,0 +1,130 @@
+import { Router, Request, Response } from "express";
+import crypto from "crypto";
+import fetch from "node-fetch";
+import { getConfig } from "./config";
+import { db } from "./firebase";
+
+export const authRouter = Router();
+
+// ─── Step 1: Start OAuth ─────────────────────────────────────────────────
+// Merchant clicks "Install" → redirect to Shopify consent screen.
+authRouter.get("/", (req: Request, res: Response) => {
+  const { shop } = req.query;
+  if (!shop || typeof shop !== "string") {
+    res.status(400).send("Missing shop parameter");
+    return;
+  }
+
+  const config = getConfig();
+  const nonce = crypto.randomBytes(16).toString("hex");
+  const redirectUri = `${config.appUrl}/auth/callback`;
+
+  // Store nonce for CSRF protection
+  db.collection("authNonces").doc(nonce).set({
+    shop,
+    createdAt: new Date().toISOString(),
+  });
+
+  const authUrl =
+    `https://${shop}/admin/oauth/authorize` +
+    `?client_id=${config.apiKey}` +
+    `&scope=${config.scopes}` +
+    `&redirect_uri=${encodeURIComponent(redirectUri)}` +
+    `&state=${nonce}`;
+
+  res.redirect(authUrl);
+});
+
+// ─── Step 2: OAuth Callback ──────────────────────────────────────────────
+// Shopify redirects back with code + HMAC. Verify, exchange, store session.
+authRouter.get("/callback", async (req: Request, res: Response) => {
+  const { shop, code, hmac, state } = req.query;
+
+  if (!shop || !code || !hmac) {
+    res.status(400).send("Missing required parameters");
+    return;
+  }
+
+  const config = getConfig();
+
+  // Verify HMAC (primary security check — timing-safe)
+  const queryParams = { ...req.query };
+  delete queryParams.hmac;
+  delete queryParams.signature;
+  const message = Object.keys(queryParams)
+    .sort()
+    .map((key) => `${key}=${queryParams[key]}`)
+    .join("&");
+  const generatedHmac = crypto
+    .createHmac("sha256", config.apiSecret)
+    .update(message)
+    .digest("hex");
+
+  const hmacBuffer = Buffer.from(hmac as string);
+  const generatedBuffer = Buffer.from(generatedHmac);
+  if (
+    hmacBuffer.length !== generatedBuffer.length ||
+    !crypto.timingSafeEqual(generatedBuffer, hmacBuffer)
+  ) {
+    res.status(403).send("HMAC verification failed");
+    return;
+  }
+
+  // Clean up nonce
+  if (state) {
+    const nonceDoc = await db.collection("authNonces").doc(state as string).get();
+    if (nonceDoc.exists) await nonceDoc.ref.delete();
+  }
+
+  // Exchange code for access token
+  try {
+    const tokenResponse = await fetch(
+      `https://${shop}/admin/oauth/access_token`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          client_id: config.apiKey,
+          client_secret: config.apiSecret,
+          code,
+        }),
+      },
+    );
+
+    if (!tokenResponse.ok) {
+      const errorText = await tokenResponse.text();
+      console.error("Token exchange failed:", errorText);
+      res.status(500).send("Token exchange failed");
+      return;
+    }
+
+    const tokenData = (await tokenResponse.json()) as {
+      access_token: string;
+      scope: string;
+    };
+
+    // Store session in Firestore
+    await db
+      .collection("shopSessions")
+      .doc(shop as string)
+      .set({
+        shop,
+        accessToken: tokenData.access_token,
+        scope: tokenData.scope,
+        installedAt: new Date().toISOString(),
+      });
+
+    console.log(`App installed for shop: ${shop}`);
+    res.redirect(`https://${shop}/admin/apps/${config.apiKey}`);
+  } catch (err: any) {
+    console.error("OAuth error:", err);
+    res.status(500).send("OAuth error");
+  }
+});
+
+// Helper: get stored access token for a shop
+export async function getAccessToken(shop: string): Promise<string | null> {
+  const doc = await db.collection("shopSessions").doc(shop).get();
+  if (!doc.exists) return null;
+  return doc.data()?.accessToken || null;
+}

package/templates/functions/src/config.ts

@@ -0,0 +1,12 @@
+// Centralized config from environment variables.
+// Firebase Functions auto-loads .env files from the functions/ directory.
+// Docs: https://firebase.google.com/docs/functions/config-env
+
+export function getConfig() {
+  return {
+    apiKey: process.env.SHOPIFY_API_KEY || "",
+    apiSecret: process.env.SHOPIFY_API_SECRET || "",
+    scopes: process.env.SCOPES || "read_products",
+    appUrl: process.env.APP_URL || "",
+  };
+}

package/templates/functions/src/firebase.ts

@@ -0,0 +1,10 @@
+import * as admin from "firebase-admin";
+
+// Initialize Firebase Admin SDK once.
+// Credentials are auto-detected on Firebase infrastructure.
+// For local dev, use `firebase emulators:start`.
+if (!admin.apps.length) {
+  admin.initializeApp();
+}
+
+export const db = admin.firestore();

package/templates/functions/src/index.ts

@@ -0,0 +1,40 @@
+import * as functions from "firebase-functions";
+import "./firebase"; // Initialize Firebase first — must be before other imports
+import express from "express";
+import cors from "cors";
+import { authRouter } from "./auth";
+import { adminApiRouter } from "./admin-api";
+import { proxyRouter } from "./proxy";
+import { webhookRouter } from "./webhooks";
+
+const expressApp = express();
+expressApp.use(cors({ origin: true }));
+
+// Capture raw body for webhook HMAC verification.
+// Shopify signs the raw request body — we need it before JSON parsing.
+expressApp.use(
+  express.json({
+    limit: "2mb",
+    verify: (req: any, _res, buf) => {
+      req.rawBody = buf.toString("utf8");
+    },
+  }),
+);
+expressApp.use(express.urlencoded({ extended: true }));
+
+// ─── Routes ────────────────────────────────────────────────────────────────
+expressApp.use("/auth", authRouter);       // OAuth install + callback
+expressApp.use("/api", adminApiRouter);     // Admin dashboard API (JWT auth)
+expressApp.use("/proxy", proxyRouter);      // App Proxy routes (HMAC auth)
+expressApp.use("/webhooks", webhookRouter); // Webhook handlers
+
+// Health check
+expressApp.get("/", (_req, res) => {
+  res.json({ status: "ok", timestamp: new Date().toISOString() });
+});
+
+// Export as a single Cloud Function.
+// Firebase Hosting rewrites (firebase.json) forward requests here.
+export const app = functions
+  .runWith({ timeoutSeconds: 60, memory: "256MB" })
+  .https.onRequest(expressApp);

package/templates/functions/src/proxy.ts

@@ -0,0 +1,50 @@
+import { Router, Request, Response } from "express";
+import crypto from "crypto";
+import { getConfig } from "./config";
+
+export const proxyRouter = Router();
+
+// ─── Verify Shopify App Proxy Signature ──────────────────────────────────
+// Docs: https://shopify.dev/docs/apps/build/online-store/app-proxies
+function verifyProxySignature(query: Record<string, any>): boolean {
+  const config = getConfig();
+  const signature = query.signature;
+  if (!signature) return false;
+
+  const params = { ...query };
+  delete params.signature;
+
+  // App proxy concatenates without & (different from OAuth HMAC)
+  const message = Object.keys(params)
+    .sort()
+    .map((key) => `${key}=${params[key]}`)
+    .join("");
+
+  const generated = crypto
+    .createHmac("sha256", config.apiSecret)
+    .update(message)
+    .digest("hex");
+
+  const sigBuffer = Buffer.from(signature);
+  const genBuffer = Buffer.from(generated);
+  if (sigBuffer.length !== genBuffer.length) return false;
+  return crypto.timingSafeEqual(genBuffer, sigBuffer);
+}
+
+// ─── Example storefront endpoint ─────────────────────────────────────────
+// Accessible at: https://your-store.myshopify.com/apps/{subpath}/hello
+proxyRouter.get("/hello", (req: Request, res: Response) => {
+  if (!verifyProxySignature(req.query as Record<string, any>)) {
+    res.status(403).json({ error: "Invalid signature" });
+    return;
+  }
+
+  const shop = req.query.shop as string;
+  res.json({ message: `Hello from the app proxy! Shop: ${shop}` });
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// Add storefront-facing routes below.
+// Always verify the proxy signature first.
+// Enable App Proxy in shopify.app.toml.
+// ──────────────────────────────────────────────────────────────────────────

package/templates/functions/src/verify-token.ts

@@ -0,0 +1,55 @@
+import { Request, Response, NextFunction } from "express";
+import jwt from "jsonwebtoken";
+import { getConfig } from "./config";
+
+// App Bridge session token payload
+// Docs: https://shopify.dev/docs/apps/build/authentication/session-tokens
+interface SessionTokenPayload {
+  iss: string; // https://{shop}.myshopify.com/admin
+  dest: string; // https://{shop}.myshopify.com
+  aud: string; // API key
+  sub: string; // User ID
+  exp: number;
+  nbf: number;
+  iat: number;
+  jti: string;
+  sid: string;
+}
+
+// Middleware: verify App Bridge session token.
+// The embedded dashboard sends Authorization: Bearer <jwt> with every request.
+export function verifySessionToken(
+  req: Request,
+  res: Response,
+  next: NextFunction,
+): void {
+  const authHeader = req.headers.authorization;
+  if (!authHeader || !authHeader.startsWith("Bearer ")) {
+    res.status(401).json({ error: "Missing Authorization header" });
+    return;
+  }
+
+  const token = authHeader.split(" ")[1];
+  const config = getConfig();
+
+  try {
+    const decoded = jwt.verify(token, config.apiSecret, {
+      algorithms: ["HS256"],
+    }) as SessionTokenPayload;
+
+    if (decoded.aud !== config.apiKey) {
+      res.status(403).json({ error: "Token audience mismatch" });
+      return;
+    }
+
+    // Extract shop from issuer URL
+    const issUrl = new URL(decoded.iss);
+    (req as any).shopDomain = issUrl.hostname;
+    (req as any).sessionToken = decoded;
+
+    next();
+  } catch (err) {
+    console.error("Session token verification failed:", err);
+    res.status(401).json({ error: "Invalid session token" });
+  }
+}

package/templates/functions/src/webhooks.ts

@@ -0,0 +1,77 @@
+import { Router, Request, Response } from "express";
+import crypto from "crypto";
+import { getConfig } from "./config";
+import { db } from "./firebase";
+
+export const webhookRouter = Router();
+
+// ─── Verify Shopify Webhook HMAC ─────────────────────────────────────────
+function verifyWebhookHmac(rawBody: string, hmacHeader: string): boolean {
+  const config = getConfig();
+  const hash = crypto
+    .createHmac("sha256", config.apiSecret)
+    .update(rawBody, "utf8")
+    .digest("base64");
+
+  try {
+    return crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(hmacHeader));
+  } catch {
+    return false;
+  }
+}
+
+// ─── Webhook Handler ─────────────────────────────────────────────────────
+// All topics route to this single POST endpoint.
+// Topic is identified via X-Shopify-Topic header.
+// IMPORTANT: Respond 200 within 5 seconds. Do heavy work async.
+webhookRouter.post("/", async (req: Request, res: Response) => {
+  const hmac = req.headers["x-shopify-hmac-sha256"] as string;
+  const topic = req.headers["x-shopify-topic"] as string;
+  const shop = req.headers["x-shopify-shop-domain"] as string;
+
+  // Verify HMAC
+  const rawBody = (req as any).rawBody;
+  if (rawBody && hmac && !verifyWebhookHmac(rawBody, hmac)) {
+    console.error("Webhook HMAC verification failed");
+    res.status(401).send("Unauthorized");
+    return;
+  }
+
+  console.log(`Webhook: ${topic} from ${shop}`);
+
+  switch (topic) {
+    // ── App lifecycle ──────────────────────────────────────────────────
+    case "app/uninstalled": {
+      await db.collection("shopSessions").doc(shop).delete();
+      console.log(`Session cleaned up for ${shop}`);
+      break;
+    }
+
+    // ── GDPR mandatory webhooks (required for App Store) ───────────────
+    case "customers/data_request": {
+      // Customer requested their data. Export within 30 days if you store any.
+      console.log(`Customer data request: ${shop}`);
+      // TODO: implement if you store customer data
+      break;
+    }
+
+    case "customers/redact": {
+      // Customer requested deletion. Delete within 30 days.
+      console.log(`Customer redact: ${shop}`);
+      // TODO: implement if you store customer data
+      break;
+    }
+
+    case "shop/redact": {
+      // 48h after uninstall. Delete ALL shop data.
+      console.log(`Shop redact: ${shop}`);
+      // TODO: delete all data for this shop from Firestore
+      break;
+    }
+
+    default:
+      console.log(`Unhandled webhook: ${topic}`);
+  }
+
+  res.status(200).send("OK");
+});

package/templates/functions/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "noImplicitReturns": true,
+    "noUnusedLocals": false,
+    "outDir": "lib",
+    "sourceMap": true,
+    "strict": true,
+    "target": "es2020",
+    "esModuleInterop": true,
+    "resolveJsonModule": true
+  },
+  "compileOnSave": true,
+  "include": ["src"]
+}

package/templates/gitignore

@@ -0,0 +1,33 @@
+# Dependencies
+node_modules/
+
+# Firebase
+.firebase/
+.firebaserc
+firebase-debug.log
+firestore-debug.log
+ui-debug.log
+
+# TypeScript build
+functions/lib/
+
+# Secrets
+.env
+functions/.env
+.runtimeconfig.json
+functions/.runtimeconfig.json
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Shopify CLI
+.shopify/
+
+# Claude Code
+.claude/

package/templates/shopify.app.toml

@@ -0,0 +1,38 @@
+# Shopify App Configuration
+# Docs: https://shopify.dev/docs/apps/tools/cli/configuration
+
+name = "{{APP_NAME}}"
+client_id = "{{API_KEY}}"
+application_url = "{{APP_URL}}"
+embedded = true
+
+[access_scopes]
+scopes = "{{SCOPES}}"
+
+[auth]
+redirect_urls = [
+  "{{APP_URL}}/auth/callback"
+]
+
+[webhooks]
+api_version = "2025-04"
+
+  # App lifecycle
+  [[webhooks.subscriptions]]
+  topics = [ "app/uninstalled" ]
+  uri = "{{APP_URL}}/webhooks"
+
+  # GDPR mandatory webhooks (handled automatically by Shopify via compliance endpoints)
+  [webhooks.privacy_compliance]
+  customer_deletion_url = "{{APP_URL}}/webhooks"
+  customer_data_request_url = "{{APP_URL}}/webhooks"
+  shop_deletion_url = "{{APP_URL}}/webhooks"
+
+# Uncomment to enable App Proxy (storefront-facing routes)
+# [app_proxy]
+# url = "{{APP_URL}}/proxy"
+# subpath = "myapp"
+# prefix = "apps"
+
+[pos]
+embedded = false

package/templates/web/css/app.css

@@ -0,0 +1,57 @@
+/* Shopify-like admin styles for embedded app dashboard */
+
+* { margin: 0; padding: 0; box-sizing: border-box; }
+
+body {
+  font-family: -apple-system, BlinkMacSystemFont, "San Francisco", "Segoe UI", Roboto, "Helvetica Neue", sans-serif;
+  font-size: 14px; line-height: 1.5; color: #1a1a1a; background: #f6f6f7;
+}
+
+.app-page { max-width: 960px; margin: 0 auto; padding: 20px 16px; }
+.page-header { display: flex; align-items: center; justify-content: space-between; margin-bottom: 20px; }
+.page-header h1 { font-size: 20px; font-weight: 600; }
+
+.card {
+  background: #fff; border: 1px solid #e1e3e5; border-radius: 12px;
+  padding: 20px; margin-bottom: 16px; box-shadow: 0 1px 2px rgba(0,0,0,0.05);
+}
+.card h2 { font-size: 16px; font-weight: 600; margin-bottom: 12px; }
+
+.btn {
+  display: inline-flex; align-items: center; gap: 6px; padding: 8px 16px;
+  border-radius: 8px; font-size: 13px; font-weight: 500; cursor: pointer;
+  border: 1px solid #c9cccf; background: #fff; color: #1a1a1a;
+  transition: background 0.15s;
+}
+.btn:hover { background: #f6f6f7; }
+.btn-primary { background: #008060; color: #fff; border-color: #008060; }
+.btn-primary:hover { background: #006e52; }
+.btn-danger { color: #d72c0d; border-color: #d72c0d; }
+.btn-danger:hover { background: #fff4f4; }
+
+.form-group { margin-bottom: 16px; }
+.form-group label { display: block; font-size: 13px; font-weight: 500; margin-bottom: 4px; color: #6d7175; }
+.form-group input, .form-group select, .form-group textarea {
+  width: 100%; padding: 8px 12px; border: 1px solid #c9cccf; border-radius: 8px; font-size: 14px;
+}
+.form-group input:focus, .form-group select:focus { outline: none; border-color: #008060; box-shadow: 0 0 0 1px #008060; }
+
+.empty-state { text-align: center; padding: 40px 20px; }
+.empty-state h3 { font-size: 16px; margin-bottom: 8px; }
+.empty-state p { color: #6d7175; margin-bottom: 16px; }
+
+.loading-overlay { display: flex; align-items: center; justify-content: center; gap: 10px; padding: 60px 20px; color: #6d7175; }
+.spinner { width: 20px; height: 20px; border: 2px solid #e1e3e5; border-top-color: #008060; border-radius: 50%; animation: spin 0.6s linear infinite; }
+@keyframes spin { to { transform: rotate(360deg); } }
+
+.toast {
+  position: fixed; bottom: 20px; left: 50%; transform: translateX(-50%) translateY(100px);
+  background: #1a1a1a; color: #fff; padding: 10px 20px; border-radius: 8px;
+  font-size: 13px; transition: transform 0.3s ease; z-index: 9999;
+}
+.toast.show { transform: translateX(-50%) translateY(0); }
+
+.badge { display: inline-block; padding: 2px 8px; border-radius: 10px; font-size: 12px; font-weight: 500; }
+.badge-success { background: #e4f5e9; color: #00713a; }
+.badge-warning { background: #fff8e6; color: #8a6500; }
+.badge-error { background: #fff4f4; color: #d72c0d; }