@merkaly/nuxt 0.12.5 → 0.13.0

package/README.md

@@ -26,14 +26,130 @@ Install the module to your Nuxt application:
 
 Every surface can sign in; `auth0.requiresAuth` only decides whether pages require a login (globally, or per page with `definePageMeta({ requiresAuth: true })`). `auth0.requiresTenant` decides whether API calls require a tenant (`global: true` adapters bypass it).
 
-On boot the module restores an existing session (user and token) and then runs the app hooks in order, `merkaly:tenant` then `merkaly:auth`, with that user (or none). `MKApp` shows its `loading` slot until both finish; if a hook throws, it shows the `error` slot instead. The auth callback page renders right away so it can complete the login.
+On boot the module restores an existing session (Auth0 claims and token) and then runs the bootstrap stages in a fixed order, each one only after the previous one finished:
+
+1. **session**: the app hooks `merkaly:tenant` then `merkaly:auth`, with those claims (or none).
+2. **organization**: the app's organization loader (see `defineBootstrap`), always, signed in or not.
+3. **user**: the app's `/auth/me` loader, only when the visitor is signed in.
+
+The app mounts (and `MKApp` renders its default slot) only after the last stage, so pages, layouts and their requests start with the session, the organization and the user already loaded. A failing stage records the failure with `useAuth().fail()` (stage `tenant`, `organization` or `user`; never a logout) and `MKApp` renders the `error` slot; `retry()` runs again only the stages that did not succeed. The auth callback page renders right away so it can complete the login, and runs the stages after it.
 
 | Surface | Login | Tenant | Boot |
 |---|---|---|---|
