@objectstack/nuxt 4.0.4 → 4.1.0

package/README.md

@@ -1,20 +1,59 @@
 # @objectstack/nuxt
 
-The official Nuxt adapter for ObjectStack, built on h3.
+> Nuxt adapter for ObjectStack — Nitro/h3 server routes for the auto-generated REST API.
 
-## Features
-- h3 router integration for Nuxt server routes
-- Full Auth/GraphQL/Metadata/Data/Storage routes
-- AuthPlugin service support
-- Works with standalone h3 apps too
+[![npm](https://img.shields.io/npm/v/@objectstack/nuxt.svg)](https://www.npmjs.com/package/@objectstack/nuxt)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-## Usage
+## Overview
+
+Provides an h3 router factory that exposes all ObjectStack dispatcher routes, mountable inside `server/api/[...].ts` of any Nuxt 3 application (or directly in a standalone Nitro app).
+
+## Installation
+
+```bash
+pnpm add @objectstack/nuxt
+```
+
+## Quick Start
 
 ```typescript
-// server/api/[...].ts
+// server/api/[...objectstack].ts
 import { createH3Router } from '@objectstack/nuxt';
-import { kernel } from '../kernel';
+import { kernel } from '~/server/kernel';
 
-const router = createH3Router({ kernel });
-export default defineEventHandler(router.handler);
+export default createH3Router({ kernel, prefix: '/api' }).handler;
 ```
+
+## Key Exports
+
+| Export | Kind | Description |
+|:---|:---|:---|
+| `createH3Router(options)` | function | h3 `Router` with dispatcher routes installed. |
+| `NuxtAdapterOptions` | interface | `{ kernel, prefix? }`. |
+
+## Middleware order
+
+Register Nuxt server middleware that rewrites or compresses responses **before** this router. Do not wrap ObjectStack routes with `defineEventHandler` validators.
+
+## When to use
+
+- ✅ Nuxt 3 / Nitro applications.
+- ✅ Any h3-based server (used directly via `createH3Router`).
+
+## When not to use
+
+- ❌ Nuxt 2 is not supported.
+
+## Related Packages
+
+- [`@objectstack/runtime`](../../runtime), [`@objectstack/rest`](../../rest).
+
+## Links
+
+- 📖 Docs: <https://objectstack.ai/docs>
+- 📚 API Reference: <https://objectstack.ai/docs/references>
+
+## License
+
+Apache-2.0 © ObjectStack

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/nuxt",
-  "version": "4.0.4",
+  "version": "4.1.0",
   "license": "Apache-2.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,13 +13,39 @@
   },
   "peerDependencies": {
     "h3": "^1.15.11",
-    "@objectstack/runtime": "^4.0.4"
+    "@objectstack/runtime": "^4.1.0"
   },
   "devDependencies": {
     "h3": "^1.15.11",
-    "typescript": "^6.0.2",
-    "vitest": "^4.1.4",
-    "@objectstack/runtime": "4.0.4"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7",
+    "@objectstack/runtime": "4.1.0"
+  },
+  "description": "Nuxt adapter for ObjectStack — Nitro server routes for the ObjectStack REST API.",
+  "keywords": [
+    "objectstack",
+    "nuxt",
+    "adapter",
+    "nitro",
+    "rest"
+  ],
+  "author": "ObjectStack",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/objectstack-ai/framework.git",
+    "directory": "packages/adapters/nuxt"
+  },
+  "homepage": "https://objectstack.ai/docs",
+  "bugs": "https://github.com/objectstack-ai/framework/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
   },
   "scripts": {
     "build": "tsup --config ../../../tsup.config.ts",

package/.turbo/turbo-build.log

@@ -1,22 +0,0 @@
-
-> @objectstack/nuxt@4.0.4 build /home/runner/work/framework/framework/packages/adapters/nuxt
-> tsup --config ../../../tsup.config.ts
-
-CLI Building entry: src/index.ts
-CLI Using tsconfig: tsconfig.json
-CLI tsup v8.5.1
-CLI Using tsup config: /home/runner/work/framework/framework/tsup.config.ts
-CLI Target: es2020
-CLI Cleaning output folder
-ESM Build start
-CJS Build start
-ESM dist/index.mjs     5.86 KB
-ESM dist/index.mjs.map 12.34 KB
-ESM ⚡️ Build success in 66ms
-CJS dist/index.js     7.07 KB
-CJS dist/index.js.map 12.31 KB
-CJS ⚡️ Build success in 66ms
-DTS Build start
-DTS ⚡️ Build success in 12490ms
-DTS dist/index.d.mts 1015.00 B
-DTS dist/index.d.ts  1015.00 B

package/CHANGELOG.md

@@ -1,194 +0,0 @@
-# @objectstack/nuxt
-
-## 4.0.4
-
-### Patch Changes
-
-- @objectstack/runtime@4.0.4
-
-## 4.0.3
-
-### Patch Changes
-
-- @objectstack/runtime@4.0.3
-
-## 4.0.2
-
-### Patch Changes
-
-- @objectstack/runtime@4.0.2
-
-## 4.0.0
-
-### Patch Changes
-
-- f08ffc3: Fix discovery API endpoint routing and protocol consistency.
-
-  **Discovery route standardization:**
-
-  - All adapters (Express, Fastify, Hono, NestJS, Next.js, Nuxt, SvelteKit) now mount the discovery endpoint at `{prefix}/discovery` instead of `{prefix}` root.
-  - `.well-known/objectstack` redirects now point to `{prefix}/discovery`.
-  - Client `connect()` fallback URL changed from `/api/v1` to `/api/v1/discovery`.
-  - Runtime dispatcher handles both `/discovery` (standard) and `/` (legacy) for backward compatibility.
-
-  **Schema & route alignment:**
-
-  - Added `storage` (service: `file-storage`) and `feed` (service: `data`) routes to `DEFAULT_DISPATCHER_ROUTES`.
-  - Added `feed` and `discovery` fields to `ApiRoutesSchema`.
-  - Unified `GetDiscoveryResponseSchema` with `DiscoverySchema` as single source of truth.
-  - Client `getRoute('feed')` fallback updated from `/api/v1/data` to `/api/v1/feed`.
-
-  **Type safety:**
-
-  - Extracted `ApiRouteType` from `ApiRoutes` keys for type-safe client route resolution.
-  - Removed `as any` type casting in client route access.
-
-- Updated dependencies [f08ffc3]
-- Updated dependencies [e0b0a78]
-  - @objectstack/runtime@4.0.0
-
-## 3.3.1
-
-### Patch Changes
-
-- @objectstack/runtime@3.3.1
-
-## 3.3.0
-
-### Patch Changes
-
-- @objectstack/runtime@3.3.0
-
-## 3.2.9
-
-### Patch Changes
-
-- @objectstack/runtime@3.2.9
-
-## 3.2.8
-
-### Patch Changes
-
-- @objectstack/runtime@3.2.8
-
-## 3.2.8
-
-### Patch Changes
-
-- fix: unified catch-all dispatch pattern — `createH3Router()` now delegates all non-framework-specific routes to `HttpDispatcher.dispatch()`, automatically supporting packages, analytics, automation, i18n, ui, openapi, custom endpoints, and any future routes
-- Only auth (service check), storage (multipart), GraphQL (raw result), and discovery (response wrapper) remain as explicit routes
-
-## 3.2.7
-
-### Patch Changes
-
-- @objectstack/runtime@3.2.7
-
-## 3.2.6
-
-### Patch Changes
-
-- @objectstack/runtime@3.2.6
-
-## 3.2.5
-
-### Patch Changes
-
-- @objectstack/runtime@3.2.5
-
-## 3.2.4
-
-### Patch Changes
-
-- @objectstack/runtime@3.2.4
-
-## 3.2.3
-
-### Patch Changes
-
-- @objectstack/runtime@3.2.3
-
-## 3.2.2
-
-### Patch Changes
-
-- @objectstack/runtime@3.2.2
-
-## 3.2.1
-
-### Patch Changes
-
-- @objectstack/runtime@3.2.1
-
-## 3.2.0
-
-### Patch Changes
-
-- @objectstack/runtime@3.2.0
-
-## 3.1.1
-
-### Patch Changes
-
-- @objectstack/runtime@3.1.1
-
-## 3.1.0
-
-### Patch Changes
-
-- @objectstack/runtime@3.1.0
-
-## 3.0.11
-
-### Patch Changes
-
-- @objectstack/runtime@3.0.11
-
-## 3.0.10
-
-### Patch Changes
-
-- @objectstack/runtime@3.0.10
-
-## 3.0.9
-
-### Patch Changes
-
-- @objectstack/runtime@3.0.9
-
-## 3.0.8
-
-### Patch Changes
-
-- @objectstack/runtime@3.0.8
-
-## 3.0.7
-
-### Patch Changes
-
-- @objectstack/runtime@3.0.7
-
-## 3.0.6
-
-### Patch Changes
-
-- @objectstack/runtime@3.0.6
-
-## 3.0.5
-
-### Patch Changes
-
-- @objectstack/runtime@3.0.5
-
-## 3.0.4
-
-### Patch Changes
-
-- @objectstack/runtime@3.0.4
-
-## 3.0.3
-
-### Patch Changes
-
-- Updated dependencies [c7267f6]
-  - @objectstack/runtime@3.0.3

package/src/__mocks__/runtime.ts

@@ -1,4 +0,0 @@
-// Stub for @objectstack/runtime - replaced by vi.mock in tests
-export const HttpDispatcher = class {};
-export type ObjectKernel = any;
-export type HttpDispatcherResult = any;

package/src/index.ts

@@ -1,229 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import {
-  createRouter,
-  defineEventHandler,
-  getQuery,
-  readBody,
-  sendRedirect,
-  setResponseHeader,
-  setResponseStatus,
-  type H3Event,
-  type Router,
-} from 'h3';
-import { type ObjectKernel, HttpDispatcher, HttpDispatcherResult } from '@objectstack/runtime';
-
-export interface NuxtAdapterOptions {
-  kernel: ObjectKernel;
-  prefix?: string;
-}
-
-/**
- * Auth service interface with handleRequest method
- */
-interface AuthService {
-  handleRequest(request: Request): Promise<Response>;
-}
-
-/**
- * Creates an h3 router with all ObjectStack route dispatchers.
- * Designed for use in Nuxt server routes or standalone h3 apps.
- *
- * Only routes that need framework-specific handling (auth service, storage
- * file upload, GraphQL raw result, discovery wrapper) are registered explicitly.
- * All other routes are handled by a catch-all that delegates to
- * `HttpDispatcher.dispatch()`, making the adapter automatically support
- * new routes added to the dispatcher.
- *
- * @example
- * ```ts
- * // server/api/[...].ts
- * import { createH3Router } from '@objectstack/nuxt';
- * import { kernel } from '../kernel';
- *
- * const router = createH3Router({ kernel });
- * export default defineEventHandler(router.handler);
- * ```
- */
-export function createH3Router(options: NuxtAdapterOptions): Router {
-  const router = createRouter();
-  const dispatcher = new HttpDispatcher(options.kernel);
-  const prefix = options.prefix || '/api';
-
-  const errorJson = (event: H3Event, message: string, code: number = 500) => {
-    setResponseStatus(event, code);
-    return { success: false, error: { message, code } };
-  };
-
-  const toResponse = (event: H3Event, result: HttpDispatcherResult) => {
-    if (result.handled) {
-      if (result.response) {
-        if (result.response.headers) {
-          Object.entries(result.response.headers).forEach(([k, v]) =>
-            setResponseHeader(event, k, v as string),
-          );
-        }
-        setResponseStatus(event, result.response.status);
-        return result.response.body;
-      }
-      if (result.result) {
-        const res = result.result;
-        if (res.type === 'redirect' && res.url) {
-          return sendRedirect(event, res.url);
-        }
-        if (res.type === 'stream' && res.stream) {
-          if (res.headers) {
-            Object.entries(res.headers).forEach(([k, v]) =>
-              setResponseHeader(event, k, v as string),
-            );
-          }
-          return res.stream;
-        }
-        return res;
-      }
-    }
-    return errorJson(event, 'Not Found', 404);
-  };
-
-  // ─── Explicit routes (framework-specific handling required) ────────────────
-
-  // --- Discovery ---
-  router.get(
-    prefix,
-    defineEventHandler(async () => {
-      return { data: await dispatcher.getDiscoveryInfo(prefix) };
-    }),
-  );
-
-  router.get(
-    `${prefix}/discovery`,
-    defineEventHandler(async () => {
-      return { data: await dispatcher.getDiscoveryInfo(prefix) };
-    }),
-  );
-
-  // --- .well-known ---
-  router.get(
-    '/.well-known/objectstack',
-    defineEventHandler((event) => {
-      return sendRedirect(event, prefix);
-    }),
-  );
-
-  // --- Auth (needs auth service integration) ---
-  router.use(
-    `${prefix}/auth/**`,
-    defineEventHandler(async (event) => {
-      try {
-        const urlPath = event.path || event.node.req.url || '';
-        const path = urlPath.substring(`${prefix}/auth/`.length).split('?')[0];
-        const method = event.method;
-
-        // Try AuthPlugin service first (prefer async to support factory-based services)
-        let authService: AuthService | null = null;
-        try {
-          if (typeof options.kernel.getServiceAsync === 'function') {
-            authService = await options.kernel.getServiceAsync<AuthService>('auth');
-          } else if (typeof options.kernel.getService === 'function') {
-            authService = options.kernel.getService<AuthService>('auth');
-          }
-        } catch {
-          // Service not registered — fall through to dispatcher
-          authService = null;
-        }
-
-        if (authService && typeof authService.handleRequest === 'function') {
-          const host = event.node.req.headers.host || 'localhost';
-          const protocol = (event.node.req.socket as any)?.encrypted ? 'https' : 'http';
-          const url = `${protocol}://${host}${urlPath}`;
-          const headers = new Headers();
-          if (event.node.req.headers) {
-            Object.entries(event.node.req.headers).forEach(([k, v]) => {
-              if (typeof v === 'string') headers.set(k, v);
-              else if (Array.isArray(v)) headers.set(k, v.join(', '));
-            });
-          }
-          const init: RequestInit = { method, headers };
-          if (method !== 'GET' && method !== 'HEAD') {
-            const body = await readBody(event);
-            if (body) {
-              init.body = typeof body === 'string' ? body : JSON.stringify(body);
-              if (!headers.has('content-type')) {
-                headers.set('content-type', 'application/json');
-              }
-            }
-          }
-          const webRequest = new Request(url, init);
-          const response = await authService.handleRequest(webRequest);
-          setResponseStatus(event, response.status);
-          response.headers.forEach((v: string, k: string) => setResponseHeader(event, k, v));
-          return await response.text();
-        }
-
-        // Fallback to dispatcher
-        const body = method === 'GET' || method === 'HEAD'
-          ? {}
-          : await readBody(event).catch(() => ({}));
-        const result = await dispatcher.handleAuth(path, method, body, { request: event.node.req });
-        return toResponse(event, result);
-      } catch (err: any) {
-        return errorJson(event, err.message || 'Internal Server Error', err.statusCode || 500);
-      }
-    }),
-  );
-
-  // --- GraphQL (returns raw result, not HttpDispatcherResult) ---
-  router.post(
-    `${prefix}/graphql`,
-    defineEventHandler(async (event) => {
-      try {
-        const body = await readBody(event);
-        const result = await dispatcher.handleGraphQL(body, { request: event.node.req });
-        return result;
-      } catch (err: any) {
-        return errorJson(event, err.message || 'Internal Server Error', err.statusCode || 500);
-      }
-    }),
-  );
-
-  // --- Storage (needs multipart form parsing) ---
-  router.use(
-    `${prefix}/storage/**`,
-    defineEventHandler(async (event) => {
-      try {
-        const urlPath = (event.path || event.node.req.url || '').split('?')[0];
-        const subPath = urlPath.substring(`${prefix}/storage`.length);
-        const method = event.method;
-        const file = undefined; // File upload requires multipart parsing (e.g., formidable)
-        const result = await dispatcher.handleStorage(subPath, method, file, { request: event.node.req });
-        return toResponse(event, result);
-      } catch (err: any) {
-        return errorJson(event, err.message || 'Internal Server Error', err.statusCode || 500);
-      }
-    }),
-  );
-
-  // ─── Catch-all: delegate to dispatcher.dispatch() ─────────────────────────
-  // Handles meta, data, packages, analytics, automation, i18n, ui, openapi,
-  // custom API endpoints, and any future routes added to HttpDispatcher.
-  router.use(
-    `${prefix}/**`,
-    defineEventHandler(async (event) => {
-      try {
-        const urlPath = (event.path || event.node.req.url || '').split('?')[0];
-        const subPath = urlPath.substring(prefix.length);
-        const method = event.method;
-        const body = (method === 'POST' || method === 'PUT' || method === 'PATCH')
-          ? await readBody(event)
-          : undefined;
-        const query = getQuery(event);
-        const result = await dispatcher.dispatch(method, subPath, body, query, { request: event.node.req }, prefix);
-        return toResponse(event, result);
-      } catch (err: any) {
-        return errorJson(event, err.message || 'Internal Server Error', err.statusCode || 500);
-      }
-    }),
-  );
-
-  return router;
-}

package/src/nuxt.test.ts

@@ -1,144 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-
-// Mock dispatcher instance
-const mockDispatcher = {
-  getDiscoveryInfo: vi.fn().mockReturnValue({ version: '1.0', endpoints: [] }),
-  handleAuth: vi.fn().mockResolvedValue({ handled: true, response: { body: { ok: true }, status: 200 } }),
-  handleGraphQL: vi.fn().mockResolvedValue({ data: {} }),
-  handleStorage: vi.fn().mockResolvedValue({ handled: true, response: { body: {}, status: 200 } }),
-  dispatch: vi.fn().mockResolvedValue({ handled: true, response: { body: { success: true }, status: 200 } }),
-};
-
-vi.mock('@objectstack/runtime', () => {
-  return {
-    HttpDispatcher: function HttpDispatcher() {
-      return mockDispatcher;
-    },
-  };
-});
-
-import { createApp, toNodeListener, createEvent } from 'h3';
-import { createH3Router } from './index';
-import http from 'node:http';
-
-const mockKernel = { name: 'test-kernel' } as any;
-
-function createTestApp() {
-  const app = createApp();
-  const router = createH3Router({ kernel: mockKernel });
-  app.use(router);
-  return app;
-}
-
-async function makeRequest(app: any, url: string, method = 'GET', body?: any) {
-  const listener = toNodeListener(app);
-
-  return new Promise<{ status: number; body: any }>((resolve, reject) => {
-    const server = http.createServer(listener);
-    server.listen(0, () => {
-      const addr = server.address() as any;
-      const reqOpts: http.RequestOptions = {
-        hostname: 'localhost',
-        port: addr.port,
-        path: url,
-        method,
-        headers: body ? { 'Content-Type': 'application/json' } : {},
-      };
-      const req = http.request(reqOpts, (res) => {
-        let data = '';
-        res.on('data', (chunk) => { data += chunk; });
-        res.on('end', () => {
-          server.close();
-          try {
-            resolve({ status: res.statusCode || 500, body: JSON.parse(data) });
-          } catch {
-            resolve({ status: res.statusCode || 500, body: data });
-          }
-        });
-      });
-      req.on('error', (err) => { server.close(); reject(err); });
-      if (body) req.write(JSON.stringify(body));
-      req.end();
-    });
-  });
-}
-
-describe('createH3Router', () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  it('handles discovery endpoint', async () => {
-    const app = createTestApp();
-    const res = await makeRequest(app, '/api');
-    expect(res.status).toBe(200);
-    expect(res.body.data).toBeDefined();
-    expect(res.body.data.version).toBe('1.0');
-    expect(mockDispatcher.getDiscoveryInfo).toHaveBeenCalledWith('/api');
-  });
-
-  it('handles auth route', async () => {
-    const app = createTestApp();
-    const res = await makeRequest(app, '/api/auth/login', 'POST', { email: 'a@b.com' });
-    expect(res.status).toBe(200);
-    expect(res.body.ok).toBe(true);
-    expect(mockDispatcher.handleAuth).toHaveBeenCalled();
-  });
-
-  it('handles graphql route', async () => {
-    const app = createTestApp();
-    const body = { query: '{ objects { name } }' };
-    const res = await makeRequest(app, '/api/graphql', 'POST', body);
-    expect(res.status).toBe(200);
-    expect(res.body.data).toBeDefined();
-    expect(mockDispatcher.handleGraphQL).toHaveBeenCalled();
-  });
-
-  it('handles metadata route', async () => {
-    const app = createTestApp();
-    const res = await makeRequest(app, '/api/meta/objects');
-    expect(res.status).toBe(200);
-    expect(mockDispatcher.dispatch).toHaveBeenCalledWith(
-      'GET',
-      '/meta/objects',
-      undefined,
-      expect.any(Object),
-      expect.objectContaining({ request: expect.anything() }),
-      '/api',
-    );
-  });
-
-  it('handles data route', async () => {
-    const app = createTestApp();
-    const res = await makeRequest(app, '/api/data/account');
-    expect(res.status).toBe(200);
-    expect(mockDispatcher.dispatch).toHaveBeenCalledWith(
-      'GET',
-      '/data/account',
-      undefined,
-      expect.any(Object),
-      expect.objectContaining({ request: expect.anything() }),
-      '/api',
-    );
-  });
-
-  it('handles storage route', async () => {
-    const app = createTestApp();
-    const res = await makeRequest(app, '/api/storage/files');
-    expect(res.status).toBe(200);
-    expect(mockDispatcher.handleStorage).toHaveBeenCalled();
-  });
-
-  it('handles errors', async () => {
-    mockDispatcher.dispatch.mockRejectedValueOnce(
-      Object.assign(new Error('Forbidden'), { statusCode: 403 }),
-    );
-    const app = createTestApp();
-    const res = await makeRequest(app, '/api/data/account');
-    expect(res.status).toBe(403);
-    expect(res.body.success).toBe(false);
-    expect(res.body.error.message).toBe('Forbidden');
-  });
-});

package/tsconfig.json

@@ -1,26 +0,0 @@
-{
-  "extends": "../../../tsconfig.json",
-  "compilerOptions": {
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "lib": [
-      "ES2020",
-      "DOM",
-      "DOM.Iterable"
-    ],
-    "types": [
-      "node"
-    ]
-  },
-  "include": [
-    "src/**/*"
-  ],
-  "exclude": [
-    "node_modules",
-    "dist"
-  ]
-}

package/vitest.config.ts

@@ -1,16 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import { defineConfig } from 'vitest/config';
-import path from 'node:path';
-
-export default defineConfig({
-  test: {
-    globals: true,
-    environment: 'node',
-  },
-  resolve: {
-    alias: {
-      '@objectstack/runtime': path.resolve(__dirname, 'src/__mocks__/runtime.ts'),
-    },
-  },
-});