add newsletter feature for premium users

NEWSLETTER_GUIDE.md

@@ -0,0 +1,145 @@
+# newsletter feature documentation
+
+## overview
+newsletters are premium content available exclusively to subscribed users on opensox.ai. they provide insights on ai, coding, open source, and developer tools.
+
+---
+
+## 📝 adding a new newsletter
+
+### step 1: open the data file
+navigate to: `apps/web/src/data/newsletters.ts`
+
+### step 2: add your newsletter entry
+add a new object to the `newsletters` array:
+
+```typescript
+{
+  id: "4", // increment from last id
+  date: "DD-MM-YY", // e.g., "20-11-25" for nov 20, 2025
+  title: "your newsletter title",
+  slug: "url-friendly-slug", // lowercase, hyphens only
+  excerpt: "a compelling 1-2 sentence description",
+  content: ```html
+    <h2>main section heading</h2>
+    <p>your paragraph content here. use <strong>bold text</strong> for emphasis.</p>
+
+    <img src="https://your-image-url.com/image.jpg" alt="descriptive alt text" />
+
+    <p>add <a href="https://example.com">external links</a> for references.</p>
+
+    <h3>subsection heading</h3>
+    <ul>
+      <li><strong>list item title</strong> - description of the item</li>
+      <li><strong>another item</strong> - more details here</li>
+    </ul>
+  ```,
+  tags: ["relevant", "topic", "tags"],
+  readTime: 6 // optional: estimated minutes to read
+}
+```
+
+### step 3: save and test
+1. save the file
+2. the dev server will auto-reload (or run `npm run dev`)
+3. visit `/newsletters` to see your new entry
+4. click through to verify content displays correctly
+
+---
+
+## 🎨 content formatting guide
+
+### headings
+```html
+<h2>main section heading</h2>
+<h3>subsection heading</h3>
+```
+- use h2 for main sections
+- use h3 for subsections
+- keep headings descriptive and concise
+
+### paragraphs
+```html
+<p>regular paragraph text goes here.</p>
+<p>use <strong>bold text</strong> to emphasize key points.</p>
+```
+- keep paragraphs 2-4 sentences for readability
+- use bold sparingly for impact
+
+### links
+```html
+<a href="https://example.com">descriptive link text</a>
+```
+- always use https://
+- make link text descriptive (avoid "click here")
+
+### images
+```html
+<img src="https://your-image-url.com/image.jpg" alt="descriptive alt text" />
+```
+- use high-quality images (minimum 1200px wide)
+- always include descriptive alt text
+- use unsplash for free stock photos
+- images should be relevant to surrounding content
+
+### lists
+```html
+<ul>
+  <li><strong>item title</strong> - description or explanation</li>
+  <li><strong>another item</strong> - more details here</li>
+  <li><strong>third item</strong> - keep it concise</li>
+</ul>
+```
+- use bold for list item titles
+- follow with a dash and description
+- keep list items parallel in structure
+
+---
+
+## 🔒 access control
+
+newsletters are **automatically protected** for premium users:
+- non-premium users see a subscription prompt
+- authentication handled by `useSubscription` hook
+- no additional configuration needed
+
+---
+
+## 🐛 troubleshooting
+
+### newsletter not appearing?
+- verify date format is `DD-MM-YY`
+- check for syntax errors in the typescript
+- ensure the newsletter is in the `newsletters` array
+- restart dev server if needed
+
+### images not loading?
+- use absolute urls starting with `https://`
+- verify the url works in a browser
+- check that alt text is provided
+- try a different image source if loading fails
+
+### formatting looks wrong?
+- ensure all html tags are properly closed
+- check for typos in tag names
+- use the examples above as templates
+- view in dev environment before committing
+
+### content overflowing or breaking?
+- avoid extremely long words
+- break up long paragraphs
+- ensure images have proper dimensions
+- check responsive display on mobile
+
+---
+
+## 📂 file structure
+
+```
+apps/web/src/
+├── app/(main)/newsletters/
+│   ├── page.tsx              # newsletter list page
+│   └── [slug]/page.tsx       # individual newsletter page
+└── data/
+    └── newsletters.ts         # ✏️ edit this file to add newsletters
+```

apps/web/src/app/(main)/newsletters/[slug]/page.tsx

