create-fedi-app 0.1.0

package/dist/templates/modules/ai-rules/rules/webln.md

@@ -0,0 +1,241 @@
+# WebLN Reference
+
+WebLN is a JavaScript standard for browser-based Lightning wallet access. In Fedi, `window.webln` is injected by the native app into every Mini App's WebView.
+
+## How Fedi injects window.webln
+
+Fedi's native app injects a `WebLNProvider` implementation into `window.webln` before the page loads. This provider routes calls through the native Lightning node (Fedimint eCash). No installation, no permissions dialog — it's there when the app opens inside Fedi.
+
+Outside Fedi (regular browser, SSR, tests without mocks) `window.webln` is `undefined`.
+
+## Detection pattern
+
+Always check before use. Never assume availability.
+
+```ts
+if (typeof window.webln !== 'undefined') {
+  // safe to use webln
+} else {
+  // show fallback UI or message
+}
+```
+
+The `@create-fedi-app/webln` package handles this internally — prefer using hooks over direct `window.webln` calls.
+
+## React hooks (preferred)
+
+### useWebLN()
+
+Returns the active provider and connection state.
+
+```ts
+import { useWebLN } from '@create-fedi-app/webln';
+
+const { provider, isLoading, error, isConnected } = useWebLN();
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `provider` | `WebLNProvider \| null` | The active provider, or null if not connected |
+| `isLoading` | `boolean` | True while the provider is initialising |
+| `error` | `Error \| null` | Set if provider initialisation failed |
+| `isConnected` | `boolean` | Shorthand for `provider !== null` |
+
+### usePayment()
+
+State-managed wrappers for `sendPayment` and `makeInvoice`.
+
+```ts
+import { usePayment } from '@create-fedi-app/webln';
+
+const {
+  sendPayment,
+  makeInvoice,
+  isPaying,
+  isCreatingInvoice,
+  paymentError,
+  lastPreimage,
+  lastInvoice,
+} = usePayment();
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `sendPayment(invoice)` | `(str) => Promise<SendPaymentResponse \| null>` | Pay a BOLT11 invoice |
+| `makeInvoice(args)` | `(args) => Promise<RequestInvoiceResponse \| null>` | Create a receive invoice |
+| `isPaying` | `boolean` | True during `sendPayment` |
+| `isCreatingInvoice` | `boolean` | True during `makeInvoice` |
+| `paymentError` | `Error \| null` | Last error from either call |
+| `lastPreimage` | `string \| null` | Preimage from last successful payment |
+| `lastInvoice` | `string \| null` | Payment request from last created invoice |
+
+## Full API (window.webln)
+
+### enable()
+
+```ts
+await window.webln.enable(): Promise<void>
+```
+
+Requests wallet access. **You do not need to call this in Fedi** — the `@create-fedi-app/webln` provider calls it automatically during initialisation.
+
+### getInfo()
+
+```ts
+const info = await window.webln.getInfo(): Promise<GetInfoResponse>
+```
+
+```ts
+interface GetInfoResponse {
+  node: {
+    alias: string;   // e.g. "Fedi Dev Node"
+    pubkey: string;  // hex-encoded node public key
+    color: string;   // hex color, e.g. "#FF6B35"
+  };
+  methods: string[]; // e.g. ["sendPayment", "makeInvoice", "getInfo", "signMessage"]
+}
+```
+
+### sendPayment()
+
+```ts
+const result = await window.webln.sendPayment(paymentRequest: string): Promise<SendPaymentResponse>
+```
+
+`paymentRequest` must be a BOLT11 string starting with `lnbc`.
+
+```ts
+interface SendPaymentResponse {
+  preimage: string; // hex-encoded 32-byte payment preimage — proof of payment
+}
+```
+
+Throws on failure (insufficient funds, expired invoice, routing failure, etc.).
+
+### makeInvoice()
+
+```ts
+const result = await window.webln.makeInvoice(args): Promise<RequestInvoiceResponse>
+```
+
+```ts
+// Three calling conventions — all valid:
+makeInvoice(1000)                                    // exact sats
+makeInvoice('1000')                                  // exact sats as string
+makeInvoice({ amount: '1000', defaultMemo: 'Coffee' }) // full args
+
+interface RequestInvoiceArgs {
+  amount?: string | number;        // exact amount in sats
+  defaultAmount?: string | number; // suggested amount (user can change)
+  minimumAmount?: string | number;
+  maximumAmount?: string | number;
+  defaultMemo?: string;
+}
+
+interface RequestInvoiceResponse {
+  paymentRequest: string; // BOLT11 string
+}
+```
+
+### signMessage()
+
+```ts
+const result = await window.webln.signMessage(message: string): Promise<SignMessageResponse>
+
+interface SignMessageResponse {
+  message: string;    // the original message
+  signature: string;  // hex-encoded signature
+}
+```
+
+Produces a Lightning node signature. Useful for proving Lightning identity. Not the same as Nostr signing.
+
+### sendKeysend()
+
+```ts
+const result = await window.webln.sendKeysend(args: KeysendArgs): Promise<SendPaymentResponse>
+
+interface KeysendArgs {
+  destination: string;               // destination node pubkey
+  amount: string | number;           // sats
+  customRecords?: Record<string, string>; // TLV records
+}
+```
+
+### verifyMessage()
+
+```ts
+await window.webln.verifyMessage(signature: string, message: string): Promise<void>
+```
+
+Verifies a signature produced by `signMessage`. Throws if invalid.
+
+## Common errors
+
+| Error message | Cause | Fix |
+|--------------|-------|-----|
+| `"Payment failed"` | Generic payment failure | Show user-friendly error, offer retry |
+| `"Invalid payment request: must start with lnbc"` | Bad invoice string | Validate invoice format before calling |
+| `"Insufficient funds"` | Wallet balance too low | Show balance, suggest amount |
+| `"Invoice expired"` | BOLT11 invoice past expiry | Refresh invoice and retry |
+
+## Graceful fallback pattern
+
+```tsx
+'use client';
+import { useWebLN } from '@create-fedi-app/webln';
+
+export function PaymentSection() {
+  const { isConnected, isLoading } = useWebLN();
+
+  if (isLoading) return <p>Connecting to wallet…</p>;
+
+  if (!isConnected) {
+    return (
+      <div>
+        <p>Open this app inside Fedi to make payments.</p>
+      </div>
+    );
+  }
+
+  return <YourPaymentUI />;
+}
+```
+
+## MockWebLNProvider (tests)
+
+```ts
+import { MockWebLNProvider } from '@create-fedi-app/webln';
+
+// Default: succeeds with 600ms delay
+const mock = new MockWebLNProvider();
+
+// Custom options:
+const slowMock = new MockWebLNProvider({ paymentDelay: 2000 });
+const failMock = new MockWebLNProvider({
+  shouldFail: true,
+  failureMessage: 'Simulated failure',
+});
+```
+
+`MockWebLNProvider` implements the full `WebLNProvider` interface:
+- `enable()` — no-op (throws if `shouldFail: true`)
+- `getInfo()` — returns static Fedi Dev Node info
+- `makeInvoice(args)` — returns a fake `lnbc...` string
+- `sendPayment(invoice)` — validates `lnbc` prefix, returns a random preimage hex
+- `signMessage(msg)` — returns message + random hex signature
+- `sendKeysend(args)` — returns a random preimage hex
+- `verifyMessage()` — no-op
+
+Use it in Vitest tests by passing it to the `WebLNProvider` context:
+
+```tsx
+import { WebLNProvider } from '@create-fedi-app/webln';
+import { MockWebLNProvider } from '@create-fedi-app/webln';
+
+render(
+  <WebLNProvider mock={new MockWebLNProvider()}>
+    <YourComponent />
+  </WebLNProvider>
+);
+```

