@octabits-io/nuxt-ui-kit 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,453 @@
+import { UserManager, UserManagerSettings, UserProfile } from "oidc-client-ts";
+import { ComputedRef, Ref } from "vue";
+import { Treaty } from "@elysiajs/eden";
+import { Elysia } from "elysia";
+//#region src/auth/oidc.d.ts
+/** Issuer + client id, resolved at first use (client-side runtime config). */
+interface OidcClientConfig {
+  issuerUrl: string;
+  clientId: string;
+}
+interface UserManagerFactoryOptions {
+  /**
+   * Resolve the issuer/client pair lazily — typically from a runtime-injected
+   * config object (e.g. a K8s-entrypoint `window.__APP_CONFIG__`) falling back
+   * to the app's build-time config.
+   */
+  getConfig: () => OidcClientConfig;
+  /** OAuth scopes requested on the initial signin. */
+  scope: string;
+  /**
+   * Scopes sent on the refresh-token grant when the IdP restricts them to a
+   * subset of the signin scopes (see `ZITADEL_REFRESH_TOKEN_ALLOWED_SCOPE`).
+   */
+  refreshTokenAllowedScope?: string;
+  /** Path the IdP redirects back to after signin. Default `/auth/callback`. */
+  redirectPath?: string;
+  /** Path the IdP redirects to after logout. Default `/login`. */
+  postLogoutRedirectPath?: string;
+  /** Default `true`. */
+  automaticSilentRenew?: boolean;
+  /** Raw oidc-client-ts settings escape hatch, applied last. */
+  settings?: Partial<UserManagerSettings>;
+  /** Called when issuer/client resolve empty. Default `console.error`. */
+  onMissingConfig?: (message: string) => void;
+}
+/**
+ * Lazily-created `UserManager` singleton bound to `window.localStorage`.
+ * Call the returned getter from plugins/stores/composables — the manager is
+ * constructed on first call (client-side only; requires `window`).
+ */
+declare function createUserManagerFactory(options: UserManagerFactoryOptions): () => UserManager;
+type StaleKeyStorage = Pick<Storage, 'length' | 'key' | 'removeItem'>;
+/**
+ * Remove any `oidc.user:` storage keys that don't belong to the current
+ * authority+clientId — leftovers from environment switches would otherwise
+ * shadow or bloat the session storage.
+ */
+declare function removeStaleOidcKeys(authority: string, clientId: string, storage?: StaleKeyStorage): void;
+/** Refresh tokens fail unrecoverably with these OIDC error codes — user must re-auth. */
+declare function isUnrecoverableRenewError(message: string): boolean;
+interface LoginRedirectorOptions {
+  getUserManager: () => UserManager;
+  /** Fallback login page for when `signinRedirect` itself fails. Default `/login`. */
+  loginPath?: string;
+  /**
+   * Paths where redirecting to login would loop (the login/callback pages
+   * themselves). Default: `loginPath` and anything under `/auth/`.
+   */
+  isAuthRoute?: (path: string) => boolean;
+  /** Default `console.error`. */
+  log?: (message: string, detail?: unknown) => void;
+}
+/**
+ * Build a `redirectToLogin()` that starts an OIDC signin redirect carrying the
+ * current path as returnUrl state, with a plain `/login?redirect=` navigation
+ * fallback when the IdP redirect cannot even be started. No-ops on auth routes.
+ */
+declare function createLoginRedirector(options: LoginRedirectorOptions): () => Promise<void>;
+/**
+ * A user-facing session event the app should surface (toast/banner). The kit
+ * classifies; presentation and copy stay in the app.
+ *
+ * - `renew-failed` — silent renew failed recoverably (next renew may succeed).
+ * - `session-expired` — the session is gone; a login redirect follows.
+ */
+type SessionNotice = {
+  kind: 'renew-failed';
+  error: Error;
+} | {
+  kind: 'session-expired';
+  error?: Error;
+};
+interface SessionLifecycleHandlers {
+  /** Start re-authentication (typically from {@link createLoginRedirector}). */
+  redirectToLogin: () => void | Promise<void>;
+  /** Surface a notice to the user (toast). Optional — omit for headless use. */
+  notify?: (notice: SessionNotice) => void;
+  /** Clear app-side session state (e.g. reset the auth store's user). */
+  onSessionLost?: () => void;
+  /** Default `console.warn`. */
+  log?: (message: string, detail?: unknown) => void;
+}
+/**
+ * Wire oidc-client-ts session events to app callbacks:
+ *
+ * - silent-renew error → `notify` (`renew-failed`, or `session-expired` when the
+ *   error is unrecoverable — see {@link isUnrecoverableRenewError}); an
+ *   unrecoverable error also triggers the login redirect
+ * - access token expired without renewal → `notify(session-expired)` +
+ *   `onSessionLost` + login redirect
+ * - back-channel signout at the IdP → `onSessionLost` + login redirect (no notice
+ *   — the user initiated it elsewhere)
+ *
+ * Returns a detach function.
+ */
+declare function attachSessionLifecycleHandlers(userManager: UserManager, handlers: SessionLifecycleHandlers): () => void;
+//#endregion
+//#region src/auth/zitadel.d.ts
+/**
+ * Zitadel scope presets for {@link createUserManagerFactory}.
+ *
+ * The URN scopes request the resource-owner (organization) claim and the
+ * project role grants; `offline_access` requests a refresh token.
+ */
+declare const ZITADEL_ORG_PROJECT_SCOPE = "openid profile email urn:zitadel:iam:user:resourceowner urn:zitadel:iam:org:project:roles offline_access";
+/**
+ * Zitadel only accepts standard OIDC scopes on the refresh-token grant —
+ * sending `offline_access` or the `urn:zitadel:*` scopes returns
+ * `invalid_scope` even though they were granted at the initial auth. The
+ * URN-based claims still need to land in the refreshed access token; that
+ * depends on "Assert Roles on Authentication" being enabled at the Zitadel
+ * project level.
+ */
+declare const ZITADEL_REFRESH_TOKEN_ALLOWED_SCOPE = "openid profile email";
+//#endregion
+//#region src/auth/bypass.d.ts
+type BypassStorage = Pick<Storage, 'getItem' | 'setItem'>;
+interface AuthBypassProfile {
+  sub: string;
+  email: string;
+  name: string;
+}
+interface SeedAuthBypassOptions {
+  /** The shared secret the API accepts as a Bearer token. Falsy → no-op. */
+  bypassSecret: string | null | undefined;
+  issuerUrl: string;
+  clientId: string;
+  /**
+   * MUST be the build-time production flag (e.g. `import.meta.env.PROD`).
+   * When `true` the seed is refused unconditionally — a leaked runtime env var
+   * cannot enable the bypass in a production build.
+   */
+  isProductionBuild: boolean;
+  /** Identity baked into the fake session. */
+  profile?: AuthBypassProfile;
+  /** Fake session lifetime. Default 86400 (24h). */
+  sessionTtlSeconds?: number;
+  storage?: BypassStorage;
+  /** Default `console.warn`. */
+  warn?: (message: string) => void;
+}
+/**
+ * Dev/E2E auth bypass: seed storage with a fake oidc-client-ts user whose
+ * `access_token` is the bypass secret, so the app considers the session
+ * authenticated and the API client sends the secret as Bearer.
+ *
+ * Call from a plugin that runs before the OIDC plugin. Skips seeding when a
+ * valid (non-expired) session already exists; overwrites corrupt entries.
+ * Returns whether a session was seeded.
+ */
+declare function seedAuthBypassSession(options: SeedAuthBypassOptions): boolean;
+//#endregion
+//#region src/auth/session.d.ts
+/** Default mapped shape of the authenticated user. */
+interface AuthSessionUser {
+  id: string;
+  email: string;
+  name: string | null;
+  picture: string | null;
+}
+interface AuthSessionCoreOptions<TUser> {
+  getUserManager: () => UserManager;
+  /** Map OIDC profile claims to the app's user shape. */
+  mapUser: (profile: UserProfile) => TUser;
+  /** Default `console.warn`. */
+  log?: (message: string, detail?: unknown) => void;
+}
+interface AuthSessionCore<TUser> {
+  user: Ref<TUser | null>;
+  initialized: Ref<boolean>;
+  loading: Ref<boolean>;
+  isAuthenticated: ComputedRef<boolean>;
+  /** Restore the session from storage, silently renewing an expired token. */
+  checkAuth: () => Promise<void>;
+  /** Start the signin redirect, carrying `returnUrl` as state. */
+  login: (returnUrl?: string) => Promise<void>;
+  /** Complete the signin redirect; returns the returnUrl state (default `/`). */
+  handleCallback: () => Promise<string>;
+  /** Clear the local session and redirect to the IdP's logout endpoint. */
+  logout: () => Promise<void>;
+}
+declare function defaultAuthUserMapper(profile: UserProfile): AuthSessionUser;
+/**
+ * Reactive OIDC session state + actions — the setup body of an auth store.
+ * Wrap it in the app's own store so naming and registration stay app-owned:
+ *
+ * ```ts
+ * export const useAuthStore = defineStore('auth', () =>
+ *   createAuthSessionCore({ getUserManager, mapUser: defaultAuthUserMapper }),
+ * )
+ * ```
+ */
+declare function createAuthSessionCore<TUser = AuthSessionUser>(options: AuthSessionCoreOptions<TUser>): AuthSessionCore<TUser>;
+//#endregion
+//#region src/auth/guard.d.ts
+/** The route fields the guard needs — structurally satisfied by a Nuxt route. */
+interface GuardRoute {
+  path: string;
+  fullPath: string;
+}
+interface AuthGuardOptions<TRoute extends GuardRoute = GuardRoute> {
+  /**
+   * Ensure the session is restored and report whether the user is
+   * authenticated — typically `checkAuth()` once, then `isAuthenticated`.
+   */
+  ensureAuthenticated: () => Promise<boolean> | boolean;
+  /** Routes reachable without auth. Default: `/login` and `/auth/*`. */
+  isPublicRoute?: (to: TRoute) => boolean;
+  /** Build the login redirect target. Default `/login?redirect=<returnTo>`. */
+  loginRedirect?: (returnTo: string) => string;
+  /**
+   * Per-app policy hook that runs once the user is authenticated — tenant/org
+   * validation, role gates, acceptance gates. Return a path to redirect to,
+   * or nothing to let the navigation through.
+   */
+  afterAuthenticated?: (to: TRoute) => Promise<string | undefined | void> | string | undefined | void;
+}
+/**
+ * Build the body of a global auth route-middleware. The returned handler
+ * yields a redirect target path or `undefined` to allow navigation; the app's
+ * middleware maps that onto its router:
+ *
+ * ```ts
+ * export default defineNuxtRouteMiddleware(async (to) => {
+ *   const target = await guard(to)
+ *   if (target) return navigateTo(target)
+ * })
+ * ```
+ */
+declare function createAuthGuard<TRoute extends GuardRoute = GuardRoute>(options: AuthGuardOptions<TRoute>): (to: TRoute) => Promise<string | undefined>;
+//#endregion
+//#region src/api/client.d.ts
+type AnyElysia = Elysia<any, any, any, any, any, any, any>;
+interface ResolveApiBaseUrlOptions {
+  /**
+   * The explicitly configured URL, first-match-wins — e.g.
+   * `__APP_CONFIG__.API_URL || runtimeConfig.public.apiUrl`. Falsy → fallback.
+   */
+  configuredUrl: string | null | undefined;
+  /** Build-time production flag (`import.meta.env.PROD`). */
+  isProductionBuild: boolean;
+  /** Dev fallback becomes `http://localhost:<port>`. */
+  devFallbackPort: number;
+  /** Production fallback origin. Default `window.location.origin`. */
+  origin?: string;
+}
+/**
+ * Resolve the API base URL: configured value, else the page origin in
+ * production builds (same-host ingress), else a localhost dev port.
+ */
+declare function resolveApiBaseUrl(options: ResolveApiBaseUrlOptions): string;
+/**
+ * Bearer-token provider backed by the OIDC session: resolves to the current
+ * access token, or `null` when there is no non-expired session.
+ */
+declare function createAccessTokenProvider(getUserManager: () => UserManager): () => Promise<string | null>;
+interface TreatyClientFactoryOptions {
+  /** Resolve (and memoize, if desired) the base URL at first client use. */
+  getBaseUrl: () => string;
+  /** Bearer token per request; `null` sends no Authorization header. */
+  getAccessToken: () => Promise<string | null>;
+  /**
+   * Eden Treaty's auto-Date parsing on responses. Default `false`: with the
+   * default `true`, any `YYYY-MM-DD` string in a response is silently
+   * converted to a `Date` object, which then JSON-serializes back as a full
+   * ISO datetime on the next request — breaking server-side "plain ISO date
+   * string" validation. Keep the wire contract string-typed unless the API
+   * genuinely round-trips Date objects.
+   */
+  parseDate?: boolean;
+  /** Extra Treaty config (fetcher, onRequest, …), applied last. */
+  treatyConfig?: Omit<Treaty.Config, 'headers' | 'parseDate'>;
+}
+/**
+ * Lazily-created Eden Treaty client singleton with OIDC bearer injection.
+ *
+ * ```ts
+ * const getClient = createTreatyClientFactory<App>({ getBaseUrl, getAccessToken })
+ * export function useApi() {
+ *   const client = getClient()
+ *   return { api: client.api, client }
+ * }
+ * ```
+ */
+declare function createTreatyClientFactory<App extends AnyElysia>(options: TreatyClientFactoryOptions): () => Treaty.Create<App>;
+//#endregion
+//#region src/org/orgStore.d.ts
+type OrgStorage = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+/** Result seam for the org fetch — mirrors an Eden Treaty `{ data, error }`. */
+type FetchOrganizationsResult<TOrg> = {
+  items: TOrg[];
+  error?: undefined;
+} | {
+  items?: undefined;
+  error: unknown;
+};
+interface OrgStoreCoreOptions<TOrg> {
+  /**
+   * Fetch the orgs the current user is granted. Return `{ items }` on
+   * success or `{ error }` to surface a fetch failure (`fetchError`).
+   */
+  fetchOrganizations: () => Promise<FetchOrganizationsResult<TOrg>>;
+  /** The org's URL/selection identity. */
+  getSlug: (org: TOrg) => string;
+  /** Storage key persisting the current selection. Default `currentOrgSlug`. */
+  persistenceKey?: string;
+  storage?: OrgStorage;
+}
+interface OrgStoreCore<TOrg> {
+  organizations: Ref<TOrg[]>;
+  currentSlug: Ref<string | null>;
+  currentOrganization: ComputedRef<TOrg | null>;
+  loading: Ref<boolean>;
+  fetchError: Ref<unknown>;
+  /** Fetch grants; revokes the current selection if access was lost. */
+  fetchOrganizations: () => Promise<void>;
+  /** Select an org by slug (or clear with `null`); persists the choice. */
+  setCurrent: (slug: string | null) => void;
+  /** Restore the persisted selection (call once at app start). */
+  loadPersisted: () => void;
+}
+/**
+ * Reactive granted-organizations state + switching — the setup body of an
+ * org/tenant store. Wrap it in the app's own store (and alias names there):
+ *
+ * ```ts
+ * export const useTenantStore = defineStore('tenant', () => {
+ *   const core = createOrgStoreCore<Tenant>({ fetchOrganizations, getSlug: t => t.slug })
+ *   return { ...core, fetchTenants: core.fetchOrganizations }
+ * })
+ * ```
+ */
+declare function createOrgStoreCore<TOrg>(options: OrgStoreCoreOptions<TOrg>): OrgStoreCore<TOrg>;
+//#endregion
+//#region src/composables/useConfirm.d.ts
+interface ConfirmOptions {
+  title: string;
+  message?: string;
+  confirmText?: string;
+  cancelText?: string;
+  /** Renders the confirm button in the error color. */
+  dangerous?: boolean;
+}
+/** Promise-based confirmation: `if (await confirm({ title, dangerous: true })) …` */
+declare function useConfirm(): {
+  confirm: (options: ConfirmOptions) => Promise<boolean>;
+};
+/** State + handlers for the dialog renderer component. */
+declare function useConfirmState(): {
+  isOpen: import("vue").Ref<boolean, boolean>;
+  options: import("vue").Ref<{
+    title: string;
+    message?: string;
+    confirmText?: string;
+    cancelText?: string;
+    dangerous?: boolean;
+  }, ConfirmOptions | {
+    title: string;
+    message?: string;
+    confirmText?: string;
+    cancelText?: string;
+    dangerous?: boolean;
+  }>;
+  handleConfirm: () => void;
+  handleCancel: () => void;
+};
+//#endregion
+//#region src/composables/apiErrorMessenger.d.ts
+/** `{ key, message }` API error body (an OctError over the wire). */
+interface ApiErrorLike {
+  key: string;
+  message: string;
+}
+/** `validation_error` body carrying per-field failures. */
+interface ValidationApiErrorLike extends ApiErrorLike {
+  key: 'validation_error';
+  fields: {
+    path: string;
+    message: string;
+  }[];
+}
+interface ApiErrorMessengerOptions {
+  /** Translate a key (assumed to exist). */
+  t: (key: string) => string;
+  /** Does a translation exist for this key? */
+  te: (key: string) => boolean;
+  /** Default `console.error`. Pass `() => {}` to silence. */
+  log?: (message: string, error: unknown) => void;
+}
+/**
+ * Map API error bodies to user-facing i18n strings using a fixed key
+ * convention the consumer's locale files fulfil:
+ *
+ * - `errors.<key>` — one entry per API error key (fallback: the raw
+ *   server `message`, and `errors.internal_server_error` for non-API errors)
+ * - `validation.fields.<path>` — display names for validated fields
+ * - `validation.messages.<snake_cased_message>` — validation message texts
+ *
+ * Framework-free: pass `t`/`te` from your i18n instance (the app-side
+ * composable is typically `const { t, te } = useI18n()` + this factory).
+ * Eden Treaty error envelopes (`{ value }`) are unwrapped automatically.
+ */
+declare function createApiErrorMessenger(options: ApiErrorMessengerOptions): {
+  getErrorMessage: (error: unknown) => string;
+  isValidationError: (error: unknown) => error is ValidationApiErrorLike;
+};
+//#endregion
+//#region src/composables/useDirtyTracking.d.ts
+/**
+ * Form change-detection over a reactive state object via JSON deep-compare:
+ * `isDirty` flips when any field differs from the snapshot; `resetInitial()`
+ * re-snapshots after load/save (optionally assigning new values first);
+ * `getDirtyFields()` yields a minimal PATCH payload.
+ */
+declare function useDirtyTracking<T extends Record<string, unknown>>(state: T): {
+  isDirty: import("vue").ComputedRef<boolean>;
+  getDirtyFields: () => Partial<T>;
+  resetInitial: (values?: Partial<T>) => void;
+};
+//#endregion
+//#region src/composables/usePagination.d.ts
+/**
+ * Offset-based table pagination: `page`/`itemsPerPage`/`total` state with a
+ * derived `offset` and ready-to-spread `queryParams { limit, offset }`.
+ * `onPaginationChange` fires whenever page or page size changes (refetch hook).
+ */
+declare function usePagination(options?: {
+  defaultLimit?: number;
+  onPaginationChange?: () => void;
+}): {
+  page: import("vue").Ref<number, number>;
+  itemsPerPage: import("vue").Ref<number, number>;
+  total: import("vue").Ref<number, number>;
+  offset: import("vue").ComputedRef<number>;
+  queryParams: import("vue").ComputedRef<{
+    limit: number;
+    offset: number;
+  }>;
+  setTotal: (value: number) => void;
+  resetPagination: () => void;
+};
+//#endregion
+export { type ApiErrorLike, type ApiErrorMessengerOptions, type AuthBypassProfile, type AuthGuardOptions, type AuthSessionCore, type AuthSessionCoreOptions, type AuthSessionUser, type ConfirmOptions, type FetchOrganizationsResult, type GuardRoute, type LoginRedirectorOptions, type OidcClientConfig, type OrgStoreCore, type OrgStoreCoreOptions, type ResolveApiBaseUrlOptions, type SeedAuthBypassOptions, type SessionLifecycleHandlers, type SessionNotice, type TreatyClientFactoryOptions, type UserManagerFactoryOptions, type ValidationApiErrorLike, ZITADEL_ORG_PROJECT_SCOPE, ZITADEL_REFRESH_TOKEN_ALLOWED_SCOPE, attachSessionLifecycleHandlers, createAccessTokenProvider, createApiErrorMessenger, createAuthGuard, createAuthSessionCore, createLoginRedirector, createOrgStoreCore, createTreatyClientFactory, createUserManagerFactory, defaultAuthUserMapper, isUnrecoverableRenewError, removeStaleOidcKeys, resolveApiBaseUrl, seedAuthBypassSession, useConfirm, useConfirmState, useDirtyTracking, usePagination };