@ratio-app/cli 0.1.1

package/dist/templates/serverless/src/webhooks.ts.tmpl

@@ -0,0 +1,36 @@
+import { verify } from '@ratio-app/sdk/webhooks';
+import type { Env } from './index.js';
+
+export async function handleWebhook(request: Request, env: Env): Promise<Response> {
+  // MUST read the raw body; do not JSON-parse before verify (SDK requires raw body for HMAC).
+  // The SDK accepts `string | Buffer`; the string path hashes the utf-8 payload bytes.
+  const rawBody = await request.text();
+  const signature = request.headers.get('x-ratio-signature') ?? '';
+
+  try {
+    verify({
+      rawBody,
+      signature,
+      secret: env.RATIO_WEBHOOK_SECRET,
+    });
+  } catch (err) {
+    const code = (err as { code?: string }).code ?? 'unknown';
+    return new Response(JSON.stringify({ ok: false, code }), {
+      status: 400,
+      headers: { 'content-type': 'application/json' },
+    });
+  }
+
+  const event = JSON.parse(rawBody) as { type?: string };
+  switch (event.type) {
+    case 'orders.created':
+      // TODO: implement handler
+      break;
+    default:
+      break;
+  }
+  return new Response(JSON.stringify({ ok: true }), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}

package/dist/templates/serverless/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "types": ["@cloudflare/workers-types"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/dist/templates/serverless/wrangler.toml.tmpl

@@ -0,0 +1,9 @@
+name = "{{appName}}"
+main = "src/index.ts"
+compatibility_date = "2026-01-15"
+compatibility_flags = ["nodejs_compat"]
+
+# Secrets — set via `wrangler secret put RATIO_CLIENT_SECRET` and
+# `wrangler secret put RATIO_WEBHOOK_SECRET`. Do NOT commit real values.
+[vars]
+# Non-secret vars go here.

package/dist/templates/with-admin-ui/.env.example.tmpl

@@ -0,0 +1,4 @@
+# Ratio app secrets — do not commit real values.
+RATIO_CLIENT_SECRET=
+RATIO_WEBHOOK_SECRET=
+PORT=3000

package/dist/templates/with-admin-ui/README.md.tmpl

@@ -0,0 +1,28 @@
+# {{appName}}
+
+Scaffolded from the Ratio `{{templateName}}` template — an Express-based
+Ratio app with OAuth install, verified webhooks, and a Next.js admin UI
+under `src/admin`.
+
+## Getting started
+
+1. Install dependencies: `npm install`.
+2. Create your Ratio app manually in the Ratio developer dashboard and copy the client id.
+3. Open `ratio.config.jsonc` and paste the client id into the `clientId` field (or run `ratio app link` to auto-fill it).
+4. Copy `.env.example` to `.env` and fill in `RATIO_CLIENT_SECRET` and `RATIO_WEBHOOK_SECRET` from the dashboard.
+5. Run `npm run dev` to start the API server on port 3000, and `npm run admin:dev` to start the admin UI on `http://localhost:3001`.
+6. Point your merchant test store at `https://<merchant>.<store>/oauth/callback` and `https://<merchant>.<store>/webhooks` (use a public tunnel such as ngrok or `ratio dev listen` for local testing).
+
+## Project layout
+
+- `src/index.ts` — Express bootstrap; mounts the install and webhook routes.
+- `src/install.ts` — OAuth install callback (`GET /oauth/callback`); exchanges the authorization code for tokens.
+- `src/webhooks.ts` — webhook receiver (`POST /webhooks`); verifies the HMAC signature over the raw body, then dispatches by topic.
+- `src/admin/` — Next.js admin UI (own `tsconfig.json`; excluded from the root build).
+- `ratio.config.jsonc` — the app manifest committed to this repo.
+
+## Notes
+
+- The webhook route uses `express.raw({ type: 'application/json' })` on purpose: signature verification needs the exact raw bytes. Do not add a global JSON body parser in front of it.
+- The admin UI is a starter stub — wire it to your own API routes as your app grows.
+- You own the dependency pins in `package.json` (including `next`) — update them as your app evolves.

package/dist/templates/with-admin-ui/gitignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+.next/
+.env
+*.log
+.DS_Store

package/dist/templates/with-admin-ui/manifest.json

@@ -0,0 +1,5 @@
+{
+  "name": "with-admin-ui",
+  "description": "Express-based Ratio app with a Next.js admin UI.",
+  "substitutionKeys": ["appName", "clientId", "sdkVersion", "templateName"]
+}

package/dist/templates/with-admin-ui/package.json.tmpl

@@ -0,0 +1,31 @@
+{
+  "name": "{{appName}}",
+  "version": "0.1.0",
+  "description": "A Ratio app scaffolded from the with-admin-ui template.",
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "admin:dev": "next dev src/admin --port 3001",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ratio-app/sdk": "{{sdkVersion}}",
+    "express": "^4.19.0",
+    "next": "^14.2.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/dist/templates/with-admin-ui/ratio.config.jsonc.tmpl

@@ -0,0 +1,17 @@
+{
+  // Canonical Ratio app manifest. Committed to the app repo.
+  // Written by scaffolder; `clientId` filled by `ratio app link`.
+  "$schema": "https://ratio.app/schema/app-manifest.v1.json",
+  "appName": "{{appName}}",
+  "clientId": "{{clientId}}",
+  "sdkVersion": "{{sdkVersion}}",
+  "template": "{{templateName}}",
+  "webhooks": {
+    "path": "/webhooks",
+    "topics": []
+  },
+  "oauth": {
+    "redirectPath": "/oauth/callback",
+    "scopes": []
+  }
+}

package/dist/templates/with-admin-ui/src/admin/app/globals.css

@@ -0,0 +1,19 @@
+:root {
+  color-scheme: light dark;
+}
+
+* {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+body {
+  font-family: system-ui, -apple-system, sans-serif;
+  line-height: 1.5;
+  padding: 2rem;
+}
+
+h1 {
+  margin-bottom: 0.5rem;
+}

package/dist/templates/with-admin-ui/src/admin/app/layout.tsx.tmpl

@@ -0,0 +1,13 @@
+import './globals.css';
+
+export const metadata = {
+  title: '{{appName}} — admin',
+};
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}

package/dist/templates/with-admin-ui/src/admin/app/page.tsx.tmpl

@@ -0,0 +1,8 @@
+export default function AdminHome() {
+  return (
+    <main>
+      <h1>{{appName}} — admin</h1>
+      <p>Scaffolded from the Ratio {{templateName}} template.</p>
+    </main>
+  );
+}

package/dist/templates/with-admin-ui/src/admin/next-env.d.ts.tmpl

@@ -0,0 +1,5 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/building-your-application/configuring/typescript for more information.

package/dist/templates/with-admin-ui/src/admin/next.config.mjs

@@ -0,0 +1,3 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {};
+export default nextConfig;

package/dist/templates/with-admin-ui/src/admin/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "jsx": "preserve",
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "strict": true,
+    "noEmit": true,
+    "allowJs": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "incremental": true,
+    "plugins": [{ "name": "next" }]
+  },
+  "include": ["**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/dist/templates/with-admin-ui/src/index.ts.tmpl

@@ -0,0 +1,26 @@
+/**
+ * {{appName}} — server entry point.
+ *
+ * Mounts the OAuth install callback and the verified webhook receiver.
+ */
+import express from 'express';
+
+import { installRouter } from './install.js';
+import { webhooksRouter } from './webhooks.js';
+
+const app = express();
+
+// Order matters: the webhook route registers its own raw-body parser;
+// keep any global JSON parsing away from it.
+app.use(installRouter);
+app.use(webhooksRouter);
+
+app.get('/', (_req, res) => {
+  res.json({ ok: true, app: '{{appName}}', template: '{{templateName}}' });
+});
+
+const port = Number(process.env['PORT'] ?? 3000);
+
+app.listen(port, () => {
+  console.log(JSON.stringify({ msg: 'server started', app: '{{appName}}', port }));
+});

package/dist/templates/with-admin-ui/src/install.ts.tmpl

@@ -0,0 +1,37 @@
+/**
+ * OAuth install callback.
+ *
+ * When a merchant approves the app, Ratio redirects the browser to
+ * `GET /oauth/callback?code=...`. This handler exchanges the code for
+ * tokens using the app's client secret.
+ */
+import { Router } from 'express';
+import { exchangeToken, type ExchangeTokenArgs } from '@ratio-app/sdk/oauth';
+
+export const installRouter: Router = Router();
+
+installRouter.get('/oauth/callback', async (req, res) => {
+  const code = req.query['code'];
+  if (typeof code !== 'string' || code === '') {
+    res.status(400).json({ ok: false, error: 'missing_code' });
+    return;
+  }
+
+  const args: ExchangeTokenArgs = {
+    code,
+    clientId: '{{clientId}}',
+    clientSecret: process.env['RATIO_CLIENT_SECRET'] ?? '',
+  };
+
+  try {
+    // exchangeToken returns `unknown` — narrow before reading fields
+    // (e.g. with a type guard or a schema parser).
+    const tokens: unknown = await exchangeToken(args);
+    void tokens; // TODO: persist tokens for this merchant.
+    res.status(200).json({ ok: true });
+  } catch {
+    // Never log the raw error object here — it can carry secret material.
+    console.error(JSON.stringify({ msg: 'token exchange failed' }));
+    res.status(502).json({ ok: false, error: 'token_exchange_failed' });
+  }
+});

package/dist/templates/with-admin-ui/src/webhooks.ts.tmpl

@@ -0,0 +1,57 @@
+/**
+ * Webhook receiver.
+ *
+ * Verifies the HMAC signature over the raw request bytes, then
+ * dispatches the event by topic.
+ */
+import express, { Router } from 'express';
+import { verify, type VerifyInput } from '@ratio-app/sdk/webhooks';
+
+export const webhooksRouter: Router = Router();
+
+webhooksRouter.post(
+  '/webhooks',
+  // Raw body on purpose: the SDK requires the exact raw body bytes for
+  // HMAC verification. Parsing JSON first changes the byte sequence and
+  // the signature will not match.
+  express.raw({ type: 'application/json' }),
+  (req, res) => {
+    const rawBody = req.body as Buffer;
+
+    const input: VerifyInput = {
+      rawBody,
+      signature: String(req.headers['x-ratio-signature'] ?? ''),
+      secret: process.env['RATIO_WEBHOOK_SECRET'] ?? '',
+    };
+
+    try {
+      verify(input);
+    } catch (err) {
+      // The SDK error carries a stable `code`. Do not log the raw body
+      // or the full error object.
+      const code = (err as { code?: string }).code ?? 'unknown';
+      console.error(JSON.stringify({ msg: 'webhook verification failed', code }));
+      res.status(400).json({ ok: false, code });
+      return;
+    }
+
+    // Safe to parse now — the signature matched.
+    const event = JSON.parse(rawBody.toString('utf8')) as { type?: string };
+
+    switch (event.type) {
+      case 'orders.created':
+        // TODO: handle new orders.
+        break;
+      case 'products.updated':
+        // TODO: handle product updates.
+        break;
+      default:
+        console.log(
+          JSON.stringify({ msg: 'unhandled webhook topic', topic: event.type ?? 'unknown' }),
+        );
+        break;
+    }
+
+    res.status(200).json({ ok: true });
+  },
+);

package/dist/templates/with-admin-ui/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "src/admin"]
+}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@ratio-app/cli",
+  "version": "0.1.1",
+  "description": "Official Ratio developer CLI",
+  "keywords": [
+    "ratio",
+    "cli",
+    "oclif",
+    "developer-tools",
+    "ecommerce",
+    "webhooks",
+    "oauth",
+    "scaffold",
+    "app-platform"
+  ],
+  "author": "Ratio",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "ratio": "bin/run.mjs"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "oclif": {
+    "bin": "ratio",
+    "commands": "./dist/commands",
+    "topicSeparator": " ",
+    "plugins": [
+      "@oclif/plugin-help",
+      "@oclif/plugin-version"
+    ],
+    "topics": {
+      "auth": {
+        "description": "Sign in, sign out, and inspect the current Ratio user."
+      },
+      "app": {
+        "description": "Create, link, run, and deploy Ratio apps."
+      },
+      "dev": {
+        "description": "Local development utilities: forward and trigger webhook events."
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@oclif/core": "^4.0.0",
+    "@oclif/plugin-help": "^6.2.53",
+    "@oclif/plugin-version": "^2.2.50",
+    "@ratio-app/sdk": "0.1.0-alpha.2",
+    "chalk": "^5.3.0",
+    "open": "^10.1.0",
+    "ws": "^8.18.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/ws": "^8.5.10",
+    "@vitest/coverage-v8": "^4.1.9",
+    "oclif": "^4.14.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.9"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}