@linkforty/core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 LinkForty
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,459 @@
+# @linkforty/core
+
+**Open-source deeplink management engine with device detection and analytics**
+
+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.
+
+[![npm version](https://img.shields.io/npm/v/@linkforty/core.svg)](https://www.npmjs.com/package/@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 
+
+## Installation
+
+```bash
+npm install @linkforty/core
+```
+
+## Quick Start
+
+### 1. Basic Server
+
+```typescript
+import { createServer } from '@linkforty/core';
+
+async function start() {
+  const server = await createServer({
+    database: {
+      url: 'postgresql://localhost/linkforty',
+    },
+    redis: {
+      url: 'redis://localhost:6379',
+    },
+  });
+
+  await server.listen({ port: 3000, host: '0.0.0.0' });
+  console.log('Server running on http://localhost:3000');
+}
+
+start();
+```
+
+### 2. Self-Hosting with Docker
+
+```bash
+# Clone the examples
+git clone https://github.com/linkforty/core.git
+cd core/examples
+
+# Start services
+docker-compose up -d
+
+# Server will be available at http://localhost:3000
+```
+
+## API Reference
+
+### Create a Link
+
+```bash
+POST /api/links
+Content-Type: application/json
+
+{
+  "userId": "user-uuid",
+  "originalUrl": "https://example.com",
+  "title": "My Link",
+  "iosUrl": "myapp://product/123",
+  "androidUrl": "myapp://product/123",
+  "webFallbackUrl": "https://example.com/product/123",
+  "utmParameters": {
+    "source": "twitter",
+    "medium": "social",
+    "campaign": "summer-sale"
+  },
+  "customCode": "summer-sale",
+  "expiresAt": "2024-12-31T23:59:59Z"
+}
+```
+
+**Response:**
+
+```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
+
+```bash
+GET /api/links?userId=user-uuid
+```
+
+### Get a Specific Link
+
+```bash
+GET /api/links/:id?userId=user-uuid
+```
+
+### Update a Link
+
+```bash
+PUT /api/links/:id?userId=user-uuid
+Content-Type: application/json
+
+{
+  "title": "Updated Title",
+  "isActive": false
+}
+```
+
+### Delete a Link
+
+```bash
+DELETE /api/links/:id?userId=user-uuid
+```
+
+### Get Analytics Overview
+
+```bash
+GET /api/analytics/overview?userId=user-uuid&days=30
+```
+
+**Response:**
+
+```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?userId=user-uuid&days=30
+```
+
+### Redirect Short Link
+
+```bash
+GET /:shortCode
+```
+
+This endpoint automatically redirects users to the appropriate URL based on their device type.
+
+## Configuration
+
+### Server Options
+
+```typescript
+interface ServerOptions {
+  database?: {
+    url?: string;           // PostgreSQL connection string
+    pool?: {
+      min?: number;         // Minimum pool connections (default: 2)
+      max?: number;         // Maximum pool connections (default: 10)
+    };
+  };
+  redis?: {
+    url: string;            // Redis connection string (optional)
+  };
+  cors?: {
+    origin: string | string[];  // CORS allowed origins (default: '*')
+  };
+  logger?: boolean;         // Enable Fastify logger (default: true)
+}
+```
+
+### Environment Variables
+
+```bash
+DATABASE_URL=postgresql://localhost/linkforty
+REDIS_URL=redis://localhost:6379
+PORT=3000
+NODE_ENV=production
+CORS_ORIGIN=*
+```
+
+## 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 |
+
+### 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 |
+
+### Click Events Table
+
+| Column       | Type         | Description                  |
+|--------------|--------------|------------------------------|
+| id           | UUID         | Primary key                  |
+| link_id      | UUID         | Foreign key to links         |
+| 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) |
+| platform     | VARCHAR(20)  | Platform (iOS/Android/Web)   |
+| country_code | CHAR(2)      | Country code                 |
+| country_name | VARCHAR(100) | Country name                 |
+| region       | VARCHAR(100) | Region/state                 |
+| city         | VARCHAR(100) | City                         |
+| latitude     | DECIMAL      | Latitude                     |
+| longitude    | DECIMAL      | Longitude                    |
+| timezone     | VARCHAR(100) | Timezone                     |
+| utm_source   | VARCHAR(255) | UTM source                   |
+| utm_medium   | VARCHAR(255) | UTM medium                   |
+| utm_campaign | VARCHAR(255) | UTM campaign                 |
+| referrer     | TEXT         | Referrer URL                 |
+
+## Utilities
+
+### Generate Short Code
+
+```typescript
+import { generateShortCode } from '@linkforty/core';
+
+const code = generateShortCode(8); // Returns 8-character nanoid
+```
+
+### Detect Device
+
+```typescript
+import { detectDevice } from '@linkforty/core';
+
+const device = detectDevice(userAgent); // Returns 'ios' | 'android' | 'web'
+```
+
+### Get Location from IP
+
+```typescript
+import { getLocationFromIP } from '@linkforty/core';
+
+const location = getLocationFromIP('8.8.8.8');
+// Returns: { countryCode, countryName, region, city, latitude, longitude, timezone }
+```
+
+### Build Redirect URL with UTM Parameters
+
+```typescript
+import { buildRedirectUrl } from '@linkforty/core';
+
+const url = buildRedirectUrl('https://example.com', {
+  source: 'twitter',
+  medium: 'social',
+  campaign: 'summer-sale'
+});
+// Returns: https://example.com?utm_source=twitter&utm_medium=social&utm_campaign=summer-sale
+```
+
+## Advanced Usage
+
+### Custom Route Registration
+
+```typescript
+import { createServer } from '@linkforty/core';
+
+const server = await createServer({
+  database: { url: 'postgresql://localhost/linkforty' },
+});
+
+// Add custom routes
+server.get('/custom', async (request, reply) => {
+  return { message: 'Hello World' };
+});
+
+await server.listen({ port: 3000 });
+```
+
+### Using Individual Route Handlers
+
+```typescript
+import Fastify from 'fastify';
+import { initializeDatabase, redirectRoutes, linkRoutes } from '@linkforty/core';
+
+const fastify = Fastify();
+
+// Initialize database separately
+await initializeDatabase({ url: 'postgresql://localhost/linkforty' });
+
+// Register only specific routes
+await fastify.register(redirectRoutes);
+await fastify.register(linkRoutes);
+
+await fastify.listen({ port: 3000 });
+```
+
+## Deployment
+
+LinkForty can be deployed in multiple ways depending on your needs:
+
+### 🚀 Production Deployment (Recommended)
+
+Deploy to managed platforms with minimal DevOps overhead:
+
+**Fly.io (Recommended)**
+- Global edge deployment
+- Managed PostgreSQL and Redis
+- Auto-scaling and SSL included
+- Starting at ~$10-15/month
+
+[View Fly.io deployment guide →](infra/fly.io/DEPLOYMENT.md)
+
+See [`infra/`](infra/) directory for all deployment options and platform-specific guides.
+
+### Docker Deployment (Self-Hosted)
+
+For local development or self-managed infrastructure:
+
+```bash
+git clone https://github.com/linkforty/core.git
+cd core/examples
+docker-compose up -d
+```
+
+See [`examples/docker-compose.yml`](examples/docker-compose.yml) for complete Docker setup.
+
+### Manual Deployment
+
+For custom infrastructure needs:
+
+1. Install dependencies: `npm install @linkforty/core`
+2. Set up PostgreSQL database (13+)
+3. Set up Redis (optional but recommended)
+4. Run migrations: `npm run migrate`
+5. Start server: `node server.js`
+
+### Other Platforms
+
+Community-maintained templates available for:
+- AWS (ECS/Fargate)
+- Google Cloud Run
+- Railway, Render, and more
+
+See [`infra/CONTRIBUTING.md`](infra/CONTRIBUTING.md) to add support for additional platforms.
+
+## Performance
+
+- **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
+
+## Security
+
+- **SQL injection protection**: Parameterized queries throughout
+- **Input validation**: Zod schema validation on all inputs
+- **CORS configuration**: Configurable CORS for API access control
+- **Link expiration**: Automatic handling of expired links
+
+## Roadmap
+
+- [ ] Webhook support for click events
+- [ ] Bulk link operations via API
+- [ ] Link grouping and tags
+- [ ] A/B testing support
+- [ ] QR code generation
+- [ ] Custom domain support (in SaaS version)
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## License
+
+MIT License - 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 
+
+## Support
+
+- **Documentation**: [https://docs.linkforty.com](https://docs.linkforty.com)
+- **Issues**: [GitHub Issues](https://github.com/linkforty/core/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/linkforty/core/discussions)
+
+## Built with:
+- [Fastify](https://www.fastify.io/) - Fast web framework
+- [PostgreSQL](https://www.postgresql.org/) - Powerful database
+- [Redis](https://redis.io/) - In-memory cache
+- [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
+
+

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+import { FastifyInstance } from 'fastify';
+import { DatabaseOptions } from './lib/database.js';
+export interface ServerOptions {
+    database?: DatabaseOptions;
+    redis?: {
+        url: string;
+    };
+    cors?: {
+        origin: string | string[];
+    };
+    logger?: boolean;
+}
+export declare function createServer(options?: ServerOptions): Promise<FastifyInstance<import("http").Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>, import("http").IncomingMessage, import("http").ServerResponse<import("http").IncomingMessage>, import("fastify").FastifyBaseLogger, import("fastify").FastifyTypeProviderDefault>>;
+export * from './lib/utils.js';
+export * from './lib/database.js';
+export * from './types/index.js';
+export { redirectRoutes, linkRoutes, analyticsRoutes } from './routes/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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;AAKxE,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,kTA0B7D;AAGD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,59 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyticsRoutes = exports.linkRoutes = exports.redirectRoutes = void 0;
+exports.createServer = createServer;
+const fastify_1 = __importDefault(require("fastify"));
+const cors_1 = __importDefault(require("@fastify/cors"));
+const redis_1 = __importDefault(require("@fastify/redis"));
+const database_js_1 = require("./lib/database.js");
+const redirect_js_1 = require("./routes/redirect.js");
+const links_js_1 = require("./routes/links.js");
+const analytics_js_1 = require("./routes/analytics.js");
+async function createServer(options = {}) {
+    const fastify = (0, fastify_1.default)({
+        logger: options.logger !== undefined ? options.logger : true,
+    });
+    // CORS
+    await fastify.register(cors_1.default, {
+        origin: options.cors?.origin || '*',
+    });
+    // Redis (optional)
+    if (options.redis?.url) {
+        await fastify.register(redis_1.default, {
+            url: options.redis.url,
+        });
+    }
+    // Database
+    await (0, database_js_1.initializeDatabase)(options.database);
+    // Routes
+    await fastify.register(redirect_js_1.redirectRoutes);
+    await fastify.register(links_js_1.linkRoutes);
+    await fastify.register(analytics_js_1.analyticsRoutes);
+    return fastify;
+}
+// Re-export utilities and types
+__exportStar(require("./lib/utils.js"), exports);
+__exportStar(require("./lib/database.js"), exports);
+__exportStar(require("./types/index.js"), exports);
+var index_js_1 = require("./routes/index.js");
+Object.defineProperty(exports, "redirectRoutes", { enumerable: true, get: function () { return index_js_1.redirectRoutes; } });
+Object.defineProperty(exports, "linkRoutes", { enumerable: true, get: function () { return index_js_1.linkRoutes; } });
+Object.defineProperty(exports, "analyticsRoutes", { enumerable: true, get: function () { return index_js_1.analyticsRoutes; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;AAmBA,oCA0BC;AA7CD,sDAAmD;AACnD,yDAAiC;AACjC,2DAAmC;AACnC,mDAAwE;AACxE,sDAAsD;AACtD,gDAA+C;AAC/C,wDAAwD;AAajD,KAAK,UAAU,YAAY,CAAC,UAAyB,EAAE;IAC5D,MAAM,OAAO,GAAG,IAAA,iBAAO,EAAC;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,cAAI,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,eAAK,EAAE;YAC5B,GAAG,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG;SACvB,CAAC,CAAC;IACL,CAAC;IAED,WAAW;IACX,MAAM,IAAA,gCAAkB,EAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAE3C,SAAS;IACT,MAAM,OAAO,CAAC,QAAQ,CAAC,4BAAc,CAAC,CAAC;IACvC,MAAM,OAAO,CAAC,QAAQ,CAAC,qBAAU,CAAC,CAAC;IACnC,MAAM,OAAO,CAAC,QAAQ,CAAC,8BAAe,CAAC,CAAC;IAExC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,gCAAgC;AAChC,iDAA+B;AAC/B,oDAAkC;AAClC,mDAAiC;AACjC,8CAAgF;AAAvE,0GAAA,cAAc,OAAA;AAAE,sGAAA,UAAU,OAAA;AAAE,2GAAA,eAAe,OAAA"}

package/dist/lib/database.d.ts

@@ -0,0 +1,11 @@
+import pg from 'pg';
+export interface DatabaseOptions {
+    url?: string;
+    pool?: {
+        min?: number;
+        max?: number;
+    };
+}
+export declare let db: pg.Pool;
+export declare function initializeDatabase(options?: DatabaseOptions): Promise<void>;
+//# sourceMappingURL=database.d.ts.map

package/dist/lib/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/lib/database.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,CAAC;AAIpB,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE;QACL,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,CAAC;CACH;AAED,eAAO,IAAI,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC;AA6BvB,wBAAsB,kBAAkB,CAAC,OAAO,GAAE,eAAoB,iBAoFrE"}