@ogcio/sag-client 0.2.0 → 0.3.0

package/dist/onboarding.d.ts

@@ -36,7 +36,7 @@ export interface OnboardingRedirectParams {
     appBaseUrl: string;
     /**
      * Logto directSignIn connector to use when the user comes back
-     * from onboarding (e.g. "social:mygovid"). Optional.
+     * from onboarding (e.g. CONNECTOR_MYGOVID). Optional.
      */
     connector?: string;
 }

package/dist/react/index.d.ts

@@ -1,5 +1,5 @@
 export { buildOnboardingRedirectUrl, buildWrongLoginMethodRedirect, CLEAR_SESSION_PATH, ONBOARDING_PATH, ONBOARDING_SOURCE_PARAM, WRONG_LOGIN_METHOD_PATH, WRONG_LOGIN_RETURN_URL_PARAM, } from "../onboarding";
-export { ALLOWED_SIGNIN_METHODS, CONNECTOR_ENTRAID, CONNECTOR_MYGOVID, DEFAULT_PUBLIC_SERVANT_ROLES, isCitizen, isCitizenOnboarded, isInactivePublicServant, isPublicServant, ORG_ROLE_ADMIN, ORG_ROLE_MEMBER, } from "../roles";
+export { ALLOWED_SIGNIN_METHODS, CONNECTOR_ENTRAID, CONNECTOR_MYGOVID, DEFAULT_PUBLIC_SERVANT_ROLES, isCitizen, isCitizenByRole, isCitizenOnboarded, isInactivePublicServant, isPublicServant, ORG_ROLE_ADMIN, ORG_ROLE_MEMBER, ROLE_NAME_CITIZEN, ROLE_NAME_ONBOARDED_CITIZEN, } from "../roles";
 export type { ActorType, AuthClaims, GatewayFetchOptions, GatewayMutationOptions, MutationMethod, OrganizationInfo, SignInOptions, UseAuthResult, } from "../types";
 export { ACTOR_TYPE_HEADER, ORGANIZATION_ID_HEADER, SagFetchError, } from "../types";
 export { SagClientProvider, useSagClient } from "./provider";

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,kBAAkB,EAClB,uBAAuB,EACvB,eAAe,EACf,cAAc,EACd,eAAe,GAChB,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,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

@@ -2,14 +2,14 @@
 // ── Re-export onboarding helpers for convenience ────────────
 export { buildOnboardingRedirectUrl, buildWrongLoginMethodRedirect, CLEAR_SESSION_PATH, ONBOARDING_PATH, ONBOARDING_SOURCE_PARAM, WRONG_LOGIN_METHOD_PATH, WRONG_LOGIN_RETURN_URL_PARAM, } from "../onboarding";
 // ── Re-export role detection utilities for convenience ──────
-export { ALLOWED_SIGNIN_METHODS, CONNECTOR_ENTRAID, CONNECTOR_MYGOVID, DEFAULT_PUBLIC_SERVANT_ROLES, isCitizen, isCitizenOnboarded, isInactivePublicServant, isPublicServant, ORG_ROLE_ADMIN, ORG_ROLE_MEMBER, } from "../roles";
+export { ALLOWED_SIGNIN_METHODS, CONNECTOR_ENTRAID, CONNECTOR_MYGOVID, DEFAULT_PUBLIC_SERVANT_ROLES, isCitizen, isCitizenByRole, isCitizenOnboarded, isInactivePublicServant, isPublicServant, ORG_ROLE_ADMIN, ORG_ROLE_MEMBER, ROLE_NAME_CITIZEN, ROLE_NAME_ONBOARDED_CITIZEN, } from "../roles";
 export { ACTOR_TYPE_HEADER, ORGANIZATION_ID_HEADER, SagFetchError, } from "../types";
 export { SagClientProvider, useSagClient } from "./provider";
 // ── Hooks ────────────────────────────────────────────────────
 export { useAuth } from "./use-auth";
 export { useGatewayFetch } from "./use-gateway-fetch";
 export { useGatewayMutation } from "./use-gateway-mutation";
-// ── Onboarding guard ─────────────────────────────────────────
+// ── Onboarding guard (includes citizen check + PS redirect) ──
 export { useOnboardingGuard } from "./use-onboarding-guard";
 // ── Public servant guard ─────────────────────────────────────
 export { usePublicServantGuard } from "./use-public-servant-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,kBAAkB,EAClB,uBAAuB,EACvB,eAAe,EACf,cAAc,EACd,eAAe,GAChB,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;AAK3D,gEAAgE;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAK3D,gEAAgE;AAChE,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA"}

package/dist/react/use-onboarding-guard.d.ts

