@rivinia/http 0.5.1 → 0.5.2

package/README.md

@@ -8,7 +8,7 @@ requests and reactive `httpResource` requests. It leaves URLs, backend
 contracts, and interceptors under app control. Response bodies pass through
 unchanged unless a request explicitly asks to unwrap one.
 
-- Prepared patch: **0.5.1** (latest published: **0.5.0**)
+- Package version: **0.5.2**
 - Requires Angular `^22.0.0` and RxJS `^6.5.3 || ^7.4.0`; `tslib` is installed
   as a dependency.
 
@@ -87,22 +87,30 @@ export const environment = {
 
 ```ts
 // src/app/trip.service.ts
-import { Injectable } from '@angular/core';
+import { Service } from '@angular/core';
+import type { HttpResponse } from '@angular/common/http';
 import { Observable } from 'rxjs';
 import { injectRiviniaHttp, joinUrl } from '@rivinia/http';
 import { environment } from '../environments/environment';
 
-interface Trip {
-  id: number;
+export interface Trip {
+  id: string;
   title: string;
+  departureDate: string;
+  status: 'planned' | 'booked' | 'cancelled';
 }
 
-interface CreateTrip {
+export interface TripDraft {
   title: string;
+  departureDate: string;
 }
 
-@Injectable({ providedIn: 'root' })
-export class TripService {
+interface ApiEnvelope<T> {
+  data: T;
+}
+
+@Service()
+export class TripApi {
   private readonly http = injectRiviniaHttp();
   private readonly tripsUrl = joinUrl(environment.apiUrl, 'trips');
 
@@ -114,33 +122,105 @@ export class TripService {
     });
   }
 
-  create(input: CreateTrip): Observable<Trip> {
-    return this.http.post<Trip>(this.tripsUrl, input, { unwrap: true, unwrapKey: 'data' });
+  get(id: string): Observable<Trip> {
+    return this.http.get<Trip>(joinUrl(this.tripsUrl, id), {
+      unwrap: true,
+      unwrapKey: 'data',
+    });
+  }
+
+  create(input: TripDraft): Observable<Trip> {
+    return this.http.post<Trip>(this.tripsUrl, input, {
+      unwrap: true,
+      unwrapKey: 'data',
+    });
+  }
+
+  replace(id: string, input: TripDraft): Observable<Trip> {
+    return this.http.put<Trip>(joinUrl(this.tripsUrl, id), input, {
+      unwrap: true,
+      unwrapKey: 'data',
+    });
+  }
+
+  updateStatus(id: string, status: Trip['status']): Observable<Trip> {
+    return this.http.patch<Trip>(
+      joinUrl(this.tripsUrl, id),
+      { status },
+      { unwrap: true, unwrapKey: 'data' },
+    );
+  }
+
+  cancel(id: string, reason: string): Observable<void> {
+    return this.http.delete<void>(joinUrl(this.tripsUrl, id), {
+      body: { reason },
+      unwrap: true,
+      unwrapKey: 'data',
+    });
+  }
+
+  downloadItinerary(id: string): Observable<Blob> {
+    return this.http.getBlob(joinUrl(this.tripsUrl, `${id}/itinerary`));
+  }
+
+  getOperatorNotes(id: string): Observable<string> {
+    return this.http.getText(joinUrl(this.tripsUrl, `${id}/operator-notes`));
+  }
+
+  listWithHeaders(): Observable<HttpResponse<ApiEnvelope<Trip[]>>> {
+    return this.http.getResponse<ApiEnvelope<Trip[]>>(this.tripsUrl, {
+      params: { page: 1 },
+    });
+  }
+
+  createAndReadLocation(input: TripDraft): Observable<HttpResponse<ApiEnvelope<Trip>>> {
+    return this.http.postResponse<ApiEnvelope<Trip>>(this.tripsUrl, input);
   }
 }
 ```
 
-Here the API is expected to respond with `{ "data": [...] }` for the list and
-`{ "data": { "id": 1, "title": "..." } }` for the create. `Observable<T>` is
-the compile-time type of the result; it does not validate the server payload.
-`joinUrl` removes one boundary slash and passes absolute `http://` or
-`https://` endpoints through unchanged. Use `params` for query values:
-`null` and `undefined` entries are omitted, while strings, numbers, and
-booleans are stringified.
-
-`get`, `post`, `put`, `patch`, and `delete` return typed `Observable`s.
-Mutation bodies are passed to Angular unchanged; `delete` accepts an optional
-`body` in its options:
+The JSON endpoints in this example return an object with a `data` field; the first five
+methods opt in to extracting that field. `getBlob()` downloads a binary file,
+and `getText()` reads plain text; neither method unwraps or checks JSON
+envelopes. `getResponse()` and `postResponse()` return the complete
+`HttpResponse` so the caller can inspect the status and headers; their body
+stays raw and is not unwrapped.
+
+| `RiviniaHttp` method | Used above for                                                     |
+| -------------------- | ------------------------------------------------------------------ |
+| `get`                | `list()` and `get(id)`                                             |
+| `post`               | `create(input)`                                                    |
+| `put`                | `replace(id, input)`                                               |
+| `patch`              | `updateStatus(id, status)`                                         |
+| `delete`             | `cancel(id, reason)`; its optional request body is passed through. |
+| `getBlob`            | `downloadItinerary(id)`                                            |
+| `getText`            | `getOperatorNotes(id)`                                             |
+| `getResponse`        | `listWithHeaders()`                                                |
+| `postResponse`       | `createAndReadLocation(input)`                                     |
+| `getResource`        | Reactive paginated list in `TripListComponent`.                    |
 
 ```ts
-this.http.delete<void>(joinUrl(environment.apiUrl, 'trips/1'), {
-  body: { reason: 'duplicate' },
+// Example use where the API returns pagination metadata in a header.
+this.api.listWithHeaders().subscribe((response) => {
+  const total = Number(response.headers.get('X-Total-Count') ?? 0);
+  console.log(response.status, total, response.body?.data);
+});
+
+// A create endpoint may return 201 plus a Location header.
+this.api.createAndReadLocation(input).subscribe((response) => {
+  const location = response.headers.get('Location');
+  console.log(response.status, location, response.body?.data);
 });
 ```
 
-The standard request options also pass `headers`, `HttpContext`, and
-`withCredentials` through to Angular's `HttpClient`. Use `HttpContext` with
-your own interceptors for app-specific controls such as opting out of auth.
+`Observable<T>` is the compile-time type of the result; it does not validate
+the server payload. `joinUrl` removes one boundary slash and passes absolute
+`http://` or `https://` endpoints through unchanged. Use `params` for query
+values: `null` and `undefined` entries are omitted, while strings, numbers,
+and booleans are stringified. The standard request options also pass
+`headers`, `HttpContext`, and `withCredentials` through to Angular's
+`HttpClient`. Use `HttpContext` with your own interceptors for app-specific
+controls such as opting out of auth.
 
 ## Reactive resources
 
@@ -155,24 +235,12 @@ import { Component, signal } from '@angular/core';
 import { injectRiviniaHttp, joinUrl } from '@rivinia/http';
 import { environment } from '../environments/environment';
 
-interface Trip {
-  id: number;
-  title: string;
-}
+import type { Trip } from './trip.service';
 
 @Component({
   selector: 'app-trip-list',
-  template: `
-    @if (trips.isLoading()) {
-      <p>Loading…</p>
-    } @else if (trips.hasValue()) {
-      @for (trip of trips.value(); track trip.id) {
-        <p>{{ trip.title }}</p>
-      }
-    } @else if (trips.error()) {
-      <p>Could not load trips.</p>
-    }
-  `,
+  standalone: true,
+  templateUrl: './trip-list.component.html',
 })
 export class TripListComponent {
   private readonly http = injectRiviniaHttp();
@@ -182,11 +250,31 @@ export class TripListComponent {
     unwrap: true,
     unwrapKey: 'data',
   });
+
+  nextPage(): void {
+    this.page.update((value) => value + 1);
+  }
+}
+```
+
+```html
+<!-- src/app/trip-list.component.html -->
+@if (trips.isLoading()) {
+<p>Loading trips…</p>
+} @else if (trips.hasValue()) {
+<ul>
+  @for (trip of trips.value(); track trip.id) {
+  <li>{{ trip.title }} — {{ trip.departureDate }} ({{ trip.status }})</li>
+  }
+</ul>
+} @else if (trips.error()) {
+<p role="alert">Could not load trips. Try again.</p>
 }
+<button type="button" (click)="nextPage()">Next page</button>
 ```
 
-In a real app, share the Trip model through a model module. `parse` is optional; when
-provided it runs after envelope validation and unwrapping, and can perform
+In a real app, share the Trip model through a model module. `parse` is optional;
+when provided it runs after envelope validation and unwrapping, and can perform
 runtime validation (for example with Zod or Valibot). A parse error, HTTP
 error, or library envelope error is exposed through `trips.error()`.
 `defaultValue` supplies a value while idle/loading. `reportProgress` is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rivinia/http",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Headless typed HTTP client for Angular: envelope unwrapping, plain Observables and httpResource.",
   "keywords": [
     "angular",