package/dist/templates/modules/database/drizzle/supabase/0000_initial.sql

@@ -0,0 +1,7 @@
+CREATE TABLE "payments" (
+	"id" text PRIMARY KEY NOT NULL,
+	"invoice" text NOT NULL,
+	"preimage" text NOT NULL,
+	"paid_at" timestamp with time zone,
+	"metadata" jsonb
+);

package/dist/templates/modules/database/drizzle/supabase/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1748736000000,
+      "tag": "0000_initial",
+      "breakpoints": true
+    }
+  ]
+}

package/dist/templates/modules/database/drizzle/turso/0000_initial.sql

@@ -0,0 +1,7 @@
+CREATE TABLE `payments` (
+	`id` text PRIMARY KEY NOT NULL,
+	`invoice` text NOT NULL,
+	`preimage` text NOT NULL,
+	`paid_at` integer,
+	`metadata` text
+);

package/dist/templates/modules/database/drizzle/turso/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "sqlite",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "6",
+      "when": 1748736000000,
+      "tag": "0000_initial",
+      "breakpoints": true
+    }
+  ]
+}

package/dist/templates/modules/database/drizzle.config.supabase.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'drizzle-kit';
+
+export default defineConfig({
+  schema: './lib/db/schema.ts',
+  out: './drizzle',
+  dialect: 'postgresql',
+  dbCredentials: {
+    url: process.env.DATABASE_URL!,
+  },
+});

