nuxt-convex-module 0.0.0 → 0.9.0

package/dist/runtime/vue/client.d.ts

@@ -1,24 +1,19 @@
 import type { InjectionKey } from 'vue';
-import { BaseConvexClient } from 'convex/browser';
 import type { AuthTokenFetcher, BaseConvexClientOptions, ConnectionState, OptimisticUpdate, PaginationStatus, QueryJournal, QueryOptions } from 'convex/browser';
 import type { Watch as ConvexWatch } from 'convex/react';
-import type { ArgsAndOptions, FunctionArgs, FunctionReference, FunctionReturnType, OptionalRestArgs, UserIdentityAttributes } from 'convex/server';
+import type { ArgsAndOptions, FunctionArgs, FunctionReference, FunctionReturnType, OptionalRestArgs } from 'convex/server';
 import type { Value } from 'convex/values';
 export type { AuthTokenFetcher, ConnectionState, OptimisticUpdate };
 /**
  * A watch on the output of a Convex query function.
  *
  * Derived from upstream's `Watch` (per-member docs live there), extended with
- * the `@internal` `localQueryLogs`, which is stripped from the published
+ * the internal `localQueryLogs`, which is stripped from the published
  * `convex/react` types but present at runtime.
  *
  * @public
  */
 export interface Watch<T> extends ConvexWatch<T> {
-    /**
-     * @internal
-     */
-    localQueryLogs(): string[] | undefined;
 }
 /**
  * A watch on the output of a paginated Convex query function.
@@ -61,10 +56,6 @@ export interface WatchQueryOptions {
      * name and arguments, this journal will have no effect.
      */
     journal?: QueryJournal;
-    /**
-     * @internal
-     */
-    componentPath?: string;
 }
 /**
  * Options for {@link ConvexVueClient.mutation}.
@@ -101,7 +92,7 @@ export type ConvexLogger = Exclude<BaseConvexClientOptions['logger'], boolean |
  * This loads reactive queries and executes mutations over a WebSocket.
  *
  * In a Nuxt app the client is provided automatically by the plugin and
- * available via the {@link useConvex} composable or `useNuxtApp().$convex`.
+ * available via the {@link useConvex} composable.
  *
  * @public
  */
