@odeva/cli 0.0.3 → 0.0.5

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,30 @@
 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 { loadCredentials } from "../../../lib/credentials.js";
 import { withErrorHandling } from "../../../lib/run.js";
 import { ui } from "../../../lib/ui.js";
+import { ApiError, CliError } from "../../../lib/errors.js";
+import { isValidSlug } from "../../../lib/slug.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 +38,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 +46,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"
       );
@@ -43,28 +65,18 @@ class AppConfigLink extends Command {
         if (match) existingId = match.id;
       }
       spinner.message(existingId ? "Updating app on Odeva" : "Creating app on Odeva");
-      const { app, rawClientSecret } = await api.upsertDeveloperApp({
-        id: existingId,
-        name: loaded.config.name,
-        slug: loaded.config.slug,
-        description: loaded.config.description,
-        homepageUrl: loaded.config.homepage_url,
-        installUrl: loaded.config.install_url,
-        privacyUrl: loaded.config.privacy_url,
-        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.
-      });
+      const { app, rawClientSecret } = await upsertWithSlugRetry(api, spinner, loaded, existingId, adminInput);
       spinner.stop(`${existingId ? "Updated" : "Registered"} app ${ui.code(app.slug)} (client_id ${ui.code(app.clientId)})`);
       loaded.config.client_id = app.clientId;
       saveAppConfig(loaded);
