@ratio-app/cli 0.1.1

package/dist/lib/render-error.js

@@ -0,0 +1,115 @@
+// src/lib/errors.ts
+var RatioCLIError = class extends Error {
+  code;
+  exitCode;
+  hint;
+  docsUrl;
+  constructor(opts) {
+    super(opts.message);
+    this.name = new.target.name;
+    this.code = opts.code;
+    this.exitCode = opts.exitCode;
+    if (opts.hint !== void 0) this.hint = opts.hint;
+    if (opts.docsUrl !== void 0) this.docsUrl = opts.docsUrl;
+  }
+};
+var ValidationError = class extends RatioCLIError {
+  constructor(message, hint) {
+    const opts = {
+      code: "VALIDATION_ERROR",
+      exitCode: 8,
+      message
+    };
+    if (hint !== void 0) opts.hint = hint;
+    super(opts);
+  }
+};
+function isRatioCLIError(err) {
+  return err instanceof RatioCLIError;
+}
+
+// src/lib/render-error.ts
+function isOclifParserError(err) {
+  return err instanceof Error && "parse" in err && err.parse !== null && err.parse !== void 0;
+}
+function buildErrorEnvelope(code, message, hint, docsUrl) {
+  const obj = { ok: false, code, message };
+  if (hint !== void 0) obj["hint"] = hint;
+  if (docsUrl !== void 0) obj["docsUrl"] = docsUrl;
+  return JSON.stringify(obj) + "\n";
+}
+function renderError(input) {
+  const { err, verbose, json } = input;
+  if (isRatioCLIError(err)) {
+    const ratioErr = err;
+    if (ratioErr.exitCode === 0) {
+      if (json) {
+        return {
+          stdout: JSON.stringify({ ok: true, data: null }) + "\n",
+          stderr: "",
+          exitCode: 0
+        };
+      }
+      return {
+        stdout: ratioErr.message + "\n",
+        stderr: "",
+        exitCode: 0
+      };
+    }
+    let stderrLines = `${ratioErr.code}: ${ratioErr.message}
+`;
+    if (ratioErr.hint !== void 0) stderrLines += `${ratioErr.hint}
+`;
+    if (ratioErr.docsUrl !== void 0) stderrLines += `${ratioErr.docsUrl}
+`;
+    if (json) {
+      return {
+        stdout: buildErrorEnvelope(ratioErr.code, ratioErr.message, ratioErr.hint, ratioErr.docsUrl),
+        stderr: verbose && ratioErr.stack ? ratioErr.stack + "\n" : "",
+        exitCode: ratioErr.exitCode
+      };
+    }
+    if (verbose && ratioErr.stack) {
+      stderrLines += ratioErr.stack + "\n";
+    }
+    return { stdout: "", stderr: stderrLines, exitCode: ratioErr.exitCode };
+  }
+  if (isOclifParserError(err)) {
+    const parserErr = err;
+    const msg = parserErr.message || "Unknown parse error";
+    const coercedErr = new ValidationError(msg);
+    let stderrText2 = `${coercedErr.code}: ${msg}
+`;
+    if (json) {
+      return {
+        stdout: buildErrorEnvelope(coercedErr.code, msg),
+        stderr: verbose && parserErr.stack ? parserErr.stack + "\n" : "",
+        exitCode: 8
+      };
+    }
+    if (verbose && parserErr.stack) {
+      stderrText2 += parserErr.stack + "\n";
+    }
+    return { stdout: "", stderr: stderrText2, exitCode: 8 };
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  const stack = err instanceof Error ? err.stack : void 0;
+  const stderrPrefix = `INTERNAL: ${message}
+`;
+  if (json) {
+    return {
+      stdout: buildErrorEnvelope("INTERNAL", message),
+      stderr: verbose && stack ? stack + "\n" : "",
+      exitCode: 1
+    };
+  }
+  let stderrText = stderrPrefix;
+  if (verbose && stack) {
+    stderrText += stack + "\n";
+  }
+  return { stdout: "", stderr: stderrText, exitCode: 1 };
+}
+export {
+  renderError
+};
+//# sourceMappingURL=render-error.js.map

package/dist/lib/render-error.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/errors.ts","../../src/lib/render-error.ts"],"sourcesContent":["/**\n * Error hierarchy for the Ratio CLI. Every error thrown from a command's\n * run() is expected to be an instance of RatioCLIError so the global\n * render-error handler can map it to a deterministic stderr line and exit\n * code. Uncaught Error subclasses render as \"INTERNAL: <msg>\" with exit 1.\n *\n * No import from @oclif/core — this file is dependency-free so tests\n * can import it without oclif overhead.\n */\n\nexport class RatioCLIError extends Error {\n  readonly code: string;\n  readonly exitCode: number;\n  readonly hint?: string;\n  readonly docsUrl?: string;\n\n  constructor(opts: {\n    code: string;\n    exitCode: number;\n    message: string;\n    hint?: string;\n    docsUrl?: string;\n  }) {\n    super(opts.message);\n    this.name = new.target.name;\n    this.code = opts.code;\n    this.exitCode = opts.exitCode;\n    if (opts.hint !== undefined) this.hint = opts.hint;\n    if (opts.docsUrl !== undefined) this.docsUrl = opts.docsUrl;\n  }\n}\n\n/** Coming-soon stub UX. Renders on stdout with exit 0. */\nexport class ComingSoonError extends RatioCLIError {\n  constructor(message: string) {\n    super({ code: 'COMING_SOON', exitCode: 0, message });\n  }\n}\n\n/** User has no credentials and command requires auth. */\nexport class NotLoggedInError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = \"Run 'ratio auth login' to sign in.\",\n  ) {\n    super({ code: 'NOT_LOGGED_IN', exitCode: 3, message, hint });\n  }\n}\n\nexport class TokenExpiredError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = \"Run 'ratio auth login' to refresh your session.\",\n  ) {\n    super({ code: 'TOKEN_EXPIRED', exitCode: 3, message, hint });\n  }\n}\n\nexport class ScopeDeniedError extends RatioCLIError {\n  constructor(message: string, hint?: string) {\n    const opts: { code: string; exitCode: number; message: string; hint?: string } = {\n      code: 'SCOPE_DENIED',\n      exitCode: 4,\n      message,\n    };\n    if (hint !== undefined) opts.hint = hint;\n    super(opts);\n  }\n}\n\nexport class NetworkError extends RatioCLIError {\n  constructor(message: string, hint: string = 'Check your network and retry.') {\n    super({ code: 'NETWORK_ERROR', exitCode: 5, message, hint });\n  }\n}\n\nexport class RelayConnectError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Verify the tunnel URL and that the auth-server is reachable.',\n  ) {\n    super({ code: 'RELAY_CONNECT', exitCode: 6, message, hint });\n  }\n}\n\nexport class TemplateExistsError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Choose a different name or remove the existing directory.',\n  ) {\n    super({ code: 'TEMPLATE_EXISTS', exitCode: 7, message, hint });\n  }\n}\n\nexport class ValidationError extends RatioCLIError {\n  constructor(message: string, hint?: string) {\n    const opts: { code: string; exitCode: number; message: string; hint?: string } = {\n      code: 'VALIDATION_ERROR',\n      exitCode: 8,\n      message,\n    };\n    if (hint !== undefined) opts.hint = hint;\n    super(opts);\n  }\n}\n\nexport class RelayResumeGapError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Reconnect from the current cursor; older events are outside the buffer window.',\n  ) {\n    super({ code: 'RELAY_RESUME_GAP', exitCode: 9, message, hint });\n  }\n}\n\nexport class OrchestratorSpawnError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = \"Could not start your app's dev command — check that the command in ratio.config.jsonc runs from this directory.\",\n  ) {\n    super({ code: 'ORCHESTRATOR_SPAWN', exitCode: 10, message, hint });\n  }\n}\n\nexport class OrchestratorDrainTimeoutError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Your dev command did not exit cleanly within 5 seconds — it was forcibly terminated.',\n  ) {\n    super({ code: 'ORCHESTRATOR_DRAIN', exitCode: 11, message, hint });\n  }\n}\n\nexport function isRatioCLIError(err: unknown): err is RatioCLIError {\n  return err instanceof RatioCLIError;\n}\n","import { isRatioCLIError, RatioCLIError, ValidationError } from './errors.js';\n\nexport interface RenderInput {\n  err: unknown;\n  verbose: boolean;\n  json: boolean;\n}\n\nexport interface RenderOutput {\n  /** Text to write to stdout. Empty string means nothing to write. */\n  stdout: string;\n  /** Text to write to stderr. Empty string means nothing to write. */\n  stderr: string;\n  exitCode: number;\n}\n\n/**\n * Detects whether an error originates from the oclif argument/flag parser.\n * oclif's CLIParseError subclasses (NonExistentFlagsError, RequiredArgsError,\n * etc.) all carry a `parse` property set by CLIParseErrorOptions. This is the\n * stable structural signal — more reliable than checking the class name string.\n */\nfunction isOclifParserError(err: unknown): err is Error & { parse: unknown } {\n  return (\n    err instanceof Error &&\n    'parse' in err &&\n    err.parse !== null &&\n    err.parse !== undefined\n  );\n}\n\n/**\n * Builds the JSON error envelope. Fields with undefined values are omitted\n * so the consumer never sees `\"hint\": null` or `\"docsUrl\": null`.\n */\nfunction buildErrorEnvelope(\n  code: string,\n  message: string,\n  hint?: string,\n  docsUrl?: string,\n): string {\n  const obj: Record<string, unknown> = { ok: false, code, message };\n  if (hint !== undefined) obj['hint'] = hint;\n  if (docsUrl !== undefined) obj['docsUrl'] = docsUrl;\n  return JSON.stringify(obj) + '\\n';\n}\n\n/**\n * Pure rendering function — no side effects, no process.exit, no I/O.\n * The caller (RatioCommand.catch) is responsible for writing output and exiting.\n *\n * Rendering rules (all branches):\n *\n * | Error shape          | --json | --verbose | stdout                         | stderr                           | exit |\n * |----------------------|--------|-----------|--------------------------------|----------------------------------|------|\n * | ComingSoonError      | false  | any       | err.message + '\\n'            | ''                               | 0    |\n * | ComingSoonError      | true   | any       | '{\"ok\":true,\"data\":null}\\n'   | ''                               | 0    |\n * | RatioCLIError >0     | false  | false     | ''                            | code: msg [+ hint] [+ docsUrl]  | N    |\n * | RatioCLIError >0     | false  | true      | ''                            | above + stack                    | N    |\n * | RatioCLIError >0     | true   | false     | JSON envelope                  | ''                               | N    |\n * | RatioCLIError >0     | true   | true      | JSON envelope                  | stack only                       | N    |\n * | oclif ParserError    | false  | any       | ''                            | VALIDATION_ERROR: msg [+stack]  | 8    |\n * | oclif ParserError    | true   | any       | JSON VALIDATION_ERROR envelope | stack if verbose                 | 8    |\n * | Plain Error / other  | false  | false     | ''                            | INTERNAL: msg\\n                 | 1    |\n * | Plain Error / other  | false  | true      | ''                            | INTERNAL: msg\\n + stack\\n       | 1    |\n * | Plain Error / other  | true   | any       | JSON INTERNAL envelope         | stack if verbose                 | 1    |\n */\nexport function renderError(input: RenderInput): RenderOutput {\n  const { err, verbose, json } = input;\n\n  // ── Branch 1: our own typed hierarchy ───────────────────────────────────\n  if (isRatioCLIError(err)) {\n    const ratioErr = err as RatioCLIError;\n\n    // exitCode === 0 → coming-soon: render on stdout, no stderr, exit 0\n    if (ratioErr.exitCode === 0) {\n      if (json) {\n        return {\n          stdout: JSON.stringify({ ok: true, data: null }) + '\\n',\n          stderr: '',\n          exitCode: 0,\n        };\n      }\n      return {\n        stdout: ratioErr.message + '\\n',\n        stderr: '',\n        exitCode: 0,\n      };\n    }\n\n    // exitCode > 0 → error render\n    let stderrLines = `${ratioErr.code}: ${ratioErr.message}\\n`;\n    if (ratioErr.hint !== undefined) stderrLines += `${ratioErr.hint}\\n`;\n    if (ratioErr.docsUrl !== undefined) stderrLines += `${ratioErr.docsUrl}\\n`;\n\n    if (json) {\n      return {\n        stdout: buildErrorEnvelope(ratioErr.code, ratioErr.message, ratioErr.hint, ratioErr.docsUrl),\n        stderr: verbose && ratioErr.stack ? ratioErr.stack + '\\n' : '',\n        exitCode: ratioErr.exitCode,\n      };\n    }\n\n    if (verbose && ratioErr.stack) {\n      stderrLines += ratioErr.stack + '\\n';\n    }\n\n    return { stdout: '', stderr: stderrLines, exitCode: ratioErr.exitCode };\n  }\n\n  // ── Branch 2: oclif parser error (unknown flag, missing required arg, etc.) ──\n  if (isOclifParserError(err)) {\n    const parserErr = err as Error & { parse: unknown };\n    const msg = parserErr.message || 'Unknown parse error';\n\n    // Strip oclif's \"Unexpected argument: --foo\" or similar prefix noise where\n    // possible, but keep the core message as-is since it's already human-readable.\n    const coercedErr = new ValidationError(msg);\n\n    let stderrText = `${coercedErr.code}: ${msg}\\n`;\n\n    if (json) {\n      return {\n        stdout: buildErrorEnvelope(coercedErr.code, msg),\n        stderr: verbose && parserErr.stack ? parserErr.stack + '\\n' : '',\n        exitCode: 8,\n      };\n    }\n\n    if (verbose && parserErr.stack) {\n      stderrText += parserErr.stack + '\\n';\n    }\n\n    return { stdout: '', stderr: stderrText, exitCode: 8 };\n  }\n\n  // ── Branch 3: plain Error or non-Error throw ─────────────────────────────\n  const message = err instanceof Error ? err.message : String(err);\n  const stack = err instanceof Error ? err.stack : undefined;\n  const stderrPrefix = `INTERNAL: ${message}\\n`;\n\n  if (json) {\n    return {\n      stdout: buildErrorEnvelope('INTERNAL', message),\n      stderr: verbose && stack ? stack + '\\n' : '',\n      exitCode: 1,\n    };\n  }\n\n  let stderrText = stderrPrefix;\n  if (verbose && stack) {\n    stderrText += stack + '\\n';\n  }\n\n  return { stdout: '', stderr: stderrText, exitCode: 1 };\n}\n"],"mappings":"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","names":["stderrText"]}

