@ogcio/sag-client 0.3.0 → 0.4.1

package/dist/react/index.d.ts

@@ -6,6 +6,8 @@ export { SagClientProvider, useSagClient } from "./provider";
 export { useAuth } from "./use-auth";
 export type { UseGatewayFetchOptions } from "./use-gateway-fetch";
 export { useGatewayFetch } from "./use-gateway-fetch";
+export type { UseGatewayDownloadOptions } from "./use-gateway-download";
+export { useGatewayDownload } from "./use-gateway-download";
 export type { UseGatewayMutationOptions } from "./use-gateway-mutation";
 export { useGatewayMutation } from "./use-gateway-mutation";
 export type { UseOnboardingGuardOptions, UseOnboardingGuardResult, } from "./use-onboarding-guard";

package/dist/react/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,0BAA0B,EAC1B,6BAA6B,EAC7B,kBAAkB,EAClB,eAAe,EACf,uBAAuB,EACvB,uBAAuB,EACvB,4BAA4B,GAC7B,MAAM,eAAe,CAAA;AAEtB,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,4BAA4B,EAC5B,SAAS,EACT,eAAe,EACf,kBAAkB,EAClB,uBAAuB,EACvB,eAAe,EACf,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,2BAA2B,GAC5B,MAAM,UAAU,CAAA;AAEjB,YAAY,EACV,SAAS,EACT,UAAU,EACV,mBAAmB,EACnB,sBAAsB,EACtB,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,aAAa,GACd,MAAM,UAAU,CAAA;AACjB,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,aAAa,GACd,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE5D,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AACpC,YAAY,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAA;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AACrD,YAAY,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAA;AACvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAC3D,YAAY,EACV,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,wBAAwB,CAAA;AAE/B,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAC3D,YAAY,EACV,4BAA4B,EAC5B,2BAA2B,GAC5B,MAAM,4BAA4B,CAAA;AAEnC,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,0BAA0B,EAC1B,6BAA6B,EAC7B,kBAAkB,EAClB,eAAe,EACf,uBAAuB,EACvB,uBAAuB,EACvB,4BAA4B,GAC7B,MAAM,eAAe,CAAA;AAEtB,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,4BAA4B,EAC5B,SAAS,EACT,eAAe,EACf,kBAAkB,EAClB,uBAAuB,EACvB,eAAe,EACf,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,2BAA2B,GAC5B,MAAM,UAAU,CAAA;AAEjB,YAAY,EACV,SAAS,EACT,UAAU,EACV,mBAAmB,EACnB,sBAAsB,EACtB,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,aAAa,GACd,MAAM,UAAU,CAAA;AACjB,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,aAAa,GACd,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE5D,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AACpC,YAAY,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAA;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AACrD,YAAY,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAA;AACvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAC3D,YAAY,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAA;AACvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAC3D,YAAY,EACV,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,wBAAwB,CAAA;AAE/B,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAC3D,YAAY,EACV,4BAA4B,EAC5B,2BAA2B,GAC5B,MAAM,4BAA4B,CAAA;AAEnC,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA"}

package/dist/react/index.js

@@ -8,6 +8,7 @@ export { SagClientProvider, useSagClient } from "./provider";
 // ── Hooks ────────────────────────────────────────────────────
 export { useAuth } from "./use-auth";
 export { useGatewayFetch } from "./use-gateway-fetch";
+export { useGatewayDownload } from "./use-gateway-download";
 export { useGatewayMutation } from "./use-gateway-mutation";
 // ── Onboarding guard (includes citizen check + PS redirect) ──
 export { useOnboardingGuard } from "./use-onboarding-guard";

package/dist/react/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAEhE,+DAA+D;AAC/D,OAAO,EACL,0BAA0B,EAC1B,6BAA6B,EAC7B,kBAAkB,EAClB,eAAe,EACf,uBAAuB,EACvB,uBAAuB,EACvB,4BAA4B,GAC7B,MAAM,eAAe,CAAA;AACtB,+DAA+D;AAC/D,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,4BAA4B,EAC5B,SAAS,EACT,eAAe,EACf,kBAAkB,EAClB,uBAAuB,EACvB,eAAe,EACf,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,2BAA2B,GAC5B,MAAM,UAAU,CAAA;AAYjB,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,aAAa,GACd,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC5D,gEAAgE;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAEpC,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAErD,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAK3D,gEAAgE;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAK3D,gEAAgE;AAChE,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAEhE,+DAA+D;AAC/D,OAAO,EACL,0BAA0B,EAC1B,6BAA6B,EAC7B,kBAAkB,EAClB,eAAe,EACf,uBAAuB,EACvB,uBAAuB,EACvB,4BAA4B,GAC7B,MAAM,eAAe,CAAA;AACtB,+DAA+D;AAC/D,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,4BAA4B,EAC5B,SAAS,EACT,eAAe,EACf,kBAAkB,EAClB,uBAAuB,EACvB,eAAe,EACf,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,2BAA2B,GAC5B,MAAM,UAAU,CAAA;AAYjB,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,aAAa,GACd,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC5D,gEAAgE;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAEpC,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAErD,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAE3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAK3D,gEAAgE;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAK3D,gEAAgE;AAChE,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA"}

