Plainform | Overview

The Events system allows you to display dynamic announcements on your homepage, such as new blog posts, featured coupons, or product launches. Events are stored in PostgreSQL and displayed with animated UI components.

What are Events?

Events are time-based announcements that appear at the top of your homepage. They're perfect for:

Promotional campaigns: Announce limited-time discounts or special offers
New content: Highlight new blog posts or product launches
Featured coupons: Automatically display Stripe coupons with urgency messaging
Product updates: Share important announcements with visitors

Key Features

Single Active Event

Only one event displays at a time - the most recent one. When you create a new event of the same type, it automatically replaces the previous one.

Automatic Stripe Integration

Events are automatically created when you add a Stripe coupon with isFeatured: true metadata. No manual API calls needed.

Fallback to Mock Data

If no events exist in the database, the system displays a mock event from locales/en.json, ensuring your homepage always looks complete during development.

Animated UI

Events display with animated border beams and shiny text effects, making them eye-catching without being intrusive.

Event Types

Events support three types, each with different link behavior:

Type	Description	Link Target
`coupon`	Featured discount or promotion	Opens in same tab
`post`	New blog post announcement	Opens in same tab
`product`	Product launch or update	Opens in new tab

How It Works

graph LR
    A[Create Event] --> B[Store in Database]
    B --> C[Revalidate Cache]
    C --> D[Display on Homepage]
    E[Stripe Coupon Created] --> F{isFeatured = true?}
    F -->|Yes| A
    F -->|No| G[No Event Created]

Create event via API or Stripe webhook
Store in database with timestamp
Revalidate cache to update homepage
Display event with animated UI

Database Schema

Events are stored in PostgreSQL with the following structure:

model Event {
  id        String  @id @default(cuid())
  type      String  // 'post', 'coupon', or 'product'
  slug      String  // URL to link to
  text      String  // Display text
  icon      String? // Optional icon name
  timestamp BigInt  // Creation timestamp
  
  @@index([type])
}

Security

The Events API is protected with:

API Secret Key: Required in Authorization header for all POST/DELETE requests
Rate Limiting: 10 requests per 10 seconds per IP address
Input Validation: Zod schema validation for all event data

The GET endpoint is public (no authentication required) since events are displayed on the public homepage.

Quick Example

Create an event via API:

curl -X POST https://yourdomain.com/api/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_event_api_secret" \
  -d '{
    "text": "🎉 50% off - Limited time offer!",
    "type": "coupon",
    "slug": "/#buy",
    "icon": "Sparkles"
  }'

The event appears immediately on your homepage with animated effects.

Overview