@tthr/vue 0.0.3 → 0.0.5

package/nuxt/module.ts

@@ -2,6 +2,7 @@
  * @tthr/vue/nuxt - Tether Nuxt Module
  *
  * Automatically configures Tether for Nuxt applications.
+ * All API calls are proxied through Nuxt server routes to keep API keys secure.
  *
  * Usage in nuxt.config.ts:
  * ```ts
@@ -13,9 +14,12 @@
  *   },
  * })
  * ```
+ *
+ * Environment variables (in .env):
+ * - TETHER_API_KEY: Your project's API key (required, kept server-side)
  */
 
-import { defineNuxtModule, addPlugin, createResolver, addImports, addComponent } from '@nuxt/kit';
+import { defineNuxtModule, addPlugin, createResolver, addImports, addComponent, addServerHandler } from '@nuxt/kit';
 
 export interface TetherModuleOptions {
   /** Project ID from Tether dashboard */
@@ -39,15 +43,33 @@ export default defineNuxtModule<TetherModuleOptions>({
   setup(options, nuxt) {
     const resolver = createResolver(import.meta.url);
 
-    // Add runtime config for client-side access
+    // Server-side config (includes API key - never exposed to client)
+    nuxt.options.runtimeConfig.tether = {
+      apiKey: '', // Will be populated from TETHER_API_KEY env var
+      url: options.url || 'https://api.tether.strands.gg',
+      projectId: options.projectId || '',
+    };
+
+    // Public config (safe for client - no secrets)
     nuxt.options.runtimeConfig.public.tether = {
       projectId: options.projectId || '',
-      url: options.url || 'https://api.tether.strands.gg',
+      wsUrl: (options.url || 'https://api.tether.strands.gg').replace('http', 'ws'),
     };
 
-    // Add the plugin that initialises Tether on the client
+    // Add server API routes for proxying Tether requests
+    addServerHandler({
+      route: '/api/_tether/query',
+      handler: resolver.resolve('./runtime/server/query.post'),
+    });
+
+    addServerHandler({
+      route: '/api/_tether/mutation',
+      handler: resolver.resolve('./runtime/server/mutation.post'),
+    });
+
+    // Add the client plugin for WebSocket subscriptions only
     addPlugin({
-      src: resolver.resolve('./runtime/plugin'),
+      src: resolver.resolve('./runtime/plugin.client'),
       mode: 'client',
     });
 
@@ -62,7 +84,7 @@ export default defineNuxtModule<TetherModuleOptions>({
         from: resolver.resolve('./runtime/composables'),
       },
       {
-        name: 'useTether',
+        name: 'useTetherSubscription',
         from: resolver.resolve('./runtime/composables'),
       },
     ]);

package/nuxt/runtime/components/TetherWelcome.vue

@@ -105,8 +105,8 @@
 </template>
 
 <script setup lang="ts">
-import { ref, onMounted } from 'vue';
-import { useTether, useQuery, useMutation } from '../composables';
+import { ref } from 'vue';
+import { useQuery, useMutation, useTetherSubscription } from '../composables';
 
 interface Post {
   id: string;
@@ -117,22 +117,16 @@ interface Post {
   updatedAt: string;
 }
 
-const isConnected = ref(false);
 const newPostTitle = ref('');
 
-// Set up queries and mutations
-const posts = useQuery<void, Post[]>({ _name: 'posts.list' });
-const createPost = useMutation<{ title: string; content?: string }, { id: string }>({ _name: 'posts.create' });
-const deletePost = useMutation<{ id: string }, void>({ _name: 'posts.remove' });
+// Set up queries and mutations (these use SSR-safe server routes)
+const posts = useQuery<void, Post[]>('posts.list');
+const createPost = useMutation<{ title: string; content?: string }, { id: string }>('posts.create');
+const deletePost = useMutation<{ id: string }, void>('posts.remove');
 
-onMounted(async () => {
-  try {
-    const client = useTether();
-    await client.connect();
-    isConnected.value = true;
-  } catch {
-    // Connection handled by client
-  }
+// Set up WebSocket subscription for realtime updates (client-side only)
+const { isConnected } = useTetherSubscription('posts.list', undefined, () => {
+  posts.refetch();
 });
 
 async function handleCreatePost() {

package/nuxt/runtime/composables.ts

@@ -2,21 +2,11 @@
  * Nuxt composables for Tether
  *
  * These are auto-imported when using the Tether Nuxt module.
+ * Queries and mutations are executed server-side to keep API keys secure.
+ * WebSocket subscriptions run client-side for realtime updates.
  */
 
-import { ref, onMounted, onUnmounted, type Ref } from 'vue';
-import { tetherClient } from './plugin';
-import type { TetherClient } from '@tthr/client';
-
-/**
- * Get the Tether client instance
- */
-export function useTether(): TetherClient {
-  if (!tetherClient) {
-    throw new Error('[Tether] Client not initialised. Make sure the Tether module is configured in nuxt.config.ts');
-  }
-  return tetherClient;
-}
+import { ref, onMounted, onUnmounted, watch, type Ref } from 'vue';
 
 /**
  * Query state returned by useQuery
@@ -38,7 +28,7 @@ export interface QueryFunction<TArgs = void, TResult = unknown> {
 }
 
 /**
- * Reactive query composable with auto-subscription
+ * Reactive query composable with auto-refresh on subscription updates
  *
  * @example
  * ```vue
@@ -48,23 +38,28 @@ export interface QueryFunction<TArgs = void, TResult = unknown> {
  * ```
  */
 export function useQuery<TArgs, TResult>(
-  query: QueryFunction<TArgs, TResult>,
+  query: QueryFunction<TArgs, TResult> | string,
   args?: TArgs
 ): QueryState<TResult> {
+  const queryName = typeof query === 'string' ? query : query._name;
   const data = ref<TResult>();
   const error = ref<Error | null>(null);
   const isLoading = ref(true);
 
-  let unsubscribe: (() => void) | null = null;
-
   const fetchData = async () => {
     try {
       isLoading.value = true;
       error.value = null;
 
-      const client = useTether();
-      const result = await client.query(query._name, args);
-      data.value = result as TResult;
+      const response = await $fetch<{ data: TResult }>('/api/_tether/query', {
+        method: 'POST',
+        body: {
+          function: queryName,
+          args,
+        },
+      });
+
+      data.value = response.data;
     } catch (e) {
       error.value = e instanceof Error ? e : new Error(String(e));
     } finally {
@@ -72,21 +67,15 @@ export function useQuery<TArgs, TResult>(
     }
   };
 
-  onMounted(async () => {
-    await fetchData();
-
-    // Subscribe to realtime updates
-    const client = useTether();
-    unsubscribe = client.subscribe(query._name, args, (newData) => {
-      data.value = newData as TResult;
-    });
+  // Fetch on mount (client-side)
+  onMounted(() => {
+    fetchData();
   });
 
-  onUnmounted(() => {
-    if (unsubscribe) {
-      unsubscribe();
-    }
-  });
+  // Also fetch immediately for SSR
+  if (import.meta.server) {
+    fetchData();
+  }
 
   return {
     data: data as Ref<TResult | undefined>,
@@ -131,8 +120,9 @@ export interface MutationFunction<TArgs = void, TResult = unknown> {
  * ```
  */
 export function useMutation<TArgs, TResult>(
-  mutation: MutationFunction<TArgs, TResult>
+  mutation: MutationFunction<TArgs, TResult> | string
 ): MutationState<TArgs, TResult> {
+  const mutationName = typeof mutation === 'string' ? mutation : mutation._name;
   const data = ref<TResult>();
   const error = ref<Error | null>(null);
   const isPending = ref(false);
@@ -142,10 +132,16 @@ export function useMutation<TArgs, TResult>(
       isPending.value = true;
       error.value = null;
 
-      const client = useTether();
-      const result = await client.mutation(mutation._name, args);
-      data.value = result as TResult;
-      return result as TResult;
+      const response = await $fetch<{ data: TResult }>('/api/_tether/mutation', {
+        method: 'POST',
+        body: {
+          function: mutationName,
+          args,
+        },
+      });
+
+      data.value = response.data;
+      return response.data;
     } catch (e) {
       error.value = e instanceof Error ? e : new Error(String(e));
       throw e;
@@ -168,3 +164,86 @@ export function useMutation<TArgs, TResult>(
     reset,
   };
 }
+
+/**
+ * WebSocket subscription composable for realtime updates
+ * This runs client-side only and calls refetch when updates are received
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * const { data: posts, refetch } = useQuery('posts.list');
+ * useTetherSubscription('posts.list', {}, refetch);
+ * </script>
+ * ```
+ */
+export function useTetherSubscription(
+  queryName: string,
+  args: Record<string, unknown> | undefined,
+  onUpdate: () => void
+): { isConnected: Ref<boolean> } {
+  const isConnected = ref(false);
+
+  if (import.meta.client) {
+    let ws: WebSocket | null = null;
+    let reconnectTimeout: ReturnType<typeof setTimeout> | null = null;
+
+    const connect = () => {
+      // Get config from window (set by plugin)
+      const config = (window as any).__TETHER_CONFIG__;
+      if (!config?.wsUrl || !config?.projectId) {
+        console.warn('[Tether] WebSocket config not available');
+        return;
+      }
+
+      const wsUrl = `${config.wsUrl}/ws/${config.projectId}`;
+      ws = new WebSocket(wsUrl);
+
+      ws.onopen = () => {
+        isConnected.value = true;
+        // Subscribe to the query
+        ws?.send(JSON.stringify({
+          type: 'subscribe',
+          query: queryName,
+          args,
+        }));
+      };
+
+      ws.onmessage = (event) => {
+        try {
+          const message = JSON.parse(event.data);
+          if (message.type === 'update' && message.query === queryName) {
+            onUpdate();
+          }
+        } catch {
+          // Ignore parse errors
+        }
+      };
+
+      ws.onclose = () => {
+        isConnected.value = false;
+        // Reconnect after 3 seconds
+        reconnectTimeout = setTimeout(connect, 3000);
+      };
+
+      ws.onerror = () => {
+        ws?.close();
+      };
+    };
+
+    onMounted(() => {
+      connect();
+    });
+
+    onUnmounted(() => {
+      if (reconnectTimeout) {
+        clearTimeout(reconnectTimeout);
+      }
+      if (ws) {
+        ws.close();
+      }
+    });
+  }
+
+  return { isConnected };
+}

package/nuxt/runtime/plugin.client.ts

@@ -0,0 +1,28 @@
+/**
+ * Client-side Tether plugin
+ *
+ * Sets up the WebSocket configuration for realtime subscriptions.
+ * This only exposes the project ID and WebSocket URL - no secrets.
+ */
+
+import { defineNuxtPlugin, useRuntimeConfig } from '#imports';
+
+declare global {
+  interface Window {
+    __TETHER_CONFIG__?: {
+      projectId: string;
+      wsUrl: string;
+    };
+  }
+}
+
+export default defineNuxtPlugin(() => {
+  const config = useRuntimeConfig();
+
+  // Make config available for WebSocket connections
+  // This is safe - no secrets are exposed
+  window.__TETHER_CONFIG__ = {
+    projectId: config.public.tether.projectId,
+    wsUrl: config.public.tether.wsUrl,
+  };
+});

package/nuxt/runtime/server/mutation.post.ts

@@ -0,0 +1,61 @@
+/**
+ * Server-side mutation handler
+ * Proxies mutations to Tether API with the secret API key
+ */
+
+import { defineEventHandler, readBody, createError } from 'h3';
+import { useRuntimeConfig } from '#imports';
+
+export default defineEventHandler(async (event) => {
+  const config = useRuntimeConfig();
+
+  // Get API key from runtime config (populated from TETHER_API_KEY env var)
+  const apiKey = config.tether?.apiKey || process.env.TETHER_API_KEY;
+  const url = config.tether?.url || process.env.TETHER_URL || 'http://localhost:3001';
+  const projectId = config.tether?.projectId || process.env.TETHER_PROJECT_ID;
+
+  if (!apiKey) {
+    throw createError({
+      statusCode: 500,
+      message: 'Tether API key not configured. Set TETHER_API_KEY environment variable.',
+    });
+  }
+
+  if (!projectId) {
+    throw createError({
+      statusCode: 500,
+      message: 'Tether project ID not configured.',
+    });
+  }
+
+  const body = await readBody(event);
+
+  if (!body?.function) {
+    throw createError({
+      statusCode: 400,
+      message: 'Missing "function" in request body',
+    });
+  }
+
+  const response = await fetch(`${url}/api/v1/${projectId}/mutation`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({
+      function: body.function,
+      args: body.args,
+    }),
+  });
+
+  if (!response.ok) {
+    const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+    throw createError({
+      statusCode: response.status,
+      message: error.error || 'Mutation failed',
+    });
+  }
+
+  return response.json();
+});

package/nuxt/runtime/server/query.post.ts

@@ -0,0 +1,61 @@
+/**
+ * Server-side query handler
+ * Proxies queries to Tether API with the secret API key
+ */
+
+import { defineEventHandler, readBody, createError } from 'h3';
+import { useRuntimeConfig } from '#imports';
+
+export default defineEventHandler(async (event) => {
+  const config = useRuntimeConfig();
+
+  // Get API key from runtime config (populated from TETHER_API_KEY env var)
+  const apiKey = config.tether?.apiKey || process.env.TETHER_API_KEY;
+  const url = config.tether?.url || process.env.TETHER_URL || 'http://localhost:3001';
+  const projectId = config.tether?.projectId || process.env.TETHER_PROJECT_ID;
+
+  if (!apiKey) {
+    throw createError({
+      statusCode: 500,
+      message: 'Tether API key not configured. Set TETHER_API_KEY environment variable.',
+    });
+  }
+
+  if (!projectId) {
+    throw createError({
+      statusCode: 500,
+      message: 'Tether project ID not configured.',
+    });
+  }
+
+  const body = await readBody(event);
+
+  if (!body?.function) {
+    throw createError({
+      statusCode: 400,
+      message: 'Missing "function" in request body',
+    });
+  }
+
+  const response = await fetch(`${url}/api/v1/${projectId}/query`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({
+      function: body.function,
+      args: body.args,
+    }),
+  });
+
+  if (!response.ok) {
+    const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+    throw createError({
+      statusCode: response.status,
+      message: error.error || 'Query failed',
+    });
+  }
+
+  return response.json();
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tthr/vue",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Tether Vue/Nuxt SDK",
   "type": "module",
   "main": "./dist/index.js",

package/nuxt/runtime/plugin.ts

@@ -1,33 +0,0 @@
-/**
- * Nuxt plugin that initialises the Tether client
- */
-
-import { defineNuxtPlugin, useRuntimeConfig } from '#app';
-import { TetherClient } from '@tthr/client';
-
-// Global client instance for use by composables
-export let tetherClient: TetherClient | null = null;
-
-export default defineNuxtPlugin(() => {
-  const config = useRuntimeConfig();
-  const tetherConfig = config.public.tether as { projectId: string; url: string };
-
-  if (!tetherConfig.projectId) {
-    console.warn('[Tether] No projectId configured. Set it in nuxt.config.ts under tether.projectId or via NUXT_PUBLIC_TETHER_PROJECT_ID env var.');
-  }
-
-  // Build the WebSocket URL from the API URL and project ID
-  const wsUrl = tetherConfig.url
-    .replace('https://', 'wss://')
-    .replace('http://', 'ws://');
-
-  tetherClient = new TetherClient({
-    url: `${wsUrl}/ws/${tetherConfig.projectId}`,
-  });
-
-  return {
-    provide: {
-      tether: tetherClient,
-    },
-  };
-});