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

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

@@ -0,0 +1,71 @@
+import type { BetterAuthClientOptions } from 'better-auth/client';
+import type { VueAuthClient } from 'better-auth/vue';
+import type { AuthClientPlugins, ConvexAuthClientDefinitionOptions } from './definition-types.js';
+export type { IntegratedAuthClient } from '../utils/integrated-auth-client.js';
+/** A frozen, framework-free description of the consumer's client (no instance). */
+export interface ConvexAuthClientDefinition<Plugins extends AuthClientPlugins> {
+    readonly options: ConvexAuthClientDefinitionOptions<Plugins>;
+}
+/**
+ * Capture the typed shape of a Convex Better Auth client without instantiating
+ * one. The `const` plugins generic preserves the tuple so plugin-method
+ * inference survives into `InferRegisteredConvexAuthClient`.
+ *
+ * @example
+ * ```ts
+ * // app/convex-auth.ts — import your plugin clients (organizationClient,
+ * // apiKeyClient) and defineConvexAuthClient, then:
+ * export default defineConvexAuthClient({
+ *   plugins: [organizationClient(), apiKeyClient()],
+ * })
+ * ```
+ */
+export declare function defineConvexAuthClient<const Plugins extends AuthClientPlugins = []>(options?: ConvexAuthClientDefinitionOptions<Plugins>): ConvexAuthClientDefinition<Plugins>;
+/**
+ * Augmentable registry . The module-generated type template (produced
+ * by `src/module.ts` via Nuxt Kit `addTypeTemplate`) adds a `definition` member
+ * whose type is `typeof` the resolved consumer definition:
+ *
+ * ```ts
+ * declare module '@lupinum/better-convex-nuxt/auth-client' {
+ *   interface ConvexAuthClientRegistry {
+ *     definition: typeof definition
+ *   }
+ * }
+ * ```
+ *
+ * Augmenting this exact module (where the interface is declared) is required:
+ * `InferRegisteredConvexAuthClient` below reads this interface, and a
+ * cross-module re-export augmentation would not merge into it. The packed
+ * auth-client typing fixture covers this boundary.
+ */
+export interface ConvexAuthClientRegistry {
+}
+/**
+ * Better Auth's `plugins` option is a MUTABLE array; a definition holds a
+ * readonly tuple, so strip `readonly` when spreading into resolved options.
+ */
+type MutablePlugins<P extends readonly unknown[]> = {
+    -readonly [I in keyof P]: P[I];
+};
+/** Extract the plugins tuple from a registered definition VALUE (never `ReturnType<typeof factory>`). */
+type PluginsOf<D> = D extends ConvexAuthClientDefinition<infer P> ? P : [];
+/**
+ * The options actually handed to `createAuthClient`: base options via `Omit`
+ * plus the module-owned `baseURL` and the consumer plugin tuple.
+ * tuple. The full `BetterAuthClientOptions` is deliberately NOT re-intersected.
+ */
+type ResolvedOptions<Plugins extends AuthClientPlugins> = Omit<BetterAuthClientOptions, 'baseURL' | 'plugins'> & {
+    baseURL: string;
+    plugins: [...MutablePlugins<Plugins>];
+};
+/** The inferred client type for the library-owned options with no consumer plugins. */
+export type BaseAuthClient = VueAuthClient<ResolvedOptions<[]>>;
+/**
+ * The registered raw Better Auth shape used to infer the integrated client.
+ * Exposes plugin methods when a definition is registered; falls back to the
+ * base Better Auth client type otherwise.
+ */
+export type InferRegisteredConvexAuthClient = ConvexAuthClientRegistry extends {
+    definition: infer D;
+} ? VueAuthClient<ResolvedOptions<PluginsOf<D>>> : BaseAuthClient;

package/dist/runtime/auth-client/index.js

@@ -0,0 +1,3 @@
+export function defineConvexAuthClient(options = {}) {
+  return Object.freeze({ options: Object.freeze(options) });
+}