-      let envPath = null;
+      const creds = loadCredentials();
+      const envValues = {
+        ODEVA_APP_CLIENT_ID: app.clientId,
+        ...rawClientSecret ? { ODEVA_APP_CLIENT_SECRET: rawClientSecret } : {},
+        ...creds?.organizationSlug ? { ODEVA_ORGANIZATION_SLUG: creds.organizationSlug } : {}
+      };
+      const envPath = saveAppEnv(loaded.path, envValues);
       if (rawClientSecret) {
-        envPath = saveAppEnv(loaded.path, {
-          ODEVA_APP_CLIENT_ID: app.clientId,
-          ODEVA_APP_CLIENT_SECRET: rawClientSecret
-        });
         p.note(
           [
             "This is the only time the secret is shown.",
@@ -80,7 +92,8 @@ class AppConfigLink extends Command {
       p.outro(
         [
           ui.ok(`Wrote client_id to ${ui.code(loaded.path)}`),
-          envPath ? ui.ok(`Wrote client_secret to ${ui.code(envPath)}`) : null,
+          rawClientSecret ? ui.ok(`Wrote client_secret to ${ui.code(envPath)}`) : null,
+          creds?.organizationSlug ? ui.ok(`Wrote organization slug to ${ui.code(envPath)}`) : null,
           "",
           `  Next: ${ui.code("odeva app dev")} to run the app locally with a public tunnel.`
         ].filter((line) => line !== null).join("\n")
@@ -88,6 +101,51 @@ class AppConfigLink extends Command {
     });
   }
 }
+const SLUG_TAKEN_RE = /slug.*(?:already been taken|taken|in use|exists)/i;
+async function upsertWithSlugRetry(api, spinner, loaded, existingId, adminInput) {
+  for (; ; ) {
+    try {
+      return await api.upsertDeveloperApp({
+        id: existingId,
+        name: loaded.config.name,
+        slug: loaded.config.slug,
+        description: loaded.config.description,
+        homepageUrl: loaded.config.homepage_url,
+        installUrl: loaded.config.install_url,
+        privacyUrl: loaded.config.privacy_url,
+        requestedScopes: loaded.config.access_scopes?.scopes,
+        ...adminInput ? { adminEmbed: adminInput } : {}
+      });
+    } catch (err) {
+      if (!(err instanceof ApiError) || !SLUG_TAKEN_RE.test(err.message)) throw err;
+      spinner.stop(ui.warn(`Slug '${loaded.config.slug}' is already taken.`));
+      const creds = loadCredentials();
+      const suggestion = creds?.organizationSlug && !loaded.config.slug.startsWith(`${creds.organizationSlug}-`) ? `${creds.organizationSlug}-${loaded.config.slug}` : `${loaded.config.slug}-2`;
+      const next = await p.text({
+        message: "Pick a new slug",
+        placeholder: suggestion,
+        initialValue: suggestion,
+        validate: (v) => {
+          const trimmed = v.trim();
+          if (!isValidSlug(trimmed)) {
+            return "Slugs are lowercase letters, digits, and hyphens (e.g. 'cabin-manager').";
+          }
+          if (trimmed === loaded.config.slug) {
+            return "Pick a different slug than the one that's taken.";
+          }
+          return void 0;
+        }
+      });
+      if (p.isCancel(next)) {
+        throw new CliError("link cancelled.");
+      }
+      loaded.config.slug = next.trim();
+      saveAppConfig(loaded);
+      spinner.start(existingId ? "Updating app on Odeva" : "Creating app on Odeva");
+    }
+  }
+}
 export {
+  buildAdminEmbedInput,
   AppConfigLink as default
 };

package/dist/commands/app/dev.js

@@ -5,6 +5,8 @@ import { OdevaApi } from "../../lib/api.js";
 import { loadAppConfig } from "../../lib/config.js";
 import { loadAppEnv } from "../../lib/app-env.js";
 import { startQuickTunnel } from "../../lib/cloudflared.js";
+import { loadCredentials } from "../../lib/credentials.js";
+import { adminUrl } from "../../lib/paths.js";
 import {
   cleanupSubscriptions,
   preflightChecks,
@@ -64,6 +66,7 @@ class AppDev extends Command {
         this.log(`  ${ui.dim("\u2192")} ${reg.config.topic.padEnd(28)} ${reg.fullUrl}`);
       }
       this.log("");
+      this.printInstallHint(loaded, tunnel.url);
       this.log(ui.dim("Press Ctrl-C to stop. Subscriptions will be cleaned up on exit."));
       this.log("");
       let server = spawnDevServer({
@@ -142,6 +145,26 @@ class AppDev extends Command {
       await Promise.allSettled([tunnel.stop(), cleanupSubscriptions(api, registered)]);
     });
   }
+  printInstallHint(loaded, tunnelUrl) {
+    const creds = loadCredentials();
+    const apps = adminUrl(creds?.apiUrl);
+    this.log(`${ui.bold("Install:")}    ${apps}/settings/apps  ${ui.dim('(find your draft app under "Your apps")')}`);
+    if (creds?.organizationSlug) {
+      this.log(`  ${ui.dim("org:")}      ${creds.organizationSlug}`);
+    }
+    const installUrl = loaded.config.install_url?.trim();
+    const expected = `${tunnelUrl}/install`;
+    if (!installUrl) {
+      this.log(ui.warn(
+        `install_url in odeva.app.toml is empty \u2014 installs won't redirect back. Set it to ${expected} and re-run \`odeva app config link\` (or use a stable URL once you deploy).`
+      ));
+    } else if (!installUrl.startsWith(tunnelUrl) && !/localhost|127\.0\.0\.1/.test(installUrl)) {
+      this.log(ui.warn(
+        `install_url is ${installUrl} \u2014 installs from your org will redirect there, not to this tunnel. Update odeva.app.toml + \`odeva app config link\` if you want installs to hit the dev tunnel.`
+      ));
+    }
+    this.log("");
+  }
   async registerDevWebhooks(api, loaded, tunnelUrl) {
     const subscriptions = loaded.config.webhooks?.subscriptions ?? [];
     if (subscriptions.length === 0) {

package/dist/commands/app/init.js

@@ -2,6 +2,8 @@ import { Args, Command, Flags } from "@oclif/core";
 import * as p from "@clack/prompts";
 import { existsSync } from "node:fs";
 import { basename, resolve } from "node:path";
+import { OdevaApi } from "../../lib/api.js";
+import { loadCredentials } from "../../lib/credentials.js";
 import { CliError } from "../../lib/errors.js";
 import { withErrorHandling } from "../../lib/run.js";
 import { isValidSlug, slugify } from "../../lib/slug.js";
@@ -43,8 +45,12 @@ class AppInit extends Command {
     await withErrorHandling(this, async () => {
       p.intro(ui.brand("odeva app init"));
       const directory = await this.resolveDirectory(args.name, flags.yes);
-      const slug = this.resolveSlug(flags.slug ?? slugify(basename(directory)));
       const displayName = flags["display-name"] ?? toTitleCase(basename(directory));
+      const slug = await this.resolveSlug({
+        explicit: flags.slug,
+        dirBase: basename(directory),
+        skipPrompts: flags.yes
+      });
       const template = flags.template;
       if (!listTemplates().includes(template)) {
         throw new CliError(`Unknown template: '${template}'.`, {
@@ -106,14 +112,63 @@ class AppInit extends Command {
     }
     return directory;
   }
-  resolveSlug(candidate) {
-    const slug = candidate.trim();
-    if (!isValidSlug(slug)) {
-      throw new CliError(`Invalid slug '${slug}'.`, {
-        hint: "Slugs are lowercase letters, digits, and hyphens (e.g. 'cabin-manager')."
+  async resolveSlug(opts) {
+    const creds = loadCredentials();
+    const orgSlug = creds?.organizationSlug;
+    const derived = slugify(opts.dirBase);
+    const initial = opts.explicit?.trim() || (orgSlug ? `${orgSlug}-${derived}` : derived);
+    validateSlug(initial);
+    if (opts.explicit || opts.skipPrompts || !creds) {
+      if (creds && opts.explicit) await assertAvailable(initial);
+      return initial;
+    }
+    let candidate = initial;
+    const api = new OdevaApi({ credentials: creds });
+    for (; ; ) {
+      const available = await isAvailable(api, candidate);
+      if (available !== false) return candidate;
+      const next = await p.text({
+        message: `Slug '${candidate}' is already taken \u2014 pick another`,
+        placeholder: `${candidate}-2`,
+        initialValue: `${candidate}-2`,
+        validate: (v) => {
+          const trimmed = v.trim();
+          if (!isValidSlug(trimmed)) {
+            return "Slugs are lowercase letters, digits, and hyphens (e.g. 'cabin-manager').";
+          }
+          return void 0;
+        }
       });
+      if (p.isCancel(next)) {
+        throw new CliError("init cancelled.");
+      }
+      candidate = next.trim();
     }
-    return slug;
+  }
+}
+function validateSlug(slug) {
+  if (!isValidSlug(slug)) {
+    throw new CliError(`Invalid slug '${slug}'.`, {
+      hint: "Slugs are lowercase letters, digits, and hyphens (e.g. 'cabin-manager')."
+    });
+  }
+}
+async function isAvailable(api, slug) {
+  try {
+    return await api.developerAppSlugAvailable(slug);
+  } catch {
+    return null;
+  }
+}
+async function assertAvailable(slug) {
+  const creds = loadCredentials();
+  if (!creds) return;
+  const api = new OdevaApi({ credentials: creds });
+  const ok = await isAvailable(api, slug);
+  if (ok === false) {
+    throw new CliError(`Slug '${slug}' is already taken.`, {
+      hint: "Choose another with --slug, or omit --slug to be prompted."
+    });
   }
 }
 function toTitleCase(input) {

package/dist/commands/autocomplete.js

@@ -0,0 +1,158 @@
+import { Args, Command } from "@oclif/core";
+import { CliError } from "../lib/errors.js";
+import { withErrorHandling } from "../lib/run.js";
+const SUPPORTED_SHELLS = ["fish", "zsh"];
+class Autocomplete extends Command {
+  static description = "Print a shell completion script for the odeva CLI";
+  static examples = [
+    "$ odeva autocomplete fish > ~/.config/fish/completions/odeva.fish",
+    "$ odeva autocomplete zsh > ~/.odeva/_odeva  # then source it from .zshrc"
+  ];
+  static args = {
+    shell: Args.string({
+      description: "Target shell",
+      options: [...SUPPORTED_SHELLS],
+      required: true
+    })
+  };
+  async run() {
+    const { args } = await this.parse(Autocomplete);
+    await withErrorHandling(this, async () => {
+      const shell = args.shell;
+      if (!SUPPORTED_SHELLS.includes(shell)) {
+        throw new CliError(`Unsupported shell '${shell}'.`, {
+          hint: `Supported: ${SUPPORTED_SHELLS.join(", ")}.`
+        });
+      }
+      const bin = this.config.bin;
+      const tree = buildCommandTree(this.config.commands, bin);
+      const script = shell === "fish" ? renderFish(bin, tree) : renderZsh(bin, tree);
+      process.stdout.write(script);
+    });
+  }
+}
+function buildCommandTree(commands, binName) {
+  const root = { name: "", description: "", children: /* @__PURE__ */ new Map() };
+  for (const cmd of commands) {
+    if (cmd.hidden || cmd.id === "autocomplete") continue;
+    const segments = cmd.id.split(":");
+    let node = root;
+    for (let i = 0; i < segments.length; i++) {
+      const seg = segments[i];
+      const isLeaf = i === segments.length - 1;
+      let child = node.children.get(seg);
+      if (!child) {
+        child = { name: seg, description: "", children: /* @__PURE__ */ new Map() };
+        node.children.set(seg, child);
+      }
+      if (isLeaf) {
+        child.command = cmd;
+        const rawDesc = cmd.summary || cmd.description?.split("\n")[0] || "";
+        child.description = rawDesc.replace(/<%=\s*config\.bin\s*%>/g, binName);
+      }
+      node = child;
+    }
+  }
+  return root;
+}
+function shellSingleQuote(s) {
+  return `'${s.replace(/'/g, "'\\''")}'`;
+}
+function renderFish(bin, root) {
+  const lines = [
+    `# fish completion for ${bin}`,
+    `# Generated by \`${bin} autocomplete fish\``,
+    "",
+    `function __${bin}_at_path`,
+    "    # Returns 0 if the current command line is exactly `bin arg1 arg2 ...`",
+    "    set -l tokens (commandline -opc)",
+    "    set -e tokens[1]",
+    "    test (count $tokens) -eq (count $argv); or return 1",
+    "    for i in (seq (count $argv))",
+    '        test "$tokens[$i]" = "$argv[$i]"; or return 1',
+    "    end",
+    "    return 0",
+    "end",
+    ""
+  ];
+  const walk = (node, path) => {
+    if (node.children.size > 0) {
+      const condition = path.length === 0 ? `__${bin}_at_path` : `__${bin}_at_path ${path.join(" ")}`;
+      for (const child of node.children.values()) {
+        const desc = child.description.replace(/\s+/g, " ").trim();
+        const descPart = desc ? ` -d ${shellSingleQuote(desc)}` : "";
+        lines.push(`complete -c ${bin} -n ${shellSingleQuote(condition)} -f -a ${shellSingleQuote(child.name)}${descPart}`);
+      }
+    }
+    if (node.command) {
+      const condition = `__${bin}_at_path ${path.join(" ")}`;
+      for (const [flagName, flag] of Object.entries(node.command.flags)) {
+        if (flag.hidden) continue;
+        const desc = (flag.summary || flag.description || "").replace(/\s+/g, " ").trim();
+        const descPart = desc ? ` -d ${shellSingleQuote(desc)}` : "";
+        const takesValue = flag.type === "option" ? " -r" : "";
+        const short = flag.char ? ` -s ${flag.char}` : "";
+        lines.push(`complete -c ${bin} -n ${shellSingleQuote(condition)} -l ${flagName}${short}${takesValue}${descPart}`);
+      }
+    }
+    for (const child of node.children.values()) {
+      walk(child, [...path, child.name]);
+    }
+  };
+  walk(root, []);
+  return lines.join("\n") + "\n";
+}
+function renderZsh(bin, root) {
+  const dispatch = [];
+  const collect = (node, path) => {
+    const key = path.join(" ");
+    const subcommands = [];
+    for (const child of node.children.values()) {
+      const desc = child.description.replace(/[:\s]+/g, " ").trim();
+      subcommands.push(`'${child.name}:${desc}'`);
+    }
+    const flagLines = [];
+    if (node.command) {
+      for (const [flagName, flag] of Object.entries(node.command.flags)) {
+        if (flag.hidden) continue;
+        const desc = (flag.summary || flag.description || "").replace(/[:[\]]/g, " ").trim();
+        const arg = flag.type === "option" ? ":value:" : "";
+        flagLines.push(`'--${flagName}[${desc}]${arg}'`);
+        if (flag.char) flagLines.push(`'-${flag.char}[${desc}]${arg}'`);
+      }
+    }
+    dispatch.push(
+      `    ${shellSingleQuote(key)})`,
+      `      _values 'subcommand or flag' ${[...subcommands, ...flagLines].join(" ")}`,
+      `      ;;`
+    );
+    for (const child of node.children.values()) {
+      collect(child, [...path, child.name]);
+    }
+  };
+  collect(root, []);
+  return `#compdef ${bin}
+# zsh completion for ${bin}
+# Generated by \`${bin} autocomplete zsh\`
+
+_${bin}() {
+  local -a words
+  words=("\${(@)words[2,$CURRENT - 1]}")
+  local key="\${(j: :)words}"
+  case "$key" in
+${dispatch.join("\n")}
+    *)
+      _values 'subcommand'
+      ;;
+  esac
+}
+
+_${bin} "$@"
+`;
+}
+export {
+  buildCommandTree,
+  Autocomplete as default,
+  renderFish,
+  renderZsh
+};

package/dist/lib/api.js

@@ -89,6 +89,21 @@ class OdevaApi {
     );
     return data.cliAuthPoll;
   }
+  /**
+   * Check whether a developer-app slug is free. Returns `null` when the CLI
+   * isn't authenticated yet (init can be invoked before `auth login`) so
+   * callers can fall back to local validation instead of bailing.
+   */
+  async developerAppSlugAvailable(slug, excludeId) {
+    if (!this.authenticated) return null;
+    const data = await this.request(
+      `query OdevaCliDeveloperAppSlugAvailable($slug: String!, $excludeId: ID) {
+        developerAppSlugAvailable(slug: $slug, excludeId: $excludeId)
+      }`,
+      { slug, excludeId }
+    );
+    return data.developerAppSlugAvailable;
+  }
   async listDeveloperApps() {
     const data = await this.request(`
       query OdevaCliListDeveloperApps {
@@ -153,6 +168,7 @@ class OdevaApi {
         $privacyUrl: String
         $requestedScopes: [String!]
         $webhookUrl: String
+        $adminEmbed: AdminEmbedInput
       ) {
         upsertDeveloperApp(
           id: $id
@@ -165,6 +181,7 @@ class OdevaApi {
           privacyUrl: $privacyUrl
           requestedScopes: $requestedScopes
           webhookUrl: $webhookUrl
+          adminEmbed: $adminEmbed
         ) {
           app {
             id

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) {
@@ -59,8 +70,60 @@ function validateConfig(config, path) {
       };
     });
   }
+  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/paths.js

@@ -5,9 +5,16 @@ const CONFIG_DIR = join(xdgConfigHome, "odeva");
 const CREDENTIALS_PATH = join(CONFIG_DIR, "credentials.json");
 const APP_CONFIG_FILE = "odeva.app.toml";
 const DEFAULT_API_URL = process.env["ODEVA_API_URL"] || "https://booking.odeva.app";
+function adminUrl(apiUrl = DEFAULT_API_URL) {
+  const override = process.env["ODEVA_ADMIN_URL"];
+  if (override) return override.replace(/\/$/, "");
+  const base = apiUrl.replace(/\/$/, "");
+  return /localhost|127\.0\.0\.1/.test(base) ? base : `${base}/admin`;
+}
 export {
   APP_CONFIG_FILE,
   CONFIG_DIR,
   CREDENTIALS_PATH,
-  DEFAULT_API_URL
+  DEFAULT_API_URL,
+  adminUrl
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odeva/cli",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "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

@@ -4,6 +4,7 @@ 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.
@@ -15,7 +16,7 @@ app.get("/", (c) =>
   c.json({
     app: "{{slug}}",
     ok: true,
-    routes: ["GET /", "GET /healthz", "GET /install", "GET /sdk/accommodations", "POST /webhooks/:topic"],
+    routes: ["GET /", "GET /healthz", "GET /install", "GET /sdk/accommodations", "GET /admin", "POST /webhooks/:topic"],
   }),
 );
 
@@ -46,6 +47,10 @@ app.get("/sdk/accommodations", async (c) => {
 // 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) => {