@lupinum/better-convex-nuxt 0.8.0-beta.40

package/dist/module.mjs

@@ -0,0 +1,309 @@
+import { existsSync } from 'node:fs';
+import { useLogger, defineNuxtModule, createResolver, addTemplate, addServerPlugin, addServerHandler, addPlugin, addTypeTemplate, addRouteMiddleware, addImports, addServerImports, resolvePath } from '@nuxt/kit';
+import { defu } from 'defu';
+import { getPackedRuntimeFingerprint } from '../dist/runtime/shared/release-fingerprint.js';
+import { normalizeConvexAuthConfig, isConvexAuthEnabled } from '../dist/runtime/utils/auth-config.js';
+import { CONVEX_MODULE_DEFAULTS } from '../dist/runtime/utils/config-defaults.js';
+import { resolveConvexSiteUrl, getSiteUrlResolutionHint } from '../dist/runtime/utils/convex-config.js';
+import { normalizeConvexDeploymentUrl, normalizeConvexSiteUrl } from '../dist/runtime/utils/site-url.js';
+
+function registerConvexAliases(options) {
+  const { nuxt, resolver, convexApiAlias } = options;
+  const convexServerAlias = resolver.resolve("./runtime/server/index");
+  nuxt.options.alias["#convex/api"] = convexApiAlias;
+  nuxt.options.alias["#convex/server"] = convexServerAlias;
+  nuxt.hook("prepare:types", (opts) => {
+    opts.references.push({
+      path: resolver.resolve(nuxt.options.buildDir, "types/better-convex-nuxt.d.ts")
+    });
+    opts.tsConfig.compilerOptions ??= {};
+    opts.tsConfig.compilerOptions.paths ??= {};
+    opts.tsConfig.compilerOptions.paths["#convex/api"] = [convexApiAlias];
+    opts.tsConfig.compilerOptions.paths["#convex/server"] = [convexServerAlias];
+  });
+}
+
+const composableAutoImports = [
+  { name: "useConvex", from: "./runtime/composables/useConvex" },
+  {
+    name: "useConvexAttachment",
+    from: "./runtime/composables/useConvexAttachment"
+  },
+  { name: "useConvexConfig", from: "./runtime/composables/useConvexConfig" },
+  {
+    name: "useConvexMutation",
+    from: "./runtime/composables/useConvexMutation"
+  },
+  { name: "useConvexAction", from: "./runtime/composables/useConvexAction" },
+  { name: "useConvexQuery", from: "./runtime/composables/useConvexQuery" },
+  {
+    name: "useConvexPaginatedQuery",
+    from: "./runtime/composables/useConvexPaginatedQuery"
+  },
+  {
+    name: "useConvexConnectionState",
+    from: "./runtime/composables/useConvexConnectionState"
+  },
+  {
+    name: "useConvexFileUpload",
+    from: "./runtime/composables/useConvexFileUpload"
+  }
+];
+const authAutoImports = [
+  { name: "useConvexAuth", from: "./runtime/composables/useConvexAuth" }
+];
+const serverAutoImports = [
+  { name: "serverConvex", from: "./runtime/server/utils/server-convex-caller" }
+];
+
+function getMissingConvexApiTemplateContents() {
+  return `
+type MissingConvexGeneratedApi = {
+  /**
+   * The generated Convex API was not found.
+   * Run the file-bound Convex dev command or \`pnpm exec better-convex-nuxt-convex codegen\` to create \`convex/_generated/api\`.
+   */
+  readonly __betterConvexNuxtError: 'Missing generated Convex API. Run the file-bound Convex dev command or pnpm exec better-convex-nuxt-convex codegen.'
+}
+
+function createMissingConvexApiProxy(path: string[]): MissingConvexGeneratedApi {
+  return new Proxy({} as MissingConvexGeneratedApi, {
+    get(_target, prop) {
+      if (typeof prop === 'symbol') return undefined
+      if (prop === '__betterConvexNuxtError') {
+        return 'Missing generated Convex API. Run the file-bound Convex dev command or pnpm exec better-convex-nuxt-convex codegen.'
+      }
+      const accessPath = [...path, String(prop)].join('.')
+      throw new Error(
+        '[better-convex-nuxt] #convex/api points to a placeholder because convex/_generated/api was not found. ' +
+          'Run the file-bound Convex dev command or \`pnpm exec better-convex-nuxt-convex codegen\` to generate your Convex API. ' +
+          'Attempted to access ' + accessPath + '.',
+      )
+    },
+  })
+}
+
+export const api = createMissingConvexApiProxy([])
+export const internal = createMissingConvexApiProxy(['internal'])
+export const components = createMissingConvexApiProxy(['components'])
+`;
+}
+function getTypeAugmentationTemplateContents(authPageMetaTypeImport) {
+  const authPageMetaImportSpecifier = JSON.stringify(authPageMetaTypeImport);
+  return `
+import type { ConvexAuthPageMeta } from ${authPageMetaImportSpecifier}
+
+// Consumers use the stable \`useConvex()\` handle and auth composables instead
+// of raw replaceable clients. Only route-protection page metadata needs a
+// generated type augmentation.
+declare module '#app' {
+  interface PageMeta {
+    /**
+     * Opt-in route protection powered by better-convex-nuxt.
+     * true = require auth (default redirect), object = custom redirect.
+     */
+    convexAuth?: ConvexAuthPageMeta
+  }
+}
+
+export {}
+`;
+}
+
+const releaseRuntimeFingerprint = getPackedRuntimeFingerprint();
+const logger = useLogger("@lupinum/better-convex-nuxt");
+function hasGeneratedConvexApi(aliasPath) {
+  return existsSync(aliasPath) || existsSync(`${aliasPath}.ts`) || existsSync(`${aliasPath}.js`) || existsSync(`${aliasPath}.d.ts`);
+}
+function resolveModuleImports(resolver, imports) {
+  return imports.map((entry) => ({
+    name: entry.name,
+    from: resolver.resolve(entry.from)
+  }));
+}
+const AUTH_CLIENT_CONVENTION_FILENAME = "convex-auth.ts";
+async function resolveAuthClientDefinitionPath(authOptions, nuxt, resolver) {
+  const explicit = typeof authOptions.client === "string" ? authOptions.client.trim() : "";
+  if (explicit) {
+    const resolved = await resolvePath(explicit, {
+      cwd: nuxt.options.rootDir,
+      alias: nuxt.options.alias
+    });
+    if (!existsSync(resolved)) {
+      throw new Error(
+        `[better-convex-nuxt] auth.client "${explicit}" could not be resolved to an existing file (resolved to "${resolved}"). Provide a path or alias to a module that default-exports a defineConvexAuthClient(...) definition.`
+      );
+    }
+    return resolved;
+  }
+  const conventionPath = resolver.resolve(nuxt.options.srcDir, AUTH_CLIENT_CONVENTION_FILENAME);
+  if (existsSync(conventionPath)) {
+    return conventionPath;
+  }
+  return resolver.resolve("./runtime/auth-client/empty-definition");
+}
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "@lupinum/better-convex-nuxt",
+    configKey: "convex",
+    compatibility: {
+      nuxt: "4.5.1"
+    }
+  },
+  defaults: {
+    url: process.env.NUXT_PUBLIC_CONVEX_URL || process.env.CONVEX_URL,
+    siteUrl: process.env.NUXT_PUBLIC_CONVEX_SITE_URL || process.env.CONVEX_SITE_URL,
+    // Auth is intentionally omitted: an ordinary Convex application has no
+    // Better Auth build graph unless it opts in with an auth object.
+    logging: CONVEX_MODULE_DEFAULTS.logging
+  },
+  async setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    const generatedConvexApiAlias = resolver.resolve(nuxt.options.rootDir, "convex/_generated/api");
+    const missingConvexApiTemplate = addTemplate({
+      filename: "@lupinum/better-convex-nuxt/convex-api-missing.ts",
+      write: true,
+      getContents: getMissingConvexApiTemplateContents
+    });
+    const convexApiAlias = hasGeneratedConvexApi(generatedConvexApiAlias) ? generatedConvexApiAlias : missingConvexApiTemplate.dst;
+    const resolvedUrl = options.url ? normalizeConvexDeploymentUrl(options.url) : void 0;
+    const siteUrlResolution = resolveConvexSiteUrl({
+      url: resolvedUrl,
+      siteUrl: options.siteUrl
+    });
+    const resolvedSiteUrl = siteUrlResolution.siteUrl;
+    if (resolvedSiteUrl) normalizeConvexSiteUrl(resolvedSiteUrl);
+    const normalizedAuthConfig = normalizeConvexAuthConfig(options.auth);
+    const isAuthEnabled = isConvexAuthEnabled(normalizedAuthConfig);
+    if (isAuthEnabled && !resolvedSiteUrl) {
+      logger.warn(
+        `Authentication is enabled but no usable siteUrl was resolved. ${getSiteUrlResolutionHint(resolvedUrl)}`
+      );
+    }
+    const convexConfig = {
+      ...defu(nuxt.options.runtimeConfig.public.convex, {
+        url: resolvedUrl || "",
+        siteUrl: resolvedSiteUrl || "",
+        logging: options.logging ?? CONVEX_MODULE_DEFAULTS.logging
+      }),
+      // Auth is build policy, not a deploy-time/public runtime override.
+      auth: normalizedAuthConfig
+    };
+    nuxt.options.runtimeConfig.public.convex = convexConfig;
+    registerConvexAliases({ nuxt, resolver, convexApiAlias });
+    addServerPlugin(resolver.resolve("./runtime/server/plugins/runtime-config"));
+    if (releaseRuntimeFingerprint) {
+      addServerHandler({
+        route: "/api/_better-convex-nuxt/release-fingerprint",
+        handler: resolver.resolve("./runtime/server/api/release-fingerprint")
+      });
+    }
+    if (!isAuthEnabled) addPlugin(resolver.resolve("./runtime/plugin.client"));
+    addPlugin({
+      src: resolver.resolve("./runtime/plugins/convex-call-error-payload"),
+      mode: "all",
+      order: -50
+    });
+    if (isAuthEnabled) {
+      const authClientDefinitionPath = await resolveAuthClientDefinitionPath(
+        options.auth,
+        nuxt,
+        resolver
+      );
+      const authClientTemplate = addTemplate({
+        filename: "@lupinum/better-convex-nuxt/auth-client.mjs",
+        write: true,
+        getContents: () => `export { default } from ${JSON.stringify(authClientDefinitionPath)}
+`
+      });
+      nuxt.options.alias["#convex/auth-client"] = authClientTemplate.dst;
+      addTypeTemplate({
+        filename: "types/better-convex-nuxt-auth-client.d.ts",
+        getContents: () => [
+          `import type definition from ${JSON.stringify(authClientDefinitionPath)}`,
+          ``,
+          `declare module '@lupinum/better-convex-nuxt/auth-client' {`,
+          `  interface ConvexAuthClientRegistry {`,
+          `    definition: typeof definition`,
+          `  }`,
+          `}`,
+          ``
+        ].join("\n")
+      });
+      nuxt.hook("prepare:types", (opts) => {
+        opts.tsConfig.compilerOptions ??= {};
+        opts.tsConfig.compilerOptions.paths ??= {};
+        opts.tsConfig.compilerOptions.paths["#convex/auth-client"] = [authClientTemplate.dst];
+      });
+      addPlugin({
+        src: resolver.resolve("./runtime/plugin.server"),
+        mode: "server"
+      });
+      addPlugin({
+        src: resolver.resolve("./runtime/plugin.auth.client"),
+        mode: "client"
+      });
+      addRouteMiddleware({
+        name: "convex-auth",
+        path: resolver.resolve("./runtime/middleware/convex-auth.global"),
+        global: true
+      });
+      addServerHandler({
+        route: "/api/auth",
+        handler: resolver.resolve("./runtime/server/api/auth/[...]")
+      });
+      addServerHandler({
+        route: "/api/auth/jwks",
+        handler: resolver.resolve("./runtime/server/api/auth/jwks")
+      });
+      addServerHandler({
+        route: "/api/auth/**",
+        handler: resolver.resolve("./runtime/server/api/auth/[...]")
+      });
+      addServerHandler({
+        route: "/.well-known/oauth-authorization-server/api/auth",
+        handler: resolver.resolve("./runtime/server/api/auth/authorization-server-metadata")
+      });
+      addTemplate({
+        filename: "types/better-convex-nuxt-auth.d.ts",
+        getContents: () => getTypeAugmentationTemplateContents(
+          resolver.resolve("./runtime/utils/auth-route-protection")
+        )
+      });
+      addImports(resolveModuleImports(resolver, authAutoImports));
+    }
+    addImports(resolveModuleImports(resolver, composableAutoImports));
+    addServerImports(resolveModuleImports(resolver, serverAutoImports));
+    if (nuxt.options.dev) {
+      setupDevTools(nuxt, resolver);
+    }
+  }
+});
+function setupDevTools(nuxt, resolver) {
+  const devtoolsOutputPath = resolver.resolve("./runtime/devtools/ui/dist");
+  nuxt.options.runtimeConfig.convexDevtoolsPath = devtoolsOutputPath;
+  nuxt.hook("devtools:customTabs", (tabs) => {
+    tabs.push({
+      name: "convex",
+      title: "Convex",
+      icon: "/__convex_devtools__/convex-logo.svg",
+      category: "app",
+      view: {
+        type: "iframe",
+        src: "/__convex_devtools__",
+        persistent: true
+      }
+    });
+  });
+  addServerHandler({
+    route: "/__convex_devtools__",
+    handler: resolver.resolve("./runtime/devtools/server")
+  });
+  addServerHandler({
+    route: "/__convex_devtools__/**",
+    handler: resolver.resolve("./runtime/devtools/server")
+  });
+  logger.info("Nuxt DevTools integration enabled");
+}
+
+export { module$1 as default };

