@odeva/cli 0.0.1 → 0.0.4

package/README.md

@@ -101,6 +101,14 @@ port = 3000
 [access_scopes]
 scopes = ["reservations:read", "reservations:write"]
 
+# Omit this section if the app doesn't surface inside the merchant admin.
+[admin]
+entry_url = "https://app.example.com/admin"
+
+[admin.sidebar]
+label = "Cabin Manager"
+icon = "puzzle"
+
 [webhooks]
 api_version = "2026-01"
 
@@ -115,6 +123,76 @@ uri = "/webhooks/payment.succeeded"
 
 This file is the source of truth for app config. `odeva app config link` pushes it to the platform; `odeva app dev` reads webhook subscriptions from it to wire up the tunnel.
 
+## Embedding apps in the merchant admin
+
+The admin embed surface lets your app appear as a sidebar entry inside the Odeva merchant admin, mounting your UI in an iframe. It is opt-in: the feature activates only when you declare an `[admin]` block in `odeva.app.toml` (see the Config example above) and run `odeva app config link`.
+
+### How it works
+
+1. Developer declares `[admin]` in `odeva.app.toml` (see the Config example above) and runs `odeva app config link`.
+2. Merchant installs the app from the marketplace.
+3. Merchant clicks the sidebar entry. `odeva-admin` mints a 5-min EdDSA session token via the `mintAppSessionToken` GraphQL mutation, then loads the iframe at `entry_url?session_token=<jwt>&host=<base_url>`.
+4. The app verifies the token against the platform JWKS at `/.well-known/odeva/apps/jwks.json`, checking `iss` and `aud`.
+5. Before the token expires, the app's **backend** calls `POST /api/apps/session-token/refresh` with `X-Api-Key: <api_key>` and hands the new token to the iframe.
+
+### Session token claims
+
+Tokens are standard JWTs signed with `EdDSA`; the JOSE header carries `alg`, `typ`, and `kid`.
+
+| Claim | Value |
+| --- | --- |
+| `iss` | Platform base URL (matches your `ODEVA_API_URL`) |
+| `aud` | The app's `client_id` (matches your `ODEVA_APP_CLIENT_ID`) |
+| `sub` | The app installation ID (string) |
+| `org_id` | The merchant organization ID (string) |
+| `app_id` | The app ID (string) |
+| `exp` | 5 minutes after `iat` |
+| `iat` | Issued-at (unix seconds) |
+| `jti` | Unique token nonce |
+
+### Verifying the token
+
+The JWKS endpoint is `${ODEVA_API_URL}/.well-known/odeva/apps/jwks.json`. The scaffolded template (`odeva app init`) provides a reference implementation in `src/admin.ts`; it uses the `jose` library with `createRemoteJWKSet` and `jwtVerify`.
+
+Key points when verifying:
+
+- Check `iss` matches your `ODEVA_API_URL`.
+- Check `aud` matches your `ODEVA_APP_CLIENT_ID`.
+- Never accept `alg: "none"` — `jose`'s `createRemoteJWKSet` enforces this automatically; if you roll your own verifier you must enforce it yourself.
+
+### Refreshing the token
+
+Tokens have a 5-minute TTL. Long-lived iframe sessions must refresh the token before it expires.
+
+Refresh from the app's **backend** only — the `api_key` must not be exposed to the browser.
+
+```sh
+curl -X POST "$ODEVA_API_URL/api/apps/session-token/refresh" \
+  -H "X-Api-Key: $ODEVA_API_KEY"
+# -> { "token": "...", "expires_at": "2026-..." }
+```
+
+Success response: `{ token, expires_at }` where `expires_at` is an ISO8601 timestamp.
+
+Error codes:
+
+| Status | Meaning |
+| --- | --- |
+| `401` | Missing, invalid, or revoked `api_key` |
+| `403` | `api_key` is not an app-installation key (e.g. a merchant key) |
+| `409` | Installation is not active, or the app has no `[admin]` declared |
+| `503` | Platform signing key not configured (operator-side; retry) |
+
+Typical pattern: the backend refreshes ~30 s before `expires_at` and pushes the new token to the iframe via your own channel (postMessage, polling, or whatever fits the app).
+
+### Quick reference
+
+- JWKS: `${ODEVA_API_URL}/.well-known/odeva/apps/jwks.json`
+- Refresh: `${ODEVA_API_URL}/api/apps/session-token/refresh`
+- Reference implementation: `src/admin.ts` (scaffolded by `odeva app init`)
+- Env vars: `ODEVA_API_URL`, `ODEVA_APP_CLIENT_ID`, `ODEVA_API_KEY`
+- Not yet shipped: host↔app `postMessage` bridge, URL sync between iframe and host.
+
 ## Templates
 
 Bundled templates live under `templates/` in this repo:

package/dist/commands/app/config/link.js

@@ -1,10 +1,28 @@
 import { Command, Flags } from "@oclif/core";
 import * as p from "@clack/prompts";
 import { OdevaApi } from "../../../lib/api.js";
-import { loadAppConfig, saveAppConfig } from "../../../lib/config.js";
+import { loadAppConfig, saveAppConfig, ADMIN_ICONS } from "../../../lib/config.js";
 import { saveAppEnv } from "../../../lib/app-env.js";
 import { withErrorHandling } from "../../../lib/run.js";
 import { ui } from "../../../lib/ui.js";