@@ -127,13 +118,6 @@ export declare class ConvexVueClient {
      * it may be canonicalized.
      */
     get url(): string;
-    /**
-     * Lazily instantiate the `BaseConvexClient` so we don't create the WebSocket
-     * when server-side rendering.
-     *
-     * @internal
-     */
-    get sync(): BaseConvexClient;
     /**
      * Set the authentication token to be used for subsequent queries and mutations.
      * `fetchToken` will be called automatically again if a token expires.
@@ -148,10 +132,6 @@ export declare class ConvexVueClient {
      * Clear the current authentication token if set.
      */
     clearAuth(): void;
-    /**
-     * @internal
-     */
-    setAdminAuth(token: string, identity?: UserIdentityAttributes): void;
     /**
      * Construct a new {@link Watch} on a Convex query function.
      *
@@ -183,30 +163,6 @@ export declare class ConvexVueClient {
     prewarmQuery<Query extends FunctionReference<'query'>>(queryOptions: QueryOptions<Query> & {
         extendSubscriptionFor?: number;
     }): void;
-    /**
-     * Construct a new {@link PaginatedWatch} on a Convex paginated query function.
-     *
-     * **Not supported in the Vue port — use the {@link usePaginatedQuery}
-     * composable instead.** Convex's paginated-subscription engine
-     * (`PaginatedQueryClient`) is not part of the public `convex` exports, so a
-     * third-party package cannot instantiate it; pagination is handled entirely
-     * in the composable layer via ordinary {@link watchQuery} subscriptions.
-     *
-     * The method is retained for structural parity with
-     * `ConvexReactClient.watchPaginatedQuery`. It is reachable only if a caller
-     * passes `paginationOptions` to {@link useConvexQueries} (the React-shaped
-     * escape hatch); doing so throws this error to fail loudly rather than
-     * silently mis-subscribe.
-     *
-     * Upstream wires {@link usePaginatedQuery_experimental} to this method's
-     * `PaginatedQueryClient`; the port re-bases that hook on the same manual
-     * page-management engine as {@link usePaginatedQuery}, so both hooks work
-     * without ever calling this method (only the experimental single-request
-     * network path is not reproduced).
-     *
-     * @internal
-     */
-    watchPaginatedQuery<Query extends FunctionReference<'query'>>(_query: Query, _args: Query['_args'], _options: unknown): PaginatedWatch<FunctionReturnType<Query>>;
     /**
      * Execute a mutation function.
      *
@@ -246,6 +202,7 @@ export declare class ConvexVueClient {
      * deployment.
      *
      * @returns The {@link ConnectionState} with the Convex deployment.
+     * @experimental May change in a minor release — see STABILITY.md.
      */
     connectionState(): ConnectionState;
     /**
@@ -259,6 +216,7 @@ export declare class ConvexVueClient {
      * out what information is most useful. As such this API is considered unstable.
      *
      * @returns An unsubscribe function to stop listening.
+     * @experimental May change in a minor release — see STABILITY.md.
      */
     subscribeToConnectionState(cb: (connectionState: ConnectionState) => void): () => void;
     /**
@@ -295,11 +253,3 @@ export declare const ConvexClientKey: InjectionKey<ConvexVueClient>;
  * @public
  */
 export declare function useConvex(): ConvexVueClient;
-/**
- * Inject the Convex client for a composable, throwing the per-composable
- * missing-client error when absent — mirrors the checks at the top of
- * upstream's `useQuery`/`useMutation`/`useAction`/`useConvexConnectionState`.
- *
- * @internal
- */
-export declare function useConvexOrThrow(composableName: string): ConvexVueClient;

package/dist/runtime/vue/client.js

@@ -243,6 +243,8 @@ export class ConvexVueClient {
    * without ever calling this method (only the experimental single-request
    * network path is not reproduced).
    *
+   * PARITY: D-05
+   *
    * @internal
    */
   watchPaginatedQuery(_query, _args, _options) {
@@ -312,6 +314,7 @@ export class ConvexVueClient {
    * deployment.
    *
    * @returns The {@link ConnectionState} with the Convex deployment.
+   * @experimental May change in a minor release — see STABILITY.md.
    */
   connectionState() {
     return this.sync.connectionState();
@@ -327,6 +330,7 @@ export class ConvexVueClient {
    * out what information is most useful. As such this API is considered unstable.
    *
    * @returns An unsubscribe function to stop listening.
+   * @experimental May change in a minor release — see STABILITY.md.
    */
   subscribeToConnectionState(cb) {
     return this.sync.subscribeToConnectionState(cb);

package/dist/runtime/vue/components/convex-image.d.ts

@@ -0,0 +1,50 @@
+import { type PropType } from 'vue';
+import { type GetStorageUrl } from '../composables/use-storage-url.js';
+import type { StorageId } from '../composables/use-upload.js';
+/**
+ * An `<img>` for a file in Convex storage. Resolves the served URL through
+ * {@link useStorageUrl} and renders the image once it is known; every other
+ * attribute (`alt`, `class`, `loading`, `width`, …) goes onto the `<img>`.
+ *
+ * - default slot — rendered while the URL is loading or `storageId` is empty
+ * - `missing` slot — rendered when the file no longer exists (the query returned `null`)
+ *
+ * @example
+ * ```vue
+ * <ConvexImage :get-url="api.files.url" :storage-id="doc.imageId" alt="Cover" class="rounded">
+ *   <div class="skeleton" />
+ *   <template #missing><div class="placeholder" /></template>
+ * </ConvexImage>
+ * ```
+ *
+ * @public
+ */
+export declare const ConvexImage: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    /** The public `getUrl` query: `{ storageId }` → served URL or `null`. Read once, at setup. */
+    getUrl: {
+        type: PropType<GetStorageUrl>;
+        required: true;
+    };
+    /** The file to show; `null`/`undefined` renders the default slot. */
+    storageId: {
+        type: PropType<StorageId | string | null | undefined>;
+        default: undefined;
+    };
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}> | import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>[] | null, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    /** The public `getUrl` query: `{ storageId }` → served URL or `null`. Read once, at setup. */
+    getUrl: {
+        type: PropType<GetStorageUrl>;
+        required: true;
+    };
+    /** The file to show; `null`/`undefined` renders the default slot. */
+    storageId: {
+        type: PropType<StorageId | string | null | undefined>;
+        default: undefined;
+    };
+}>> & Readonly<{}>, {
+    storageId: string | StorageId | null | undefined;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;

package/dist/runtime/vue/components/convex-image.js

@@ -0,0 +1,21 @@
+import { defineComponent, h } from "vue";
+import { useStorageUrl } from "../composables/use-storage-url.js";
+export const ConvexImage = defineComponent({
+  name: "ConvexImage",
+  inheritAttrs: false,
+  props: {
+    /** The public `getUrl` query: `{ storageId }` → served URL or `null`. Read once, at setup. */
+    getUrl: { type: Object, required: true },
+    /** The file to show; `null`/`undefined` renders the default slot. */
+    storageId: { type: String, default: void 0 }
+  },
+  setup(props, { attrs, slots }) {
+    const url = useStorageUrl(props.getUrl, () => props.storageId);
+    return () => {
+      const value = url.value;
+      if (value) return h("img", { ...attrs, src: value });
+      if (value === null) return slots.missing?.() ?? null;
+      return slots.default?.() ?? null;
+    };
+  }
+});

package/dist/runtime/vue/composables/use-connection-state.d.ts

@@ -26,5 +26,6 @@ import type { ShallowRef } from 'vue';
  * @returns The current {@link ConnectionState} with the Convex deployment.
  *
  * @public
+ * @experimental May change in a minor release — see STABILITY.md.
  */
 export declare function useConvexConnectionState(): ShallowRef<ConnectionState>;

package/dist/runtime/vue/composables/use-paginated-query.d.ts

@@ -32,7 +32,10 @@ export type { PaginatedQueryReference, PaginatedQueryArgs, PaginatedQueryItem, U
 export declare function usePaginatedQuery<Query extends PaginatedQueryReference>(query: Query, args: MaybeRefOrGetter<PaginatedQueryArgs<Query> | 'skip'>, options: {
     initialNumItems: number;
 }): UsePaginatedQueryReturnType<Query>;
-/** @internal */
+/**
+ * Reset pagination id for tests only, so tests know what it is.
+ * @experimental May change in a minor release — see STABILITY.md.
+ */
 export declare function resetPaginationId(): void;
 /**
  * Return shape of {@link usePaginatedQuery} — the fields of upstream's
@@ -125,6 +128,7 @@ export declare function insertAtPosition<Query extends PaginatedQueryReference>(
  * identical observable results (`results`/`data`, `status`, `loadMore`).
  *
  * @public
+ * @experimental May change in a minor release — see STABILITY.md.
  */
 export declare function usePaginatedQuery_experimental<Query extends PaginatedQueryReference>(query: Query, args: MaybeRefOrGetter<PaginatedQueryArgs<Query> | 'skip'>, options: {
     initialNumItems: number;

package/dist/runtime/vue/composables/use-paginated-query.js

@@ -1,7 +1,7 @@
 import { getFunctionName } from "convex/server";
 import { ConvexError, compareValues, convexToJson } from "convex/values";
 import { computed, shallowRef, toValue } from "vue";
-import { useConvex } from "../client.js";
+import { useConvexOrThrow } from "../client.js";
 import { useConvexQueries } from "./use-queries.js";
 const splitQuery = (key, splitCursor, continueCursor) => (prevState) => {
   const queries = { ...prevState.queries };
@@ -98,7 +98,7 @@ function usePaginatedQueryInternal(query, args, options) {
       `\`options.initialNumItems\` must be a positive number. Received \`${initialOptions?.initialNumItems}\`.`
     );
   }
-  const convex = useConvex();
+  const convex = useConvexOrThrow("usePaginatedQuery");
   const logger = convex.logger;
   function createInitialState(q, currentArgs, skip, initialNumItems) {
     const id = nextPaginationId();

package/dist/runtime/vue/composables/use-query.d.ts

@@ -6,6 +6,7 @@ export type OptionalRestArgsOrSkip<FuncRef extends FunctionReference<any>> = Fun
  * Result returned by object-form {@link useQuery_experimental}.
  *
  * @public
+ * @experimental May change in a minor release — see STABILITY.md.
  */
 export type UseQueryResult<QueryResult, ThrowOnError extends boolean = false> = ConvexUseQueryResult<QueryResult, ThrowOnError>;
 type UseQueryOptions<Query extends FunctionReference<'query'>, ThrowOnError extends boolean> = {
@@ -80,6 +81,7 @@ export declare function useQuery<Query extends FunctionReference<'query'>>(query
  * {@link UseQueryResult} object.
  *
  * @public
+ * @experimental May change in a minor release — see STABILITY.md.
  */
 export declare function useQuery_experimental<Query extends FunctionReference<'query'>, ThrowOnError extends boolean = false>(options: UseQueryOptions<Query, ThrowOnError>): ComputedRef<UseQueryResult<Query['_returnType'], ThrowOnError>>;
 /** @public */

package/dist/runtime/vue/composables/use-subscription.d.ts

@@ -1,15 +1 @@
-import { type ShallowRef } from 'vue';
-/**
- * Composable used for safely managing subscriptions in concurrent mode.
- *
- * In order to avoid removing and re-adding subscriptions each time this composable is called,
- * the parameters passed to this composable should be memoized in some way–
- * either by wrapping the entire params object with useMemo()
- * or by wrapping the individual callbacks with useCallback().
- *
- * @internal
- */
-export declare function useSubscription<Value>({ getCurrentValue, subscribe, }: {
-    getCurrentValue: () => Value;
-    subscribe: (callback: () => void) => () => void;
-}): ShallowRef<Value>;
+export {};

package/dist/runtime/vue/composables/use-upload-queue.d.ts

@@ -40,8 +40,8 @@ export interface UseUploadQueueOptions {
     /** Called once every queued item has settled (succeeded or failed). */
     onComplete?: (items: UploadQueueItem[]) => void;
 }
-/** Accepted inputs to {@link VueUploadQueue.enqueue}. */
-type EnqueueInput = Blob | Blob[] | FileList | null | undefined;
+/** Accepted inputs to {@link VueUploadQueue.enqueue}. @public */
+export type EnqueueInput = Blob | Blob[] | FileList | null | undefined;
 /**
  * The reactive queue returned by {@link useUploadQueue}.
  *
@@ -114,4 +114,3 @@ export interface VueUploadQueue {
 export declare function useUploadQueue(generateUploadUrl: GenerateUploadUrl, options?: UseUploadQueueOptions): VueUploadQueue;
 /** @public */
 export declare const useConvexUploadQueue: typeof useUploadQueue;
-export {};

package/dist/runtime/vue/hydration.d.ts

@@ -14,10 +14,10 @@ export type Preloaded<Query extends FunctionReference<'query'>> = {
 };
 /**
  * Load a reactive query within a Vue component using a `Preloaded` payload
- * from the server returned by {@link preloadQuery}.
+ * from the server returned by {@link server!preloadQuery | preloadQuery}.
  *
- * This Vue composable contains internal state that will cause a rerender
- * whenever the query result changes.
+ * This Vue composable returns a computed that updates whenever the query
+ * result changes.
  *
  * Throws an error if no Convex client has been provided (see {@link useConvex}).
  *
@@ -43,24 +43,3 @@ export type Preloaded<Query extends FunctionReference<'query'>> = {
  * @public
  */
 export declare function usePreloadedQuery<Query extends FunctionReference<'query'>>(preloadedQuery: MaybeRefOrGetter<Preloaded<Query>>): ComputedRef<Query['_returnType']>;
-/**
- * Derive the query reference and reactive args/fallback from a (possibly
- * reactive) `Preloaded` payload. All three are reactive: swapping in a payload
- * for a different query re-derives the reference, matching upstream's
- * `usePreloadedQuery`, which recomputes `makeFunctionReference(_name)` on
- * every render.
- *
- * @internal
- */
-export declare function usePreloadedPayload<Query extends FunctionReference<'query'>>(preloadedQuery: MaybeRefOrGetter<Preloaded<Query>>): {
-    query: ComputedRef<Query>;
-    args: ComputedRef<Query['_args']>;
-    preloadedResult: ComputedRef<Query['_returnType']>;
-};
-/**
- * A `useQuery` variant whose query *reference* is reactive alongside its args.
- * Pass `'skip'` args to pause the subscription.
- *
- * @internal
- */
-export declare function useReactiveQuery<Query extends FunctionReference<'query'>>(query: ComputedRef<Query>, args: ComputedRef<Query['_args'] | 'skip'>): ComputedRef<Query['_returnType'] | undefined>;

package/dist/runtime/vue/index.d.ts

@@ -69,7 +69,6 @@ export type { AuthTokenFetcher } from 'convex/browser';
 export * from './auth/helpers.js';
 export * from './auth/index.js';
 export { usePreloadedQuery, type Preloaded } from './hydration.js';
-export { useSubscription } from './composables/use-subscription.js';
 export { type VueMutation } from './composables/use-mutation.js';
 export { type VueAction } from './composables/use-action.js';
 export { type Watch, type WatchQueryOptions, type MutationOptions, type ConvexVueClientOptions, } from './client.js';
@@ -89,6 +88,7 @@ export type { ConnectionState, OptimisticUpdate, QueryJournal, } from 'convex/br
 export type { FunctionReference, FunctionArgs, FunctionReturnType, OptionalRestArgs, ArgsAndOptions, } from 'convex/server';
 export type { Value } from 'convex/values';
 export { useUpload, useConvexUpload, uploadFile, type VueUpload, type UseUploadOptions, type UploadFileOptions, type GenerateUploadUrl, type StorageId, } from './composables/use-upload.js';
-export { useUploadQueue, useConvexUploadQueue, type VueUploadQueue, type UseUploadQueueOptions, type UploadQueueItem, type UploadItemStatus, } from './composables/use-upload-queue.js';
+export { useUploadQueue, useConvexUploadQueue, type VueUploadQueue, type UseUploadQueueOptions, type UploadQueueItem, type UploadItemStatus, type EnqueueInput, } from './composables/use-upload-queue.js';
 export { useStorageUrl, useConvexStorageUrl, type GetStorageUrl, } from './composables/use-storage-url.js';
+export { ConvexImage } from './components/convex-image.js';
 export { provideConvexApi, useConvexApi, useConvexNamespace, ConvexApiKey, type ConvexApi, } from './provide.js';

package/dist/runtime/vue/index.js

@@ -34,6 +34,7 @@ export {
   useStorageUrl,
   useConvexStorageUrl
 } from "./composables/use-storage-url.js";
+export { ConvexImage } from "./components/convex-image.js";
 export {
   provideConvexApi,
   useConvexApi,

package/dist/runtime/vue/plugin.js

@@ -6,7 +6,7 @@ export default defineNuxtPlugin({
     const url = useRuntimeConfig().public.convex.url;
     if (!url) {
       if (import.meta.client) {
-        console.warn("[nuxt-convex-module] No Convex URL configured; client not created.");
+        console.warn("[nuxt-convex-module] No Convex deployment URL configured \u2014 client not created. Set NUXT_PUBLIC_CONVEX_URL or `convex.url` in nuxt.config.");
       }
       return;
     }

package/dist/runtime/vue/provide.d.ts

@@ -9,8 +9,8 @@ export type ConvexApi = Record<string, Record<string, unknown>>;
 export declare const ConvexApiKey: InjectionKey<ConvexApi>;
 /**
  * Make the generated Convex `api` available to every `nuxt-convex-module` composable
- * and component, so `useBilling()`, `<CheckoutLink>`, `useEmailStatus()`, … work
- * with zero arguments.
+ * and component, so `<CheckoutLink>`, `<CustomerPortalLink>`, `useConvexNamespace()`,
+ * … work with zero arguments.
  *
  * The packaged Nuxt plugin calls this automatically with `#convex/api`. Call it
  * yourself (e.g. with a custom `api`) only to override that default — pass the
@@ -30,9 +30,9 @@ export declare function provideConvexApi(api: ConvexApi, app?: App): void;
  */
 export declare function useConvexApi(): ConvexApi | undefined;
 /**
- * The named function group from the generated `api` (e.g. `'billing'`,
- * `'email'`), or `undefined` when billing/email isn't scaffolded — letting the
- * feature degrade to a graceful no-op rather than throwing.
+ * The named function group from the generated `api` (e.g. `'polar'`), or
+ * `undefined` when that group isn't scaffolded — letting the feature degrade
+ * to a graceful no-op rather than throwing.
  *
  * @typeParam T - The expected shape of the namespace's function references.
  */

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { default } from './module.mjs'
+
+export { type BetterAuthModuleOptions, type ModuleOptions } from './module.mjs'