docs: implement proper documentation

Author: athexweb3

docs/.gitignore

@@ -0,0 +1,26 @@
+# deps
+/node_modules
+
+# generated content
+.source
+
+# test & build
+/coverage
+/.next/
+/out/
+/build
+*.tsbuildinfo
+
+# misc
+.DS_Store
+*.pem
+/.pnp
+.pnp.js
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# others
+.env*.local
+.vercel
+next-env.d.ts

docs/README.md

@@ -0,0 +1,45 @@
+# docs
+
+This is a Next.js application generated with
+[Create Fumadocs](https://github.com/fuma-nama/fumadocs).
+
+Run development server:
+
+```bash
+npm run dev
+# or
+pnpm dev
+# or
+yarn dev
+```
+
+Open http://localhost:3000 with your browser to see the result.
+
+## Explore
+
+In the project, you can see:
+
+- `lib/source.ts`: Code for content source adapter, [`loader()`](https://fumadocs.dev/docs/headless/source-api) provides the interface to access your content.
+- `lib/layout.shared.tsx`: Shared options for layouts, optional but preferred to keep.
+
+| Route                     | Description                                            |
+| ------------------------- | ------------------------------------------------------ |
+| `app/(home)`              | The route group for your landing page and other pages. |
+| `app/docs`                | The documentation layout and pages.                    |
+| `app/api/search/route.ts` | The Route Handler for search.                          |
+
+### Fumadocs MDX
+
+A `source.config.ts` config file has been included, you can customise different options like frontmatter schema.
+
+Read the [Introduction](https://fumadocs.dev/docs/mdx) for further details.
+
+## Learn More
+
+To learn more about Next.js and Fumadocs, take a look at the following
+resources:
+
+- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js
+  features and API.
+- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+- [Fumadocs](https://fumadocs.dev) - learn about Fumadocs

docs/app/(home)/layout.tsx

@@ -0,0 +1,6 @@
+import { HomeLayout } from 'fumadocs-ui/layouts/home';
+import { baseOptions } from '@/lib/layout.shared';
+
+export default function Layout({ children }: LayoutProps<'/'>) {
+  return <HomeLayout {...baseOptions()}>{children}</HomeLayout>;
+}

docs/app/(home)/page.tsx

@@ -0,0 +1,14 @@
+
+import { Hero } from '../../components/landing/Hero';
+import { FeatureSection } from '../../components/landing/FeatureSection';
+
+export default function HomePage() {
+  return (
+
+    <div className="flex flex-col min-h-screen bg-fd-background">
+      <Hero />
+      <FeatureSection />
+    </div>
+
+  );
+}

docs/app/api/contributors/route.ts

@@ -0,0 +1,31 @@
+import { NextResponse } from 'next/server';
+
+export const revalidate = 86400; // Cache response for 24 hours (Maximum rate-limit friendliness)
+
+export async function GET() {
+    try {
+        console.log('[API] Fetching contributors from GitHub...');
+        const headers: Record<string, string> = process.env.GITHUB_TOKEN ? { Authorization: `Bearer ${process.env.GITHUB_TOKEN}` } : {};
+
+        const res = await fetch('https://api.github.com/repos/margelo/react-native-quick-crypto/contributors?per_page=100', { 
+            headers,
+            next: { revalidate: 86400 }
+        });
+
+        if (!res.ok) {
+            console.error('[API] GitHub Contributors fetch failed:', res.status, res.statusText);
+            throw new Error(`GitHub API Error: ${res.status} ${res.statusText}`);
+        }
+
+        const data = await res.json();
+
+        if (!Array.isArray(data)) return NextResponse.json([]);
+
+        const humans = data.filter((c: any) => !c.login.toLowerCase().includes('[bot]'));
+
+        return NextResponse.json(humans);
+    } catch (error) {
+        console.error('[API] Handler error:', error);
+        return NextResponse.json({ error: 'Internal Server Error' }, { status: 500 });
+    }
+}

docs/app/api/releases/route.ts

@@ -0,0 +1,158 @@
+import { NextResponse } from 'next/server';
+import { unstable_cache } from 'next/cache';
+
+export const revalidate = 86400; // Cache response for 24 hours (releases don't change often)
+
+function extractContributors(text: string): string[] {
+    const mentionRegex = /@([a-zA-Z0-9-]+)/g;
+    const matches = text ? text.match(mentionRegex) : null;
+    if (!matches) return [];
+
+    // Clean up matches, remove duplicates, and filter out common bots/keywords
+    const uniqueUsers = Array.from(new Set(matches.map(m => m.substring(1)))); // remove @
+    const banned = ['dependabot', 'github-actions', 'channel', 'here', 'all']; // common non-user mentions
+
+    return uniqueUsers.filter(u => !u.includes('[bot]') && !banned.includes(u.toLowerCase()));
+}
+
+interface ContributorDetails {
+    login: string;
+    name?: string;
+    avatar_url: string;
+    html_url: string;
+    bio?: string;
+    location?: string;
+    company?: string;
+}
+
+// Persistently cache user details forever (or until manually invalidated)
+// This fetches the "real name" and other details from GitHub User API
+const getContributorDetails = unstable_cache(
+    async (login: string): Promise<ContributorDetails | null> => {
+        try {
+            console.log(`[API] Fetching user details for ${login}...`);
+            const headers: Record<string, string> = process.env.GITHUB_TOKEN ? { Authorization: `Bearer ${process.env.GITHUB_TOKEN}` } : {};
+            const res = await fetch(`https://api.github.com/users/${login}`, { headers });
+
+            if (!res.ok) {
+                if (res.status === 404) return null;
+                throw new Error(`GitHub User API Error: ${res.status}`);
+            }
+
+            const data = await res.json();
+            return {
+                login: data.login,
+                name: data.name,
+                avatar_url: data.avatar_url,
+                html_url: data.html_url,
+                bio: data.bio,
+                location: data.location,
+                company: data.company
+            };
+        } catch (e) {
+            console.error(`[API] Failed to fetch user ${login}:`, e);
+            // Fallback to basic details if API fails
+            return {
+                login,
+                avatar_url: `https://github.com/${login}.png`,
+                html_url: `https://github.com/${login}`
+            };
+        }
+    },
+    ['github-user-details'], // Cache key namespace
+    {
+        revalidate: false, // Cache forever (never revalidate automatically)
+        tags: ['contributors']
+    }
+);
+
+export async function GET() {
+    try {
+        console.log('[API] Fetching releases from GitHub...');
+        const headers: Record<string, string> = process.env.GITHUB_TOKEN ? { Authorization: `Bearer ${process.env.GITHUB_TOKEN}` } : {};
+
+        const releasesRes = await fetch('https://api.github.com/repos/margelo/react-native-quick-crypto/releases?per_page=10', {
+            headers,
+            next: { revalidate: 86400 }
+        });
+
+        if (!releasesRes.ok) {
+            console.error('[API] GitHub Releases fetch failed:', releasesRes.status, releasesRes.statusText);
+            throw new Error(`GitHub API Error: ${releasesRes.status} ${releasesRes.statusText}`);
+        }
+
+        const releases = await releasesRes.json();
+        if (!Array.isArray(releases)) return NextResponse.json([]);
+
+        // Process releases in parallel to fetch contributors
+        const enhanced = await Promise.all(releases.map(async (release: any, index: number) => {
+            const previousTag = releases[index + 1]?.tag_name;
+            const contributorsMap = new Map<string, { login: string, commits: number }>();
+
+            // 1. Text mentions (legacy method, but good for shoutouts)
+            extractContributors(release.body).forEach(user => {
+                contributorsMap.set(user, { login: user, commits: 0 });
+            });
+
+            // 2. Compare API (if previous tag exists) to get actual committers
+            if (previousTag) {
+                try {
+                    const compareUrl = `https://api.github.com/repos/margelo/react-native-quick-crypto/compare/${previousTag}...${release.tag_name}`;
+                    const compareRes = await fetch(compareUrl, { headers, next: { revalidate: 86400 } });
+
+                    if (compareRes.ok) {
+                        const data = await compareRes.json();
+                        if (data.commits && Array.isArray(data.commits)) {
+                            data.commits.forEach((commit: any) => {
+                                if (commit.author && commit.author.login) {
+                                    if (!commit.author.login.includes('[bot]')) {
+                                        const login = commit.author.login;
+                                        const current = contributorsMap.get(login) || { login, commits: 0 };
+                                        current.commits++;
+                                        contributorsMap.set(login, current);
+                                    }
+                                }
+                            });
+                        }
+                    } else if (compareRes.status === 403 && process.env.NODE_ENV === 'development') {
+                        // Mock data for development when rate limited
+                        console.warn(`[API] Rate limited. Using mock contributors for ${release.tag_name}.`);
+                        ['mrousavy', 'szymonkapala', 'ospfranco'].forEach(login => {
+                            contributorsMap.set(login, { login, commits: Math.floor(Math.random() * 5) + 1 });
+                        });
+                    } else {
+                        console.warn(`[API] Compare fetch failed for ${previousTag}...${release.tag_name}: ${compareRes.status}`);
+                    }
+                } catch (e) {
+                    console.error('[API] Compare fetch error:', e);
+                }
+            }
+
+            // 3. Hydrate with full user details (Names, Bios, etc.) using persistent cache
+            const hydratedContributors = await Promise.all(
+                Array.from(contributorsMap.values()).map(async (c) => {
+                    const details = await getContributorDetails(c.login);
+                    return {
+                        ...details,
+                        commits: c.commits
+                    };
+                })
+            );
+
+            // Sort: High commits first, then by name
+            const sortedContributors = hydratedContributors
+                .filter(c => c !== null)
+                .sort((a: any, b: any) => b.commits - a.commits);
+
+            return {
+                ...release,
+                contributors: sortedContributors
+            };
+        }));
+
+        return NextResponse.json(enhanced);
+    } catch (error) {
+        console.error('[API] Handler error:', error);
+        return NextResponse.json({ error: 'Internal Server Error' }, { status: 500 });
+    }
+}

docs/app/api/search/route.ts

@@ -0,0 +1,7 @@
+import { source } from '@/lib/source';
+import { createFromSource } from 'fumadocs-core/search/server';
+
+export const { GET } = createFromSource(source, {
+  // https://docs.orama.com/docs/orama-js/supported-languages
+  language: 'english',
+});

docs/app/docs/[[...slug]]/page.tsx

@@ -0,0 +1,54 @@
+import { getPageImage, source } from '@/lib/source';
+import {
+  DocsBody,
+  DocsDescription,
+  DocsPage,
+  DocsTitle,
+} from 'fumadocs-ui/layouts/docs/page';
+import { notFound } from 'next/navigation';
+import { getMDXComponents } from '@/mdx-components';
+import type { Metadata } from 'next';
+import { createRelativeLink } from 'fumadocs-ui/mdx';
+
+export default async function Page(props: PageProps<'/docs/[[...slug]]'>) {
+  const params = await props.params;
+  const page = source.getPage(params.slug);
+  if (!page) notFound();
+
+  const MDX = page.data.body;
+
+  return (
+    <DocsPage toc={page.data.toc} full={page.data.full}>
+      <DocsTitle>{page.data.title}</DocsTitle>
+      <DocsDescription>{page.data.description}</DocsDescription>
+      <DocsBody>
+        <MDX
+          components={getMDXComponents({
+            // this allows you to link to other pages with relative file paths
+            a: createRelativeLink(source, page),
+          })}
+        />
+      </DocsBody>
+    </DocsPage>
+  );
+}
+
+export async function generateStaticParams() {
+  return source.generateParams();
+}
+
+export async function generateMetadata(
+  props: PageProps<'/docs/[[...slug]]'>,
+): Promise<Metadata> {
+  const params = await props.params;
+  const page = source.getPage(params.slug);
+  if (!page) notFound();
+
+  return {
+    title: page.data.title,
+    description: page.data.description,
+    openGraph: {
+      images: getPageImage(page).url,
+    },
+  };
+}

docs/app/docs/layout.tsx

@@ -0,0 +1,14 @@
+
+import { DocsLayout, type DocsLayoutProps } from 'fumadocs-ui/layouts/docs';
+import { baseOptions } from '@/lib/layout.shared';
+import { source } from '@/lib/source';
+function docsOptions(): DocsLayoutProps {
+  return {
+    ...baseOptions(),
+    tree: source.pageTree,
+    links: [],
+  };
+}
+export default function Layout({ children }: { children: React.ReactNode }) {
+  return <DocsLayout {...docsOptions()}>{children}</DocsLayout>;
+}