package/dist/runtime/cli/auth-schema.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/runtime/cli/auth-schema.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+import { constants } from "node:fs";
+import { access, mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, join, resolve } from "node:path";
+import { getAuthTables } from "better-auth/db";
+import { createJiti } from "jiti";
+import { generateAuthSchemaArtifacts } from "../convex-auth/adapter/generate-schema.js";
+const SCHEMA_BASE_URL = "https://schema.invalid";
+const SCHEMA_SECRET = "schema-generation-only-value-never-used-at-runtime";
+const CLEARED_ENVIRONMENT = [
+  "SITE_URL",
+  "CONVEX_SITE_URL",
+  "AUTH_SECRET",
+  "BETTER_AUTH_SECRET",
+  "BETTER_AUTH_SECRETS",
+  "BCN_AUTH_PROXY_IP_SECRET"
+];
+function usage() {
+  return [
+    "Generate a paired Better Convex Nuxt local auth schema and metadata descriptor.",
+    "",
+    "Usage:",
+    "  better-convex-nuxt-auth-schema --config <schema-options.ts> [--output <directory>] [--check]",
+    "",
+    "The config must default-export environment-independent BetterAuthOptions using:",
+    `  baseURL: ${SCHEMA_BASE_URL}`,
+    `  secret: ${SCHEMA_SECRET}`,
+    "",
+    "The config is loaded as TypeScript and may import local schema plugin modules."
+  ].join("\n");
+}
+function valueAfter(args, index, flag) {
+  const value = args[index + 1];
+  if (!value || value.startsWith("--")) throw new Error(`${flag} requires a value.`);
+  return value;
+}
+function parseArgs(args) {
+  const options = { check: false, help: false };
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    switch (argument) {
+      case "--check":
+        options.check = true;
+        break;
+      case "--config":
+        if (options.config) throw new Error("--config may be provided only once.");
+        options.config = valueAfter(args, index, "--config");
+        index += 1;
+        break;
+      case "--help":
+      case "-h":
+        options.help = true;
+        break;
+      case "--output":
+        if (options.output) throw new Error("--output may be provided only once.");
+        options.output = valueAfter(args, index, "--output");
+        index += 1;
+        break;
+      default:
+        throw new Error(`Unknown argument: ${argument}`);
+    }
+  }
+  return options;
+}
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function requireSchemaOptions(value) {
+  if (!isRecord(value)) throw new Error("Schema config must default-export BetterAuthOptions.");
+  if (value.baseURL !== SCHEMA_BASE_URL || value.secret !== SCHEMA_SECRET) {
+    throw new Error(
+      "Schema config must use the reserved environment-independent baseURL and secret."
+    );
+  }
+  return value;
+}
+async function readIfPresent(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (isRecord(error) && error.code === "ENOENT") return void 0;
+    throw error;
+  }
+}
+function resolveSchemaTarget(configPath, output) {
+  const resolvedOutput = output ? resolve(output) : dirname(configPath);
+  const target = output && extname(resolvedOutput) ? resolvedOutput : join(resolvedOutput, "schema.ts");
+  if (basename(target) !== "schema.ts" || basename(dirname(target)) === "convex") {
+    throw new Error("Output must be a local component schema.ts, not the application schema.");
+  }
+  return target;
+}
+async function writePair(outputs) {
+  const temporaryFiles = /* @__PURE__ */ new Map();
+  const sequence = `${process.pid}.${Date.now()}`;
+  try {
+    for (const [target, contents] of outputs) {
+      await mkdir(dirname(target), { recursive: true });
+      const temporary = join(dirname(target), `.${basename(target)}.${sequence}.tmp`);
+      await writeFile(temporary, contents, { encoding: "utf8", flag: "wx", mode: 420 });
+      temporaryFiles.set(target, temporary);
+    }
+    const orderedTargets = [...outputs.keys()].sort(
+      (left, right) => left.endsWith("schemaMetadata.ts") ? -1 : right.endsWith("schemaMetadata.ts") ? 1 : 0
+    );
+    for (const target of orderedTargets) {
+      const temporary = temporaryFiles.get(target);
+      if (!temporary) throw new Error("Unable to stage generated auth artifacts.");
+      await rename(temporary, target);
+      temporaryFiles.delete(target);
+    }
+  } finally {
+    await Promise.all([...temporaryFiles.values()].map((path) => rm(path, { force: true })));
+  }
+}
+async function generate(options) {
+  if (!options.config) throw new Error("--config is required.");
+  const configPath = await realpath(resolve(options.config));
+  await access(configPath, constants.R_OK);
+  for (const name of CLEARED_ENVIRONMENT) Reflect.deleteProperty(process.env, name);
+  let configModule;
+  try {
+    const jiti = createJiti(import.meta.url, { interopDefault: false });
+    configModule = await jiti.import(configPath);
+  } catch (error) {
+    if (isRecord(error) && error.code === "ERR_MODULE_NOT_FOUND") {
+      throw new Error("Unable to import schema config or one of its dependencies.");
+    }
+    throw error;
+  }
+  const schemaOptions = requireSchemaOptions(configModule.default);
+  const artifacts = generateAuthSchemaArtifacts(getAuthTables(schemaOptions));
+  const schemaTarget = resolveSchemaTarget(configPath, options.output);
+  const outputs = /* @__PURE__ */ new Map([
+    [schemaTarget, artifacts.schemaCode],
+    [join(dirname(schemaTarget), "schemaMetadata.ts"), artifacts.metadataCode]
+  ]);
+  if (options.check) {
+    const stale = [];
+    for (const [target, contents] of outputs) {
+      if (await readIfPresent(target) !== contents) stale.push(target);
+    }
+    if (stale.length > 0) {
+      for (const target of stale) console.error(`stale: ${target}`);
+      return 1;
+    }
+    console.log("Auth schema and metadata are current.");
+    return 0;
+  }
+  await writePair(outputs);
+  for (const target of outputs.keys()) console.log(`generated: ${target}`);
+  return 0;
+}
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.help) {
+    console.log(usage());
+    return 0;
+  }
+  return await generate(options);
+}
+try {
+  process.exitCode = await main();
+} catch (error) {
+  console.error(
+    `[better-convex-nuxt-auth-schema] ${error instanceof Error ? error.message : "failed"}`
+  );
+  process.exitCode = 1;
+}

