@rivinia/http 0.3.0 → 0.4.0

package/README.md

@@ -7,7 +7,7 @@ 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.3.0**
+- Version: **0.4.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
@@ -103,16 +103,39 @@ export class MixedService {
 `getResource` applies the same rules through `parse` (your own `parse` runs
 after unwrapping — ideal for Zod/Valibot validation).
 
+## Envelope failure validation (opt-in)
+
+Backends that report failure inside HTTP 200 (`{ data: null, isSuccess: false }`)
+must never flow into `next()` as success — critical in payment flows:
+
+```ts
+provideRiviniaHttp({ envelope: {} });                 // whole app (isSuccess/error keys)
+this.api.get(url, { envelope: { successKey: 'ok', errorKey: 'message' } });
+```
+
+A failed envelope throws `RiviniaHttpEnvelopeError` (`body` + `code` attached;
+in `getResource` it surfaces as `resource.error()`). Validation runs on the raw
+body before unwrapping, independent of `unwrap`. Per-call policy replaces any
+global one wholesale.
+
 ## API
 
 | Export | Kind | Purpose |
 |---|---|---|
-| `provideRiviniaHttp(config?)` | provider | `{ unwrap?=false, unwrapKey?='data', httpFeatures? }` |
-| `RiviniaHttp` | `@Service()` | `get/post/put/patch/delete`, `getBlob`, `getResource` |
+| `provideRiviniaHttp(config?)` | provider | `{ unwrap?=false, unwrapKey?='data', envelope?, httpFeatures? }` |
+| `RiviniaHttp` | `@Service()` | `get/post/put/patch/delete`, `getBlob`, `getText`, `getResponse`, `postResponse`, `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` |
+| `unwrapAs(body, key)` | util | single-level envelope extraction (nested keys preserved) |
+| types | types | `RiviniaHttpConfig`, `RiviniaRequestOptions`, `RiviniaDeleteOptions`, `RiviniaResourceOptions`, `RiviniaEnvelopePolicy`, `ReactiveInput`, `QueryParamsInput` |
+
+`getResponse`/`postResponse` return the raw `HttpResponse` (status + headers,
+body never unwrapped — compose `unwrapAs` yourself if needed). A configured
+`envelope` policy still validates the body on these paths: a globally declared
+failure rule holds on every JSON path, never just the unwrapped ones. `getText`
+returns raw text; binary/text bodies cannot carry envelopes, so the policy does
+not apply there. In `getResource`, the URL, `params`, `headers` and `context`
+accept values, signals or reactive functions (everything else is static).
 
 `getBlob` is never unwrapped. `HttpContext` passes through untouched, so
 app interceptors (auth opt-out, error toasts) keep working. For caching,

package/fesm2022/rivinia-http.mjs

@@ -9,7 +9,7 @@ function joinUrl(baseUrl, endpoint) {
 	return path ? `${base}/${path}` : base;
 }
 function unwrapAs(body, key) {
-	if (isObjectRecord(body) && hasOwn(body, key)) return unwrapAs(body[key], key);
+	if (isObjectRecord(body) && hasOwn(body, key)) return body[key];
 	return body;
 }
 function isObjectRecord(value) {
@@ -18,6 +18,26 @@ function isObjectRecord(value) {
 function hasOwn(obj, key) {
 	return Object.prototype.hasOwnProperty.call(obj, key);
 }
+var RiviniaHttpEnvelopeError = class extends Error {
+	body;
+	code;
+	constructor(body, code) {
+		super(typeof code === "string" && code.length > 0 ? `[rivinia/http] Request failed: ${code}` : "[rivinia/http] Request failed (backend envelope)");
+		this.name = "RiviniaHttpEnvelopeError";
+		this.body = body;
+		this.code = code;
+	}
+};
+const DEFAULT_SUCCESS_KEY = "isSuccess";
+const DEFAULT_ERROR_KEY = "error";
+function assertEnvelope(body, policy) {
+	if (policy.throwOnFailure === false) return;
+	if (typeof body !== "object" || body === null || Array.isArray(body)) return;
+	const successKey = policy.successKey ?? DEFAULT_SUCCESS_KEY;
+	const record = body;
+	if (!(successKey in record) || record[successKey] !== false) return;
+	throw new RiviniaHttpEnvelopeError(body, record[policy.errorKey ?? DEFAULT_ERROR_KEY]);
+}
 const RIVINIA_HTTP_CONFIG = new InjectionToken("RIVINIA_HTTP_CONFIG");
 var RiviniaHttp = class RiviniaHttp {
 	http = inject(HttpClient);
@@ -46,6 +66,32 @@ var RiviniaHttp = class RiviniaHttp {
 			responseType: "blob"
 		});
 	}
+	getText(endpoint, options) {
+		return this.http.get(this.url(endpoint), {
+			...this.httpOptions(options),
+			responseType: "text"
+		});
+	}
+	getResponse(endpoint, options) {
+		const envelope = this.resolveEnvelope(options);
+		return this.http.get(this.url(endpoint), {
+			...this.httpOptions(options),
+			observe: "response"
+		}).pipe(map((res) => {
+			if (envelope) assertEnvelope(res.body, envelope);
+			return res;
+		}));
+	}
+	postResponse(endpoint, body, options) {
+		const envelope = this.resolveEnvelope(options);
+		return this.http.post(this.url(endpoint), body, {
+			...this.httpOptions(options),
+			observe: "response"
+		}).pipe(map((res) => {
+			if (envelope) assertEnvelope(res.body, envelope);
+			return res;
+		}));
+	}
 	getResource(endpoint, options) {
 		const { defaultValue, parse, reportProgress, ...requestOptions } = options ?? {};
 		const source = typeof endpoint === "function" && !isSignal(endpoint) ? computed(endpoint) : endpoint;
@@ -54,34 +100,29 @@ var RiviniaHttp = class RiviniaHttp {
 			if (ep === void 0) return void 0;
 			return {
 				url: this.url(ep),
-				params: this.toParams(requestOptions.params),
-				headers: requestOptions.headers,
-				context: requestOptions.context,
+				params: this.toParams(resolveInput(requestOptions.params)),
+				headers: resolveInput(requestOptions.headers),
+				context: resolveInput(requestOptions.context),
 				withCredentials: requestOptions.withCredentials,
 				...reportProgress !== void 0 ? { reportProgress } : {}
 			};
 		};
 		const unwrapKey = this.resolveKey(requestOptions);
 		const unwrapEnabled = this.resolveUnwrap(requestOptions);
+		const envelope = this.resolveEnvelope(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
-			});
-		}
+		const applyParse = (raw) => {
+			if (envelope) assertEnvelope(raw, envelope);
+			const unwrapped = unwrapEnabled ? unwrapAs(raw, unwrapKey) : raw;
+			return parse ? parse(unwrapped) : unwrapped;
+		};
 		return defaultValue === void 0 ? httpResource(request, {
 			...base,
-			...parse ? { parse } : {}
+			parse: applyParse
 		}) : httpResource(request, {
 			...base,
 			defaultValue,
-			...parse ? { parse } : {}
+			parse: applyParse
 		});
 	}
 	url(endpoint) {
@@ -93,7 +134,12 @@ var RiviniaHttp = class RiviniaHttp {
 	resolveKey(options) {
 		return options?.unwrapKey ?? this.config?.unwrapKey ?? "data";
 	}
+	resolveEnvelope(options) {
+		return options?.envelope ?? this.config?.envelope;
+	}
 	applyUnwrap(body, options) {
+		const envelope = this.resolveEnvelope(options);
+		if (envelope) assertEnvelope(body, envelope);
 		if (!this.resolveUnwrap(options)) return body;
 		return unwrapAs(body, this.resolveKey(options));
 	}
@@ -134,6 +180,12 @@ i0.ɵɵngDeclareClassMetadata({
 	type: RiviniaHttp,
 	decorators: [{ type: Service }]
 });
+function resolveInput(value) {
+	if (value === void 0) return void 0;
+	if (isSignal(value)) return value();
+	if (typeof value === "function") return value();
+	return value;
+}
 function provideRiviniaHttp(config = {}) {
 	const { httpFeatures, ...rest } = config;
 	return makeEnvironmentProviders([...httpFeatures ? [provideHttpClient(...httpFeatures)] : [], {
@@ -144,6 +196,6 @@ function provideRiviniaHttp(config = {}) {
 function injectRiviniaHttp() {
 	return inject(RiviniaHttp);
 }
-export { RiviniaHttp, injectRiviniaHttp, joinUrl, provideRiviniaHttp, unwrapAs };
+export { RiviniaHttp, RiviniaHttpEnvelopeError, injectRiviniaHttp, joinUrl, provideRiviniaHttp, unwrapAs };
 
 //# sourceMappingURL=rivinia-http.mjs.map

package/fesm2022/rivinia-http.mjs.map

@@ -1 +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, computed, inject, isSignal, 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   * The endpoint can be a static string, a signal, or a reactive function\n   * (same as `httpResource` itself) — it re-fetches on change, and\n   * `undefined` disables the request. Unwrap applies through `parse`,\n   * composed before a user `parse` if given.\n   */\n  getResource<T>(\n    endpoint: string | Signal<string | undefined> | (() => string | undefined),\n    options?: RiviniaResourceOptions<T>,\n  ): HttpResourceRef<T | undefined> {\n    const { defaultValue, parse, reportProgress, ...requestOptions } = options ?? {};\n    const source: string | Signal<string | undefined> =\n      typeof endpoint === 'function' && !isSignal(endpoint)\n        ? computed(endpoint)\n        : (endpoint as string | Signal<string | undefined>);\n    const request = () => {\n      const ep = typeof source === 'string' ? source : source();\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":";;;;AAIA,SAAgB,QAAQ,SAAiB,UAAgB;CACvD,IAAI,gBAAgB,KAAK,QAAQ,GAC/B,OAAO;CAET,MAAM,OAAO,QAAQ,SAAS,GAAG,IAAI,QAAQ,MAAM,GAAG,EAAE,IAAI;CAC5D,MAAM,OAAO,SAAS,WAAW,GAAG,IAAI,SAAS,MAAM,CAAC,IAAI;CAC5D,OAAO,OAAO,GAAG,KAAI,GAAI,SAAS;AACpC;AAOA,SAAgB,SAAY,MAAe,KAAW;CACpD,IAAI,eAAe,IAAI,KAAK,OAAO,MAAM,GAAG,GAC1C,OAAO,SAAY,KAAK,MAAM,GAAG;CAEnC,OAAO;AACT;AAEA,SAAS,eAAe,OAAc;CACpC,OAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC5E;AAEA,SAAS,OAAO,KAA8B,KAAW;CACvD,OAAO,OAAO,UAAU,eAAe,KAAK,KAAK,GAAG;AACtD;ACSA,MAAa,sBAAsB,IAAI,eACrC,qBAAqB;ACUvB,IAAa,cAAb,MAAa,YAAW;CACL,OAAO,OAAO,UAAU;CACxB,SAAS,OAA0B,qBAAqB,EACvE,UAAU,KACX,CAAA;CAED,IAAO,UAAkB,SAA+B;EACtD,OAAO,KAAK,KACT,IAAa,KAAK,IAAI,QAAQ,GAAG,KAAK,YAAY,OAAO,CAAC,CAAC,CAC3D,KAAK,KAAK,SAAS,KAAK,YAAe,MAAM,OAAO,CAAC,CAAC;CAC3D;CAEA,KAAQ,UAAkB,MAAgB,SAA+B;EACvE,OAAO,KAAK,KACT,KAAc,KAAK,IAAI,QAAQ,GAAG,MAAM,KAAK,YAAY,OAAO,CAAC,CAAC,CAClE,KAAK,KAAK,QAAQ,KAAK,YAAe,KAAK,OAAO,CAAC,CAAC;CACzD;CAEA,IAAO,UAAkB,MAAgB,SAA+B;EACtE,OAAO,KAAK,KACT,IAAa,KAAK,IAAI,QAAQ,GAAG,MAAM,KAAK,YAAY,OAAO,CAAC,CAAC,CACjE,KAAK,KAAK,QAAQ,KAAK,YAAe,KAAK,OAAO,CAAC,CAAC;CACzD;CAEA,MAAS,UAAkB,MAAgB,SAA+B;EACxE,OAAO,KAAK,KACT,MAAe,KAAK,IAAI,QAAQ,GAAG,MAAM,KAAK,YAAY,OAAO,CAAC,CAAC,CACnE,KAAK,KAAK,QAAQ,KAAK,YAAe,KAAK,OAAO,CAAC,CAAC;CACzD;CAEA,OAAU,UAAkB,SAA8B;EACxD,OAAO,KAAK,KACT,OAAgB,KAAK,IAAI,QAAQ,GAAG;GACnC,GAAG,KAAK,YAAY,OAAO;GAC3B,MAAM,SAAS;EAChB,CAAA,CAAC,CACD,KAAK,KAAK,QAAQ,KAAK,YAAe,KAAK,OAAO,CAAC,CAAC;CACzD;CAGA,QAAQ,UAAkB,SAA+B;EACvD,OAAO,KAAK,KAAK,IAAI,KAAK,IAAI,QAAQ,GAAG;GACvC,GAAG,KAAK,YAAY,OAAO;GAC3B,cAAc;EACf,CAAA;CACH;CASA,YACE,UACA,SAAmC;EAEnC,MAAM,EAAE,cAAc,OAAO,gBAAgB,GAAG,mBAAmB,WAAW,CAAA;EAC9E,MAAM,SACJ,OAAO,aAAa,cAAc,CAAC,SAAS,QAAQ,IAChD,SAAS,QAAQ,IAChB;EACP,MAAM,gBAAe;GACnB,MAAM,KAAK,OAAO,WAAW,WAAW,SAAS,OAAM;GACvD,IAAI,OAAO,QAAW,OAAO;GAC7B,OAAO;IACL,KAAK,KAAK,IAAI,EAAE;IAChB,QAAQ,KAAK,SAAS,eAAe,MAAM;IAC3C,SAAS,eAAe;IACxB,SAAS,eAAe;IACxB,iBAAiB,eAAe;IAChC,GAAI,mBAAmB,SAAY,EAAE,eAAc,IAAK,CAAA;GACzD;EACH;EACA,MAAM,YAAY,KAAK,WAAW,cAAc;EAChD,MAAM,gBAAgB,KAAK,cAAc,cAAc;EACvD,MAAM,OAAO,EAAgB,aAA6B;EAC1D,IAAI,eAAe;GACjB,MAAM,cAAc,QAClB,QAAQ,MAAM,SAAY,KAAK,SAAS,CAAC,IAAI,SAAY,KAAK,SAAS;GACzE,OAAO,iBAAiB,SACpB,aAAgB,SAAS;IAAE,GAAG;IAAM,OAAO;GAAU,CAAE,IACvD,aAAgB,SAAS;IACvB,GAAG;IACW;IACd,OAAO;GACR,CAAA;EACP;EACA,OAAO,iBAAiB,SACpB,aAAgB,SAAS;GAAE,GAAG;GAAM,GAAI,QAAQ,EAAE,MAAK,IAAK,CAAA;EAAG,CAAE,IACjE,aAAgB,SAAS;GACvB,GAAG;GACW;GACd,GAAI,QAAQ,EAAE,MAAK,IAAK,CAAA;EACzB,CAAA;CACP;CAEQ,IAAI,UAAgB;EAG1B,OAAO;CACT;CAEQ,cAAc,SAA+B;EACnD,OAAO,SAAS,UAAU,KAAK,QAAQ,UAAA;CACzC;CAEQ,WAAW,SAA+B;EAChD,OAAO,SAAS,aAAa,KAAK,QAAQ,aAAA;CAC5C;CAEQ,YAAe,MAAe,SAA+B;EACnE,IAAI,CAAC,KAAK,cAAc,OAAO,GAAG,OAAO;EACzC,OAAO,SAAY,MAAM,KAAK,WAAW,OAAO,CAAC;CACnD;CAEQ,YAAY,SAA+B;EACjD,OAAO;GACL,QAAQ,KAAK,SAAS,SAAS,MAAM;GACrC,SAAS,SAAS;GAClB,SAAS,SAAS,WAAW,IAAI,YAAW;GAC5C,iBAAiB,SAAS;EAC3B;CACH;CAEQ,SAAS,OAAwB;EACvC,IAAI,CAAC,OAAO,OAAO;EACnB,IAAI,iBAAiB,YAAY,OAAO;EACxC,IAAI,SAAS,IAAI,WAAU;EAC3B,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,KAAK,GAC7C,IAAI,UAAU,UAAa,UAAU,MACnC,SAAS,OAAO,IAAI,KAAK,OAAO,KAAK,CAAC;EAG1C,OAAO;CACT;CAxIW,OAAA,OAAA,GAAA,mBAAA;EAAA,YAAA;EAAA,SAAA;EAAA,UAAA;EAAA,MAAA;EAAW,MAAA,CAAA;EAAA,QAAA,GAAA,gBAAA;CAAA,CAAA;CAAX,OAAA,QAAA,GAAA,mBAAA;EAAA,YAAA;EAAA,SAAA;EAAA,UAAA;EAAA,MAAA;CAAW,CAAA;;AAAX,GAAA,yBAAA;CAAA,YAAA;CAAA,SAAA;CAAA,UAAA;CAAA,MAAA;CAAW,YAAA,CAAA,EADvB,MAAA,QAAA,CAAA;;AC1BD,SAAgB,mBAAmB,SAA4B,CAAA,GAAE;CAC/D,MAAM,EAAE,cAAc,GAAG,SAAS;CAClC,OAAO,yBAAyB,CAC9B,GAAI,eAAe,CAAC,kBAAkB,GAAG,YAAY,CAAC,IAAI,CAAA,GAC1D;EAAE,SAAS;EAAqB,UAAU;CAAI,CAC/C,CAAA;AACH;AAGA,SAAgB,oBAAiB;CAC/B,OAAO,OAAO,WAAW;AAC3B"}
+{"version":3,"file":"rivinia-http.mjs","names":[],"sources":["../../../projects/http/src/lib/http-utils.ts","../../../projects/http/src/lib/http-envelope.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. Unwraps EXACTLY ONE level: a payload that itself contains the\n * key (`{ data: { data: […], page: 1 } }`) is returned whole — recursive\n * unwrapping silently destroyed sibling fields (data-loss bug, fixed).\n */\nexport function unwrapAs<T>(body: unknown, key: string): T {\n  if (isObjectRecord(body) && hasOwn(body, key)) {\n    return body[key] as T;\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","/**\n * Typed envelope failure. Thrown when a backend signals failure inside a\n * successful HTTP response (e.g. `{ data: null, isSuccess: false }` with\n * HTTP 200) and the envelope policy opts into throwing. In `getResource`\n * this surfaces as `resource.error()`.\n */\nexport class RiviniaHttpEnvelopeError extends Error {\n  /** The raw response body. */\n  readonly body: unknown;\n  /** The machine-readable failure code (`body[errorKey]`), if any. */\n  readonly code: unknown;\n\n  constructor(body: unknown, code: unknown) {\n    super(\n      typeof code === 'string' && code.length > 0\n        ? `[rivinia/http] Request failed: ${code}`\n        : '[rivinia/http] Request failed (backend envelope)',\n    );\n    this.name = 'RiviniaHttpEnvelopeError';\n    this.body = body;\n    this.code = code;\n  }\n}\n\n/**\n * Opt-in backend-envelope validation. When present (globally or per call),\n * a response object whose `successKey` is strictly `false` throws\n * `RiviniaHttpEnvelopeError` instead of flowing into `next()` as success.\n * Runs on the raw body before unwrapping, independent of `unwrap`.\n */\nexport interface RiviniaEnvelopePolicy {\n  /** Body key holding the success flag. @default 'isSuccess' */\n  readonly successKey?: string;\n  /** Body key holding the failure code. @default 'error' */\n  readonly errorKey?: string;\n  /** Throw on failure. Explicit `false` disables (policy becomes passive). @default true */\n  readonly throwOnFailure?: boolean;\n}\n\nconst DEFAULT_SUCCESS_KEY = 'isSuccess';\nconst DEFAULT_ERROR_KEY = 'error';\n\n/** Throws when the envelope signals failure and the policy opts in. */\nexport function assertEnvelope(body: unknown, policy: RiviniaEnvelopePolicy): void {\n  if (policy.throwOnFailure === false) return;\n  if (typeof body !== 'object' || body === null || Array.isArray(body)) return;\n  const successKey = policy.successKey ?? DEFAULT_SUCCESS_KEY;\n  const record = body as Record<string, unknown>;\n  if (!(successKey in record) || record[successKey] !== false) return;\n  const errorKey = policy.errorKey ?? DEFAULT_ERROR_KEY;\n  throw new RiviniaHttpEnvelopeError(body, record[errorKey]);\n}\n","import type { HttpFeature, HttpFeatureKind } from '@angular/common/http';\nimport { InjectionToken } from '@angular/core';\nimport type { RiviniaEnvelopePolicy } from './http-envelope';\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   * Opt-in backend-envelope validation applied to every call unless the call\n   * provides its own `envelope` (which replaces this wholesale). See\n   * `RiviniaEnvelopePolicy`. Off by default — plain bodies flow untouched.\n   */\n  envelope?: RiviniaEnvelopePolicy;\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 HttpHeaders,\n  type HttpResourceRef,\n  type HttpResponse,\n} from '@angular/common/http';\nimport { Service, computed, inject, isSignal, 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 ReactiveInput,\n  type RiviniaDeleteOptions,\n  type RiviniaRequestOptions,\n} from './http-options';\nimport { unwrapAs } from './http-utils';\nimport { assertEnvelope, type RiviniaEnvelopePolicy } from './http-envelope';\n\n/** Options for `getResource` in addition to per-request options. */\nexport interface RiviniaResourceOptions<T>\n  extends Omit<RiviniaRequestOptions, 'params' | 'headers' | 'context'> {\n  /**\n   * Query params re-evaluated on every request: value, signal, or reactive\n   * function. Anything else in these options is read once per call site —\n   * only the URL, params, headers and context are reactive.\n   */\n  params?: ReactiveInput<QueryParamsInput>;\n  headers?: ReactiveInput<HttpHeaders | Record<string, string | string[]>>;\n  context?: ReactiveInput<HttpContext>;\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 * URLs pass through untouched; the library adds opt-in envelope handling —\n * unwrapping (`unwrap`/`unwrapKey`) and failure validation (`envelope`).\n *\n * Unwrap resolution per call: `options.unwrap ?? config.unwrap ?? false`,\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  /** Plain-text download. Never unwrapped. */\n  getText(endpoint: string, options?: RiviniaRequestOptions): Observable<string> {\n    return this.http.get(this.url(endpoint), {\n      ...this.httpOptions(options),\n      responseType: 'text',\n    });\n  }\n\n  /**\n   * Full response access (status, headers — e.g. pagination counts or a 201\n   * `Location`). Raw body (no unwrapping), but the configured/per-call\n   * `envelope` validation still applies to the body — a globally declared\n   * failure policy must hold on every JSON path, not just the unwrapped ones.\n   */\n  getResponse<T>(endpoint: string, options?: RiviniaRequestOptions): Observable<HttpResponse<T>> {\n    const envelope = this.resolveEnvelope(options);\n    return this.http\n      .get<T>(this.url(endpoint), {\n        ...this.httpOptions(options),\n        observe: 'response',\n      })\n      .pipe(\n        map((res) => {\n          if (envelope) assertEnvelope(res.body, envelope);\n          return res;\n        }),\n      );\n  }\n\n  /**\n   * Full response access for creates (status, `Location` header). Same\n   * envelope-validation rule as `getResponse`; body otherwise raw.\n   */\n  postResponse<T>(\n    endpoint: string,\n    body?: unknown,\n    options?: RiviniaRequestOptions,\n  ): Observable<HttpResponse<T>> {\n    const envelope = this.resolveEnvelope(options);\n    return this.http\n      .post<T>(this.url(endpoint), body, {\n        ...this.httpOptions(options),\n        observe: 'response',\n      })\n      .pipe(\n        map((res) => {\n          if (envelope) assertEnvelope(res.body, envelope);\n          return res;\n        }),\n      );\n  }\n\n  /**\n   * Reactive GET as an `httpResource` (stable since Angular v22).\n   * The endpoint can be a static string, a signal, or a reactive function\n   * (same as `httpResource` itself) — it re-fetches on change, and\n   * `undefined` disables the request. Unwrap applies through `parse`,\n   * composed before a user `parse` if given.\n   */\n  getResource<T>(\n    endpoint: string | Signal<string | undefined> | (() => string | undefined),\n    options?: RiviniaResourceOptions<T>,\n  ): HttpResourceRef<T | undefined> {\n    const { defaultValue, parse, reportProgress, ...requestOptions } = options ?? {};\n    const source: string | Signal<string | undefined> =\n      typeof endpoint === 'function' && !isSignal(endpoint)\n        ? computed(endpoint)\n        : (endpoint as string | Signal<string | undefined>);\n    const request = () => {\n      const ep = typeof source === 'string' ? source : source();\n      if (ep === undefined) return undefined;\n      return {\n        url: this.url(ep),\n        params: this.toParams(resolveInput(requestOptions.params)),\n        headers: resolveInput(requestOptions.headers),\n        context: resolveInput(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 envelope = this.resolveEnvelope(requestOptions);\n    const base = { defaultValue: defaultValue as T | undefined };\n    // Pipeline order: envelope validation (raw) -> unwrap -> user parse.\n    // A throwing envelope surfaces as resource.error() automatically.\n    const applyParse = (raw: unknown): T => {\n      if (envelope) assertEnvelope(raw, envelope);\n      const unwrapped = unwrapEnabled ? unwrapAs<T>(raw, unwrapKey) : (raw as T);\n      return parse ? parse(unwrapped) : unwrapped;\n    };\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\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?: { unwrap?: boolean }): boolean {\n    return options?.unwrap ?? this.config?.unwrap ?? DEFAULT_UNWRAP;\n  }\n\n  private resolveKey(options?: { unwrapKey?: string }): string {\n    return options?.unwrapKey ?? this.config?.unwrapKey ?? DEFAULT_UNWRAP_KEY;\n  }\n\n  private resolveEnvelope(options?: { envelope?: RiviniaEnvelopePolicy }): RiviniaEnvelopePolicy | undefined {\n    return options?.envelope ?? this.config?.envelope;\n  }\n\n  private applyUnwrap<T>(body: unknown, options?: RiviniaRequestOptions): T {\n    const envelope = this.resolveEnvelope(options);\n    if (envelope) assertEnvelope(body, envelope);\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 {    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\n/**\n * Evaluates a reactive input inside the request function: signals are read\n * (tracked), plain functions are called, values pass through.\n */\nfunction resolveInput<T>(value: ReactiveInput<T> | undefined): T | undefined {\n  if (value === undefined) return undefined;\n  if (isSignal(value)) return (value as Signal<T>)();\n  if (typeof value === 'function') return (value as () => T)();\n  return value as T;\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,6 @@
 {
   "name": "@rivinia/http",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Headless typed HTTP client for Angular: envelope unwrapping, plain Observables and httpResource.",
   "keywords": [
     "angular",

package/types/rivinia-http.d.ts

@@ -1,7 +1,36 @@
-import { HttpContext, HttpFeature, HttpFeatureKind, HttpHeaders, HttpParams, HttpResourceRef } from "@angular/common/http";
+import { HttpContext, HttpFeature, HttpFeatureKind, HttpHeaders, HttpParams, HttpResourceRef, HttpResponse } from "@angular/common/http";
 import * as i0 from "@angular/core";
 import { EnvironmentProviders, InjectionToken, Signal } from "@angular/core";
 import { Observable } from "rxjs";
+/**
+ * Typed envelope failure. Thrown when a backend signals failure inside a
+ * successful HTTP response (e.g. `{ data: null, isSuccess: false }` with
+ * HTTP 200) and the envelope policy opts into throwing. In `getResource`
+ * this surfaces as `resource.error()`.
+ */
+export declare class RiviniaHttpEnvelopeError extends Error {
+  /** The raw response body. */
+  readonly body: unknown;
+  /** The machine-readable failure code (`body[errorKey]`), if any. */
+  readonly code: unknown;
+  constructor(body: unknown, code: unknown);
+}
+/**
+ * Opt-in backend-envelope validation. When present (globally or per call),
+ * a response object whose `successKey` is strictly `false` throws
+ * `RiviniaHttpEnvelopeError` instead of flowing into `next()` as success.
+ * Runs on the raw body before unwrapping, independent of `unwrap`.
+ */
+interface RiviniaEnvelopePolicy {
+  /** Body key holding the success flag. @default 'isSuccess' */
+  readonly successKey?: string;
+  /** Body key holding the failure code. @default 'error' */
+  readonly errorKey?: string;
+  /** Throw on failure. Explicit `false` disables (policy becomes passive). @default true */
+  readonly throwOnFailure?: boolean;
+}
+/** Throws when the envelope signals failure and the policy opts in. */
+declare function assertEnvelope(body: unknown, policy: RiviniaEnvelopePolicy): void;
 /**
  * Global configuration for `@rivinia/http`.
  *
@@ -33,6 +62,12 @@ interface RiviniaHttpConfig {
    * `HttpClient` (fetch backend) is injectable by default.
    */
   httpFeatures?: HttpFeature<HttpFeatureKind>[];
+  /**
+   * Opt-in backend-envelope validation applied to every call unless the call
+   * provides its own `envelope` (which replaces this wholesale). See
+   * `RiviniaEnvelopePolicy`. Off by default — plain bodies flow untouched.
+   */
+  envelope?: RiviniaEnvelopePolicy;
 }
 /**
  * Internal configuration token. Consumers must use `provideRiviniaHttp()`.
@@ -41,6 +76,12 @@ interface RiviniaHttpConfig {
 declare const RIVINIA_HTTP_CONFIG: InjectionToken<RiviniaHttpConfig>;
 declare const DEFAULT_UNWRAP = false;
 declare const DEFAULT_UNWRAP_KEY = "data";
+/**
+ * A value, a signal of it, or a reactive function returning it — evaluated
+ * inside the `httpResource` request function, so signal reads stay reactive
+ * (same contract as `httpResource` itself).
+ */
+type ReactiveInput<T> = T | Signal<T> | (() => T);
 /** Shorthand for building query strings; `null`/`undefined` values are dropped. */
 type QueryParamsInput = HttpParams | Record<string, string | number | boolean | undefined | null>;
 /**
@@ -57,12 +98,25 @@ interface RiviniaRequestOptions {
   unwrap?: boolean;
   /** Envelope key for this call (overrides global `unwrapKey`). */
   unwrapKey?: string;
+  /**
+   * Opt-in backend-envelope validation for this call (replaces any global
+   * `envelope` policy wholesale). See `RiviniaEnvelopePolicy`.
+   */
+  envelope?: RiviniaEnvelopePolicy;
 }
 interface RiviniaDeleteOptions extends RiviniaRequestOptions {
   body?: unknown;
 }
 /** Options for `getResource` in addition to per-request options. */
-interface RiviniaResourceOptions<T> extends RiviniaRequestOptions {
+interface RiviniaResourceOptions<T> extends Omit<RiviniaRequestOptions, 'params' | 'headers' | 'context'> {
+  /**
+   * Query params re-evaluated on every request: value, signal, or reactive
+   * function. Anything else in these options is read once per call site —
+   * only the URL, params, headers and context are reactive.
+   */
+  params?: ReactiveInput<QueryParamsInput>;
+  headers?: ReactiveInput<HttpHeaders | Record<string, string | string[]>>;
+  context?: ReactiveInput<HttpContext>;
   /** Value while idle/loading. Defaults to `undefined`. */
   defaultValue?: T;
   /**
@@ -82,10 +136,10 @@ interface RiviniaResourceOptions<T> extends RiviniaRequestOptions {
  *
  * 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.
+ * URLs pass through untouched; the library adds opt-in envelope handling —
+ * unwrapping (`unwrap`/`unwrapKey`) and failure validation (`envelope`).
  *
- * Unwrap resolution per call: `options.unwrap ?? config.unwrap ?? true`,
+ * Unwrap resolution per call: `options.unwrap ?? config.unwrap ?? false`,
  * key: `options.unwrapKey ?? config.unwrapKey ?? 'data'`.
  */
 export declare class RiviniaHttp {
@@ -98,6 +152,20 @@ export declare class RiviniaHttp {
   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>;
+  /** Plain-text download. Never unwrapped. */
+  getText(endpoint: string, options?: RiviniaRequestOptions): Observable<string>;
+  /**
+   * Full response access (status, headers — e.g. pagination counts or a 201
+   * `Location`). Raw body (no unwrapping), but the configured/per-call
+   * `envelope` validation still applies to the body — a globally declared
+   * failure policy must hold on every JSON path, not just the unwrapped ones.
+   */
+  getResponse<T>(endpoint: string, options?: RiviniaRequestOptions): Observable<HttpResponse<T>>;
+  /**
+   * Full response access for creates (status, `Location` header). Same
+   * envelope-validation rule as `getResponse`; body otherwise raw.
+   */
+  postResponse<T>(endpoint: string, body?: unknown, options?: RiviniaRequestOptions): Observable<HttpResponse<T>>;
   /**
    * Reactive GET as an `httpResource` (stable since Angular v22).
    * The endpoint can be a static string, a signal, or a reactive function
@@ -109,6 +177,7 @@ export declare class RiviniaHttp {
   private url;
   private resolveUnwrap;
   private resolveKey;
+  private resolveEnvelope;
   private applyUnwrap;
   private httpOptions;
   private toParams;
@@ -123,7 +192,9 @@ 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.
+ * unchanged. Unwraps EXACTLY ONE level: a payload that itself contains the
+ * key (`{ data: { data: […], page: 1 } }`) is returned whole — recursive
+ * unwrapping silently destroyed sibling fields (data-loss bug, fixed).
  */
 export declare function unwrapAs<T>(body: unknown, key: string): T;
 /**
@@ -148,4 +219,4 @@ export declare function unwrapAs<T>(body: unknown, key: string): T;
 export declare function provideRiviniaHttp(config?: RiviniaHttpConfig): EnvironmentProviders;
 /** Shorthand for `inject(RiviniaHttp)`. */
 export declare function injectRiviniaHttp(): RiviniaHttp;
-export type { QueryParamsInput, RiviniaDeleteOptions, RiviniaHttpConfig, RiviniaRequestOptions, RiviniaResourceOptions };
+export type { QueryParamsInput, ReactiveInput, RiviniaDeleteOptions, RiviniaEnvelopePolicy, RiviniaHttpConfig, RiviniaRequestOptions, RiviniaResourceOptions };