package/dist/templates/modules/database/drizzle.config.turso.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'drizzle-kit';
+
+export default defineConfig({
+  schema: './lib/db/schema.ts',
+  out: './drizzle',
+  dialect: 'turso',
+  dbCredentials: {
+    url: process.env.DATABASE_URL!,
+    authToken: process.env.DATABASE_AUTH_TOKEN,
+  },
+});

package/dist/templates/modules/database/env.supabase.ts

@@ -0,0 +1,24 @@
+import { createEnv } from '@t3-oss/env-nextjs';
+import { z } from 'zod';
+
+export const env = createEnv({
+  server: {
+    NODE_ENV: z.enum(['development', 'production', 'test']),
+    DATABASE_URL: z
+      .string()
+      .min(1)
+      .refine(
+        (value) =>
+          value.startsWith('postgresql://') || value.startsWith('postgres://'),
+        'DATABASE_URL must be a postgresql:// URL for Supabase',
+      ),
+    DATABASE_AUTH_TOKEN: z.string().optional(),
+  },
+  client: { NEXT_PUBLIC_APP_NAME: z.string().default('My Fedi App') },
+  runtimeEnv: {
+    NODE_ENV: process.env.NODE_ENV,
+    DATABASE_URL: process.env.DATABASE_URL,
+    DATABASE_AUTH_TOKEN: process.env.DATABASE_AUTH_TOKEN,
+    NEXT_PUBLIC_APP_NAME: process.env.NEXT_PUBLIC_APP_NAME,
+  },
+});

package/dist/templates/modules/database/env.turso.ts

@@ -0,0 +1,23 @@
+import { createEnv } from '@t3-oss/env-nextjs';
+import { z } from 'zod';
+
+export const env = createEnv({
+  server: {
+    NODE_ENV: z.enum(['development', 'production', 'test']),
+    DATABASE_URL: z
+      .string()
+      .min(1)
+      .refine(
+        (value) => value.startsWith('libsql://') || value.startsWith('file:'),
+        'DATABASE_URL must be a libsql:// or file: URL for Turso',
+      ),
+    DATABASE_AUTH_TOKEN: z.string().min(1),
+  },
+  client: { NEXT_PUBLIC_APP_NAME: z.string().default('My Fedi App') },
+  runtimeEnv: {
+    NODE_ENV: process.env.NODE_ENV,
+    DATABASE_URL: process.env.DATABASE_URL,
+    DATABASE_AUTH_TOKEN: process.env.DATABASE_AUTH_TOKEN,
+    NEXT_PUBLIC_APP_NAME: process.env.NEXT_PUBLIC_APP_NAME,
+  },
+});

