@volchoklv/newsletter-kit 1.0.0

package/README.md

@@ -0,0 +1,505 @@
+# @volchoklv/newsletter-kit
+
+Drop-in newsletter subscription components and API handlers for Next.js with adapter support for email providers and storage backends.
+
+## Features
+
+- 🎨 **shadcn/ui compatible** - Styled components that match your design system
+- 🔌 **Adapter pattern** - Swap email providers and storage backends without changing code
+- 🛡️ **Built-in protection** - Honeypot bot detection, rate limiting, email validation
+- 📊 **Source tracking** - Track where subscribers come from
+- ✅ **Double opt-in** - Optional email confirmation flow
+- 🎯 **TypeScript first** - Full type safety
+
+## Installation
+
+```bash
+npm install @volchoklv/newsletter-kit
+# or
+pnpm add @volchoklv/newsletter-kit
+# or
+yarn add @volchoklv/newsletter-kit
+```
+
+Install peer dependencies based on your choices:
+
+```bash
+# For Resend
+npm install resend
+
+# For Nodemailer/SMTP
+npm install nodemailer
+
+# For Prisma storage
+npm install @prisma/client
+
+# For Supabase storage
+npm install @supabase/supabase-js
+```
+
+## Quick Start
+
+### 1. Create the newsletter handler
+
+```ts
+// lib/newsletter.ts
+import { createNewsletterHandlers } from '@volchoklv/newsletter-kit/server';
+import { createResendAdapter } from '@volchoklv/newsletter-kit/adapters/email';
+import { createPrismaAdapter } from '@volchoklv/newsletter-kit/adapters/storage';
+import { prisma } from '@/lib/prisma';
+
+export const newsletter = createNewsletterHandlers({
+  emailAdapter: createResendAdapter({
+    apiKey: process.env.RESEND_API_KEY!,
+    from: 'newsletter@yourdomain.com',
+    adminEmail: 'you@yourdomain.com', // Get notified of new subscribers
+  }),
+  storageAdapter: createPrismaAdapter({ prisma }),
+  baseUrl: process.env.NEXT_PUBLIC_URL!,
+  doubleOptIn: true,
+  honeypotField: 'website',
+  rateLimit: {
+    max: 5,
+    windowSeconds: 60,
+  },
+});
+```
+
+### 2. Create API routes
+
+```ts
+// app/api/newsletter/subscribe/route.ts
+import { newsletter } from '@/lib/newsletter';
+
+export const POST = newsletter.subscribe;
+```
+
+```ts
+// app/api/newsletter/confirm/route.ts
+import { newsletter } from '@/lib/newsletter';
+
+export const GET = newsletter.confirm;
+```
+
+```ts
+// app/api/newsletter/unsubscribe/route.ts
+import { newsletter } from '@/lib/newsletter';
+
+export const POST = newsletter.unsubscribe;
+export const GET = newsletter.unsubscribe;
+```
+
+### 3. Add the form component
+
+```tsx
+// components/footer.tsx
+import { NewsletterForm } from '@volchoklv/newsletter-kit/components';
+
+export function Footer() {
+  return (
+    <footer>
+      <NewsletterForm
+        endpoint="/api/newsletter/subscribe"
+        source="footer"
+        placeholder="Enter your email"
+        buttonText="Subscribe"
+      />
+    </footer>
+  );
+}
+```
+
+### 4. Add Prisma schema
+
+**PostgreSQL / Neon / MySQL:**
+
+```prisma
+model NewsletterSubscriber {
+  id             String    @id @default(cuid())
+  email          String    @unique
+  status         String    @default("pending")
+  token          String?   @unique
+  source         String?
+  tags           String[]  @default([])
+  metadata       Json?
+  consentIp      String?
+  consentAt      DateTime?
+  confirmedAt    DateTime?
+  unsubscribedAt DateTime?
+  createdAt      DateTime  @default(now())
+  updatedAt      DateTime  @updatedAt
+
+  @@index([status])
+  @@index([source])
+}
+```
+
+**MongoDB:**
+
+```prisma
+model NewsletterSubscriber {
+  id             String    @id @default(auto()) @map("_id") @db.ObjectId
+  email          String    @unique
+  status         String    @default("pending")
+  token          String?   @unique
+  source         String?
+  tags           String[]  @default([])
+  metadata       Json?
+  consentIp      String?
+  consentAt      DateTime?
+  confirmedAt    DateTime?
+  unsubscribedAt DateTime?
+  createdAt      DateTime  @default(now())
+  updatedAt      DateTime  @updatedAt
+
+  @@index([status])
+  @@index([source])
+}
+```
+
+> **Note:** The adapter code works identically for both — Prisma handles the database differences.
+
+## Components
+
+### NewsletterForm
+
+Basic form component with full customization:
+
+```tsx
+<NewsletterForm
+  endpoint="/api/newsletter/subscribe"
+  source="homepage"
+  tags={['marketing', 'product-updates']}
+  placeholder="Enter your email"
+  buttonText="Subscribe"
+  loadingText="Subscribing..."
+  successMessage="Check your inbox to confirm!"
+  onSuccess={(email, message) => console.log('Subscribed:', email)}
+  onError={(error) => console.error('Error:', error)}
+  className="max-w-md"
+  inputClassName="border-2"
+  buttonClassName="bg-blue-600 hover:bg-blue-700"
+/>
+```
+
+### NewsletterBlock
+
+Full-width section for landing pages:
+
+```tsx
+<NewsletterBlock
+  endpoint="/api/newsletter/subscribe"
+  title="Stay in the loop"
+  description="Get weekly updates on the latest features and news."
+  source="landing-page"
+/>
+```
+
+### NewsletterCard
+
+Card variant for sidebars:
+
+```tsx
+<NewsletterCard
+  endpoint="/api/newsletter/subscribe"
+  title="Newsletter"
+  description="Don't miss out on updates."
+  source="sidebar"
+/>
+```
+
+### NewsletterFooter
+
+Optimized for site footers:
+
+```tsx
+<NewsletterFooter
+  endpoint="/api/newsletter/subscribe"
+  title="Newsletter"
+  description="Stay up to date."
+  source="footer"
+  privacyText="We respect your privacy."
+  privacyLink="/privacy"
+/>
+```
+
+### NewsletterModalContent
+
+For use in dialogs/modals:
+
+```tsx
+import { Dialog, DialogContent, DialogTrigger } from '@/components/ui/dialog';
+import { NewsletterModalContent } from '@volchoklv/newsletter-kit/components';
+
+export function NewsletterModal() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <Dialog open={open} onOpenChange={setOpen}>
+      <DialogTrigger asChild>
+        <Button>Subscribe</Button>
+      </DialogTrigger>
+      <DialogContent>
+        <NewsletterModalContent
+          endpoint="/api/newsletter/subscribe"
+          source="popup"
+          onSuccess={() => setTimeout(() => setOpen(false), 2000)}
+        />
+      </DialogContent>
+    </Dialog>
+  );
+}
+```
+
+## Hook
+
+For custom implementations:
+
+```tsx
+import { useNewsletter } from '@volchoklv/newsletter-kit/components';
+
+export function CustomForm() {
+  const { subscribe, isLoading, isSuccess, isError, message } = useNewsletter({
+    endpoint: '/api/newsletter/subscribe',
+    source: 'custom',
+    onSuccess: (email) => {
+      // Track in analytics
+    },
+  });
+
+  return (
+    <form onSubmit={(e) => {
+      e.preventDefault();
+      subscribe(e.currentTarget.email.value);
+    }}>
+      {/* Your custom UI */}
+    </form>
+  );
+}
+```
+
+## Email Adapters
+
+### Resend
+
+```ts
+import { createResendAdapter } from '@volchoklv/newsletter-kit/adapters/email';
+
+const emailAdapter = createResendAdapter({
+  apiKey: process.env.RESEND_API_KEY!,
+  from: 'newsletter@yourdomain.com',
+  replyTo: 'hello@yourdomain.com',
+  adminEmail: 'you@yourdomain.com',
+  templates: {
+    confirmation: {
+      subject: 'Please confirm your subscription',
+      html: ({ confirmUrl, email }) => `
+        <h1>Confirm your subscription</h1>
+        <a href="${confirmUrl}">Click here to confirm</a>
+      `,
+    },
+    welcome: {
+      subject: 'Welcome aboard! 🎉',
+      html: ({ email }) => `
+        <h1>You're subscribed!</h1>
+        <p>Thanks for joining us.</p>
+      `,
+    },
+  },
+});
+```
+
+### Nodemailer (SMTP)
+
+```ts
+import { createNodemailerAdapter } from '@volchoklv/newsletter-kit/adapters/email';
+
+const emailAdapter = createNodemailerAdapter({
+  smtp: {
+    host: 'smtp.example.com',
+    port: 587,
+    secure: false,
+    auth: {
+      user: process.env.SMTP_USER!,
+      pass: process.env.SMTP_PASS!,
+    },
+  },
+  from: 'newsletter@yourdomain.com',
+});
+```
+
+### Mailchimp
+
+```ts
+import { createMailchimpAdapter } from '@volchoklv/newsletter-kit/adapters/email';
+
+const emailAdapter = createMailchimpAdapter({
+  apiKey: process.env.MAILCHIMP_API_KEY!,
+  server: 'us1',
+  listId: 'your-list-id',
+  from: 'newsletter@yourdomain.com',
+  useAsStorage: true, // Use Mailchimp as storage too
+});
+```
+
+## Storage Adapters
+
+### Prisma
+
+```ts
+import { createPrismaAdapter } from '@volchoklv/newsletter-kit/adapters/storage';
+import { prisma } from '@/lib/prisma';
+
+const storageAdapter = createPrismaAdapter({ prisma });
+```
+
+### Supabase
+
+```ts
+import { createSupabaseAdapter } from '@volchoklv/newsletter-kit/adapters/storage';
+import { createClient } from '@supabase/supabase-js';
+
+const supabase = createClient(
+  process.env.SUPABASE_URL!,
+  process.env.SUPABASE_SERVICE_KEY!
+);
+
+const storageAdapter = createSupabaseAdapter({ supabase });
+```
+
+### In-Memory (Development/Testing)
+
+```ts
+import { createMemoryAdapter } from '@volchoklv/newsletter-kit/adapters/storage';
+
+const storageAdapter = createMemoryAdapter();
+```
+
+### No Storage (Email Only)
+
+When using Mailchimp or similar that handles storage:
+
+```ts
+import { createNoopAdapter } from '@volchoklv/newsletter-kit/adapters/storage';
+
+const storageAdapter = createNoopAdapter();
+```
+
+## Configuration
+
+Full configuration options:
+
+```ts
+const newsletter = createNewsletterHandlers({
+  // Required
+  emailAdapter: createResendAdapter({ ... }),
+  baseUrl: 'https://yourdomain.com',
+
+  // Optional storage (defaults to in-memory)
+  storageAdapter: createPrismaAdapter({ prisma }),
+
+  // Double opt-in (default: true)
+  doubleOptIn: true,
+
+  // API paths (defaults shown)
+  confirmPath: '/api/newsletter/confirm',
+  unsubscribePath: '/api/newsletter/unsubscribe',
+
+  // Bot protection
+  honeypotField: 'website',
+
+  // Rate limiting
+  rateLimit: {
+    max: 5,
+    windowSeconds: 60,
+  },
+
+  // Custom email validation
+  validateEmail: async (email) => {
+    // Block disposable emails, etc.
+    return !email.includes('tempmail.com');
+  },
+
+  // Allowed sources for tracking
+  allowedSources: ['footer', 'sidebar', 'popup', 'landing-page'],
+
+  // Default tags for all subscribers
+  defaultTags: ['newsletter'],
+
+  // Callbacks
+  onSubscribe: async (subscriber) => {
+    // Track in analytics
+  },
+  onConfirm: async (subscriber) => {
+    // Send to CRM
+  },
+  onUnsubscribe: async (email) => {
+    // Update CRM
+  },
+  onError: async (error, context) => {
+    // Log to error tracking
+  },
+});
+```
+
+## API Reference
+
+### Server Methods
+
+```ts
+// Route handlers
+newsletter.subscribe  // POST handler
+newsletter.confirm    // GET handler
+newsletter.unsubscribe // POST/GET handler
+
+// Direct access
+newsletter.handlers.subscribe(req)
+newsletter.handlers.confirm(token)
+newsletter.handlers.unsubscribe(email)
+
+// Storage access
+newsletter.storage.listSubscribers({ status: 'confirmed' })
+newsletter.getSubscriber('email@example.com')
+```
+
+## Tailwind CSS
+
+The components use Tailwind CSS with shadcn/ui-compatible class names. Make sure your `tailwind.config.js` includes:
+
+```js
+module.exports = {
+  content: [
+    // ...
+    './node_modules/@volchoklv/newsletter-kit/**/*.{js,ts,jsx,tsx}',
+  ],
+  theme: {
+    extend: {
+      colors: {
+        border: 'hsl(var(--border))',
+        input: 'hsl(var(--input))',
+        ring: 'hsl(var(--ring))',
+        background: 'hsl(var(--background))',
+        foreground: 'hsl(var(--foreground))',
+        primary: {
+          DEFAULT: 'hsl(var(--primary))',
+          foreground: 'hsl(var(--primary-foreground))',
+        },
+        muted: {
+          DEFAULT: 'hsl(var(--muted))',
+          foreground: 'hsl(var(--muted-foreground))',
+        },
+        card: {
+          DEFAULT: 'hsl(var(--card))',
+          foreground: 'hsl(var(--card-foreground))',
+        },
+      },
+    },
+  },
+};
+```
+
+Or use the `className` props to apply your own styles.
+
+## License
+
+MIT