package/dist/runtime/auth/auth-identity.d.ts

@@ -0,0 +1,31 @@
+import { type ConvexIdentityKey } from '../utils/identity-key.js';
+import type { ConvexUser } from '../utils/types.js';
+/**
+ * Identity as ONE discriminated value (architecture invariant). Never independent booleans
+ * for token/user/authenticated/loading, and never a manufactured empty-string
+ * user field. `key` is always the stable Better Auth `user.id`.
+ */
+export type AuthIdentity = {
+    status: 'loading';
+} | {
+    status: 'anonymous';
+} | {
+    status: 'authenticated';
+    token: string;
+    user: ConvexUser;
+    key: `user:${string}`;
+};
+export declare const LOADING_IDENTITY: AuthIdentity;
+export declare const ANONYMOUS_IDENTITY: AuthIdentity;
+/**
+ * Build an authenticated identity from a confirmed token + user, or fall back to
+ * anonymous when the user has no stable id. A token without a resolved user is
+ * not a settled identity. Pure.
+ */
+export declare function toAuthenticatedIdentity(token: string, user: ConvexUser): AuthIdentity;
+/** The stable identity key for any identity value. Settled values only. */
+export declare function identityKeyOf(identity: AuthIdentity): ConvexIdentityKey;
+/** The published token, or null for any non-authenticated identity. */
+export declare function identityToken(identity: AuthIdentity): string | null;
+/** The published user, or null for any non-authenticated identity. */
+export declare function identityUser(identity: AuthIdentity): ConvexUser | null;

