SurfSense/SOCIAL_MEDIA_LINKS_ADMIN.md

Social Media Links Management

This document explains how to manage dynamic social media links for the SurfSense homepage footer.

Overview

Social media links are now managed dynamically through the backend API. No hardcoded links exist in the frontend code. Administrators can add, edit, or remove links, and they will automatically appear or disappear from the homepage footer.

API Endpoints

All admin endpoints require authentication and superuser privileges.

Base URL

{BACKEND_URL}/api/v1/social-media-links

1. Get All Links (Admin)

GET /api/v1/social-media-links
Authorization: Bearer {your_jwt_token}

Response:

[
  {
    "id": 1,
    "platform": "MASTODON",
    "url": "https://mastodon.social/@username",
    "label": "Follow us on Mastodon",
    "display_order": 0,
    "is_active": true,
    "created_at": "2025-11-17T00:00:00Z"
  }
]

2. Get Public Links (No Auth Required)

GET /api/v1/social-media-links/public

This endpoint returns only active links, ordered by display_order. Used by the homepage footer.

3. Create a Link (Admin)

POST /api/v1/social-media-links
Authorization: Bearer {your_jwt_token}
Content-Type: application/json

{
  "platform": "MASTODON",
  "url": "https://mastodon.social/@username",
  "label": "Mastodon",
  "display_order": 0,
  "is_active": true
}

Supported Platforms:

• MASTODON
• PIXELFED
• BOOKWYRM
• LEMMY
• PEERTUBE
• GITHUB
• GITLAB
• MATRIX
• LINKEDIN
• WEBSITE
• EMAIL
• OTHER

4. Update a Link (Admin)

PATCH /api/v1/social-media-links/{link_id}
Authorization: Bearer {your_jwt_token}
Content-Type: application/json

{
  "url": "https://new-url.example.com",
  "is_active": false
}

You can update any field(s). Omit fields you don't want to change.

5. Delete a Link (Admin)

DELETE /api/v1/social-media-links/{link_id}
Authorization: Bearer {your_jwt_token}

Example: Using cURL

Add a Mastodon Link

# First, login to get JWT token
TOKEN=$(curl -X POST "http://localhost:8000/auth/jwt/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin@example.com&password=yourpassword" \
  | jq -r '.access_token')

# Create the link
curl -X POST "http://localhost:8000/api/v1/social-media-links" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "MASTODON",
    "url": "https://mastodon.social/@surfsense",
    "label": "Mastodon",
    "display_order": 1,
    "is_active": true
  }'

Add Multiple Links

# Pixelfed
curl -X POST "http://localhost:8000/api/v1/social-media-links" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "PIXELFED",
    "url": "https://pixelfed.social/username",
    "label": "Pixelfed",
    "display_order": 2,
    "is_active": true
  }'

# Bookwyrm
curl -X POST "http://localhost:8000/api/v1/social-media-links" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "BOOKWYRM",
    "url": "https://bookwyrm.social/user/username",
    "label": "Bookwyrm",
    "display_order": 3,
    "is_active": true
  }'

Update a Link

# Hide a link without deleting it
curl -X PATCH "http://localhost:8000/api/v1/social-media-links/1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

List All Links

curl "http://localhost:8000/api/v1/social-media-links" \
  -H "Authorization: Bearer $TOKEN"

Delete a Link

curl -X DELETE "http://localhost:8000/api/v1/social-media-links/1" \
  -H "Authorization: Bearer $TOKEN"

Icon Mapping

The frontend automatically maps platform names to appropriate icons:

Platform	Icon
MASTODON	Mastodon logo
PIXELFED	Photo icon
BOOKWYRM	Book icon
GITHUB	GitHub logo
GITLAB	GitLab logo
LINKEDIN	LinkedIn logo
WEBSITE	World/globe icon
EMAIL	Mail icon
MATRIX	Matrix logo
PEERTUBE	TV/video icon
LEMMY	World icon
OTHER	World icon

How It Works

1. Backend: Social media links are stored in the social_media_links database table
2. Public API: The /api/v1/social-media-links/public endpoint returns only active links
3. Frontend: The footer component (components/homepage/footer.tsx) fetches links on page load
4. Display: Only links with is_active=true are shown, ordered by display_order
5. Icons: Platform-specific icons are automatically selected based on the platform field

Database Migration

To apply the database schema:

cd surfsense_backend
alembic upgrade head

This will create the social_media_links table and the socialmediaplatform enum type.

Security Notes

• Admin endpoints require superuser privileges - regular users cannot manage links
• Public endpoint is unauthenticated - anyone can view active links (as intended for homepage display)
• No hardcoded URLs - all social media links come from the database
• Validation - URLs are validated (max 500 chars), labels max 100 chars

Future Enhancements

Future improvements could include:

1. Web UI: A graphical admin panel in the dashboard for managing links
2. Drag-and-drop reordering: UI to easily reorder links by changing display_order
3. Link analytics: Track clicks on social media links
4. Per-user links: Allow different users to have different social links (currently global)
5. Link preview: Show how the footer will look before saving changes

Troubleshooting

Links not appearing on homepage:

1. Check that is_active=true for the link
2. Verify the backend API is reachable from frontend
3. Check browser console for fetch errors
4. Confirm NEXT_PUBLIC_FASTAPI_BACKEND_URL environment variable is set correctly

Cannot create links:

1. Ensure you're logged in as a superuser
2. Check JWT token is valid and not expired
3. Verify request payload matches the schema

Icons not displaying:

1. Check that the platform name exactly matches one of the supported platforms (case-sensitive)
2. Unsupported platforms will default to the world/globe icon