Release v1.6.0

Docker Image

Pull the image:

docker pull docker.io/linkforty/core:1.6.0

Run with Docker Compose:

curl -o docker-compose.yml https://raw.githubusercontent.com/linkforty/core/v1.6.0/examples/docker-compose.yml
docker compose up -d

See CHANGELOG.md for details.

Release v1.5.1

Docker Image

Pull the image:

docker pull docker.io/linkforty/core:1.5.1

Run with Docker Compose:

curl -o docker-compose.yml https://raw.githubusercontent.com/linkforty/core/v1.5.1/examples/docker-compose.yml
docker compose up -d

See CHANGELOG.md for details.

Release v1.5.0

Summary

• Decouple Core from auth/user management to align with its role as a framework (like Laravel for deeplinks) — not an opinionated full-stack app
• Remove the users table, make userId optional everywhere, and remove Cloud-only types that leaked into Core
• Enables single-tenant usage out of the box without any auth layer

Breaking Changes

users table removed from initializeDatabase()

Core no longer creates or manages a users table. Consumers that relied on it must create the table themselves before calling initializeDatabase().

user_id column on links and webhooks is now nullable with no FK

• Changed from UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE to UUID (nullable, no foreign key)
• Existing consumers that always provide userId are unaffected — the column still accepts UUIDs

userId is optional in all API endpoints

• POST /api/links — userId field in request body is now optional
• GET/PUT/DELETE /api/links/:id — userId query param is now optional
• GET /api/analytics/overview and GET /api/analytics/links/:linkId — same
• GET/POST/PUT/DELETE /api/webhooks — same
• POST /api/debug/simulate and WS /api/debug/live — same
• When userId is omitted, routes operate in single-tenant mode (no user scoping)
• When userId is provided, routes filter by user_id (multi-tenant mode)

Removed types from @linkforty/core/types

• User — auth concern, consumers define their own
• Organization, AppConfig, OrganizationSettings — Cloud-only, never used by Core

Link.userId is now optional in the TypeScript interface

• ClickEventData.userId is now optional (string | undefined)

Other Changes

• Removed JWT_SECRET and email configuration sections from .env.example
• Removed idx_users_email index from schema initialization
• Added CLAUDE.md to .gitignore
• Updated CLAUDE.md to reflect framework-first philosophy

What does NOT change

• Redirect engine, SDK routes, QR generation, OG preview, well-known routes — all unchanged
• Utilities (generateShortCode, device detection, geo lookup) — unchanged
• Redis caching, webhook delivery, event emitters — unchanged
• All existing tests pass (20/20)

Cloud compatibility

Cloud is not affected because:

• Cloud already has its own link/analytics/webhook routes with JWT + org-based multi-tenancy
• Cloud always provides user_id on inserts and scopes reads by organization_id
• Cloud's initializeSaaSDatabase() now creates the users table itself (see Cloud v1.4.10)

Docker Image

Pull the image:

docker pull docker.io/linkforty/core:1.5.0

Run with Docker Compose:

curl -o docker-compose.yml https://raw.githubusercontent.com/linkforty/core/v1.5.0/examples/docker-compose.yml
docker compose up -d

See CHANGELOG.md for details.

Release v1.4.4

Docker Image

Pull the image:

docker pull docker.io/linkforty/core:1.4.4

Run with Docker Compose:

curl -o docker-compose.yml https://raw.githubusercontent.com/linkforty/core/v1.4.4/examples/docker-compose.yml
docker compose up -d

See CHANGELOG.md for details.

Release v1.4.3

Docker Image

Pull the image:

docker pull docker.io/linkforty/core:1.4.3

Run with Docker Compose:

curl -o docker-compose.yml https://raw.githubusercontent.com/linkforty/core/v1.4.3/examples/docker-compose.yml
docker compose up -d

See CHANGELOG.md for details.

v1.0.0 - Initial Release!

Release v1.0.0 🎉

This is the first official release of @linkforty/core with automated CI/CD, semantic versioning, and comprehensive testing infrastructure.

What is LinkForty Core?

LinkForty Core is an open-source deeplink management engine that provides smart link routing with device detection, analytics, and UTM parameter support. Built on Fastify with PostgreSQL for persistence and optional Redis for caching.

Features

Smart Linking & Routing

• QR Code Generation - Generate QR codes for short links with configurable sizes and error correction levels
• Open Graph Support - Rich social media previews with customizable OG tags
• Deferred Deep Linking - Probabilistic fingerprint matching for app install attribution
• Device-Specific URLs - Route users to platform-specific destinations (iOS/Android/Web)

Real-Time Features

• Event Streaming - Real-time click event broadcasting via WebSocket
• Live Analytics - Stream click events to connected clients in real-time
• Event Emitter - Programmatic access to click events for custom integrations

Developer Experience

• TypeScript First - Full type definitions and type safety
• Comprehensive API - RESTful endpoints for link management and analytics
• Testing Routes - Built-in debugging endpoints for link validation
• Modular Architecture - Use as a complete server or import individual components

Data & Analytics

• Attribution Windows - Configurable time windows for conversion tracking
• Click Analytics - Comprehensive tracking with geolocation, device, platform, and referrer data
• UTM Parameters - Built-in support for campaign tracking
• Device Detection - Automatic user-agent parsing for platform identification

Getting Started

Installation

npm install @linkforty/core

Quick Start

import { createServer } from '@linkforty/core';

const server = await createServer({
  port: 3000,
  corsOrigin: '*'
});

await server.listen({ port: 3000 });
console.log('Server running on http://localhost:3000');

Docker Deployment

# Clone the repository
git clone https://github.com/linkforty/core.git
cd core/examples

# Start services
docker compose up -d

The API will be available at http://localhost:3000

CI/CD & Automation

This release includes:

• ✅ Automated testing with Vitest
• ✅ Code coverage reporting with Codecov
• ✅ Multi-platform Docker builds (AMD64)
• ✅ Semantic versioning with conventional commits
• ✅ Automated releases to NPM and GitHub
• ✅ Comprehensive GitHub Actions workflows

Changelog

For a detailed list of changes, see CHANGELOG.md.

Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Full Changelog: https://github.com/linkforty/core/commits/v1.0.0

For issues, questions, or feature requests, please open an issue on GitHub.