Merge pull request #15 from YoussefChahib/feat/add-blob-download-api

feat: Add file download support to ApiService

Author: ismailza

projects/ngx-api-client/src/lib/api.service.spec.ts

@@ -460,6 +460,38 @@ describe('ApiService', () => {
       req.flush(emptyPage());
     });
   });
+  
+  describe('file downloads', () => {
+    it('issues a GET and returns the file as a Blob', () => {
+      const blob = new Blob(['file content'], { type: 'application/pdf' });
+
+      api.download('/documents/001').subscribe();
+
+      const req = httpMock.expectOne(`${BASE_URL}/api/v1/documents/001`);
+
+      expect(req.request.method).toBe('GET');
+      expect(req.request.responseType).toBe('blob');
+
+      req.flush(blob);
+    });
+
+    it('issues a GET and returns the full HTTP response for a file download', () => {
+      const blob = new Blob(['file content'], { type: 'application/pdf' });
+
+      api.downloadResponse('/documents/001').subscribe();
+
+      const req = httpMock.expectOne(`${BASE_URL}/api/v1/documents/001`);
+
+      expect(req.request.method).toBe('GET');
+      expect(req.request.responseType).toBe('blob');
+
+      req.flush(blob, {
+        headers: {
+          'Content-Disposition': 'attachment; filename="document.pdf"',
+        },
+      });
+    });
+  });
 
   describe('loading state', () => {
     it('does not start until the caller subscribes', () => {

projects/ngx-api-client/src/lib/api.service.ts

@@ -1,4 +1,4 @@
-import { HttpClient, HttpContext, HttpHeaders, HttpParams } from '@angular/common/http';
+import { HttpClient, HttpContext, HttpHeaders, HttpParams, HttpResponse } from '@angular/common/http';
 import { inject, Injectable } from '@angular/core';
 import { defer, finalize, Observable } from 'rxjs';
 import { ApiLoadingService } from './api-loading.service';
@@ -99,6 +99,30 @@ export class ApiService {
   delete<T>(endpoint: string, options?: ApiRequestOptions): Observable<T> {
     return this.request<T>('DELETE', endpoint, null, options);
   }
+    
+  /**
+   * Downloads a binary file by performing a `GET` request to the specified API endpoint
+   * with optional request options.
+   *
+   * @param endpoint API endpoint (e.g. `'/resource/{id}'`).
+   * @param options Additional request options (query params, headers, etc.).
+   * @returns An `Observable` of the downloaded file as a `Blob`.
+   */
+  download(endpoint: string, options?: ApiRequestOptions): Observable<Blob> {
+    return this.request<Blob>('GET', endpoint, null, options, 'blob');
+  }
+
+  /**
+   * Downloads a binary file and returns the complete HTTP response, including
+   * response metadata such as headers and the filename from the `Content-Disposition` header.
+   *
+   * @param endpoint API endpoint (e.g. `'/resource/{id}'`).
+   * @param options Additional request options (query params, headers, etc.).
+   * @returns An `Observable` of the complete HTTP response containing the downloaded file as a `Blob`.
+   */
+  downloadResponse(endpoint: string, options?: ApiRequestOptions): Observable<HttpResponse<Blob>> {
+    return this.request<HttpResponse<Blob>>('GET', endpoint, null, options, 'blob', true);
+  }
 
   /**
    * Convenience method for paginated `GET` requests.
@@ -138,13 +162,16 @@ export class ApiService {
    * @param endpoint API endpoint (e.g. `'/resource'`).
    * @param body Request body (for POST, PUT, PATCH).
    * @param options Additional request options (query params, headers, flags for interceptors, etc.).
-   * @returns An `Observable` of the response body typed as `T`.
+   * @param observeResponse Whether to return the complete HTTP response, including headers and other metadata.
+   * @returns An `Observable` of the response typed as `T`.
    */
   private request<T>(
     method: string,
     endpoint: string,
     body: unknown,
     options?: ApiRequestOptions,
+    responseType: 'json' | 'blob' = 'json',
+    observeResponse = false,
   ): Observable<T> {
     const showLoader = options?.showLoader ?? this.defaultShowLoader;
 
@@ -157,12 +184,16 @@ export class ApiService {
         this.loadingService.start();
       }
 
-      return this.http.request<T>(method, url, {
+      const requestOptions = {
         body,
         params: this.buildParams(options, versioning),
         headers: this.buildHeaders(options, versioning),
         context,
-      });
+        responseType,
+        ...(observeResponse ? { observe: 'response' as const } : {}),
+      };
+
+      return this.http.request(method, url, requestOptions) as Observable<T>;
     }).pipe(
       finalize(() => {
         if (showLoader) {

website/docs/api/api-service.mdx

@@ -16,6 +16,8 @@ The single entry point for HTTP calls. Builds URLs from the configured
 `HttpContext` for interceptors, and tracks loading state.
 
 Every method returns an `Observable` of the **response body**, typed as `T`.
+Except for file download methods, they provide dedicated return types: `download()` returns a
+`Blob`, while `downloadResponse()` returns the complete `HttpResponse<Blob>`.
 Requests are created lazily — nothing is sent until you subscribe.
 
 ## `get`
@@ -63,6 +65,31 @@ delete<T>(endpoint: string, options?: ApiRequestOptions): Observable<T>
 this.api.delete<void>(`/orders/${id}`);
 ```
 
+```ts
+download(endpoint: string, options?: ApiRequestOptions): Observable<Blob>
+```
+
+Downloads a binary file and returns the response body as a `Blob`.
+
+```ts
+this.api.download('/documents/001');
+```
+
+## `downloadResponse`
+
+```ts
+downloadResponse(
+  endpoint: string,
+  options?: ApiRequestOptions,
+): Observable<HttpResponse<Blob>>
+```
+
+Downloads a binary file and returns the complete HTTP response, including response headers and metadata.
+
+```ts
+this.api.downloadResponse('/documents/001');
+```
+
 ## `getPage`
 
 ```ts