package/dist/templates/modules/database/lib/db/index.supabase.ts

@@ -0,0 +1,19 @@
+import { drizzle } from 'drizzle-orm/postgres-js';
+import postgres from 'postgres';
+import { env } from '../../env';
+import * as schema from './schema';
+
+export { createClient } from '@supabase/supabase-js';
+
+const url = env.DATABASE_URL;
+
+if (!url.startsWith('postgresql://') && !url.startsWith('postgres://')) {
+  throw new Error(
+    'DATABASE_URL must be a postgresql:// URL for Supabase. Regenerate with database=supabase or update your connection string.',
+  );
+}
+
+const client = postgres(url, { prepare: false });
+
+export const db = drizzle(client, { schema });
+export * from './schema';

package/dist/templates/modules/database/lib/db/index.turso.ts

@@ -0,0 +1,20 @@
+import { createClient } from '@libsql/client';
+import { drizzle } from 'drizzle-orm/libsql';
+import { env } from '../../env';
+import * as schema from './schema';
+
+const url = env.DATABASE_URL;
+
+if (!url.startsWith('libsql://') && !url.startsWith('file:')) {
+  throw new Error(
+    'DATABASE_URL must be a libsql:// or file: URL for Turso. Regenerate with database=turso or update your connection string.',
+  );
+}
+
+const client = createClient({
+  url,
+  authToken: env.DATABASE_AUTH_TOKEN,
+});
+
+export const db = drizzle(client, { schema });
+export * from './schema';

package/dist/templates/modules/database/lib/db/schema.supabase.ts

@@ -0,0 +1,13 @@
+import { jsonb, pgTable, text, timestamp } from 'drizzle-orm/pg-core';
+
+/** Payment records for payment-gated content and other Lightning-gated features. */
+export const payments = pgTable('payments', {
+  id: text('id').primaryKey(),
+  invoice: text('invoice').notNull(),
+  preimage: text('preimage').notNull(),
+  paidAt: timestamp('paid_at', { withTimezone: true, mode: 'date' }),
+  metadata: jsonb('metadata').$type<Record<string, unknown>>(),
+});
+
+export type TPayment = typeof payments.$inferSelect;
+export type TNewPayment = typeof payments.$inferInsert;

package/dist/templates/modules/database/lib/db/schema.turso.ts

@@ -0,0 +1,13 @@
+import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+
+/** Payment records for payment-gated content and other Lightning-gated features. */
+export const payments = sqliteTable('payments', {
+  id: text('id').primaryKey(),
+  invoice: text('invoice').notNull(),
+  preimage: text('preimage').notNull(),
+  paidAt: integer('paid_at', { mode: 'timestamp_ms' }),
+  metadata: text('metadata', { mode: 'json' }).$type<Record<string, unknown>>(),
+});
+
+export type TPayment = typeof payments.$inferSelect;
+export type TNewPayment = typeof payments.$inferInsert;

package/dist/templates/modules/database/module.json

