@limetech/lime-web-components 6.7.0 → 6.8.0

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## [6.8.0](https://github.com/Lundalogik/lime-web-components/compare/v6.7.0...v6.8.0) (2026-01-28)
+
+
+### Features
+
+
+* **problem:** add problem provider interfaces ([a4d003f](https://github.com/Lundalogik/lime-web-components/commit/a4d003f3a8665185c7ec7a99458ebf671d541641))
+
 ## [6.7.0](https://github.com/Lundalogik/lime-web-components/compare/v6.6.0...v6.7.0) (2026-01-14)
 
 

package/dist/eventdispatcher/eventdispatcher.d.ts

@@ -1,28 +1,94 @@
 /**
- * Service for handling application level events
+ * Service for application-wide event communication
+ *
+ * The {@link EventDispatcher} enables loosely-coupled communication between
+ * components through a publish-subscribe pattern.
+ *
+ * Components can dispatch custom events and subscribe to events from other
+ * components without direct coupling. This is particularly useful for:
+ * - Cross-component communication
+ * - Responding to platform-level events (navigation, data changes)
+ * - Notifying other components of state changes
+ *
+ * @example
+ * Basic usage
+ * ```typescript
+ * const eventDispatcher = platform.get(PlatformServiceName.EventDispatcher);
+ *
+ * // Dispatch an event
+ * eventDispatcher.dispatch('data-changed', { id: 123 });
+ *
+ * // Listen for events
+ * const handler = (event: CustomEvent<{ id: number }>) => {
+ *     console.log('Data changed:', event.detail.id);
+ * };
+ * eventDispatcher.addListener('data-changed', handler);
+ *
+ * // Clean up
+ * eventDispatcher.removeListener('data-changed', handler);
+ * ```
+ *
  * @public
  * @group Event dispatching
  */
 export interface EventDispatcher {
     /**
-     * Dispatch a new event
+     * Dispatch a custom event to all registered listeners
      *
-     * @param eventName - name of the event to dispatch
-     * @param data - data attached to the event
+     * Creates and dispatches a `CustomEvent` with the provided data. All components
+     * that have registered listeners for this event name will be notified.
+     *
+     * @param eventName - Unique name identifying the event type
+     * @param data - Data payload to include in the event's `detail` property
+     * @returns The `CustomEvent` that was dispatched
+     *
+     * @example
+     * ```typescript
+     * const eventDispatcher = platform.get(PlatformServiceName.EventDispatcher);
+     * eventDispatcher.dispatch('item-selected', { itemId: 42, name: 'Widget' });
+     * ```
      */
     dispatch<T>(eventName: string, data: T): CustomEvent<T>;
     /**
-     * Add a new listener for a specific event
+     * Register a listener for a specific event type
+     *
+     * The listener function will be called whenever an event with the matching
+     * name is dispatched. The same listener can be registered multiple times,
+     * but should typically be registered only once per component instance.
+     *
+     * **Important:** Always remove listeners in `disconnectedCallback()` to
+     * prevent memory leaks.
      *
-     * @param eventName - name of the event to listen to
-     * @param listener - listener to invoke when the event is dispatched
+     * @param eventName - Name of the event to listen for
+     * @param listener - Callback function to invoke when the event is dispatched
+     *
+     * @example
+     * ```typescript
+     * eventDispatcher.addListener('message-received', (event) => {
+     *     console.log('Message:', event.detail);
+     * });
+     * ```
      */
     addListener<T>(eventName: string, listener: (event: CustomEvent<T>) => void): void;
     /**
-     * Stop listening for a specific event
+     * Unregister a previously registered event listener
+     *
+     * Removes the specified listener function for the given event name. The
+     * listener reference must be the same function instance that was passed
+     * to {@link addListener}.
+     *
+     * Always call this in `disconnectedCallback()` to clean up listeners and
+     * prevent memory leaks.
+     *
+     * @param eventName - Name of the event to stop listening for
+     * @param listener - The exact listener function that was previously registered
      *
-     * @param eventName - name of the event to stop listening to
-     * @param listener - listener to remove from the dispatcher
+     * @example
+     * ```typescript
+     * const handler = (event: CustomEvent<string>) => console.log(event.detail);
+     * eventDispatcher.addListener('message-received', handler);
+     * eventDispatcher.removeListener('message-received', handler);
+     * ```
      */
     removeListener<T>(eventName: string, listener: (event: CustomEvent<T>) => void): void;
 }

package/dist/eventdispatcher/eventdispatcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"eventdispatcher.d.ts","sourceRoot":"","sources":["../../src/eventdispatcher/eventdispatcher.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;IAExD;;;;;OAKG;IACH,WAAW,CAAC,CAAC,EACT,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,GAC1C,IAAI,CAAC;IAER;;;;;OAKG;IACH,cAAc,CAAC,CAAC,EACZ,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,GAC1C,IAAI,CAAC;CACX"}
+{"version":3,"file":"eventdispatcher.d.ts","sourceRoot":"","sources":["../../src/eventdispatcher/eventdispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,WAAW,eAAe;IAC5B;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;IAExD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,WAAW,CAAC,CAAC,EACT,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,GAC1C,IAAI,CAAC;IAER;;;;;;;;;;;;;;;;;;;OAmBG;IACH,cAAc,CAAC,CAAC,EACZ,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,GAC1C,IAAI,CAAC;CACX"}

package/dist/filter/decorator.d.ts

@@ -9,10 +9,28 @@ export interface SelectFiltersOptions extends StateOptions {
     limetype?: string;
 }
 /**
- * Gets a list of filters
+ * Decorator that subscribes to filters from the {@link FilterRepository}.
+ *
+ * This decorator automatically updates the decorated property whenever filters
+ * change in the platform. You can optionally filter by limetype or filter ID.
+ *
+ * @param options - Configuration including limetype/ID filtering and state transformation via {@link SelectFiltersOptions}
+ * @returns A PropertyDecorator that sets up automatic subscription to filters
+ *
+ * @example
+ * ```typescript
+ * @State()
+ * @SelectFilters()
+ * private filters: Filter[];
+ * ```
+ *
+ * @example
+ * ```typescript
+ * @State()
+ * @SelectFilters({ limetype: 'company' })
+ * private companyFilters: Filter[];
+ * ```
  *
- * @param options - state decorator options
- * @returns state decorator
  * @public
  * @group Filters
  */

package/dist/filter/decorator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decorator.d.ts","sourceRoot":"","sources":["../../src/filter/decorator.ts"],"names":[],"mappings":"AAAA,OAAO,EAEH,YAAY,EAEf,MAAM,SAAS,CAAC;AAGjB;;;;GAIG;AACH,MAAM,WAAW,oBAAqB,SAAQ,YAAY;IACtD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CACzB,OAAO,GAAE,oBAAyB,GACnC,iBAAiB,CAMnB"}
+{"version":3,"file":"decorator.d.ts","sourceRoot":"","sources":["../../src/filter/decorator.ts"],"names":[],"mappings":"AAAA,OAAO,EAEH,YAAY,EAEf,MAAM,SAAS,CAAC;AAGjB;;;;GAIG;AACH,MAAM,WAAW,oBAAqB,SAAQ,YAAY;IACtD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,aAAa,CACzB,OAAO,GAAE,oBAAyB,GACnC,iBAAiB,CAMnB"}

package/dist/filter/repository.d.ts

@@ -1,22 +1,100 @@
 import { Filter } from '../query';
 import { StateRepository } from '../core';
 /**
+ * Repository for managing saved filter definitions.
+ *
+ * {@link FilterRepository} provides methods to create, update, and delete {@link Filter}
+ * definitions. Filters are named, reusable query expressions that can be applied to
+ * limetypes to define subsets of objects (e.g., "My Active Deals", "High Priority Tickets").
+ *
+ * Filters can be:
+ * - System-wide (available to all users)
+ * - User-specific (private to a single user when `iduser` is set)
+ * - Referenced in {@link InFilterExpression}s for advanced queries
+ *
+ * The repository extends {@link StateRepository}, enabling:
+ * - Reactive subscriptions to filter changes
+ * - Automatic UI updates when filters are created or deleted
+ * - Integration with state decorators
+ *
+ * @example
+ * Basic usage
+ * ```typescript
+ * const repo = platform.get(PlatformServiceName.FilterRepository);
+ *
+ * const filter: Filter = {
+ *     id: 'high_value_deals',
+ *     limetype: 'deal',
+ *     name: { 'en': 'High Value Deals' },
+ *     filter: {
+ *         op: Operator.AND,
+ *         exp: [
+ *             { key: 'status', op: Operator.EQUALS, exp: 'active' },
+ *             { key: 'value', op: Operator.GREATER_OR_EQUAL, exp: 100000 }
+ *         ]
+ *     }
+ * };
+ *
+ * await repo.save(filter);
+ * ```
+ *
  * @public
  * @group Filters
+ * @see {@link Filter} for filter definition structure
+ * @see {@link Expression} for building filter expressions
+ * @see {@link InFilterExpression} for referencing filters in queries
+ * @see {@link StateRepository} for subscription patterns
  */
 export interface FilterRepository extends StateRepository {
     /**
-     * Saves the new filter to the database
+     * Save a filter definition to the database.
      *
-     * @param filter - a filter to save
-     * @returns a promise that will be resolved when the filter is saved
+     * Creates a new filter or updates an existing one. The filter will be stored
+     * persistently and become available for use in queries and filter expressions.
+     *
+     * If a filter with the same `id` already exists, it will be updated with the
+     * new values. Otherwise, a new filter is created.
+     *
+     * @param filter - The {@link Filter} definition to save
+     * @returns Promise that resolves when the filter is saved
+     * @throws Error if save fails due to validation or permission issues
+     *
+     * @example
+     * ```typescript
+     * const repo = platform.get(PlatformServiceName.FilterRepository);
+     *
+     * const filter: Filter = {
+     *     id: 'my_deals',
+     *     limetype: 'deal',
+     *     name: { 'en': 'My Deals' },
+     *     filter: { key: 'owner', op: Operator.EQUALS, exp: currentUserId }
+     * };
+     *
+     * await repo.save(filter);
+     * ```
+     *
+     * @see {@link Filter} for the filter structure
+     * @see {@link Expression} for building filter expressions
+     * @see {@link delete} to remove a filter
      */
     save(filter: Filter): Promise<void>;
     /**
-     * Deletes the filter
+     * Delete a filter from the database.
+     *
+     * Permanently removes the specified filter. This operation cannot be undone.
+     *
+     * @param filter - The {@link Filter} to delete
+     * @returns Promise that resolves when the filter is deleted
+     * @throws Error if deletion fails due to permissions or other issues
+     *
+     * @example
+     * ```typescript
+     * const repo = platform.get(PlatformServiceName.FilterRepository);
+     * await repo.delete(filter);
+     * ```
      *
-     * @param filter - a filter to delete
-     * @returns a promise that will be resolved when the filter is deleted
+     * @see {@link Filter} for the filter structure
+     * @see {@link save} to create or update a filter
      */
     delete(filter: Filter): Promise<void>;
 }

package/dist/filter/repository.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../src/filter/repository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE1C;;;GAGG;AACH,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACrD;;;;;OAKG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC"}
+{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../src/filter/repository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpC;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC"}

package/dist/http/http.d.ts

@@ -1,76 +1,227 @@
 /**
- * HTTP service for sending requests to a given URL
+ * HTTP service for sending requests to backend endpoints
  *
- * By default, the service will work with the JSON data format. If anything but JSON is returned from the endpoint,
- * the `responseType` property in the `options` parameter needs to be set.
+ * The {@link HttpClient} is the primary interface for making HTTP requests
+ * within the Lime platform.
+ *
+ * By default, all requests expect JSON responses. For other content types
+ * (text, binary data, etc.), set the `responseType` in {@link HttpOptions}.
+ *
+ * All methods throw {@link HttpResponseError} on HTTP errors (4xx, 5xx status codes).
+ *
+ * @example
+ * Basic GET request for JSON data
+ * ```typescript
+ * const http = platform.get(PlatformServiceName.Http);
+ * const data = await http.get('my_addon/endpoint');
+ * console.log(data);
+ * ```
+ *
+ * @example
+ * POST request with data and query parameters
+ * ```typescript
+ * const http = platform.get(PlatformServiceName.Http);
+ * const response = await http.post(
+ *     'my_addon/users',
+ *     { name: 'John Doe', email: 'john@example.com' },
+ *     { params: { notify: 'true' } }
+ * );
+ * ```
+ *
+ * @example
+ * Error handling with HttpResponseError
+ * ```typescript
+ * const http = platform.get(PlatformServiceName.Http);
+ * try {
+ *     const data = await http.get('my_addon/endpoint');
+ * } catch (error) {
+ *     if (error.name === 'HttpResponseError') {
+ *         console.error(`HTTP ${error.status}: ${error.message}`);
+ *         console.error('Response:', error.response);
+ *     }
+ * }
+ * ```
+ *
+ * @example
+ * Downloading a file as blob
+ * ```typescript
+ * const http = platform.get(PlatformServiceName.Http);
+ * const blob = await http.get('my_addon/download/report.pdf', {
+ *     responseType: 'blob'
+ * });
+ * const url = URL.createObjectURL(blob);
+ * window.open(url);
+ * ```
  *
  * @public
  * @group HTTP
  */
 export interface HttpClient {
     /**
-     * Sends a get request.
+     * Sends a GET request to retrieve data from the server
      *
-     * @param url - Url to resource (for instance my_addon/endpoint).
-     * @param options - The HTTP options to send with the request.
-     * @returns
+     * @param url - Relative URL to the resource (e.g., 'my_addon/endpoint').
+     * The URL is relative to the Lime CRM base URL.
+     * @param options - Optional {@link HttpOptions} for query parameters, headers, or response type
+     * @returns Promise resolving to the response data. Type depends on {@link HttpOptions.responseType}
+     *
+     * @throws {@link HttpResponseError} when the server responds with an error status (4xx, 5xx)
+     *
+     * @example
+     * ```typescript
+     * const http = platform.get(PlatformServiceName.Http);
+     * const users = await http.get('my_addon/users', {
+     *     params: { active: 'true', limit: '10' }
+     * });
+     * ```
      */
     get(url: string, options?: HttpOptions): Promise<any>;
     /**
-     * Sends a post request.
+     * Sends a POST request to create new data on the server
+     *
+     * @param url - Relative URL to the resource (e.g., 'my_addon/endpoint')
+     * @param data - Payload to send in the request body. Will be JSON-encoded by default.
+     * @param options - Optional {@link HttpOptions} for query parameters, headers, or response type
+     * @returns Promise resolving to the response data. Type depends on {@link HttpOptions.responseType}
      *
-     * @param url - Url to resource (for instance my_addon/endpoint).
-     * @param data - Payload to send to the server.
-     * @param options - The HTTP options to send with the request.
-     * @returns
+     * @throws {@link HttpResponseError} when the server responds with an error status (4xx, 5xx)
+     *
+     * @example
+     * ```typescript
+     * const http = platform.get(PlatformServiceName.Http);
+     * const newUser = await http.post('my_addon/users', {
+     *     name: 'Jane Smith',
+     *     email: 'jane@example.com'
+     * });
+     * ```
      */
     post(url: string, data?: object, options?: HttpOptions): Promise<any>;
     /**
-     * Sends a patch request.
+     * Sends a PATCH request to partially update existing data on the server
+     *
+     * @param url - Relative URL to the resource (e.g., 'my_addon/users/123')
+     * @param data - Partial payload containing only the fields to update
+     * @param options - Optional {@link HttpOptions} for query parameters, headers, or response type
+     * @returns Promise resolving to the response data. Type depends on {@link HttpOptions.responseType}
      *
-     * @param url - Url to resource (for instance my_addon/endpoint).
-     * @param data - Payload to send to the server.
-     * @param options - The HTTP options to send with the request.
-     * @returns
+     * @throws {@link HttpResponseError} when the server responds with an error status (4xx, 5xx)
+     *
+     * @example
+     * ```typescript
+     * const http = platform.get(PlatformServiceName.Http);
+     * await http.patch('my_addon/users/123', {
+     *     email: 'newemail@example.com'
+     * });
+     * ```
      */
     patch(url: string, data?: object, options?: HttpOptions): Promise<any>;
     /**
-     * Sends a put request.
+     * Sends a PUT request to replace existing data on the server
+     *
+     * @param url - Relative URL to the resource (e.g., 'my_addon/users/123')
+     * @param data - Complete payload to replace the existing resource
+     * @param options - Optional {@link HttpOptions} for query parameters, headers, or response type
+     * @returns Promise resolving to the response data. Type depends on {@link HttpOptions.responseType}
+     *
+     * @throws {@link HttpResponseError} when the server responds with an error status (4xx, 5xx)
      *
-     * @param url - Url to resource (for instance my_addon/endpoint).
-     * @param data - Payload to send to the server.
-     * @param options - The HTTP options to send with the request.
-     * @returns
+     * @example
+     * ```typescript
+     * const http = platform.get(PlatformServiceName.Http);
+     * await http.put('my_addon/users/123', {
+     *     name: 'Jane Doe',
+     *     email: 'jane@example.com',
+     *     role: 'admin'
+     * });
+     * ```
      */
     put(url: string, data?: object, options?: HttpOptions): Promise<any>;
     /**
-     * Sends a delete request.
+     * Sends a DELETE request to remove data from the server
+     *
+     * @param url - Relative URL to the resource (e.g., 'my_addon/users/123')
+     * @param options - Optional {@link HttpOptions} for query parameters or headers
+     * @returns Promise resolving to the response data. Type depends on {@link HttpOptions.responseType}
+     *
+     * @throws {@link HttpResponseError} when the server responds with an error status (4xx, 5xx)
      *
-     * @param url - Url to resource (for instance my_addon/endpoint).
-     * @param options - The HTTP options to send with the request.
-     * @returns
+     * @example
+     * ```typescript
+     * const http = platform.get(PlatformServiceName.Http);
+     * await http.delete('my_addon/users/123');
+     * ```
      */
     delete(url: string, options?: HttpOptions): Promise<any>;
 }
 /**
+ * Configuration options for HTTP requests
+ *
+ * @example
+ * ```typescript
+ * const http = platform.get(PlatformServiceName.Http);
+ * const options: HttpOptions = {
+ *     params: { search: 'John', limit: '10' },
+ *     headers: { 'X-Custom-Header': 'value' },
+ *     responseType: 'json'
+ * };
+ * const data = await http.get('my_addon/users', options);
+ * ```
+ *
  * @public
  * @group HTTP
  */
 export interface HttpOptions {
     /**
-     * Query parameters to include in the request
+     * Query parameters to append to the URL
+     *
+     * Parameters will be URL-encoded and appended to the request URL.
+     *
+     * @example
+     * ```typescript
+     * // Results in: my_addon/users?active=true&role=admin&role=user
+     * const params = {
+     *     active: 'true',
+     *     role: ['admin', 'user']
+     * };
+     * ```
      */
     params?: HttpParams;
     /**
-     * Additional HTTP-headers to send in the request
+     * Additional HTTP headers to include in the request
+     *
+     * @example
+     * ```typescript
+     * const headers = {
+     *     'Authorization': 'Bearer token123',
+     *     'Accept-Language': 'en-US'
+     * };
+     * ```
      */
     headers?: HttpHeaders;
     /**
-     * Type of the response that is returned. Defaults to `json`
+     * Expected response data type. Defaults to 'json'
+     *
+     * - `json`: Parse response as JSON (default)
+     * - `text`: Get response as plain text string
+     * - `blob`: Get response as binary Blob (for file downloads)
+     * - `arraybuffer`: Get response as ArrayBuffer (for binary data processing)
+     *
+     * @example
+     * ```typescript
+     * // Download PDF file
+     * const pdfBlob = await http.get('my_addon/report.pdf', {
+     *     responseType: 'blob'
+     * });
+     * ```
      */
     responseType?: HttpResponseType;
 }
 /**
+ * URL query parameters for HTTP requests
+ *
+ * Key-value pairs that will be appended to the request URL as query string.
+ * Array values will be repeated for the same parameter name.
+ *
  * @public
  * @group HTTP
  */
@@ -78,6 +229,11 @@ export interface HttpParams {
     [param: string]: string | string[];
 }
 /**
+ * HTTP headers for requests
+ *
+ * Custom headers to include in the HTTP request. Array values will be
+ * joined as comma-separated values for the same header name.
+ *
  * @public
  * @group HTTP
  */
@@ -85,15 +241,33 @@ export interface HttpHeaders {
     [header: string]: string | string[];
 }
 /**
+ * Response data type for HTTP requests
+ *
+ * Determines how the response body will be parsed and returned.
+ *
  * @public
  * @group HTTP
  */
 export type HttpResponseType = 'text' | 'json' | 'arraybuffer' | 'blob';
 /**
- * Defines the HTTP methods as constants.
- * Used in the UploadFile class in lime-crm-components
+ * HTTP method constants
+ *
+ * Standard HTTP methods as constant values. Useful for type-safe method
+ * selection in custom HTTP utilities.
+ *
+ * @example
+ * ```typescript
+ * function makeRequest(method: HttpMethod, url: string) {
+ *     if (method === HttpMethod.Get) {
+ *         // Handle GET request
+ *     }
+ * }
+ *
+ * makeRequest(HttpMethod.Post, 'my_addon/endpoint');
+ * ```
  *
  * @public
+ * @group HTTP
  */
 export declare const HttpMethod: {
     readonly Get: "GET";
@@ -103,26 +277,59 @@ export declare const HttpMethod: {
     readonly Patch: "PATCH";
 };
 /**
- * Type definition for HTTP methods. It can be any of the values defined in the
- * HttpMethod constant.
+ * Type definition for HTTP methods
+ *
+ * Union type of all values in the {@link HttpMethod} constant.
  *
  * @public
+ * @group HTTP
  */
 export type HttpMethod = (typeof HttpMethod)[keyof typeof HttpMethod];
 /**
- * Exception thrown by {@link HttpClient} when an error occurs while sending a
- * request
+ * Error thrown when an HTTP request fails
+ *
+ * This error is thrown by {@link HttpClient} methods when the server responds
+ * with an error status code (4xx or 5xx).
+ *
+ * @example
+ * ```typescript
+ * const http = platform.get(PlatformServiceName.Http);
+ *
+ * try {
+ *     const data = await http.get('my_addon/data');
+ * } catch (error) {
+ *     if (error.name !== 'HttpResponseError') {
+ *         throw error;
+ *     }
+ *
+ *     if (error.status === 404) {
+ *         console.error('Resource not found');
+ *     } else if (error.status >= 500) {
+ *         console.error('Server error:', error.status);
+ *     }
+ *
+ *     const body = await error.response.text();
+ *     console.error('Response body:', body);
+ * }
+ * ```
  *
  * @public
+ * @group HTTP
  */
 export interface HttpResponseError extends Error {
     name: 'HttpResponseError';
     /**
-     * Http status code
+     * HTTP status code from the failed response
      */
     status: number;
     /**
-     * The response from the request
+     * The full Response object from the failed request
+     *
+     * Use this to access response headers or read the response body:
+     * ```typescript
+     * const body = await error.response.text();
+     * const contentType = error.response.headers.get('content-type');
+     * ```
      */
     response: Response;
 }

package/dist/http/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/http/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACvB;;;;;;OAMG;IAEH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAEtD;;;;;;;OAOG;IAEH,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAEtE;;;;;;;OAOG;IAEH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAEvE;;;;;;;OAOG;IAEH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAErE;;;;;;OAMG;IAEH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;CAC5D;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IACxB;;OAEG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC;IAEpB;;OAEG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;OAEG;IACH,YAAY,CAAC,EAAE,gBAAgB,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACvB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC;CACtC;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IACxB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC;CACvC;AAED;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,aAAa,GAAG,MAAM,CAAC;AAExE;;;;;GAKG;AACH,eAAO,MAAM,UAAU;;;;;;CAMb,CAAC;AAEX;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,OAAO,UAAU,CAAC,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,WAAW,iBAAkB,SAAQ,KAAK;IAC5C,IAAI,EAAE,mBAAmB,CAAC;IAC1B;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,QAAQ,EAAE,QAAQ,CAAC;CACtB"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/http/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,MAAM,WAAW,UAAU;IACvB;;;;;;;;;;;;;;;;;OAiBG;IAEH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAEtD;;;;;;;;;;;;;;;;;;OAkBG;IAEH,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAEtE;;;;;;;;;;;;;;;;;OAiBG;IAEH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAEvE;;;;;;;;;;;;;;;;;;;OAmBG;IAEH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAErE;;;;;;;;;;;;;;OAcG;IAEH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;CAC5D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,WAAW;IACxB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC;IAEpB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CAAC,EAAE,gBAAgB,CAAC;CACnC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACvB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC;CACtC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IACxB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC;CACvC;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,aAAa,GAAG,MAAM,CAAC;AAExE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,UAAU;;;;;;CAMb,CAAC;AAEX;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,OAAO,UAAU,CAAC,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,iBAAkB,SAAQ,KAAK;IAC5C,IAAI,EAAE,mBAAmB,CAAC;IAE1B;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;;;;;OAQG;IACH,QAAQ,EAAE,QAAQ,CAAC;CACtB"}