+import { CliError } from "../../../lib/errors.js";
+function buildAdminEmbedInput(admin, configPath) {
+  const validIcons = ADMIN_ICONS;
+  if (!validIcons.includes(admin.sidebar.icon)) {
+    const iconList = ADMIN_ICONS.join(", ");
+    throw new CliError(
+      `Invalid 'admin.sidebar.icon' in odeva.app.toml: '${admin.sidebar.icon}'. Must be one of: ${iconList}.`,
+      { hint: `Edit ${configPath}` }
+    );
+  }
+  return {
+    entryUrl: admin.entry_url,
+    sidebar: {
+      label: admin.sidebar.label,
+      icon: admin.sidebar.icon
+    }
+  };
+}
 class AppConfigLink extends Command {
   static description = "Register the local app on Odeva and sync its client_id back to odeva.app.toml";
   static examples = ["$ odeva app config link"];
@@ -18,6 +36,7 @@ class AppConfigLink extends Command {
     const { flags } = await this.parse(AppConfigLink);
     await withErrorHandling(this, async () => {
       const loaded = loadAppConfig();
+      const adminInput = loaded.config.admin ? buildAdminEmbedInput(loaded.config.admin, loaded.path) : void 0;
       p.intro(ui.brand("odeva app config link"));
       p.note(
         [
@@ -25,7 +44,8 @@ class AppConfigLink extends Command {
           `${ui.dim("slug:")}        ${loaded.config.slug}`,
           `${ui.dim("client_id:")}   ${loaded.config.client_id ?? ui.dim("(new)")}`,
           `${ui.dim("homepage:")}    ${loaded.config.homepage_url ?? ui.dim("(none)")}`,
-          `${ui.dim("scopes:")}      ${(loaded.config.access_scopes?.scopes ?? []).join(", ") || ui.dim("(none)")}`
+          `${ui.dim("scopes:")}      ${(loaded.config.access_scopes?.scopes ?? []).join(", ") || ui.dim("(none)")}`,
+          ...loaded.config.admin ? [`${ui.dim("admin:")}       ${loaded.config.admin.sidebar.label} (${loaded.config.admin.entry_url})`] : []
         ].join("\n"),
         "Will register this app"
       );
@@ -51,10 +71,11 @@ class AppConfigLink extends Command {
         homepageUrl: loaded.config.homepage_url,
         installUrl: loaded.config.install_url,
         privacyUrl: loaded.config.privacy_url,
-        requestedScopes: loaded.config.access_scopes?.scopes
+        requestedScopes: loaded.config.access_scopes?.scopes,
         // `webhookUrl` is the install-time URL recorded on the App; per-event
         // subscriptions are managed separately by `odeva app dev` against the
         // tunnel URL.
+        ...adminInput ? { adminEmbed: adminInput } : {}
       });
       spinner.stop(`${existingId ? "Updated" : "Registered"} app ${ui.code(app.slug)} (client_id ${ui.code(app.clientId)})`);
       loaded.config.client_id = app.clientId;
@@ -89,5 +110,6 @@ class AppConfigLink extends Command {
   }
 }
 export {
+  buildAdminEmbedInput,
   AppConfigLink as default
 };

package/dist/commands/app/dev.js

@@ -1,5 +1,6 @@
 import { Command, Flags } from "@oclif/core";
 import * as p from "@clack/prompts";
+import { unwatchFile, watchFile } from "node:fs";
 import { OdevaApi } from "../../lib/api.js";
 import { loadAppConfig } from "../../lib/config.js";
 import { loadAppEnv } from "../../lib/app-env.js";
@@ -7,8 +8,10 @@ import { startQuickTunnel } from "../../lib/cloudflared.js";
 import {
   cleanupSubscriptions,
   preflightChecks,
+  registeredWebhookEnv,
   registerWebhookSubscriptions,
   spawnDevServer,
+  watchedDevInputPaths,
   writeDevEnvFile
 } from "../../lib/dev-runner.js";
 import { CliError } from "../../lib/errors.js";
@@ -31,7 +34,6 @@ class AppDev extends Command {
       const loaded = loadAppConfig();
       const appEnv = loadAppEnv(loaded.path);
       const port = flags.port ?? loaded.config.build?.port ?? 3e3;
-      const subscriptions = loaded.config.webhooks?.subscriptions ?? [];
       for (const warning of preflightChecks(loaded.root).warnings) {
         this.log(ui.warn(warning));
       }
@@ -54,24 +56,7 @@ class AppDev extends Command {
       const tunnel = await startQuickTunnel(port);
       tunnelSpinner.stop(`Tunnel ready at ${ui.code(tunnel.url)}`);
       let registered = [];
-      if (subscriptions.length > 0) {
-        const whSpinner = p.spinner();
-        whSpinner.start(`Registering ${subscriptions.length} webhook subscription${subscriptions.length === 1 ? "" : "s"}`);
-        try {
-          registered = await registerWebhookSubscriptions(api, loaded.config.name, tunnel.url, subscriptions);
-          whSpinner.stop(`Registered ${registered.length} subscription${registered.length === 1 ? "" : "s"}`);
-        } catch (err) {
-          whSpinner.stop(ui.err("Webhook registration failed"));
-          await tunnel.stop();
-          throw err instanceof CliError ? err : new CliError(`Webhook registration failed: ${err.message}`);
-        }
-        const envPath = writeDevEnvFile(loaded.root, registered);
-        if (envPath) {
-          this.log(ui.ok(`Wrote ${ui.code(envPath)} (add to .gitignore \u2014 it contains secrets)`));
-        }
-      } else {
-        this.log(ui.dim("No webhook subscriptions in odeva.app.toml \u2014 skipping registration."));
-      }
+      registered = await this.registerDevWebhooks(api, loaded, tunnel.url);
       this.log("");
       this.log(`${ui.bold("Tunnel:")}     ${tunnel.url}`);
       this.log(`${ui.bold("Local:")}      http://localhost:${port}`);
@@ -81,18 +66,68 @@ class AppDev extends Command {
       this.log("");
       this.log(ui.dim("Press Ctrl-C to stop. Subscriptions will be cleaned up on exit."));
       this.log("");
-      const server = spawnDevServer({
+      let server = spawnDevServer({
         cwd: loaded.root,
         config: loaded.config,
         env: {
           ...appEnv,
           PORT: String(port),
           ODEVA_TUNNEL_URL: tunnel.url,
-          ...registered[0] ? { ODEVA_WEBHOOK_SECRET: registered[0].secret } : {}
+          ...registeredWebhookEnv(registered)
         }
       });
+      let shuttingDown = false;
+      let restartingServer = false;
+      let serverExited = () => {
+      };
+      const serverExit = new Promise((resolve) => {
+        serverExited = resolve;
+      });
+      const watchServerExit = (devServer) => {
+        devServer.process.once("exit", (code) => {
+          if (!restartingServer && !shuttingDown) serverExited(code);
+        });
+      };
+      watchServerExit(server);
+      let reloading = Promise.resolve();
+      const stopWatcher = this.watchDevInputs(loaded.path, async () => {
+        reloading = reloading.then(async () => {
+          this.log("\n" + ui.dim("Reloading app dev config..."));
+          const nextLoaded = loadAppConfig(loaded.root);
+          const nextPort = flags.port ?? nextLoaded.config.build?.port ?? 3e3;
+          if (nextPort !== port) {
+            this.log(ui.warn(`Port changed to ${nextPort}; restart \`odeva app dev\` to recreate the tunnel.`));
+          }
+          const nextRegistered = await this.registerDevWebhooks(api, nextLoaded, tunnel.url);
+          await cleanupSubscriptions(api, registered);
+          registered = nextRegistered;
+          const nextAppEnv = loadAppEnv(nextLoaded.path);
+          restartingServer = true;
+          await server.stop();
+          restartingServer = false;
+          const nextServer = spawnDevServer({
+            cwd: nextLoaded.root,
+            config: nextLoaded.config,
+            env: {
+              ...nextAppEnv,
+              PORT: String(port),
+              ODEVA_TUNNEL_URL: tunnel.url,
+              ...registeredWebhookEnv(registered)
+            }
+          });
+          server = nextServer;
+          watchServerExit(server);
+          this.log(ui.ok("Reloaded app dev config."));
+        }).catch((err) => {
+          restartingServer = false;
+          this.log(ui.err(`Reload failed: ${err.message}`));
+        });
+      });
       installShutdownHandler(async () => {
+        shuttingDown = true;
         this.log("\n" + ui.dim("Cleaning up..."));
+        stopWatcher();
+        await reloading;
         await Promise.allSettled([
           server.stop(),
           tunnel.stop(),
@@ -100,10 +135,51 @@ class AppDev extends Command {
         ]);
         this.log(ui.ok("Done."));
       });
-      await server.waitForExit();
+      await serverExit;
+      shuttingDown = true;
+      stopWatcher();
+      await reloading;
       await Promise.allSettled([tunnel.stop(), cleanupSubscriptions(api, registered)]);
     });
   }
+  async registerDevWebhooks(api, loaded, tunnelUrl) {
+    const subscriptions = loaded.config.webhooks?.subscriptions ?? [];
+    if (subscriptions.length === 0) {
+      this.log(ui.dim("No webhook subscriptions in odeva.app.toml \u2014 skipping registration."));
+      return [];
+    }
+    const whSpinner = p.spinner();
+    whSpinner.start(`Registering ${subscriptions.length} webhook subscription${subscriptions.length === 1 ? "" : "s"}`);
+    try {
+      const registered = await registerWebhookSubscriptions(api, loaded.config.name, tunnelUrl, subscriptions);
+      whSpinner.stop(`Registered ${registered.length} subscription${registered.length === 1 ? "" : "s"}`);
+      const envPath = writeDevEnvFile(loaded.root, registered);
+      if (envPath) {
+        this.log(ui.ok(`Wrote ${ui.code(envPath)} (add to .gitignore \u2014 it contains secrets)`));
+      }
+      return registered;
+    } catch (err) {
+      whSpinner.stop(ui.err("Webhook registration failed"));
+      throw err instanceof CliError ? err : new CliError(`Webhook registration failed: ${err.message}`);
+    }
+  }
+  watchDevInputs(appConfigPath, onChange) {
+    const paths = watchedDevInputPaths(appConfigPath);
+    let timer;
+    const queue = () => {
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(onChange, 250);
+    };
+    for (const path of paths) {
+      watchFile(path, { interval: 500 }, (curr, prev) => {
+        if (curr.mtimeMs !== prev.mtimeMs || curr.size !== prev.size) queue();
+      });
+    }
+    return () => {
+      if (timer) clearTimeout(timer);
+      for (const path of paths) unwatchFile(path);
+    };
+  }
 }
 let shutdownInstalled = false;
 function installShutdownHandler(handler) {

package/dist/commands/auth/login.js

@@ -10,6 +10,8 @@ import { pickOrganization } from "../../lib/org-picker.js";
 import { withErrorHandling } from "../../lib/run.js";
 import { ui } from "../../lib/ui.js";
 const POLL_TIMEOUT_MS = 15 * 60 * 1e3;
+const MIN_POLL_INTERVAL_MS = 10 * 1e3;
+const RATE_LIMIT_BACKOFF_MS = 30 * 1e3;
 class AuthLogin extends Command {
   static description = "Authenticate the CLI with your Odeva account";
   static examples = [
@@ -42,6 +44,7 @@ class AuthLogin extends Command {
       const api = new OdevaApi({ apiUrl });
       p.intro(ui.brand("odeva auth login"));
       const begin = await api.cliAuthBegin(osHostname());
+      const pollIntervalMs = Math.max(begin.interval * 1e3, MIN_POLL_INTERVAL_MS);
       p.note(
         [
           `Verify this code matches the one shown on the approval page:`,
@@ -58,18 +61,28 @@ class AuthLogin extends Command {
           this.log(ui.warn(`Could not open a browser automatically. Visit the URL above to approve.`));
         }
       }
-      const token = await this.pollUntilResolved(api, begin.deviceCode, begin.interval);
+      const token = await this.pollUntilResolved(api, begin.deviceCode, pollIntervalMs);
       await this.completeWithToken(token, apiUrl);
     });
   }
-  async pollUntilResolved(api, deviceCode, intervalSec) {
+  async pollUntilResolved(api, deviceCode, intervalMs) {
     const spinner = p.spinner();
     spinner.start("Waiting for approval in your browser\u2026");
     const deadline = Date.now() + POLL_TIMEOUT_MS;
     try {
       while (Date.now() < deadline) {
-        await sleep(intervalSec * 1e3);
-        const result = await api.cliAuthPoll(deviceCode);
+        await sleep(intervalMs);
+        let result;
+        try {
+          result = await api.cliAuthPoll(deviceCode);
+        } catch (err) {
+          if (isRateLimitError(err)) {
+            spinner.message("Waiting for approval in your browser\u2026");
+            await sleep(RATE_LIMIT_BACKOFF_MS);
+            continue;
+          }
+          throw err;
+        }
         switch (result.status) {
           case "approved":
             if (!result.token) {
@@ -131,6 +144,15 @@ class AuthLogin extends Command {
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function isRateLimitError(err) {
+  if (!(err instanceof ApiError)) return false;
+  return err.graphqlErrors?.some((gqlError) => {
+    const extensions = gqlError.extensions;
+    if (!extensions || typeof extensions !== "object") return false;
+    const code = extensions.code;
+    return typeof code === "string" && code.toUpperCase() === "RATE_LIMITED";
+  }) ?? /rate limit/i.test(err.message);
+}
 export {
   AuthLogin as default
 };

package/dist/commands/webhook/trigger.js

@@ -5,7 +5,7 @@ import { loadAppConfig, findAppConfigPath } from "../../lib/config.js";
 import { buildFixture, signPayload } from "../../lib/webhook-fixtures.js";
 import { CliError } from "../../lib/errors.js";
 import { withErrorHandling } from "../../lib/run.js";
-import { readEnvFile } from "../../lib/dev-runner.js";
+import { readEnvFile, webhookSecretForEvent } from "../../lib/dev-runner.js";
 import { ui } from "../../lib/ui.js";
 import { join } from "node:path";
 class WebhookTrigger extends Command {
@@ -45,10 +45,11 @@ class WebhookTrigger extends Command {
     const { args, flags } = await this.parse(WebhookTrigger);
     await withErrorHandling(this, async () => {
       const event = args.event;
-      const url = flags.url ?? this.urlFromConfig(event, flags.port);
+      const configSubscription = this.subscriptionFromConfig(event);
+      const url = flags.url ?? this.urlFromConfig(event, flags.port, configSubscription?.uri);
       const payload = flags.payload ? this.readPayload(flags.payload, event) : buildFixture(event);
       const body = JSON.stringify(payload);
-      const secret = flags.secret ?? this.secretFromEnvFile();
+      const secret = flags.secret ?? this.secretFromEnvFile(event);
       const headers = {
         "content-type": "application/json",
         "x-odeva-event": event,
@@ -57,7 +58,7 @@ class WebhookTrigger extends Command {
       if (!flags["no-sign"]) {
         if (!secret) {
           throw new CliError("No webhook secret available.", {
-            hint: "Run `odeva app dev` first to generate one, or pass --secret <value>, or use --no-sign for unsigned testing."
+            hint: flags.url || configSubscription ? "Run `odeva app dev` to generate one, or pass --secret <value>, or use --no-sign for unsigned testing." : `Add a '${event}' subscription to odeva.app.toml, let \`odeva app dev\` reload, then try again.`
           });
         }
         headers["x-odeva-signature"] = signPayload(body, secret);
@@ -83,7 +84,13 @@ class WebhookTrigger extends Command {
       if (text) this.log(ui.dim(text.length > 500 ? `${text.slice(0, 500)}\u2026` : text));
     });
   }
-  urlFromConfig(event, portFlag) {
+  subscriptionFromConfig(event) {
+    const cfgPath = findAppConfigPath();
+    if (!cfgPath) return void 0;
+    const loaded = loadAppConfig();
+    return loaded.config.webhooks?.subscriptions?.find((s) => s.topic === event);
+  }
+  urlFromConfig(event, portFlag, subscriptionUri) {
     const cfgPath = findAppConfigPath();
     if (!cfgPath) {
       throw new CliError("No odeva.app.toml found, and no --url provided.", {
@@ -91,17 +98,16 @@ class WebhookTrigger extends Command {
       });
     }
     const loaded = loadAppConfig();
-    const sub = loaded.config.webhooks?.subscriptions?.find((s) => s.topic === event);
     const port = portFlag ?? loaded.config.build?.port ?? 3e3;
-    const path = sub?.uri ?? `/webhooks/${event}`;
+    const path = subscriptionUri ?? `/webhooks/${event}`;
     return `http://localhost:${port}${path.startsWith("/") ? path : `/${path}`}`;
   }
-  secretFromEnvFile() {
+  secretFromEnvFile(event) {
     const cfgPath = findAppConfigPath();
     if (!cfgPath) return void 0;
     const envPath = join(resolve(cfgPath, ".."), ".env.odeva.local");
     const env = readEnvFile(envPath);
-    return env["ODEVA_WEBHOOK_SECRET"];
+    return webhookSecretForEvent(event, env);
   }
   readPayload(path, event) {
     const abs = resolve(process.cwd(), path);

package/dist/lib/api.js

@@ -153,6 +153,7 @@ class OdevaApi {
         $privacyUrl: String
         $requestedScopes: [String!]
         $webhookUrl: String
+        $adminEmbed: AdminEmbedInput
       ) {
         upsertDeveloperApp(
           id: $id
@@ -165,6 +166,7 @@ class OdevaApi {
           privacyUrl: $privacyUrl
           requestedScopes: $requestedScopes
           webhookUrl: $webhookUrl
+          adminEmbed: $adminEmbed
         ) {
           app {
             id
@@ -246,7 +248,7 @@ class OdevaApi {
           appInstallationId: $appInstallationId
         ) {
           webhookSubscription { id name endpointUrl eventTypes status }
-          webhookSecret
+          signingSecret
           errors
         }
       }
@@ -257,7 +259,10 @@ class OdevaApi {
     if (payload.errors?.length) {
       throw new ApiError(`Could not create webhook subscription: ${payload.errors.join(", ")}`);
     }
-    return { subscription: payload.webhookSubscription, webhookSecret: payload.webhookSecret };
+    if (!payload.signingSecret) {
+      throw new ApiError("Could not create webhook subscription: no signing secret returned");
+    }
+    return { subscription: payload.webhookSubscription, signingSecret: payload.signingSecret };
   }
   async deleteWebhookSubscription(id) {
     await this.request(

package/dist/lib/config.js

@@ -3,6 +3,17 @@ import { dirname, join, resolve } from "node:path";
 import { parse, stringify } from "smol-toml";
 import { APP_CONFIG_FILE } from "./paths.js";
 import { AppConfigNotFoundError, CliError } from "./errors.js";
+const ADMIN_ICONS = [
+  "puzzle",
+  "box",
+  "plug",
+  "bot",
+  "sparkles",
+  "wrench",
+  "database",
+  "bar-chart",
+  "wallet"
+];
 function findAppConfigPath(startDir = process.cwd()) {
   let dir = resolve(startDir);
   while (true) {
@@ -42,8 +53,77 @@ function validateConfig(config, path) {
       { hint: `Edit ${path}` }
     );
   }
+  if (config.webhooks?.subscriptions) {
+    const rawSubscriptions = config.webhooks.subscriptions;
+    config.webhooks.subscriptions = rawSubscriptions.map((subscription) => {
+      if (typeof subscription === "string") {
+        return { topic: subscription, uri: `/webhooks/${subscription}` };
+      }
+      if (!subscription.topic || typeof subscription.topic !== "string") {
+        throw new CliError(`Invalid ${APP_CONFIG_FILE}: webhook subscription missing 'topic'.`, {
+          hint: `Edit ${path}`
+        });
+      }
+      return {
+        ...subscription,
+        uri: subscription.uri || `/webhooks/${subscription.topic}`
+      };
+    });
+  }
+  if (config.admin !== void 0) {
+    validateAdminSection(config.admin, path);
+  }
+}
+function validateAdminSection(admin, path) {
+  if (typeof admin !== "object" || admin === null || Array.isArray(admin)) {
+    throw new CliError(`Invalid ${APP_CONFIG_FILE}: 'admin' must be a table.`, {
+      hint: `Edit ${path}`
+    });
+  }
+  const a = admin;
+  if (typeof a["entry_url"] !== "string" || !a["entry_url"]) {
+    throw new CliError(`Invalid ${APP_CONFIG_FILE}: missing 'admin.entry_url'.`, {
+      hint: `Edit ${path}`
+    });
+  }
+  if (!a["entry_url"].startsWith("https://")) {
+    throw new CliError(
+      `Invalid 'admin.entry_url' in ${APP_CONFIG_FILE}: must start with https://.`,
+      { hint: `Edit ${path}` }
+    );
+  }
+  const sidebar = a["sidebar"];
+  if (typeof sidebar !== "object" || sidebar === null || Array.isArray(sidebar)) {
+    throw new CliError(`Invalid ${APP_CONFIG_FILE}: missing 'admin.sidebar' table.`, {
+      hint: `Edit ${path}`
+    });
+  }
+  const s = sidebar;
+  if (typeof s["label"] !== "string" || s["label"].length === 0) {
+    throw new CliError(`Invalid ${APP_CONFIG_FILE}: missing 'admin.sidebar.label'.`, {
+      hint: `Edit ${path}`
+    });
+  }
+  if (s["label"].length > 30) {
+    throw new CliError(
+      `Invalid 'admin.sidebar.label' in ${APP_CONFIG_FILE}: must be 30 characters or fewer.`,
+      { hint: `Edit ${path}` }
+    );
+  }
+  if (typeof s["icon"] !== "string" || !s["icon"]) {
+    throw new CliError(`Invalid ${APP_CONFIG_FILE}: missing 'admin.sidebar.icon'.`, { hint: `Edit ${path}` });
+  }
+  const validIcons = ADMIN_ICONS;
+  if (!validIcons.includes(s["icon"])) {
+    const iconList = ADMIN_ICONS.join(", ");
+    throw new CliError(
+      `Invalid 'admin.sidebar.icon' in ${APP_CONFIG_FILE}: '${s["icon"]}'. Must be one of: ${iconList}.`,
+      { hint: `Edit ${path}` }
+    );
+  }
 }
 export {
+  ADMIN_ICONS,
   findAppConfigPath,
   loadAppConfig,
   saveAppConfig,

package/dist/lib/dev-runner.js

@@ -1,16 +1,17 @@
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { APP_ENV_FILE } from "./app-env.js";
 async function registerWebhookSubscriptions(api, appName, tunnelUrl, subscriptions) {
   const created = [];
   for (const sub of subscriptions) {
     const fullUrl = joinUrl(tunnelUrl, sub.uri);
-    const { subscription, webhookSecret } = await api.createWebhookSubscription({
+    const { subscription, signingSecret } = await api.createWebhookSubscription({
       name: `${appName} (dev) \u2014 ${sub.topic}`,
       endpointUrl: fullUrl,
       eventTypes: [sub.topic]
     });
-    created.push({ config: sub, subscription, secret: webhookSecret, fullUrl });
+    created.push({ config: sub, subscription, secret: signingSecret, fullUrl });
   }
   return created;
 }
@@ -26,6 +27,7 @@ function spawnDevServer(opts) {
   const command = opts.config.build?.dev ?? "bun run dev";
   const proc = spawn(command, {
     cwd: opts.cwd,
+    detached: process.platform !== "win32",
     shell: true,
     stdio: "inherit",
     env: {
@@ -53,14 +55,28 @@ function writeDevEnvFile(cwd, registered) {
   lines.push(`ODEVA_WEBHOOK_SECRET=${primary.secret}`);
   for (const reg of registered) {
     lines.push(`# ${reg.config.topic} \u2192 ${reg.fullUrl}`);
-    lines.push(`ODEVA_WEBHOOK_SECRET__${secretEnvKey(reg.config.topic)}=${reg.secret}`);
+    lines.push(`ODEVA_WEBHOOK_SECRET__${webhookSecretEnvKey(reg.config.topic)}=${reg.secret}`);
   }
   writeFileSync(path, lines.join("\n") + "\n", { mode: 384 });
   return path;
 }
-function secretEnvKey(topic) {
+function registeredWebhookEnv(registered) {
+  const env = {};
+  if (registered[0]) env.ODEVA_WEBHOOK_SECRET = registered[0].secret;
+  for (const reg of registered) {
+    env[`ODEVA_WEBHOOK_SECRET__${webhookSecretEnvKey(reg.config.topic)}`] = reg.secret;
+  }
+  return env;
+}
+function webhookSecretEnvKey(topic) {
   return topic.toUpperCase().replace(/[^A-Z0-9]+/g, "_");
 }
+function webhookSecretForEvent(event, env) {
+  return env[`ODEVA_WEBHOOK_SECRET__${webhookSecretEnvKey(event)}`] ?? env["ODEVA_WEBHOOK_SECRET"];
+}
+function watchedDevInputPaths(appConfigPath) {
+  return [appConfigPath, join(dirname(appConfigPath), APP_ENV_FILE)];
+}
 function joinUrl(base, path) {
   const trimmedBase = base.replace(/\/$/, "");
   const trimmedPath = path.startsWith("/") ? path : `/${path}`;
@@ -71,7 +87,7 @@ function stopProcess(proc) {
     if (proc.exitCode !== null) return resolve();
     proc.once("exit", () => resolve());
     try {
-      proc.kill("SIGTERM");
+      killDevProcess(proc, "SIGTERM");
     } catch {
       resolve();
       return;
@@ -79,13 +95,24 @@ function stopProcess(proc) {
     setTimeout(() => {
       if (proc.exitCode === null) {
         try {
-          proc.kill("SIGKILL");
+          killDevProcess(proc, "SIGKILL");
         } catch {
         }
       }
     }, 2e3);
   });
 }
+function killDevProcess(proc, signal) {
+  if (process.platform === "win32") {
+    proc.kill(signal);
+    return;
+  }
+  if (proc.pid) {
+    process.kill(-proc.pid, signal);
+  } else {
+    proc.kill(signal);
+  }
+}
 function preflightChecks(cwd) {
   const warnings = [];
   if (!existsSync(join(cwd, "node_modules"))) {
@@ -110,6 +137,10 @@ export {
   preflightChecks,
   readEnvFile,
   registerWebhookSubscriptions,
+  registeredWebhookEnv,
   spawnDevServer,
+  watchedDevInputPaths,
+  webhookSecretEnvKey,
+  webhookSecretForEvent,
   writeDevEnvFile
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odeva/cli",
-  "version": "0.0.1",
+  "version": "0.0.4",
   "description": "Build apps on the Odeva booking platform — scaffold, develop, deploy.",
   "license": "MIT",
   "type": "module",

package/templates/hono-bun/README.md.tmpl

@@ -21,3 +21,22 @@ odeva webhook trigger reservation.created
 - `odeva.app.toml` — app config (name, slug, webhooks, scopes)
 - `src/index.ts` — Hono server with a webhook handler stub
 - `src/webhook.ts` — HMAC signature verification
+- `src/admin.ts` — iframe session-token verification
+
+## Embed in the merchant admin
+
+This template ships a `/admin` route that verifies Odeva session tokens against
+the platform's JWKS. To surface your app inside the merchant admin sidebar:
+
+1. Uncomment the `[admin]` block at the bottom of `odeva.app.toml` and set
+   `entry_url` to a publicly reachable URL (your `odeva app dev` tunnel works).
+2. Run `odeva app config link` to push the embed config to Odeva.
+3. Reinstall the app on a test org; the sidebar entry appears.
+
+`/admin` reads `?session_token=<jwt>` from the iframe URL, verifies it via
+`jose` + the JWKS at `${ODEVA_API_URL}/.well-known/odeva/apps/jwks.json`,
+and renders `Hello, org <org_id>`. See `src/admin.ts` for the verification
+recipe and a comment showing how to refresh tokens server-side.
+
+Env: `ODEVA_APP_CLIENT_ID` is written into `.odeva.env` by `config link`;
+`ODEVA_API_URL` overrides the default `https://booking.odeva.app`.

package/templates/hono-bun/odeva.app.toml.tmpl

@@ -23,3 +23,16 @@ api_version = "2026-01"
 # [[webhooks.subscriptions]]
 # topic = "reservation.created"
 # uri = "/webhooks/reservation.created"
+
+# Uncomment to embed this app inside the merchant admin sidebar.
+# The merchant admin will iframe `entry_url?session_token=<short-lived JWT>`
+# and your `/admin` route verifies that token against the Odeva JWKS.
+#
+# Icons: puzzle, box, plug, bot, sparkles, wrench, database, bar-chart, wallet.
+#
+# [admin]
+# entry_url = "https://<your-app-dev-url>/admin"
+#
+# [admin.sidebar]
+# label = "{{name}}"
+# icon = "puzzle"

package/templates/hono-bun/package.json.tmpl

@@ -10,7 +10,8 @@
   },
   "dependencies": {
     "@odeva/booking-sdk": "^0.1.0",
-    "hono": "^4.6.0"
+    "hono": "^4.6.0",
+    "jose": "^6.0.0"
   },
   "devDependencies": {
     "@types/bun": "^1.1.0",

package/templates/hono-bun/src/admin.ts

@@ -0,0 +1,99 @@
+// Admin embed route. The Odeva merchant admin iframes this route with
+// `?session_token=<short-lived EdDSA JWT>`. We verify the token against
+// the platform's JWKS and render a personalised page for the org.
+//
+// Opt in by uncommenting the `[admin]` block in `odeva.app.toml` and
+// running `odeva app config link`.
+
+import { Hono } from "hono";
+import { createRemoteJWKSet, jwtVerify } from "jose";
+
+const ODEVA_API_URL = process.env.ODEVA_API_URL ?? "https://booking.odeva.app";
+const ODEVA_APP_CLIENT_ID = process.env.ODEVA_APP_CLIENT_ID;
+
+// Lazily initialised on first request so module load stays side-effect-free.
+let _jwks: ReturnType<typeof createRemoteJWKSet> | null = null;
+
+function getJwks(): ReturnType<typeof createRemoteJWKSet> {
+  if (!_jwks) {
+    _jwks = createRemoteJWKSet(
+      new URL("/.well-known/odeva/apps/jwks.json", ODEVA_API_URL),
+    );
+  }
+  return _jwks;
+}
+
+// Cheap HTML escaping — values come from a verified JWT (Odeva-issued) but
+// defence costs nothing.
+function escape(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+export const adminApp = new Hono();
+
+adminApp.get("/", async (c) => {
+  if (!ODEVA_APP_CLIENT_ID) {
+    return c.text(
+      "Server is missing ODEVA_APP_CLIENT_ID. " +
+        "Set it via `.odeva.env` (managed by `odeva app config link`).",
+      500,
+    );
+  }
+
+  const token = c.req.query("session_token");
+  if (!token) {
+    return c.text("Missing session_token query parameter.", 400);
+  }
+
+  // Session tokens are short-lived (5 minutes). To refresh from your backend,
+  // POST to the refresh endpoint with your installation's api_key:
+  //
+  //   const res = await fetch(`${process.env.ODEVA_API_URL}/api/apps/session-token/refresh`, {
+  //     method: "POST",
+  //     headers: { "X-Api-Key": installationApiKey },
+  //   });
+  //   const { token, expires_at } = await res.json();
+  //
+  // The api_key is the one Odeva minted at install time (see src/install.ts).
+  // NEVER call this from the iframe — the api_key would be exposed to the
+  // browser. Mint a fresh token server-side and hand it to your frontend.
+
+  let payload: { org_id?: unknown; sub?: string };
+  try {
+    const result = await jwtVerify(token, getJwks(), {
+      issuer: ODEVA_API_URL,
+      audience: ODEVA_APP_CLIENT_ID,
+    });
+    payload = result.payload as { org_id?: unknown; sub?: string };
+  } catch {
+    return c.text("Invalid session token.", 401);
+  }
+
+  const rawOrgId = payload.org_id;
+  const rawSub = payload.sub;
+  if (
+    typeof rawOrgId !== "string" ||
+    !rawOrgId ||
+    typeof rawSub !== "string" ||
+    !rawSub
+  ) {
+    return c.text("Invalid session token.", 401);
+  }
+  const orgId = escape(rawOrgId);
+  const installationId = escape(rawSub);
+
+  return c.html(`
+    <!doctype html>
+    <html><head><title>{{name}}</title></head>
+    <body style="font-family: system-ui; max-width: 32rem; margin: 4rem auto; padding: 0 1rem;">
+      <h1>Hello, org ${orgId}</h1>
+      <p>This page was rendered by your app inside the merchant admin iframe.</p>
+      <p>Installation: <code>${installationId}</code></p>
+    </body></html>
+  `);
+});

package/templates/hono-bun/src/index.ts

@@ -1,7 +1,10 @@
 import { Hono } from "hono";
+import { OdevaClient } from "@odeva/booking-sdk";
 import { verifyWebhook } from "./webhook.js";
 import { makeInstallHandler } from "./install.js";
 import { SqliteInstallationStore } from "./installations.js";
+import { logger } from "./logger.js";
+import { adminApp } from "./admin.js";
 
 // Default store: SQLite file next to the app. Swap to your own
 // `InstallationStore` impl (e.g. Postgres) for multi-instance deploys.
@@ -13,29 +16,57 @@ app.get("/", (c) =>
   c.json({
     app: "{{slug}}",
     ok: true,
-    routes: ["GET /", "GET /healthz", "GET /install", "POST /webhooks/:topic"],
+    routes: ["GET /", "GET /healthz", "GET /install", "GET /sdk/accommodations", "GET /admin", "POST /webhooks/:topic"],
   }),
 );
 
 app.get("/healthz", (c) => c.json({ ok: true }));
 
+// SDK example. Set ODEVA_ORGANIZATION_SLUG to query public booking data for an
+// organization, then visit /sdk/accommodations while the app is running.
+app.get("/sdk/accommodations", async (c) => {
+  const organizationSlug = process.env.ODEVA_ORGANIZATION_SLUG;
+  if (!organizationSlug) {
+    return c.json({
+      error: "missing ODEVA_ORGANIZATION_SLUG",
+      hint: "Set ODEVA_ORGANIZATION_SLUG in .odeva.env, then let `odeva app dev` reload.",
+    }, 400);
+  }
+
+  const odeva = new OdevaClient({ organizationSlug });
+  const accommodations = await odeva.searchAccommodations({
+    startDate: "2026-07-01",
+    endDate: "2026-07-08",
+    guests: 2,
+    limit: 5,
+  });
+
+  return c.json({ accommodations });
+});
+
 // Install handshake. Odeva redirects here with `?install_code=...`.
 app.get("/install", makeInstallHandler(installations));
 
+// Admin embed. Verifies the session_token JWT issued by Odeva and renders
+// a page inside the merchant admin sidebar iframe.
+app.route("/admin", adminApp);
+
 // Webhook handler. `odeva app dev` registers subscriptions from odeva.app.toml
 // against the dev tunnel, so payloads from the Odeva platform arrive here.
 app.post("/webhooks/:topic", async (c) => {
   const topic = c.req.param("topic");
   const rawBody = await c.req.text();
   const signature = c.req.header("x-odeva-signature");
-  const secret = process.env.ODEVA_WEBHOOK_SECRET;
+  const secret =
+    process.env[`ODEVA_WEBHOOK_SECRET__${topic.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}`] ??
+    process.env.ODEVA_WEBHOOK_SECRET;
 
   if (secret && !verifyWebhook(rawBody, signature, secret)) {
     return c.json({ error: "invalid signature" }, 401);
   }
 
   const payload = JSON.parse(rawBody) as Record<string, unknown>;
-  console.log(`[webhook] ${topic}`, payload);
+  logger.info(`[webhook] ${topic}`, payload);
 
   // TODO: handle the event.
   // Tip: run `odeva webhook trigger <topic>` to fire a sample payload at this handler.
@@ -44,6 +75,6 @@ app.post("/webhooks/:topic", async (c) => {
 });
 
 const port = Number(process.env.PORT ?? 3000);
-console.log(`{{name}} listening on http://localhost:${port}`);
+logger.info(`{{name}} listening on http://localhost:${port}`);
 
 export default { port, fetch: app.fetch };

package/templates/hono-bun/src/logger.ts

@@ -0,0 +1,20 @@
+import { inspect } from "node:util";
+
+type LogLevel = "info" | "warn" | "error";
+
+function log(level: LogLevel, message: string, details?: unknown): void {
+  const prefix = `[${new Date().toISOString()}] ${level.toUpperCase()} ${message}`;
+  if (details === undefined) {
+    console.log(prefix);
+    return;
+  }
+
+  console.log(prefix);
+  console.log(inspect(details, { colors: true, depth: 6, compact: false }));
+}
+
+export const logger = {
+  info: (message: string, details?: unknown) => log("info", message, details),
+  warn: (message: string, details?: unknown) => log("warn", message, details),
+  error: (message: string, details?: unknown) => log("error", message, details),
+};