package/dist/lib/verbose-flag.d.ts

@@ -0,0 +1,12 @@
+import * as _oclif_core_interfaces from '@oclif/core/interfaces';
+
+/** Global verbose flag — every command imports and spreads this. */
+declare const verboseFlag: {
+    verbose: _oclif_core_interfaces.BooleanFlag<boolean>;
+};
+/** JSON envelope flag — read-style commands (whoami, dev trigger --list) import. */
+declare const jsonFlag: {
+    json: _oclif_core_interfaces.BooleanFlag<boolean>;
+};
+
+export { jsonFlag, verboseFlag };

package/dist/lib/verbose-flag.js

@@ -0,0 +1,17 @@
+// src/lib/verbose-flag.ts
+import { Flags } from "@oclif/core";
+var verboseFlag = {
+  verbose: Flags.boolean({
+    description: "Show diagnostic detail: HTTP status/timing lines for auth requests (stderr) and stack traces for internal errors."
+  })
+};
+var jsonFlag = {
+  json: Flags.boolean({
+    description: "Emit machine-readable JSON on stdout."
+  })
+};
+export {
+  jsonFlag,
+  verboseFlag
+};
+//# sourceMappingURL=verbose-flag.js.map

package/dist/lib/verbose-flag.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/verbose-flag.ts"],"sourcesContent":["import { Flags } from '@oclif/core';\n\n/** Global verbose flag — every command imports and spreads this. */\nexport const verboseFlag = {\n  verbose: Flags.boolean({\n    description:\n      'Show diagnostic detail: HTTP status/timing lines for auth requests (stderr) and stack traces for internal errors.',\n  }),\n};\n\n/** JSON envelope flag — read-style commands (whoami, dev trigger --list) import. */\nexport const jsonFlag = {\n  json: Flags.boolean({\n    description: 'Emit machine-readable JSON on stdout.',\n  }),\n};\n"],"mappings":";AAAA,SAAS,aAAa;AAGf,IAAM,cAAc;AAAA,EACzB,SAAS,MAAM,QAAQ;AAAA,IACrB,aACE;AAAA,EACJ,CAAC;AACH;AAGO,IAAM,WAAW;AAAA,EACtB,MAAM,MAAM,QAAQ;AAAA,IAClB,aAAa;AAAA,EACf,CAAC;AACH;","names":[]}