-| admin | required | required | `merkaly:tenant` creates the session and sets the tenant; without a session the auth middleware redirects to login. |
-| dashboard | required | not used | `merkaly:auth` loads the session; without a session it redirects to login. |
-| store | optional | required | `merkaly:tenant` resolves the store from the host (public); a signed-in buyer is restored too; protected pages (account, checkout) ask for login. |
-| www | optional | not used | No hooks; anonymous or signed-in. |
+| admin | required | required | `merkaly:tenant` creates the session and sets the tenant; then organization (`/settings/organization`) and user (`/auth/me`). Without a session the auth middleware redirects to login. |
+| dashboard | required | not used | `merkaly:auth` loads the session; then user if it declares a loader. Without a session it redirects to login. |
+| store | optional | required | `merkaly:tenant` resolves the store from the host (public); then organization (`/company`, public, also during SSR); user only for a signed-in buyer. Protected pages (account, checkout) ask for login. |
+| www | optional | not used | No hooks and no loaders; anonymous or signed-in. |
+
+### Ordered bootstrap (`defineBootstrap`, `useOrganization`, `useAuth().user`)
+
+Each app declares its loaders once, from a plugin, with its own adapters (the module has no app endpoints):
+
+```ts
+// admin: app/plugins/bootstrap.ts
+import { readAccountProfile } from '~/adapters/account/read.account.profile';
+import { readSettingsOrganization } from '~/adapters/settings/organization/read.settings.organization';
+
+export default defineNuxtPlugin(() => {
+  defineBootstrap({
+    organization: () => readSettingsOrganization(() => ({ immediate: false })),
+    user: () => readAccountProfile(() => ({ immediate: false })),
+  });
+});
+```
+
+```ts
+// store: app/plugins/bootstrap.ts (universal, not .client: SSR loads the organization too)
+import { readAppCompany } from '~/adapters/app/read.company';
+
+export default defineNuxtPlugin(() => {
+  defineBootstrap({ organization: () => readAppCompany(() => ({ immediate: false })) });
+});
+```
+
+A loader returns an adapter (`withAdapter()` result, preferably with `immediate: false`, the bootstrap runs it), a promise or a plain value. An adapter with an api error, or a rejected promise, fails the stage. Every stage is optional: an app without loaders skips it.
+
+Two composables hold the state, shared by the whole app:
+
+- `useOrganization()`: everything about the organization (tenant). It exists without a login and also loads on the server.
+- `useAuth()`: everything about the user: `user`, the loaded profile (`/auth/me`), and `claims`, the Auth0 ID token user (`sub`, `email`, `name`, `picture`, custom claims), plus `token`, `isAuthenticated` (from `claims.sub`), `fail`, `retry`, `logout`, `signup`.
+
+Use `claims` for what the token already carries (id, email, roles) and `user.data` for the profile the api stores (own avatar, locale, saved name).
+
+| `useOrganization()` | Description |
+|---|---|
+| `id` | Organization id (Auth0 org), sent as the `identity` header; `''` until set |
+| `setId(id, { server? })` | Sets the id; `server: true` when resolved during SSR |
+| `hasId` | `Boolean(id)` |
+| `fromServer` | The id was resolved during SSR: the page renders before auth |
+| `data`, `status`, `error`, `isReady`, `refresh()` | The loaded organization, see below |
+
+| `useAuth().user` and the stage keys of `useOrganization()` | Description |
+|---|---|
+| `data` | Loaded value; `undefined` until it loads (and always for `user` with visitors) |
+| `status` | `idle`, `pending`, `success` or `error` |
+| `error` | `{ message, status? }` of the last failure |
+| `isReady` | `status === 'success'` |
+| `refresh()` | Loads it again (e.g. after saving the settings); a failure here only sets `error`, it does not block the app |
+
+```ts
+const { data: organization, id } = useOrganization();
+const { claims, user } = useAuth();
+
+const name = computed(() => user.data.value?.name || claims.value?.name); // typed by MerkalyUser
+```
+
+#### Typing (`MerkalyOrganization`, `MerkalyUser`)
+
+`data` is typed with two interfaces exported by the package, empty by default. Each app extends them once with its own contracts (module augmentation, no generics at call sites), e.g. in `app/types/merkaly.d.ts`:
+
+```ts
+import type { AccountAuthProfile } from '@merkaly/api/account/auth';
+import type { SettingsOrganizationProfileResponse } from '@merkaly/api/settings/organization';
+
+declare module '@merkaly/nuxt' {
+  interface MerkalyOrganization extends SettingsOrganizationProfileResponse {}
+  interface MerkalyUser extends AccountAuthProfile {}
+}
+```
+
+The file must be a module (keep at least one `import` or an `export {}`), otherwise it replaces the package types instead of extending them. The loaders passed to `defineBootstrap` are checked against the same interfaces.
+
+In SSR apps (store) the organization stage also runs on the server, after the server plugins (`tenant.server.ts`), so it reaches the HTML; the client reuses it from the payload and does not request it again. `user` never runs on the server (there is no session there), so avoid rendering `user` data in SSR markup to keep hydration stable.
+
+#### Migration per app (breaking: `useTenant` is gone and `useAuth().user` changed)
+
+- `useTenant()` is removed; its keys live in `useOrganization()`: `tenant` → `id`, `setTenant(id, options)` → `setId(id, options)`, `fromServer` → `fromServer`, `isReady` (id set) → `hasId` (`isReady` now means the organization data loaded). The `merkaly:tenant` hook is unchanged: it still runs first and is where the id gets set.
+- `useAuth().user` (the Auth0 user) is now `useAuth().claims`, same object. `useAuth().user` is the loaded profile (`data`, `status`, `error`, `isReady`, `refresh`). Every current app read of `user` is a token field (name, email, picture, sub, roles claim), so the rename is `user` → `claims`, in templates too (`user.name` → `claims.name`, `v-if="user"` → `v-if="claims"`). `isAuthenticated` is unchanged.
+- The `merkaly:tenant` and `merkaly:auth` hooks still receive the Auth0 claims.
+
+- **admin**
+  - `app/plugins/auth.ts:4`: `const { setTenant } = useTenant()` → `const { setId } = useOrganization()`; line 25: `setTenant(data.orgId)` → `setId(data.orgId)`.
+  - `app/plugins/money.ts:8-18`: drop `useTenant()`, the `readSettingsOrganization()` call and the `watch(tenant, ...)`; use `watch(useOrganization().data, (data) => data && setMoneyDefaults({ currency: data.localization?.currency, locale: data.localization?.language }), { immediate: true })`.
+  - New `app/plugins/bootstrap.ts` and `app/types/merkaly.d.ts` (above).
+  - `app/composables/useAccountProfile.ts:5`: `const { user } = useAuth()` → `const { claims, user } = useAuth()`; line 7: `readAccountProfile()` → `const { data: profile, refresh } = user`; line 9: `user.value?.picture` → `claims.value?.picture`.
+  - `app/components/ui/select/SelectLocale.vue:9`: `{ user }` → `{ claims }`; line 32: `user.value?.name` → `claims.value?.name`.
+  - `app/components/ui/nav/NavUser.vue:2`: `{ user }` → `{ claims }`; template lines 22, 24, 25, 29, 30, 33, 50, 54, 61: `user` / `user.name` / `user.email` → `claims` / `claims.name` / `claims.email`.
+  - `app/pages/settings/(overview)/.components/SettingsMembersSection.vue:16`: `{ user }` → `{ claims }`; line 28: `user.value?.[AUTH_CLAIM]` → `claims.value?.[AUTH_CLAIM]`; line 36: `user.value?.sub` → `claims.value?.sub`.
+  - `app/pages/profile/(overview)/.components/ProfileOverviewSection.vue:7`: `{ user }` → `{ claims }`; lines 16, 22: `user.value?.name` → `claims.value?.name`; template lines 83 and 109: `user?.name`, `user?.email` → `claims?.name`, `claims?.email`.
+  - `app/pages/profile/(overview)/.components/ProfileSignInMethodSection.vue:9`: `{ user }` → `{ claims }`; template line 74: `user?.email` → `claims?.email`.
+  - `app/pages/settings/(overview)/.composables/useSettingsOrganization.ts:5` (optional): read `useOrganization()` (`data`, `status === 'pending'`, `refresh`) instead of a second `readSettingsOrganization()`.
+- **store**
+  - `app/plugins/tenant.server.ts:4`: `const { setTenant } = useTenant()` → `const { setId } = useOrganization()`; lines 7 and 15: `setTenant(..., { server: true })` → `setId(..., { server: true })`.
+  - `app/plugins/auth.ts:4`: `const { fromServer, setTenant } = useTenant()` → `const { fromServer, setId } = useOrganization()`; lines 9 and 13: `setTenant(...)` → `setId(...)`.
+  - `app/pages/checkout/.composables/usePaymentStream.ts:11`: `const { tenant } = useTenant()` → `const { id: tenant } = useOrganization()` (line 43 keeps `tenant.value`).
+  - `app/components/nav/NavUser.vue:8`: `user` → `claims` in the destructuring; template line 55: `user?.name` → `claims?.name`.
+  - `app/pages/checkout/index.vue:22`: `{ user }` → `{ claims }`; line 76: `watch(user, ...)` → `watch(claims, ...)`.
+  - `app/pages/account/.components/AccountUser.vue:2`: `{ user }` → `{ claims }`; line 4 and template lines 9, 10, 21, 23, 24: `user` → `claims`.
+  - New universal `app/plugins/bootstrap.ts` (above) and `app/types/merkaly.d.ts` with `MerkalyOrganization extends SettingsOrganizationStoreProfile`.
+  - `app/layouts/default.vue:5` and `app/pages/account/orders/[order]/index.vue:85`: `readAppCompany()` → `const { data: company } = useOrganization()`.
+  - `app/plugins/README.md:11` mentions `fromServer`: now from `useOrganization()`.
+- **dashboard**
+  - `app/components/ui/nav/NavUser.vue:2`: `{ user }` → `{ claims }`; line 7 and template lines 12, 21, 28, 33, 35: `user` → `claims`.
+  - No `useTenant` usages. Add `defineBootstrap({ user })` and `MerkalyUser` only if it needs `/auth/me` before the pages.
+- **www**
+  - `app/components/modals/ModalBookDemo.vue:11`: `{ isAuthenticated, user }` → `{ isAuthenticated, claims }`; lines 14 and 15: `user.value?.name`, `user.value?.email` → `claims.value?.name`, `claims.value?.email`.
+  - No `useTenant` usages, no loaders needed.
 
 ### Login entry points (`MKAuth`)
 
