@linkforty/core 1.4.4 → 1.6.6

package/README.md

@@ -3,9 +3,9 @@
 
   # LinkForty Core
 
-  **Open-source deeplink management engine with device detection and analytics**
+  **Open-source alternative to Branch.io, AppsFlyer OneLink, and Firebase Dynamic Links**
 
-  LinkForty Core is a powerful, self-hosted deeplink management system that enables you to create, manage, and track smart links with device-specific routing, analytics, and UTM parameter support. It's the open-source foundation of the LinkForty platform.
+  Self-hosted deep linking engine with device detection, analytics, deferred deep linking, and smart routing. No per-click pricing, no vendor lock-in, full data ownership — runs on your own PostgreSQL. Firebase Dynamic Links shut down in August 2025; LinkForty is a production-ready, open-source replacement you can deploy today.
 </div>
 
 [![npm version](https://img.shields.io/npm/v/@linkforty/core.svg)](https://www.npmjs.com/package/@linkforty/core)
@@ -13,18 +13,52 @@
 [![codecov](https://codecov.io/gh/linkforty/core/branch/main/graph/badge.svg)](https://codecov.io/gh/linkforty/core)
 [![Docker Pulls](https://img.shields.io/docker/pulls/linkforty/core)](https://hub.docker.com/r/linkforty/core)
 [![Docker Image Size](https://img.shields.io/docker/image-size/linkforty/core/latest)](https://hub.docker.com/r/linkforty/core)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-
-## Features 
-
-✅ **Smart Link Routing** - Create short links with device-specific URLs for iOS, Android, and web \
-✅ **Device Detection** - Automatic detection and routing based on user device \
-✅ **Click Analytics** - Track clicks with geolocation, device type, platform, and more \
-✅ **UTM Parameters** - Built-in support for UTM campaign tracking \
-✅ **Link Expiration** - Set expiration dates for time-sensitive links \
-✅ **Redis Caching** - Optional Redis support for high-performance link lookups \
-✅ **PostgreSQL Storage** - Reliable data persistence with full SQL capabilities \
-✅ **TypeScript** - Fully typed API for better developer experience 
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
+
+## Why LinkForty?
+
+- **Self-hosted and open-source** — AGPL-3.0 licensed, deploy on your own infrastructure
+- **No per-click pricing** — No usage-based fees, no monthly minimums, no enterprise sales calls
+- **Full data ownership** — All click data, analytics, and attribution stored in your PostgreSQL database
+- **Privacy-first** — No third-party data sharing, no tracking pixels, your users' data stays with you
+- **Drop-in replacement** — REST API + mobile SDKs for React Native, Expo, iOS (Swift), and Android (Kotlin)
+- **Firebase Dynamic Links replacement** — Google shut down Firebase Dynamic Links in August 2025. LinkForty provides the same capabilities with a self-hosted, open-source stack
+
+### How LinkForty Compares
+
+| Feature | LinkForty Core | Branch | AppsFlyer | Firebase Dynamic Links |
+|---------|---------------|--------|-----------|----------------------|
+| **Pricing** | Free (self-hosted) | Starts at $299/mo | Starts at $500/mo | Shut down (Aug 2025) |
+| **Open Source** | Yes (AGPL-3.0) | No | No | No |
+| **Self-Hosted** | Yes | No | No | No |
+| **Data Ownership** | Complete | Vendor-controlled | Vendor-controlled | Was Google-controlled |
+| **Deferred Deep Linking** | Yes | Yes | Yes | Was supported |
+| **Device Detection & Routing** | Yes | Yes | Yes | Was supported |
+| **Click Analytics** | Yes | Yes | Yes | Basic |
+| **QR Code Generation** | Built-in | No | No | No |
+| **Webhooks** | Yes | Enterprise only | Enterprise only | No |
+| **iOS Universal Links** | Yes | Yes | Yes | Was supported |
+| **Android App Links** | Yes | Yes | Yes | Was supported |
+| **UTM Parameter Tracking** | Yes | Yes | Custom params | Was supported |
+| **Custom Domains** | Yes | Enterprise only | Enterprise only | No |
+
+## Features
+
+**Smart Link Routing** - Create short links with device-specific URLs for iOS, Android, and web \
+**Device Detection** - Automatic detection and routing based on user device \
+**Click Analytics** - Track clicks with geolocation, device type, platform, and more \
+**UTM Parameters** - Built-in support for UTM campaign tracking \
+**Targeting Rules** - Filter by country, device, and language before redirecting \
+**QR Code Generation** - Generate QR codes (PNG/SVG) for any link \
+**Deferred Deep Linking** - Probabilistic fingerprint matching for install attribution \
+**Webhooks** - Event-driven integrations with HMAC-signed payloads and retry logic \
+**OG Preview Pages** - Social media scraper detection with Open Graph meta tags \
+**iOS Universal Links & Android App Links** - Serve `.well-known` files automatically \
+**Link Expiration** - Set expiration dates for time-sensitive links \
+**Redis Caching** - Optional Redis support for high-performance link lookups \
+**PostgreSQL Storage** - Reliable data persistence with full SQL capabilities \
+**TypeScript** - Fully typed API for better developer experience \
+**No Auth Included** - Bring your own authentication; `userId` is optional for multi-tenant scoping
 
 ## Installation
 
@@ -81,17 +115,21 @@ docker run -d \
 ```
 
 **Features:**
-- ✅ Pre-built multi-architecture images (AMD64 + ARM64)
-- ✅ Automatic updates with version tags
-- ✅ Non-root user for security
-- ✅ Built-in health checks
-- ✅ Supply chain attestations (SBOM + Provenance)
+- Pre-built multi-architecture images (AMD64 + ARM64)
+- Automatic updates with version tags
+- Non-root user for security
+- Built-in health checks
+- Supply chain attestations (SBOM + Provenance)
 
 See [DOCKER.md](DOCKER.md) for complete deployment guide.
 
 ## API Reference
 
-### Create a Link
+### Links
+
+#### Create a Link
+
+`userId` is optional. When provided, the link is scoped to that user (multi-tenant mode). When omitted, the link has no owner (single-tenant mode).
 
 ```bash
 POST /api/links
@@ -101,57 +139,54 @@ Content-Type: application/json
   "userId": "user-uuid",
   "originalUrl": "https://example.com",
   "title": "My Link",
-  "iosUrl": "myapp://product/123",
-  "androidUrl": "myapp://product/123",
+  "description": "Summer campaign link",
+  "iosAppStoreUrl": "https://apps.apple.com/app/id123456",
+  "androidAppStoreUrl": "https://play.google.com/store/apps/details?id=com.example",
   "webFallbackUrl": "https://example.com/product/123",
+  "appScheme": "myapp",
+  "iosUniversalLink": "https://example.com/app/product/123",
+  "androidAppLink": "https://example.com/app/product/123",
+  "deepLinkPath": "/product/123",
+  "deepLinkParameters": { "ref": "campaign-1" },
   "utmParameters": {
     "source": "twitter",
     "medium": "social",
     "campaign": "summer-sale"
   },
+  "ogTitle": "Check out this deal",
+  "ogDescription": "50% off summer sale",
+  "ogImageUrl": "https://example.com/og-image.png",
+  "targetingRules": {
+    "countries": ["US", "CA"],
+    "devices": ["ios", "android"],
+    "languages": ["en"]
+  },
+  "attributionWindowHours": 168,
   "customCode": "summer-sale",
-  "expiresAt": "2024-12-31T23:59:59Z"
+  "expiresAt": "2026-12-31T23:59:59Z"
 }
 ```
 
-**Response:**
+All fields except `originalUrl` are optional.
 
-```json
-{
-  "id": "link-uuid",
-  "userId": "user-uuid",
-  "short_code": "summer-sale",
-  "original_url": "https://example.com",
-  "title": "My Link",
-  "ios_url": "myapp://product/123",
-  "android_url": "myapp://product/123",
-  "web_fallback_url": "https://example.com/product/123",
-  "utmParameters": {
-    "source": "twitter",
-    "medium": "social",
-    "campaign": "summer-sale"
-  },
-  "is_active": true,
-  "expires_at": "2024-12-31T23:59:59Z",
-  "created_at": "2024-01-01T00:00:00Z",
-  "updated_at": "2024-01-01T00:00:00Z",
-  "clickCount": 0
-}
-```
-
-### Get All Links
+#### Get All Links
 
 ```bash
+# Single-tenant (all links)
+GET /api/links
+
+# Multi-tenant (scoped to user)
 GET /api/links?userId=user-uuid
 ```
 
-### Get a Specific Link
+#### Get a Specific Link
 
 ```bash
+GET /api/links/:id
 GET /api/links/:id?userId=user-uuid
 ```
 
-### Update a Link
+#### Update a Link
 
 ```bash
 PUT /api/links/:id?userId=user-uuid
@@ -163,62 +198,99 @@ Content-Type: application/json
 }
 ```
 
-### Delete a Link
+#### Duplicate a Link
+
+```bash
+POST /api/links/:id/duplicate?userId=user-uuid
+```
+
+#### Delete a Link
 
 ```bash
 DELETE /api/links/:id?userId=user-uuid
 ```
 
-### Get Analytics Overview
+### Analytics
+
+#### Get Analytics Overview
 
 ```bash
+# All links
+GET /api/analytics/overview?days=30
+
+# Scoped to user
 GET /api/analytics/overview?userId=user-uuid&days=30
 ```
 
-**Response:**
+Returns: `totalClicks`, `uniqueClicks`, `clicksByDate`, `clicksByCountry`, `clicksByDevice`, `clicksByPlatform`, `topLinks`
 
-```json
-{
-  "totalClicks": 1234,
-  "uniqueClicks": 567,
-  "clicksByDate": [
-    { "date": "2024-01-01", "clicks": 45 }
-  ],
-  "clicksByCountry": [
-    { "countryCode": "US", "country": "United States", "clicks": 234 }
-  ],
-  "clicksByDevice": [
-    { "device": "mobile", "clicks": 789 }
-  ],
-  "clicksByPlatform": [
-    { "platform": "iOS", "clicks": 456 }
-  ],
-  "topLinks": [
-    {
-      "id": "link-uuid",
-      "shortCode": "summer-sale",
-      "title": "My Link",
-      "originalUrl": "https://example.com",
-      "totalClicks": 123,
-      "uniqueClicks": 67
-    }
-  ]
-}
+#### Get Link-Specific Analytics
+
+```bash
+GET /api/analytics/links/:linkId?days=30
 ```
 
-### Get Link-Specific Analytics
+### Redirect
 
 ```bash
-GET /api/analytics/links/:linkId?userId=user-uuid&days=30
+GET /:shortCode
+GET /:templateSlug/:shortCode
 ```
 
-### Redirect Short Link
+Automatically redirects users to the appropriate URL based on device type (iOS/Android/web), evaluates targeting rules, and tracks the click asynchronously.
+
+### QR Codes
 
 ```bash
-GET /:shortCode
+GET /api/links/:id/qr?format=png&size=300
+GET /api/links/:id/qr?format=svg
+```
+
+### Webhooks
+
+```bash
+GET    /api/webhooks?userId=user-uuid
+POST   /api/webhooks                     # Body: { name, url, events, userId? }
+GET    /api/webhooks/:id?userId=user-uuid
+PUT    /api/webhooks/:id?userId=user-uuid
+DELETE /api/webhooks/:id?userId=user-uuid
+POST   /api/webhooks/:id/test?userId=user-uuid
 ```
 
-This endpoint automatically redirects users to the appropriate URL based on their device type.
+Events: `click_event`, `install_event`, `conversion_event`. Payloads are HMAC SHA-256 signed.
+
+### Mobile SDK Endpoints
+
+```bash
+POST /api/sdk/v1/install               # Report app install, get deferred deep link
+GET  /api/sdk/v1/attribution/:fingerprint  # Debug attribution lookups
+POST /api/sdk/v1/event                 # Track in-app conversion events
+GET  /api/sdk/v1/resolve/:shortCode    # Resolve link to deep link data (no redirect)
+GET  /api/sdk/v1/health                # Health check
+```
+
+### Debug & Testing
+
+```bash
+POST /api/debug/simulate               # Simulate a link click with custom parameters
+WS   /api/debug/live?userId=user-uuid  # WebSocket live click event stream
+GET  /api/debug/user-agents            # Common UA strings for testing
+GET  /api/debug/countries              # Common countries list
+GET  /api/debug/languages              # Common languages list
+```
+
+### Well-Known Routes
+
+```bash
+GET /.well-known/apple-app-site-association   # iOS Universal Links
+GET /.well-known/assetlinks.json              # Android App Links
+```
+
+### OG Preview
+
+```bash
+GET /:shortCode/preview                # OG meta tag page for social scrapers
+```
 
 ## Configuration
 
@@ -251,39 +323,50 @@ REDIS_URL=redis://localhost:6379
 PORT=3000
 NODE_ENV=production
 CORS_ORIGIN=*
+
+# Mobile SDK (optional — for iOS Universal Links and Android App Links)
+IOS_TEAM_ID=ABC123XYZ
+IOS_BUNDLE_ID=com.yourcompany.yourapp
+ANDROID_PACKAGE_NAME=com.yourcompany.yourapp
+ANDROID_SHA256_FINGERPRINTS=AA:BB:CC:DD:...
+
+# Custom domain for QR code URLs (optional)
+SHORTLINK_DOMAIN=yourdomain.com
 ```
 
 ## Database Schema
 
-### Users Table
-
-| Column        | Type         | Description           |
-|---------------|--------------|-----------------------|
-| id            | UUID         | Primary key           |
-| email         | VARCHAR(255) | Unique email          |
-| name          | VARCHAR(255) | User name             |
-| password_hash | VARCHAR(255) | Hashed password       |
-| created_at    | TIMESTAMP    | Creation timestamp    |
-| updated_at    | TIMESTAMP    | Last update timestamp |
+Core does not create a `users` table. Authentication and user management are the consumer's responsibility. The `user_id` column on `links` and `webhooks` is optional (nullable, no foreign key) — use it for multi-tenant scoping when your auth layer provides a user identity.
 
 ### Links Table
 
-| Column           | Type         | Description           |
-|------------------|--------------|-----------------------|
-| id               | UUID         | Primary key           |
-| user_id          | UUID         | Foreign key to users  |
-| short_code       | VARCHAR(20)  | Unique short code     |
-| original_url     | TEXT         | Original URL          |
-| title            | VARCHAR(255) | Link title            |
-| ios_url          | TEXT         | iOS-specific URL      |
-| android_url      | TEXT         | Android-specific URL  |
-| web_fallback_url | TEXT         | Web fallback URL      |
-| utm_parameters   | JSONB        | UTM parameters        |
-| targeting_rules  | JSONB        | Targeting rules       |
-| is_active        | BOOLEAN      | Active status         |
-| expires_at       | TIMESTAMP    | Expiration date       |
-| created_at       | TIMESTAMP    | Creation timestamp    |
-| updated_at       | TIMESTAMP    | Last update timestamp |
+| Column                  | Type         | Description                              |
+|-------------------------|--------------|------------------------------------------|
+| id                      | UUID         | Primary key                              |
+| user_id                 | UUID         | Optional owner/tenant identifier         |
+| short_code              | VARCHAR(20)  | Unique short code                        |
+| original_url            | TEXT         | Original URL                             |
+| title                   | VARCHAR(255) | Link title                               |
+| description             | TEXT         | Link description                         |
+| ios_app_store_url       | TEXT         | iOS App Store URL                        |
+| android_app_store_url   | TEXT         | Android Play Store URL                   |
+| web_fallback_url        | TEXT         | Web fallback URL                         |
+| app_scheme              | VARCHAR(255) | URI scheme (e.g., "myapp")               |
+| ios_universal_link      | TEXT         | iOS Universal Link URL                   |
+| android_app_link        | TEXT         | Android App Link URL                     |
+| deep_link_path          | TEXT         | In-app destination path                  |
+| deep_link_parameters    | JSONB        | Custom app parameters                    |
+| utm_parameters          | JSONB        | UTM tracking parameters                  |
+| targeting_rules         | JSONB        | Country/device/language targeting         |
+| og_title                | VARCHAR(255) | Open Graph title                         |
+| og_description          | TEXT         | Open Graph description                   |
+| og_image_url            | TEXT         | Open Graph image URL                     |
+| og_type                 | VARCHAR(50)  | Open Graph type (default: "website")     |
+| attribution_window_hours| INTEGER      | Install attribution window (default: 168)|
+| is_active               | BOOLEAN      | Active status                            |
+| expires_at              | TIMESTAMP    | Expiration date                          |
+| created_at              | TIMESTAMP    | Creation timestamp                       |
+| updated_at              | TIMESTAMP    | Last update timestamp                    |
 
 ### Click Events Table
 
@@ -294,7 +377,7 @@ CORS_ORIGIN=*
 | clicked_at   | TIMESTAMP    | Click timestamp              |
 | ip_address   | INET         | User IP address              |
 | user_agent   | TEXT         | User agent string            |
-| device_type  | VARCHAR(20)  | Device type (mobile/desktop) |
+| device_type  | VARCHAR(20)  | Device type (ios/android/web)|
 | platform     | VARCHAR(20)  | Platform (iOS/Android/Web)   |
 | country_code | CHAR(2)      | Country code                 |
 | country_name | VARCHAR(100) | Country name                 |
@@ -308,6 +391,68 @@ CORS_ORIGIN=*
 | utm_campaign | VARCHAR(255) | UTM campaign                 |
 | referrer     | TEXT         | Referrer URL                 |
 
+### Device Fingerprints Table
+
+| Column           | Type        | Description                         |
+|------------------|-------------|-------------------------------------|
+| id               | UUID        | Primary key                         |
+| click_id         | UUID        | Foreign key to click_events         |
+| fingerprint_hash | VARCHAR(64) | SHA-256 hash of fingerprint signals |
+| ip_address       | INET        | IP address                          |
+| user_agent       | TEXT        | User agent string                   |
+| timezone         | VARCHAR(100)| Timezone                            |
+| language         | VARCHAR(10) | Browser language                    |
+| screen_width     | INTEGER     | Screen width                        |
+| screen_height    | INTEGER     | Screen height                       |
+| platform         | VARCHAR(50) | Platform                            |
+| platform_version | VARCHAR(50) | Platform version                    |
+| created_at       | TIMESTAMP   | Creation timestamp                  |
+
+### Install Events Table
+
+| Column                  | Type        | Description                        |
+|-------------------------|-------------|------------------------------------|
+| id                      | UUID        | Primary key                        |
+| link_id                 | UUID        | Attributed link (nullable)         |
+| click_id                | UUID        | Attributed click (nullable)        |
+| fingerprint_hash        | VARCHAR(64) | Device fingerprint hash            |
+| confidence_score        | DECIMAL     | Match confidence (0-100)           |
+| installed_at            | TIMESTAMP   | Install timestamp                  |
+| first_open_at           | TIMESTAMP   | First app open                     |
+| deep_link_retrieved     | BOOLEAN     | Whether deferred link was fetched  |
+| deep_link_data          | JSONB       | Deferred deep link data            |
+| attribution_window_hours| INTEGER     | Attribution window used (default: 168) |
+| device_id               | VARCHAR(255)| Optional device identifier         |
+| created_at              | TIMESTAMP   | Creation timestamp                 |
+
+### In-App Events Table
+
+| Column          | Type         | Description                  |
+|-----------------|--------------|------------------------------|
+| id              | UUID         | Primary key                  |
+| install_id      | UUID         | Foreign key to install_events|
+| event_name      | VARCHAR(255) | Event name                   |
+| event_data      | JSONB        | Custom event properties      |
+| event_timestamp | TIMESTAMP    | When the event occurred      |
+| created_at      | TIMESTAMP    | Creation timestamp           |
+
+### Webhooks Table
+
+| Column     | Type         | Description                      |
+|------------|--------------|----------------------------------|
+| id         | UUID         | Primary key                      |
+| user_id    | UUID         | Optional owner/tenant identifier |
+| name       | VARCHAR(255) | Webhook name                     |
+| url        | TEXT         | Delivery URL                     |
+| secret     | VARCHAR(255) | HMAC signing secret              |
+| events     | TEXT[]       | Subscribed event types           |
+| is_active  | BOOLEAN      | Active status                    |
+| retry_count| INTEGER      | Max retries (default: 3)         |
+| timeout_ms | INTEGER      | Request timeout (default: 10000) |
+| headers    | JSONB        | Custom HTTP headers              |
+| created_at | TIMESTAMP    | Creation timestamp               |
+| updated_at | TIMESTAMP    | Last update timestamp            |
+
 ## Utilities
 
 ### Generate Short Code
@@ -389,7 +534,7 @@ await fastify.listen({ port: 3000 });
 
 LinkForty can be deployed in multiple ways depending on your needs:
 
-### 🚀 Production Deployment (Recommended)
+### Production Deployment (Recommended)
 
 Deploy to managed platforms with minimal DevOps overhead:
 
@@ -399,11 +544,11 @@ Deploy to managed platforms with minimal DevOps overhead:
 - Auto-scaling and SSL included
 - Starting at ~$10-15/month
 
-[View Fly.io deployment guide →](infra/fly.io/DEPLOYMENT.md)
+[View Fly.io deployment guide](infra/fly.io/DEPLOYMENT.md)
 
 See [`infra/`](infra/) directory for all deployment options and platform-specific guides.
 
-### 🐳 Docker Deployment (Recommended for Self-Hosting)
+### Docker Deployment (Recommended for Self-Hosting)
 
 **Production-ready Docker images available on Docker Hub:**
 
@@ -424,7 +569,7 @@ docker compose up -d
 ```yaml
 services:
   linkforty:
-    image: linkforty/core:v1.4.0  # Pin to specific version
+    image: linkforty/core:v1.5.0  # Pin to specific version
 ```
 
 See [DOCKER.md](DOCKER.md) for complete deployment guide including:
@@ -456,8 +601,8 @@ See [`infra/CONTRIBUTING.md`](infra/CONTRIBUTING.md) to add support for addition
 
 - **Redis caching**: 5-minute TTL on link lookups reduces database queries by 90%
 - **Database indexes**: Optimized queries for fast link lookups and analytics
-- **Async click tracking**: Non-blocking click event logging
-- **Connection pooling**: Efficient database connection management
+- **Async click tracking**: Non-blocking click event logging via `setImmediate()`
+- **Connection pooling**: Efficient database connection management (min 2, max 10)
 
 ## Security
 
@@ -465,6 +610,8 @@ See [`infra/CONTRIBUTING.md`](infra/CONTRIBUTING.md) to add support for addition
 - **Input validation**: Zod schema validation on all inputs
 - **CORS configuration**: Configurable CORS for API access control
 - **Link expiration**: Automatic handling of expired links
+- **Webhook signing**: HMAC SHA-256 signed payloads
+- **No auth included**: Core does not include authentication. The optional `userId` parameter provides data scoping but does not verify identity. Add your own auth middleware as needed.
 
 ## Mobile SDK Integration
 
@@ -556,12 +703,14 @@ LinkForty Core supports iOS Universal Links and Android App Links for seamless d
 
 ### Available Mobile SDKs
 
-- **React Native**: `npm install @linkforty/react-native-sdk`
-- **iOS**: Coming soon
-- **Android**: Coming soon
-- **Flutter**: Coming soon
+| Platform | Package | Install |
+|----------|---------|---------|
+| React Native | [`@linkforty/mobile-sdk-react-native`](https://github.com/LinkForty/mobile-sdk-react-native) | `npm install @linkforty/mobile-sdk-react-native` |
+| Expo | [`@linkforty/mobile-sdk-expo`](https://github.com/LinkForty/mobile-sdk-expo) | `npx expo install @linkforty/mobile-sdk-expo` |
+| iOS (Swift) | [LinkFortySDK](https://github.com/LinkForty/mobile-sdk-ios) | Swift Package Manager |
+| Android (Kotlin) | [LinkFortySDK](https://github.com/LinkForty/mobile-sdk-android) | Gradle dependency |
 
-See [SDK Integration Guide](https://docs.linkforty.com/guides/sdk-integration) for detailed documentation.
+See the [SDK documentation](https://docs.linkforty.com/sdks/react-native) for integration guides.
 
 ### Testing Domain Verification
 
@@ -577,18 +726,47 @@ adb shell am start -a android.intent.action.VIEW \
 ```
 
 
+## Migrate from Another Platform
+
+Switching from an existing deep linking provider? LinkForty supports zero-downtime migration via custom domain DNS cutover.
+
+- [Migrate from Branch.io](https://docs.linkforty.com/migrations/branch)
+- [Migrate from AppsFlyer OneLink](https://docs.linkforty.com/migrations/appsflyer)
+- [Migrate from Firebase Dynamic Links](https://docs.linkforty.com/comparisons/firebase-dynamic-links-migration) (shut down August 2025)
+- [Migrate from Adjust](https://docs.linkforty.com/migrations/adjust)
+- [Migrate from Kochava](https://docs.linkforty.com/migrations/kochava)
+- [Migration overview and checklist](https://docs.linkforty.com/migrations/overview)
+
+## For AI Tools (llms.txt)
+
+LinkForty provides machine-readable documentation for AI coding assistants (Claude, ChatGPT, Cursor, Copilot).
+
+- **Quick reference**: [docs.linkforty.com/llms.txt](https://docs.linkforty.com/llms.txt)
+- **Complete integration guide**: [docs.linkforty.com/llms-full.txt](https://docs.linkforty.com/llms-full.txt)
+
+Download into your project for AI-assisted integration:
+
+```bash
+curl -o LINKFORTY.md https://docs.linkforty.com/llms-full.txt
+```
+
+The npm package also ships with an `llms.txt` file — AI tools that read from `node_modules` can discover it automatically.
+
 ## Contributing
 
 Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) file for details.
+AGPL-3.0 - see [LICENSE](LICENSE) file for details.
 
 ## Related Projects
 
-- **@linkforty/ui** - React UI components for link management
-- **[LinkForty Cloud](https://linkforty.com)** - Hosted SaaS version with additional features 
+- **[@linkforty/mobile-sdk-react-native](https://github.com/LinkForty/mobile-sdk-react-native)** - React Native SDK
+- **[@linkforty/mobile-sdk-expo](https://github.com/LinkForty/mobile-sdk-expo)** - Expo SDK
+- **[mobile-sdk-ios](https://github.com/LinkForty/mobile-sdk-ios)** - iOS SDK (Swift)
+- **[mobile-sdk-android](https://github.com/LinkForty/mobile-sdk-android)** - Android SDK (Kotlin)
+- **[LinkForty Cloud](https://linkforty.com)** - Hosted SaaS version with authentication, teams, billing, and dashboard
 
 ## Support
 
@@ -600,8 +778,8 @@ MIT License - see [LICENSE](LICENSE) file for details.
 - [Fastify](https://www.fastify.io/) - Fast web framework
 - [PostgreSQL](https://www.postgresql.org/) - Powerful database
 - [Redis](https://redis.io/) - In-memory cache
+- [Zod](https://zod.dev/) - TypeScript-first schema validation
 - [nanoid](https://github.com/ai/nanoid) - Unique ID generation
 - [geoip-lite](https://github.com/geoip-lite/node-geoip) - IP geolocation
 - [ua-parser-js](https://github.com/faisalman/ua-parser-js) - User agent parsing
-
-
+- [qrcode](https://github.com/soldair/node-qrcode) - QR code generation

package/dist/index.d.ts

@@ -17,5 +17,5 @@ export * from './lib/fingerprint.js';
 export * from './lib/webhook.js';
 export * from './lib/event-emitter.js';
 export * from './types/index.js';
-export { redirectRoutes, linkRoutes, analyticsRoutes, sdkRoutes, webhookRoutes, qrRoutes, previewRoutes, debugRoutes, wellKnownRoutes } from './routes/index.js';
+export { redirectRoutes, linkRoutes, analyticsRoutes, sdkRoutes, webhookRoutes, templateRoutes, qrRoutes, previewRoutes, debugRoutes, wellKnownRoutes } from './routes/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAgB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAGnD,OAAO,EAAsB,eAAe,EAAE,MAAM,mBAAmB,CAAC;AASxE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,KAAK,CAAC,EAAE;QACN,GAAG,EAAE,MAAM,CAAC;KACb,CAAC;IACF,IAAI,CAAC,EAAE;QACL,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;KAC3B,CAAC;IACF,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,YAAY,CAAC,OAAO,GAAE,aAAkB,kTA8B7D;AAGD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,eAAe,EAAE,SAAS,EAAE,aAAa,EAAE,QAAQ,EAAE,aAAa,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAgB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAGnD,OAAO,EAAsB,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAUxE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,KAAK,CAAC,EAAE;QACN,GAAG,EAAE,MAAM,CAAC;KACb,CAAC;IACF,IAAI,CAAC,EAAE;QACL,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;KAC3B,CAAC;IACF,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,YAAY,CAAC,OAAO,GAAE,aAAkB,kTA+B7D;AAGD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,eAAe,EAAE,SAAS,EAAE,aAAa,EAAE,cAAc,EAAE,QAAQ,EAAE,aAAa,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -7,6 +7,7 @@ import { linkRoutes } from './routes/links.js';
 import { analyticsRoutes } from './routes/analytics.js';
 import { sdkRoutes } from './routes/sdk.js';
 import { webhookRoutes } from './routes/webhooks.js';
+import { templateRoutes } from './routes/templates.js';
 import { qrRoutes } from './routes/qr.js';
 import { wellKnownRoutes } from './routes/well-known.js';
 export async function createServer(options = {}) {
@@ -32,6 +33,7 @@ export async function createServer(options = {}) {
     await fastify.register(analyticsRoutes);
     await fastify.register(sdkRoutes);
     await fastify.register(webhookRoutes);
+    await fastify.register(templateRoutes);
     await fastify.register(qrRoutes);
     return fastify;
 }
@@ -42,5 +44,5 @@ export * from './lib/fingerprint.js';
 export * from './lib/webhook.js';
 export * from './lib/event-emitter.js';
 export * from './types/index.js';
-export { redirectRoutes, linkRoutes, analyticsRoutes, sdkRoutes, webhookRoutes, qrRoutes, previewRoutes, debugRoutes, wellKnownRoutes } from './routes/index.js';
+export { redirectRoutes, linkRoutes, analyticsRoutes, sdkRoutes, webhookRoutes, templateRoutes, qrRoutes, previewRoutes, debugRoutes, wellKnownRoutes } from './routes/index.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,OAA4B,MAAM,SAAS,CAAC;AACnD,OAAO,IAAI,MAAM,eAAe,CAAC;AACjC,OAAO,KAAK,MAAM,gBAAgB,CAAC;AACnC,OAAO,EAAE,kBAAkB,EAAmB,MAAM,mBAAmB,CAAC;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAazD,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,UAAyB,EAAE;IAC5D,MAAM,OAAO,GAAG,OAAO,CAAC;QACtB,MAAM,EAAE,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI;KAC7D,CAAC,CAAC;IAEH,OAAO;IACP,MAAM,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE;QAC3B,MAAM,EAAE,OAAO,CAAC,IAAI,EAAE,MAAM,IAAI,GAAG;KACpC,CAAC,CAAC;IAEH,mBAAmB;IACnB,IAAI,OAAO,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC;QACvB,MAAM,OAAO,CAAC,QAAQ,CAAC,KAAK,EAAE;YAC5B,GAAG,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG;SACvB,CAAC,CAAC;IACL,CAAC;IAED,WAAW;IACX,MAAM,kBAAkB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAE3C,SAAS;IACT,MAAM,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;IACxC,MAAM,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;IACvC,MAAM,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IACnC,MAAM,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;IACxC,MAAM,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IAClC,MAAM,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;IACtC,MAAM,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAEjC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,gCAAgC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,eAAe,EAAE,SAAS,EAAE,aAAa,EAAE,QAAQ,EAAE,aAAa,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,OAA4B,MAAM,SAAS,CAAC;AACnD,OAAO,IAAI,MAAM,eAAe,CAAC;AACjC,OAAO,KAAK,MAAM,gBAAgB,CAAC;AACnC,OAAO,EAAE,kBAAkB,EAAmB,MAAM,mBAAmB,CAAC;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAazD,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,UAAyB,EAAE;IAC5D,MAAM,OAAO,GAAG,OAAO,CAAC;QACtB,MAAM,EAAE,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI;KAC7D,CAAC,CAAC;IAEH,OAAO;IACP,MAAM,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE;QAC3B,MAAM,EAAE,OAAO,CAAC,IAAI,EAAE,MAAM,IAAI,GAAG;KACpC,CAAC,CAAC;IAEH,mBAAmB;IACnB,IAAI,OAAO,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC;QACvB,MAAM,OAAO,CAAC,QAAQ,CAAC,KAAK,EAAE;YAC5B,GAAG,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG;SACvB,CAAC,CAAC;IACL,CAAC;IAED,WAAW;IACX,MAAM,kBAAkB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAE3C,SAAS;IACT,MAAM,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;IACxC,MAAM,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;IACvC,MAAM,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IACnC,MAAM,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;IACxC,MAAM,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IAClC,MAAM,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;IACtC,MAAM,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;IACvC,MAAM,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAEjC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,gCAAgC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,eAAe,EAAE,SAAS,EAAE,aAAa,EAAE,cAAc,EAAE,QAAQ,EAAE,aAAa,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}