platform-codebase/features/linky/docs/integration-guide.md

Linky Integration Guide

How to use @platform/linky from other features.

---

Shared Types

Import types from @platform/linky:

import type {
  LinkyLink,
  CreateLinkRequest,
  UpdateLinkRequest,
  LinkListQuery,
  LinkListResponse,
  LinkAnalyticsSummary,
  AnalyticsQuery,
  LinkyDomain,
  ClickEvent,
} from '@platform/linky';

import {
  LinkStatus,
  RedirectType,
  ClickSource,
  LINKY_SERVICE_ID,
} from '@platform/linky';

---

LinkyClient Interface

The @platform/linky shared module exports a LinkyClient interface. Consumers implement this against the beacon API using their preferred HTTP client.

import type { LinkyClient } from '@platform/linky';

// Example implementation using fetch:
const beaconClient: LinkyClient = {
  async createLink(request) {
    const res = await fetch(`${BEACON_API_URL}/api/links`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
      body: JSON.stringify(request),
    });
    return res.json();
  },
  // ... other methods
};

---

Common Integration Patterns

Generate a trackable share URL (from share feature)

const link = await beaconClient.createLink({
  destinationUrl: fullUrlWithUtm,
  title: shareTitle,
  metadata: { sourceFeature: 'share', platform: 'twitter' },
  tags: ['share'],
});
// Use link.shortCode to build: beacon.atlilith.com/{shortCode}

Fetch user's bio links (from portal feature)

const { links } = await beaconClient.listLinksByUser(userId, {
  status: LinkStatus.ACTIVE,
  tag: 'bio',
  sortBy: 'createdAt',
});

Create a bio link (from portal feature)

const link = await beaconClient.createLink({
  destinationUrl: 'https://instagram.com/username',
  title: 'Instagram',
  tags: ['bio', 'social'],
});

Get link analytics (from any dashboard)

const analytics = await beaconClient.getLinkAnalytics(linkId, {
  startDate: '2026-01-01',
  endDate: '2026-01-31',
  groupBy: 'day',
});

---

Service Discovery

Use @lilith/service-registry to resolve the beacon API URL:

import { getServiceUrl } from '@lilith/service-registry';
import { LINKY_SERVICE_ID } from '@platform/linky';

const beaconApiUrl = getServiceUrl(LINKY_SERVICE_ID);
// → http://localhost:4170 (dev) or https://beacon.atlilith.com (prod)

---

Domain Events

Subscribe to beacon events via @lilith/domain-events:

import { DomainEventsSubscriber } from '@lilith/domain-events';

@DomainEventsSubscriber('beacon:link_clicked')
async handleLinkClicked(payload: LinkyLinkClickedPayload) {
  // React to click events from beacon
}

Available events:

• beacon:link_created — new link created
• beacon:link_clicked — redirect occurred
• beacon:link_updated — link details changed
• beacon:link_deleted — link deactivated
• beacon:domain_verified — custom domain verified