package/dist/react/use-gateway-download.d.ts

@@ -0,0 +1,19 @@
+import { type ActorType, SagFetchError } from "../types";
+export interface UseGatewayDownloadOptions {
+    actorType?: ActorType;
+}
+export interface UseGatewayDownloadResult {
+    download: (path: string, filename: string) => Promise<void>;
+    isDownloading: boolean;
+    error: SagFetchError | null;
+}
+/**
+ * Hook that returns an authenticated `download(path, filename)` function
+ * for fetching binary files through the Secure API Gateway.
+ *
+ * The file is fetched as a blob, then offered to the browser via a
+ * temporary object URL. Auth handling (401 / session-expired) mirrors
+ * `useGatewayFetch`.
+ */
+export declare function useGatewayDownload(options?: UseGatewayDownloadOptions): UseGatewayDownloadResult;
+//# sourceMappingURL=use-gateway-download.d.ts.map

package/dist/react/use-gateway-download.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-gateway-download.d.ts","sourceRoot":"","sources":["../../src/react/use-gateway-download.ts"],"names":[],"mappings":"AAIA,OAAO,EAAqB,KAAK,SAAS,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAG3E,MAAM,WAAW,yBAAyB;IACxC,SAAS,CAAC,EAAE,SAAS,CAAA;CACtB;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3D,aAAa,EAAE,OAAO,CAAA;IACtB,KAAK,EAAE,aAAa,GAAG,IAAI,CAAA;CAC5B;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,CAAC,EAAE,yBAAyB,GAClC,wBAAwB,CAmF1B"}

package/dist/react/use-gateway-download.js

@@ -0,0 +1,81 @@
+"use client";
+import { useCallback, useState } from "react";
+import { signIn } from "../auth";
+import { ACTOR_TYPE_HEADER, SagFetchError } from "../types";
+import { useSagClient } from "./provider";
+/**
+ * Hook that returns an authenticated `download(path, filename)` function
+ * for fetching binary files through the Secure API Gateway.
+ *
+ * The file is fetched as a blob, then offered to the browser via a
+ * temporary object URL. Auth handling (401 / session-expired) mirrors
+ * `useGatewayFetch`.
+ */
+export function useGatewayDownload(options) {
+    const client = useSagClient();
+    const [isDownloading, setIsDownloading] = useState(false);
+    const [error, setError] = useState(null);
+    const download = useCallback(async (path, filename) => {
+        setIsDownloading(true);
+        setError(null);
+        try {
+            const url = `${client.gatewayUrl}${path}`;
+            const headers = {
+                "X-Application": client.appName,
+            };
+            if (options === null || options === void 0 ? void 0 : options.actorType) {
+                headers[ACTOR_TYPE_HEADER] = options.actorType;
+            }
+            const response = await fetch(url, {
+                credentials: "include",
+                headers,
+            });
+            if (response.status === 401) {
+                signIn(client.gatewayUrl, client.appName);
+                throw new SagFetchError("Session expired. Redirecting to sign in\u2026", 401);
+            }
+            if (!response.ok) {
+                let message = `HTTP error! status: ${response.status} ${response.statusText}`;
+                let code;
+                try {
+                    const body = (await response.json());
+                    if (body.details)
+                        message = body.details;
+                    else if (body.error)
+                        message = body.error;
+                    if (body.code)
+                        code = body.code;
+                }
+                catch (_a) {
+                    // non-JSON body
+                }
+                throw new SagFetchError(message, response.status, code);
+            }
+            const blob = await response.blob();
+            const objectUrl = URL.createObjectURL(blob);
+            const anchor = document.createElement("a");
+            anchor.href = objectUrl;
+            anchor.download = filename;
+            anchor.style.display = "none";
+            document.body.appendChild(anchor);
+            anchor.click();
+            // Clean up after a tick so the browser has time to start the download
+            setTimeout(() => {
+                URL.revokeObjectURL(objectUrl);
+                document.body.removeChild(anchor);
+            }, 100);
+        }
+        catch (err) {
+            const sagError = err instanceof SagFetchError
+                ? err
+                : new SagFetchError(err instanceof Error ? err.message : "Download failed", 0);
+            setError(sagError);
+            throw sagError;
+        }
+        finally {
+            setIsDownloading(false);
+        }
+    }, [client, options === null || options === void 0 ? void 0 : options.actorType]);
+    return { download, isDownloading, error };
+}
+//# sourceMappingURL=use-gateway-download.js.map