@@ -9,16 +9,19 @@ export interface UseOnboardingGuardOptions {
      */
     appBaseUrl: string;
     /**
-     * Role names that identify an active public servant.
-     * Citizens are users who do NOT hold any of these organisation roles.
+     * When set, authenticated users who are NOT citizens (i.e. public servants
+     * of any kind) are redirected here immediately, before any other check.
      *
-     * @default DEFAULT_PUBLIC_SERVANT_ROLES — `["Organisation Admin", "Organisation Member"]`
-     * @example ["Organisation Admin", "Organisation Member"]
+     * Use for citizen-only apps that have a companion admin app.
+     * The check is based on `organization_roles`: any user with org membership
+     * is treated as a PS (active or inactive); citizens have zero org roles.
+     *
+     * @example publicServantRedirectUrl: "https://admin.example.com"
      */
-    publicServantRoles?: string[];
+    publicServantRedirectUrl?: string;
     /**
      * Logto `directSignIn` connector to use when the user comes back
-     * from onboarding (e.g. "social:mygovid"). Optional.
+     * from onboarding (e.g. CONNECTOR_MYGOVID). Optional.
      */
     connector?: string;
     /**
@@ -47,41 +50,52 @@ export interface UseOnboardingGuardResult {
     resolved: boolean;
 }
 /**
- * Onboarding guard hook for citizen-facing applications.
+ * Login / onboarding guard hook for citizen-facing applications.
  *
  * Must be used within a `SagClientProvider`.  Internally calls
  * `useAuth()` for auth state and `useSagClient()` for the gateway
  * URL and app name.
  *
- * **Behaviour:**
+ * **Behaviour (in order):**
  *
- * 1. If the user is not a citizen → resolved (let them through).
- * 2. If the user signed in with a wrong method → redirect to the
- *    profile service's error page (checked for ALL citizens,
- *    including onboarded ones).
- * 3. If the user is onboarded (`isCitizenOnboarded`) → resolved.
- * 4. If a redirect happened less than `debounceMs` ago → resolved
+ * 1. If the user is not authenticated → resolved (let sign-in render).
+ * 2. If `publicServantRedirectUrl` is set and the user has org membership
+ *    (`organization_roles.length > 0`) → redirect to `publicServantRedirectUrl`.
+ * 3. If the user is a PS and no redirect is configured →
+ *    resolved (pass-through for PS on non-citizen-locked apps).
+ * 4. If the user signed in with a wrong method → redirect to the
+ *    profile service's error page.
+ * 5. If the user is onboarded → resolved.
+ * 6. If a redirect happened less than `debounceMs` ago → resolved
  *    (prevents infinite loops).
- * 5. If the user is a citizen who has not completed onboarding →
+ * 7. If the user is a citizen who has not completed onboarding →
  *    invalidate the server session and redirect to the profile
  *    service's onboarding page.
  *
- * While the check is pending or a redirect is in flight, `resolved`
- * remains `false`.  The consuming component should gate children
- * behind `resolved` to prevent `useGatewayFetch` from firing.
+ * The citizen check uses `organization_roles` (not user-level `roles`),
+ * so it correctly handles dev environments where the same account holds
+ * both a citizen role and PS org membership.
  *
  * @example
  * ```tsx
+ * // Citizen-only app with a companion admin app:
  * function Shell({ children }) {
- *   // publicServantRoles defaults to DEFAULT_PUBLIC_SERVANT_ROLES
- *   // (["Organisation Admin", "Organisation Member"])
  *   const { resolved } = useOnboardingGuard({
  *     profileUrl: "http://localhost:3001",
  *     appBaseUrl: "http://localhost:3000",
+ *     publicServantRedirectUrl: "http://localhost:3022",
  *     connector: CONNECTOR_MYGOVID,
  *   })
- *   const { user, signIn, signOut } = useAuth()
+ *   if (!resolved) return <Loading />
+ *   return user ? <App>{children}</App> : <SignInButton />
+ * }
  *
+ * // Citizen-only app without a companion admin app:
+ * function Shell({ children }) {
+ *   const { resolved } = useOnboardingGuard({
+ *     profileUrl: "http://localhost:3001",
+ *     appBaseUrl: "http://localhost:3000",
+ *   })
  *   if (!resolved) return <Loading />
  *   return user ? <App>{children}</App> : <SignInButton />
  * }

package/dist/react/use-onboarding-guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-onboarding-guard.d.ts","sourceRoot":"","sources":["../../src/react/use-onboarding-guard.ts"],"names":[],"mappings":"AAuBA,iDAAiD;AACjD,MAAM,WAAW,yBAAyB;IACxC,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAA;IAElB;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAA;IAElB;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAA;IAE7B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,4CAA4C;AAC5C,MAAM,WAAW,wBAAwB;IACvC;;;;;;;;;;;OAWG;IACH,QAAQ,EAAE,OAAO,CAAA;CAClB;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,yBAAyB,GACjC,wBAAwB,CA6G1B"}
+{"version":3,"file":"use-onboarding-guard.d.ts","sourceRoot":"","sources":["../../src/react/use-onboarding-guard.ts"],"names":[],"mappings":"AAkBA,iDAAiD;AACjD,MAAM,WAAW,yBAAyB;IACxC,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAA;IAElB;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAA;IAElB;;;;;;;;;OASG;IACH,wBAAwB,CAAC,EAAE,MAAM,CAAA;IAEjC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,4CAA4C;AAC5C,MAAM,WAAW,wBAAwB;IACvC;;;;;;;;;;;OAWG;IACH,QAAQ,EAAE,OAAO,CAAA;CAClB;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,yBAAyB,GACjC,wBAAwB,CAuG1B"}

package/dist/react/use-onboarding-guard.js

@@ -1,7 +1,7 @@
 "use client";
 import { useEffect, useRef, useState } from "react";
 import { buildOnboardingRedirectUrl, buildWrongLoginMethodRedirect, } from "../onboarding";
-import { ALLOWED_SIGNIN_METHODS, DEFAULT_PUBLIC_SERVANT_ROLES, isCitizen, isCitizenOnboarded, } from "../roles";
+import { ALLOWED_SIGNIN_METHODS, isCitizenOnboarded } from "../roles";
 import { useSagClient } from "./provider";
 import { useAuth } from "./use-auth";
 // ── Constants ───────────────────────────────────────────────
@@ -9,81 +9,89 @@ const ONBOARDING_STORAGE_KEY = "sag_onboarding_ts";
 const DEFAULT_DEBOUNCE_MS = 30000; // 30 seconds
 // ── Hook ────────────────────────────────────────────────────
 /**
- * Onboarding guard hook for citizen-facing applications.
+ * Login / onboarding guard hook for citizen-facing applications.
  *
  * Must be used within a `SagClientProvider`.  Internally calls
  * `useAuth()` for auth state and `useSagClient()` for the gateway
  * URL and app name.
  *
- * **Behaviour:**
+ * **Behaviour (in order):**
  *
- * 1. If the user is not a citizen → resolved (let them through).
- * 2. If the user signed in with a wrong method → redirect to the
- *    profile service's error page (checked for ALL citizens,
- *    including onboarded ones).
- * 3. If the user is onboarded (`isCitizenOnboarded`) → resolved.
- * 4. If a redirect happened less than `debounceMs` ago → resolved
+ * 1. If the user is not authenticated → resolved (let sign-in render).
+ * 2. If `publicServantRedirectUrl` is set and the user has org membership
+ *    (`organization_roles.length > 0`) → redirect to `publicServantRedirectUrl`.
+ * 3. If the user is a PS and no redirect is configured →
+ *    resolved (pass-through for PS on non-citizen-locked apps).
+ * 4. If the user signed in with a wrong method → redirect to the
+ *    profile service's error page.
+ * 5. If the user is onboarded → resolved.
+ * 6. If a redirect happened less than `debounceMs` ago → resolved
  *    (prevents infinite loops).
- * 5. If the user is a citizen who has not completed onboarding →
+ * 7. If the user is a citizen who has not completed onboarding →
  *    invalidate the server session and redirect to the profile
  *    service's onboarding page.
  *
- * While the check is pending or a redirect is in flight, `resolved`
- * remains `false`.  The consuming component should gate children
- * behind `resolved` to prevent `useGatewayFetch` from firing.
+ * The citizen check uses `organization_roles` (not user-level `roles`),
+ * so it correctly handles dev environments where the same account holds
+ * both a citizen role and PS org membership.
  *
  * @example
  * ```tsx
+ * // Citizen-only app with a companion admin app:
  * function Shell({ children }) {
- *   // publicServantRoles defaults to DEFAULT_PUBLIC_SERVANT_ROLES
- *   // (["Organisation Admin", "Organisation Member"])
  *   const { resolved } = useOnboardingGuard({
  *     profileUrl: "http://localhost:3001",
  *     appBaseUrl: "http://localhost:3000",
+ *     publicServantRedirectUrl: "http://localhost:3022",
  *     connector: CONNECTOR_MYGOVID,
  *   })
- *   const { user, signIn, signOut } = useAuth()
+ *   if (!resolved) return <Loading />
+ *   return user ? <App>{children}</App> : <SignInButton />
+ * }
  *
+ * // Citizen-only app without a companion admin app:
+ * function Shell({ children }) {
+ *   const { resolved } = useOnboardingGuard({
+ *     profileUrl: "http://localhost:3001",
+ *     appBaseUrl: "http://localhost:3000",
+ *   })
  *   if (!resolved) return <Loading />
  *   return user ? <App>{children}</App> : <SignInButton />
  * }
  * ```
  */
 export function useOnboardingGuard(options) {
-    const { profileUrl, appBaseUrl, publicServantRoles, connector, debounceMs = DEFAULT_DEBOUNCE_MS, } = options;
-    // Keep the roles in a ref so the effect dependency list stays stable.
-    // A new array reference from the caller (or the default spread) won't
-    // re-trigger the effect — only the ref's `.current` is read inside.
-    const rolesRef = useRef(publicServantRoles !== null && publicServantRoles !== void 0 ? publicServantRoles : [...DEFAULT_PUBLIC_SERVANT_ROLES]);
-    rolesRef.current = publicServantRoles !== null && publicServantRoles !== void 0 ? publicServantRoles : [...DEFAULT_PUBLIC_SERVANT_ROLES];
+    const { profileUrl, appBaseUrl, publicServantRedirectUrl, connector, debounceMs = DEFAULT_DEBOUNCE_MS, } = options;
     const client = useSagClient();
     const { user, claims, loading, invalidateSession } = useAuth();
     const [resolved, setResolved] = useState(false);
-    // Once we've started redirecting (invalidate + location change),
-    // never allow resolved to flip back to true — even if the effect
-    // re-fires before the browser finishes navigating.
     const redirectingRef = useRef(false);
     useEffect(() => {
-        var _a;
         if (loading)
             return;
         if (redirectingRef.current)
             return;
-        // Not authenticated — no onboarding needed
+        // 1. Not authenticated — no checks needed
         if (!user || !claims) {
             setResolved(true);
             return;
         }
-        const orgRoles = (_a = claims.organization_roles) !== null && _a !== void 0 ? _a : [];
-        // 1. Not a citizen — let them through (public servants use different
-        //    sign-in methods so the signinMethod check doesn't apply)
-        if (!isCitizen(orgRoles, rolesRef.current)) {
+        // A user with any org membership is a PS (active or inactive).
+        // Citizens have zero org roles. This correctly handles dev users who
+        // hold both a "citizen" user-role and PS org roles simultaneously.
+        const isACitizen = claims.organization_roles.length === 0;
+        // 2. Not a citizen (public servant of any kind)
+        if (!isACitizen) {
+            if (publicServantRedirectUrl) {
+                redirectingRef.current = true;
+                window.location.href = publicServantRedirectUrl;
+                return;
+            }
+            // No redirect configured — let them through
             setResolved(true);
             return;
         }
-        // 2. Wrong login method — checked for ALL citizens (including
-        //    onboarded ones) to enforce that citizens always use MyGovID.
-        //    This mirrors the original authorisation package's ordering.
+        // 3. Wrong login method — checked for ALL citizens (including onboarded)
         const signinMethod = claims.signinMethod;
         if (signinMethod &&
             !ALLOWED_SIGNIN_METHODS.includes(signinMethod)) {
@@ -95,21 +103,19 @@ export function useOnboardingGuard(options) {
             });
             return;
         }
-        // 3. Citizen who has completed onboarding — clear debounce, proceed
+        // 4. Citizen who has completed onboarding — clear debounce, proceed
         if (isCitizenOnboarded(claims.roles)) {
             sessionStorage.removeItem(ONBOARDING_STORAGE_KEY);
             setResolved(true);
             return;
         }
-        // 4. Debounce — if we recently redirected, don't loop
+        // 5. Debounce — if we recently redirected, don't loop
         const lastTs = Number(sessionStorage.getItem(ONBOARDING_STORAGE_KEY) || "0");
         if (Date.now() - lastTs < debounceMs) {
             setResolved(true);
             return;
         }
-        // 5. Citizen not onboarded — invalidate session and redirect.
-        //    Lock the guard immediately so no subsequent effect run can
-        //    set resolved=true and allow children to render.
+        // 6. Citizen not onboarded — invalidate session and redirect.
         redirectingRef.current = true;
         sessionStorage.setItem(ONBOARDING_STORAGE_KEY, String(Date.now()));
         const url = buildOnboardingRedirectUrl({
@@ -130,6 +136,7 @@ export function useOnboardingGuard(options) {
         invalidateSession,
         profileUrl,
         appBaseUrl,
+        publicServantRedirectUrl,
         connector,
         debounceMs,
         client.gatewayUrl,

package/dist/react/use-onboarding-guard.js.map

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

package/dist/roles.d.ts

@@ -8,13 +8,27 @@
  */
 /** Default organization role string for inactive public servants. */
 export declare const INACTIVE_PS_ORG_ROLE = "inactive-ps-org:Inactive Public Servant";
+/** Logto role name assigned to a citizen at registration (before onboarding). */
+export declare const ROLE_NAME_CITIZEN = "citizen";
 /** Default Logto role name assigned after citizen onboarding. */
 export declare const ROLE_NAME_ONBOARDED_CITIZEN = "Onboarded citizen";
-/** Logto directSignIn value for MyGovID social connector. */
-export declare const CONNECTOR_MYGOVID = "social:mygovid";
-/** Logto directSignIn value for Entra ID social connector. */
-export declare const CONNECTOR_ENTRAID = "social:ogcio-entraid";
-/** Sign-in methods that are considered valid for citizen flows. */
+/**
+ * Logto directSignIn value for MyGovID social connector.
+ * Must match the connector's `target` (Identity provider name) in Logto,
+ * NOT the connector `id`.
+ */
+export declare const CONNECTOR_MYGOVID = "social:MyGovId (MyGovId connector)";
+/**
+ * Logto directSignIn value for Entra ID social connector.
+ * Must match the connector's `target` (Identity provider name) in Logto,
+ * NOT the connector `id`.
+ */
+export declare const CONNECTOR_ENTRAID = "social:OGCIO EntraID";
+/**
+ * Sign-in methods that are considered valid for citizen flows.
+ * These use connector `id` (not `target`) because the custom JWT claim
+ * `signInMethod` is built from `record.connectorId`.
+ */
 export declare const ALLOWED_SIGNIN_METHODS: readonly ["social:mygovid"];
 /** Organisation role name for organisation administrators. */
 export declare const ORG_ROLE_ADMIN = "Organisation Admin";
@@ -57,6 +71,23 @@ export declare function isPublicServant(orgRoles: string[] | null | undefined, e
  * servant nor an active public servant.
  */
 export declare function isCitizen(orgRoles: string[] | null | undefined, expectedPublicServantRoles: string[]): boolean;
+/**
+ * Check whether the user is a citizen (active or inactive) based on the
+ * ID-token `roles` claim — without needing to know any app-specific
+ * public-servant role names.
+ *
+ * A user is a citizen when their `roles` includes either the pre-onboarding
+ * citizen role (`"citizen"`) or the onboarded-citizen role (`"Onboarded citizen"`).
+ * Anyone without either role is considered a public servant (of any kind).
+ *
+ * Prefer this over `isCitizen(orgRoles, expectedRoles)` for citizen-facing
+ * apps, as it is universal across all applications.
+ *
+ * @param roles              `roles` claim from the ID token.
+ * @param citizenRoleName    Override the default citizen role name.
+ * @param onboardedRoleName  Override the default onboarded-citizen role name.
+ */
+export declare function isCitizenByRole(roles: string[] | null | undefined, citizenRoleName?: string, onboardedRoleName?: string): boolean;
 /**
  * Check whether the citizen has completed onboarding.
  *

package/dist/roles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"roles.d.ts","sourceRoot":"","sources":["../src/roles.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,qEAAqE;AACrE,eAAO,MAAM,oBAAoB,4CAA4C,CAAA;AAE7E,iEAAiE;AACjE,eAAO,MAAM,2BAA2B,sBAAsB,CAAA;AAE9D,6DAA6D;AAC7D,eAAO,MAAM,iBAAiB,mBAAmB,CAAA;AAEjD,8DAA8D;AAC9D,eAAO,MAAM,iBAAiB,yBAAyB,CAAA;AAEvD,mEAAmE;AACnE,eAAO,MAAM,sBAAsB,6BAA8B,CAAA;AAQjE,8DAA8D;AAC9D,eAAO,MAAM,cAAc,uBAAuB,CAAA;AAElD,+DAA+D;AAC/D,eAAO,MAAM,eAAe,wBAAwB,CAAA;AAEpD;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B,wDAG/B,CAAA;AAIV;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,EACrC,eAAe,GAAE,MAA6B,GAC7C,OAAO,CAET;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,EACrC,aAAa,EAAE,MAAM,EAAE,GACtB,OAAO,CAMT;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,EACrC,0BAA0B,EAAE,MAAM,EAAE,GACnC,OAAO,CAKT;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,EAClC,iBAAiB,GAAE,MAAoC,GACtD,OAAO,CAET"}
+{"version":3,"file":"roles.d.ts","sourceRoot":"","sources":["../src/roles.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,qEAAqE;AACrE,eAAO,MAAM,oBAAoB,4CAA4C,CAAA;AAE7E,iFAAiF;AACjF,eAAO,MAAM,iBAAiB,YAAY,CAAA;AAE1C,iEAAiE;AACjE,eAAO,MAAM,2BAA2B,sBAAsB,CAAA;AAE9D;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,uCAAuC,CAAA;AAErE;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,yBAAyB,CAAA;AAEvD;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,6BAA8B,CAAA;AAQjE,8DAA8D;AAC9D,eAAO,MAAM,cAAc,uBAAuB,CAAA;AAElD,+DAA+D;AAC/D,eAAO,MAAM,eAAe,wBAAwB,CAAA;AAEpD;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B,wDAG/B,CAAA;AAIV;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,EACrC,eAAe,GAAE,MAA6B,GAC7C,OAAO,CAET;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,EACrC,aAAa,EAAE,MAAM,EAAE,GACtB,OAAO,CAMT;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,EACrC,0BAA0B,EAAE,MAAM,EAAE,GACnC,OAAO,CAKT;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,EAClC,eAAe,GAAE,MAA0B,EAC3C,iBAAiB,GAAE,MAAoC,GACtD,OAAO,CAKT;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,EAClC,iBAAiB,GAAE,MAAoC,GACtD,OAAO,CAET"}

package/dist/roles.js

@@ -9,13 +9,27 @@
 // ── Constants (configurable defaults) ───────────────────────
 /** Default organization role string for inactive public servants. */
 export const INACTIVE_PS_ORG_ROLE = "inactive-ps-org:Inactive Public Servant";
+/** Logto role name assigned to a citizen at registration (before onboarding). */
+export const ROLE_NAME_CITIZEN = "citizen";
 /** Default Logto role name assigned after citizen onboarding. */
 export const ROLE_NAME_ONBOARDED_CITIZEN = "Onboarded citizen";
-/** Logto directSignIn value for MyGovID social connector. */
-export const CONNECTOR_MYGOVID = "social:mygovid";
-/** Logto directSignIn value for Entra ID social connector. */
-export const CONNECTOR_ENTRAID = "social:ogcio-entraid";
-/** Sign-in methods that are considered valid for citizen flows. */
+/**
+ * Logto directSignIn value for MyGovID social connector.
+ * Must match the connector's `target` (Identity provider name) in Logto,
+ * NOT the connector `id`.
+ */
+export const CONNECTOR_MYGOVID = "social:MyGovId (MyGovId connector)";
+/**
+ * Logto directSignIn value for Entra ID social connector.
+ * Must match the connector's `target` (Identity provider name) in Logto,
+ * NOT the connector `id`.
+ */
+export const CONNECTOR_ENTRAID = "social:OGCIO EntraID";
+/**
+ * Sign-in methods that are considered valid for citizen flows.
+ * These use connector `id` (not `target`) because the custom JWT claim
+ * `signInMethod` is built from `record.connectorId`.
+ */
 export const ALLOWED_SIGNIN_METHODS = ["social:mygovid"];
 // ── Common public-servant organisation role names ───────────
 //
@@ -80,6 +94,26 @@ export function isCitizen(orgRoles, expectedPublicServantRoles) {
     return !(isInactivePublicServant(orgRoles) ||
         isPublicServant(orgRoles, expectedPublicServantRoles));
 }
+/**
+ * Check whether the user is a citizen (active or inactive) based on the
+ * ID-token `roles` claim — without needing to know any app-specific
+ * public-servant role names.
+ *
+ * A user is a citizen when their `roles` includes either the pre-onboarding
+ * citizen role (`"citizen"`) or the onboarded-citizen role (`"Onboarded citizen"`).
+ * Anyone without either role is considered a public servant (of any kind).
+ *
+ * Prefer this over `isCitizen(orgRoles, expectedRoles)` for citizen-facing
+ * apps, as it is universal across all applications.
+ *
+ * @param roles              `roles` claim from the ID token.
+ * @param citizenRoleName    Override the default citizen role name.
+ * @param onboardedRoleName  Override the default onboarded-citizen role name.
+ */
+export function isCitizenByRole(roles, citizenRoleName = ROLE_NAME_CITIZEN, onboardedRoleName = ROLE_NAME_ONBOARDED_CITIZEN) {
+    var _a;
+    return ((_a = ((roles === null || roles === void 0 ? void 0 : roles.includes(citizenRoleName)) || (roles === null || roles === void 0 ? void 0 : roles.includes(onboardedRoleName)))) !== null && _a !== void 0 ? _a : false);
+}
 /**
  * Check whether the citizen has completed onboarding.
  *

package/dist/roles.js.map

@@ -1 +1 @@
-{"version":3,"file":"roles.js","sourceRoot":"","sources":["../src/roles.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,+DAA+D;AAE/D,qEAAqE;AACrE,MAAM,CAAC,MAAM,oBAAoB,GAAG,yCAAyC,CAAA;AAE7E,iEAAiE;AACjE,MAAM,CAAC,MAAM,2BAA2B,GAAG,mBAAmB,CAAA;AAE9D,6DAA6D;AAC7D,MAAM,CAAC,MAAM,iBAAiB,GAAG,gBAAgB,CAAA;AAEjD,8DAA8D;AAC9D,MAAM,CAAC,MAAM,iBAAiB,GAAG,sBAAsB,CAAA;AAEvD,mEAAmE;AACnE,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,gBAAgB,CAAU,CAAA;AAEjE,+DAA+D;AAC/D,EAAE;AACF,mEAAmE;AACnE,kEAAkE;AAClE,8DAA8D;AAE9D,8DAA8D;AAC9D,MAAM,CAAC,MAAM,cAAc,GAAG,oBAAoB,CAAA;AAElD,+DAA+D;AAC/D,MAAM,CAAC,MAAM,eAAe,GAAG,qBAAqB,CAAA;AAEpD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG;IAC1C,cAAc;IACd,eAAe;CACP,CAAA;AAEV,+DAA+D;AAE/D;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CACrC,QAAqC,EACrC,kBAA0B,oBAAoB;;IAE9C,OAAO,MAAA,QAAQ,aAAR,QAAQ,uBAAR,QAAQ,CAAE,QAAQ,CAAC,eAAe,CAAC,mCAAI,KAAK,CAAA;AACrD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAqC,EACrC,aAAuB;IAEvB,IAAI,uBAAuB,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAA;IAChE,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE;QAC/B,MAAM,CAAC,EAAE,IAAI,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;QACnC,OAAO,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;IACrC,CAAC,CAAC,CAAA;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CACvB,QAAqC,EACrC,0BAAoC;IAEpC,OAAO,CAAC,CACN,uBAAuB,CAAC,QAAQ,CAAC;QACjC,eAAe,CAAC,QAAQ,EAAE,0BAA0B,CAAC,CACtD,CAAA;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAkC,EAClC,oBAA4B,2BAA2B;;IAEvD,OAAO,MAAA,KAAK,aAAL,KAAK,uBAAL,KAAK,CAAE,QAAQ,CAAC,iBAAiB,CAAC,mCAAI,KAAK,CAAA;AACpD,CAAC"}
+{"version":3,"file":"roles.js","sourceRoot":"","sources":["../src/roles.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,+DAA+D;AAE/D,qEAAqE;AACrE,MAAM,CAAC,MAAM,oBAAoB,GAAG,yCAAyC,CAAA;AAE7E,iFAAiF;AACjF,MAAM,CAAC,MAAM,iBAAiB,GAAG,SAAS,CAAA;AAE1C,iEAAiE;AACjE,MAAM,CAAC,MAAM,2BAA2B,GAAG,mBAAmB,CAAA;AAE9D;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,oCAAoC,CAAA;AAErE;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,sBAAsB,CAAA;AAEvD;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,gBAAgB,CAAU,CAAA;AAEjE,+DAA+D;AAC/D,EAAE;AACF,mEAAmE;AACnE,kEAAkE;AAClE,8DAA8D;AAE9D,8DAA8D;AAC9D,MAAM,CAAC,MAAM,cAAc,GAAG,oBAAoB,CAAA;AAElD,+DAA+D;AAC/D,MAAM,CAAC,MAAM,eAAe,GAAG,qBAAqB,CAAA;AAEpD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG;IAC1C,cAAc;IACd,eAAe;CACP,CAAA;AAEV,+DAA+D;AAE/D;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CACrC,QAAqC,EACrC,kBAA0B,oBAAoB;;IAE9C,OAAO,MAAA,QAAQ,aAAR,QAAQ,uBAAR,QAAQ,CAAE,QAAQ,CAAC,eAAe,CAAC,mCAAI,KAAK,CAAA;AACrD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAqC,EACrC,aAAuB;IAEvB,IAAI,uBAAuB,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAA;IAChE,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE;QAC/B,MAAM,CAAC,EAAE,IAAI,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;QACnC,OAAO,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;IACrC,CAAC,CAAC,CAAA;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CACvB,QAAqC,EACrC,0BAAoC;IAEpC,OAAO,CAAC,CACN,uBAAuB,CAAC,QAAQ,CAAC;QACjC,eAAe,CAAC,QAAQ,EAAE,0BAA0B,CAAC,CACtD,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,eAAe,CAC7B,KAAkC,EAClC,kBAA0B,iBAAiB,EAC3C,oBAA4B,2BAA2B;;IAEvD,OAAO,CACL,MAAA,CAAC,CAAA,KAAK,aAAL,KAAK,uBAAL,KAAK,CAAE,QAAQ,CAAC,eAAe,CAAC,MAAI,KAAK,aAAL,KAAK,uBAAL,KAAK,CAAE,QAAQ,CAAC,iBAAiB,CAAC,CAAA,CAAC,mCACxE,KAAK,CACN,CAAA;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAkC,EAClC,oBAA4B,2BAA2B;;IAEvD,OAAO,MAAA,KAAK,aAAL,KAAK,uBAAL,KAAK,CAAE,QAAQ,CAAC,iBAAiB,CAAC,mCAAI,KAAK,CAAA;AACpD,CAAC"}

package/dist/types.d.ts

@@ -33,8 +33,8 @@ export interface SignInOptions {
      * Logto `directSignIn` value — bypass the sign-in screen and go
      * directly to a specific social connector or SSO provider.
      *
-     * @example "social:mygovid"
-     * @example "social:ogcio-entraid"
+     * @example "social:MyGovId (MyGovId connector)"
+     * @example "social:OGCIO EntraID"
      * @example "sso:connector-id"
      */
     connector?: string;
@@ -105,14 +105,8 @@ export interface GatewayMutationOptions extends GatewayFetchOptions {
     /** HTTP method for the mutation (defaults to `"POST"`). */
     method?: MutationMethod;
 }
-/** Options for the `useOnboardingGuard` hook. */
-export type { UseOnboardingGuardOptions } from "./react/use-onboarding-guard";
-/** Return value of the `useOnboardingGuard` hook. */
-export type { UseOnboardingGuardResult } from "./react/use-onboarding-guard";
-/** Options for the `usePublicServantGuard` hook. */
-export type { UsePublicServantGuardOptions } from "./react/use-public-servant-guard";
-/** Return value of the `usePublicServantGuard` hook. */
-export type { UsePublicServantGuardResult } from "./react/use-public-servant-guard";
+export type { UseOnboardingGuardOptions, UseOnboardingGuardResult, } from "./react/use-onboarding-guard";
+export type { UsePublicServantGuardOptions, UsePublicServantGuardResult, } from "./react/use-public-servant-guard";
 export type UseAuthResult = {
     authenticated: boolean;
     user?: AuthUser;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,QAAQ,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAErE,yEAAyE;AACzE,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,kBAAkB,EAAE,MAAM,EAAE,CAAA;IAC5B,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,CAAA;AAED,MAAM,MAAM,UAAU,GAClB;IAAE,aAAa,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GACxE;IAAE,aAAa,EAAE,KAAK,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAI9C,2FAA2F;AAC3F,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,EAAE,MAAM,EAAE,CAAA;CAChB;AAID,oCAAoC;AACpC,MAAM,WAAW,aAAa;IAC5B;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAID,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAA;IAClB,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,IAAI,CAAA;CAC9B;AAID;;;;GAIG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;gBAED,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM;CAM3D;AAID;;;GAGG;AACH,eAAO,MAAM,iBAAiB,yBAAyB,CAAA;AAEvD;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,sBAAsB,CAAA;AAEzD;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,KAAK,CAAA;AAEtC,iDAAiD;AACjD,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAA;IAErB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,yCAAyC;AACzC,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAA;AAEhE,oDAAoD;AACpD,MAAM,WAAW,sBAAuB,SAAQ,mBAAmB;IACjE,2DAA2D;IAC3D,MAAM,CAAC,EAAE,cAAc,CAAA;CACxB;AAID,iDAAiD;AACjD,YAAY,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAA;AAC7E,qDAAqD;AACrD,YAAY,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAA;AAE5E,oDAAoD;AACpD,YAAY,EAAE,4BAA4B,EAAE,MAAM,kCAAkC,CAAA;AACpF,wDAAwD;AACxD,YAAY,EAAE,2BAA2B,EAAE,MAAM,kCAAkC,CAAA;AAEnF,MAAM,MAAM,aAAa,GAAG;IAC1B,aAAa,EAAE,OAAO,CAAA;IACtB,IAAI,CAAC,EAAE,QAAQ,CAAA;IACf,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,sEAAsE;IACtE,cAAc,EAAE,OAAO,CAAA;IACvB,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,aAAa,KAAK,IAAI,CAAA;IACzC,OAAO,EAAE,MAAM,IAAI,CAAA;IACnB,8EAA8E;IAC9E,iBAAiB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACtC,OAAO,EAAE,MAAM,IAAI,CAAA;CACpB,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

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