package/dist/render-CrHGqTPH.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Template scaffold engine for `ratio app create`.
+ *
+ * Renders a bundled app template into a destination directory:
+ *
+ * - Files ending in `.tmpl` are read as UTF-8 and every `{{key}}`
+ *   placeholder is substituted from the provided substitution map,
+ *   then written with the `.tmpl` suffix stripped
+ *   (`package.json.tmpl` → `package.json`).
+ * - All other files are copied byte-for-byte.
+ *
+ * The engine is intentionally minimal: a single-pass
+ * `String.replace(/\{\{key\}\}/g, …)` with a replacer FUNCTION (so
+ * `$&`, `$1`, `$$` in substitution values are never interpreted as
+ * special replacement patterns). There is no template library and no
+ * recursive substitution — if a substitution value itself contains
+ * `{{...}}`, that literal text appears in the output untouched.
+ *
+ * Every template root carries a `manifest.json`:
+ *
+ * ```json
+ * {
+ *   "name": "minimal",
+ *   "description": "Express-based Ratio app (default).",
+ *   "substitutionKeys": ["appName", "clientId", "sdkVersion", "templateName"]
+ * }
+ * ```
+ *
+ * `substitutionKeys` is the closed set of placeholders the template's
+ * `.tmpl` files may use. A `{{key}}` found in a `.tmpl` file that is
+ * not declared in the manifest is a render-time error
+ * (`unknown_substitution_key`). The `manifest.json` itself is copied
+ * verbatim into the generated app so tooling can re-inspect which
+ * template produced it.
+ *
+ * The canonical `ratio.config.jsonc` produced by every template has
+ * this shape (the scaffolder writes it; `ratio app link` later fills
+ * `clientId`):
+ *
+ * ```jsonc
+ * {
+ *   // 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": []
+ *   }
+ * }
+ * ```
+ *
+ * The engine does not hardcode that shape — it only substitutes keys —
+ * but the block above documents the contract for template authors.
+ */
+/** Per-template metadata, loaded from `<templateRoot>/manifest.json`. */
+interface TemplateManifest {
+    /** Template identifier, e.g. 'minimal' | 'with-admin-ui' | 'serverless'. */
+    readonly name: string;
+    readonly description: string;
+    /** Closed set of `{{key}}` placeholders the template's `.tmpl` files may use. */
+    readonly substitutionKeys: readonly string[];
+}
+interface RenderInput {
+    /** Must match one of the discovered templates. */
+    readonly templateName: string;
+    /** Absolute path to write into. Must be empty (or not yet exist). */
+    readonly destinationDir: string;
+    readonly substitutions: Readonly<Record<string, string>>;
+    /** Overrides template-root discovery (test injection). */
+    readonly sourceRootOverride?: string;
+    /** Called once per file AFTER a successful write. Bytes = per-file, NOT cumulative. */
+    readonly onFile?: (relativePath: string, bytesWritten: number) => void;
+}
+interface RenderResult {
+    /** Absolute paths, in write order. */
+    readonly filesWritten: readonly string[];
+    readonly bytesWritten: number;
+}
+type RatioTemplateErrorCode = 'template_not_found' | 'unknown_substitution_key' | 'missing_substitution_value' | 'destination_not_empty' | 'io_error';
+/** Error surface for the scaffold engine. All failures carry a stable `code`. */
+declare class RatioTemplateError extends Error {
+    readonly code: RatioTemplateErrorCode;
+    readonly templateName?: string;
+    readonly key?: string;
+    constructor(opts: {
+        readonly code: RatioTemplateErrorCode;
+        readonly message: string;
+        readonly templateName?: string;
+        readonly key?: string;
+        readonly cause?: unknown;
+    });
+}
+/**
+ * Discover all bundled templates and return their manifests, sorted by
+ * template directory name for a stable order.
+ */
+declare function listTemplates(sourceRootOverride?: string): Promise<readonly TemplateManifest[]>;
+/**
+ * Render the named template into `destinationDir`.
+ *
+ * Strict about its destination: if the directory already contains any
+ * entry the render throws `destination_not_empty` — the caller owns
+ * the "directory already has content" UX.
+ */
+declare function renderTemplate(input: RenderInput): Promise<RenderResult>;
+
+export { type RenderInput as R, type TemplateManifest as T, type RenderResult as a, RatioTemplateError as b, listTemplates as l, renderTemplate as r };

