@rivinia/http 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,135 @@
-# Temporary Holding Version
+# @rivinia/http
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/@rivinia/http.svg)](https://www.npmjs.com/package/@rivinia/http)
+[![license](https://img.shields.io/npm/l/@rivinia/http.svg)](https://www.npmjs.com/package/@rivinia/http)
+
+Headless typed HTTP client for Angular 22+. Configurable envelope
+unwrapping, plain Observables **and** `httpResource` — URLs always used as
+given, zero styling, zero backend opinions, interceptors left to your app.
+
+- Version: **0.2.0**
+- Requires: **Angular `^22.0.0`**, `rxjs` (same range Angular uses), `tslib`
+- Since Angular 21 `HttpClient` (fetch backend) is injectable with zero setup.
+  Call `provideHttpClient()` / pass `httpFeatures` only when you configure
+  interceptors or other backend features.
+
+## Install
+
+```bash
+npm install @rivinia/http
+ng add @rivinia/http   # interactive: asks about unwrapping + key, then wires app.config.ts
+```
+
+## Quick start — pick ONE backend style
+
+```ts
+// app.config.ts — style A: nothing to configure (Angular ≥21 default)
+providers: [provideRiviniaHttp()];
+
+// style B: single call with interceptors (do NOT also call provideHttpClient)
+providers: [provideRiviniaHttp({ httpFeatures: [withInterceptors([authInterceptor])] })];
+
+// style C: explicit backend config, like the official setup guide
+providers: [provideHttpClient(withInterceptors([authInterceptor])), provideRiviniaHttp()];
+```
+
+## URLs: yours, always
+
+The library never joins, prefixes, or rewrites URLs. Compose them at the
+call site from wherever you want — typically your environment files
+(the BRT pattern):
+
+```ts
+// src/environments/environment.ts / environment.prod.ts
+export const environment = { apiUrl: 'https://api.example.com' };
+
+// feature service
+import { joinUrl } from '@rivinia/http';
+
+export class TripService {
+  private api = injectRiviniaHttp();
+  private url = (path: string) => joinUrl(environment.apiUrl, path);
+
+  list = () => this.api.get<Trip[]>(this.url('trips'));
+  create = (dto: CreateTrip) => this.api.post<Trip>(this.url('trips'), dto);
+}
+
+// Reactive resource (auto refetch, loading/error signals)
+export class TripPage {
+  page = signal(1);
+  trips = this.api.getResource<Trip[]>(() => this.url(`trips?page=${this.page()}`));
+}
+```
+
+```html
+@if (trips.hasValue()) {
+  @for (t of trips.value(); track t.id) { <p>{{ t.title }}</p> }
+} @else if (trips.isLoading()) {
+  <p>Loading…</p>
+}
+```
+
+## Envelope unwrapping (opt-in, default off)
+
+The library assumes nothing about your backend: responses pass through raw
+unless unwrapping is enabled. Backends that wrap payloads
+(`{ data, error, isSuccess }`) opt in globally or per call:
+
+```ts
+provideRiviniaHttp({ unwrap: true });                               // whole app, 'data' key
+provideRiviniaHttp({ unwrap: true, unwrapKey: 'result' });          // whole app, custom key
+this.api.get<Legacy>(url, { unwrap: true, unwrapKey: 'result' });   // this call only
+this.api.get<Raw>(url);                                             // raw body (default)
+```
+
+NOTE: a key alone never enables unwrapping — only `unwrap: true` does,
+at either level. Different shapes per API in the same app:
+
+```ts
+export class MixedService {
+  private api = injectRiviniaHttp();
+
+  // main backend: { data: … } (global unwrap: true applies, nothing to say)
+  trips = () => this.api.get<Trip[]>(fullUrl('trips'));
+
+  // legacy backend: { result: … } (per-call key, unwrapping already on globally)
+  legacy = () => this.api.get<Old[]>(fullUrl('old'), { unwrapKey: 'result' });
+
+  // webhook endpoint: raw body despite the enabled global (per-call kill-switch)
+  ping = () => this.api.get<string>(fullUrl('ping'), { unwrap: false });
+}
+```
+
+`getResource` applies the same rules through `parse` (your own `parse` runs
+after unwrapping — ideal for Zod/Valibot validation).
+
+## API
+
+| Export | Kind | Purpose |
+|---|---|---|
+| `provideRiviniaHttp(config?)` | provider | `{ unwrap?=false, unwrapKey?='data', httpFeatures? }` |
+| `RiviniaHttp` | `@Service()` | `get/post/put/patch/delete`, `getBlob`, `getResource` |
+| `injectRiviniaHttp()` | function | shorthand for `inject(RiviniaHttp)` |
+| `joinUrl(base, endpoint)` | util | slash-safe join; absolute URLs pass through |
+| `unwrapAs(body, key)` | util | recursive envelope extraction |
+| types | types | `RiviniaHttpConfig`, `RiviniaRequestOptions`, `RiviniaDeleteOptions`, `RiviniaResourceOptions`, `QueryParamsInput` |
+
+`getBlob` is never unwrapped. `HttpContext` passes through untouched, so
+app interceptors (auth opt-out, error toasts) keep working. For caching,
+polling, retry and TanStack Query interop see [RECIPES.md](./RECIPES.md).
+
+## Testing your app code
+
+Standard Angular tooling — nothing custom to learn:
+
+```ts
+TestBed.configureTestingModule({
+  providers: [provideHttpClient(), provideHttpClientTesting(), provideRiviniaHttp()],
+});
+api.get('https://api.test/users').subscribe();
+TestBed.inject(HttpTestingController).expectOne('https://api.test/users').flush({ data: [] });
+```
+
+## License
+
+MIT.

package/fesm2022/rivinia-http.mjs

@@ -0,0 +1,148 @@
+import * as i0 from "@angular/core";
+import { InjectionToken, Service, inject, makeEnvironmentProviders } from "@angular/core";
+import { HttpClient, HttpContext, HttpParams, httpResource, provideHttpClient } from "@angular/common/http";
+import { map } from "rxjs";
+function joinUrl(baseUrl, endpoint) {
+	if (/^https?:\/\//i.test(endpoint)) return endpoint;
+	const base = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+	const path = endpoint.startsWith("/") ? endpoint.slice(1) : endpoint;
+	return path ? `${base}/${path}` : base;
+}
+function unwrapAs(body, key) {
+	if (isObjectRecord(body) && hasOwn(body, key)) return unwrapAs(body[key], key);
+	return body;
+}
+function isObjectRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasOwn(obj, key) {
+	return Object.prototype.hasOwnProperty.call(obj, key);
+}
+const RIVINIA_HTTP_CONFIG = new InjectionToken("RIVINIA_HTTP_CONFIG");
+var RiviniaHttp = class RiviniaHttp {
+	http = inject(HttpClient);
+	config = inject(RIVINIA_HTTP_CONFIG, { optional: true });
+	get(endpoint, options) {
+		return this.http.get(this.url(endpoint), this.httpOptions(options)).pipe(map((body) => this.applyUnwrap(body, options)));
+	}
+	post(endpoint, body, options) {
+		return this.http.post(this.url(endpoint), body, this.httpOptions(options)).pipe(map((res) => this.applyUnwrap(res, options)));
+	}
+	put(endpoint, body, options) {
+		return this.http.put(this.url(endpoint), body, this.httpOptions(options)).pipe(map((res) => this.applyUnwrap(res, options)));
+	}
+	patch(endpoint, body, options) {
+		return this.http.patch(this.url(endpoint), body, this.httpOptions(options)).pipe(map((res) => this.applyUnwrap(res, options)));
+	}
+	delete(endpoint, options) {
+		return this.http.delete(this.url(endpoint), {
+			...this.httpOptions(options),
+			body: options?.body
+		}).pipe(map((res) => this.applyUnwrap(res, options)));
+	}
+	getBlob(endpoint, options) {
+		return this.http.get(this.url(endpoint), {
+			...this.httpOptions(options),
+			responseType: "blob"
+		});
+	}
+	getResource(endpoint, options) {
+		const { defaultValue, parse, reportProgress, ...requestOptions } = options ?? {};
+		const request = () => {
+			const ep = typeof endpoint === "string" ? endpoint : endpoint();
+			if (ep === void 0) return void 0;
+			return {
+				url: this.url(ep),
+				params: this.toParams(requestOptions.params),
+				headers: requestOptions.headers,
+				context: requestOptions.context,
+				withCredentials: requestOptions.withCredentials,
+				...reportProgress !== void 0 ? { reportProgress } : {}
+			};
+		};
+		const unwrapKey = this.resolveKey(requestOptions);
+		const unwrapEnabled = this.resolveUnwrap(requestOptions);
+		const base = { defaultValue };
+		if (unwrapEnabled) {
+			const applyParse = (raw) => parse ? parse(unwrapAs(raw, unwrapKey)) : unwrapAs(raw, unwrapKey);
+			return defaultValue === void 0 ? httpResource(request, {
+				...base,
+				parse: applyParse
+			}) : httpResource(request, {
+				...base,
+				defaultValue,
+				parse: applyParse
+			});
+		}
+		return defaultValue === void 0 ? httpResource(request, {
+			...base,
+			...parse ? { parse } : {}
+		}) : httpResource(request, {
+			...base,
+			defaultValue,
+			...parse ? { parse } : {}
+		});
+	}
+	url(endpoint) {
+		return endpoint;
+	}
+	resolveUnwrap(options) {
+		return options?.unwrap ?? this.config?.unwrap ?? false;
+	}
+	resolveKey(options) {
+		return options?.unwrapKey ?? this.config?.unwrapKey ?? "data";
+	}
+	applyUnwrap(body, options) {
+		if (!this.resolveUnwrap(options)) return body;
+		return unwrapAs(body, this.resolveKey(options));
+	}
+	httpOptions(options) {
+		return {
+			params: this.toParams(options?.params),
+			headers: options?.headers,
+			context: options?.context ?? new HttpContext(),
+			withCredentials: options?.withCredentials
+		};
+	}
+	toParams(input) {
+		if (!input) return void 0;
+		if (input instanceof HttpParams) return input;
+		let params = new HttpParams();
+		for (const [key, value] of Object.entries(input)) if (value !== void 0 && value !== null) params = params.set(key, String(value));
+		return params;
+	}
+	static ɵfac = i0.ɵɵngDeclareFactory({
+		minVersion: "12.0.0",
+		version: "22.2.2",
+		ngImport: i0,
+		type: RiviniaHttp,
+		deps: [],
+		target: i0.ɵɵFactoryTarget.Service
+	});
+	static ɵprov = i0.ɵɵngDeclareService({
+		minVersion: "22.0.0",
+		version: "22.2.2",
+		ngImport: i0,
+		type: RiviniaHttp
+	});
+};
+i0.ɵɵngDeclareClassMetadata({
+	minVersion: "12.0.0",
+	version: "22.2.2",
+	ngImport: i0,
+	type: RiviniaHttp,
+	decorators: [{ type: Service }]
+});
+function provideRiviniaHttp(config = {}) {
+	const { httpFeatures, ...rest } = config;
+	return makeEnvironmentProviders([...httpFeatures ? [provideHttpClient(...httpFeatures)] : [], {
+		provide: RIVINIA_HTTP_CONFIG,
+		useValue: rest
+	}]);
+}
+function injectRiviniaHttp() {
+	return inject(RiviniaHttp);
+}
+export { RiviniaHttp, injectRiviniaHttp, joinUrl, provideRiviniaHttp, unwrapAs };
+
+//# sourceMappingURL=rivinia-http.mjs.map

package/fesm2022/rivinia-http.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"rivinia-http.mjs","names":[],"sources":["../../../projects/http/src/lib/http-utils.ts","../../../projects/http/src/lib/http-config.ts","../../../projects/http/src/lib/rivinia-http.ts","../../../projects/http/src/lib/provide-http.ts"],"sourcesContent":["/**\n * Joins a base URL and an endpoint without producing double slashes.\n * Absolute `http(s)` endpoints pass through untouched.\n */\nexport function joinUrl(baseUrl: string, endpoint: string): string {\n  if (/^https?:\\/\\//i.test(endpoint)) {\n    return endpoint;\n  }\n  const base = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;\n  const path = endpoint.startsWith('/') ? endpoint.slice(1) : endpoint;\n  return path ? `${base}/${path}` : base;\n}\n\n/**\n * Extracts `body[key]` when the backend wraps payloads in an envelope\n * (e.g. `{ data, error, isSuccess }`); passes anything else through\n * unchanged. Recursive, so nested envelopes collapse.\n */\nexport function unwrapAs<T>(body: unknown, key: string): T {\n  if (isObjectRecord(body) && hasOwn(body, key)) {\n    return unwrapAs<T>(body[key], key);\n  }\n  return body as T;\n}\n\nfunction isObjectRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nfunction hasOwn(obj: Record<string, unknown>, key: string): boolean {\n  return Object.prototype.hasOwnProperty.call(obj, key);\n}\n","import type { HttpFeature, HttpFeatureKind } from '@angular/common/http';\nimport { InjectionToken } from '@angular/core';\n\n/**\n * Global configuration for `@rivinia/http`.\n *\n * Every field is optional and can be overridden per request.\n * URLs are ALWAYS used as given — the library never joins, prefixes, or\n * rewrites them. Build them at the call site from wherever you want\n * (`environment.apiUrl`, a constant, a signal …) with the exported `joinUrl`.\n */\nexport interface RiviniaHttpConfig {\n  /**\n   * Unwrap `{ [unwrapKey]: payload }` envelopes by default.\n   * @default false — the library assumes nothing about your backend;\n   * opt in globally here or per call with `{ unwrap: true }`.\n   */\n  unwrap?: boolean;\n  /**\n   * Envelope key unwrapped when `unwrap` is enabled.\n   * @default 'data'\n   */\n  unwrapKey?: string;\n  /**\n   * Optional `HttpClient` features (`withInterceptors(...)`, `withXhr()`, …),\n   * applied via a single internal `provideHttpClient(...httpFeatures)` call.\n   *\n   * Use this INSTEAD of calling `provideHttpClient()` yourself — calling both\n   * registers the built-in XSRF interceptor twice (verified against Angular\n   * 22.2.2 source: `xsrfInterceptorFn` is a multi-provider with no cross-call\n   * dedup). Omit it entirely on Angular ≥21 when you need no features:\n   * `HttpClient` (fetch backend) is injectable by default.\n   */\n  httpFeatures?: HttpFeature<HttpFeatureKind>[];\n}\n\n/**\n * Internal configuration token. Consumers must use `provideRiviniaHttp()`.\n * @internal\n */\nexport const RIVINIA_HTTP_CONFIG = new InjectionToken<RiviniaHttpConfig>(\n  'RIVINIA_HTTP_CONFIG',\n);\n\nexport const DEFAULT_UNWRAP = false;\nexport const DEFAULT_UNWRAP_KEY = 'data';\n","import {\n  HttpClient,\n  HttpContext,\n  HttpParams,\n  httpResource,\n  type HttpResourceRef,\n} from '@angular/common/http';\nimport { Service, inject, type Signal } from '@angular/core';\nimport { map, type Observable } from 'rxjs';\nimport {\n  DEFAULT_UNWRAP,\n  DEFAULT_UNWRAP_KEY,\n  RIVINIA_HTTP_CONFIG,\n  type RiviniaHttpConfig,\n} from './http-config';\nimport {\n  type QueryParamsInput,\n  type RiviniaDeleteOptions,\n  type RiviniaRequestOptions,\n} from './http-options';\nimport { unwrapAs } from './http-utils';\n\n/** Options for `getResource` in addition to per-request options. */\nexport interface RiviniaResourceOptions<T> extends RiviniaRequestOptions {\n  /** Value while idle/loading. Defaults to `undefined`. */\n  defaultValue?: T;\n  /**\n   * Runs AFTER envelope unwrapping: `raw -> unwrap -> parse`.\n   * Use for runtime validation (e.g. Zod) or shaping.\n   */\n  parse?: (value: unknown) => T;\n  /**\n   * Forwarded to the `httpResource` request object only (enables the\n   * resource `progress` signal for downloads). Has no effect on the\n   * plain Observable methods — use `HttpClient` events there directly.\n   */\n  reportProgress?: boolean;\n}\n\n/**\n * Headless typed HTTP client.\n *\n * Thin over `HttpClient` (so app interceptors, `HttpContext` escape hatches\n * and `provideHttpClient()` testing all keep working). Owns no backend:\n * the app provides `HttpClient`, this library only adds base-URL joining\n * plus configurable envelope unwrapping.\n *\n * Unwrap resolution per call: `options.unwrap ?? config.unwrap ?? true`,\n * key: `options.unwrapKey ?? config.unwrapKey ?? 'data'`.\n */\n@Service()\nexport class RiviniaHttp {\n  private readonly http = inject(HttpClient);\n  private readonly config = inject<RiviniaHttpConfig>(RIVINIA_HTTP_CONFIG, {\n    optional: true,\n  });\n\n  get<T>(endpoint: string, options?: RiviniaRequestOptions): Observable<T> {\n    return this.http\n      .get<unknown>(this.url(endpoint), this.httpOptions(options))\n      .pipe(map((body) => this.applyUnwrap<T>(body, options)));\n  }\n\n  post<T>(endpoint: string, body?: unknown, options?: RiviniaRequestOptions): Observable<T> {\n    return this.http\n      .post<unknown>(this.url(endpoint), body, this.httpOptions(options))\n      .pipe(map((res) => this.applyUnwrap<T>(res, options)));\n  }\n\n  put<T>(endpoint: string, body?: unknown, options?: RiviniaRequestOptions): Observable<T> {\n    return this.http\n      .put<unknown>(this.url(endpoint), body, this.httpOptions(options))\n      .pipe(map((res) => this.applyUnwrap<T>(res, options)));\n  }\n\n  patch<T>(endpoint: string, body?: unknown, options?: RiviniaRequestOptions): Observable<T> {\n    return this.http\n      .patch<unknown>(this.url(endpoint), body, this.httpOptions(options))\n      .pipe(map((res) => this.applyUnwrap<T>(res, options)));\n  }\n\n  delete<T>(endpoint: string, options?: RiviniaDeleteOptions): Observable<T> {\n    return this.http\n      .delete<unknown>(this.url(endpoint), {\n        ...this.httpOptions(options),\n        body: options?.body,\n      })\n      .pipe(map((res) => this.applyUnwrap<T>(res, options)));\n  }\n\n  /** Binary download. Never unwrapped — envelopes don't apply to blobs. */\n  getBlob(endpoint: string, options?: RiviniaRequestOptions): Observable<Blob> {\n    return this.http.get(this.url(endpoint), {\n      ...this.httpOptions(options),\n      responseType: 'blob',\n    });\n  }\n\n  /**\n   * Reactive GET as an `httpResource` (stable since Angular v22).\n   * Re-fetches when the endpoint signal changes; `undefined` disables.\n   * Unwrap applies through `parse`, composed before a user `parse` if given.\n   */\n  getResource<T>(\n    endpoint: string | Signal<string | undefined>,\n    options?: RiviniaResourceOptions<T>,\n  ): HttpResourceRef<T | undefined> {\n    const { defaultValue, parse, reportProgress, ...requestOptions } = options ?? {};\n    const request = () => {\n      const ep = typeof endpoint === 'string' ? endpoint : endpoint();\n      if (ep === undefined) return undefined;\n      return {\n        url: this.url(ep),\n        params: this.toParams(requestOptions.params),\n        headers: requestOptions.headers,\n        context: requestOptions.context,\n        withCredentials: requestOptions.withCredentials,\n        ...(reportProgress !== undefined ? { reportProgress } : {}),\n      };\n    };\n    const unwrapKey = this.resolveKey(requestOptions);\n    const unwrapEnabled = this.resolveUnwrap(requestOptions);\n    const base = { defaultValue: defaultValue as T | undefined };\n    if (unwrapEnabled) {\n      const applyParse = (raw: unknown): T =>\n        parse ? parse(unwrapAs<T>(raw, unwrapKey)) : unwrapAs<T>(raw, unwrapKey);\n      return defaultValue === undefined\n        ? httpResource<T>(request, { ...base, parse: applyParse })\n        : httpResource<T>(request, {\n            ...base,\n            defaultValue: defaultValue as T,\n            parse: applyParse,\n          });\n    }\n    return defaultValue === undefined\n      ? httpResource<T>(request, { ...base, ...(parse ? { parse } : {}) })\n      : httpResource<T>(request, {\n          ...base,\n          defaultValue: defaultValue as T,\n          ...(parse ? { parse } : {}),\n        });\n  }\n\n  private url(endpoint: string): string {\n    // Deliberate passthrough: the caller owns the URL (environment, constant,\n    // signal …). Use the exported `joinUrl` at the call site when composing.\n    return endpoint;\n  }\n\n  private resolveUnwrap(options?: RiviniaRequestOptions): boolean {\n    return options?.unwrap ?? this.config?.unwrap ?? DEFAULT_UNWRAP;\n  }\n\n  private resolveKey(options?: RiviniaRequestOptions): string {\n    return options?.unwrapKey ?? this.config?.unwrapKey ?? DEFAULT_UNWRAP_KEY;\n  }\n\n  private applyUnwrap<T>(body: unknown, options?: RiviniaRequestOptions): T {\n    if (!this.resolveUnwrap(options)) return body as T;\n    return unwrapAs<T>(body, this.resolveKey(options));\n  }\n\n  private httpOptions(options?: RiviniaRequestOptions) {\n    return {\n      params: this.toParams(options?.params),\n      headers: options?.headers,\n      context: options?.context ?? new HttpContext(),\n      withCredentials: options?.withCredentials,\n    };\n  }\n\n  private toParams(input?: QueryParamsInput): HttpParams | undefined {\n    if (!input) return undefined;\n    if (input instanceof HttpParams) return input;\n    let params = new HttpParams();\n    for (const [key, value] of Object.entries(input)) {\n      if (value !== undefined && value !== null) {\n        params = params.set(key, String(value));\n      }\n    }\n    return params;\n  }\n}\n","import { EnvironmentProviders, inject, makeEnvironmentProviders } from '@angular/core';\nimport { provideHttpClient } from '@angular/common/http';\nimport { RIVINIA_HTTP_CONFIG, type RiviniaHttpConfig } from './http-config';\nimport { RiviniaHttp } from './rivinia-http';\n\n/**\n * Configures `@rivinia/http`.\n *\n * URLs are always used as given — build them at the call site from wherever\n * you want (see the exported `joinUrl` + your `environment.apiUrl`).\n *\n * Three backend styles (pick ONE):\n * - `provideRiviniaHttp()` alone — Angular ≥21 already injects `HttpClient` (fetch).\n * - `provideRiviniaHttp({ httpFeatures: [withInterceptors([...])] })` — single\n *   call that also configures the backend. Do NOT additionally call\n *   `provideHttpClient()` (double registration duplicates the XSRF interceptor).\n * - `provideHttpClient(...)` + `provideRiviniaHttp()` separately — equivalent,\n *   keeps backend config visibly in app code (this is what `ng add` generates).\n *\n * @example\n * ```ts\n * provideRiviniaHttp({ unwrapKey: 'data' })\n * ```\n */\nexport function provideRiviniaHttp(config: RiviniaHttpConfig = {}): EnvironmentProviders {\n  const { httpFeatures, ...rest } = config;\n  return makeEnvironmentProviders([\n    ...(httpFeatures ? [provideHttpClient(...httpFeatures)] : []),\n    { provide: RIVINIA_HTTP_CONFIG, useValue: rest },\n  ]);\n}\n\n/** Shorthand for `inject(RiviniaHttp)`. */\nexport function injectRiviniaHttp(): RiviniaHttp {\n  return inject(RiviniaHttp);\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@rivinia/http",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Headless typed HTTP client for Angular: envelope unwrapping, plain Observables and httpResource.",
+  "keywords": [
+    "angular",
+    "http",
+    "http-client",
+    "signals",
+    "http-resource",
+    "typescript"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@angular/common": "^22.0.0",
+    "@angular/core": "^22.0.0",
+    "rxjs": "^6.5.3 || ^7.4.0"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "sideEffects": false,
+  "schematics": "./schematics/collection.json",
+  "module": "fesm2022/rivinia-http.mjs",
+  "typings": "types/rivinia-http.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./types/rivinia-http.d.ts",
+      "default": "./fesm2022/rivinia-http.mjs"
+    }
+  },
+  "type": "module"
 }

package/schematics/collection.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "../../../node_modules/@angular-devkit/schematics/collection-schema.json",
+  "schematics": {
+    "ng-add": {
+      "description": "Add provideHttpClient() and provideRiviniaHttp() to the application config.",
+      "factory": "./ng-add/index.cjs#ngAdd",
+      "schema": "./ng-add/schema.json"
+    }
+  }
+}

package/schematics/ng-add/index.cjs

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ngAdd = ngAdd;
+const schematics_1 = require("@angular-devkit/schematics");
+const HTTP_CLIENT_IMPORT = `import { provideHttpClient } from '@angular/common/http';`;
+const PROVIDE_HTTP_IMPORT = `import { provideRiviniaHttp } from '@rivinia/http';`;
+/**
+ * `ng add @rivinia/http` — wires the library into a standalone app config.
+ *
+ * - Never overwrites user files; only inserts two imports + two providers.
+ * - Idempotent: safe to run twice (existing entries are detected and skipped).
+ * - Never provides the backend beyond `provideHttpClient()`; interceptors,
+ *   URLs and unwrap options stay app-owned (see schema options).
+ */
+function ngAdd(options) {
+    return (tree, context) => {
+        let configPath;
+        try {
+            configPath = findAppConfig(tree, options.project);
+        }
+        catch (error) {
+            context.logger.warn(`[rivinia/http] workspace lookup failed (${error instanceof Error ? error.message : error}) — skipping. ` +
+                `Add provideHttpClient() and provideRiviniaHttp() manually (see README).`);
+            return tree;
+        }
+        if (!configPath || !tree.exists(configPath)) {
+            context.logger.warn(`[rivinia/http] app.config.ts not found — skipping. ` +
+                `Add provideHttpClient() and provideRiviniaHttp() manually (see README).`);
+            return tree;
+        }
+        let content = tree.read(configPath)?.toString('utf-8') ?? '';
+        if (!content) {
+            throw new schematics_1.SchematicsException(`[rivinia/http] ${configPath} is empty.`);
+        }
+        // Deterministic mapping, no ambiguity (library default: disabled):
+        // - unwrap !== true   → emit nothing about unwrapping (raw passthrough).
+        //   A custom key given alongside is ignored, said plainly in logs.
+        // - unwrap === true   → emit `unwrap: true`, plus the key only when custom
+        //   (anything but ''/'data', which both mean the library default key).
+        // URLs are never touched: the caller owns them (environment, joinUrl, …).
+        const parts = [];
+        const unwrapEnabled = options.unwrap === true;
+        if (!unwrapEnabled) {
+            if (options.unwrapKey && options.unwrapKey !== 'data') {
+                context.logger.info(`[rivinia/http] unwrapping not enabled — custom unwrapKey '${options.unwrapKey}' ignored.`);
+            }
+        }
+        else {
+            parts.push('unwrap: true');
+            if (options.unwrapKey && options.unwrapKey.length > 0 && options.unwrapKey !== 'data') {
+                parts.push(`unwrapKey: '${options.unwrapKey}'`);
+            }
+        }
+        const provideArg = parts.length > 0 ? `{ ${parts.join(', ')} }` : '';
+        let changed = false;
+        if (!content.includes(HTTP_CLIENT_IMPORT)) {
+            content = insertAfterLastImport(content, HTTP_CLIENT_IMPORT);
+            changed = true;
+        }
+        if (!content.includes(PROVIDE_HTTP_IMPORT)) {
+            content = insertAfterLastImport(content, PROVIDE_HTTP_IMPORT);
+            changed = true;
+        }
+        if (!content.includes('provideHttpClient(')) {
+            content = insertProvider(content, 'provideHttpClient()');
+            changed = true;
+        }
+        else {
+            context.logger.info('[rivinia/http] provideHttpClient() already present — skipped.');
+        }
+        const provideCall = `provideRiviniaHttp(${provideArg})`;
+        if (!content.includes('provideRiviniaHttp(')) {
+            content = insertProvider(content, provideCall);
+            changed = true;
+        }
+        else {
+            context.logger.info('[rivinia/http] provideRiviniaHttp() already present — skipped.');
+        }
+        if (changed) {
+            tree.overwrite(configPath, content);
+            context.logger.info(`[rivinia/http] wired into ${configPath}.`);
+        }
+        return tree;
+    };
+}
+function defaultProjectName(tree, requested) {
+    if (requested)
+        return requested;
+    const angularJson = tree.read('/angular.json')?.toString('utf-8');
+    if (!angularJson) {
+        throw new schematics_1.SchematicsException('[rivinia/http] angular.json not found.');
+    }
+    const workspace = JSON.parse(angularJson);
+    if (workspace.defaultProject && typeof workspace.defaultProject === 'string') {
+        return workspace.defaultProject;
+    }
+    const names = Object.keys(workspace.projects ?? {});
+    if (names.length === 0) {
+        throw new schematics_1.SchematicsException('[rivinia/http] no projects in angular.json.');
+    }
+    return names[0];
+}
+function findAppConfig(tree, requestedProject) {
+    const angularJson = tree.read('/angular.json')?.toString('utf-8');
+    if (!angularJson)
+        return null;
+    const workspace = JSON.parse(angularJson);
+    const name = defaultProjectName(tree, requestedProject);
+    const project = workspace.projects?.[name];
+    if (!project)
+        return null;
+    const sourceRoot = project.sourceRoot ?? (project.root ? `${project.root}/src` : 'src');
+    return `/${sourceRoot}/app/app.config.ts`;
+}
+function insertAfterLastImport(content, line) {
+    const lines = content.split('\n');
+    let idx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (/^\s*import\s/.test(lines[i]))
+            idx = i;
+    }
+    lines.splice(idx + 1, 0, line);
+    return lines.join('\n');
+}
+function insertProvider(content, call) {
+    const match = /providers\s*:\s*\[/.exec(content);
+    if (!match) {
+        throw new schematics_1.SchematicsException('[rivinia/http] no `providers: [` array found in app.config.ts — add providers manually.');
+    }
+    const at = match.index + match[0].length;
+    return `${content.slice(0, at)}\n    ${call},${content.slice(at)}`;
+}

package/schematics/ng-add/schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "rivinia-http-ng-add",
+  "title": "Rivinia HTTP ng-add options",
+  "type": "object",
+  "properties": {
+    "project": {
+      "type": "string",
+      "description": "Angular CLI project name — only for multi-app workspaces. Defaults to the workspace default project. Unrelated to unwrap scope.",
+      "default": ""
+    },
+    "unwrapKey": {
+      "type": "string",
+      "description": "Envelope key passed as provideRiviniaHttp({ unwrapKey }). Asked only in effect when unwrapping is enabled; omit to keep the 'data' default.",
+      "x-prompt": {
+        "message": "Backend envelope key (Enter for the 'data' default)?",
+        "type": "input"
+      }
+    },
+    "unwrap": {
+      "type": "boolean",
+      "description": "Enable envelope unwrapping project-wide. When false, provideRiviniaHttp({ unwrap: false }) is emitted and unwrapKey is ignored.",
+      "x-prompt": {
+        "message": "Enable backend envelope unwrapping for this project?",
+        "type": "confirmation"
+      }
+    }
+  },
+  "required": []
+}

package/types/rivinia-http.d.ts

@@ -0,0 +1,149 @@
+import { HttpContext, HttpFeature, HttpFeatureKind, HttpHeaders, HttpParams, HttpResourceRef } from "@angular/common/http";
+import * as i0 from "@angular/core";
+import { EnvironmentProviders, InjectionToken, Signal } from "@angular/core";
+import { Observable } from "rxjs";
+/**
+ * Global configuration for `@rivinia/http`.
+ *
+ * Every field is optional and can be overridden per request.
+ * URLs are ALWAYS used as given — the library never joins, prefixes, or
+ * rewrites them. Build them at the call site from wherever you want
+ * (`environment.apiUrl`, a constant, a signal …) with the exported `joinUrl`.
+ */
+interface RiviniaHttpConfig {
+  /**
+   * Unwrap `{ [unwrapKey]: payload }` envelopes by default.
+   * @default false — the library assumes nothing about your backend;
+   * opt in globally here or per call with `{ unwrap: true }`.
+   */
+  unwrap?: boolean;
+  /**
+   * Envelope key unwrapped when `unwrap` is enabled.
+   * @default 'data'
+   */
+  unwrapKey?: string;
+  /**
+   * Optional `HttpClient` features (`withInterceptors(...)`, `withXhr()`, …),
+   * applied via a single internal `provideHttpClient(...httpFeatures)` call.
+   *
+   * Use this INSTEAD of calling `provideHttpClient()` yourself — calling both
+   * registers the built-in XSRF interceptor twice (verified against Angular
+   * 22.2.2 source: `xsrfInterceptorFn` is a multi-provider with no cross-call
+   * dedup). Omit it entirely on Angular ≥21 when you need no features:
+   * `HttpClient` (fetch backend) is injectable by default.
+   */
+  httpFeatures?: HttpFeature<HttpFeatureKind>[];
+}
+/**
+ * Internal configuration token. Consumers must use `provideRiviniaHttp()`.
+ * @internal
+ */
+declare const RIVINIA_HTTP_CONFIG: InjectionToken<RiviniaHttpConfig>;
+declare const DEFAULT_UNWRAP = false;
+declare const DEFAULT_UNWRAP_KEY = "data";
+/** Shorthand for building query strings; `null`/`undefined` values are dropped. */
+type QueryParamsInput = HttpParams | Record<string, string | number | boolean | undefined | null>;
+/**
+ * Per-request options. `unwrap` / `unwrapKey` override the global
+ * `provideRiviniaHttp()` configuration for this call only.
+ */
+interface RiviniaRequestOptions {
+  params?: QueryParamsInput;
+  headers?: HttpHeaders | Record<string, string | string[]>;
+  /** Pass-through for app-owned interceptors (auth opt-out, error policy, ...). */
+  context?: HttpContext;
+  withCredentials?: boolean;
+  /** Enable envelope unwrapping for this call (overrides global `unwrap`). */
+  unwrap?: boolean;
+  /** Envelope key for this call (overrides global `unwrapKey`). */
+  unwrapKey?: string;
+}
+interface RiviniaDeleteOptions extends RiviniaRequestOptions {
+  body?: unknown;
+}
+/** Options for `getResource` in addition to per-request options. */
+interface RiviniaResourceOptions<T> extends RiviniaRequestOptions {
+  /** Value while idle/loading. Defaults to `undefined`. */
+  defaultValue?: T;
+  /**
+   * Runs AFTER envelope unwrapping: `raw -> unwrap -> parse`.
+   * Use for runtime validation (e.g. Zod) or shaping.
+   */
+  parse?: (value: unknown) => T;
+  /**
+   * Forwarded to the `httpResource` request object only (enables the
+   * resource `progress` signal for downloads). Has no effect on the
+   * plain Observable methods — use `HttpClient` events there directly.
+   */
+  reportProgress?: boolean;
+}
+/**
+ * Headless typed HTTP client.
+ *
+ * Thin over `HttpClient` (so app interceptors, `HttpContext` escape hatches
+ * and `provideHttpClient()` testing all keep working). Owns no backend:
+ * the app provides `HttpClient`, this library only adds base-URL joining
+ * plus configurable envelope unwrapping.
+ *
+ * Unwrap resolution per call: `options.unwrap ?? config.unwrap ?? true`,
+ * key: `options.unwrapKey ?? config.unwrapKey ?? 'data'`.
+ */
+export declare class RiviniaHttp {
+  private readonly http;
+  private readonly config;
+  get<T>(endpoint: string, options?: RiviniaRequestOptions): Observable<T>;
+  post<T>(endpoint: string, body?: unknown, options?: RiviniaRequestOptions): Observable<T>;
+  put<T>(endpoint: string, body?: unknown, options?: RiviniaRequestOptions): Observable<T>;
+  patch<T>(endpoint: string, body?: unknown, options?: RiviniaRequestOptions): Observable<T>;
+  delete<T>(endpoint: string, options?: RiviniaDeleteOptions): Observable<T>;
+  /** Binary download. Never unwrapped — envelopes don't apply to blobs. */
+  getBlob(endpoint: string, options?: RiviniaRequestOptions): Observable<Blob>;
+  /**
+   * Reactive GET as an `httpResource` (stable since Angular v22).
+   * Re-fetches when the endpoint signal changes; `undefined` disables.
+   * Unwrap applies through `parse`, composed before a user `parse` if given.
+   */
+  getResource<T>(endpoint: string | Signal<string | undefined>, options?: RiviniaResourceOptions<T>): HttpResourceRef<T | undefined>;
+  private url;
+  private resolveUnwrap;
+  private resolveKey;
+  private applyUnwrap;
+  private httpOptions;
+  private toParams;
+  static ɵfac: i0.ɵɵFactoryDeclaration<RiviniaHttp, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+/**
+ * Joins a base URL and an endpoint without producing double slashes.
+ * Absolute `http(s)` endpoints pass through untouched.
+ */
+export declare function joinUrl(baseUrl: string, endpoint: string): string;
+/**
+ * Extracts `body[key]` when the backend wraps payloads in an envelope
+ * (e.g. `{ data, error, isSuccess }`); passes anything else through
+ * unchanged. Recursive, so nested envelopes collapse.
+ */
+export declare function unwrapAs<T>(body: unknown, key: string): T;
+/**
+ * Configures `@rivinia/http`.
+ *
+ * URLs are always used as given — build them at the call site from wherever
+ * you want (see the exported `joinUrl` + your `environment.apiUrl`).
+ *
+ * Three backend styles (pick ONE):
+ * - `provideRiviniaHttp()` alone — Angular ≥21 already injects `HttpClient` (fetch).
+ * - `provideRiviniaHttp({ httpFeatures: [withInterceptors([...])] })` — single
+ *   call that also configures the backend. Do NOT additionally call
+ *   `provideHttpClient()` (double registration duplicates the XSRF interceptor).
+ * - `provideHttpClient(...)` + `provideRiviniaHttp()` separately — equivalent,
+ *   keeps backend config visibly in app code (this is what `ng add` generates).
+ *
+ * @example
+ * ```ts
+ * provideRiviniaHttp({ unwrapKey: 'data' })
+ * ```
+ */
+export declare function provideRiviniaHttp(config?: RiviniaHttpConfig): EnvironmentProviders;
+/** Shorthand for `inject(RiviniaHttp)`. */
+export declare function injectRiviniaHttp(): RiviniaHttp;
+export type { QueryParamsInput, RiviniaDeleteOptions, RiviniaHttpConfig, RiviniaRequestOptions, RiviniaResourceOptions };