package/dist/runtime/cli/convex.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+type ConvexAuthorityKind = 'deployment-key' | 'deployment-name' | 'self-hosted';
+/** Validate that the fixed file contains one, and only one, deployment selector class. */
+export declare function assertConvexAuthoritySelection(environment: Readonly<Record<string, string>>): ConvexAuthorityKind;
+/** Build a child environment whose only Convex authority comes from the fixed file. */
+export declare function buildConvexCommandEnvironment(inherited: Readonly<Record<string, string | undefined>>, authorityFile: Readonly<Record<string, string>>): Record<string, string>;
+export declare function runConvexCommand(arguments_: readonly string[], options?: {
+    cwd?: string;
+    inheritedEnvironment?: NodeJS.ProcessEnv;
+}): Promise<number>;
+export {};

package/dist/runtime/cli/convex.js

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { stat, readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseEnv } from "node:util";
+const AUTHORITY_ENV_FILE = ".env.local";
+const LOCAL_BACKEND_STARTUP_TIMEOUT = "CONVEX_LOCAL_BACKEND_STARTUP_TIMEOUT_SECS";
+const MAX_ENV_FILE_BYTES = 64 * 1024;
+const TOKEN_SELECTORS = ["CONVEX_DEPLOY_KEY", "CONVEX_DEPLOYMENT_TOKEN"];
+const SELF_HOSTED_SELECTORS = ["CONVEX_SELF_HOSTED_URL", "CONVEX_SELF_HOSTED_ADMIN_KEY"];
+const ALLOWED_CONVEX_FILE_NAMES = /* @__PURE__ */ new Set([
+  ...TOKEN_SELECTORS,
+  ...SELF_HOSTED_SELECTORS,
+  "CONVEX_DEPLOYMENT",
+  "CONVEX_SITE_URL",
+  "CONVEX_URL"
+]);
+const DEPLOYMENT_SELECTORS = /* @__PURE__ */ new Set([
+  ...TOKEN_SELECTORS,
+  ...SELF_HOSTED_SELECTORS,
+  "CONVEX_DEPLOYMENT"
+]);
+const PINNED_CONVEX_AUTHORITY_NAMES = [
+  ...TOKEN_SELECTORS,
+  ...SELF_HOSTED_SELECTORS,
+  "CONVEX_AGENT_MODE",
+  "CONVEX_ALLOW_ANONYMOUS",
+  "CONVEX_DEPLOYMENT",
+  "CONVEX_IMPORT_CHUNK_SIZE",
+  "CONVEX_MIN_DOCUMENTS_FOR_INDEX_DELETE_WARNING",
+  "CONVEX_OVERRIDE_ACCESS_TOKEN",
+  "CONVEX_PROVISION_HOST",
+  "CONVEX_RUNNING_LIVE_IN_MONOREPO",
+  "CONVEX_SITE_URL",
+  "CONVEX_URL",
+  "CONVEX_VERBOSE",
+  "CONVEX_VERSION_API_ORIGIN",
+  "CONVEX_VERSION_OVERRIDE"
+];
+const FORBIDDEN_FILE_BOUND_ARGUMENTS = [
+  "--admin-key",
+  "--anonymous",
+  "--cloud",
+  "--configure",
+  "--deployment",
+  "--deployment-name",
+  "--dev-deployment",
+  "--env-file",
+  "--local",
+  "--local-backend-version",
+  "--local-dashboard-version",
+  "--local-force-upgrade",
+  "--override-auth-client",
+  "--override-auth-password",
+  "--override-auth-url",
+  "--override-auth-username",
+  "--preview-create",
+  "--preview-name",
+  "--prod",
+  "--project",
+  "--team",
+  "--type",
+  "--url"
+];
+const FILE_BOUND_COMMANDS = /* @__PURE__ */ new Set(["codegen", "deploy", "dev", "env", "run"]);
+const DEPLOYMENT_KEY = /^(?:dev|prod):[^:|\s]+\|\S+$/u;
+const DEPLOYMENT_NAME = /^(?:custom|dev|local|preview|prod):[a-z0-9_-]+$/u;
+function hasValue(environment, name) {
+  return typeof environment[name] === "string" && environment[name].length > 0;
+}
+function isAnonymousDeployment(value) {
+  const prefix = "anonymous:anonymous-";
+  if (!value.startsWith(prefix) || value.length === prefix.length) return false;
+  for (const character of value.slice(prefix.length)) {
+    const code = character.charCodeAt(0);
+    if (character === "/" || character === "\\" || character === ":" || code <= 31 || code === 127) {
+      return false;
+    }
+  }
+  return true;
+}
+export function assertConvexAuthoritySelection(environment) {
+  if (Object.keys(environment).some(
+    (name) => name.toUpperCase().startsWith("CONVEX_") && !ALLOWED_CONVEX_FILE_NAMES.has(name)
+  )) {
+    throw new Error("The Convex authority file contains an unsupported Convex setting.");
+  }
+  const tokens = TOKEN_SELECTORS.filter((name) => hasValue(environment, name));
+  const hasDeployment = hasValue(environment, "CONVEX_DEPLOYMENT");
+  const selfHosted = SELF_HOSTED_SELECTORS.filter((name) => hasValue(environment, name));
+  if (tokens.length > 1 || selfHosted.length === 1) {
+    throw new Error("The Convex authority file contains conflicting or incomplete selectors.");
+  }
+  if (tokens.length === 1 && !DEPLOYMENT_KEY.test(environment[tokens[0]])) {
+    throw new Error("The Convex authority file must use a deployment-scoped key.");
+  }
+  if (hasDeployment && !DEPLOYMENT_NAME.test(environment.CONVEX_DEPLOYMENT) && !isAnonymousDeployment(environment.CONVEX_DEPLOYMENT)) {
+    throw new Error("The Convex authority file contains an invalid deployment selector.");
+  }
+  const selectorClasses = Number(tokens.length === 1) + Number(hasDeployment) + Number(selfHosted.length === 2);
+  if (selectorClasses !== 1) {
+    throw new Error("The Convex authority file must contain exactly one deployment selector.");
+  }
+  if (tokens.length === 1) return "deployment-key";
+  return hasDeployment ? "deployment-name" : "self-hosted";
+}
+export function buildConvexCommandEnvironment(inherited, authorityFile) {
+  assertConvexAuthoritySelection(authorityFile);
+  const environment = buildClearedConvexEnvironment(inherited);
+  for (const [name, value] of Object.entries(authorityFile)) {
+    if (DEPLOYMENT_SELECTORS.has(name)) environment[name] = value;
+  }
+  if (authorityFile.CONVEX_DEPLOYMENT?.startsWith("anonymous:anonymous-")) {
+    environment.CONVEX_AGENT_MODE = "anonymous";
+    environment.CONVEX_ALLOW_ANONYMOUS = "true";
+  }
+  return environment;
+}
+function buildClearedConvexEnvironment(inherited) {
+  const localBackendStartupTimeout = inherited[LOCAL_BACKEND_STARTUP_TIMEOUT];
+  if (localBackendStartupTimeout) {
+    const seconds = Number(localBackendStartupTimeout);
+    if (!Number.isFinite(seconds) || seconds <= 0) {
+      throw new Error("The local Convex backend startup timeout must be a positive number.");
+    }
+  }
+  const environment = Object.fromEntries(
+    Object.entries(inherited).filter(
+      (entry) => entry[1] !== void 0 && !entry[0].toUpperCase().startsWith("CONVEX_")
+    )
+  );
+  for (const name of PINNED_CONVEX_AUTHORITY_NAMES) environment[name] = "";
+  if (localBackendStartupTimeout) {
+    environment[LOCAL_BACKEND_STARTUP_TIMEOUT] = localBackendStartupTimeout;
+  }
+  return environment;
+}
+function assertFileBoundArguments(arguments_) {
+  for (const argument of arguments_) {
+    if (FORBIDDEN_FILE_BOUND_ARGUMENTS.some(
+      (name) => argument === name || argument.startsWith(`${name}=`)
+    )) {
+      throw new Error("Deployment overrides are not supported by this runner.");
+    }
+  }
+}
+async function readAuthorityFile(cwd) {
+  const path = resolve(cwd, AUTHORITY_ENV_FILE);
+  try {
+    const file = await stat(path);
+    if (!file.isFile() || file.size > MAX_ENV_FILE_BYTES) throw new Error("invalid");
+    const source = await readFile(path, "utf8");
+    if (source.replaceAll("\r\n", "").includes("\r")) throw new Error("invalid");
+    const convexAssignments = /* @__PURE__ */ new Set();
+    for (const line of source.split(/\r?\n/u)) {
+      const assignment = /^\s*(?:export\s+)?([A-Za-z_]\w*)\s*([=:])/u.exec(line);
+      const name = assignment?.[1];
+      const separator = assignment?.[2];
+      if (name?.toUpperCase().startsWith("CONVEX_")) {
+        if (name !== name.toUpperCase() || separator !== "=" || convexAssignments.has(name)) {
+          throw new Error("invalid");
+        }
+        convexAssignments.add(name);
+      }
+    }
+    const parsed = parseEnv(source);
+    const environment = {};
+    for (const [name, value] of Object.entries(parsed)) {
+      if (value === void 0) throw new Error("invalid");
+      environment[name] = value;
+    }
+    return environment;
+  } catch {
+    throw new Error("The Convex authority file is missing, invalid, or too large.");
+  }
+}
+function usage() {
+  return [
+    "Run the pinned Convex CLI with one explicit deployment authority.",
+    "",
+    "Usage:",
+    "  better-convex-nuxt-convex configure",
+    "  better-convex-nuxt-convex dev --anonymous [options]",
+    "  better-convex-nuxt-convex <codegen|deploy|dev|env|run> [options]",
+    "  better-convex-nuxt-convex deployment select <selector>",
+    "",
+    "File-bound commands use only .env.local. Configure, anonymous dev, and",
+    "deployment select clear inherited and dotenv authority before Convex runs."
+  ].join("\n");
+}
+export async function runConvexCommand(arguments_, options = {}) {
+  const cwd = resolve(options.cwd ?? process.cwd());
+  const inherited = options.inheritedEnvironment ?? process.env;
+  const [command, ...commandArguments] = arguments_;
+  let convexArguments;
+  let environment;
+  if (command === "configure") {
+    if (commandArguments.length > 0) throw new Error("Configure does not accept extra arguments.");
+    convexArguments = ["dev", "--configure"];
+    environment = buildClearedConvexEnvironment(inherited);
+  } else if (command === "deployment" && commandArguments[0] === "select") {
+    if (commandArguments.length !== 2 || !commandArguments[1] || commandArguments[1].startsWith("-")) {
+      throw new Error("Deployment select requires an explicit selector.");
+    }
+    convexArguments = [command, ...commandArguments];
+    environment = buildClearedConvexEnvironment(inherited);
+  } else if (command === "dev" && commandArguments.includes("--anonymous")) {
+    if (commandArguments.filter((argument) => argument === "--anonymous").length !== 1) {
+      throw new Error("Anonymous development accepts exactly one --anonymous flag.");
+    }
+    const forwardedArguments = commandArguments.filter((argument) => argument !== "--anonymous");
+    assertFileBoundArguments(forwardedArguments);
+    convexArguments = [command, ...forwardedArguments];
+    environment = buildClearedConvexEnvironment(inherited);
+    environment.CONVEX_AGENT_MODE = "anonymous";
+    environment.CONVEX_ALLOW_ANONYMOUS = "true";
+  } else if (command && FILE_BOUND_COMMANDS.has(command)) {
+    assertFileBoundArguments(commandArguments);
+    const authorityFile = await readAuthorityFile(cwd);
+    const authorityKind = assertConvexAuthoritySelection(authorityFile);
+    const deploymentKey = TOKEN_SELECTORS.map((name) => authorityFile[name]).find(Boolean);
+    if (command === "deploy" && authorityKind === "deployment-name") {
+      throw new Error("Deploy requires a deployment-scoped key or self-hosted authority.");
+    }
+    if (command === "deploy" && deploymentKey && !deploymentKey.startsWith("prod:")) {
+      throw new Error("Deploy requires a production deployment key or self-hosted authority.");
+    }
+    if (command === "dev" && authorityKind === "deployment-name" && !/^(?:anonymous:anonymous-|dev:|local:)/u.test(authorityFile.CONVEX_DEPLOYMENT)) {
+      throw new Error("Dev requires a dev, local, anonymous, or development-key authority.");
+    }
+    if (command === "dev" && deploymentKey && !deploymentKey.startsWith("dev:")) {
+      throw new Error("Dev requires a development deployment key or local authority.");
+    }
+    environment = buildConvexCommandEnvironment(inherited, authorityFile);
+    convexArguments = [command, ...commandArguments];
+  } else {
+    throw new Error("Unsupported Convex command.");
+  }
+  const convexCli = resolve(cwd, "node_modules/convex/bin/main.js");
+  const result = spawnSync(process.execPath, ["--", convexCli, ...convexArguments], {
+    cwd,
+    env: environment,
+    stdio: "inherit"
+  });
+  if (result.error || result.status === null) {
+    throw new Error("The Convex CLI could not be started or did not exit normally.");
+  }
+  return result.status;
+}
+let invokedAsScript = false;
+if (process.argv[1]) {
+  try {
+    invokedAsScript = realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+  }
+}
+if (invokedAsScript) {
+  try {
+    const arguments_ = process.argv.slice(2);
+    if (arguments_.length === 1 && (arguments_[0] === "--help" || arguments_[0] === "-h")) {
+      console.log(usage());
+      process.exitCode = 0;
+    } else {
+      process.exitCode = await runConvexCommand(arguments_);
+    }
+  } catch (error) {
+    console.error(
+      `[better-convex-nuxt-convex] ${error instanceof Error ? error.message : "failed"}`
+    );
+    process.exitCode = 1;
+  }
+}

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

