@serialsubscriptions/platform-integration 0.0.79

package/lib/SSISubscribedFeatureApi.js

@@ -0,0 +1,511 @@
+"use strict";
+/**
+ * @file
+ * SSISubscribedFeatureApi - JSON:API Client for Subscribed Feature Entities
+ *
+ * A TypeScript client for interacting with Drupal JSON:API endpoints
+ * for subscribed_feature 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 SSISubscribedFeatureApi('https://example.com');
+ *
+ * // Set Bearer token authentication
+ * client.setBearerToken('your-oauth-or-jwt-token-here');
+ *
+ * // List subscribed features with filters and pagination
+ * const features = await client.list(
+ *   { status: 'active' },
+ *   ['-created'],
+ *   { offset: 0, limit: 10 }
+ * );
+ *
+ * // Get a single subscribed feature by UUID
+ * const feature = await client.get('550e8400-e29b-41d4-a716-446655440000', {
+ *   include: ['subscription', 'feature'],
+ * });
+ *
+ * // Create a subscribed feature
+ * const newFeature = await client.create(
+ *   { status: 'active' },
+ *   {
+ *     subscription: { type: 'subscription--subscription', id: 'subscription-uuid' },
+ *     feature: { type: 'feature--feature', id: 'feature-uuid' },
+ *   }
+ * );
+ *
+ * // Update a subscribed feature by UUID
+ * await client.update('550e8400-e29b-41d4-a716-446655440000', { status: 'inactive' });
+ *
+ * // Delete a subscribed feature by UUID
+ * await client.delete('550e8400-e29b-41d4-a716-446655440000');
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SSISubscribedFeatureApi = void 0;
+/**
+ * SSISubscribedFeatureApi - JSON:API Client for Subscribed Feature Entities
+ */
+class SSISubscribedFeatureApi {
+    /**
+     * Constructs an SSISubscribedFeatureApi 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/subscribed_feature/subscribed_feature')
+     *   - timeout: Request timeout in milliseconds (default: 30000)
+     */
+    constructor(domain, options) {
+        this.apiBasePath = '/jsonapi/subscribed_feature/subscribed_feature';
+        this.bearerToken = null;
+        this.csrfToken = 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;
+        }
+    }
+    /**
+     * 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;
+    }
+    /**
+     * Fetches a CSRF token from the Drupal session/token endpoint.
+     * The token is cached after the first fetch to avoid unnecessary requests.
+     *
+     * @returns Promise resolving to the CSRF token string.
+     *
+     * @throws Error if the request fails.
+     *
+     * @private
+     */
+    async getCsrfToken() {
+        if (this.csrfToken) {
+            return this.csrfToken;
+        }
+        const url = `${this.baseUrl}/session/token`;
+        const headers = {
+            'Accept': 'text/plain',
+        };
+        if (this.bearerToken) {
+            headers['Authorization'] = `Bearer ${this.bearerToken}`;
+        }
+        try {
+            const response = await fetch(url, {
+                method: 'GET',
+                headers,
+            });
+            if (!response.ok) {
+                throw new Error(`Failed to fetch CSRF token: HTTP ${response.status} ${response.statusText}`);
+            }
+            const token = await response.text();
+            if (!token || !token.trim()) {
+                throw new Error('CSRF token response was empty');
+            }
+            this.csrfToken = token.trim();
+            return this.csrfToken;
+        }
+        catch (error) {
+            console.error('[SSISubscribedFeatureApi] Failed to fetch CSRF token:', error);
+            if (error instanceof Error) {
+                throw new Error(`CSRF token fetch failed: ${error.message}`);
+            }
+            throw new Error(`CSRF token fetch failed: ${String(error)}`);
+        }
+    }
+    /**
+     * Clears the cached CSRF token, forcing a fresh fetch on the next write operation.
+     * This may be useful if the token expires or becomes invalid.
+     */
+    clearCsrfToken() {
+        this.csrfToken = null;
+    }
+    /**
+     * Lists subscribed_feature 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', 'status'] for descending created, ascending status)
+     *   - pagination: Pagination options (offset, limit; max limit: 50)
+     *   - include: Related resources to include (e.g., ['subscription', 'feature'])
+     *   - fields: Sparse fieldsets to limit returned fields
+     *
+     * @returns Promise resolving to the JSON:API document with subscribed features.
+     *
+     * @throws Error if the request fails.
+     */
+    async list(options = {}) {
+        const queryParams = new URLSearchParams();
+        if (options.filters) {
+            const filterParams = this.buildFilterParams(options.filters);
+            for (const [key, value] of Object.entries(filterParams)) {
+                queryParams.append(key, String(value));
+            }
+        }
+        if (options.sort && options.sort.length > 0) {
+            queryParams.set('sort', options.sort.join(','));
+        }
+        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)));
+            }
+        }
+        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}${queryParams.toString() ? `?${queryParams.toString()}` : ''}`;
+        return this.request('GET', url);
+    }
+    /**
+     * Retrieves a single subscribed_feature entity by UUID.
+     *
+     * The API endpoint is constructed as: baseUrl + apiBasePath + "/" + uuid
+     * Example: https://example.com/jsonapi/subscribed_feature/subscribed_feature/550e8400-e29b-41d4-a716-446655440000
+     *
+     * @param uuid - The UUID of the subscribed_feature entity (NOT the subscribed_feature ID).
+     *               Must be a valid UUID string (e.g., '550e8400-e29b-41d4-a716-446655440000').
+     * @param options - Get options:
+     *   - include: Related resources to include (e.g., ['subscription', 'feature'])
+     *   - fields: Sparse fieldsets to limit returned fields
+     *
+     * @returns Promise resolving to the JSON:API document with the subscribed feature.
+     *
+     * @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 subscribed_feature entity.
+     *
+     * @param attributes - Entity attributes.
+     * @param options - Create options:
+     *   - relationships: Entity relationships
+     *   - resourceType: The resource type (default: 'subscribed_feature--subscribed_feature')
+     *
+     * @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 || 'subscribed_feature--subscribed_feature';
+        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 subscribed_feature entity.
+     *
+     * The API endpoint is constructed as: baseUrl + apiBasePath + "/" + uuid
+     * Example: https://example.com/jsonapi/subscribed_feature/subscribed_feature/550e8400-e29b-41d4-a716-446655440000
+     *
+     * @param uuid - The UUID of the subscribed_feature entity to update (NOT the subscribed_feature ID).
+     *               Must be a valid UUID string (e.g., '550e8400-e29b-41d4-a716-446655440000').
+     * @param attributes - Attributes to update (partial updates supported).
+     * @param options - Update options:
+     *   - relationships: Relationships to update (optional)
+     *   - resourceType: The resource type (default: 'subscribed_feature--subscribed_feature')
+     *
+     * @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 || 'subscribed_feature--subscribed_feature';
+        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 subscribed_feature entity.
+     *
+     * The API endpoint is constructed as: baseUrl + apiBasePath + "/" + uuid
+     * Example: https://example.com/jsonapi/subscribed_feature/subscribed_feature/550e8400-e29b-41d4-a716-446655440000
+     *
+     * @param uuid - The UUID of the subscribed_feature entity to delete (NOT the subscribed_feature ID).
+     *               Must be a valid UUID string (e.g., '550e8400-e29b-41d4-a716-446655440000').
+     *
+     * @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);
+        const responseClone = response.clone();
+        const responseText = await responseClone.text();
+        if (response.status === 204) {
+            return true;
+        }
+        if (!response.ok) {
+            const errorData = await this.parseErrorResponse(response);
+            console.error('[SSISubscribedFeatureApi] DELETE error response:', errorData);
+            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);
+        const responseText = await response.text();
+        if (!response.ok) {
+            const errorData = this.parseErrorResponseFromText(responseText);
+            console.error('[SSISubscribedFeatureApi] Error response:', errorData);
+            throw this.createError(errorData, response.status, response.statusText);
+        }
+        if (response.status === 204) {
+            return { data: [] };
+        }
+        const json = JSON.parse(responseText);
+        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 };
+        if (this.bearerToken) {
+            headers['Authorization'] = `Bearer ${this.bearerToken}`;
+        }
+        if (['POST', 'PATCH', 'DELETE'].includes(method)) {
+            try {
+                const csrfToken = await this.getCsrfToken();
+                if (csrfToken) {
+                    headers['X-CSRF-Token'] = csrfToken;
+                }
+            }
+            catch (error) {
+                console.warn('[SSISubscribedFeatureApi] Failed to fetch CSRF token, proceeding without it:', error);
+            }
+        }
+        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) {
+            console.error('[SSISubscribedFeatureApi] Request error:', 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();
+            return this.parseErrorResponseFromText(text);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Parses error response from text string.
+     *
+     * @param text - The response text.
+     *
+     * @returns The error data, or null if parsing fails.
+     *
+     * @private
+     */
+    parseErrorResponseFromText(text) {
+        try {
+            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)) {
+            if (typeof condition === 'string' || typeof condition === 'number') {
+                params[`filter[${field}]`] = String(condition);
+                continue;
+            }
+            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;
+                    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)) {
+            if (relationship && typeof relationship === 'object' && 'type' in relationship && 'id' in relationship) {
+                formatted[fieldName] = {
+                    data: {
+                        type: relationship.type,
+                        id: relationship.id,
+                    },
+                };
+            }
+            else if (Array.isArray(relationship)) {
+                formatted[fieldName] = {
+                    data: relationship.map((item) => ({
+                        type: item.type,
+                        id: item.id,
+                    })),
+                };
+            }
+        }
+        return formatted;
+    }
+}
+exports.SSISubscribedFeatureApi = SSISubscribedFeatureApi;