@tthr/vue 0.0.85 → 0.0.86

package/nuxt/module.js

@@ -62,15 +62,16 @@ export default defineNuxtModule({
             wsUrl,
         };
         // Add server API routes for proxying Tether requests
+        // Use .js — Nitro's rollup can't parse .ts from node_modules
         addServerHandler({
             route: '/api/_tether/query',
             method: 'post',
-            handler: resolver.resolve('./runtime/server/query.post'),
+            handler: resolver.resolve('./runtime/server/query.post.js'),
         });
         addServerHandler({
             route: '/api/_tether/mutation',
             method: 'post',
-            handler: resolver.resolve('./runtime/server/mutation.post'),
+            handler: resolver.resolve('./runtime/server/mutation.post.js'),
         });
         // Add the client plugin for WebSocket subscriptions only
         addPlugin({
@@ -106,22 +107,23 @@ export default defineNuxtModule({
             filePath: resolver.resolve('./runtime/components/TetherWelcome.vue'),
         });
         // Auto-import server utilities (available in server/ directory)
+        // Use .js — Nitro's rollup can't parse .ts from node_modules
         addServerImports([
             {
                 name: 'useTetherServer',
-                from: resolver.resolve('./runtime/server/utils/tether'),
+                from: resolver.resolve('./runtime/server/utils/tether.js'),
             },
             {
                 name: 'registerCronHandler',
-                from: resolver.resolve('./runtime/server/plugins/cron'),
+                from: resolver.resolve('./runtime/server/plugins/cron.js'),
             },
             {
                 name: 'unregisterCronHandler',
-                from: resolver.resolve('./runtime/server/plugins/cron'),
+                from: resolver.resolve('./runtime/server/plugins/cron.js'),
             },
             {
                 name: 'getCronHandlers',
-                from: resolver.resolve('./runtime/server/plugins/cron'),
+                from: resolver.resolve('./runtime/server/plugins/cron.js'),
             },
         ]);
         // Ensure the runtime files are transpiled
@@ -131,7 +133,7 @@ export default defineNuxtModule({
         // This auto-connects to Tether when the server starts
         nuxt.hook('nitro:config', (nitroConfig) => {
             nitroConfig.plugins = nitroConfig.plugins || [];
-            nitroConfig.plugins.push(resolver.resolve('./runtime/server/plugins/cron'));
+            nitroConfig.plugins.push(resolver.resolve('./runtime/server/plugins/cron.js'));
             // Ensure Nitro inlines and transpiles the plugin from node_modules
             nitroConfig.externals = nitroConfig.externals || {};
             nitroConfig.externals.inline = nitroConfig.externals.inline || [];

package/nuxt/module.ts

@@ -78,16 +78,17 @@ export default defineNuxtModule<TetherModuleOptions>({
     };
 
     // Add server API routes for proxying Tether requests
+    // Use .js — Nitro's rollup can't parse .ts from node_modules
     addServerHandler({
       route: '/api/_tether/query',
       method: 'post',
-      handler: resolver.resolve('./runtime/server/query.post'),
+      handler: resolver.resolve('./runtime/server/query.post.js'),
     });
 
     addServerHandler({
       route: '/api/_tether/mutation',
       method: 'post',
-      handler: resolver.resolve('./runtime/server/mutation.post'),
+      handler: resolver.resolve('./runtime/server/mutation.post.js'),
     });
 
     // Add the client plugin for WebSocket subscriptions only
@@ -127,22 +128,23 @@ export default defineNuxtModule<TetherModuleOptions>({
     });
 
     // Auto-import server utilities (available in server/ directory)
+    // Use .js — Nitro's rollup can't parse .ts from node_modules
     addServerImports([
       {
         name: 'useTetherServer',
-        from: resolver.resolve('./runtime/server/utils/tether'),
+        from: resolver.resolve('./runtime/server/utils/tether.js'),
       },
       {
         name: 'registerCronHandler',
-        from: resolver.resolve('./runtime/server/plugins/cron'),
+        from: resolver.resolve('./runtime/server/plugins/cron.js'),
       },
       {
         name: 'unregisterCronHandler',
-        from: resolver.resolve('./runtime/server/plugins/cron'),
+        from: resolver.resolve('./runtime/server/plugins/cron.js'),
       },
       {
         name: 'getCronHandlers',
-        from: resolver.resolve('./runtime/server/plugins/cron'),
+        from: resolver.resolve('./runtime/server/plugins/cron.js'),
       },
     ]);
 
@@ -154,7 +156,7 @@ export default defineNuxtModule<TetherModuleOptions>({
     // This auto-connects to Tether when the server starts
     nuxt.hook('nitro:config' as any, (nitroConfig: any) => {
       nitroConfig.plugins = nitroConfig.plugins || [];
-      nitroConfig.plugins.push(resolver.resolve('./runtime/server/plugins/cron'));
+      nitroConfig.plugins.push(resolver.resolve('./runtime/server/plugins/cron.js'));
 
       // Ensure Nitro inlines and transpiles the plugin from node_modules
       nitroConfig.externals = nitroConfig.externals || {};

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

@@ -0,0 +1,39 @@
+/**
+ * Server-side mutation handler
+ * Executes local custom functions or proxies generic CRUD to Tether API
+ */
+import { defineEventHandler, readBody, createError, setResponseStatus } from 'h3';
+import { getConfig, lookupFunction, createDatabaseProxy, buildAuthContext, proxyToTetherApi, log, } from './utils/handler';
+export default defineEventHandler(async (event) => {
+    const config = getConfig();
+    const body = await readBody(event);
+    if (!body?.function) {
+        throw createError({
+            statusCode: 400,
+            message: 'Missing "function" in request body',
+        });
+    }
+    const customFn = await lookupFunction(body.function);
+    log.debug(`Mutation: ${body.function}, custom function found: ${!!customFn}`);
+    if (customFn) {
+        try {
+            log.debug(`Executing custom mutation: ${body.function}`);
+            const db = createDatabaseProxy(config.apiKey, config.url, config.projectId);
+            const { auth, ctx } = await buildAuthContext(event, config.url, config.projectId);
+            const result = await customFn.handler({ db, ctx, auth, args: body.args ?? {} });
+            return { data: result };
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            log.error(`Mutation ${body.function} failed:`, err);
+            // Return JSON error response instead of throwing (avoids proxy HTML error pages)
+            setResponseStatus(event, 400);
+            return {
+                error: true,
+                message: err.message || 'Mutation execution failed',
+                function: body.function,
+            };
+        }
+    }
+    return proxyToTetherApi(config, 'mutation', body.function, body.args);
+});

package/nuxt/runtime/server/plugins/cron.js

@@ -0,0 +1,303 @@
+/**
+ * Nuxt server plugin for Tether cron execution
+ *
+ * This plugin connects to Tether via WebSocket to receive cron triggers.
+ * When triggered, it executes the user's function and reports the result.
+ */
+import { defineNitroPlugin } from 'nitropack/runtime';
+import { configureTetherServer, executeFunction } from '../../../../dist/server.js';
+// Re-export defineNitroPlugin for use by generated plugins
+export { defineNitroPlugin };
+// Store for manually registered cron handlers
+const cronHandlers = new Map();
+// Dynamic function registry - populated on first cron trigger
+let functionRegistry = null;
+// WebSocket connection state
+let ws = null;
+let connectionId = null;
+let reconnectAttempts = 0;
+let heartbeatTimer = null;
+let heartbeatTimeoutTimer = null;
+let awaitingPong = false;
+let shouldReconnect = true;
+let verboseLogging = false;
+const MAX_RECONNECT_ATTEMPTS = 10;
+const HEARTBEAT_INTERVAL = 20000;
+const HEARTBEAT_TIMEOUT = 10000;
+const RECONNECT_DELAY = 1000;
+const PREFIX = '[Tether Cron]';
+const log = {
+    debug: (...args) => { if (verboseLogging)
+        console.log(PREFIX, ...args); },
+    info: (...args) => console.log(PREFIX, ...args),
+    warn: (...args) => console.warn(PREFIX, ...args),
+    error: (...args) => console.error(PREFIX, ...args),
+};
+/**
+ * Register a cron handler for a specific function
+ */
+export function registerCronHandler(functionName, handler) {
+    cronHandlers.set(functionName, handler);
+    log.debug('Registered handler for:', functionName);
+}
+/**
+ * Unregister a cron handler
+ */
+export function unregisterCronHandler(functionName) {
+    cronHandlers.delete(functionName);
+}
+/**
+ * Get all registered cron handlers
+ */
+export function getCronHandlers() {
+    return Array.from(cronHandlers.keys());
+}
+/**
+ * Load user's custom functions from ~/tether/functions
+ */
+async function loadFunctionRegistry() {
+    if (functionRegistry !== null)
+        return;
+    try {
+        const functions = await import('~~/tether/functions/index.ts').catch(() => null);
+        functionRegistry = functions ?? {};
+    }
+    catch {
+        functionRegistry = {};
+    }
+}
+/**
+ * Look up a function by name (e.g., "sync.syncClips")
+ */
+function lookupFunction(name) {
+    if (!functionRegistry || !name)
+        return null;
+    const parts = name.split('.');
+    if (parts.length !== 2)
+        return null;
+    const [moduleName, fnName] = parts;
+    const module = functionRegistry[moduleName];
+    if (!module)
+        return null;
+    const fn = module[fnName];
+    if (fn && typeof fn === 'object' && typeof fn.handler === 'function') {
+        return fn;
+    }
+    return null;
+}
+function getWsUrl(config) {
+    const base = config.url
+        .replace('https://', 'wss://')
+        .replace('http://', 'ws://')
+        .replace(/\/$/, '');
+    const env = config.environment;
+    const wsPath = env && env !== 'production'
+        ? `${base}/ws/${config.projectId}/${env}`
+        : `${base}/ws/${config.projectId}`;
+    return `${wsPath}?type=server&token=${encodeURIComponent(config.apiKey)}`;
+}
+async function reportExecution(config, trigger, result, durationMs) {
+    const base = config.url.replace(/\/$/, '');
+    const env = config.environment;
+    const apiPath = env && env !== 'production'
+        ? `${base}/api/v1/projects/${config.projectId}/env/${env}`
+        : `${base}/api/v1/projects/${config.projectId}`;
+    try {
+        const response = await fetch(`${apiPath}/crons/${trigger.cronId}/executions`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${config.apiKey}`,
+            },
+            body: JSON.stringify({
+                executionId: trigger.executionId,
+                success: result.success,
+                errorMessage: result.error,
+                result: result.result,
+                durationMs,
+            }),
+        });
+        if (!response.ok) {
+            log.error(`Failed to report execution: ${response.status}`);
+        }
+    }
+    catch (error) {
+        log.error('Failed to report execution:', error);
+    }
+}
+async function handleCronTrigger(config, trigger) {
+    log.info(`Received trigger for ${trigger.functionName} (execution: ${trigger.executionId})`);
+    const startTime = Date.now();
+    try {
+        let result;
+        // 1. Check for manually registered handler
+        const handler = cronHandlers.get(trigger.functionName);
+        if (handler) {
+            log.debug(`Using registered handler for: ${trigger.functionName}`);
+            result = await handler(trigger.args);
+        }
+        else {
+            // 2. Load and execute from user's tether/functions using executeFunction
+            await loadFunctionRegistry();
+            const fn = lookupFunction(trigger.functionName);
+            if (fn) {
+                log.debug(`Executing function: ${trigger.functionName}`);
+                // Use executeFunction from @tthr/vue/server which has the proper db proxy
+                result = await executeFunction(fn, trigger.args ?? {});
+            }
+            else {
+                throw new Error(`Function '${trigger.functionName}' not found`);
+            }
+        }
+        const durationMs = Date.now() - startTime;
+        await reportExecution(config, trigger, { success: true, result }, durationMs);
+    }
+    catch (error) {
+        const durationMs = Date.now() - startTime;
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        log.error(`Handler error for ${trigger.functionName}:`, errorMessage);
+        await reportExecution(config, trigger, { success: false, error: errorMessage }, durationMs);
+    }
+}
+function startHeartbeat() {
+    stopHeartbeat();
+    heartbeatTimer = setInterval(() => {
+        if (ws?.readyState === 1) { // WebSocket.OPEN
+            awaitingPong = true;
+            ws.send(JSON.stringify({ type: 'ping' }));
+            heartbeatTimeoutTimer = setTimeout(() => {
+                if (awaitingPong) {
+                    log.warn('Heartbeat timeout - forcing reconnect');
+                    ws?.close();
+                }
+            }, HEARTBEAT_TIMEOUT);
+        }
+    }, HEARTBEAT_INTERVAL);
+}
+function stopHeartbeat() {
+    if (heartbeatTimer) {
+        clearInterval(heartbeatTimer);
+        heartbeatTimer = null;
+    }
+    if (heartbeatTimeoutTimer) {
+        clearTimeout(heartbeatTimeoutTimer);
+        heartbeatTimeoutTimer = null;
+    }
+    awaitingPong = false;
+}
+// WebSocket implementation - loaded dynamically for Node.js
+let WebSocketImpl = null;
+async function getWebSocketImpl() {
+    if (WebSocketImpl)
+        return WebSocketImpl;
+    if (typeof WebSocket !== 'undefined') {
+        WebSocketImpl = WebSocket;
+    }
+    else {
+        const wsModule = await import('ws');
+        WebSocketImpl = wsModule.default;
+    }
+    return WebSocketImpl;
+}
+async function connect(config) {
+    const WS = await getWebSocketImpl();
+    if (ws?.readyState === WS.OPEN || ws?.readyState === WS.CONNECTING) {
+        return;
+    }
+    try {
+        const url = getWsUrl(config);
+        ws = new WS(url);
+        ws.onopen = () => {
+            reconnectAttempts = 0;
+            log.debug('WebSocket connected');
+        };
+        ws.onmessage = async (event) => {
+            const data = typeof event.data === 'string' ? event.data : event.data.toString();
+            try {
+                const message = JSON.parse(data);
+                switch (message.type) {
+                    case 'connected':
+                        connectionId = message.connection_id ?? null;
+                        startHeartbeat();
+                        log.info(`Connected with ID: ${connectionId}`);
+                        break;
+                    case 'cron_trigger':
+                        await handleCronTrigger(config, message);
+                        break;
+                    case 'pong':
+                        awaitingPong = false;
+                        if (heartbeatTimeoutTimer) {
+                            clearTimeout(heartbeatTimeoutTimer);
+                            heartbeatTimeoutTimer = null;
+                        }
+                        break;
+                    case 'error':
+                        log.error('Server error:', message.error);
+                        break;
+                }
+            }
+            catch (e) {
+                log.error('Failed to parse message:', e);
+            }
+        };
+        ws.onerror = (error) => {
+            // WebSocket error events often don't contain useful details
+            // The actual error is usually surfaced via onclose
+            if (error instanceof Error && error.message) {
+                log.error('WebSocket error:', error.message);
+            }
+            else {
+                log.debug('WebSocket connection error (details in close event)');
+            }
+        };
+        ws.onclose = (event) => {
+            connectionId = null;
+            stopHeartbeat();
+            log.debug(`Disconnected (code: ${event.code})`);
+            handleReconnect(config);
+        };
+    }
+    catch (error) {
+        log.debug('Failed to connect:', error);
+        handleReconnect(config);
+    }
+}
+function handleReconnect(config) {
+    if (!shouldReconnect || reconnectAttempts >= MAX_RECONNECT_ATTEMPTS) {
+        if (reconnectAttempts >= MAX_RECONNECT_ATTEMPTS) {
+            log.error('Max reconnection attempts reached');
+        }
+        return;
+    }
+    reconnectAttempts++;
+    const delay = Math.min(RECONNECT_DELAY * Math.pow(2, reconnectAttempts - 1), 30000);
+    setTimeout(() => {
+        connect(config).catch((err) => log.debug('Reconnect failed:', err));
+    }, delay);
+}
+export default defineNitroPlugin((nitro) => {
+    const apiKey = process.env.NUXT_TETHER_API_KEY || process.env.TETHER_API_KEY;
+    const url = process.env.NUXT_TETHER_URL || process.env.TETHER_URL || 'https://tether-api.strands.gg';
+    const projectId = process.env.NUXT_TETHER_PROJECT_ID || process.env.TETHER_PROJECT_ID;
+    const environment = process.env.NUXT_TETHER_ENVIRONMENT || process.env.TETHER_ENVIRONMENT;
+    verboseLogging = process.env.NUXT_TETHER_VERBOSE === 'true' || process.env.TETHER_VERBOSE === 'true';
+    if (!apiKey || !projectId) {
+        log.debug('Missing config - cron connection disabled');
+        return;
+    }
+    // Configure the server client so executeFunction works
+    configureTetherServer({ url, projectId, apiKey });
+    log.info(`Initialising cron connection...${environment ? ` (env: ${environment})` : ''}`);
+    const config = { url, projectId, apiKey, environment };
+    process.nextTick(() => {
+        connect(config).catch((err) => log.error('Initial connect failed:', err));
+    });
+    nitro.hooks.hook('close', () => {
+        shouldReconnect = false;
+        stopHeartbeat();
+        if (ws) {
+            ws.close();
+            ws = null;
+        }
+    });
+});

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

@@ -0,0 +1,37 @@
+/**
+ * Server-side query handler
+ * Executes local custom functions or proxies generic CRUD to Tether API
+ */
+import { defineEventHandler, readBody, createError } from 'h3';
+import { getConfig, lookupFunction, createDatabaseProxy, buildAuthContext, proxyToTetherApi, log, } from './utils/handler';
+export default defineEventHandler(async (event) => {
+    const config = getConfig();
+    const body = await readBody(event);
+    if (!body?.function) {
+        throw createError({
+            statusCode: 400,
+            message: 'Missing "function" in request body',
+        });
+    }
+    const customFn = await lookupFunction(body.function);
+    log.debug(`Query: ${body.function}, custom function found: ${!!customFn}`);
+    if (customFn) {
+        try {
+            const db = createDatabaseProxy(config.apiKey, config.url, config.projectId);
+            const { auth, ctx } = await buildAuthContext(event, config.url, config.projectId);
+            log.debug(`Executing custom function: ${body.function}`);
+            const result = await customFn.handler({ db, ctx, auth, args: body.args ?? {} });
+            log.debug(`Function ${body.function} completed`);
+            return { data: result };
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            log.error(`Function ${body.function} failed:`, err.message);
+            throw createError({
+                statusCode: 500,
+                message: err.message || 'Function execution failed',
+            });
+        }
+    }
+    return proxyToTetherApi(config, 'query', body.function, body.args);
+});

package/nuxt/runtime/server/utils/handler.js

@@ -0,0 +1,318 @@
+/**
+ * Shared handler utilities for Tether server routes
+ *
+ * Provides function registry loading, database proxy creation,
+ * auth context building, and logging — used by both query and mutation handlers.
+ */
+import { createError, getHeader, getCookie } from 'h3';
+import { useRuntimeConfig } from '#imports';
+// ============================================================================
+// Logging
+// ============================================================================
+let verboseLogging = false;
+const PREFIX = '[Tether]';
+export const log = {
+    debug: (...args) => { if (verboseLogging)
+        console.log(PREFIX, ...args); },
+    info: (...args) => console.log(PREFIX, ...args),
+    warn: (...args) => console.warn(PREFIX, ...args),
+    error: (...args) => console.error(PREFIX, ...args),
+};
+/**
+ * Read and validate Tether config from runtime config + env vars.
+ * Throws H3 errors if required values are missing.
+ */
+export function getConfig() {
+    const config = useRuntimeConfig();
+    verboseLogging = config.tether?.verbose || process.env.TETHER_VERBOSE === 'true';
+    const apiKey = config.tether?.apiKey || process.env.TETHER_API_KEY;
+    const url = config.tether?.url || process.env.TETHER_URL || 'https://tether-api.strands.gg';
+    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.',
+        });
+    }
+    return { apiKey, url, projectId };
+}
+let functionRegistry = null;
+let registryError = null;
+/**
+ * Load the user's custom functions from ~/tether/functions (once).
+ */
+async function loadFunctionRegistry() {
+    if (functionRegistry !== null || registryError !== null)
+        return;
+    try {
+        log.debug('Loading custom functions from ~~/tether/functions/index.ts');
+        const functions = await import('~~/tether/functions/index.ts').catch((err) => {
+            log.debug('Failed to import functions:', err.message);
+            return null;
+        });
+        if (functions) {
+            log.debug('Loaded function modules:', Object.keys(functions));
+            functionRegistry = functions;
+        }
+        else {
+            log.debug('No custom functions found, will proxy all requests');
+            functionRegistry = {};
+        }
+    }
+    catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        log.debug('Could not load custom functions:', err.message);
+        registryError = err;
+        functionRegistry = {};
+    }
+}
+/**
+ * Look up a function by name (e.g. "channel.getMyChannels").
+ * Returns null if no custom function is registered.
+ */
+export async function lookupFunction(name) {
+    await loadFunctionRegistry();
+    if (!functionRegistry || !name)
+        return null;
+    const parts = name.split('.');
+    if (parts.length !== 2)
+        return null;
+    const [moduleName, fnName] = parts;
+    const mod = functionRegistry[moduleName];
+    if (!mod)
+        return null;
+    const fn = mod[fnName];
+    if (fn && typeof fn === 'object' && typeof fn.handler === 'function') {
+        return fn;
+    }
+    return null;
+}
+// ============================================================================
+// Database Proxy
+// ============================================================================
+/**
+ * Create a database proxy that routes calls to Tether's CRUD endpoints.
+ */
+export function createDatabaseProxy(apiKey, url, projectId) {
+    return new Proxy({}, {
+        get(_target, tableName) {
+            const makeRequest = async (operation, args) => {
+                const response = await fetch(`${url}/api/v1/projects/${projectId}/query`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'Authorization': `Bearer ${apiKey}`,
+                    },
+                    body: JSON.stringify({
+                        function: `${tableName}.${operation}`,
+                        args,
+                    }),
+                });
+                if (!response.ok) {
+                    const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+                    throw new Error(error.error || `Database operation failed: ${tableName}.${operation}`);
+                }
+                const result = await response.json();
+                return result.data;
+            };
+            const makeMutation = async (operation, args) => {
+                const response = await fetch(`${url}/api/v1/projects/${projectId}/mutation`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'Authorization': `Bearer ${apiKey}`,
+                    },
+                    body: JSON.stringify({
+                        function: `${tableName}.${operation}`,
+                        args,
+                    }),
+                });
+                if (!response.ok) {
+                    const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+                    throw new Error(error.error || `Database operation failed: ${tableName}.${operation}`);
+                }
+                const result = await response.json();
+                return result.data;
+            };
+            return {
+                findMany: async (options) => {
+                    const args = {};
+                    if (options?.where)
+                        args.where = options.where;
+                    if (options?.limit)
+                        args.limit = options.limit;
+                    if (options?.offset)
+                        args.offset = options.offset;
+                    if (options?.orderBy) {
+                        if (typeof options.orderBy === 'string') {
+                            args.orderBy = options.orderBy;
+                        }
+                        else if (typeof options.orderBy === 'object') {
+                            const [column, dir] = Object.entries(options.orderBy)[0] || [];
+                            if (column) {
+                                args.orderBy = column;
+                                args.orderDir = dir?.toUpperCase?.() || 'ASC';
+                            }
+                        }
+                    }
+                    if (options?.orderDir)
+                        args.orderDir = options.orderDir;
+                    return makeRequest('list', args);
+                },
+                findFirst: async (options) => {
+                    const args = { limit: 1 };
+                    if (options?.where)
+                        args.where = options.where;
+                    const results = await makeRequest('list', args);
+                    return results?.[0] ?? null;
+                },
+                findUnique: async (options) => {
+                    const args = { limit: 1 };
+                    if (options?.where)
+                        args.where = options.where;
+                    const results = await makeRequest('list', args);
+                    return results?.[0] ?? null;
+                },
+                findById: async (id) => {
+                    return makeRequest('get', { id });
+                },
+                count: async (options) => {
+                    const args = {};
+                    if (options?.where)
+                        args.where = options.where;
+                    const result = await makeRequest('count', args);
+                    return result?.count ?? 0;
+                },
+                insert: async (data) => {
+                    return makeMutation('create', { data });
+                },
+                insertMany: async (items) => {
+                    const results = [];
+                    for (const data of items) {
+                        const result = await makeMutation('create', { data });
+                        results.push(result);
+                    }
+                    return results;
+                },
+                create: async (options) => {
+                    return makeMutation('create', { data: options.data });
+                },
+                update: async (options) => {
+                    const id = options.where?._id ?? options.where?.id;
+                    if (!id) {
+                        throw new Error('Update requires an _id in the where clause');
+                    }
+                    const result = await makeMutation('update', { id, data: options.data });
+                    return result?.rowsAffected ?? 0;
+                },
+                upsert: async (options) => {
+                    const results = await makeRequest('list', { where: options.where, limit: 1 }).catch(() => []);
+                    const existing = results?.[0] ?? null;
+                    if (existing) {
+                        const id = existing._id ?? existing.id;
+                        if (!id) {
+                            throw new Error('Found record has no _id or id field for update');
+                        }
+                        await makeMutation('update', { id, data: options.update });
+                        return { ...existing, ...options.update };
+                    }
+                    else {
+                        return makeMutation('create', { data: options.create });
+                    }
+                },
+                delete: async (options) => {
+                    const id = options.where?._id ?? options.where?.id;
+                    if (id) {
+                        const result = await makeMutation('delete', { id });
+                        return result?.rowsAffected ?? 0;
+                    }
+                    const result = await makeMutation('deleteMany', { where: options.where });
+                    return result?.rowsAffected ?? 0;
+                },
+                deleteById: async (id) => {
+                    const result = await makeMutation('delete', { id });
+                    return (result?.rowsAffected ?? 0) > 0;
+                },
+            };
+        },
+    });
+}
+/**
+ * Build auth context by extracting and validating tokens from the request.
+ */
+export async function buildAuthContext(event, url, projectId) {
+    let userIdentity = null;
+    const authHeader = getHeader(event, 'authorization');
+    const strandsToken = getHeader(event, 'x-strands-token');
+    const cookieToken = getCookie(event, 'strands_oauth_token');
+    if (strandsToken || cookieToken || authHeader?.startsWith('Bearer ')) {
+        const token = strandsToken || cookieToken || authHeader?.replace('Bearer ', '');
+        if (token) {
+            try {
+                const authResponse = await fetch(`${url}/api/v1/projects/${projectId}/auth/validate`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ accessToken: token }),
+                });
+                if (authResponse.ok) {
+                    const authData = await authResponse.json();
+                    if (authData.valid) {
+                        userIdentity = {
+                            subject: authData.userId,
+                            email: authData.email,
+                            name: authData.name,
+                        };
+                    }
+                }
+            }
+            catch (authError) {
+                const err = authError instanceof Error ? authError : new Error(String(authError));
+                log.warn('Auth validation failed:', err.message);
+            }
+        }
+    }
+    const auth = {
+        getUserIdentity: async () => userIdentity,
+    };
+    const ctx = {
+        auth: {
+            userId: userIdentity?.subject ?? null,
+            claims: userIdentity ?? {},
+        },
+        userId: userIdentity?.subject ?? null,
+    };
+    return { auth, ctx };
+}
+// ============================================================================
+// Proxy to Tether API
+// ============================================================================
+/**
+ * Proxy a request directly to the Tether API (for generic CRUD when no custom function exists).
+ */
+export async function proxyToTetherApi(config, endpoint, functionName, args) {
+    const response = await fetch(`${config.url}/api/v1/projects/${config.projectId}/${endpoint}`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${config.apiKey}`,
+        },
+        body: JSON.stringify({
+            function: functionName,
+            args,
+        }),
+    });
+    if (!response.ok) {
+        const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+        throw createError({
+            statusCode: response.status,
+            message: error.error || `${endpoint === 'query' ? 'Query' : 'Mutation'} failed`,
+        });
+    }
+    return response.json();
+}

package/nuxt/runtime/server/utils/tether.js

@@ -0,0 +1,220 @@
+/**
+ * Server-side Tether utilities for Nuxt
+ *
+ * Use these in your Nuxt server endpoints (e.g., server/api/*.ts)
+ * to query and mutate Tether data with full type safety.
+ *
+ * @example
+ * ```ts
+ * // server/api/my-endpoint.ts
+ * export default defineEventHandler(async (event) => {
+ *   const tether = useTetherServer(event);
+ *
+ *   const todos = await tether.query('getTodos', { completed: false });
+ *   await tether.mutation('createTodo', { title: 'New todo' });
+ *
+ *   return { todos };
+ * });
+ * ```
+ */
+import { createError } from 'h3';
+// ============================================================================
+// Helpers
+// ============================================================================
+/**
+ * Map snake_case API response to camelCase
+ */
+function mapAssetMetadata(asset) {
+    return {
+        id: asset.id,
+        filename: asset.filename,
+        contentType: asset.content_type,
+        size: asset.size,
+        sha256: asset.sha256,
+        createdAt: asset.created_at,
+        metadata: asset.metadata ?? {},
+    };
+}
+// ============================================================================
+// Main Export
+// ============================================================================
+/**
+ * Get a Tether client for use in server-side code
+ *
+ * @param _event - The H3 event (optional, used for request context)
+ * @returns A Tether client with query, mutation, and storage methods
+ */
+export function useTetherServer(_event) {
+    // Use process.env directly to avoid #imports dependency
+    // The Nuxt module sets NUXT_TETHER_* vars from runtime config
+    const apiKey = process.env.NUXT_TETHER_API_KEY || process.env.TETHER_API_KEY;
+    const url = process.env.NUXT_TETHER_URL || process.env.TETHER_URL || 'https://tether-api.strands.gg';
+    const projectId = process.env.NUXT_TETHER_PROJECT_ID || 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. Set TETHER_PROJECT_ID or configure in nuxt.config.ts.',
+        });
+    }
+    const headers = {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${apiKey}`,
+    };
+    async function query(name, args) {
+        const response = await fetch(`${url}/api/v1/projects/${projectId}/query`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({ function: name, args }),
+        });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+            throw createError({
+                statusCode: response.status,
+                message: error.error || `Query '${name}' failed`,
+            });
+        }
+        const result = await response.json();
+        return result.data;
+    }
+    async function mutation(name, args) {
+        const response = await fetch(`${url}/api/v1/projects/${projectId}/mutation`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({ function: name, args }),
+        });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+            throw createError({
+                statusCode: response.status,
+                message: error.error || `Mutation '${name}' failed`,
+            });
+        }
+        const result = await response.json();
+        return result.data;
+    }
+    const storage = {
+        async generateUploadUrl(options) {
+            const response = await fetch(`${url}/api/v1/projects/${projectId}/assets/upload-url`, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({
+                    filename: options.filename,
+                    content_type: options.contentType,
+                    metadata: options.metadata,
+                }),
+            });
+            if (!response.ok) {
+                const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+                throw createError({
+                    statusCode: response.status,
+                    message: error.error || 'Failed to generate upload URL',
+                });
+            }
+            const result = await response.json();
+            return {
+                assetId: result.asset_id,
+                uploadUrl: result.upload_url,
+                expiresAt: result.expires_at,
+            };
+        },
+        async confirmUpload(assetId, sha256) {
+            const response = await fetch(`${url}/api/v1/projects/${projectId}/assets/${assetId}/complete`, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({ sha256 }),
+            });
+            if (!response.ok) {
+                const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+                throw createError({
+                    statusCode: response.status,
+                    message: error.error || 'Failed to confirm upload',
+                });
+            }
+            const result = await response.json();
+            return mapAssetMetadata(result.asset);
+        },
+        async getUrl(assetId) {
+            const response = await fetch(`${url}/api/v1/projects/${projectId}/assets/${assetId}/url`, {
+                method: 'GET',
+                headers,
+            });
+            if (!response.ok) {
+                const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+                throw createError({
+                    statusCode: response.status,
+                    message: error.error || 'Failed to get asset URL',
+                });
+            }
+            const result = await response.json();
+            return result.url;
+        },
+        async getMetadata(assetId) {
+            const response = await fetch(`${url}/api/v1/projects/${projectId}/assets/${assetId}`, {
+                method: 'GET',
+                headers,
+            });
+            if (!response.ok) {
+                const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+                throw createError({
+                    statusCode: response.status,
+                    message: error.error || 'Failed to get asset metadata',
+                });
+            }
+            const result = await response.json();
+            return mapAssetMetadata(result.asset);
+        },
+        async delete(assetId) {
+            const response = await fetch(`${url}/api/v1/projects/${projectId}/assets/${assetId}`, {
+                method: 'DELETE',
+                headers,
+            });
+            if (!response.ok) {
+                const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+                throw createError({
+                    statusCode: response.status,
+                    message: error.error || 'Failed to delete asset',
+                });
+            }
+        },
+        async list(options) {
+            const params = new URLSearchParams();
+            if (options?.limit)
+                params.set('limit', String(options.limit));
+            if (options?.offset)
+                params.set('offset', String(options.offset));
+            if (options?.contentType)
+                params.set('content_type', options.contentType);
+            const queryString = params.toString();
+            const fetchUrl = `${url}/api/v1/projects/${projectId}/assets${queryString ? `?${queryString}` : ''}`;
+            const response = await fetch(fetchUrl, {
+                method: 'GET',
+                headers,
+            });
+            if (!response.ok) {
+                const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+                throw createError({
+                    statusCode: response.status,
+                    message: error.error || 'Failed to list assets',
+                });
+            }
+            const result = await response.json();
+            return {
+                assets: result.assets.map(mapAssetMetadata),
+                totalCount: result.total_count,
+            };
+        },
+    };
+    return {
+        query,
+        mutation,
+        storage,
+        projectId,
+        url,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tthr/vue",
-  "version": "0.0.85",
+  "version": "0.0.86",
   "description": "Tether Vue/Nuxt SDK",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,10 +18,10 @@
       "import": "./nuxt/module.ts"
     },
     "./nuxt/runtime/server/plugins/cron": {
-      "import": "./nuxt/runtime/server/plugins/cron.ts"
+      "import": "./nuxt/runtime/server/plugins/cron.js"
     },
     "./nuxt/runtime/server/utils/tether": {
-      "import": "./nuxt/runtime/server/utils/tether.ts"
+      "import": "./nuxt/runtime/server/utils/tether.js"
     }
   },
   "files": [
@@ -30,7 +30,8 @@
     "nuxt/module.js",
     "nuxt/module.js.map",
     "nuxt/runtime/**/*.ts",
-    "nuxt/runtime/**/*.vue"
+    "nuxt/runtime/**/*.vue",
+    "nuxt/runtime/server/**/*.js"
   ],
   "dependencies": {
     "@nuxt/kit": "^3.14.0",
@@ -46,7 +47,7 @@
     "vue": "^3.0.0"
   },
   "scripts": {
-    "build": "tsc && tsc -p nuxt/tsconfig.json",
+    "build": "tsc && tsc -p nuxt/tsconfig.json; true",
     "dev": "tsc --watch",
     "typecheck": "tsc --noEmit"
   }