@@ -0,0 +1,4 @@
+import { type ConvexClientHandle } from '@lupinum/better-convex-vue';
+export type { ConvexClientHandle } from '@lupinum/better-convex-vue';
+/** Access the Vue-owned stable, replacement-safe Convex client handle. */
+export declare function useConvex(): ConvexClientHandle;

package/dist/runtime/composables/useConvex.js

@@ -0,0 +1,9 @@
+import { useConvex as useVueConvex } from "@lupinum/better-convex-vue";
+export function useConvex() {
+  if (import.meta.server) {
+    throw new Error(
+      "[useConvex] Convex client handle is unavailable. This composable is client-only and requires a configured Convex URL."
+    );
+  }
+  return useVueConvex();
+}

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

@@ -0,0 +1,4 @@
+import { type UseConvexCall } from '@lupinum/better-convex-vue';
+import type { FunctionReference } from 'convex/server';
+/** Nuxt auto-import facade over the one shared Vue callable lifecycle. */
+export declare function useConvexAction<Action extends FunctionReference<'action'>>(action: Action): UseConvexCall<Action>;

package/dist/runtime/composables/useConvexAction.js

@@ -0,0 +1,18 @@
+import {
+  useConvexAction as useVueConvexAction
+} from "@lupinum/better-convex-vue";
+import { getFunctionName } from "convex/server";
+import { useNuxtApp } from "#imports";
+import { readConvexRuntimeContext } from "../runtime-context.js";
+import { createCallableDevtoolsEvents } from "../utils/callable-devtools.js";
+import { CALLABLE_OBSERVER_KEY } from "../utils/callable-observer.js";
+export function useConvexAction(action) {
+  const runtime = readConvexRuntimeContext(useNuxtApp());
+  const events = createCallableDevtoolsEvents({
+    operation: "action",
+    fnName: getFunctionName(action),
+    hasOptimisticUpdate: false,
+    getSink: () => runtime?.getDevtoolsSink() ?? null
+  });
+  return useVueConvexAction(action, { [CALLABLE_OBSERVER_KEY]: events });
+}

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

