@serialsubscriptions/platform-integration 0.0.79

package/lib/SSIProjectApi.d.ts

@@ -0,0 +1,384 @@
+/**
+ * @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 by UUID
+ * const project = await client.get('550e8400-e29b-41d4-a716-446655440000', {
+ *   include: ['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 by UUID
+ * await client.update('550e8400-e29b-41d4-a716-446655440000', { status: 'completed' });
+ *
+ * // Delete a project by UUID
+ * await client.delete('550e8400-e29b-41d4-a716-446655440000');
+ * ```
+ */
+/**
+ * JSON:API Resource Identifier
+ */
+export interface ResourceIdentifier {
+    type: string;
+    id: string;
+}
+/**
+ * JSON:API Relationship Data
+ */
+export type RelationshipData = ResourceIdentifier | ResourceIdentifier[];
+/**
+ * JSON:API Relationship
+ */
+export interface Relationship {
+    data: RelationshipData;
+}
+/**
+ * JSON:API Resource Object
+ */
+export interface JsonApiResource {
+    type: string;
+    id?: string;
+    attributes?: Record<string, unknown>;
+    relationships?: Record<string, Relationship>;
+}
+/**
+ * JSON:API Document
+ */
+export interface JsonApiDocument {
+    data: JsonApiResource | JsonApiResource[];
+    included?: JsonApiResource[];
+    links?: {
+        self?: string;
+        first?: string;
+        last?: string;
+        next?: string;
+        prev?: string;
+    };
+    meta?: {
+        count?: number;
+        [key: string]: unknown;
+    };
+}
+/**
+ * JSON:API Error
+ */
+export interface JsonApiError {
+    status?: string;
+    code?: string;
+    title?: string;
+    detail?: string;
+    source?: {
+        pointer?: string;
+        parameter?: string;
+    };
+}
+/**
+ * JSON:API Error Document
+ */
+export interface JsonApiErrorDocument {
+    errors: JsonApiError[];
+}
+/**
+ * Filter condition with operator
+ */
+export interface FilterCondition {
+    operator: string;
+    value: string | number | string[] | number[];
+}
+/**
+ * Filter parameters
+ */
+export type FilterParams = Record<string, string | number | FilterCondition>;
+/**
+ * Sort field (with optional '-' prefix for descending)
+ */
+export type SortField = string;
+/**
+ * Pagination options
+ */
+export interface PaginationOptions {
+    offset?: number;
+    limit?: number;
+}
+/**
+ * Sparse fieldset options
+ */
+export type SparseFieldsetOptions = Record<string, string[]>;
+/**
+ * Relationship format for create/update
+ */
+export interface RelationshipInput {
+    type: string;
+    id: string;
+}
+/**
+ * Relationships for create/update
+ */
+export type RelationshipsInput = Record<string, RelationshipInput | RelationshipInput[]>;
+/**
+ * Options for list() method
+ */
+export interface ListOptions {
+    filters?: FilterParams;
+    sort?: SortField[];
+    pagination?: PaginationOptions;
+    include?: string[];
+    fields?: SparseFieldsetOptions;
+}
+/**
+ * Options for get() method
+ */
+export interface GetOptions {
+    include?: string[];
+    fields?: SparseFieldsetOptions;
+}
+/**
+ * Options for create() method
+ */
+export interface CreateOptions {
+    relationships?: RelationshipsInput;
+    resourceType?: string;
+}
+/**
+ * Options for update() method
+ */
+export interface UpdateOptions {
+    relationships?: RelationshipsInput;
+    resourceType?: string;
+}
+/**
+ * SSIProjectApi - JSON:API Client for Project Entities
+ */
+export declare class SSIProjectApi {
+    private baseUrl;
+    private apiBasePath;
+    private bearerToken;
+    private csrfToken;
+    private defaultHeaders;
+    /**
+     * 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: string, options?: {
+        apiBasePath?: string;
+        timeout?: number;
+    });
+    /**
+     * Sets the Bearer token for authentication.
+     *
+     * @param token - The Bearer token (OAuth/JWT).
+     */
+    setBearerToken(token: string): void;
+    /**
+     * Gets the current Bearer token.
+     *
+     * @returns The Bearer token, or null if not set.
+     */
+    getBearerToken(): string | null;
+    /**
+     * 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
+     */
+    private getCsrfToken;
+    /**
+     * 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(): void;
+    /**
+     * 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.
+     */
+    list(options?: ListOptions): Promise<JsonApiDocument>;
+    /**
+     * Retrieves a single project entity by UUID.
+     *
+     * The API endpoint is constructed as: baseUrl + apiBasePath + "/" + uuid
+     * Example: https://example.com/jsonapi/project/project/550e8400-e29b-41d4-a716-446655440000
+     *
+     * @param uuid - The UUID of the project entity (NOT the project 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., ['owner', 'tags'])
+     *   - 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.
+     */
+    get(uuid: string, options?: GetOptions): Promise<JsonApiDocument>;
+    /**
+     * 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.
+     */
+    create(attributes: Record<string, unknown>, options?: CreateOptions): Promise<JsonApiDocument>;
+    /**
+     * Updates an existing project entity.
+     *
+     * The API endpoint is constructed as: baseUrl + apiBasePath + "/" + uuid
+     * Example: https://example.com/jsonapi/project/project/550e8400-e29b-41d4-a716-446655440000
+     *
+     * @param uuid - The UUID of the project entity to update (NOT the project 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: 'project--project')
+     *
+     * @returns Promise resolving to the JSON:API document with the updated entity.
+     *
+     * @throws Error if the request fails or validation errors occur.
+     */
+    update(uuid: string, attributes: Record<string, unknown>, options?: UpdateOptions): Promise<JsonApiDocument>;
+    /**
+     * Deletes a project entity.
+     *
+     * The API endpoint is constructed as: baseUrl + apiBasePath + "/" + uuid
+     * Example: https://example.com/jsonapi/project/project/550e8400-e29b-41d4-a716-446655440000
+     *
+     * @param uuid - The UUID of the project entity to delete (NOT the project 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.
+     */
+    delete(uuid: string): Promise<boolean>;
+    /**
+     * 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
+     */
+    private request;
+    /**
+     * 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
+     */
+    private requestRaw;
+    /**
+     * Parses error response from JSON:API.
+     *
+     * @param response - The HTTP response.
+     *
+     * @returns Promise resolving to the error data.
+     *
+     * @private
+     */
+    private parseErrorResponse;
+    /**
+     * Parses error response from text string.
+     *
+     * @param text - The response text.
+     *
+     * @returns The error data, or null if parsing fails.
+     *
+     * @private
+     */
+    private parseErrorResponseFromText;
+    /**
+     * 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
+     */
+    private createError;
+    /**
+     * Builds filter query parameters from a filter object.
+     *
+     * @param filters - Filter conditions.
+     *
+     * @returns Query parameters for filters.
+     *
+     * @private
+     */
+    private buildFilterParams;
+    /**
+     * Formats relationships for JSON:API format.
+     *
+     * @param relationships - Relationships input.
+     *
+     * @returns Formatted relationships.
+     *
+     * @private
+     */
+    private formatRelationships;
+}