package/dist/runtime/auth/auth-identity.js

@@ -0,0 +1,21 @@
+import { getConvexIdentityKey } from "../utils/identity-key.js";
+export const LOADING_IDENTITY = { status: "loading" };
+export const ANONYMOUS_IDENTITY = { status: "anonymous" };
+export function toAuthenticatedIdentity(token, user) {
+  try {
+    const key = getConvexIdentityKey(user);
+    if (key === "anonymous") return ANONYMOUS_IDENTITY;
+    return { status: "authenticated", token, user, key };
+  } catch {
+    return ANONYMOUS_IDENTITY;
+  }
+}
+export function identityKeyOf(identity) {
+  return identity.status === "authenticated" ? identity.key : "anonymous";
+}
+export function identityToken(identity) {
+  return identity.status === "authenticated" ? identity.token : null;
+}
+export function identityUser(identity) {
+  return identity.status === "authenticated" ? identity.user : null;
+}

package/dist/runtime/auth/better-auth-browser-adapter.d.ts

@@ -0,0 +1,33 @@
+import type { BetterConvexAuthAdapter } from '@lupinum/better-convex-vue';
+import { type Ref } from 'vue';
+import type { ConvexUser } from '../utils/types.js';
+import { type ConvexTokenSource } from './token-fetcher.js';
+interface BetterAuthSessionState {
+    data?: {
+        session?: {
+            token?: unknown;
+        };
+        user?: {
+            id?: unknown;
+        };
+    } | null;
+    isPending?: boolean;
+    isRefetching?: boolean;
+    error?: unknown;
+    refetch?: () => Promise<void>;
+}
+interface BetterAuthBrowserSource extends ConvexTokenSource {
+    useSession(): Readonly<Ref<BetterAuthSessionState>>;
+}
+/** Private first-party adapter proof. It becomes a Nuxt adapter only after the atomic package cut. */
+export declare function createBetterAuthBrowserAdapter(source: BetterAuthBrowserSource, callbacks?: {
+    authenticated(token: string, user: ConvexUser): void;
+    anonymous(error: string | null): void;
+    sessionChanged?(sessionToken: string | null, error: string | null, sessionGeneration: number): void;
+}, options?: {
+    initialIdentityKey?: string;
+}): BetterConvexAuthAdapter & {
+    failClosed(message: string): void;
+    dispose(): void;
+};
+export {};