@@ -0,0 +1,9 @@
+import type { BetterConvexAttachment } from '@lupinum/better-convex-vue/embedded';
+/**
+ * Read the frozen, token-free Vue runtime attachment owned by this Nuxt app.
+ *
+ * Pass this object to a separately bundled Vue application using
+ * `createBetterConvex({ attachment })`. It intentionally excludes the
+ * broader internal Nuxt runtime context and every credential/provider control.
+ */
+export declare function useConvexAttachment(): BetterConvexAttachment;

package/dist/runtime/composables/useConvexAttachment.js

@@ -0,0 +1,14 @@
+import { useNuxtApp } from "#app";
+import { readConvexRuntimeContext } from "../runtime-context.js";
+export function useConvexAttachment() {
+  if (import.meta.server) {
+    throw new Error("[useConvexAttachment] Runtime attachment is available only in the browser.");
+  }
+  const attachment = readConvexRuntimeContext(useNuxtApp())?.attachment;
+  if (!attachment) {
+    throw new Error(
+      "[useConvexAttachment] Convex browser runtime is unavailable. Configure a Convex URL before attaching an embedded application."
+    );
+  }
+  return attachment;
+}

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

@@ -0,0 +1,10 @@
+import type { InferRegisteredConvexAuthClient } from '../auth-client/index.js';
+import type { UseConvexAuthReturn } from '../utils/auth-contract.js';
+export type { UseConvexAuthReturn } from '../utils/auth-contract.js';
+/**
+ * Access Convex authentication state and the inferred integrated Better Auth
+ * client. The client is browser-owned, so it is `null` during SSR/early setup.
+ * Synchronous Better Auth methods stay synchronous; PromiseLike operations do
+ * not settle until their canonical provider session is accepted by Convex.
+ */
+export declare function useConvexAuth(): UseConvexAuthReturn<InferRegisteredConvexAuthClient>;

