@serialsubscriptions/platform-integration 0.0.79

package/lib/SSISubscribedPlanApi.js

@@ -0,0 +1,537 @@
+"use strict";
+/**
+ * @file
+ * SSISubscribedPlanApi - JSON:API Client for Subscribed Plan Entities
+ *
+ * A TypeScript client for interacting with Drupal JSON:API endpoints
+ * for subscribed_plan 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 SSISubscribedPlanApi('https://example.com');
+ *
+ * // Set Bearer token authentication
+ * client.setBearerToken('your-oauth-or-jwt-token-here');
+ *
+ * // List subscribed plans with filters and pagination
+ * const plans = await client.list(
+ *   { status: 'active' },
+ *   ['-created'],
+ *   { offset: 0, limit: 10 }
+ * );
+ *
+ * // Get a single subscribed plan by UUID
+ * const plan = await client.get('550e8400-e29b-41d4-a716-446655440000', {
+ *   include: ['owner', 'subscription_plan']
+ * });
+ *
+ * // Create a subscribed plan
+ * const newPlan = await client.create(
+ *   { status: 'active' },
+ *   { user: { type: 'user--user', id: 'user-uuid' } }
+ * );
+ *
+ * // Update a subscribed plan by UUID
+ * await client.update('550e8400-e29b-41d4-a716-446655440000', { status: 'cancelled' });
+ *
+ * // Delete a subscribed plan by UUID
+ * await client.delete('550e8400-e29b-41d4-a716-446655440000');
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SSISubscribedPlanApi = void 0;
+/**
+ * SSISubscribedPlanApi - JSON:API Client for Subscribed Plan Entities
+ */
+class SSISubscribedPlanApi {
+    /**
+     * Constructs an SSISubscribedPlanApi 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_plan/subscribed_plan')
+     *   - timeout: Request timeout in milliseconds (currently unused; reserved for future use)
+     */
+    constructor(domain, options) {
+        this.apiBasePath = '/jsonapi/subscribed_plan/subscribed_plan';
+        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() {
+        // Return cached token if available
+        if (this.csrfToken) {
+            return this.csrfToken;
+        }
+        const url = `${this.baseUrl}/session/token`;
+        const headers = {
+            Accept: 'text/plain',
+        };
+        // Include Bearer token if available (for authenticated requests)
+        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');
+            }
+            // Cache the token
+            this.csrfToken = token.trim();
+            return this.csrfToken;
+        }
+        catch (error) {
+            console.error('[SSISubscribedPlanApi] 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_plan 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., ['user', 'subscription_plan'])
+     *   - fields: Sparse fieldsets to limit returned fields
+     *
+     * @returns Promise resolving to the JSON:API document with subscribed plans.
+     *
+     * @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 subscribed_plan entity by UUID.
+     *
+     * The API endpoint is constructed as: baseUrl + apiBasePath + "/" + uuid
+     * Example: https://example.com/jsonapi/subscribed_plan/subscribed_plan/550e8400-e29b-41d4-a716-446655440000
+     *
+     * @param uuid - The UUID of the subscribed_plan entity (NOT the internal 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., ['user', 'subscription_plan'])
+     *   - fields: Sparse fieldsets to limit returned fields
+     *
+     * @returns Promise resolving to the JSON:API document with the subscribed plan.
+     *
+     * @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(','));
+            }
+        }
+        // Construct URL: baseUrl + apiBasePath + "/" + uuid
+        const url = `${this.baseUrl}${this.apiBasePath}/${uuid}${queryParams.toString() ? `?${queryParams.toString()}` : ''}`;
+        return this.request('GET', url);
+    }
+    /**
+     * Creates a new subscribed_plan entity.
+     *
+     * @param attributes - Entity attributes (e.g., { status: 'active' }).
+     * @param options - Create options:
+     *   - relationships: Entity relationships
+     *   - resourceType: The resource type (default: 'subscribed_plan--subscribed_plan')
+     *
+     * @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_plan--subscribed_plan';
+        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_plan entity.
+     *
+     * The API endpoint is constructed as: baseUrl + apiBasePath + "/" + uuid
+     * Example: https://example.com/jsonapi/subscribed_plan/subscribed_plan/550e8400-e29b-41d4-a716-446655440000
+     *
+     * @param uuid - The UUID of the subscribed_plan entity to update (NOT the internal 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_plan--subscribed_plan')
+     *
+     * @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_plan--subscribed_plan';
+        const data = {
+            type: resourceType,
+            id: uuid,
+            attributes,
+        };
+        if (options.relationships) {
+            data.relationships = this.formatRelationships(options.relationships);
+        }
+        const body = { data };
+        // Construct URL: baseUrl + apiBasePath + "/" + uuid
+        const url = `${this.baseUrl}${this.apiBasePath}/${uuid}`;
+        return this.request('PATCH', url, body);
+    }
+    /**
+     * Deletes a subscribed_plan entity.
+     *
+     * The API endpoint is constructed as: baseUrl + apiBasePath + "/" + uuid
+     * Example: https://example.com/jsonapi/subscribed_plan/subscribed_plan/550e8400-e29b-41d4-a716-446655440000
+     *
+     * @param uuid - The UUID of the subscribed_plan entity to delete (NOT the internal 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) {
+        // Construct URL: baseUrl + apiBasePath + "/" + uuid
+        const url = `${this.baseUrl}${this.apiBasePath}/${uuid}`;
+        const response = await this.requestRaw('DELETE', url);
+        // Get response text for debugging
+        const responseClone = response.clone();
+        const responseText = await responseClone.text();
+        // 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);
+            console.error('[SSISubscribedPlanApi] 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);
+        // Get response text for debugging and parsing
+        const responseText = await response.text();
+        if (!response.ok) {
+            // Parse error from the response text we already read
+            const errorData = this.parseErrorResponseFromText(responseText);
+            console.error('[SSISubscribedPlanApi] Error response:', errorData);
+            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: [] };
+        }
+        // Parse JSON from the response text
+        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 };
+        // Add authentication if configured
+        if (this.bearerToken) {
+            headers['Authorization'] = `Bearer ${this.bearerToken}`;
+        }
+        // Add CSRF token for write operations
+        if (['POST', 'PATCH', 'DELETE'].includes(method)) {
+            try {
+                const csrfToken = await this.getCsrfToken();
+                if (csrfToken) {
+                    headers['X-CSRF-Token'] = csrfToken;
+                }
+            }
+            catch (error) {
+                console.warn('[SSISubscribedPlanApi] Failed to fetch CSRF token, proceeding without it:', error);
+                // Continue without CSRF token - some configurations may not require it
+            }
+        }
+        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('[SSISubscribedPlanApi] 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)) {
+            // 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: { user: { 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;
+    }
+}
+exports.SSISubscribedPlanApi = SSISubscribedPlanApi;