# Linky Integration Guide

How to use `@platform/linky` from other features.

---

## Shared Types

Import types from `@platform/linky`:

```typescript
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.

```typescript
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)

```typescript
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 platform-user feature)

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

### Create a bio link (from platform-user feature)

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

### Get link analytics (from any dashboard)

```typescript
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:

```typescript
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`:

```typescript
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