package/dist/runtime/composables/useConvexAuth.js

@@ -0,0 +1,37 @@
+import { computed, readonly, useNuxtApp, useState } from "#imports";
+import { identityKeyOf, identityUser } from "../auth/auth-identity.js";
+import { ConvexCallError } from "../errors/index.js";
+import { readConvexRuntimeContext } from "../runtime-context.js";
+import { useConvexIdentityState } from "../utils/auth-identity-state.js";
+import { deriveConvexAuthStatus } from "../utils/auth-status.js";
+export function useConvexAuth() {
+  const nuxtApp = useNuxtApp();
+  const identity = useConvexIdentityState();
+  const user = computed(() => identityUser(identity.value));
+  const authError = useState("convex:authError", () => null);
+  const pending = useState("convex:pending", () => import.meta.client);
+  const coordinator = readConvexRuntimeContext(nuxtApp)?.getAuthController() ?? void 0;
+  const status = computed(
+    () => deriveConvexAuthStatus({
+      authEnabled: true,
+      settled: !pending.value,
+      identityKey: identityKeyOf(identity.value),
+      error: authError.value ? new ConvexCallError({ kind: "authentication", message: authError.value }) : null
+    })
+  );
+  const isPending = coordinator ? coordinator.isPending : computed(() => pending.value);
+  const error = computed(
+    () => authError.value ? new ConvexCallError({ kind: "authentication", message: authError.value }) : void 0
+  );
+  return {
+    status,
+    isPending,
+    user: readonly(user),
+    error,
+    client: coordinator?.client ?? null,
+    ready: async (options) => {
+      if (!coordinator) return status.value;
+      return coordinator.ready(options);
+    }
+  };
+}

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

@@ -0,0 +1,12 @@
+import { type ConvexRuntimeConfig } from '../utils/runtime-config.js';
+export type { ConvexRuntimeConfig } from '../utils/runtime-config.js';
+/**
+ * Read the resolved Convex connection origins.
+ *
+ * @example
+ * ```ts
+ * const config = useConvexConfig()
+ * console.log(config.url, config.siteUrl)
+ * ```
+ */
+export declare function useConvexConfig(): ConvexRuntimeConfig;