v1.5.0 - breaking changes

Author: onamfc

.env.example

@@ -33,21 +33,6 @@ LINKFORTY_PORT=3000
 # -----------------------------------------------------------------------------
 CORS_ORIGIN=*
 
-# -----------------------------------------------------------------------------
-# Authentication (Optional)
-# Generate a secure JWT secret with: openssl rand -hex 32
-# -----------------------------------------------------------------------------
-# JWT_SECRET=your-super-secret-jwt-key-here
-
-# -----------------------------------------------------------------------------
-# Email Configuration (Optional - for notifications)
-# -----------------------------------------------------------------------------
-# SMTP_HOST=smtp.gmail.com
-# SMTP_PORT=587
-# SMTP_USER=your-email@gmail.com
-# SMTP_PASS=your-app-password
-# EMAIL_FROM=Your App <noreply@yourdomain.com>
-
 # -----------------------------------------------------------------------------
 # Custom Domain Configuration (Optional)
 # -----------------------------------------------------------------------------

CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to this project will be documented in this file. This projec
 
 Automated releases are managed by [semantic-release](https://github.com/semantic-release/semantic-release).
 
+## 1.5.0 (2026-02-20)
+
+### BREAKING CHANGES - Making Core less opinionated
+
+* **Remove `users` table from Core** — Core no longer creates or manages a `users` table. Authentication and user management are now the consumer's responsibility, aligning Core with a framework-first philosophy (bring your own auth). Consumers that relied on Core's `users` table must create it themselves before any tables that reference `users(id)`.
+* **Make `user_id` nullable on `links` and `webhooks` tables** — The `user_id` column on both `links` and `webhooks` is now nullable with no foreign key constraint. This enables single-tenant usage without a user model.
+* **Remove `User`, `Organization`, `AppConfig`, and `OrganizationSettings` types** — These Cloud-only types have been removed from `@linkforty/core/types`. Consumers that imported them must define their own.
+
+### Features
+
+* **Optional `userId` across all API endpoints** — All link, analytics, webhook, and debug endpoints now accept `userId` as an optional parameter. When provided, queries are scoped to that user (multi-tenant mode). When omitted, all records are accessible (single-tenant mode).
+* **Single-tenant mode** — Core can now be used without any user/auth model. Create and manage links, view analytics, and configure webhooks without providing a `userId`.
+* **WebSocket live debug stream no longer requires `userId`** — When `userId` is omitted, the `/api/debug/live` WebSocket streams all click events.
+
+### Removed
+
+* `users` table DDL and `idx_users_email` index from `initializeDatabase()`
+* `JWT_SECRET` and email configuration sections from `.env.example`
+* `User`, `Organization`, `AppConfig`, `OrganizationSettings` interfaces from types
+
 ## 1.4.4 (2026-02-11)
 
 ### Features

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linkforty/core",
-  "version": "1.4.4",
+  "version": "1.5.0",
   "type": "module",
   "description": "Open-source deeplink management engine with device detection and analytics",
   "main": "dist/index.js",

src/lib/database.ts

@@ -51,23 +51,11 @@ export async function initializeDatabase(options: DatabaseOptions = {}) {
   const client = await connectWithRetry();
 
   try {
-    // Users table
-    await client.query(`
-      CREATE TABLE IF NOT EXISTS users (
-        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-        email VARCHAR(255) UNIQUE NOT NULL,
-        name VARCHAR(255) NOT NULL,
-        password_hash VARCHAR(255) NOT NULL,
-        created_at TIMESTAMP DEFAULT NOW(),
-        updated_at TIMESTAMP DEFAULT NOW()
-      )
-    `);
-
     // Links table
     await client.query(`
       CREATE TABLE IF NOT EXISTS links (
         id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-        user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+        user_id UUID,
         short_code VARCHAR(20) UNIQUE NOT NULL,
         original_url TEXT NOT NULL,
         title VARCHAR(255),
@@ -168,7 +156,7 @@ export async function initializeDatabase(options: DatabaseOptions = {}) {
     await client.query(`
       CREATE TABLE IF NOT EXISTS webhooks (
         id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-        user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+        user_id UUID,
         name VARCHAR(255) NOT NULL,
         url TEXT NOT NULL,
         secret VARCHAR(255) NOT NULL,
@@ -361,8 +349,6 @@ export async function initializeDatabase(options: DatabaseOptions = {}) {
     await client.query('CREATE INDEX IF NOT EXISTS idx_clicks_link_id ON click_events(link_id)');
     await client.query('CREATE INDEX IF NOT EXISTS idx_clicks_timestamp ON click_events(clicked_at DESC)');
     await client.query('CREATE INDEX IF NOT EXISTS idx_clicks_link_date ON click_events(link_id, clicked_at DESC)');
-    await client.query('CREATE INDEX IF NOT EXISTS idx_users_email ON users(email)');
-
     // Indexes for deferred deep linking
     await client.query('CREATE INDEX IF NOT EXISTS idx_fingerprints_hash ON device_fingerprints(fingerprint_hash)');
     await client.query('CREATE INDEX IF NOT EXISTS idx_fingerprints_click_id ON device_fingerprints(click_id)');

src/lib/event-emitter.ts

@@ -14,7 +14,7 @@ export interface ClickEventData {
   timestamp: string;
   linkId: string;
   shortCode: string;
-  userId: string;
+  userId?: string;
   organizationId?: string;
 
   // Request details

src/routes/analytics.ts

@@ -2,15 +2,15 @@ import { FastifyInstance, FastifyRequest } from 'fastify';
 import { db } from '../lib/database.js';
 
 export async function analyticsRoutes(fastify: FastifyInstance) {
-  // Get overall analytics for a user
+  // Get overall analytics (optionally filtered by userId)
   fastify.get('/api/analytics/overview', async (request: FastifyRequest<{
-    Querystring: { userId: string; days?: number }
+    Querystring: { userId?: string; days?: number }
   }>) => {
     const { userId, days = 30 } = request.query;
 
-    if (!userId) {
-      throw new Error('userId query parameter is required');
-    }
+    const userFilter = userId ? 'AND l.user_id = $1' : '';
+    const userFilterWhere = userId ? 'WHERE l.user_id = $1' : '';
+    const params = userId ? [userId] : [];
 
     // Get total and unique clicks
     const clicksResult = await db.query(
@@ -19,8 +19,8 @@ export async function analyticsRoutes(fastify: FastifyInstance) {
          COUNT(DISTINCT ip_address) as unique_clicks
        FROM click_events ce
               JOIN links l ON ce.link_id = l.id
-       WHERE l.user_id = $1 AND ce.clicked_at >= NOW() - INTERVAL '${days} days'`,
-      [userId]
+       WHERE ce.clicked_at >= NOW() - INTERVAL '${days} days' ${userFilter}`,
+      params
     );
 
     // Get clicks by date
@@ -30,10 +30,10 @@ export async function analyticsRoutes(fastify: FastifyInstance) {
          COUNT(*) as clicks
        FROM click_events ce
          JOIN links l ON ce.link_id = l.id
-       WHERE l.user_id = $1 AND ce.clicked_at >= NOW() - INTERVAL '${days} days'
+       WHERE ce.clicked_at >= NOW() - INTERVAL '${days} days' ${userFilter}
        GROUP BY DATE(ce.clicked_at)
        ORDER BY date`,
-      [userId]
+      params
     );
 
     // Get clicks by country
@@ -44,10 +44,10 @@ export async function analyticsRoutes(fastify: FastifyInstance) {
          COUNT(*) as clicks
        FROM click_events ce
               JOIN links l ON ce.link_id = l.id
-       WHERE l.user_id = $1 AND ce.clicked_at >= NOW() - INTERVAL '${days} days'
+       WHERE ce.clicked_at >= NOW() - INTERVAL '${days} days' ${userFilter}
        GROUP BY ce.country_code, ce.country_name
        ORDER BY clicks DESC`,
-      [userId]
+      params
     );
 
     // Get clicks by device
@@ -57,10 +57,10 @@ export async function analyticsRoutes(fastify: FastifyInstance) {
          COUNT(*) as clicks
        FROM click_events ce
               JOIN links l ON ce.link_id = l.id
-       WHERE l.user_id = $1 AND ce.clicked_at >= NOW() - INTERVAL '${days} days'
+       WHERE ce.clicked_at >= NOW() - INTERVAL '${days} days' ${userFilter}
        GROUP BY ce.device_type
        ORDER BY clicks DESC`,
-      [userId]
+      params
     );
 
     // Get clicks by platform
@@ -70,10 +70,10 @@ export async function analyticsRoutes(fastify: FastifyInstance) {
          COUNT(*) as clicks
        FROM click_events ce
               JOIN links l ON ce.link_id = l.id
-       WHERE l.user_id = $1 AND ce.clicked_at >= NOW() - INTERVAL '${days} days'
+       WHERE ce.clicked_at >= NOW() - INTERVAL '${days} days' ${userFilter}
        GROUP BY ce.platform
        ORDER BY clicks DESC`,
-      [userId]
+      params
     );
 
     // Get top performing links
@@ -88,11 +88,11 @@ export async function analyticsRoutes(fastify: FastifyInstance) {
        FROM links l
               LEFT JOIN click_events ce ON l.id = ce.link_id
          AND ce.clicked_at >= NOW() - INTERVAL '${days} days'
-       WHERE l.user_id = $1
+       ${userFilterWhere}
        GROUP BY l.id
        ORDER BY total_clicks DESC
          LIMIT 10`,
-      [userId]
+      params
     );
 
     return {
@@ -129,21 +129,25 @@ export async function analyticsRoutes(fastify: FastifyInstance) {
   // Get link-specific analytics
   fastify.get('/api/analytics/links/:linkId', async (request: FastifyRequest<{
     Params: { linkId: string };
-    Querystring: { userId: string; days?: number };
+    Querystring: { userId?: string; days?: number };
   }>) => {
     const { linkId } = request.params;
     const { userId, days = 30 } = request.query;
 
-    if (!userId) {
-      throw new Error('userId query parameter is required');
+    // Verify link exists (and ownership if userId provided)
+    let linkResult;
+    if (userId) {
+      linkResult = await db.query(
+        'SELECT id FROM links WHERE id = $1 AND user_id = $2',
+        [linkId, userId]
+      );
+    } else {
+      linkResult = await db.query(
+        'SELECT id FROM links WHERE id = $1',
+        [linkId]
+      );
     }
 
-    // Verify link ownership
-    const linkResult = await db.query(
-      'SELECT id FROM links WHERE id = $1 AND user_id = $2',
-      [linkId, userId]
-    );
-
     if (linkResult.rows.length === 0) {
       throw new Error('Link not found');
     }

src/routes/debug.ts

@@ -9,7 +9,7 @@ import { subscribeToClickEvents, ClickEventData } from '../lib/event-emitter.js'
  */
 const simulateRequestSchema = z.object({
   linkId: z.string().uuid(),
-  userId: z.string().uuid(),
+  userId: z.string().uuid().optional(),
   deviceType: z.enum(['ios', 'android', 'web']).optional(),
   userAgent: z.string().optional(),
   country: z.string().length(2).optional(), // ISO country code
@@ -33,10 +33,18 @@ export async function debugRoutes(fastify: FastifyInstance) {
     const data = simulateRequestSchema.parse(request.body);
 
     // Fetch the link
-    const linkResult = await db.query(
-      `SELECT * FROM links WHERE id = $1 AND user_id = $2`,
-      [data.linkId, data.userId]
-    );
+    let linkResult;
+    if (data.userId) {
+      linkResult = await db.query(
+        `SELECT * FROM links WHERE id = $1 AND user_id = $2`,
+        [data.linkId, data.userId]
+      );
+    } else {
+      linkResult = await db.query(
+        `SELECT * FROM links WHERE id = $1`,
+        [data.linkId]
+      );
+    }
 
     if (linkResult.rows.length === 0) {
       throw new Error('Link not found');
@@ -299,37 +307,26 @@ export async function debugRoutes(fastify: FastifyInstance) {
     '/api/debug/live',
     { websocket: true },
     (connection: any, request: FastifyRequest<{
-      Querystring: { userId: string; linkId?: string };
+      Querystring: { userId?: string; linkId?: string };
     }>) => {
       const { userId, linkId } = request.query;
 
-      if (!userId) {
-        connection.socket.send(
-          JSON.stringify({
-            type: 'error',
-            message: 'userId query parameter is required',
-          })
-        );
-        connection.socket.close();
-        return;
-      }
-
       // Send welcome message
       connection.socket.send(
         JSON.stringify({
           type: 'connected',
           message: 'Connected to live request inspector',
           filters: {
-            userId,
+            userId: userId || 'all',
             linkId: linkId || 'all',
           },
         })
       );
 
       // Subscribe to click events
       const unsubscribe = subscribeToClickEvents((eventData: ClickEventData) => {
-        // Filter by userId
-        if (eventData.userId !== userId) {
+        // Filter by userId if provided
+        if (userId && eventData.userId !== userId) {
           return;
         }