create-fedi-app 0.1.2 → 0.1.4

package/README.md

@@ -0,0 +1,161 @@
+# create-fedi-app
+
+CLI scaffolder for [Fedi](https://www.fedi.xyz) Bitcoin mini apps on **Next.js 16**. It copies a production-ready base template, merges optional feature modules (Lightning payments, Nostr identity, AI chat, LNURL, and more), and writes the env vars and dependencies each module needs.
+
+Generated apps run inside Fedi's in-app browser with access to `window.webln`, `window.nostr`, and `window.fediInternal`, and degrade cleanly when opened in a normal browser. Each project includes a `.gitignore` for Next.js, env files, and Vercel artifacts.
+
+## Quick start
+
+```bash
+npx create-fedi-app@latest
+```
+
+Follow the prompts for project name, database adapter, optional modules, and package manager. Then:
+
+```bash
+cd my-fedi-app
+cp .env.example .env.local   # optional for base-only projects
+bun install                  # or pnpm / npm
+bun dev
+```
+
+Open `http://localhost:3000`. Use the **Fedi Dev Toolbar** (bottom-right, dev only) to toggle mock WebLN and mock Nostr without the wallet.
+
+**Full documentation:** [create-fedi-app.keeganfrancis.com/docs](https://create-fedi-app.keeganfrancis.com/docs)
+
+## Modules
+
+Three modules are always included. The rest are optional at scaffold time.
+
+| Name | Description | Requires |
+|------|-------------|----------|
+| `webln-payments` | Send and receive Lightning payments via `window.webln` | Always included |
+| `nostr-identity` | NIP-07 identity connection and signed messages | Always included |
+| `ecash-balance` | Fedi ecash balance and `fediInternal` API demos | Always included |
+| `payment-gated-content` | Lock content behind a Lightning invoice with signed access cookies | `webln-payments` |
+| `lnurl` | LNURL-pay, LNURL-auth, and LNURL-withdraw flows | — |
+| `ai-chat-gated` | AI chat where each message costs sats via WebLN | `webln-payments`, `AI_PROVIDER`, `AI_API_KEY` |
+| `ai-assistant` | Free AI assistant using the Vercel AI SDK | `AI_PROVIDER`, `AI_API_KEY` |
+| `multispend-demo` | Threshold spending UI with Nostr-signed approvals | `nostr-identity` |
+| `nostr-feed` | Read, publish, and zap Nostr notes | `nostr-identity` |
+| `database` | Drizzle ORM CRUD example (Turso or Supabase) | Turso or Supabase selected at scaffold time |
+| `ai-rules` | Agent-readable `.ai/rules/` context for Cursor, Claude Code, and Copilot | — |
+
+## Local development (before deploy)
+
+1. **Mock providers** — On `/demo/webln` and `/demo/nostr`, enable mocks in the dev toolbar and exercise pay/sign flows without Lightning.
+2. **Unit tests** — `bun test` (Vitest). Optional E2E: `bun run test:e2e` (Playwright).
+3. **Production build locally** — `bun run build && bun start` (mocks are off in production).
+
+## Deploy on Vercel
+
+Mini apps are standard Next.js apps served over **HTTPS**. Vercel is the recommended host.
+
+### 1. Push to GitHub
+
+```bash
+git init
+git add .
+git commit -m "Initial Fedi mini app"
+git remote add origin https://github.com/you/my-fedi-app.git
+git push -u origin main
+```
+
+### 2. Import the project
+
+1. Go to [vercel.com/new](https://vercel.com/new) and import your repository.
+2. **Framework preset:** Next.js
+3. **Root directory:** project root (where `package.json` lives)
+4. Leave the default build command (`next build`) and output settings.
+
+### 3. Set environment variables
+
+In Vercel → **Settings** → **Environment Variables**, add every key from `.env.local` that your modules need:
+
+| Variable | When required |
+|----------|----------------|
+| `PAYMENT_GATE_SECRET` | `payment-gated-content` |
+| `AI_PROVIDER`, `AI_API_KEY` | `ai-chat-gated` or `ai-assistant` |
+| `DATABASE_URL` | Turso or Supabase database module |
+| `LNURL_SERVER_URL` | `lnurl` — use your **production** URL (not `localhost`) |
+| `NEXT_PUBLIC_NOSTR_RELAY` | `nostr-feed` (optional override) |
+
+Use long random values for secrets in production. Do not commit `.env.local`.
+
+### 4. Deploy
+
+Vercel deploys on every push to `main` and creates preview URLs for pull requests. Confirm your production URL loads over HTTPS (required by Fedi).
+
+If you use the **lnurl** module, set:
+
+```bash
+LNURL_SERVER_URL=https://your-production-domain.vercel.app
+```
+
+## Test inside the Fedi mini app ecosystem
+
+Fedi injects `window.webln`, `window.nostr`, and `window.fediInternal` in its mobile WebView. Your deployed app must be reachable over **HTTPS** (or your phone's LAN IP during local testing).
+
+### Before catalog listing (development)
+
+1. Install Fedi: [fedi.xyz/get-the-app](https://fedi.xyz/get-the-app)
+2. Join a **Mutinynet** test federation — [Fedi Fedimint intro](https://fedibtc.github.io/fedi-docs/docs/fedimint/intro/)
+3. In Fedi → **Settings** → **Developer** (or **Custom Mini Apps**), add your app URL:
+   - **Deployed:** `https://your-app.vercel.app`
+   - **Local on device:** `http://<your-computer-lan-ip>:3000` (same Wi‑Fi; Fedi cannot reach `localhost` on your laptop)
+   - **Remote dev:** a tunnel URL (e.g. ngrok) pointing at port 3000
+4. Open the mini app from Fedi's app list.
+
+### In-wallet checklist
+
+- [ ] App loads in the WebView without horizontal scroll
+- [ ] `/demo/webln` — real Lightning payment on Mutinynet
+- [ ] `/demo/nostr` — connect identity and sign a message
+- [ ] `/demo/ecash` — fediInternal version badge; Load installed apps after granting `manageInstalledMiniApps`
+- [ ] Safe area / notch padding looks correct
+
+Use **Mutinynet test sats**, not mainnet, while developing.
+
+### Programmatic install (`fediInternal` v2)
+
+The `ecash-balance` module includes `InstallMiniAppButton`, which calls:
+
+```typescript
+await window.fediInternal?.installMiniApp({
+  id: 'my-app',
+  title: 'My App',
+  url: 'https://your-app.vercel.app',
+  imageUrl: 'https://your-app.vercel.app/icon.png',
+  description: 'One-line description',
+});
+```
+
+This only works inside Fedi when API v2 is available. Requires the user to grant **`manageInstalledMiniApps`** when prompted.
+
+### Publish to the Fedi catalog
+
+For wallet discovery beyond custom URLs, submit to the official catalog:
+
+**[Catalog submission form](https://docs.google.com/forms/d/e/1FAIpQLSfrvsoeaNYiGhoc8QwzLXEi4zMFVyxpa4ufJFTwEHp97AeUmQ/viewform)**
+
+Prepare: app name, production HTTPS URL, short description, square icon (min 256×256), mobile screenshots, and category. Reference: [fedibtc/catalog](https://github.com/fedibtc/catalog).
+
+## Pre-ship checklist
+
+- [ ] All required env vars set on Vercel
+- [ ] `PAYMENT_GATE_SECRET` is a strong random string (not a dev default)
+- [ ] `LNURL_SERVER_URL` matches your production domain (if using lnurl)
+- [ ] App tested on Mutinynet inside Fedi
+- [ ] Icon and metadata ready for catalog review
+
+## Links
+
+- [Documentation](https://create-fedi-app.keeganfrancis.com/docs)
+- [Quickstart](https://create-fedi-app.keeganfrancis.com/docs/quickstart)
+- [Deployment guide](https://create-fedi-app.keeganfrancis.com/docs/deployment)
+- [Source repository](https://github.com/keegan-lee/create-fedi-app)
+- [Fedi developer docs](https://fedibtc.github.io/fedi-docs/)
+
+## License
+
+MIT

package/dist/index.js

@@ -2921,13 +2921,22 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "create-fedi-app",
-      version: "0.1.2",
+      version: "0.1.4",
       description: "CLI scaffolder for Fedi Bitcoin mini apps",
       bin: {
         "create-fedi-app": "./dist/index.js"
       },
       files: ["dist/"],
       keywords: ["fedi", "fedimint", "bitcoin", "lightning", "webln", "nostr", "mini-app", "nextjs"],
+      homepage: "https://create-fedi-app.keeganfrancis.com/docs",
+      repository: {
+        type: "git",
+        url: "git+https://github.com/keegan-lee/create-fedi-app.git",
+        directory: "apps/cli"
+      },
+      bugs: {
+        url: "https://github.com/keegan-lee/create-fedi-app/issues"
+      },
       license: "MIT",
       scripts: {
         build: "tsup && rm -rf dist/templates && cp -R ../../templates dist/templates",
@@ -3623,6 +3632,12 @@ var import_path3 = __toESM(require("path"));
 
 // src/parse-args.ts
 init_cjs_shims();
+
+// src/types.ts
+init_cjs_shims();
+var DEFAULT_LNURL_PAY_ADDRESS = "lnurl1dp68gurn8ghj7un9vd6hyunfdenkgtnrw3exytnfduhkcmnkxyhhqctevdhkgetn9uenzvmxv33kyefj8yerqefk8p3rvd34x93nvdr9vvukgcfexcergv3jxc6kgcm9x4jxydenxvengwf48q6rxwpsxf3ryctpvvenwefswhw4au";
+
+// src/parse-args.ts
 var ALL_MODULES = [
   "payment-gated-content",
   "lnurl",
@@ -3689,13 +3704,15 @@ function parseCliArgs(argv) {
   if (!PM_SET.has(packageManagerRaw)) {
     throw new Error(`Invalid --package-manager: ${packageManagerRaw}`);
   }
+  const lnurlPayAddress = getFlagValue(argv, "--lnurl-pay-address") ?? DEFAULT_LNURL_PAY_ADDRESS;
   return {
     projectName,
     database,
     modules,
     includeAiRules,
     aiProvider,
-    packageManager: packageManagerRaw
+    packageManager: packageManagerRaw,
+    lnurlPayAddress
   };
 }
 
@@ -3782,13 +3799,27 @@ async function promptUser() {
       ]
     })
   );
+  const lnurlPayAddress = cancelCheck(
+    await ue({
+      message: "LNURL pay address (demo payments destination)",
+      defaultValue: DEFAULT_LNURL_PAY_ADDRESS,
+      placeholder: "lnurl1\u2026",
+      validate: (v2) => {
+        const value = (v2 || DEFAULT_LNURL_PAY_ADDRESS).trim();
+        if (!value.toLowerCase().startsWith("lnurl") && !value.startsWith("http")) {
+          return "Enter a bech32 LNURL (lnurl1\u2026) or HTTPS LNURL-pay endpoint";
+        }
+      }
+    })
+  );
   return {
     projectName: projectName || "my-fedi-app",
     database,
     modules: modules ?? [],
     includeAiRules,
     aiProvider,
-    packageManager
+    packageManager,
+    lnurlPayAddress: (lnurlPayAddress || DEFAULT_LNURL_PAY_ADDRESS).trim()
   };
 }
 
@@ -3857,7 +3888,7 @@ var MODULE_DEMO_ROUTES = {
   "ecash-balance": {
     href: "/demo/ecash",
     title: "Ecash Balance",
-    description: "Read Fedi ecash balance and install mini app prompts."
+    description: "fediInternal mini-app discovery, list, and install prompts."
   },
   "payment-gated-content": {
     href: "/demo/payment-gated",
@@ -4050,7 +4081,24 @@ async function generateEnvLocal(selections, targetDir, templatesDir) {
     }
   }
   const content = example + (extraLines.length > 0 ? "\n" + extraLines.join("\n") + "\n" : "");
-  await import_fs_extra2.default.writeFile(envLocal, content, "utf-8");
+  const paymentReplacements = [
+    [/^LNURL_PAY_ADDRESS=.*$/m, `LNURL_PAY_ADDRESS=${selections.lnurlPayAddress}`],
+    [
+      /^NEXT_PUBLIC_LNURL_PAY_ADDRESS=.*$/m,
+      `NEXT_PUBLIC_LNURL_PAY_ADDRESS=${selections.lnurlPayAddress}`
+    ]
+  ];
+  let finalContent = content;
+  for (const [pattern, replacement] of paymentReplacements) {
+    finalContent = finalContent.replace(pattern, replacement);
+  }
+  await import_fs_extra2.default.writeFile(envLocal, finalContent, "utf-8");
+}
+async function applyGitignore(baseDir, targetDir) {
+  const src = import_path2.default.join(baseDir, "gitignore");
+  if (!await import_fs_extra2.default.pathExists(src)) return;
+  await import_fs_extra2.default.copy(src, import_path2.default.join(targetDir, ".gitignore"), { overwrite: true });
+  await import_fs_extra2.default.remove(import_path2.default.join(targetDir, "gitignore"));
 }
 async function scaffold(selections, targetDir) {
   const templatesDir = getTemplatesDir();
@@ -4058,6 +4106,7 @@ async function scaffold(selections, targetDir) {
   await import_fs_extra2.default.ensureDir(targetDir);
   if (await import_fs_extra2.default.pathExists(baseDir)) {
     await import_fs_extra2.default.copy(baseDir, targetDir, { overwrite: true });
+    await applyGitignore(baseDir, targetDir);
   }
   await replaceInFiles(targetDir, [
     ["{{PROJECT_NAME}}", selections.projectName],
@@ -11087,7 +11136,7 @@ function printNextSteps(selections) {
       `\u25B8 Add http://localhost:3000 as a custom Mini App in Fedi`,
       `\u25B8 window.webln and window.nostr are now injected`,
       ``,
-      `Docs: https://fedi.keeganfrancis.com/docs`
+      `Docs: https://create-fedi-app.keeganfrancis.com/docs`
     ].join("\n"),
     "Next steps"
   );
@@ -11124,7 +11173,7 @@ Interactive prompts:
   5. AI provider (if AI modules selected)
   6. Package manager: bun | pnpm | npm
 
-Docs: https://fedi.keeganfrancis.com/docs`);
+Docs: https://create-fedi-app.keeganfrancis.com/docs`);
 }
 async function main() {
   if (process.argv.includes("--help") || process.argv.includes("-h")) {
@@ -11200,9 +11249,9 @@ async function main() {
   }
   printNextSteps(selections);
   if (nonInteractive) {
-    console.log("Happy building. Docs: https://fedi.keeganfrancis.com/docs");
+    console.log("Happy building. Docs: https://create-fedi-app.keeganfrancis.com/docs");
   } else {
-    fe("Happy building. Docs: https://fedi.keeganfrancis.com/docs");
+    fe("Happy building. Docs: https://create-fedi-app.keeganfrancis.com/docs");
   }
 }
 main().catch((err) => {

package/dist/templates/base/.env.example

@@ -1,5 +1,18 @@
 # App
 NEXT_PUBLIC_APP_NAME="{{PROJECT_NAME}}"
 
+# Lightning demo payments (create-fedi-app maintainer test wallet)
+# Server-side LNURL address for invoice generation
+LNURL_PAY_ADDRESS=lnurl1dp68gurn8ghj7un9vd6hyunfdenkgtnrw3exytnfduhkcmnkxyhhqctevdhkgetn9uenzvmxv33kyefj8yerqefk8p3rvd34x93nvdr9vvukgcfexcergv3jxc6kgcm9x4jxydenxvengwf48q6rxwpsxf3ryctpvvenwefswhw4au
+# Client-visible LNURL for QR codes and UI callouts
+NEXT_PUBLIC_LNURL_PAY_ADDRESS=lnurl1dp68gurn8ghj7un9vd6hyunfdenkgtnrw3exytnfduhkcmnkxyhhqctevdhkgetn9uenzvmxv33kyefj8yerqefk8p3rvd34x93nvdr9vvukgcfexcergv3jxc6kgcm9x4jxydenxvengwf48q6rxwpsxf3ryctpvvenwefswhw4au
+# Demo payment amounts (sats) — adjust in .env.local after scaffolding
+# WebLN demo: default invoice amount on /demo/webln
+NEXT_PUBLIC_DEMO_WEBLN_SATS=21
+# Payment gate: unlock price for /demo/payment-gated
+NEXT_PUBLIC_DEMO_GATE_SATS=7
+# LNURL-withdraw: payout amount on /demo/lnurl
+NEXT_PUBLIC_DEMO_LNURL_SATS=1
+
 # Add module-specific variables below
 # (populated by CLI based on selected modules)

package/dist/templates/base/app/page.tsx

@@ -1,18 +1,102 @@
 'use client';
 
 import Link from 'next/link';
+import { useState } from 'react';
 import { useWebLN } from '../lib/webln';
 import { useNostr } from '../lib/nostr';
 import { cn } from '../lib/utils';
 
 function ConnectionStatus() {
-  const { provider: weblnProvider, isLoading: weblnLoading } = useWebLN();
-  const { provider: nostrProvider, isLoading: nostrLoading } = useNostr();
+  const {
+    isAvailable: weblnAvailable,
+    isConnected: weblnConnected,
+    isLoading: weblnLoading,
+    connect: connectWebLN,
+    error: weblnError,
+  } = useWebLN();
+  const {
+    isAvailable: nostrAvailable,
+    isConnected: nostrConnected,
+    isLoading: nostrLoading,
+    connect: connectNostr,
+    error: nostrError,
+  } = useNostr();
+  const [isConnectingWebLN, setIsConnectingWebLN] = useState(false);
+  const [isConnectingNostr, setIsConnectingNostr] = useState(false);
+
+  async function handleConnectWebLN() {
+    setIsConnectingWebLN(true);
+    try {
+      await connectWebLN();
+    } finally {
+      setIsConnectingWebLN(false);
+    }
+  }
+
+  async function handleConnectNostr() {
+    setIsConnectingNostr(true);
+    try {
+      await connectNostr();
+    } finally {
+      setIsConnectingNostr(false);
+    }
+  }
 
   return (
-    <div className="flex flex-wrap gap-2">
-      <StatusPill label="WebLN" active={!!weblnProvider} loading={weblnLoading} />
-      <StatusPill label="Nostr" active={!!nostrProvider} loading={nostrLoading} />
+    <div className="space-y-3">
+      <div className="flex flex-wrap gap-2">
+        <StatusPill
+          label="WebLN"
+          active={weblnConnected}
+          loading={weblnLoading}
+          available={weblnAvailable}
+        />
+        <StatusPill
+          label="Nostr"
+          active={nostrConnected}
+          loading={nostrLoading}
+          available={nostrAvailable}
+        />
+      </div>
+
+      <div className="flex flex-wrap gap-2">
+        {weblnAvailable && !weblnConnected && (
+          <button
+            type="button"
+            onClick={() => void handleConnectWebLN()}
+            disabled={isConnectingWebLN || weblnLoading}
+            className="rounded-lg px-3 py-1.5 text-xs font-semibold transition-opacity duration-200 hover:opacity-80 disabled:opacity-40"
+            style={{
+              background: 'var(--color-surface-1)',
+              border: '1px solid var(--color-border)',
+              color: 'var(--color-text)',
+            }}
+          >
+            {isConnectingWebLN ? 'Connecting WebLN…' : 'Connect WebLN'}
+          </button>
+        )}
+        {nostrAvailable && !nostrConnected && (
+          <button
+            type="button"
+            onClick={() => void handleConnectNostr()}
+            disabled={isConnectingNostr || nostrLoading}
+            className="rounded-lg px-3 py-1.5 text-xs font-semibold transition-opacity duration-200 hover:opacity-80 disabled:opacity-40"
+            style={{
+              background: 'var(--color-surface-1)',
+              border: '1px solid var(--color-border)',
+              color: 'var(--color-text)',
+            }}
+          >
+            {isConnectingNostr ? 'Connecting Nostr…' : 'Connect Nostr'}
+          </button>
+        )}
+      </div>
+
+      {(weblnError || nostrError) && (
+        <p className="text-xs" style={{ color: 'var(--color-error, #ef4444)' }} role="alert">
+          {weblnError?.message ?? nostrError?.message}
+        </p>
+      )}
     </div>
   );
 }
@@ -21,10 +105,12 @@ function StatusPill({
   label,
   active,
   loading,
+  available,
 }: {
   label: string;
   active: boolean;
   loading: boolean;
+  available: boolean;
 }) {
   return (
     <span
@@ -34,7 +120,9 @@ function StatusPill({
           ? 'bg-[var(--color-surface-2)] text-[var(--color-text-subtle)]'
           : active
             ? 'bg-[var(--color-accent-dim)] text-[var(--color-accent)]'
-            : 'bg-[var(--color-surface-2)] text-[var(--color-text-subtle)]',
+            : available
+              ? 'bg-[var(--color-surface-2)] text-[var(--color-text-muted)]'
+              : 'bg-[var(--color-surface-2)] text-[var(--color-text-subtle)]',
       )}
     >
       <span
@@ -48,6 +136,9 @@ function StatusPill({
         )}
       />
       {label}
+      {!loading && !active && available && (
+        <span className="opacity-60">(available)</span>
+      )}
     </span>
   );
 }

package/dist/templates/base/components/InvoiceQr.tsx

@@ -0,0 +1,31 @@
+'use client';
+
+import { QRCodeSVG } from 'qrcode.react';
+
+/** SVG-safe foreground color for QR codes (CSS variables break in some WebViews). */
+export const QR_FOREGROUND = '#e8e8e8';
+
+interface IInvoiceQrProps {
+  value: string;
+  size?: number;
+  label?: string;
+}
+
+/** Renders a BOLT11 or LNURL string as a scannable QR code. */
+export function InvoiceQr({ value, size = 136, label = 'Invoice QR code' }: IInvoiceQrProps) {
+  return (
+    <div
+      className="mx-auto flex w-full max-w-[160px] items-center justify-center rounded-lg p-3"
+      style={{ background: 'var(--color-surface-2)' }}
+      aria-label={label}
+    >
+      <QRCodeSVG
+        value={value}
+        size={size}
+        level="M"
+        bgColor="transparent"
+        fgColor={QR_FOREGROUND}
+      />
+    </div>
+  );
+}

package/dist/templates/base/components/PaymentCallout.tsx

@@ -0,0 +1,55 @@
+'use client';
+
+import {
+  getPublicLnurlPayAddress,
+  PUBLIC_FEDI_APP_REPO,
+  truncateLnurl,
+} from '../lib/payment-config';
+
+interface IPaymentCalloutProps {
+  className?: string;
+}
+
+/**
+ * Explains that demo Lightning payments route to the create-fedi-app maintainer wallet.
+ */
+export function PaymentCallout({ className }: IPaymentCalloutProps) {
+  const lnurl = getPublicLnurlPayAddress();
+
+  return (
+    <div
+      className={`space-y-2 rounded-lg px-4 py-3 text-sm leading-[1.65] ${className ?? ''}`}
+      style={{
+        background: 'var(--color-accent-dim)',
+        border: '1px solid var(--color-border)',
+        borderRadius: 'var(--radius-lg)',
+        color: 'var(--color-text-muted)',
+      }}
+      role="note"
+    >
+      <p className="font-semibold" style={{ color: 'var(--color-accent)' }}>
+        Demo payments support create-fedi-app
+      </p>
+      <p>
+        Lightning sent in these demos goes to the maintainer test wallet so you can verify real
+        payment flows inside Fedi.
+      </p>
+      <p className="font-mono text-xs break-all" style={{ color: 'var(--color-text-subtle)' }}>
+        {truncateLnurl(lnurl)}
+      </p>
+      <p>
+        If this template helped you, please{' '}
+        <a
+          href={PUBLIC_FEDI_APP_REPO}
+          target="_blank"
+          rel="noopener noreferrer"
+          className="font-semibold underline transition-opacity hover:opacity-80"
+          style={{ color: 'var(--color-accent)' }}
+        >
+          star, fork, or like the repo
+        </a>
+        .
+      </p>
+    </div>
+  );
+}

package/dist/templates/base/gitignore

@@ -0,0 +1,46 @@
+# Dependencies
+node_modules/
+.pnp
+.pnp.js
+
+# Next.js
+.next/
+out/
+
+# Production
+build/
+
+# TypeScript
+*.tsbuildinfo
+next-env.d.ts
+
+# Environment (never commit secrets)
+.env
+.env*.local
+
+# Vercel
+.vercel
+
+# Testing
+coverage/
+playwright-report/
+test-results/
+
+# Debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Misc
+*.log

package/dist/templates/base/hooks/useIsMounted.ts

@@ -0,0 +1,14 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+/** Returns true after the component has mounted on the client. */
+export function useIsMounted(): boolean {
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  return mounted;
+}

package/dist/templates/base/lib/__tests__/fedi.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest';
+import { isFediPermissionError } from '../fedi';
+
+describe('isFediPermissionError', () => {
+  it('detects permission denied errors', () => {
+    expect(isFediPermissionError(new Error('Permission denied: manageInstalledMiniApps'))).toBe(
+      true,
+    );
+  });
+
+  it('detects missing-permissions toast messages', () => {
+    expect(
+      isFediPermissionError(
+        new Error('create-fedi-app-demo is missing the following permissions: manageInstalledMiniApps'),
+      ),
+    ).toBe(true);
+  });
+
+  it('returns false for unrelated errors', () => {
+    expect(isFediPermissionError(new Error('Network request failed'))).toBe(false);
+    expect(isFediPermissionError('not an error object')).toBe(false);
+  });
+});

package/dist/templates/base/lib/demo-routes.ts

@@ -19,6 +19,6 @@ export const demoRoutes: IDemoRoute[] = [
   {
     href: '/demo/ecash',
     title: 'Ecash Balance',
-    description: 'Read Fedi ecash balance and install mini app prompts.',
+    description: 'fediInternal mini-app discovery, list, and install prompts.',
   },
 ];

package/dist/templates/base/lib/fedi-types.ts

@@ -75,7 +75,17 @@ type FediInternalV0 = { version: 0 };
 type FediInternalV1 = { version: 1 };
 type FediInternalV2 = {
   version: 2;
+  /**
+   * Lists mini apps installed in the user's Fedi wallet.
+   * Requires the `manageInstalledMiniApps` permission — call only on user gesture
+   * and handle rejection (user may deny or remember denial).
+   */
   getInstalledMiniApps(): Promise<Array<{ url: string }>>;
+  /**
+   * Prompts the user to install a mini app in Fedi.
+   * Requires the `manageInstalledMiniApps` permission — call only on user gesture
+   * and handle rejection (user may deny or remember denial).
+   */
   installMiniApp(miniApp: {
     id: string;
     title: string;