docs: add JSDoc documentation to core modules (directus, i18n, router, helpers)

js/services/directus.js

@@ -1,10 +1,43 @@
 /**
  * Directus API Service for dgray.io
  * Connects to https://api.dgray.io/
+ * @module services/directus
  */
 
+/** @type {string} */
 const DIRECTUS_URL = 'https://api.dgray.io'
 
+/**
+ * @typedef {Object} AuthTokens
+ * @property {string} access_token - JWT access token
+ * @property {string} refresh_token - Refresh token for session renewal
+ * @property {number} expires - Token expiry in seconds
+ */
+
+/**
+ * @typedef {Object} Listing
+ * @property {string} id - UUID
+ * @property {string} title - Listing title
+ * @property {string} [description] - Listing description
+ * @property {number} price - Price value
+ * @property {string} currency - Currency code (EUR, USD, CHF, XMR)
+ * @property {string} status - Status (draft, published, sold, expired)
+ * @property {Object} [location] - Location object
+ * @property {Array} [images] - Array of image objects
+ */
+
+/**
+ * @typedef {Object} Category
+ * @property {string} id - UUID
+ * @property {string} slug - URL-safe slug
+ * @property {string} [parent] - Parent category ID
+ * @property {Array} [translations] - Category translations
+ */
+
+/**
+ * Main Directus API client
+ * @class
+ */
 class DirectusService {
     constructor() {
         this.baseUrl = DIRECTUS_URL
@@ -82,6 +115,13 @@ class DirectusService {
 
     // ==================== HTTP Methods ====================
 
+    /**
+     * Make an HTTP request to the Directus API
+     * @param {string} endpoint - API endpoint path
+     * @param {RequestInit} [options={}] - Fetch options
+     * @returns {Promise<Object|null>} Response data or null for 204
+     * @throws {DirectusError} On request failure
+     */
     async request(endpoint, options = {}) {
         const url = `${this.baseUrl}${endpoint}`
         
@@ -128,12 +168,24 @@ class DirectusService {
         }
     }
 
+    /**
+     * GET request with query parameters
+     * @param {string} endpoint - API endpoint
+     * @param {Object} [params={}] - Query parameters
+     * @returns {Promise<Object>} Response data
+     */
     async get(endpoint, params = {}) {
         const queryString = this.buildQueryString(params)
         const url = queryString ? `${endpoint}?${queryString}` : endpoint
         return this.request(url, { method: 'GET' })
     }
 
+    /**
+     * POST request with JSON body
+     * @param {string} endpoint - API endpoint
+     * @param {Object} data - Request body
+     * @returns {Promise<Object>} Response data
+     */
     async post(endpoint, data) {
         return this.request(endpoint, {
             method: 'POST',
@@ -141,6 +193,12 @@ class DirectusService {
         })
     }
 
+    /**
+     * PATCH request with JSON body
+     * @param {string} endpoint - API endpoint
+     * @param {Object} data - Request body
+     * @returns {Promise<Object>} Response data
+     */
     async patch(endpoint, data) {
         return this.request(endpoint, {
             method: 'PATCH',
@@ -250,6 +308,15 @@ class DirectusService {
 
     // ==================== Listings (Anzeigen) ====================
 
+    /**
+     * Get listings with filters and pagination
+     * @param {Object} [options={}] - Query options
+     * @param {number} [options.limit=20] - Max items to return
+     * @param {number} [options.page=1] - Page number
+     * @param {string} [options.category] - Filter by category slug
+     * @param {string} [options.search] - Search query
+     * @returns {Promise<{items: Listing[], total: number}>} Paginated listings
+     */
     async getListings(options = {}) {
         const params = {
             fields: options.fields || [
@@ -291,6 +358,11 @@ class DirectusService {
         }
     }
 
+    /**
+     * Get a single listing by ID
+     * @param {string} id - Listing UUID
+     * @returns {Promise<Listing|null>} Listing object or null
+     */
     async getListing(id) {
         const response = await this.get(`/items/listings/${id}`, {
             fields: [
@@ -324,6 +396,11 @@ class DirectusService {
         return response.data
     }
 
+    /**
+     * Create a new listing
+     * @param {Object} data - Listing data
+     * @returns {Promise<Listing>} Created listing
+     */
     async createListing(data) {
         const response = await this.post('/items/listings', data)
         return response?.data || response
@@ -656,6 +733,13 @@ class DirectusService {
 
     // ==================== Files (Dateien/Bilder) ====================
 
+    /**
+     * Upload a file to Directus
+     * @param {File} file - File to upload
+     * @param {Object} [options={}] - Upload options
+     * @param {string} [options.folder] - Target folder ID
+     * @returns {Promise<Object>} Uploaded file data
+     */
     async uploadFile(file, options = {}) {
         const formData = new FormData()
         formData.append('file', file)
@@ -684,6 +768,15 @@ class DirectusService {
         return Promise.all(uploads)
     }
 
+    /**
+     * Get URL for a file with optional transformations
+     * @param {string} fileId - File UUID
+     * @param {Object} [options={}] - Transform options
+     * @param {number} [options.width] - Resize width
+     * @param {number} [options.height] - Resize height
+     * @param {string} [options.fit] - Fit mode (cover, contain, etc.)
+     * @returns {string|null} File URL or null
+     */
     getFileUrl(fileId, options = {}) {
         if (!fileId) return null