@volchoklv/newsletter-kit 1.0.0

package/dist/types-BmajlhNp.d.ts

@@ -0,0 +1,226 @@
+type SubscriptionStatus = 'pending' | 'confirmed' | 'unsubscribed';
+interface Subscriber {
+    id: string;
+    email: string;
+    status: SubscriptionStatus;
+    source?: string;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+    consentIp?: string;
+    consentAt?: Date;
+    confirmedAt?: Date;
+    unsubscribedAt?: Date;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface SubscribeInput {
+    email: string;
+    source?: string;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+    ip?: string;
+}
+interface SubscribeResult {
+    success: boolean;
+    message: string;
+    subscriber?: Subscriber;
+    requiresConfirmation?: boolean;
+}
+interface ConfirmResult {
+    success: boolean;
+    message: string;
+    subscriber?: Subscriber;
+}
+interface UnsubscribeResult {
+    success: boolean;
+    message: string;
+}
+interface EmailTemplates {
+    confirmation?: {
+        subject?: string;
+        html?: (data: {
+            confirmUrl: string;
+            email: string;
+        }) => string;
+        text?: (data: {
+            confirmUrl: string;
+            email: string;
+        }) => string;
+    };
+    welcome?: {
+        subject?: string;
+        html?: (data: {
+            email: string;
+        }) => string;
+        text?: (data: {
+            email: string;
+        }) => string;
+    };
+    unsubscribed?: {
+        subject?: string;
+        html?: (data: {
+            email: string;
+            resubscribeUrl?: string;
+        }) => string;
+        text?: (data: {
+            email: string;
+            resubscribeUrl?: string;
+        }) => string;
+    };
+}
+interface EmailAdapter {
+    /**
+     * Send confirmation email for double opt-in
+     */
+    sendConfirmation(email: string, token: string, confirmUrl: string): Promise<void>;
+    /**
+     * Send welcome email after subscription confirmed
+     */
+    sendWelcome(email: string): Promise<void>;
+    /**
+     * Optional: Send unsubscribe confirmation
+     */
+    sendUnsubscribed?(email: string, resubscribeUrl?: string): Promise<void>;
+    /**
+     * Optional: Notify admin of new subscriber
+     */
+    notifyAdmin?(subscriber: Subscriber): Promise<void>;
+}
+interface EmailAdapterConfig {
+    from: string;
+    replyTo?: string;
+    templates?: EmailTemplates;
+    adminEmail?: string;
+}
+interface StorageAdapter {
+    /**
+     * Create or update a subscriber (upsert behavior)
+     */
+    createSubscriber(input: SubscribeInput, token?: string): Promise<Subscriber>;
+    /**
+     * Get subscriber by email
+     */
+    getSubscriberByEmail(email: string): Promise<Subscriber | null>;
+    /**
+     * Get subscriber by confirmation token
+     */
+    getSubscriberByToken(token: string): Promise<Subscriber | null>;
+    /**
+     * Confirm a subscriber (set status to confirmed)
+     */
+    confirmSubscriber(token: string): Promise<Subscriber | null>;
+    /**
+     * Unsubscribe by email
+     */
+    unsubscribe(email: string): Promise<boolean>;
+    /**
+     * List subscribers with optional filters
+     */
+    listSubscribers?(options?: {
+        status?: SubscriptionStatus;
+        source?: string;
+        tags?: string[];
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        subscribers: Subscriber[];
+        total: number;
+    }>;
+    /**
+     * Delete subscriber permanently
+     */
+    deleteSubscriber?(email: string): Promise<boolean>;
+    /**
+     * Update subscriber metadata/tags
+     */
+    updateSubscriber?(email: string, data: Partial<Subscriber>): Promise<Subscriber | null>;
+}
+interface RateLimitConfig {
+    /** Max requests per window */
+    max: number;
+    /** Window size in seconds */
+    windowSeconds: number;
+    /** Identifier function - defaults to IP */
+    identifier?: (req: Request) => string;
+}
+interface NewsletterConfig {
+    /** Email sending adapter */
+    emailAdapter: EmailAdapter;
+    /** Storage adapter (optional - if not provided, emails are sent but not stored) */
+    storageAdapter?: StorageAdapter;
+    /** Require email confirmation (double opt-in) */
+    doubleOptIn?: boolean;
+    /** Base URL for confirmation/unsubscribe links */
+    baseUrl: string;
+    /** Path for confirmation endpoint */
+    confirmPath?: string;
+    /** Path for unsubscribe endpoint */
+    unsubscribePath?: string;
+    /** Honeypot field name for bot protection */
+    honeypotField?: string;
+    /** Rate limiting config */
+    rateLimit?: RateLimitConfig;
+    /** Custom validation for email */
+    validateEmail?: (email: string) => boolean | Promise<boolean>;
+    /** Allowed sources (for source tracking) */
+    allowedSources?: string[];
+    /** Default tags to apply */
+    defaultTags?: string[];
+    /** Callbacks */
+    onSubscribe?: (subscriber: Subscriber) => void | Promise<void>;
+    onConfirm?: (subscriber: Subscriber) => void | Promise<void>;
+    onUnsubscribe?: (email: string) => void | Promise<void>;
+    onError?: (error: Error, context: string) => void | Promise<void>;
+}
+interface NewsletterFormProps {
+    /** API endpoint for subscription */
+    endpoint?: string;
+    /** Source identifier for tracking */
+    source?: string;
+    /** Tags to apply to subscriber */
+    tags?: string[];
+    /** Honeypot field name (must match server config) */
+    honeypotField?: string;
+    /** Custom class names */
+    className?: string;
+    formClassName?: string;
+    inputClassName?: string;
+    buttonClassName?: string;
+    messageClassName?: string;
+    /** Custom text */
+    placeholder?: string;
+    buttonText?: string;
+    loadingText?: string;
+    successMessage?: string;
+    errorMessage?: string;
+    /** Show inline message or use callback only */
+    showMessage?: boolean;
+    /** Callbacks */
+    onSuccess?: (email: string, message: string) => void;
+    onError?: (error: string) => void;
+    onSubmit?: (email: string) => void;
+    /** Disable the form */
+    disabled?: boolean;
+    /** Additional metadata to send */
+    metadata?: Record<string, unknown>;
+}
+interface NewsletterFormState {
+    status: 'idle' | 'loading' | 'success' | 'error';
+    message: string;
+    email: string;
+}
+interface SubscribeRequest {
+    email: string;
+    source?: string;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface APIResponse<T = unknown> {
+    success: boolean;
+    message: string;
+    data?: T;
+    error?: string;
+}
+
+export type { APIResponse as A, ConfirmResult as C, EmailAdapter as E, NewsletterConfig as N, RateLimitConfig as R, StorageAdapter as S, UnsubscribeResult as U, EmailAdapterConfig as a, EmailTemplates as b, NewsletterFormProps as c, NewsletterFormState as d, SubscribeInput as e, SubscribeRequest as f, SubscribeResult as g, Subscriber as h, SubscriptionStatus as i };

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@volchoklv/newsletter-kit",
+  "version": "1.0.0",
+  "description": "Drop-in newsletter subscription components and API handlers for Next.js with adapter support for email providers and storage backends",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./components": {
+      "types": "./dist/components/index.d.ts",
+      "import": "./dist/components/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js"
+    },
+    "./adapters/email": {
+      "types": "./dist/adapters/email/index.d.ts",
+      "import": "./dist/adapters/email/index.js"
+    },
+    "./adapters/storage": {
+      "types": "./dist/adapters/storage/index.d.ts",
+      "import": "./dist/adapters/storage/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src/",
+    "type-check": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "next": "^14.0.0 || ^15.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@prisma/client": {
+      "optional": true
+    },
+    "@supabase/supabase-js": {
+      "optional": true
+    },
+    "resend": {
+      "optional": true
+    },
+    "nodemailer": {
+      "optional": true
+    },
+    "@mailchimp/mailchimp_marketing": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@mailchimp/mailchimp_marketing": "^3.0.80",
+    "@prisma/client": "^7.3.0",
+    "@supabase/supabase-js": "^2.91.1",
+    "@types/mailchimp__mailchimp_marketing": "^3.0.22",
+    "@types/node": "^20.0.0",
+    "@types/nodemailer": "^6.4.14",
+    "@types/react": "^18.0.0",
+    "eslint": "^8.0.0",
+    "resend": "^6.8.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "keywords": [
+    "newsletter",
+    "email",
+    "subscription",
+    "nextjs",
+    "react",
+    "resend",
+    "nodemailer",
+    "prisma",
+    "supabase",
+    "shadcn"
+  ],
+  "author": "Volchok",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/volchoklv/newsletter-kit"
+  }
+}