135 lines
2.9 KiB
Markdown
135 lines
2.9 KiB
Markdown
# 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
|