package/dist/react/use-gateway-download.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-gateway-download.js","sourceRoot":"","sources":["../../src/react/use-gateway-download.ts"],"names":[],"mappings":"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"}

package/dist/react/use-gateway-fetch.d.ts

@@ -15,15 +15,27 @@ export interface UseGatewayFetchOptions {
  *
  * Must be used within a `SagClientProvider`.
  *
+ * The gateway API convention wraps responses as `{ data: T }`. For paginated
+ * endpoints that also return a `metadata` field alongside `data` (e.g.
+ * `{ data: T[], metadata: { totalCount: number } }`), provide the second type
+ * parameter `M` to get a typed `metadata` value back from the hook:
+ *
+ * ```ts
+ * const { data: items, metadata } =
+ *   useGatewayFetch<Item[], { totalCount?: number }>("/api/v1/items")
+ * ```
+ *
  * @param path    - Gateway path (e.g. "/cars", "/weather", "/notifications")
  * @param options - Fetch options (enabled, actorType)
  */
-export declare function useGatewayFetch<T>(path: string | null, options?: UseGatewayFetchOptions): {
+export declare function useGatewayFetch<T, M = undefined>(path: string | null, options?: UseGatewayFetchOptions): {
     data: T | undefined;
+    metadata: M | undefined;
     error: any;
     isLoading: boolean;
     refresh: import("swr").KeyedMutator<{
         data: T;
+        metadata?: M;
     }>;
 };
 //# sourceMappingURL=use-gateway-fetch.d.ts.map

package/dist/react/use-gateway-fetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-gateway-fetch.d.ts","sourceRoot":"","sources":["../../src/react/use-gateway-fetch.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAGzC,8CAA8C;AAC9C,MAAM,WAAW,sBAAsB;IACrC,6CAA6C;IAC7C,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAA;CACtB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,OAAO,CAAC,EAAE,sBAAsB;;;;;cAiC0B,CAAC;;EAW5D"}
+{"version":3,"file":"use-gateway-fetch.d.ts","sourceRoot":"","sources":["../../src/react/use-gateway-fetch.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAGzC,8CAA8C;AAC9C,MAAM,WAAW,sBAAsB;IACrC,6CAA6C;IAC7C,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAA;CACtB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,CAAC,GAAG,SAAS,EAC9C,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,OAAO,CAAC,EAAE,sBAAsB;;;;;;cAmC0B,CAAC;mBAAa,CAAC;;EAY1E"}

package/dist/react/use-gateway-fetch.js

@@ -7,6 +7,16 @@ import { useSagClient } from "./provider";
  *
  * Must be used within a `SagClientProvider`.
  *
+ * The gateway API convention wraps responses as `{ data: T }`. For paginated
+ * endpoints that also return a `metadata` field alongside `data` (e.g.
+ * `{ data: T[], metadata: { totalCount: number } }`), provide the second type
+ * parameter `M` to get a typed `metadata` value back from the hook:
+ *
+ * ```ts
+ * const { data: items, metadata } =
+ *   useGatewayFetch<Item[], { totalCount?: number }>("/api/v1/items")
+ * ```
+ *
  * @param path    - Gateway path (e.g. "/cars", "/weather", "/notifications")
  * @param options - Fetch options (enabled, actorType)
  */
@@ -36,9 +46,12 @@ export function useGatewayFetch(path, options) {
         const inner = fetcher;
         return (keyOrUrl) => inner(Array.isArray(keyOrUrl) ? keyOrUrl[0] : keyOrUrl);
     }, [fetcher]);
+    // The SWR value type is the full API response shape. `metadata` is optional
+    // so the fetcher's `{ data: T }` return is assignable to `{ data: T; metadata?: M }`.
     const { data, error, isLoading, mutate } = useSWR(swrKey, wrappedFetcher);
     return {
         data: data === null || data === void 0 ? void 0 : data.data,
+        metadata: data === null || data === void 0 ? void 0 : data.metadata,
         error,
         isLoading,
         refresh: mutate,

package/dist/react/use-gateway-fetch.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-gateway-fetch.js","sourceRoot":"","sources":["../../src/react/use-gateway-fetch.ts"],"names":[],"mappings":"AAAA,YAAY,CAAA;AAEZ,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAA;AAC/B,OAAO,MAAM,MAAM,KAAK,CAAA;AAExB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAczC;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAmB,EACnB,OAAgC;;IAEhC,MAAM,MAAM,GAAG,YAAY,EAAE,CAAA;IAC7B,MAAM,OAAO,GAAG,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,OAAO,mCAAI,IAAI,CAAA;IACxC,MAAM,SAAS,GAAG,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,SAAS,CAAA;IAEpC,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,EAAE;QAC/B,IAAI,CAAC,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO,IAAI,CAAA;QAClC,OAAO,GAAG,MAAM,CAAC,UAAU,GAAG,IAAI,EAAE,CAAA;IACtC,CAAC,EAAE,CAAC,MAAM,CAAC,UAAU,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAA;IAEtC,sEAAsE;IACtE,iEAAiE;IACjE,mEAAmE;IACnE,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE;QAC1B,IAAI,CAAC,WAAW;YAAE,OAAO,IAAI,CAAA;QAC7B,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,WAAW,CAAA;IAC3D,CAAC,EAAE,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC,CAAA;IAE5B,MAAM,OAAO,GAAG,OAAO,CACrB,GAAG,EAAE,CAAC,MAAM,CAAC,aAAa,CAAI,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,EACpE,CAAC,MAAM,EAAE,SAAS,CAAC,CACpB,CAAA;IAED,iEAAiE;IACjE,mEAAmE;IACnE,oEAAoE;IACpE,MAAM,cAAc,GAAG,OAAO,CAAC,GAAG,EAAE;QAClC,MAAM,KAAK,GAAG,OAAO,CAAA;QACrB,OAAO,CAAC,QAAyC,EAAE,EAAE,CACnD,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAA;IAC3D,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAA;IAEb,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAC/C,MAAM,EACN,cAAc,CACf,CAAA;IAED,OAAO;QACL,IAAI,EAAE,IAAI,aAAJ,IAAI,uBAAJ,IAAI,CAAE,IAAI;QAChB,KAAK;QACL,SAAS;QACT,OAAO,EAAE,MAAM;KAChB,CAAA;AACH,CAAC"}
+{"version":3,"file":"use-gateway-fetch.js","sourceRoot":"","sources":["../../src/react/use-gateway-fetch.ts"],"names":[],"mappings":"AAAA,YAAY,CAAA;AAEZ,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAA;AAC/B,OAAO,MAAM,MAAM,KAAK,CAAA;AAExB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAczC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAmB,EACnB,OAAgC;;IAEhC,MAAM,MAAM,GAAG,YAAY,EAAE,CAAA;IAC7B,MAAM,OAAO,GAAG,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,OAAO,mCAAI,IAAI,CAAA;IACxC,MAAM,SAAS,GAAG,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,SAAS,CAAA;IAEpC,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,EAAE;QAC/B,IAAI,CAAC,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO,IAAI,CAAA;QAClC,OAAO,GAAG,MAAM,CAAC,UAAU,GAAG,IAAI,EAAE,CAAA;IACtC,CAAC,EAAE,CAAC,MAAM,CAAC,UAAU,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAA;IAEtC,sEAAsE;IACtE,iEAAiE;IACjE,mEAAmE;IACnE,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE;QAC1B,IAAI,CAAC,WAAW;YAAE,OAAO,IAAI,CAAA;QAC7B,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,WAAW,CAAA;IAC3D,CAAC,EAAE,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC,CAAA;IAE5B,MAAM,OAAO,GAAG,OAAO,CACrB,GAAG,EAAE,CAAC,MAAM,CAAC,aAAa,CAAI,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,EACpE,CAAC,MAAM,EAAE,SAAS,CAAC,CACpB,CAAA;IAED,iEAAiE;IACjE,mEAAmE;IACnE,oEAAoE;IACpE,MAAM,cAAc,GAAG,OAAO,CAAC,GAAG,EAAE;QAClC,MAAM,KAAK,GAAG,OAAO,CAAA;QACrB,OAAO,CAAC,QAAyC,EAAE,EAAE,CACnD,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAA;IAC3D,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAA;IAEb,4EAA4E;IAC5E,sFAAsF;IACtF,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAC/C,MAAM,EACN,cAAc,CACf,CAAA;IAED,OAAO;QACL,IAAI,EAAE,IAAI,aAAJ,IAAI,uBAAJ,IAAI,CAAE,IAAI;QAChB,QAAQ,EAAE,IAAI,aAAJ,IAAI,uBAAJ,IAAI,CAAE,QAAQ;QACxB,KAAK;QACL,SAAS;QACT,OAAO,EAAE,MAAM;KAChB,CAAA;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ogcio/sag-client",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Framework-agnostic client for the Secure API Gateway — authentication, health checks, and authenticated fetching",
   "type": "module",
   "private": false,