managarten/apps/uload/docs/cards/api-reference.md

Card System API Reference

CardTemplateService

Der zentrale Service für die Verwaltung von Cards, Templates und Themes.

Import

import { cardTemplateService } from '$lib/services/cardTemplates';

Methoden

Theme-Verwaltung

getPublicThemes()

Lädt alle öffentlichen Themes.

Returns: Promise<DBTheme[]>

Beispiel:

const themes = await cardTemplateService.getPublicThemes();

getTheme(id)

Lädt ein spezifisches Theme.

Parameters:

• id: string - Theme-ID

Returns: Promise<DBTheme | null>

Beispiel:

const theme = await cardTemplateService.getTheme('theme_123');

createTheme(theme)

Erstellt ein neues Theme.

Parameters:

• theme: Partial<DBTheme> - Theme-Daten

Returns: Promise<DBTheme | null>

Beispiel:

const newTheme = await cardTemplateService.createTheme({
	name: 'My Theme',
	colors: {
		primary: '#ff0000'
	}
});

updateTheme(id, updates)

Aktualisiert ein existierendes Theme.

Parameters:

• id: string - Theme-ID
• updates: Partial<DBTheme> - Zu aktualisierende Felder

Returns: Promise<DBTheme | null>

Beispiel:

await cardTemplateService.updateTheme('theme_123', {
	colors: { primary: '#00ff00' }
});

Template-Verwaltung

getPublicTemplates(category?)

Lädt öffentliche Templates, optional gefiltert nach Kategorie.

Parameters:

• category?: string - Optional: Kategorie-Filter

Returns: Promise<DBCardTemplate[]>

Beispiel:

// Alle Templates
const allTemplates = await cardTemplateService.getPublicTemplates();

// Nur Profile-Templates
const profileTemplates = await cardTemplateService.getPublicTemplates('profile');

getTemplate(id)

Lädt ein spezifisches Template.

Parameters:

• id: string - Template-ID

Returns: Promise<DBCardTemplate | null>

Beispiel:

const template = await cardTemplateService.getTemplate('template_123');

createTemplate(template)

Erstellt ein neues Template.

Parameters:

• template: Partial<DBCardTemplate> - Template-Daten

Returns: Promise<DBCardTemplate | null>

Beispiel:

const newTemplate = await cardTemplateService.createTemplate({
	name: 'My Template',
	slug: 'my-template',
	modules: [
		/* ... */
	]
});

updateTemplate(id, updates)

Aktualisiert ein Template.

Parameters:

• id: string - Template-ID
• updates: Partial<DBCardTemplate> - Updates

Returns: Promise<DBCardTemplate | null>

Beispiel:

await cardTemplateService.updateTemplate('template_123', {
	name: 'Updated Name'
});

User Cards

getUserCards(page)

Lädt die Karten eines Benutzers für eine bestimmte Seite.

Parameters:

• page: string - Seitenname (z.B. 'profile', 'dashboard')

Returns: Promise<DBUserCard[]>

Beispiel:

const profileCards = await cardTemplateService.getUserCards('profile');

saveUserCard(card)

Speichert oder aktualisiert eine Benutzerkarte.

Parameters:

• card: Partial<DBUserCard> - Kartendaten

Returns: Promise<DBUserCard | null>

Beispiel:

const savedCard = await cardTemplateService.saveUserCard({
	template_id: 'template_123',
	page: 'profile',
	position: 0,
	is_active: true
});

deleteUserCard(id)

Löscht eine Benutzerkarte.

Parameters:

• id: string - Karten-ID

Returns: Promise<boolean>

Beispiel:

const success = await cardTemplateService.deleteUserCard('card_123');

Konvertierungsmethoden

templateToCardConfig(template)

Konvertiert ein Datenbank-Template zu einer CardConfig.

Parameters:

• template: DBCardTemplate - Template aus Datenbank

Returns: CardConfig

Beispiel:

const config = cardTemplateService.templateToCardConfig(dbTemplate);

dbThemeToThemeConfig(dbTheme)

Konvertiert ein Datenbank-Theme zu einer ThemeConfig.

Parameters:

• dbTheme: DBTheme - Theme aus Datenbank

Returns: ThemeConfig

Beispiel:

const themeConfig = cardTemplateService.dbThemeToThemeConfig(dbTheme);

userCardToCardConfig(userCard)

Konvertiert eine Benutzerkarte zu einer CardConfig.

Parameters:

• userCard: DBUserCard - Benutzerkarte

Returns: CardConfig

Beispiel:

const config = cardTemplateService.userCardToCardConfig(userCard);

Spezielle Methoden

createStandardProfileCardTemplate(userData)

Erstellt eine Standard-Profilkarten-Konfiguration.

Parameters:

userData: {
  username?: string;
  email?: string;
  bio?: string;
  avatar?: string;
  websiteUrl?: string;
  socialLinks?: any[];
  totalLinks?: number;
  totalClicks?: number;
  memberSince?: string;
  showEmail?: boolean;
  showStats?: boolean;
}