package/dist/templates/minimal/.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/minimal/README.md.tmpl

@@ -0,0 +1,26 @@
+# {{appName}}
+
+Scaffolded from the Ratio `{{templateName}}` template — an Express-based
+Ratio app with OAuth install and verified webhooks wired up via
+`@ratio-app/sdk`.
+
+## 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 local server on port 3000.
+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.
+- `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.
+- You own the dependency pins in `package.json` — update them as your app evolves.

package/dist/templates/minimal/gitignore

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

package/dist/templates/minimal/manifest.json

@@ -0,0 +1,5 @@
+{
+  "name": "minimal",
+  "description": "Express-based Ratio app (default).",
+  "substitutionKeys": ["appName", "clientId", "sdkVersion", "templateName"]
+}

package/dist/templates/minimal/package.json.tmpl

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

package/dist/templates/minimal/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/minimal/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/minimal/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/minimal/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/minimal/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"]
+}

package/dist/templates/serverless/README.md.tmpl

@@ -0,0 +1,28 @@
+# {{appName}}
+
+Scaffolded from the Ratio `{{templateName}}` template — a Cloudflare
+Workers Ratio app with OAuth install and verified webhooks wired up via
+`@ratio-app/sdk`.
+
+## 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. Set your secrets with `wrangler secret put RATIO_CLIENT_SECRET` and `wrangler secret put RATIO_WEBHOOK_SECRET` (values from the dashboard).
+5. Run `npm run dev` to start `wrangler dev` locally, then `npm run deploy` when ready.
+6. Point your merchant test store at your `*.workers.dev` route: `https://<worker>.<subdomain>.workers.dev/oauth/callback` and `https://<worker>.<subdomain>.workers.dev/webhooks`.
+
+## Project layout
+
+- `src/index.ts` — Workers `fetch` handler; routes the install and webhook paths.
+- `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.
+- `ratio.config.jsonc` — the app manifest committed to this repo.
+- `wrangler.toml` — Workers config; keep `compatibility_flags = ["nodejs_compat"]` (the SDK uses `node:crypto` at runtime).
+
+## Notes
+
+- The webhook handler reads the raw request body with `request.text()` before verification on purpose: signature verification needs the exact payload bytes. Parse JSON only after `verify()` succeeds.
+- Secrets live in Workers secrets (`wrangler secret put ...`), never in committed files.
+- You own the dependency pins in `package.json` — update them as your app evolves.

package/dist/templates/serverless/gitignore

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

package/dist/templates/serverless/manifest.json

@@ -0,0 +1,5 @@
+{
+  "name": "serverless",
+  "description": "Cloudflare Workers Ratio app.",
+  "substitutionKeys": ["appName", "clientId", "sdkVersion", "templateName"]
+}

package/dist/templates/serverless/package.json.tmpl

@@ -0,0 +1,22 @@
+{
+  "name": "{{appName}}",
+  "version": "0.1.0",
+  "description": "A Ratio app scaffolded from the serverless (Cloudflare Workers) template.",
+  "type": "module",
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ratio-app/sdk": "{{sdkVersion}}"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20240909.0",
+    "typescript": "^5.6.0",
+    "wrangler": "^3.80.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/dist/templates/serverless/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/serverless/src/index.ts.tmpl

@@ -0,0 +1,20 @@
+export interface Env {
+  RATIO_CLIENT_SECRET: string;
+  RATIO_WEBHOOK_SECRET: string;
+}
+
+import { handleInstall } from './install.js';
+import { handleWebhook } from './webhooks.js';
+
+export default {
+  async fetch(request: Request, env: Env, _ctx: ExecutionContext): Promise<Response> {
+    const url = new URL(request.url);
+    if (url.pathname === '/oauth/callback') {
+      return handleInstall(request, env);
+    }
+    if (url.pathname === '/webhooks') {
+      return handleWebhook(request, env);
+    }
+    return new Response('Not found', { status: 404 });
+  },
+} satisfies ExportedHandler<Env>;

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

@@ -0,0 +1,20 @@
+import { exchangeToken } from '@ratio-app/sdk/oauth';
+import type { Env } from './index.js';
+
+export async function handleInstall(request: Request, env: Env): Promise<Response> {
+  const url = new URL(request.url);
+  const code = url.searchParams.get('code');
+  if (code === null) {
+    return new Response('Missing code', { status: 400 });
+  }
+  const result = await exchangeToken({
+    code,
+    clientId: '{{clientId}}',
+    clientSecret: env.RATIO_CLIENT_SECRET,
+  });
+  // TODO: persist tokens (KV / D1 / durable object).
+  return new Response(JSON.stringify({ ok: true, result }), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}