@serialsubscriptions/platform-integration 0.0.79

package/lib/SSIProject.js

@@ -0,0 +1,429 @@
+/**
+ * @file
+ * SSIProjectApi - JSON:API Client for Project Entities
+ *
+ * A TypeScript client for interacting with Drupal JSON:API endpoints
+ * for project entities. This class is independent of Drupal and can be used
+ * on any platform that supports fetch.
+ *
+ * Requirements:
+ * - Node.js 18+ (for native fetch) or a fetch polyfill
+ * - TypeScript 5.0+
+ *
+ * Usage:
+ * @example
+ * ```typescript
+ * // Initialize the client with a domain
+ * const client = new SSIProjectApi('https://example.com');
+ *
+ * // Set Bearer token authentication
+ * client.setBearerToken('your-oauth-or-jwt-token-here');
+ *
+ * // List projects with filters and pagination
+ * const projects = await client.list(
+ *   { status: 'active' },
+ *   ['-created'],
+ *   { offset: 0, limit: 10 }
+ * );
+ *
+ * // Get a single project
+ * const project = await client.get('uuid-here', ['owner', 'tags']);
+ *
+ * // Create a project
+ * const newProject = await client.create(
+ *   { title: 'New Project', status: 'active' },
+ *   { owner: { type: 'user--user', id: 'user-uuid' } }
+ * );
+ *
+ * // Update a project
+ * await client.update('uuid-here', { status: 'completed' });
+ *
+ * // Delete a project
+ * await client.delete('uuid-here');
+ * ```
+ */
+/**
+ * SSIProjectApi - JSON:API Client for Project Entities
+ */
+export class SSIProjectApi {
+    /**
+     * Constructs an SSIProjectApi client.
+     *
+     * @param domain - The full URL prefix of the Drupal site (e.g., 'https://example.com').
+     * @param options - Optional configuration:
+     *   - apiBasePath: Override the default API path (default: '/jsonapi/project/project')
+     *   - timeout: Request timeout in milliseconds (default: 30000)
+     */
+    constructor(domain, options) {
+        this.apiBasePath = '/jsonapi/project/project';
+        this.bearerToken = null;
+        this.defaultHeaders = {
+            'Accept': 'application/vnd.api+json',
+            'Content-Type': 'application/vnd.api+json',
+        };
+        this.baseUrl = domain.trim().replace(/\/+$/, ''); // Remove trailing slashes
+        if (options?.apiBasePath) {
+            this.apiBasePath = options.apiBasePath;
+        }
+        // TODO: Add CSRF token handling
+        // CSRF tokens may be required for write operations (POST, PATCH, DELETE)
+        // when using certain authentication methods. This should be implemented
+        // by fetching the token from /session/token endpoint before write operations.
+    }
+    /**
+     * Sets the Bearer token for authentication.
+     *
+     * @param token - The Bearer token (OAuth/JWT).
+     */
+    setBearerToken(token) {
+        this.bearerToken = token;
+    }
+    /**
+     * Gets the current Bearer token.
+     *
+     * @returns The Bearer token, or null if not set.
+     */
+    getBearerToken() {
+        return this.bearerToken;
+    }
+    /**
+     * Lists project entities with optional filtering, sorting, and pagination.
+     *
+     * @param options - List options:
+     *   - filters: Filter conditions (e.g., { status: 'active' } or { created: { operator: '>', value: '2024-01-01' } })
+     *   - sort: Sort fields (e.g., ['-created', 'title'] for descending created, ascending title)
+     *   - pagination: Pagination options (offset, limit; max limit: 50)
+     *   - include: Related resources to include (e.g., ['owner', 'tags'])
+     *   - fields: Sparse fieldsets to limit returned fields
+     *
+     * @returns Promise resolving to the JSON:API document with projects.
+     *
+     * @throws Error if the request fails.
+     */
+    async list(options = {}) {
+        const queryParams = new URLSearchParams();
+        // Build filter query parameters
+        if (options.filters) {
+            const filterParams = this.buildFilterParams(options.filters);
+            for (const [key, value] of Object.entries(filterParams)) {
+                queryParams.append(key, String(value));
+            }
+        }
+        // Build sort query parameters
+        if (options.sort && options.sort.length > 0) {
+            queryParams.set('sort', options.sort.join(','));
+        }
+        // Build pagination query parameters
+        if (options.pagination) {
+            if (options.pagination.offset !== undefined) {
+                queryParams.set('page[offset]', String(options.pagination.offset));
+            }
+            if (options.pagination.limit !== undefined) {
+                queryParams.set('page[limit]', String(Math.min(options.pagination.limit, 50)));
+            }
+        }
+        // Build include query parameters
+        if (options.include && options.include.length > 0) {
+            queryParams.set('include', options.include.join(','));
+        }
+        // Build fields query parameters
+        if (options.fields) {
+            for (const [resourceType, fieldList] of Object.entries(options.fields)) {
+                queryParams.set(`fields[${resourceType}]`, fieldList.join(','));
+            }
+        }
+        const url = `${this.baseUrl}${this.apiBasePath}${queryParams.toString() ? `?${queryParams.toString()}` : ''}`;
+        return this.request('GET', url);
+    }
+    /**
+     * Retrieves a single project entity by UUID.
+     *
+     * @param uuid - The UUID of the project entity.
+     * @param options - Get options:
+     *   - include: Related resources to include
+     *   - fields: Sparse fieldsets to limit returned fields
+     *
+     * @returns Promise resolving to the JSON:API document with the project.
+     *
+     * @throws Error if the request fails or entity is not found.
+     */
+    async get(uuid, options = {}) {
+        const queryParams = new URLSearchParams();
+        if (options.include && options.include.length > 0) {
+            queryParams.set('include', options.include.join(','));
+        }
+        if (options.fields) {
+            for (const [resourceType, fieldList] of Object.entries(options.fields)) {
+                queryParams.set(`fields[${resourceType}]`, fieldList.join(','));
+            }
+        }
+        const url = `${this.baseUrl}${this.apiBasePath}/${uuid}${queryParams.toString() ? `?${queryParams.toString()}` : ''}`;
+        return this.request('GET', url);
+    }
+    /**
+     * Creates a new project entity.
+     *
+     * @param attributes - Entity attributes (e.g., { title: 'My Project', status: 'active' }).
+     * @param options - Create options:
+     *   - relationships: Entity relationships
+     *   - resourceType: The resource type (default: 'project--project')
+     *
+     * @returns Promise resolving to the JSON:API document with the created entity.
+     *
+     * @throws Error if the request fails or validation errors occur.
+     */
+    async create(attributes, options = {}) {
+        const resourceType = options.resourceType || 'project--project';
+        const data = {
+            type: resourceType,
+            attributes,
+        };
+        if (options.relationships) {
+            data.relationships = this.formatRelationships(options.relationships);
+        }
+        const body = { data };
+        const url = `${this.baseUrl}${this.apiBasePath}`;
+        return this.request('POST', url, body);
+    }
+    /**
+     * Updates an existing project entity.
+     *
+     * @param uuid - The UUID of the project entity to update.
+     * @param attributes - Attributes to update (partial updates supported).
+     * @param options - Update options:
+     *   - relationships: Relationships to update (optional)
+     *   - resourceType: The resource type (default: 'project--project')
+     *
+     * @returns Promise resolving to the JSON:API document with the updated entity.
+     *
+     * @throws Error if the request fails or validation errors occur.
+     */
+    async update(uuid, attributes, options = {}) {
+        const resourceType = options.resourceType || 'project--project';
+        const data = {
+            type: resourceType,
+            id: uuid,
+            attributes,
+        };
+        if (options.relationships) {
+            data.relationships = this.formatRelationships(options.relationships);
+        }
+        const body = { data };
+        const url = `${this.baseUrl}${this.apiBasePath}/${uuid}`;
+        return this.request('PATCH', url, body);
+    }
+    /**
+     * Deletes a project entity.
+     *
+     * @param uuid - The UUID of the project entity to delete.
+     *
+     * @returns Promise resolving to true if deletion was successful.
+     *
+     * @throws Error if the request fails.
+     */
+    async delete(uuid) {
+        const url = `${this.baseUrl}${this.apiBasePath}/${uuid}`;
+        const response = await this.requestRaw('DELETE', url);
+        // DELETE returns 204 No Content on success
+        if (response.status === 204) {
+            return true;
+        }
+        // If not 204, try to parse error response
+        if (!response.ok) {
+            const errorData = await this.parseErrorResponse(response);
+            throw this.createError(errorData, response.status, response.statusText);
+        }
+        return true;
+    }
+    /**
+     * Makes an HTTP request to the API and returns the parsed JSON:API document.
+     *
+     * @param method - HTTP method (GET, POST, PATCH).
+     * @param url - The full URL.
+     * @param body - Request body (for POST/PATCH).
+     *
+     * @returns Promise resolving to the parsed JSON:API document.
+     *
+     * @throws Error if the request fails.
+     *
+     * @private
+     */
+    async request(method, url, body) {
+        const response = await this.requestRaw(method, url, body);
+        if (!response.ok) {
+            const errorData = await this.parseErrorResponse(response);
+            throw this.createError(errorData, response.status, response.statusText);
+        }
+        // Handle 204 No Content (shouldn't happen for GET/POST/PATCH, but handle gracefully)
+        if (response.status === 204) {
+            return { data: [] };
+        }
+        const json = await response.json();
+        return json;
+    }
+    /**
+     * Makes a raw HTTP request to the API and returns the Response object.
+     *
+     * @param method - HTTP method (GET, POST, PATCH, DELETE).
+     * @param url - The full URL.
+     * @param body - Request body (for POST/PATCH).
+     *
+     * @returns Promise resolving to the Response object.
+     *
+     * @throws Error if the request fails (network errors, etc.).
+     *
+     * @private
+     */
+    async requestRaw(method, url, body) {
+        const headers = { ...this.defaultHeaders };
+        // Add authentication if configured
+        if (this.bearerToken) {
+            headers['Authorization'] = `Bearer ${this.bearerToken}`;
+        }
+        // TODO: Add CSRF token for write operations
+        // if (['POST', 'PATCH', 'DELETE'].includes(method)) {
+        //   const csrfToken = await this.getCsrfToken();
+        //   if (csrfToken) {
+        //     headers['X-CSRF-Token'] = csrfToken;
+        //   }
+        // }
+        const fetchOptions = {
+            method,
+            headers,
+        };
+        if (body && (method === 'POST' || method === 'PATCH')) {
+            fetchOptions.body = JSON.stringify(body);
+        }
+        try {
+            const response = await fetch(url, fetchOptions);
+            return response;
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Request failed: ${error.message}`);
+            }
+            throw new Error(`Request failed: ${String(error)}`);
+        }
+    }
+    /**
+     * Parses error response from JSON:API.
+     *
+     * @param response - The HTTP response.
+     *
+     * @returns Promise resolving to the error data.
+     *
+     * @private
+     */
+    async parseErrorResponse(response) {
+        try {
+            const text = await response.text();
+            if (!text) {
+                return null;
+            }
+            return JSON.parse(text);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Creates an error from JSON:API error response.
+     *
+     * @param errorData - The error data.
+     * @param status - HTTP status code.
+     * @param statusText - HTTP status text.
+     *
+     * @returns Error instance.
+     *
+     * @private
+     */
+    createError(errorData, status, statusText) {
+        if (errorData && errorData.errors && errorData.errors.length > 0) {
+            const messages = errorData.errors.map((error) => {
+                const statusCode = error.status || String(status);
+                const message = error.detail || error.title || 'Unknown error';
+                return `[${statusCode}] ${message}`;
+            });
+            const error = new Error(messages.join('; '));
+            error.status = status;
+            error.errors = errorData.errors;
+            return error;
+        }
+        const error = new Error(`HTTP ${status} ${statusText}`);
+        error.status = status;
+        return error;
+    }
+    /**
+     * Builds filter query parameters from a filter object.
+     *
+     * @param filters - Filter conditions.
+     *
+     * @returns Query parameters for filters.
+     *
+     * @private
+     */
+    buildFilterParams(filters) {
+        const params = {};
+        let index = 0;
+        for (const [field, condition] of Object.entries(filters)) {
+            // Simple equality filter: { status: 'active' }
+            if (typeof condition === 'string' || typeof condition === 'number') {
+                params[`filter[${field}]`] = String(condition);
+                continue;
+            }
+            // Complex filter with operator: { created: { operator: '>', value: '2024-01-01' } }
+            if (condition && typeof condition === 'object' && 'operator' in condition) {
+                const filterKey = `filter[${index}]`;
+                params[`${filterKey}[condition][path]`] = field;
+                params[`${filterKey}[condition][operator]`] = condition.operator;
+                if ('value' in condition) {
+                    const value = condition.value;
+                    // Handle array values for IN, NOT IN operators
+                    if (Array.isArray(value)) {
+                        value.forEach((v, i) => {
+                            params[`${filterKey}[condition][value][${i}]`] = String(v);
+                        });
+                    }
+                    else {
+                        params[`${filterKey}[condition][value]`] = String(value);
+                    }
+                }
+                index++;
+            }
+        }
+        return params;
+    }
+    /**
+     * Formats relationships for JSON:API format.
+     *
+     * @param relationships - Relationships input.
+     *
+     * @returns Formatted relationships.
+     *
+     * @private
+     */
+    formatRelationships(relationships) {
+        const formatted = {};
+        for (const [fieldName, relationship] of Object.entries(relationships)) {
+            // Single relationship: { owner: { type: 'user--user', id: 'user-uuid' } }
+            if (relationship && typeof relationship === 'object' && 'type' in relationship && 'id' in relationship) {
+                formatted[fieldName] = {
+                    data: {
+                        type: relationship.type,
+                        id: relationship.id,
+                    },
+                };
+            }
+            // Multiple relationships: { tags: [{ type: 'taxonomy_term--tags', id: 'tag-uuid-1' }, ...] }
+            else if (Array.isArray(relationship)) {
+                formatted[fieldName] = {
+                    data: relationship.map((item) => ({
+                        type: item.type,
+                        id: item.id,
+                    })),
+                };
+            }
+        }
+        return formatted;
+    }
+}