Prompt (Claude / Cursor)

# Unlockfy — context for AI coding assistants (Claude, Cursor, GPT, etc.)

You are helping a developer integrate Unlockfy (https://unlockfy.cc).
Unlockfy monetizes links: visitors complete a short unlock gate (ads), then get a destination URL and/or unlock text (.txt). Creators earn a share of ad revenue.

## Base URL
https://unlockfy.cc

## Auth (do not confuse these)
| Credential | What it is | Where used |
|---|---|---|
| `unlockfy_session` cookie | Dashboard login (HTTP-only) | Browser dashboard / settings |
| API key `uf_…` | Secret server key | Links API: Authorization: Bearer uf_… OR X-Api-Key |
| User ID (public) | Public account id | Full Script embed only — NEVER a secret |

Rules:
- Never put `uf_…` API keys in frontend / client JS.
- Full Script uses **User ID only** (public).
- **Payouts are Dashboard-only** — not part of the public API. Do not call /api/payouts with an API key (returns 403 dashboard_only).
- Adsterra / AdSense publisher credentials are **platform-side** (Unlockfy ops). Creators do not need Adsterra API keys to use Links API or Full Script.

## Link sources (`source` field)
Every link has `source`:
| source | Created by | Expiration |
|---|---|---|
| `dashboard` | Dashboard UI (session cookie) | Optional temporary expiry |
| `api` | Links API with `uf_…` key | **Never expires** (expiry fields ignored) |
| `script` | Full Script redirect | **Never expires** |

Dashboard UI tabs: **My links** (dashboard) · **API links** (api + script) · **Expired** (dashboard temps past `expiresAt`; can reactivate). Expired dashboard links are hard-deleted after **14 days**.

## Full Script (embed)

- Intercepts outbound clicks → unlock gate.
- Whitelist / blacklist configured in Dashboard → API.
- Internal redirect: GET /api/script/redirect?uid=USER_ID&url=ENCODED_URL → 302 to /u/{slug}
- Creates/reuses links with `source: "script"` (no expiry).

## Links API
Auth: session cookie OR Bearer uf_…

### List
GET /api/links
Returns all of the user’s links (includes `source`, `expiresAt`, stats).

### Create
POST /api/links
Body (JSON): at least one of destinationUrl | contentText

Optional (dashboard/session only): `expiresIn` + `expiresUnit` (minutes | hours | days | months), or `expiresAt` ISO.
With an **API key**, expiry is always `null` even if sent.
Response includes `unlockUrl` like https://unlockfy.cc/u/{slug} and `source`.

### Update
PATCH /api/links/{id}
Fields: destinationUrl, title, contentText, active.
Expiry fields apply only to `source: "dashboard"` links. API/script links stay non-expiring.

### Delete
DELETE /api/links/{id}
POST /api/links/bulk-delete  { "ids": ["…"] }

## Unlock gate (visitors)
Public pages: /{locale}/u/{slug}
Server enforces 3 steps + offer ack + timed wait + signed tickets.
Visible steps use banner/native creatives; social bar + popunder load on the host page (Unlockfy platform Adsterra).
Destination / contentText are returned only after successful unlock — never bypass client-side.
Expired dashboard links → `410 expired` until reactivated in the Dashboard.

## Payouts
**Not a public API.** Creators request PayPal / LTC / BTC payouts from the Unlockfy Dashboard UI only.

## Docs for humans
- EN: https://unlockfy.cc/en/docs
- IT: https://unlockfy.cc/it/docs
- This AI page: https://unlockfy.cc/en/docs/ai/prompt
- Machine-readable: https://unlockfy.cc/llms.txt

## When writing code
1. Prefer server-side calls with uf_ API key for Links API.
2. Use User ID only for Full Script tags.
3. Always handle delivery_required, expired (410), rate limits (429).
4. Do not invent Adsterra client secrets for creators — ads are served by Unlockfy’s unlock gate.
5. Do not build payout integrations against /api/payouts for third-party apps.
6. Do not rely on `expiresIn` for API-key creates — those links never expire.