@@ -103,7 +219,7 @@ overrides it at runtime.
 **Client plugin.** Initializes `posthog-js` **only in production builds**
 (`nuxt dev` never sends events) with `api_host: '/phog'` and
 `ui_host: 'https://us.posthog.com'`. It identifies the Auth0 user from
-`useAuth()` (`identify(sub, { email, name })`) and calls `posthog.reset()` on
+`useAuth().claims` (`identify(sub, { email, name })`) and calls `posthog.reset()` on
 logout. The app can keep using `import posthog from 'posthog-js'` for
 `capture()`: the module dedupes `posthog-js` so the app and the plugin share
 the initialized instance (keep `posthog-js` as an app dependency).

package/dist/module.d.mts

@@ -3,6 +3,7 @@ import { ClientAuthorizationParams } from '@auth0/auth0-spa-js';
 import { Strategies } from '@nuxtjs/i18n';
 export { AdapterArgs, AdapterOptions } from '../dist/runtime/utils/withAdapter.js';
 export { ApiOptions, HooksOptions, ParamsOptions, RefOptions } from '../dist/runtime/plugins/api.global.js';
+export { BootstrapError, BootstrapLoader, BootstrapLoaders, BootstrapStatus, MerkalyOrganization, MerkalyUser } from '../dist/runtime/internal/state.js';
 
 interface MerkalyI18nLocale {
     code: string;

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": ">=3.14.0"
   },