@@ -0,0 +1,110 @@
+{
+  "name": "database",
+  "description": "Drizzle ORM CRUD example with Turso or Supabase",
+  "dependencies": ["drizzle-orm"],
+  "devDependencies": ["drizzle-kit"],
+  "databaseType": {
+    "turso": {
+      "dependencies": ["@libsql/client"],
+      "devDependencies": []
+    },
+    "supabase": {
+      "dependencies": ["postgres", "@supabase/supabase-js"],
+      "devDependencies": []
+    }
+  },
+  "scripts": {
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "db:push": "drizzle-kit push",
+    "db:studio": "drizzle-kit studio"
+  },
+  "files": [
+    {
+      "src": "lib/db/index.turso.ts",
+      "dest": "lib/db/index.ts",
+      "merge": "add",
+      "databaseType": "turso"
+    },
+    {
+      "src": "lib/db/index.supabase.ts",
+      "dest": "lib/db/index.ts",
+      "merge": "add",
+      "databaseType": "supabase"
+    },
+    {
+      "src": "lib/db/schema.turso.ts",
+      "dest": "lib/db/schema.ts",
+      "merge": "add",
+      "databaseType": "turso"
+    },
+    {
+      "src": "lib/db/schema.supabase.ts",
+      "dest": "lib/db/schema.ts",
+      "merge": "add",
+      "databaseType": "supabase"
+    },
+    {
+      "src": "drizzle.config.turso.ts",
+      "dest": "drizzle.config.ts",
+      "merge": "add",
+      "databaseType": "turso"
+    },
+    {
+      "src": "drizzle.config.supabase.ts",
+      "dest": "drizzle.config.ts",
+      "merge": "add",
+      "databaseType": "supabase"
+    },
+    {
+      "src": "env.turso.ts",
+      "dest": "env.ts",
+      "merge": "replace",
+      "databaseType": "turso"
+    },
+    {
+      "src": "env.supabase.ts",
+      "dest": "env.ts",
+      "merge": "replace",
+      "databaseType": "supabase"
+    },
+    {
+      "src": "drizzle/turso/0000_initial.sql",
+      "dest": "drizzle/0000_initial.sql",
+      "merge": "add",
+      "databaseType": "turso"
+    },
+    {
+      "src": "drizzle/turso/meta/_journal.json",
+      "dest": "drizzle/meta/_journal.json",
+      "merge": "add",
+      "databaseType": "turso"
+    },
+    {
+      "src": "drizzle/supabase/0000_initial.sql",
+      "dest": "drizzle/0000_initial.sql",
+      "merge": "add",
+      "databaseType": "supabase"
+    },
+    {
+      "src": "drizzle/supabase/meta/_journal.json",
+      "dest": "drizzle/meta/_journal.json",
+      "merge": "add",
+      "databaseType": "supabase"
+    }
+  ],
+  "envVars": [
+    {
+      "key": "DATABASE_URL",
+      "description": "Database connection URL (libsql:// for Turso, postgresql:// for Supabase)",
+      "example": "libsql://your-db.turso.io",
+      "required": true
+    },
+    {
+      "key": "DATABASE_AUTH_TOKEN",
+      "description": "Database auth token (Turso only)",
+      "example": "eyJ...",
+      "required": false
+    }
+  ]
+}

package/dist/templates/modules/ecash-balance/app/demo/ecash/page.tsx