package/dist/adapters/email/index.d.ts

@@ -0,0 +1,119 @@
+import { a as EmailAdapterConfig, E as EmailAdapter } from '../../types-BmajlhNp.js';
+export { b as EmailTemplates } from '../../types-BmajlhNp.js';
+
+interface ResendAdapterConfig extends EmailAdapterConfig {
+    apiKey: string;
+}
+/**
+ * Email adapter for Resend (https://resend.com)
+ *
+ * @example
+ * ```ts
+ * import { createResendAdapter } from '@volchok/newsletter-kit/adapters/email';
+ *
+ * const emailAdapter = createResendAdapter({
+ *   apiKey: process.env.RESEND_API_KEY!,
+ *   from: 'newsletter@yourdomain.com',
+ *   adminEmail: 'you@yourdomain.com', // optional
+ * });
+ * ```
+ */
+declare function createResendAdapter(config: ResendAdapterConfig): EmailAdapter;
+
+interface SMTPConfig {
+    host: string;
+    port: number;
+    secure?: boolean;
+    auth?: {
+        user: string;
+        pass: string;
+    };
+}
+interface NodemailerAdapterConfig extends EmailAdapterConfig {
+    smtp: SMTPConfig;
+}
+/**
+ * Email adapter for Nodemailer/SMTP
+ *
+ * @example
+ * ```ts
+ * import { createNodemailerAdapter } from '@volchok/newsletter-kit/adapters/email';
+ *
+ * const emailAdapter = createNodemailerAdapter({
+ *   smtp: {
+ *     host: 'smtp.example.com',
+ *     port: 587,
+ *     secure: false,
+ *     auth: {
+ *       user: process.env.SMTP_USER!,
+ *       pass: process.env.SMTP_PASS!,
+ *     },
+ *   },
+ *   from: 'newsletter@yourdomain.com',
+ *   adminEmail: 'you@yourdomain.com', // optional
+ * });
+ * ```
+ */
+declare function createNodemailerAdapter(config: NodemailerAdapterConfig): EmailAdapter;
+
+interface MailchimpAdapterConfig extends EmailAdapterConfig {
+    apiKey: string;
+    server: string;
+    listId: string;
+    /** If true, use Mailchimp for storage too (adds to list on subscribe) */
+    useAsStorage?: boolean;
+}
+/**
+ * Email adapter for Mailchimp
+ *
+ * Note: Mailchimp works differently from other adapters. It manages its own
+ * subscriber list, so this adapter can optionally act as both email AND storage.
+ *
+ * @example
+ * ```ts
+ * import { createMailchimpAdapter } from '@volchok/newsletter-kit/adapters/email';
+ *
+ * const emailAdapter = createMailchimpAdapter({
+ *   apiKey: process.env.MAILCHIMP_API_KEY!,
+ *   server: 'us1',
+ *   listId: 'your-list-id',
+ *   from: 'newsletter@yourdomain.com',
+ *   useAsStorage: true, // Use Mailchimp's list as storage
+ * });
+ * ```
+ */
+declare function createMailchimpAdapter(config: MailchimpAdapterConfig): EmailAdapter;
+/**
+ * Create a combined Mailchimp adapter that handles both email and storage
+ *
+ * This is useful when you want Mailchimp to be your single source of truth
+ * for subscribers.
+ */
+declare function createMailchimpStorageAdapter(config: MailchimpAdapterConfig): {
+    createSubscriber(input: {
+        email: string;
+        source?: string;
+        tags?: string[];
+    }): Promise<{
+        id: string;
+        email: string;
+        status: "pending";
+        source: string | undefined;
+        tags: string[] | undefined;
+        createdAt: Date;
+        updatedAt: Date;
+    }>;
+    getSubscriberByEmail(email: string): Promise<{
+        id: string;
+        email: string;
+        status: string;
+        tags: string[] | undefined;
+        createdAt: Date;
+        updatedAt: Date;
+    } | null>;
+    getSubscriberByToken(): Promise<null>;
+    confirmSubscriber(_token: string): Promise<null>;
+    unsubscribe(email: string): Promise<boolean>;
+};
+
+export { EmailAdapter, EmailAdapterConfig, createMailchimpAdapter, createMailchimpStorageAdapter, createNodemailerAdapter, createResendAdapter };