-  "version": "0.12.5",
+  "version": "0.13.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -278,6 +278,7 @@ function configureNuxtOptions(nuxt, options) {
 function registerRuntimeFeatures(options, resolver) {
   addPlugin({ src: resolver.resolve("./runtime/plugins/api.global") });
   addPlugin({ src: resolver.resolve("./runtime/plugins/auth0.client") });
+  addPlugin({ src: resolver.resolve("./runtime/plugins/bootstrap.server") });
   addPlugin({ src: resolver.resolve("./runtime/plugins/sentry.global") });
   if (hasPosthogConfig(options)) {
     addPlugin({ src: resolver.resolve("./runtime/plugins/posthog.client") });

package/dist/runtime/components/app.vue

@@ -1,7 +1,7 @@
 <script setup>
 import { useRoute } from "#app";
 import { computed } from "vue";
-import { useAuth, useTenant, watchOnce, addRouteMiddleware, useNuxtApp, useRuntimeConfig } from "#imports";
+import { useAuth, useOrganization, watchOnce, addRouteMiddleware, useNuxtApp, useRuntimeConfig } from "#imports";
 import AuthMiddleware from "../middleware/auth";
 import { useNavigation } from "../composables/useNavigation";
 import AuthError from "./auth/AuthError.vue";
@@ -9,7 +9,7 @@ import { useColorMode } from "@vueuse/core";
 import { Notivue, NotificationProgress, Notification, pastelTheme } from "notivue";
 const $route = useRoute();
 const { clear, error, isLoading, logout, retry } = useAuth();
-const { fromServer } = useTenant();
+const { fromServer } = useOrganization();
 const { hook } = useNuxtApp();
 const { public: { merkaly } } = useRuntimeConfig();
 useColorMode({ attribute: "data-bs-theme" });

package/dist/runtime/components/auth/AuthError.vue

@@ -5,8 +5,15 @@ const props = defineProps({
 });
 const emit = defineEmits(["logout", "retry"]);
 const isDenied = computed(() => [401, 403].includes(props.error.status));
-const title = computed(() => isDenied.value ? "Access denied" : "We could not start your session");
-const description = computed(() => isDenied.value ? "You signed in successfully, but this account is not allowed to access this application." : "You signed in successfully, but something failed while preparing your session.");
+const isOrganization = computed(() => props.error.stage === "organization");
+const title = computed(() => {
+  if (isDenied.value) return "Access denied";
+  return isOrganization.value ? "We could not load this organization" : "We could not start your session";
+});
+const description = computed(() => {
+  if (isDenied.value) return "You signed in successfully, but this account is not allowed to access this application.";
+  return isOrganization.value ? "Something failed while loading the organization of this application." : "You signed in successfully, but something failed while preparing your session.";
+});
 const details = computed(() => [props.error.stage, props.error.status, props.error.url].filter(Boolean).join(" \xB7 "));
 </script>
 

package/dist/runtime/components/format/FormatDate.d.vue.ts

@@ -1,7 +1,7 @@
 import type { PropType } from 'vue';
 declare const __VLS_export: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     date: {
-        type: (DateConstructor | StringConstructor)[];
+        type: (StringConstructor | DateConstructor)[];
         default: () => Date;
     };
     format: {
@@ -10,7 +10,7 @@ declare const __VLS_export: import("vue").DefineComponent<import("vue").ExtractP
     };
 }>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
     date: {
-        type: (DateConstructor | StringConstructor)[];
+        type: (StringConstructor | DateConstructor)[];
         default: () => Date;
     };
     format: {

package/dist/runtime/components/format/FormatDate.vue.d.ts

@@ -1,7 +1,7 @@
 import type { PropType } from 'vue';
 declare const __VLS_export: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     date: {
-        type: (DateConstructor | StringConstructor)[];
+        type: (StringConstructor | DateConstructor)[];
         default: () => Date;
     };
     format: {
@@ -10,7 +10,7 @@ declare const __VLS_export: import("vue").DefineComponent<import("vue").ExtractP
     };
 }>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
     date: {
-        type: (DateConstructor | StringConstructor)[];
+        type: (StringConstructor | DateConstructor)[];
         default: () => Date;
     };
     format: {

package/dist/runtime/components/format/FormatIcon.d.vue.ts

@@ -18,7 +18,7 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
         required: true;
     };
     opacity: {
-        type: (NumberConstructor | StringConstructor)[];
+        type: (StringConstructor | NumberConstructor)[];
         default: () => string;
     };
     provider: {
@@ -71,7 +71,7 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
         required: true;
     };
     opacity: {
-        type: (NumberConstructor | StringConstructor)[];
+        type: (StringConstructor | NumberConstructor)[];
         default: () => string;
     };
     provider: {

package/dist/runtime/components/format/FormatIcon.vue.d.ts

@@ -18,7 +18,7 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
         required: true;
     };
     opacity: {
-        type: (NumberConstructor | StringConstructor)[];
+        type: (StringConstructor | NumberConstructor)[];
         default: () => string;
     };
     provider: {
@@ -71,7 +71,7 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
         required: true;
     };
     opacity: {
-        type: (NumberConstructor | StringConstructor)[];
+        type: (StringConstructor | NumberConstructor)[];
         default: () => string;
     };
     provider: {

package/dist/runtime/composables/useAuth.d.ts

@@ -1,5 +1,5 @@
 import type { User } from '@auth0/auth0-spa-js';
-export type AuthErrorStage = 'callback' | 'token' | 'session' | 'tenant';
+export type AuthErrorStage = 'callback' | 'token' | 'session' | 'tenant' | 'organization' | 'user';
 export interface AuthError {
     message: string;
     stage: AuthErrorStage;
@@ -13,6 +13,7 @@ export interface AuthErrorContext {
     retry: () => Promise<void>;
 }
 export declare const useAuth: () => {
+    claims: import("vue").Ref<User | undefined, User | undefined>;
     clear: () => undefined;
     error: import("vue").Ref<AuthError | undefined, AuthError | undefined>;
     fail: (reason: AuthError) => Promise<void>;
@@ -24,5 +25,11 @@ export declare const useAuth: () => {
         redirectTo?: string;
     }) => any;
     token: import("vue").Ref<string | null, string | null>;
-    user: import("vue").Ref<User | undefined, User | undefined>;
+    user: {
+        data: import("vue").Ref<import("../internal/state.js").MerkalyUser | undefined, import("../internal/state.js").MerkalyUser | undefined>;
+        error: import("vue").Ref<import("../internal/state.js").BootstrapError | undefined, import("../internal/state.js").BootstrapError | undefined>;
+        isReady: import("vue").ComputedRef<boolean>;
+        refresh: () => Promise<boolean>;
+        status: import("vue").Ref<import("../internal/state.js").BootstrapStatus, import("../internal/state.js").BootstrapStatus>;
+    };
 };

package/dist/runtime/composables/useAuth.js

@@ -1,12 +1,14 @@
 import { computed } from "vue";
 import { useNuxtApp, useState } from "#imports";
+import { useBootstrapStage } from "../internal/state.js";
 export const useAuth = () => {
   const nuxtApp = useNuxtApp();
-  const user = useState("auth:user", () => void 0);
+  const claims = useState("auth:claims", () => void 0);
   const token = useState("auth:token", () => null);
   const isLoading = useState("auth:loading", () => true);
   const error = useState("auth:error", () => void 0);
-  const isAuthenticated = computed(() => Boolean(user.value?.sub));
+  const isAuthenticated = computed(() => Boolean(claims.value?.sub));
+  const user = useBootstrapStage(nuxtApp, "user");
   const clear = () => error.value = void 0;
   const logout = () => nuxtApp.$auth0.logout();
   const signup = ({ redirectTo = "/" } = {}) => nuxtApp.$auth0.loginWithRedirect({
@@ -28,6 +30,7 @@ export const useAuth = () => {
     await nuxtApp.callHook("merkaly:auth:error", { clear, error: reason, logout, retry });
   };
   return {
+    claims,
     clear,
     error,
     fail,

package/dist/runtime/composables/useOrganization.d.ts

@@ -0,0 +1,13 @@
+export declare const useOrganization: () => {
+    fromServer: import("vue").Ref<boolean, boolean>;
+    hasId: import("vue").ComputedRef<boolean>;
+    id: import("vue").Ref<string, string>;
+    setId: (value: string, options?: {
+        server?: boolean;
+    }) => void;
+    data: import("vue").Ref<import("../internal/state.js").MerkalyOrganization | undefined, import("../internal/state.js").MerkalyOrganization | undefined>;
+    error: import("vue").Ref<import("../internal/state.js").BootstrapError | undefined, import("../internal/state.js").BootstrapError | undefined>;
+    isReady: import("vue").ComputedRef<boolean>;
+    refresh: () => Promise<boolean>;
+    status: import("vue").Ref<import("../internal/state.js").BootstrapStatus, import("../internal/state.js").BootstrapStatus>;
+};

package/dist/runtime/composables/useOrganization.js

@@ -0,0 +1,13 @@
+import { computed, useNuxtApp, useState } from "#imports";
+import { useBootstrapStage } from "../internal/state.js";
+export const useOrganization = () => {
+  const id = useState("merkaly:organization:id", () => "");
+  const fromServer = useState("merkaly:organization:server", () => false);
+  const stage = useBootstrapStage(useNuxtApp(), "organization");
+  const hasId = computed(() => Boolean(id.value));
+  const setId = (value, options = {}) => {
+    id.value = value;
+    if (options.server) fromServer.value = true;
+  };
+  return { ...stage, fromServer, hasId, id, setId };
+};

package/dist/runtime/internal/bootstrap.d.ts

@@ -0,0 +1,2 @@
+import type { NuxtApp } from '#app';
+export declare const runBootstrap: (nuxtApp: NuxtApp) => Promise<void>;

package/dist/runtime/internal/bootstrap.js

@@ -0,0 +1,13 @@
+import { useAuth } from "../composables/useAuth.js";
+import { inApp, runBootstrapStage, useBootstrapState } from "./state.js";
+export const runBootstrap = async (nuxtApp) => {
+  const { error, fail, isAuthenticated, token } = inApp(nuxtApp, useAuth);
+  if (error.value || nuxtApp.payload.error) return;
+  const failStage = (stage) => {
+    const reason = inApp(nuxtApp, () => useBootstrapState(stage)).error.value;
+    return fail({ message: reason?.message || `${stage} failed`, stage, status: reason?.status });
+  };
+  if (!await runBootstrapStage(nuxtApp, "organization")) return failStage("organization");
+  if (!isAuthenticated.value || !token.value) return;
+  if (!await runBootstrapStage(nuxtApp, "user")) return failStage("user");
+};

package/dist/runtime/internal/state.d.ts

@@ -0,0 +1,45 @@
+import type { NuxtApp } from '#app';
+import type { Ref } from '#imports';
+export interface MerkalyOrganization {
+}
+export interface MerkalyUser {
+}
+export type BootstrapStage = 'organization' | 'user';
+export type BootstrapStatus = 'idle' | 'pending' | 'success' | 'error';
+export interface BootstrapError {
+    message: string;
+    status?: number;
+}
+interface AdapterLike<T> {
+    data: Ref<T>;
+    error: Ref<unknown>;
+    execute: () => Promise<void>;
+    loading: Ref<boolean>;
+}
+export type BootstrapLoader<T = unknown> = () => T | Promise<T> | AdapterLike<T>;
+export interface BootstrapLoaders {
+    organization?: BootstrapLoader<MerkalyOrganization>;
+    user?: BootstrapLoader<MerkalyUser>;
+}
+interface StageData {
+    organization: MerkalyOrganization;
+    user: MerkalyUser;
+}
+export declare const inApp: <T>(nuxtApp: NuxtApp, fn: () => T) => T;
+export declare const registerBootstrapLoaders: (nuxtApp: NuxtApp, loaders: BootstrapLoaders) => void;
+export declare const useBootstrapState: <S extends BootstrapStage>(stage: S) => {
+    data: Ref<StageData[S] | undefined, StageData[S] | undefined>;
+    error: Ref<BootstrapError | undefined, BootstrapError | undefined>;
+    status: Ref<BootstrapStatus, BootstrapStatus>;
+};
+export declare const runBootstrapStage: (nuxtApp: NuxtApp, stage: BootstrapStage, { force }?: {
+    force?: boolean | undefined;
+}) => Promise<boolean>;
+export declare const useBootstrapStage: <S extends BootstrapStage>(nuxtApp: NuxtApp, stage: S) => {
+    data: Ref<StageData[S] | undefined, StageData[S] | undefined>;
+    error: Ref<BootstrapError | undefined, BootstrapError | undefined>;
+    isReady: import("vue").ComputedRef<boolean>;
+    refresh: () => Promise<boolean>;
+    status: Ref<BootstrapStatus, BootstrapStatus>;
+};
+export {};

package/dist/runtime/internal/state.js

@@ -0,0 +1,51 @@
+import { computed, useState } from "#imports";
+import { until } from "@vueuse/core";
+export const inApp = (nuxtApp, fn) => nuxtApp.runWithContext(fn);
+const registry = /* @__PURE__ */ new WeakMap();
+export const registerBootstrapLoaders = (nuxtApp, loaders) => {
+  registry.set(nuxtApp, { ...registry.get(nuxtApp), ...loaders });
+};
+export const useBootstrapState = (stage) => ({
+  data: useState(`merkaly:${stage}:data`, () => void 0),
+  error: useState(`merkaly:${stage}:error`, () => void 0),
+  status: useState(`merkaly:${stage}:status`, () => "idle")
+});
+const isAdapter = (value) => Boolean(value && typeof value === "object" && "execute" in value && "loading" in value);
+const toError = (reason) => {
+  const value = reason;
+  return {
+    message: String(value?.message || reason || "Request failed"),
+    status: Number(value?.statusCode ?? value?.status) || void 0
+  };
+};
+const resolveLoader = async (nuxtApp, loader) => {
+  const result = await nuxtApp.runWithContext(loader);
+  if (!isAdapter(result)) return result;
+  if (result.loading.value) await until(result.loading).toBe(false);
+  else await result.execute();
+  if (result.error.value) throw result.error.value;
+  return result.data.value;
+};
+export const runBootstrapStage = (nuxtApp, stage, { force = false } = {}) => {
+  const loader = registry.get(nuxtApp)?.[stage];
+  const { data, error, status } = inApp(nuxtApp, () => useBootstrapState(stage));
+  if (!loader) return Promise.resolve(true);
+  if (status.value === "success" && !force) return Promise.resolve(true);
+  status.value = "pending";
+  error.value = void 0;
+  return resolveLoader(nuxtApp, loader).then((value) => {
+    data.value = value;
+    status.value = "success";
+    return true;
+  }).catch((reason) => {
+    error.value = toError(reason);
+    status.value = "error";
+    return false;
+  });
+};
+export const useBootstrapStage = (nuxtApp, stage) => {
+  const { data, error, status } = useBootstrapState(stage);
+  const isReady = computed(() => status.value === "success");
+  const refresh = () => runBootstrapStage(nuxtApp, stage, { force: true });
+  return { data, error, isReady, refresh, status };
+};

package/dist/runtime/plugins/api.global.js

@@ -1,5 +1,5 @@
 import { defineNuxtPlugin, useNuxtApp, useRequestURL, useRuntimeConfig } from "#app";
-import { useAuth, useTenant } from "#imports";
+import { useAuth, useOrganization } from "#imports";
 const GLOBAL_API_HEADER = "x-merkaly-global";
 function serverBaseURL(api, global) {
   const prefix = global ? "" : (api.prefix ?? "").replace(/^\/+|\/+$/g, "");
@@ -14,7 +14,7 @@ export default defineNuxtPlugin(({ provide }) => {
   provide("api", async (url, options = {}) => {
     const { token } = useAuth();
     if (import.meta.client && token.value) await nuxtApp.$auth0?.getTokenSilently();
-    const { tenant } = useTenant();
+    const { id: tenant } = useOrganization();
     const { public: { merkaly } } = useRuntimeConfig();
     const requiresTenant = options.requiresTenant ?? merkaly.auth0.requiresTenant;
     if (!tenant.value && !options.global && requiresTenant) {
@@ -22,7 +22,7 @@ export default defineNuxtPlugin(({ provide }) => {
         `[api] Tenant context is required but not set for: ${url}
 This surface has requiresTenant: true. Possible causes:
   1. The request fired before the auth boot sequence completed (race condition).
-  2. setTenant() was never called in this surface's auth plugin.
+  2. useOrganization().setId() was never called in this surface's auth plugin.
   3. The adapter should use { global: true } to bypass tenant enforcement.`
       );
     }

package/dist/runtime/plugins/auth0.client.js

@@ -3,8 +3,10 @@ import { defineNuxtPlugin, useRuntimeConfig, useNuxtApp, useState } from "#impor
 import { navigateTo } from "#app";
 import { defu } from "defu";
 import { useAuth } from "../composables/useAuth.js";
+import { runBootstrap } from "../internal/bootstrap.js";
 const NO_SESSION_ERRORS = ["consent_required", "interaction_required", "invalid_grant", "login_required", "missing_refresh_token"];
-export default defineNuxtPlugin(async ({ callHook, hook }) => {
+export default defineNuxtPlugin(async (nuxtApp) => {
+  const { callHook, hook } = nuxtApp;
   const { public: $config } = useRuntimeConfig();
   const callbackPath = URL.canParse($config.merkaly.auth0.callbackUrl) ? new URL($config.merkaly.auth0.callbackUrl).pathname : $config.merkaly.auth0.callbackUrl;
   const auth0 = await createAuth0Client({
@@ -13,11 +15,11 @@ export default defineNuxtPlugin(async ({ callHook, hook }) => {
     domain: $config.merkaly.auth0.domain,
     useRefreshTokens: true
   });
-  const { error, isLoading, user, token, fail } = useAuth();
+  const { claims, error, isLoading, token, fail } = useAuth();
   const isStarting = useState("auth:starting", () => false);
   const self0 = Object.assign(Object.create(Object.getPrototypeOf(auth0)), auth0);
   let tokenError;
-  auth0.getUser = () => self0.getUser().then((result) => user.value = result).catch((reason) => console.error("[Auth0] getUser failed", reason));
+  auth0.getUser = () => self0.getUser().then((result) => claims.value = result).catch((reason) => console.error("[Auth0] getUser failed", reason));
   auth0.getTokenSilently = (options = {}) => self0.getTokenSilently(defu({ authorizationParams: { audience: $config.merkaly.auth0.audience } }, options)).then((result) => {
     tokenError = void 0;
     return token.value = result;
@@ -28,26 +30,27 @@ export default defineNuxtPlugin(async ({ callHook, hook }) => {
   const resolveIdentity = () => Promise.allSettled([auth0.getUser(), auth0.getTokenSilently()]);
   const initTenantContext = async () => {
     try {
-      await callHook("merkaly:tenant", user.value);
-      await callHook("merkaly:auth", user.value);
+      await callHook("merkaly:tenant", claims.value);
+      await callHook("merkaly:auth", claims.value);
     } catch (reason) {
       if (!error.value) {
         await fail({ message: reason?.message || String(reason), stage: "tenant" });
       }
     }
+    await runBootstrap(nuxtApp);
   };
   const startSession = async () => {
-    if (user.value && !token.value && tokenError && !NO_SESSION_ERRORS.includes(tokenError.error)) {
+    if (claims.value && !token.value && tokenError && !NO_SESSION_ERRORS.includes(tokenError.error)) {
       return fail({ message: tokenError.error_description || tokenError.message, stage: "token" });
     }
-    if (user.value && !token.value && tokenError) {
-      user.value = void 0;
+    if (claims.value && !token.value && tokenError) {
+      claims.value = void 0;
       await self0.logout({ openUrl: false });
       if ($config.merkaly.auth0.requiresAuth) {
         return auth0.loginWithRedirect({ appState: { target: location.pathname + location.search } });
       }
     }
-    if (!user.value && $config.merkaly.auth0.requiresAuth) {
+    if (!claims.value && $config.merkaly.auth0.requiresAuth) {
       return auth0.loginWithRedirect({ appState: { target: location.pathname + location.search } });
     }
     return initTenantContext();
@@ -86,14 +89,14 @@ export default defineNuxtPlugin(async ({ callHook, hook }) => {
   auth0.linkWithConnection = async (connection) => {
     const client = getLinkingClient();
     await client.loginWithPopup({ authorizationParams: { connection } });
-    const claims = await client.getIdTokenClaims();
-    if (!claims?.__raw) {
+    const idClaims = await client.getIdTokenClaims();
+    if (!idClaims?.__raw) {
       throw new Error("Failed to get ID token for linking");
     }
     const { $api } = useNuxtApp();
     return await $api("/auth/identities", {
       // the api verifies it and derives the identity
-      body: { idToken: claims.__raw },
+      body: { idToken: idClaims.__raw },
       global: true,
       method: "POST"
     });

package/dist/runtime/plugins/bootstrap.server.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from '#app';
+declare const plugin: Plugin;
+export default plugin;

package/dist/runtime/plugins/bootstrap.server.js

@@ -0,0 +1,6 @@
+import { defineNuxtPlugin } from "#imports";
+import { runBootstrap } from "../internal/bootstrap.js";
+const plugin = defineNuxtPlugin((nuxtApp) => {
+  nuxtApp.hook("app:created", () => runBootstrap(nuxtApp));
+});
+export default plugin;

package/dist/runtime/plugins/posthog.client.js

@@ -14,9 +14,9 @@ export default defineNuxtPlugin(() => {
     // first-party proxy
     ui_host: "https://us.posthog.com"
   });
-  const { user } = useAuth();
-  watchImmediate(() => user.value?.sub, (sub, previous) => {
-    if (sub) return posthog.identify(sub, { email: user.value?.email, name: user.value?.name });
+  const { claims } = useAuth();
+  watchImmediate(() => claims.value?.sub, (sub, previous) => {
+    if (sub) return posthog.identify(sub, { email: claims.value?.email, name: claims.value?.name });
     if (previous) posthog.reset();
   });
 });

package/dist/runtime/types/nuxt.d.ts

@@ -15,10 +15,10 @@ declare module '#app' {
   }
 
   interface RuntimeNuxtHooks {
-    'merkaly:auth': (user?: User) => HookResult;
+    'merkaly:auth': (claims?: User) => HookResult;
     'merkaly:auth:error': (context: AuthErrorContext) => HookResult;
     'merkaly:auth:retry': () => HookResult;
-    'merkaly:tenant': (user?: User) => HookResult;
+    'merkaly:tenant': (claims?: User) => HookResult;
   }
 }
 

package/dist/runtime/utils/defineBootstrap.d.ts

@@ -0,0 +1,2 @@
+import type { BootstrapLoaders } from '../internal/state.js';
+export declare const defineBootstrap: (loaders: BootstrapLoaders) => void;

package/dist/runtime/utils/defineBootstrap.js

@@ -0,0 +1,3 @@
+import { useNuxtApp } from "#imports";
+import { registerBootstrapLoaders } from "../internal/state.js";
+export const defineBootstrap = (loaders) => registerBootstrapLoaders(useNuxtApp(), loaders);

package/dist/types.d.mts

@@ -8,6 +8,8 @@ export { type AdapterArgs, type AdapterOptions } from '../dist/runtime/utils/wit
 
 export { type ApiOptions, type HooksOptions, type ParamsOptions, type RefOptions } from '../dist/runtime/plugins/api.global.js'
 
+export { type BootstrapError, type BootstrapLoader, type BootstrapLoaders, type BootstrapStatus, type MerkalyOrganization, type MerkalyUser } from '../dist/runtime/internal/state.js'
+
 export { default } from './module.mjs'
 
 export { type MerkalyI18nLocale, type MerkalyModuleOptions } from './module.mjs'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@merkaly/nuxt",
-  "version": "0.12.5",
+  "version": "0.13.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/merkaly-io/nuxt.git"

package/dist/runtime/composables/useTenant.d.ts

@@ -1,8 +0,0 @@
-export declare const useTenant: () => {
-    fromServer: import("vue").Ref<boolean, boolean>;
-    isReady: import("vue").ComputedRef<boolean>;
-    setTenant: (value: string, options?: {
-        server?: boolean;
-    }) => void;
-    tenant: import("vue").Ref<string, string>;
-};

package/dist/runtime/composables/useTenant.js

@@ -1,17 +0,0 @@
-import { computed } from "vue";
-import { useState } from "#imports";
-export const useTenant = () => {
-  const tenant = useState("tenant:id", () => "");
-  const fromServer = useState("tenant:server", () => false);
-  const isReady = computed(() => Boolean(tenant.value));
-  const setTenant = (value, options = {}) => {
-    tenant.value = value;
-    if (options.server) fromServer.value = true;
-  };
-  return {
-    fromServer,
-    isReady,
-    setTenant,
-    tenant
-  };
-};