package/dist/runtime/auth/better-auth-browser-adapter.js

@@ -0,0 +1,215 @@
+import { watch } from "vue";
+import { fetchConvexToken, isTokenUsable } from "./token-fetcher.js";
+const UNAVAILABLE = "Authentication is temporarily unavailable";
+const SESSION_SETTLEMENT_TIMEOUT_MS = 5e3;
+function isUnauthorized(error) {
+  return Boolean(
+    error && typeof error === "object" && "status" in error && error.status === 401
+  );
+}
+export function createBetterAuthBrowserAdapter(source, callbacks = { authenticated: () => {
+}, anonymous: () => {
+} }, options = {}) {
+  const session = source.useSession();
+  const listeners = /* @__PURE__ */ new Set();
+  const cancelSessionSettlement = /* @__PURE__ */ new Set();
+  let disposed = false;
+  let sessionGeneration = 0;
+  let observedSessionToken;
+  let observedIdentityKey = options.initialIdentityKey;
+  let cachedToken = null;
+  let snapshot = options.initialIdentityKey ? {
+    status: "authenticated",
+    identityKey: options.initialIdentityKey,
+    sessionGeneration,
+    error: null
+  } : {
+    status: "loading",
+    identityKey: null,
+    sessionGeneration,
+    error: null
+  };
+  const notify = () => {
+    for (const listener of [...listeners]) {
+      try {
+        listener();
+      } catch {
+      }
+    }
+  };
+  const publishFromSession = (value) => {
+    const rawSessionToken = value.data?.session?.token;
+    const sessionToken = typeof rawSessionToken === "string" && rawSessionToken.length > 0 ? rawSessionToken : null;
+    const rawUserId = value.data?.user?.id;
+    const userId = typeof rawUserId === "string" && rawUserId.length > 0 ? rawUserId : null;
+    const key = userId;
+    if (value.isPending === true) {
+      if (observedSessionToken === void 0 && observedIdentityKey !== void 0 && snapshot.status === "authenticated") {
+        return;
+      }
+      snapshot = {
+        status: "loading",
+        identityKey: null,
+        sessionGeneration,
+        error: null
+      };
+      notify();
+      return;
+    }
+    const malformed = value.data?.session !== void 0 && sessionToken === null || sessionToken !== null && key === null;
+    const retainsEstablishedSession = Boolean(value.error) && !isUnauthorized(value.error) && snapshot.status === "authenticated" && observedSessionToken === sessionToken && observedIdentityKey === key;
+    if (retainsEstablishedSession) return;
+    if (value.error || malformed) {
+      cachedToken = null;
+      sessionGeneration += 1;
+      observedSessionToken = null;
+      observedIdentityKey = null;
+      snapshot = {
+        status: "error",
+        identityKey: null,
+        sessionGeneration,
+        error: new Error(UNAVAILABLE)
+      };
+      callbacks.anonymous(UNAVAILABLE);
+      callbacks.sessionChanged?.(null, UNAVAILABLE, sessionGeneration);
+      notify();
+      return;
+    }
+    const establishesMatchingProvisionalIdentity = observedSessionToken === void 0 && observedIdentityKey !== void 0 && observedIdentityKey === key;
+    const changed = !establishesMatchingProvisionalIdentity && (observedSessionToken !== sessionToken || observedIdentityKey !== key);
+    if (changed) {
+      sessionGeneration += 1;
+      cachedToken = null;
+    }
+    observedSessionToken = sessionToken;
+    observedIdentityKey = key;
+    snapshot = sessionToken && key ? {
+      status: "authenticated",
+      identityKey: key,
+      sessionGeneration,
+      error: null
+    } : {
+      status: "anonymous",
+      identityKey: null,
+      sessionGeneration,
+      error: null
+    };
+    if (!sessionToken) callbacks.anonymous(null);
+    callbacks.sessionChanged?.(sessionToken, null, sessionGeneration);
+    notify();
+  };
+  const stop = watch(
+    [
+      () => session.value.isPending === true,
+      () => session.value.data,
+      () => session.value.error
+    ],
+    ([isPending, data, error]) => publishFromSession({ isPending, data, error }),
+    {
+      immediate: true,
+      deep: false,
+      // Identity observation is a security boundary: retire the old identity
+      // in the same turn rather than after Vue's render queue flushes.
+      flush: "sync"
+    }
+  );
+  const waitForSessionSettlement = async () => {
+    const isUnsettled = () => session.value.isPending === true || session.value.isRefetching === true;
+    if (!isUnsettled()) return;
+    await new Promise((resolve, reject) => {
+      let settled = false;
+      let stopPending = () => {
+      };
+      const finish = (error) => {
+        if (settled) return;
+        settled = true;
+        stopPending();
+        clearTimeout(timer);
+        cancelSessionSettlement.delete(cancel);
+        if (error) reject(error);
+        else resolve();
+      };
+      const cancel = () => finish(new Error(UNAVAILABLE));
+      cancelSessionSettlement.add(cancel);
+      stopPending = watch(
+        isUnsettled,
+        (unsettled) => {
+          if (!unsettled) finish();
+        },
+        { flush: "sync" }
+      );
+      const timer = setTimeout(cancel, SESSION_SETTLEMENT_TIMEOUT_MS);
+      if (disposed) cancel();
+      else if (!isUnsettled()) finish();
+    });
+  };
+  return Object.freeze({
+    snapshot: () => snapshot,
+    subscribe(listener) {
+      if (disposed) return () => {
+      };
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    async fetchToken() {
+      if (disposed || snapshot.status !== "authenticated") return null;
+      const expectedKey = snapshot.identityKey;
+      const outcome = await fetchConvexToken(source);
+      if (disposed || snapshot.status !== "authenticated" || snapshot.identityKey !== expectedKey) {
+        return null;
+      }
+      if (outcome.identity) {
+        const fetchedKey = outcome.identity.user.id;
+        if (fetchedKey !== expectedKey) {
+          cachedToken = null;
+          return null;
+        }
+        cachedToken = outcome.identity.token;
+        callbacks.authenticated(outcome.identity.token, outcome.identity.user);
+        return cachedToken;
+      }
+      if (!outcome.definitive && isTokenUsable(cachedToken)) return cachedToken;
+      cachedToken = null;
+      callbacks.anonymous(outcome.authError);
+      return null;
+    },
+    async refreshSession() {
+      if (disposed) return;
+      const refetch = session.value.refetch;
+      if (typeof refetch !== "function") throw new Error(UNAVAILABLE);
+      try {
+        await refetch();
+        await waitForSessionSettlement();
+      } catch {
+        throw new Error(UNAVAILABLE);
+      }
+      if (disposed || session.value.error) throw new Error(UNAVAILABLE);
+    },
+    failClosed(message) {
+      if (disposed) return;
+      cachedToken = null;
+      sessionGeneration += 1;
+      snapshot = {
+        status: "error",
+        identityKey: null,
+        sessionGeneration,
+        error: new Error(UNAVAILABLE)
+      };
+      observedSessionToken = null;
+      observedIdentityKey = null;
+      callbacks.anonymous(message);
+      callbacks.sessionChanged?.(null, UNAVAILABLE, sessionGeneration);
+      notify();
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      stop();
+      for (const cancel of [...cancelSessionSettlement]) cancel();
+      cancelSessionSettlement.clear();
+      listeners.clear();
+      cachedToken = null;
+      observedSessionToken = null;
+    }
+  });
+}

package/dist/runtime/auth/client-engine-types.d.ts

@@ -0,0 +1,4 @@
+import type { createAuthClient } from 'better-auth/vue';
+import type { ConvexTokenSource } from './token-fetcher.js';
+/** Better Auth client augmented with the prepended Convex token plugin. */
+export type AuthClientWithConvex = ReturnType<typeof createAuthClient> & ConvexTokenSource;

package/dist/runtime/auth/integrated-client.d.ts

@@ -0,0 +1,25 @@
+import type { IntegratedAuthClient } from '../auth-client/index.js';
+export interface SessionCheckpoint {
+    readonly revision: number;
+}
+export interface CanonicalSessionReconciler {
+    checkpoint(): SessionCheckpoint;
+    /**
+     * Finish a synchronous call. This deliberately may throw when that call
+     * changed the provider session: such a plugin operation cannot be reconciled
+     * without changing its synchronous contract.
+     */
+    cancel(checkpoint: SessionCheckpoint): void;
+    /** Re-read the canonical provider session, then await its Convex acceptance. */
+    reconcile(checkpoint: SessionCheckpoint): Promise<void>;
+}
+/**
+ * Integrates Better Auth without inventing a second action list.
+ *
+ * The apply trap is intentionally synchronous. Better Auth 1.7 exposes both
+ * synchronous APIs (`useSession()` and plugin permission checks) and
+ * Promise-returning actions through recursive callable proxies. Synchronous
+ * values pass through unchanged; only actual PromiseLike results cross the
+ * canonical session reconciliation barrier.
+ */
+export declare function createIntegratedAuthClient<Client extends object>(client: Client, reconciler: CanonicalSessionReconciler, track?: <Value>(operation: Promise<Value>) => Promise<Value>): IntegratedAuthClient<Client>;