← reference

Drops Currency System

Overview

Drops are the in-app currency for HiveJournal, themed as "honey drops" to match the hive theme. Users earn drops through signup bonuses and monthly recurring awards, and can spend them to purchase tone packs.

Currency Rules

Earning Drops

  1. Signup Bonus: 50 drops awarded automatically when a user signs up
  2. Monthly Recurring:
    • Regular users: 30 drops per month
    • Premium users (active subscription): 250 drops per month

Spending Drops

  • Tone Packs: Users can purchase tone packs with drops (price set by pack creator)

Database Schema

Tables

  • profiles.drops_balance: Current balance of drops for each user
  • drop_transactions: Transaction history for all drop movements
  • monthly_drops: Tracks monthly recurring drop awards to prevent duplicates
  • tone_packs.price_drops: Price in drops to purchase a tone pack
  • tone_pack_purchases: Records which users have purchased which tone packs

API Endpoints

Drops

  • GET /api/drops/balance - Get current drop balance
  • GET /api/drops/transactions - Get transaction history
  • POST /api/drops/award-monthly - Manually trigger monthly drops (for testing)
  • POST /api/drops/cron/award-monthly-all - Cron endpoint to award monthly drops to all users

Tone Packs (Updated)

  • POST /api/tone-packs/:id/purchase - Purchase a tone pack with drops
  • GET /api/tone-packs - Now includes purchased section

Setup

1. Database Migration

Run the migration to create the necessary tables:

supabase migration up

Or manually run supabase/migrations/016_add_drops_currency.sql

2. Signup Bonus

The signup bonus is automatically awarded via a database trigger when a profile is created. The trigger function award_signup_bonus() checks if the user has already received the bonus to prevent duplicates.

3. Monthly Drops Cron Job

Set up a cron job to call the monthly drops endpoint. Example configurations:

Vercel Cron

Add to vercel.json:

{
  "crons": [{
    "path": "/api/drops/cron/award-monthly-all",
    "schedule": "0 0 1 * *"
  }]
}

Railway Cron

Use Railway's cron job feature or an external service like EasyCron to call:

POST https://your-api-url.com/api/drops/cron/award-monthly-all
Headers: x-cron-secret: YOUR_SECRET

Environment Variables

Set DROPS_CRON_SECRET in your backend environment for cron endpoint security.

4. Premium User Detection

The system checks for active subscriptions in the subscriptions table:

  • Status must be 'active'
  • User must have a record in the subscriptions table

Usage

Frontend

The drops balance is displayed in the Tone Packs settings section. Users can:

  • View their current balance
  • Purchase tone packs with drops
  • See transaction history (future enhancement)

Backend

Use the helper functions in apps/backend/src/routes/drops.ts:

import { addDrops, deductDrops, awardSignupBonus, awardMonthlyDrops } from './routes/drops.js'

// Award signup bonus
await awardSignupBonus(userId)

// Award monthly drops
await awardMonthlyDrops(userId)

// Add drops manually
await addDrops(userId, 100, 'admin_adjustment', 'Admin bonus')

// Deduct drops
await deductDrops(userId, 50, 'purchase', 'Purchased item', itemId, 'item_type')

Transaction Types

  • signup_bonus: Initial 50 drops on signup
  • monthly_recurring: Monthly drops (30 or 250)
  • purchase: Spending drops on tone packs
  • refund: Refund for purchases (future)
  • admin_adjustment: Manual adjustments by admins

Future Enhancements

  • Drop purchase via Stripe
  • Drop gifting between users
  • Drop rewards for achievements
  • Drop expiration (optional)
  • Drop history UI in settings
  • Drop balance display in navbar
DROPS CURRENCY — Docs | HiveJournal