@forjacms/client 1.2.6

package/dist/client-d-QwwKUW.d.mts

@@ -0,0 +1,1673 @@
+//#region src/types.d.ts
+interface ForjaClientConfig {
+  baseUrl: string;
+  apiKey: string;
+  siteId: string;
+  fetch?: typeof globalThis.fetch;
+}
+interface PaginationMeta {
+  page: number;
+  page_size: number;
+  total_pages: number;
+  total_items: number;
+}
+interface Paginated<T> {
+  data: T[];
+  meta: PaginationMeta;
+}
+interface PaginationParams {
+  page?: number;
+  pageSize?: number;
+}
+interface LocaleFilterParams extends PaginationParams {
+  /** Filter to content with a localization in this locale (UUID). */
+  localeId?: string;
+}
+interface SearchablePaginationParams extends PaginationParams {
+  search?: string;
+  sortBy?: string;
+  sortDir?: 'asc' | 'desc';
+}
+type ContentStatus = 'Draft' | 'InReview' | 'Scheduled' | 'Published' | 'Archived';
+type TranslationStatus = 'Pending' | 'InProgress' | 'Review' | 'Approved' | 'Outdated';
+type PageType = 'Static' | 'Landing' | 'Contact' | 'BlogIndex' | 'Custom';
+type SectionType = 'Hero' | 'Features' | 'Cta' | 'Gallery' | 'Testimonials' | 'Pricing' | 'Faq' | 'Contact' | 'Custom' | 'Stats' | 'Team' | 'Timeline' | 'LogoCloud' | 'Newsletter' | 'Video' | 'Divider' | 'Text' | 'Portfolio' | 'TagCloud' | 'Projects' | 'Blog' | 'Legal';
+type CvEntryType = 'Work' | 'Education' | 'Volunteer' | 'Certification' | 'Project';
+type SkillCategory = 'Programming' | 'Framework' | 'Database' | 'Devops' | 'Language' | 'SoftSkill' | 'Tool' | 'Other';
+type LegalDocType = 'CookieConsent' | 'PrivacyPolicy' | 'TermsOfService' | 'Imprint' | 'Disclaimer';
+interface LocalizationResponse {
+  id: string;
+  content_id: string;
+  locale_id: string;
+  title: string;
+  subtitle: string | null;
+  excerpt: string | null;
+  body: string | null;
+  meta_title: string | null;
+  meta_description: string | null;
+  translation_status: TranslationStatus;
+  created_at: string;
+  updated_at: string;
+}
+interface BlogListItem {
+  id: string;
+  content_id: string;
+  slug: string | null;
+  author: string;
+  published_date: string;
+  reading_time_minutes: number | null;
+  cover_image_id: string | null;
+  header_image_id: string | null;
+  is_featured: boolean;
+  is_sample: boolean;
+  status: ContentStatus;
+  publish_start: string | null;
+  publish_end: string | null;
+  created_at: string;
+  updated_at: string;
+}
+interface BlogResponse {
+  id: string;
+  content_id: string;
+  slug: string | null;
+  author: string;
+  published_date: string;
+  reading_time_minutes: number | null;
+  cover_image_id: string | null;
+  header_image_id: string | null;
+  is_featured: boolean;
+  is_sample: boolean;
+  allow_comments: boolean;
+  status: ContentStatus;
+  published_at: string | null;
+  publish_start: string | null;
+  publish_end: string | null;
+  created_at: string;
+  updated_at: string;
+}
+interface BlogDocumentResponse {
+  id: string;
+  blog_id: string;
+  document_id: string;
+  display_order: number;
+  url: string | null;
+  document_type: string;
+  file_name: string | null;
+  has_file: boolean;
+  localizations: DocumentLocalizationResponse[];
+  created_at: string;
+}
+interface DocumentLocalizationResponse {
+  id: string;
+  document_id: string;
+  locale_id: string;
+  name: string;
+  description: string | null;
+  created_at: string;
+  updated_at: string;
+}
+interface BlogDetailResponse extends BlogResponse {
+  localizations: LocalizationResponse[];
+  categories: CategoryResponse[];
+  documents: BlogDocumentResponse[];
+  og_image_url: string | null;
+}
+interface PageListItem {
+  id: string;
+  route: string;
+  page_type: PageType;
+  slug: string | null;
+  is_in_navigation: boolean;
+  status: ContentStatus;
+  publish_start: string | null;
+  publish_end: string | null;
+  created_at: string;
+}
+interface PageResponse {
+  id: string;
+  content_id: string;
+  route: string;
+  page_type: PageType;
+  template: string | null;
+  is_in_navigation: boolean;
+  navigation_order: number | null;
+  parent_page_id: string | null;
+  slug: string | null;
+  status: ContentStatus;
+  published_at: string | null;
+  publish_start: string | null;
+  publish_end: string | null;
+  created_at: string;
+  updated_at: string;
+}
+interface PageDetailResponse extends PageResponse {
+  localizations: LocalizationResponse[];
+  og_image_url: string | null;
+}
+interface PageSectionResponse {
+  id: string;
+  page_id: string;
+  section_type: SectionType;
+  display_order: number;
+  cover_image_id: string | null;
+  call_to_action_route: string | null;
+  settings: Record<string, unknown> | null;
+}
+interface SectionLocalizationResponse {
+  id: string;
+  page_section_id: string;
+  locale_id: string;
+  title: string | null;
+  text: string | null;
+  button_text: string | null;
+}
+interface NavigationMenuResponse {
+  id: string;
+  site_id: string;
+  slug: string;
+  description: string | null;
+  max_depth: number;
+  is_active: boolean;
+  item_count: number;
+  created_at: string;
+}
+interface NavigationItemResponse {
+  id: string;
+  menu_id: string;
+  parent_id: string | null;
+  page_id: string | null;
+  external_url: string | null;
+  icon: string | null;
+  display_order: number;
+  open_in_new_tab: boolean;
+  title: string | null;
+}
+interface NavigationTree {
+  id: string;
+  parent_id: string | null;
+  page_id: string | null;
+  external_url: string | null;
+  icon: string | null;
+  display_order: number;
+  open_in_new_tab: boolean;
+  title: string | null;
+  page_slug: string | null;
+  children: NavigationTree[];
+}
+interface NavigationItemLocalizationResponse {
+  id: string;
+  navigation_item_id: string;
+  locale_id: string;
+  title: string;
+}
+interface TagResponse {
+  id: string;
+  slug: string;
+  is_global: boolean;
+  created_at: string;
+}
+interface CategoryResponse {
+  id: string;
+  parent_id: string | null;
+  slug: string;
+  is_global: boolean;
+  created_at: string;
+}
+interface CategoryTree {
+  id: string;
+  slug: string;
+  is_global: boolean;
+  children: CategoryTree[];
+}
+interface CategoryWithCountResponse {
+  id: string;
+  parent_id: string | null;
+  slug: string;
+  is_global: boolean;
+  created_at: string;
+  blog_count: number;
+}
+interface TopContentItem {
+  path: string;
+  total_views: number;
+  unique_visitors: number;
+}
+interface TrendDataPoint {
+  date: string;
+  total_views: number;
+  unique_visitors: number;
+}
+interface AnalyticsReportResponse {
+  total_views: number;
+  total_unique_visitors: number;
+  top_content: TopContentItem[];
+  trend: TrendDataPoint[];
+}
+interface ReferrerItem {
+  domain: string;
+  views: number;
+}
+interface AnalyticsPageDetailResponse {
+  path: string;
+  total_views: number;
+  total_unique_visitors: number;
+  trend: TrendDataPoint[];
+  referrers: ReferrerItem[];
+}
+interface TrackPageviewRequest {
+  path: string;
+  referrer?: string;
+}
+interface TrackPageviewResponse {
+  ok: boolean;
+}
+interface AnalyticsReportParams {
+  days?: number;
+  topN?: number;
+  startDate?: string;
+  endDate?: string;
+}
+interface AnalyticsPageParams {
+  path: string;
+  days?: number;
+  startDate?: string;
+  endDate?: string;
+}
+interface SkillResponse {
+  id: string;
+  name: string;
+  slug: string;
+  category: SkillCategory | null;
+  icon: string | null;
+  proficiency_level: number | null;
+}
+interface CvEntryResponse {
+  id: string;
+  company: string;
+  company_url: string | null;
+  company_logo_id: string | null;
+  location: string;
+  start_date: string;
+  end_date: string | null;
+  is_current: boolean;
+  entry_type: CvEntryType;
+  display_order: number;
+  created_at: string;
+  updated_at: string;
+}
+interface CvEntryParams extends SearchablePaginationParams {
+  entryType?: CvEntryType;
+}
+interface LegalDocumentResponse {
+  id: string;
+  cookie_name: string;
+  document_type: LegalDocType;
+  created_at: string;
+  updated_at: string;
+}
+interface LegalDocLocalizationResponse {
+  id: string;
+  locale_id: string;
+  title: string;
+  intro: string | null;
+}
+interface LegalDocumentDetailResponse {
+  id: string;
+  cookie_name: string;
+  document_type: LegalDocType;
+  localizations: LegalDocLocalizationResponse[];
+  created_at: string;
+  updated_at: string;
+}
+interface LegalGroupResponse {
+  id: string;
+  cookie_name: string;
+  display_order: number;
+  is_required: boolean;
+  default_enabled: boolean;
+}
+interface LegalItemResponse {
+  id: string;
+  cookie_name: string;
+  display_order: number;
+  is_required: boolean;
+}
+interface LegalGroupWithItems {
+  id: string;
+  cookie_name: string;
+  display_order: number;
+  is_required: boolean;
+  default_enabled: boolean;
+  items: LegalItemResponse[];
+}
+interface LegalDocumentWithGroups {
+  id: string;
+  cookie_name: string;
+  document_type: LegalDocType;
+  groups: LegalGroupWithItems[];
+}
+interface SiteResponse {
+  id: string;
+  name: string;
+  slug: string;
+  description: string | null;
+  logo_url: string | null;
+  favicon_url: string | null;
+  base_url: string | null;
+  theme: Record<string, unknown> | null;
+  default_locale_id: string | null;
+  timezone: string;
+  is_active: boolean;
+  created_at: string;
+  updated_at: string;
+}
+interface MediaVariantResponse {
+  id: string;
+  variant_name: string;
+  width: number;
+  height: number;
+  file_size: number;
+  public_url: string | null;
+}
+interface MediaResponse {
+  id: string;
+  filename: string;
+  original_filename: string;
+  mime_type: string;
+  file_size: number;
+  storage_provider: string;
+  public_url: string | null;
+  width: number | null;
+  height: number | null;
+  duration: number | null;
+  is_global: boolean;
+  created_at: string;
+  updated_at: string;
+  variants: MediaVariantResponse[];
+}
+interface SocialLinkResponse {
+  id: string;
+  title: string;
+  url: string;
+  icon: string;
+  alt_text: string | null;
+  display_order: number;
+}
+/** Link type for project resources (repository, demo, docs, etc.). */
+type ProjectLinkType = 'repository' | 'demo' | 'documentation' | 'website' | 'other';
+/** Project summary for list views. */
+interface ProjectResponse {
+  id: string;
+  slug: string;
+  display_order: number;
+  is_featured: boolean;
+  start_date: string | null;
+  end_date: string | null;
+  is_ongoing: boolean;
+  status: ContentStatus;
+  published_at: string | null;
+  created_at: string;
+  updated_at: string;
+}
+/** Localized content for a project. */
+interface ProjectLocalizationResponse {
+  id: string;
+  locale_id: string;
+  title: string;
+  short_description: string | null;
+  description: string | null;
+}
+/** External link attached to a project. */
+interface ProjectLinkResponse {
+  id: string;
+  label: string;
+  url: string;
+  link_type: ProjectLinkType;
+  icon: string | null;
+  display_order: number;
+}
+/** Media attachment on a project (cover image, screenshots). */
+interface ProjectMediaResponse {
+  media_id: string;
+  display_order: number;
+  is_cover: boolean;
+}
+/** Full project detail including localizations, links, and media. */
+interface ProjectDetailResponse extends ProjectResponse {
+  localizations: ProjectLocalizationResponse[];
+  links: ProjectLinkResponse[];
+  media: ProjectMediaResponse[];
+  skill_ids: string[];
+  cv_entry_ids: string[];
+}
+/** Pagination and filter params for project listings. */
+interface ProjectListParams extends PaginationParams {
+  /** Sort field (e.g. `"display_order"`, `"start_date"`). */
+  sortBy?: string;
+  /** Sort direction. */
+  sortDir?: 'asc' | 'desc';
+  /** Filter to featured projects only. */
+  isFeatured?: boolean;
+}
+/** A URL redirect rule. */
+interface RedirectResponse {
+  id: string;
+  site_id: string;
+  source_path: string;
+  destination_path: string;
+  status_code: number;
+  is_active: boolean;
+  description: string | null;
+  created_at: string;
+  updated_at: string;
+}
+/** Result of a redirect path lookup. */
+interface RedirectLookupResponse {
+  destination_path: string;
+  status_code: number;
+}
+/** A locale configured for a site. */
+interface SiteLocaleResponse {
+  locale_id: string;
+  code: string;
+  name: string;
+  native_name: string | null;
+  direction: 'ltr' | 'rtl';
+  is_default: boolean;
+  is_active: boolean;
+}
+/** Media item summary for list views (lighter than full MediaResponse). */
+interface MediaListItem {
+  id: string;
+  filename: string;
+  original_filename: string;
+  mime_type: string;
+  file_size: number;
+  public_url: string | null;
+  width: number | null;
+  height: number | null;
+  is_global: boolean;
+  folder_id: string | null;
+  created_at: string;
+}
+/** Filter params for media listings. */
+interface MediaListParams extends SearchablePaginationParams {
+  /** Filter by MIME category (e.g. `"image"`, `"video"`, `"document"`). */
+  mimeCategory?: string;
+  /** Filter to a specific folder. */
+  folderId?: string;
+}
+/** Full legal document detail including content localizations. */
+interface LegalDocumentFullDetailResponse {
+  id: string;
+  content_id: string;
+  cookie_name: string;
+  document_type: LegalDocType;
+  status: ContentStatus;
+  slug: string | null;
+  version: number;
+  parent_version_id: string | null;
+  publish_start: string | null;
+  publish_end: string | null;
+  localizations: LocalizationResponse[];
+  doc_localizations: LegalDocLocalizationResponse[];
+  created_at: string;
+  updated_at: string;
+}
+/** A version entry in a legal document's version history. */
+interface LegalVersionResponse {
+  id: string;
+  version: number;
+  status: ContentStatus;
+  created_at: string;
+}
+//#endregion
+//#region src/http.d.ts
+/**
+ * Low-level HTTP client interface used by all resource classes.
+ *
+ * Handles authentication (X-API-Key header), JSON serialization, and
+ * error mapping. You don't interact with this directly — use
+ * {@link ForjaClient} instead.
+ */
+interface HttpClient {
+  /** Send a GET request. Query params with `undefined` values are omitted. */
+  get<T>(path: string, params?: Record<string, string | undefined>): Promise<T>;
+  /** Send a GET request and return the response as plain text (for XML, HTML, etc.). */
+  getText(path: string, params?: Record<string, string | undefined>): Promise<string>;
+  /** Send a POST request with a JSON body. */
+  post<T>(path: string, body?: unknown): Promise<T>;
+}
+/**
+ * A paginated API response enriched with navigation helpers.
+ *
+ * Extends the raw {@link Paginated} response with methods to fetch
+ * subsequent pages or collect all items.
+ *
+ * @typeParam T - The type of items in the paginated collection.
+ *
+ * @example
+ * ```ts
+ * const page1 = await forja.blogs.listPublished({ pageSize: 10 });
+ *
+ * // Navigate to next page
+ * const page2 = await page1.fetchNext();
+ *
+ * // Or collect everything
+ * const allBlogs = await page1.fetchAll();
+ *
+ * // Or iterate page by page
+ * for await (const page of page1) {
+ *   console.log(page.data);
+ * }
+ * ```
+ */
+interface PaginatedResult<T> extends Paginated<T> {
+  /** Fetch the next page. Returns `null` if this is the last page. */
+  fetchNext(): Promise<PaginatedResult<T> | null>;
+  /** Fetch all remaining pages and return every item as a flat array. */
+  fetchAll(): Promise<T[]>;
+  /** Async iterator that yields each page (including the current one). */
+  [Symbol.asyncIterator](): AsyncIterableIterator<Paginated<T>>;
+}
+//#endregion
+//#region src/resources/analytics.d.ts
+/**
+ * Privacy-first analytics operations.
+ *
+ * Track pageviews and retrieve analytics reports. Forja analytics is
+ * cookie-free, GDPR-compliant by design — no PII is stored, visitor
+ * hashes are rotated daily, and raw data is pruned after a configurable retention period.
+ *
+ * Pageview tracking requires an API key with `Read` permission.
+ * Reports require `Read` permission.
+ */
+declare class AnalyticsResource {
+  private readonly http;
+  private readonly siteId;
+  constructor(http: HttpClient, siteId: string);
+  /**
+   * Track a pageview.
+   *
+   * **Endpoint:** `POST /sites/{siteId}/analytics/pageview`
+   *
+   * The server computes the visitor hash from the client IP and user agent.
+   * No cookies or PII are stored.
+   *
+   * @param request - The pageview data.
+   * @param request.path - The page path (e.g. `"/blog/hello-world"`).
+   * @param request.referrer - Optional full referrer URL (only the domain is stored).
+   * @returns Acknowledgement (`{ ok: true }`).
+   *
+   * @example
+   * ```ts
+   * await forja.analytics.trackPageview({ path: '/blog/hello-world' });
+   * ```
+   */
+  trackPageview(request: TrackPageviewRequest): Promise<TrackPageviewResponse>;
+  /**
+   * Fetch an analytics summary report for the site.
+   *
+   * **Endpoint:** `GET /sites/{siteId}/analytics/report?days=&top_n=&start_date=&end_date=`
+   *
+   * Returns total views, unique visitors, top content pages, and daily trends.
+   *
+   * @param params - Report parameters.
+   * @param params.days - Number of days to look back (default: 30). Ignored if date range is set.
+   * @param params.topN - Number of top content pages to include (default: 10).
+   * @param params.startDate - Start date in `YYYY-MM-DD` format.
+   * @param params.endDate - End date in `YYYY-MM-DD` format.
+   * @returns The analytics report with totals, top content, and daily trend data.
+   *
+   * @example
+   * ```ts
+   * const report = await forja.analytics.getReport({ days: 7, topN: 5 });
+   * console.log(`${report.total_views} views, ${report.total_unique_visitors} unique`);
+   * ```
+   */
+  getReport(params?: AnalyticsReportParams): Promise<AnalyticsReportResponse>;
+  /**
+   * Fetch analytics for a specific page path.
+   *
+   * **Endpoint:** `GET /sites/{siteId}/analytics/report/page?path=&days=&start_date=&end_date=`
+   *
+   * Returns views, unique visitors, daily trend, and top referrer domains for a single page.
+   *
+   * @param params - Page analytics parameters.
+   * @param params.path - The page path to query (e.g. `"/blog/hello-world"`).
+   * @param params.days - Number of days to look back.
+   * @param params.startDate - Start date in `YYYY-MM-DD` format.
+   * @param params.endDate - End date in `YYYY-MM-DD` format.
+   * @returns Page-level analytics with trend and referrer data.
+   *
+   * @example
+   * ```ts
+   * const stats = await forja.analytics.getPageAnalytics({
+   *   path: '/blog/hello-world',
+   *   days: 30,
+   * });
+   * console.log(stats.referrers); // [{ domain: "google.com", views: 42 }, ...]
+   * ```
+   */
+  getPageAnalytics(params: AnalyticsPageParams): Promise<AnalyticsPageDetailResponse>;
+}
+//#endregion
+//#region src/resources/blogs.d.ts
+/**
+ * Blog post operations.
+ *
+ * Provides access to published blog content, featured posts, category filtering,
+ * similar post discovery, and individual blog retrieval by ID or slug.
+ *
+ * All read operations require an API key with `Read` permission.
+ */
+declare class BlogsResource {
+  private readonly http;
+  private readonly siteId;
+  constructor(http: HttpClient, siteId: string);
+  /**
+   * Fetch a paginated list of published blog posts.
+   *
+   * **Endpoint:** `GET /sites/{siteId}/blogs/published?page=&page_size=&locale_id=`
+   *
+   * @param params - Pagination and locale filter options.
+   * @param params.page - 1-indexed page number (default: 1).
+   * @param params.pageSize - Items per page (default: server-side, typically 10).
+   * @param params.localeId - Filter to blogs with content in this locale (UUID).
+   * @returns A paginated result with {@link PaginatedResult.fetchNext | fetchNext()},
+   *   {@link PaginatedResult.fetchAll | fetchAll()}, and async iteration support.
+   *
+   * @example
+   * ```ts
+   * // All locales
+   * const page1 = await forja.blogs.listPublished({ page: 1, pageSize: 10 });
+   *
+   * // Filtered to a specific locale
+   * const german = await forja.blogs.listPublished({ page: 1, localeId: 'de-locale-uuid' });
+   * ```
+   */
+  listPublished(params?: LocaleFilterParams): Promise<PaginatedResult<BlogListItem>>;
+  /**
+   * Fetch published blog posts filtered by category.
+   *
+   * **Endpoint:** `GET /sites/{siteId}/blogs/published/category/{categorySlug}?page=&page_size=&locale_id=`
+   *
+   * @param categorySlug - The category slug to filter by (e.g. `"tech"`, `"travel"`).
+   * @param params - Pagination and locale filter options.
+   * @returns A paginated result of blogs in the given category.
+   *
+   * @example
+   * ```ts
+   * const techBlogs = await forja.blogs.listByCategory('tech', { page: 1, localeId: 'uuid' });
+   * ```
+   */
+  listByCategory(categorySlug: string, params?: LocaleFilterParams): Promise<PaginatedResult<BlogListItem>>;
+  /**
+   * Fetch featured blog posts.
+   *
+   * **Endpoint:** `GET /sites/{siteId}/blogs/featured?limit=`
+   *
+   * @param opts.limit - Maximum number of featured posts to return (default: server-side).
+   * @returns Array of blog detail responses (includes localizations, categories, documents).
+   *
+   * @example
+   * ```ts
+   * const featured = await forja.blogs.listFeatured({ limit: 3 });
+   * ```
+   */
+  listFeatured(opts?: {
+    limit?: number;
+  }): Promise<BlogDetailResponse[]>;
+  /**
+   * Fetch blog posts similar to a given blog (by shared categories/tags).
+   *
+   * **Endpoint:** `GET /sites/{siteId}/blogs/{blogId}/similar?limit=`
+   *
+   * @param blogId - The UUID of the blog to find similar content for.
+   * @param opts.limit - Maximum number of similar posts (default: server-side, typically 3).
+   * @returns Array of similar blog list items.
+   *
+   * @example
+   * ```ts
+   * const similar = await forja.blogs.listSimilar('blog-uuid', { limit: 3 });
+   * ```
+   */
+  listSimilar(blogId: string, opts?: {
+    limit?: number;
+  }): Promise<BlogListItem[]>;
+  /**
+   * Fetch a blog post's full detail by its URL slug.
+   *
+   * Performs a two-step lookup:
+   * 1. **Endpoint:** `GET /sites/{siteId}/blogs/by-slug/{slug}` — resolves slug to ID.
+   * 2. **Endpoint:** `GET /blogs/{id}/detail` — fetches the full detail response.
+   *
+   * @param slug - The blog's URL slug (e.g. `"my-first-post"`).
+   * @returns The full blog detail (with localizations, categories, documents), or `null` if not found.
+   *
+   * @example
+   * ```ts
+   * const blog = await forja.blogs.getBySlug('my-first-post');
+   * if (blog) {
+   *   console.log(blog.localizations[0]?.title);
+   * }
+   * ```
+   */
+  getBySlug(slug: string): Promise<BlogDetailResponse | null>;
+  /**
+   * Fetch a blog post's full detail by its UUID.
+   *
+   * **Endpoint:** `GET /blogs/{id}/detail`
+   *
+   * @param idOrSlug - The blog's UUID.
+   * @returns The full blog detail (with localizations, categories, documents), or `null` if not found.
+   *
+   * @example
+   * ```ts
+   * const blog = await forja.blogs.get('550e8400-e29b-41d4-a716-446655440000');
+   * ```
+   */
+  get(idOrSlug: string): Promise<BlogDetailResponse | null>;
+  /**
+   * Fetch the site's RSS feed as raw XML.
+   *
+   * **Endpoint:** `GET /sites/{siteId}/feed.rss`
+   *
+   * @returns RSS 2.0 XML string.
+   */
+  rss(): Promise<string>;
+}
+//#endregion
+//#region src/resources/cv.d.ts
+/**
+ * CV / resume operations.
+ *
+ * Provides access to skills (technologies, languages, tools) and CV entries
+ * (work experience, education, certifications, projects).
+ *
+ * All operations require an API key with `Read` permission.
+ */
+declare class CvResource {
+  private readonly http;
+  private readonly siteId;
+  constructor(http: HttpClient, siteId: string);
+  /**
+   * Fetch a paginated list of skills.
+   *
+   * **Endpoint:** `GET /sites/{siteId}/skills?page=&page_size=&search=&sort_by=&sort_dir=`
+   *
+   * @param params - Pagination, search, and sort options.
+   * @returns A paginated result of skills (name, slug, category, proficiency level).
+   *
+   * @example
+   * ```ts
+   * const skills = await forja.cv.listSkills({ page: 1, pageSize: 50 });
+   * const programming = skills.data.filter(s => s.category === 'Programming');
+   * ```
+   */
+  listSkills(params?: SearchablePaginationParams): Promise<PaginatedResult<SkillResponse>>;
+  /**
+   * Fetch a skill by its UUID.
+   *
+   * **Endpoint:** `GET /skills/{id}`
+   *
+   * @param id - The skill's UUID.
+   * @returns The skill, or `null` if not found.
+   */
+  getSkill(id: string): Promise<SkillResponse | null>;
+  /**
+   * Fetch a skill by its URL slug.
+   *
+   * **Endpoint:** `GET /skills/by-slug/{slug}`
+   *
+   * @param slug - The skill's slug (e.g. `"typescript"`, `"rust"`).
+   * @returns The skill, or `null` if not found.
+   *
+   * @example
+   * ```ts
+   * const ts = await forja.cv.getSkillBySlug('typescript');
+   * if (ts) console.log(`${ts.name}: level ${ts.proficiency_level}`);
+   * ```
+   */
+  getSkillBySlug(slug: string): Promise<SkillResponse | null>;
+  /**
+   * Fetch a paginated list of CV entries (work, education, certifications, etc.).
+   *
+   * **Endpoint:** `GET /sites/{siteId}/cv?entry_type=&page=&page_size=&search=&sort_by=&sort_dir=`
+   *
+   * @param params - Pagination and filter options.
+   * @param params.entryType - Filter by entry type: `"Work"`, `"Education"`, `"Volunteer"`, `"Certification"`, or `"Project"`.
+   * @returns A paginated result of CV entries.
+   *
+   * @example
+   * ```ts
+   * const work = await forja.cv.listEntries({ entryType: 'Work' });
+   * const education = await forja.cv.listEntries({ entryType: 'Education' });
+   * ```
+   */
+  listEntries(params?: CvEntryParams): Promise<PaginatedResult<CvEntryResponse>>;
+}
+//#endregion
+//#region src/resources/legal.d.ts
+/**
+ * Legal document operations.
+ *
+ * Provides access to legal documents (privacy policy, terms of service, cookie consent, etc.),
+ * their consent groups, and individual consent items for building cookie banners and legal pages.
+ *
+ * All operations require an API key with `Read` permission.
+ */
+declare class LegalResource {
+  private readonly http;
+  private readonly siteId;
+  constructor(http: HttpClient, siteId: string);
+  /**
+   * Fetch a paginated list of legal documents for the site.
+   *
+   * **Endpoint:** `GET /sites/{siteId}/legal?page=&page_size=&search=&sort_by=&sort_dir=`
+   *
+   * @param params - Pagination, search, and sort options.
+   * @returns A paginated result of legal document summaries.
+   *
+   * @example
+   * ```ts
+   * const docs = await forja.legal.list();
+   * ```
+   */
+  list(params?: SearchablePaginationParams): Promise<PaginatedResult<LegalDocumentResponse>>;
+  /**
+   * Fetch a legal document by its UUID, including localizations.
+   *
+   * **Endpoint:** `GET /legal/{id}`
+   *
+   * @param id - The legal document's UUID.
+   * @returns The document with all localizations, or `null` if not found.
+   */
+  get(id: string): Promise<LegalDocumentDetailResponse | null>;
+  /**
+   * Fetch a legal document by its URL slug.
+   *
+   * **Endpoint:** `GET /sites/{siteId}/legal/by-slug/{slug}`
+   *
+   * @param slug - The document slug (e.g. `"privacy-policy"`, `"terms-of-service"`).
+   * @returns The document with all localizations, or `null` if not found.
+   *
+   * @example
+   * ```ts
+   * const privacy = await forja.legal.getBySlug('privacy-policy');
+   * if (privacy) {
+   *   const enLocale = privacy.localizations.find(l => l.locale_id === enLocaleId);
+   * }
+   * ```
+   */
+  getBySlug(slug: string): Promise<LegalDocumentDetailResponse | null>;
+  /**
+   * Fetch the cookie consent document with its consent groups and items.
+   *
+   * **Endpoint:** `GET /sites/{siteId}/legal/cookie-consent`
+   *
+   * Returns a structured document with groups (e.g. "Essential", "Analytics", "Marketing")
+   * and their items, including `is_required` and `default_enabled` flags for building
+   * GDPR-compliant cookie consent banners.
+   *
+   * @returns The cookie consent document with groups and items, or `null` if not configured.
+   *
+   * @example
+   * ```ts
+   * const consent = await forja.legal.getCookieConsent();
+   * if (consent) {
+   *   consent.groups.forEach(group => {
+   *     console.log(group.cookie_name, group.is_required ? '(required)' : '(optional)');
+   *   });
+   * }
+   * ```
+   */
+  getCookieConsent(): Promise<LegalDocumentWithGroups | null>;
+  /**
+   * Fetch consent groups (with their items) for a legal document.
+   *
+   * **Endpoint:** `GET /legal/{documentId}/groups`
+   *
+   * @param documentId - The legal document's UUID.
+   * @returns Array of consent groups, each containing their items.
+   */
+  getGroups(documentId: string): Promise<LegalGroupWithItems[]>;
+  /**
+   * Fetch consent items within a specific group.
+   *
+   * **Endpoint:** `GET /legal/groups/{groupId}/items`
+   *
+   * @param groupId - The consent group's UUID.
+   * @returns Array of consent items (cookie name, required flag, display order).
+   */
+  getGroupItems(groupId: string): Promise<LegalItemResponse[]>;
+  /**
+   * Fetch the full detail of a legal document, including content localizations.
+   *
+   * **Endpoint:** `GET /legal/{id}/detail`
+   *
+   * Unlike {@link get}, this returns the full content body localizations
+   * (rendered text), document status, slug, version, and publish window.
+   * Use for rendering the full legal document page.
+   *
+   * @param id - The legal document's UUID.
+   * @returns The full document detail with content and doc localizations, or `null` if not found.
+   *
+   * @example
+   * ```ts
+   * const detail = await forja.legal.getDetail('doc-uuid');
+   * if (detail) {
+   *   console.log(detail.version);            // 3
+   *   console.log(detail.document_type);      // "PrivacyPolicy"
+   *   console.log(detail.localizations);      // content body per locale
+   *   console.log(detail.doc_localizations);  // title + intro per locale
+   * }
+   * ```
+   */
+  getDetail(id: string): Promise<LegalDocumentFullDetailResponse | null>;
+  /**
+   * Fetch the version history of a legal document.
+   *
+   * **Endpoint:** `GET /legal/{id}/versions`
+   *
+   * Returns all versions of the document, ordered by version number.
+   * Each entry includes the version number, content status, and creation date.
+   * Use for displaying a "Version history" section on legal pages.
+   *
+   * @param id - The legal document's UUID.
+   * @returns Array of version entries, newest first.
+   *
+   * @example
+   * ```ts
+   * const versions = await forja.legal.listVersions('doc-uuid');
+   * versions.forEach(v => {
+   *   console.log(`v${v.version} — ${v.status} — ${v.created_at}`);
+   * });
+   * ```
+   */
+  listVersions(id: string): Promise<LegalVersionResponse[]>;
+}
+//#endregion
+//#region src/resources/media.d.ts
+/**
+ * Media asset operations.
+ *
+ * Provides access to media assets (images, videos, documents) stored in the CMS.
+ * Each media item includes its public URL, dimensions, file metadata, and
+ * responsive variants (thumbnails, different sizes).
+ *
+ * Requires an API key with `Read` permission.
+ */
+declare class MediaResource {
+  private readonly http;
+  private readonly siteId;
+  constructor(http: HttpClient, siteId: string);
+  /**
+   * Fetch a paginated list of media assets for the site.
+   *
+   * **Endpoint:** `GET /sites/{siteId}/media?page=&page_size=&search=&sort_by=&sort_dir=&mime_category=&folder_id=`
+   *
+   * Returns a lightweight list without variants. Use {@link get} to fetch full
+   * detail with responsive variants for a specific asset.
+   *
+   * @param params - Pagination, search, sort, and filter options.
+   * @param params.search - Search by filename.
+   * @param params.mimeCategory - Filter by MIME category: `"image"`, `"video"`, `"document"`, `"audio"`.
+   * @param params.folderId - Filter to a specific media folder (UUID).
+   * @returns A paginated result of media list items.
+   *
+   * @example
+   * ```ts
+   * // Browse all images
+   * const images = await forja.media.list({ mimeCategory: 'image', pageSize: 20 });
+   *
+   * // Search by filename
+   * const results = await forja.media.list({ search: 'hero-banner' });
+   *
+   * // Browse a specific folder
+   * const folder = await forja.media.list({ folderId: 'folder-uuid' });
+   * ```
+   */
+  list(params?: MediaListParams): Promise<PaginatedResult<MediaListItem>>;
+  /**
+   * Fetch a media asset by its UUID.
+   *
+   * **Endpoint:** `GET /media/{id}`
+   *
+   * Returns the full media metadata including filename, MIME type, dimensions,
+   * public URL, and all responsive variants (thumbnails, different sizes).
+   *
+   * @param id - The media asset's UUID.
+   * @returns The media asset with variants, or `null` if not found.
+   *
+   * @example
+   * ```ts
+   * const cover = await forja.media.get(blog.cover_image_id);
+   * if (cover) {
+   *   console.log(cover.public_url);    // original image URL
+   *   console.log(cover.variants);      // [{ variant_name, width, height, public_url }, ...]
+   *   console.log(cover.mime_type);     // "image/jpeg"
+   * }
+   * ```
+   */
+  get(id: string): Promise<MediaResponse | null>;
+}
+//#endregion
+//#region src/resources/navigation.d.ts
+/**
+ * Navigation menu operations.
+ *
+ * Provides access to navigation menus, their hierarchical tree structure,
+ * and individual menu items. Used to render site headers, footers, and sidebars.
+ *
+ * All operations require an API key with `Read` permission.
+ */
+declare class NavigationResource {
+  private readonly http;
+  private readonly siteId;
+  constructor(http: HttpClient, siteId: string);
+  /**
+   * Fetch all navigation menus for the site.
+   *
+   * **Endpoint:** `GET /sites/{siteId}/menus`
+   *
+   * @returns Array of menu metadata (slug, description, depth, item count).
+   *
+   * @example
+   * ```ts
+   * const menus = await forja.navigation.listMenus();
+   * const primary = menus.find(m => m.slug === 'primary');
+   * ```
+   */
+  listMenus(): Promise<NavigationMenuResponse[]>;
+  /**
+   * Fetch a navigation menu by its UUID.
+   *
+   * **Endpoint:** `GET /menus/{menuId}`
+   *
+   * @param menuId - The menu's UUID.
+   * @returns Menu metadata, or `null` if not found.
+   */
+  getMenu(menuId: string): Promise<NavigationMenuResponse | null>;
+  /**
+   * Fetch a navigation menu by its slug.
+   *
+   * **Endpoint:** `GET /sites/{siteId}/menus/slug/{slug}`
+   *
+   * @param slug - The menu's slug (e.g. `"primary"`, `"footer"`).
+   * @returns Menu metadata, or `null` if not found.
+   *
+   * @example
+   * ```ts
+   * const primary = await forja.navigation.getMenuBySlug('primary');
+   * if (primary) {
+   *   const tree = await forja.navigation.getTree(primary.id);
+   * }
+   * ```
+   */
+  getMenuBySlug(slug: string): Promise<NavigationMenuResponse | null>;
+  /**
+   * Fetch the hierarchical navigation tree for a menu.
+   *
+   * **Endpoint:** `GET /menus/{menuId}/tree?locale=`
+   *
+   * Returns a recursive tree of navigation items with children, page slugs,
+   * external URLs, and icons. Optionally filtered by locale for multi-language sites.
+   *
+   * @param menuId - The menu's UUID.
+   * @param opts.locale - Optional locale code (e.g. `"en"`, `"de"`) to filter localized titles.
+   * @returns Array of root-level navigation tree nodes (each may have nested children).
+   *
+   * @example
+   * ```ts
+   * const tree = await forja.navigation.getTree('menu-uuid', { locale: 'de' });
+   * tree.forEach(node => {
+   *   console.log(node.title, node.page_slug, node.children.length);
+   * });
+   * ```
+   */
+  getTree(menuId: string, opts?: {
+    locale?: string;
+  }): Promise<NavigationTree[]>;
+  /**
+   * Fetch all flat (non-hierarchical) items in a menu.
+   *
+   * **Endpoint:** `GET /menus/{menuId}/items`
+   *
+   * @param menuId - The menu's UUID.
+   * @returns Array of navigation items (use `parent_id` to reconstruct hierarchy if needed).
+   */
+  listItems(menuId: string): Promise<NavigationItemResponse[]>;
+  /**
+   * Fetch a single navigation item by its UUID.
+   *
+   * **Endpoint:** `GET /navigation/{itemId}`
+   *
+   * @param itemId - The navigation item's UUID.
+   * @returns The navigation item, or `null` if not found.
+   */
+  getItem(itemId: string): Promise<NavigationItemResponse | null>;
+}
+//#endregion
+//#region src/resources/pages.d.ts
+/**
+ * Extended pagination params for page listings.
+ * Supports filtering by status, page type, and exclusion.
+ */
+interface PageListParams extends SearchablePaginationParams {
+  /** Filter by content status (e.g. `"Published"`, `"Draft"`). */
+  status?: string;
+  /** Filter by page type (e.g. `"Static"`, `"Landing"`, `"Contact"`). */
+  pageType?: string;
+  /** Exclude pages with this status. */
+  excludeStatus?: string;
+}
+/**
+ * CMS page operations.
+ *
+ * Provides access to page listings, route-based lookup, page sections,
+ * and section localizations for multi-language content rendering.
+ *
+ * All operations require an API key with `Read` permission.
+ */
+declare class PagesResource {
+  private readonly http;
+  private readonly siteId;
+  constructor(http: HttpClient, siteId: string);
+  /**
+   * Fetch a paginated list of CMS pages.
+   *
+   * **Endpoint:** `GET /sites/{siteId}/pages?page=&page_size=&search=&status=&page_type=&sort_by=&sort_dir=&exclude_status=`
+   *
+   * @param params - Pagination, search, and filter options.
+   * @returns A paginated result of page list items.
+   *
+   * @example
+   * ```ts
+   * const pages = await forja.pages.list({ page: 1, pageSize: 100 });
+   * const allPages = await pages.fetchAll();
+   * ```
+   */
+  list(params?: PageListParams): Promise<PaginatedResult<PageListItem>>;
+  /**
+   * Fetch a page by its URL route path.
+   *
+   * **Endpoint:** `GET /sites/{siteId}/pages/by-route/{route}`
+   *
+   * Leading slashes are stripped automatically (`"/about"` and `"about"` both work).
+   *
+   * @param route - The page's route path (e.g. `"/about"` or `"contact"`).
+   * @returns The page detail with localizations and OG image, or `null` if not found.
+   *
+   * @example
+   * ```ts
+   * const aboutPage = await forja.pages.getByRoute('/about');
+   * if (aboutPage) {
+   *   console.log(aboutPage.localizations[0]?.title);
+   * }
+   * ```
+   */
+  getByRoute(route: string): Promise<PageDetailResponse | null>;
+  /**
+   * Fetch all sections for a page.
+   *
+   * **Endpoint:** `GET /pages/{pageId}/sections`
+   *
+   * Sections are returned in display order and include type, settings,
+   * cover image reference, and call-to-action route.
+   *
+   * @param pageId - The page's UUID.
+   * @returns Array of page sections.
+   */
+  getSections(pageId: string): Promise<PageSectionResponse[]>;
+  /**
+   * Fetch localizations for a single section.
+   *
+   * **Endpoint:** `GET /pages/sections/{sectionId}/localizations`
+   *
+   * @param sectionId - The section's UUID.
+   * @returns Array of localized content (title, text, button text) per locale.
+   */
+  getSectionLocalizations(sectionId: string): Promise<SectionLocalizationResponse[]>;
+  /**
+   * Fetch localizations for all sections of a page in a single request.
+   *
+   * **Endpoint:** `GET /pages/{pageId}/sections/localizations`
+   *
+   * More efficient than calling {@link getSectionLocalizations} per section.
+   *
+   * @param pageId - The page's UUID.
+   * @returns Array of all section localizations for the page.
+   */
+  getPageSectionLocalizations(pageId: string): Promise<SectionLocalizationResponse[]>;
+}
+//#endregion
+//#region src/resources/projects.d.ts
+/**
+ * Portfolio project operations.
+ *
+ * Provides access to published projects with localizations, links, media
+ * attachments, and skill/CV associations. Use for portfolio pages, project
+ * showcases, and case studies.
+ *
+ * All read operations require an API key with `Read` permission.
+ */
+declare class ProjectsResource {
+  private readonly http;
+  private readonly siteId;
+  constructor(http: HttpClient, siteId: string);
+  /**
+   * Fetch a paginated list of published projects.
+   *
+   * **Endpoint:** `GET /sites/{siteId}/projects/public?page=&page_size=&sort_by=&sort_dir=&is_featured=`
+   *
+   * Returns projects with `published` or `scheduled` status that are within
+   * their publish window. Results can be sorted and filtered to featured only.
+   *
+   * @param params - Pagination, sort, and filter options.
+   * @param params.page - 1-indexed page number (default: 1).
+   * @param params.pageSize - Items per page, 1–100 (default: 10).
+   * @param params.sortBy - Sort field (e.g. `"display_order"`, `"start_date"`, `"created_at"`).
+   * @param params.sortDir - Sort direction: `"asc"` or `"desc"`.
+   * @param params.isFeatured - When `true`, returns only featured projects.
+   * @returns A paginated result with {@link PaginatedResult.fetchNext | fetchNext()},
+   *   {@link PaginatedResult.fetchAll | fetchAll()}, and async iteration support.
+   *
+   * @example
+   * ```ts
+   * // All published projects
+   * const projects = await forja.projects.listPublished({ page: 1, pageSize: 12 });
+   *
+   * // Featured projects only, sorted by display order
+   * const featured = await forja.projects.listPublished({
+   *   isFeatured: true,
+   *   sortBy: 'display_order',
+   *   sortDir: 'asc',
+   * });
+   * ```
+   */
+  listPublished(params?: ProjectListParams): Promise<PaginatedResult<ProjectResponse>>;
+  /**
+   * Fetch a project's full detail by its UUID.
+   *
+   * **Endpoint:** `GET /projects/{id}`
+   *
+   * Returns the complete project with localizations (title, description per locale),
+   * external links (repository, demo, docs), media attachments (cover image,
+   * screenshots), and associations to skills and CV entries.
+   *
+   * @param id - The project's UUID.
+   * @returns The full project detail, or `null` if not found.
+   *
+   * @example
+   * ```ts
+   * const project = await forja.projects.get('project-uuid');
+   * if (project) {
+   *   const loc = project.localizations.find(l => l.locale_id === localeId);
+   *   console.log(loc?.title, loc?.short_description);
+   *   console.log(project.links);  // [{ label, url, link_type }]
+   * }
+   * ```
+   */
+  get(id: string): Promise<ProjectDetailResponse | null>;
+  /**
+   * Fetch a project by its URL slug.
+   *
+   * **Endpoint:** `GET /sites/{siteId}/projects/by-slug/{slug}`
+   *
+   * @param slug - The project's URL slug (e.g. `"forja-cms"`, `"my-portfolio"`).
+   * @returns The project summary, or `null` if not found.
+   *
+   * @example
+   * ```ts
+   * const project = await forja.projects.getBySlug('forja-cms');
+   * ```
+   */
+  getBySlug(slug: string): Promise<ProjectResponse | null>;
+}
+//#endregion
+//#region src/resources/redirects.d.ts
+/**
+ * URL redirect operations.
+ *
+ * Provides server-side redirect lookup for SSR frameworks. When a request
+ * arrives at a path that has a redirect configured, use {@link lookup} to
+ * check if the path should be redirected and to which destination.
+ *
+ * Requires an API key with `Read` permission.
+ */
+declare class RedirectsResource {
+  private readonly http;
+  private readonly siteId;
+  constructor(http: HttpClient, siteId: string);
+  /**
+   * Look up a redirect for a given request path.
+   *
+   * **Endpoint:** `GET /sites/{siteId}/redirects/lookup?path=`
+   *
+   * Checks if the site has an active redirect configured for the given path.
+   * Returns the destination URL and HTTP status code (301 permanent, 302 temporary,
+   * 307 temporary preserve method, 308 permanent preserve method).
+   *
+   * Use this in SSR middleware to handle redirects before rendering the page.
+   *
+   * @param path - The request path to check (e.g. `"/old-blog-post"`, `"/legacy/page"`).
+   * @returns The redirect destination and status code, or `null` if no redirect exists for this path.
+   *
+   * @example
+   * ```ts
+   * // In Astro middleware or Next.js middleware:
+   * const redirect = await forja.redirects.lookup('/old-url');
+   * if (redirect) {
+   *   return Response.redirect(redirect.destination_path, redirect.status_code);
+   * }
+   * ```
+   *
+   * @example
+   * ```ts
+   * // In Express:
+   * app.use(async (req, res, next) => {
+   *   const redirect = await forja.redirects.lookup(req.path);
+   *   if (redirect) {
+   *     return res.redirect(redirect.status_code, redirect.destination_path);
+   *   }
+   *   next();
+   * });
+   * ```
+   */
+  lookup(path: string): Promise<RedirectLookupResponse | null>;
+}
+//#endregion
+//#region src/resources/site.d.ts
+/**
+ * Site configuration operations.
+ *
+ * Provides access to the site's metadata (name, slug, timezone, etc.)
+ * and configured locales (languages available for content).
+ *
+ * Requires an API key with `Read` permission.
+ */
+declare class SiteResource {
+  private readonly http;
+  private readonly siteId;
+  constructor(http: HttpClient, siteId: string);
+  /**
+   * Fetch the site's configuration.
+   *
+   * **Endpoint:** `GET /sites/{siteId}`
+   *
+   * Returns the site's name, slug, description, logo/favicon URLs, timezone,
+   * theme settings, and default locale. Useful for rendering site-wide UI
+   * elements (header, footer, SEO defaults).
+   *
+   * @returns The site configuration.
+   *
+   * @example
+   * ```ts
+   * const site = await forja.site.get();
+   * console.log(site.name);        // "My Website"
+   * console.log(site.timezone);    // "Europe/Vienna"
+   * console.log(site.favicon_url); // "https://cdn.example.com/favicon.ico"
+   * ```
+   */
+  get(): Promise<SiteResponse>;
+  /**
+   * Fetch all locales configured for the site.
+   *
+   * **Endpoint:** `GET /sites/{siteId}/locales`
+   *
+   * Returns the languages available for content on this site, including
+   * the default locale, locale codes, text direction (LTR/RTL), and
+   * active status. Use to build language switchers and determine which
+   * locale to pass to other API calls (e.g. blog listing with `localeId`).
+   *
+   * @returns Array of site locales, with the default locale marked via `is_default`.
+   *
+   * @example
+   * ```ts
+   * const locales = await forja.site.listLocales();
+   * const defaultLocale = locales.find(l => l.is_default);
+   * console.log(defaultLocale?.code); // "en"
+   *
+   * // Build a language switcher
+   * locales
+   *   .filter(l => l.is_active)
+   *   .forEach(l => console.log(`${l.name} (${l.code})`));
+   * ```
+   */
+  listLocales(): Promise<SiteLocaleResponse[]>;
+}
+//#endregion
+//#region src/resources/social.d.ts
+/**
+ * Social media link operations.
+ *
+ * Provides access to the site's configured social media links
+ * (GitHub, Twitter/X, LinkedIn, etc.) for rendering in headers, footers,
+ * and about pages.
+ *
+ * Requires an API key with `Read` permission.
+ */
+declare class SocialResource {
+  private readonly http;
+  private readonly siteId;
+  constructor(http: HttpClient, siteId: string);
+  /**
+   * Fetch all social media links for the site.
+   *
+   * **Endpoint:** `GET /sites/{siteId}/social`
+   *
+   * Returns links sorted by `display_order`. Each link includes a title,
+   * URL, icon identifier, and optional alt text for accessibility.
+   *
+   * @returns Array of social links.
+   *
+   * @example
+   * ```ts
+   * const links = await forja.social.list();
+   * links.forEach(link => {
+   *   console.log(`${link.title}: ${link.url} (icon: ${link.icon})`);
+   * });
+   * ```
+   */
+  list(): Promise<SocialLinkResponse[]>;
+}
+//#endregion
+//#region src/resources/taxonomy.d.ts
+/**
+ * Taxonomy operations (tags and categories).
+ *
+ * Tags and categories are used to organize blog posts and other content.
+ * Categories support hierarchy (parent/child), while tags are flat labels.
+ *
+ * All operations require an API key with `Read` permission.
+ */
+declare class TaxonomyResource {
+  private readonly http;
+  private readonly siteId;
+  constructor(http: HttpClient, siteId: string);
+  /**
+   * Fetch a paginated list of tags for the site.
+   *
+   * **Endpoint:** `GET /sites/{siteId}/tags?page=&page_size=&search=&sort_by=&sort_dir=`
+   *
+   * @param params - Pagination, search, and sort options.
+   * @returns A paginated result of tags.
+   *
+   * @example
+   * ```ts
+   * const tags = await forja.taxonomy.listTags({ search: 'rust', sortBy: 'slug' });
+   * ```
+   */
+  listTags(params?: SearchablePaginationParams): Promise<PaginatedResult<TagResponse>>;
+  /**
+   * Fetch a paginated list of categories for the site.
+   *
+   * **Endpoint:** `GET /sites/{siteId}/categories?page=&page_size=&search=&sort_by=&sort_dir=`
+   *
+   * @param params - Pagination, search, and sort options.
+   * @returns A paginated result of categories.
+   *
+   * @example
+   * ```ts
+   * const categories = await forja.taxonomy.listCategories({ page: 1, pageSize: 50 });
+   * ```
+   */
+  listCategories(params?: SearchablePaginationParams): Promise<PaginatedResult<CategoryResponse>>;
+  /**
+   * Fetch all categories with their associated blog post counts.
+   *
+   * **Endpoint:** `GET /sites/{siteId}/categories/blog-counts`
+   *
+   * Useful for rendering category sidebars with post counts.
+   *
+   * @returns Array of categories, each with a `blog_count` field.
+   *
+   * @example
+   * ```ts
+   * const categories = await forja.taxonomy.getCategoriesWithBlogCounts();
+   * categories.forEach(c => console.log(`${c.slug}: ${c.blog_count} posts`));
+   * ```
+   */
+  getCategoriesWithBlogCounts(): Promise<CategoryWithCountResponse[]>;
+  /**
+   * Fetch all tags associated with a specific content item (blog, page, etc.).
+   *
+   * **Endpoint:** `GET /content/{contentId}/tags`
+   *
+   * @param contentId - The content item's UUID (the `content_id` field, not the blog/page ID).
+   * @returns Array of tags assigned to the content.
+   */
+  getContentTags(contentId: string): Promise<TagResponse[]>;
+  /**
+   * Fetch all categories associated with a specific content item.
+   *
+   * **Endpoint:** `GET /content/{contentId}/categories`
+   *
+   * @param contentId - The content item's UUID (the `content_id` field, not the blog/page ID).
+   * @returns Array of categories assigned to the content.
+   */
+  getContentCategories(contentId: string): Promise<CategoryResponse[]>;
+  /**
+   * Fetch a single tag by its UUID.
+   *
+   * **Endpoint:** `GET /tags/{id}`
+   *
+   * @param id - The tag's UUID.
+   * @returns The tag, or `null` if not found.
+   *
+   * @example
+   * ```ts
+   * const tag = await forja.taxonomy.getTag('tag-uuid');
+   * ```
+   */
+  getTag(id: string): Promise<TagResponse | null>;
+  /**
+   * Fetch a single tag by its URL slug.
+   *
+   * **Endpoint:** `GET /tags/by-slug/{slug}`
+   *
+   * @param slug - The tag's URL slug (e.g. `"typescript"`, `"web-components"`).
+   * @returns The tag, or `null` if not found.
+   *
+   * @example
+   * ```ts
+   * const tag = await forja.taxonomy.getTagBySlug('typescript');
+   * if (tag) {
+   *   console.log(tag.name, tag.slug);
+   * }
+   * ```
+   */
+  getTagBySlug(slug: string): Promise<TagResponse | null>;
+  /**
+   * Fetch a single category by its UUID.
+   *
+   * **Endpoint:** `GET /categories/{id}`
+   *
+   * @param id - The category's UUID.
+   * @returns The category, or `null` if not found.
+   *
+   * @example
+   * ```ts
+   * const category = await forja.taxonomy.getCategory('cat-uuid');
+   * ```
+   */
+  getCategory(id: string): Promise<CategoryResponse | null>;
+  /**
+   * Fetch child categories of a parent category.
+   *
+   * **Endpoint:** `GET /categories/{parentId}/children`
+   *
+   * Use to build hierarchical category trees (e.g. nested navigation menus,
+   * category sidebars with subcategories).
+   *
+   * @param parentId - The parent category's UUID.
+   * @returns Array of child categories.
+   *
+   * @example
+   * ```ts
+   * const subcategories = await forja.taxonomy.getCategoryChildren('parent-uuid');
+   * subcategories.forEach(child => console.log(child.slug));
+   * ```
+   */
+  getCategoryChildren(parentId: string): Promise<CategoryResponse[]>;
+}
+//#endregion
+//#region src/client.d.ts
+/**
+ * The main entry point for the Forja CMS content SDK.
+ *
+ * Create an instance with your API credentials and use the resource
+ * properties to interact with the Forja content API.
+ *
+ * @example
+ * ```ts
+ * import { ForjaClient } from '@forjacms/client';
+ *
+ * const forja = new ForjaClient({
+ *   baseUrl: 'https://cms.example.com/api/v1',
+ *   apiKey: 'your-read-api-key',
+ *   siteId: 'your-site-uuid',
+ * });
+ *
+ * const blogs = await forja.blogs.listPublished({ page: 1 });
+ * const site = await forja.site.get();
+ * const locales = await forja.site.listLocales();
+ * ```
+ */
+declare class ForjaClient {
+  /** Blog posts — published listings, featured, similar, detail by slug/ID. */
+  readonly blogs: BlogsResource;
+  /** CMS pages — list, fetch by route, sections and localizations. */
+  readonly pages: PagesResource;
+  /** Navigation menus — menu metadata, tree structure, items. */
+  readonly navigation: NavigationResource;
+  /** Tags and categories — listing, lookup by slug, content associations, blog counts. */
+  readonly taxonomy: TaxonomyResource;
+  /** Privacy-first analytics — pageview tracking and reports. */
+  readonly analytics: AnalyticsResource;
+  /** CV / resume — skills and work/education entries. */
+  readonly cv: CvResource;
+  /** Legal documents — privacy policy, cookie consent, terms, version history. */
+  readonly legal: LegalResource;
+  /** Portfolio projects — published listings, detail, skill/CV associations. */
+  readonly projects: ProjectsResource;
+  /** URL redirects — path-based lookup for SSR middleware. */
+  readonly redirects: RedirectsResource;
+  /** Site configuration — name, slug, logo, timezone, locales. */
+  readonly site: SiteResource;
+  /** Media assets — browse, search, filter by type, full detail with variants. */
+  readonly media: MediaResource;
+  /** Social media links — GitHub, Twitter, LinkedIn, etc. */
+  readonly social: SocialResource;
+  /**
+   * @param config - API connection settings.
+   * @param config.baseUrl - Full URL to the Forja API (e.g. `https://cms.example.com/api/v1`).
+   * @param config.apiKey - API key with at least `Read` permission.
+   * @param config.siteId - UUID of the site to query.
+   * @param config.fetch - Optional custom `fetch` implementation for edge runtimes or testing.
+   */
+  constructor(config: ForjaClientConfig);
+}
+//#endregion
+export { ProjectLocalizationResponse as $, LegalVersionResponse as A, NavigationTree as B, LegalDocumentDetailResponse as C, LegalGroupResponse as D, LegalDocumentWithGroups as E, MediaResponse as F, PageType as G, PageListItem as H, MediaVariantResponse as I, PaginationParams as J, Paginated as K, NavigationItemLocalizationResponse as L, LocalizationResponse as M, MediaListItem as N, LegalGroupWithItems as O, MediaListParams as P, ProjectListParams as Q, NavigationItemResponse as R, LegalDocType as S, LegalDocumentResponse as T, PageResponse as U, PageDetailResponse as V, PageSectionResponse as W, ProjectLinkResponse as X, ProjectDetailResponse as Y, ProjectLinkType as Z, CvEntryResponse as _, TranslationStatus as _t, AnalyticsPageParams as a, SearchablePaginationParams as at, ForjaClientConfig as b, BlogDetailResponse as c, SiteLocaleResponse as ct, BlogResponse as d, SkillResponse as dt, ProjectMediaResponse as et, CategoryResponse as f, SocialLinkResponse as ft, CvEntryParams as g, TrackPageviewResponse as gt, ContentStatus as h, TrackPageviewRequest as ht, AnalyticsPageDetailResponse as i, ReferrerItem as it, LocaleFilterParams as j, LegalItemResponse as k, BlogDocumentResponse as l, SiteResponse as lt, CategoryWithCountResponse as m, TopContentItem as mt, HttpClient as n, RedirectLookupResponse as nt, AnalyticsReportParams as o, SectionLocalizationResponse as ot, CategoryTree as p, TagResponse as pt, PaginationMeta as q, PaginatedResult as r, RedirectResponse as rt, AnalyticsReportResponse as s, SectionType as st, ForjaClient as t, ProjectResponse as tt, BlogListItem as u, SkillCategory as ut, CvEntryType as v, TrendDataPoint as vt, LegalDocumentFullDetailResponse as w, LegalDocLocalizationResponse as x, DocumentLocalizationResponse as y, NavigationMenuResponse as z };