@@ -0,0 +1,240 @@
+"use client";
+
+import { use } from "react";
+import { notFound } from "next/navigation";
+import Link from "next/link";
+import { ArrowLeft, Home } from "lucide-react";
+import { newsletters } from "@/data/newsletters";
+import { useSubscription } from "@/hooks/useSubscription";
+
+export default function NewsletterPage({ 
+  params 
+}: { 
+  params: Promise<{ slug: string }> 
+}) {
+  const { slug } = use(params);
+  const { isPaidUser, isLoading } = useSubscription();
+  const newsletter = newsletters.find(n => n.slug === slug);
+
+  if (!newsletter) notFound();
+
+  // loading
+  if (isLoading) {
+    return (
+      <div className="min-h-screen bg-[#101010] flex items-center justify-center text-white">
+        <p>loading...</p>
+      </div>
+    );
+  }
+
+  // premium gate
+  if (!isPaidUser) {
+    return (
+      <div className="min-h-screen bg-[#101010] flex items-center justify-center p-4">
+        <div className="text-center max-w-md text-white">
+          <h1 className="text-2xl font-bold mb-4">premium content</h1>
+          <p className="text-gray-400 mb-6">subscribe to access this newsletter</p>
+          <Link href="/pricing" className="text-[#a472ea] hover:underline">
+            view plans
+          </Link>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <main className="min-h-screen bg-[#101010] text-white">
+      {/* navigation bar */}
+      <div className="sticky top-0 z-10 bg-[#101010]/95 backdrop-blur-sm border-b border-[#252525]">
+        <div className="max-w-4xl mx-auto px-4 md:px-6 py-4">
+          <div className="flex items-center justify-between">
+            {/* back to newsletters */}
+            <Link 
+              href="/newsletters" 
+              className="inline-flex items-center gap-2 text-sm text-gray-400 hover:text-white transition"
+            >
+              <ArrowLeft className="w-4 h-4" />
+              <span className="hidden md:inline">newsletters</span>
+            </Link>
+
+            {/* back to dashboard */}
+            <Link 
+              href="/dashboard/home"
+              className="inline-flex items-center gap-2 text-sm text-gray-400 hover:text-white transition"
+            >
+              <Home className="w-4 h-4" />
+              <span className="hidden md:inline">dashboard</span>
+            </Link>
+          </div>
+        </div>
+      </div>
+
+      <div className="max-w-4xl mx-auto px-4 md:px-6 py-8 md:py-12">
+        {/* header */}
+        <header className="mb-8 md:mb-12">
+          {/* metadata */}
+          <div className="flex flex-wrap items-center gap-2 md:gap-3 mb-4">
+            <span className="text-xs md:text-sm text-gray-500 font-mono">
+              {newsletter.date}
+            </span>
+            <span className="text-gray-600">•</span>
+            <span className="text-xs md:text-sm text-gray-500">
+              {calculateReadTime(newsletter.content)} min read
+            </span>
+          </div>
+
+          {/* title */}
+          <h1 className="text-3xl md:text-4xl lg:text-5xl font-bold mb-4 leading-tight">
+            {newsletter.title}
+          </h1>
+
+          {/* excerpt */}
+          <p className="text-lg md:text-xl text-gray-400 mb-6">
+            {newsletter.excerpt}
+          </p>
+
+          {/* tags */}
+          <div className="flex flex-wrap gap-2">
+            {newsletter.tags.map(tag => (
+              <span 
+                key={tag}
+                className="text-xs md:text-sm bg-[#a472ea]/10 text-[#a472ea] px-3 py-1 rounded"
+              >
+                {tag}
+              </span>
+            ))}
+          </div>
+        </header>
+
+        {/* divider */}
+        <div className="h-px bg-[#252525] mb-8 md:mb-12"></div>
+
+        {/* content */}
+        <article 
+          className="prose-newsletter"
+          dangerouslySetInnerHTML={{ __html: newsletter.content }}
+        />
+
+        {/* divider */}
+        <div className="h-px bg-[#252525] mt-12 mb-8"></div>
+
+        {/* footer navigation */}
+        <div className="flex flex-col sm:flex-row items-center justify-between gap-4">
+          <Link 
+            href="/newsletters"
+            className="inline-flex items-center gap-2 text-gray-400 hover:text-white transition"
+          >
+            <ArrowLeft className="w-4 h-4" />
+            <span>all newsletters</span>
+          </Link>
+
+          <Link 
+            href="/dashboard/home"
+            className="inline-flex items-center gap-2 text-gray-400 hover:text-white transition"
+          >
+            <Home className="w-4 h-4" />
+            <span>back to dashboard</span>
+          </Link>
+        </div>
+      </div>
+
+      {/* styles */}
+      <style jsx global>{`
+        .prose-newsletter h2 {
+          font-size: 1.75rem;
+          font-weight: 700;
+          color: white;
+          margin-top: 2.5rem;
+          margin-bottom: 1rem;
+          line-height: 1.3;
+        }
+
+        .prose-newsletter h2:first-child {
+          margin-top: 0;
+        }
+
+        .prose-newsletter h3 {
+          font-size: 1.375rem;
+          font-weight: 600;
+          color: white;
+          margin-top: 2rem;
+          margin-bottom: 0.75rem;
+        }
+
+        .prose-newsletter p {
+          color: #d1d5db;
+          line-height: 1.75;
+          margin-bottom: 1.25rem;
+          font-size: 1.0625rem;
+        }
+
+        .prose-newsletter strong {
+          color: white;
+          font-weight: 600;
+        }
+
+        .prose-newsletter a {
+          color: #a472ea;
+          text-decoration: underline;
+          text-underline-offset: 2px;
+        }
+
+        .prose-newsletter a:hover {
+          color: #b894f5;
+        }
+
+        .prose-newsletter img {
+          width: 100%;
+          border-radius: 0.5rem;
+          margin: 2rem 0;
+        }
+
+        .prose-newsletter ul {
+          list-style: none;
+          margin: 1.25rem 0;
+          padding: 0;
+        }
+
+        .prose-newsletter li {
+          color: #d1d5db;
+          margin-bottom: 0.75rem;
+          padding-left: 1.5rem;
+          position: relative;
+          line-height: 1.7;
+        }
+
+        .prose-newsletter li::before {
+          content: "•";
+          position: absolute;
+          left: 0;
+          color: #a472ea;
+          font-weight: bold;
+          font-size: 1.2em;
+        }
+
+        /* mobile adjustments */
+        @media (max-width: 768px) {
+          .prose-newsletter h2 {
+            font-size: 1.5rem;
+            margin-top: 2rem;
+          }
+
+          .prose-newsletter h3 {
+            font-size: 1.25rem;
+          }
+
+          .prose-newsletter p {
+            font-size: 1rem;
+          }
+        }
+      `}</style>
+    </main>
+  );
+}
+
+function calculateReadTime(content: string): number {
+  const text = content.replace(/<[^>]*>/g, '');
+  const words = text.trim().split(/\s+/).length;
+  const minutes = words / 238;
+  return Math.max(1, Math.ceil(minutes));
+}