@@ -0,0 +1,115 @@
+'use client';
+
+import Link from 'next/link';
+import { useState } from 'react';
+import { BalanceDisplay } from '../../../components/fedi/BalanceDisplay';
+import { FediVersionBadge } from '../../../components/fedi/FediVersionBadge';
+
+const DEMO_INSTALL_APP = {
+  id: 'com.create-fedi-app.demo',
+  title: 'Fedi Demo App',
+  url: 'https://example.com',
+  description: 'Sample mini app entry for the ecash-balance demo.',
+};
+
+export default function EcashDemoPage() {
+  const [howItWorksOpen, setHowItWorksOpen] = useState(false);
+
+  return (
+    <div className="min-h-dvh bg-[var(--color-bg)] font-[family-name:var(--font-body)] text-[var(--color-text)]">
+      <div
+        className="mx-auto w-full max-w-[390px] px-4 pt-6"
+        style={{ paddingBottom: 'max(5rem, env(safe-area-inset-bottom, 20px))' }}
+      >
+        <div className="mb-6 flex items-center justify-between gap-3">
+          <Link
+            href="/demo"
+            className="inline-block text-xs text-[var(--color-text-muted)] transition-opacity duration-200 ease-[cubic-bezier(0.25,1,0.5,1)] hover:opacity-80"
+          >
+            ← back
+          </Link>
+          <FediVersionBadge />
+        </div>
+
+        <header className="mb-8 space-y-2">
+          <h1 className="font-[family-name:var(--font-display)] text-2xl font-bold leading-tight text-[var(--color-text)]">
+            Ecash &amp; Fedi API
+          </h1>
+          <p className="max-w-[75ch] text-sm leading-[1.65] text-[var(--color-text-muted)]">
+            Reads <code className="font-mono text-xs">window.fediInternal</code> for versioned mini
+            app discovery. Unlike WebLN and Nostr, this API is optional. Older Fedi builds may not
+            expose it.
+          </p>
+        </header>
+
+        <div className="space-y-8">
+          <section className="space-y-4">
+            <div className="max-w-[75ch] space-y-1.5">
+              <h2 className="font-[family-name:var(--font-display)] text-xl font-semibold leading-tight tracking-tight text-[var(--color-text)]">
+                Environment &amp; installed apps
+              </h2>
+              <p className="text-sm leading-[1.65] text-[var(--color-text-muted)]">
+                On fediInternal v2, lists installed mini app URLs (click to open) and can trigger
+                Fedi&apos;s native install sheet via <code className="font-mono text-xs">installMiniApp()</code>.
+              </p>
+            </div>
+            <BalanceDisplay installApp={DEMO_INSTALL_APP} />
+          </section>
+
+          <section className="space-y-3">
+            <button
+              type="button"
+              onClick={() => setHowItWorksOpen((open) => !open)}
+              className="flex w-full items-center justify-between rounded-lg px-4 py-3 text-left text-sm font-semibold transition-opacity duration-200 ease-[cubic-bezier(0.25,1,0.5,1)] hover:opacity-80"
+              style={{
+                background: 'var(--color-surface-1)',
+                border: '1px solid var(--color-border)',
+                color: 'var(--color-text)',
+                borderRadius: 'var(--radius-lg)',
+              }}
+              aria-expanded={howItWorksOpen}
+              aria-controls="ecash-how-it-works"
+            >
+              How fediInternal works
+              <span aria-hidden>{howItWorksOpen ? '−' : '+'}</span>
+            </button>
+
+            {howItWorksOpen && (
+              <div
+                id="ecash-how-it-works"
+                className="space-y-3 rounded-lg px-4 py-3 text-sm leading-[1.65]"
+                style={{
+                  background: 'var(--color-surface-1)',
+                  border: '1px solid var(--color-border)',
+                  color: 'var(--color-text-muted)',
+                  borderRadius: 'var(--radius-lg)',
+                }}
+              >
+                <p>
+                  <strong className="text-[var(--color-text)]">fediInternal</strong> is a versioned
+                  bridge for mini app discovery inside Fedi. Version{' '}
+                  <code className="font-mono text-xs">0</code> and{' '}
+                  <code className="font-mono text-xs">1</code> only expose the version number;{' '}
+                  <code className="font-mono text-xs">2</code> adds{' '}
+                  <code className="font-mono text-xs">getInstalledMiniApps()</code> and{' '}
+                  <code className="font-mono text-xs">installMiniApp()</code>.
+                </p>
+                <p>
+                  Always check both presence and version before calling methods. Outside Fedi (or on
+                  very old builds), <code className="font-mono text-xs">window.fediInternal</code> is{' '}
+                  <code className="font-mono text-xs">undefined</code>. Show an &quot;Open in
+                  Fedi&quot; prompt instead of failing silently.
+                </p>
+                <p>
+                  Use <code className="font-mono text-xs">installMiniApp()</code> to suggest
+                  companion apps to your users. Fedi shows a native confirmation sheet; your mini app
+                  never writes to the user&apos;s home screen directly.
+                </p>
+              </div>
+            )}
+          </section>
+        </div>
+      </div>
+    </div>
+  );
+}