Returns: CardConfig

Beispiel:

const profileConfig = cardTemplateService.createStandardProfileCardTemplate({
	username: 'johndoe',
	bio: 'Software Developer',
	totalLinks: 42
});

createOrUpdateStandardProfileCard(userData)

Erstellt oder aktualisiert die Standard-Profilkarte eines Benutzers.

Parameters:

• userData: any - Benutzerdaten

Returns: Promise<DBUserCard | null>

Beispiel:

const card = await cardTemplateService.createOrUpdateStandardProfileCard({
	username: 'johndoe',
	bio: 'Updated bio'
});

incrementDownloads(templateId)

Erhöht den Download-Zähler eines Templates.

Parameters:

• templateId: string - Template-ID

Returns: Promise<void>

Beispiel:

await cardTemplateService.incrementDownloads('template_123');

rateTemplate(templateId, rating)

Bewertet ein Template.

Parameters:

• templateId: string - Template-ID
• rating: number - Bewertung (1-5)

Returns: Promise<void>

Beispiel:

await cardTemplateService.rateTemplate('template_123', 5);

Datentypen

DBTheme

interface DBTheme {
	id: string;
	name: string;
	slug: string;
	description?: string;
	author?: string;
	version?: string;
	is_public?: boolean;
	is_premium?: boolean;
	price?: number;
	colors?: any;
	typography?: any;
	spacing?: any;
	borderRadius?: any;
	shadows?: any;
	animations?: any;
	created: string;
	updated: string;
}

DBCardTemplate

interface DBCardTemplate {
	id: string;
	name: string;
	slug: string;
	description?: string;
	category?: string;
	theme_id?: string;
	is_public?: boolean;
	modules?: any;
	layout?: any;
	responsive?: any;
	preview_image?: string;
	downloads?: number;
	rating?: number;
	author_id?: string;
	created: string;
	updated: string;
	expand?: {
		theme_id?: DBTheme;
		author_id?: any;
	};
}

DBUserCard

interface DBUserCard {
	id: string;
	user_id: string;
	template_id?: string;
	page?: string;
	position?: number;
	custom_config?: any;
	is_active?: boolean;
	created: string;
	updated: string;
	expand?: {
		template_id?: DBCardTemplate;
	};
}

CardConfig

interface CardConfig {
	id?: string;
	variant?: 'default' | 'compact' | 'hero' | 'minimal' | 'glass' | 'gradient';
	theme?: ThemeConfig;
	modules?: ModuleConfig[];
	layout?: LayoutConfig;
	animations?: AnimationConfig;
	responsive?: ResponsiveConfig;
	className?: string;
	style?: string;
}

ModuleConfig

interface ModuleConfig {
	type: 'header' | 'content' | 'footer' | 'media' | 'stats' | 'actions' | 'links' | 'custom';
	component?: string;
	props?: Record<string, any>;
	order?: number;
	visibility?: 'always' | 'desktop' | 'mobile' | 'conditional';
	grid?: {
		col?: number;
		row?: number;
		colSpan?: number;
		rowSpan?: number;
	};
	className?: string;
}

ThemeConfig

interface ThemeConfig {
	id?: string;
	name?: string;
	colors?: {
		primary?: string;
		secondary?: string;
		accent?: string;
		background?: string;
		surface?: string;
		text?: string;
		textMuted?: string;
		border?: string;
		hover?: string;
		[key: string]: string | undefined;
	};
	typography?: {
		fontFamily?: string;
		fontSize?: Record<string, string>;
		fontWeight?: Record<string, number>;
		lineHeight?: Record<string, string>;
	};
	spacing?: Record<string, string>;
	borderRadius?: Record<string, string>;
	shadows?: Record<string, string>;
}

Error Handling

Alle Service-Methoden geben null zurück oder werfen Fehler, die abgefangen werden sollten:

try {
	const template = await cardTemplateService.getTemplate('invalid_id');
	if (!template) {
		console.log('Template nicht gefunden');
	}
} catch (error) {
	console.error('Fehler beim Laden des Templates:', error);
}

Authentifizierung

Einige Methoden erfordern eine aktive Authentifizierung über PocketBase:

import { pb } from '$lib/pocketbase';

// Prüfen ob Benutzer eingeloggt ist
if (pb.authStore.model) {
	// Authentifizierte Aktionen
	const userCards = await cardTemplateService.getUserCards('profile');
} else {
	// Redirect zu Login
	goto('/login');
}

Performance-Tipps

1. Caching: Templates und Themes können gecached werden
2. Lazy Loading: Lade nur benötigte Daten
3. Batch Operations: Nutze Promise.all für parallele Anfragen
4. Pagination: Nutze Pagination für große Listen

// Parallel laden
const [themes, templates] = await Promise.all([
	cardTemplateService.getPublicThemes(),
	cardTemplateService.getPublicTemplates()
]);