@etus/bhono-app 0.1.1

package/templates/base/src/server/routes/invitations/index.ts

@@ -0,0 +1,25 @@
+// src/routes/invitations/index.ts
+import { OpenAPIHono } from '@hono/zod-openapi'
+import type { HonoEnv } from '../../types'
+import { requireRole } from '../../auth/guards'
+import {
+  createInvitationRoute,
+  listInvitationsRoute,
+  revokeInvitationRoute,
+} from './routes'
+import {
+  createInvitationHandler,
+  listInvitationsHandler,
+  revokeInvitationHandler,
+} from './handlers'
+
+const invitationsRouter = new OpenAPIHono<HonoEnv>()
+
+// All routes require MANAGER or ADMIN
+invitationsRouter.use('/*', requireRole('MANAGER'))
+
+invitationsRouter.openapi(createInvitationRoute, createInvitationHandler)
+invitationsRouter.openapi(listInvitationsRoute, listInvitationsHandler)
+invitationsRouter.openapi(revokeInvitationRoute, revokeInvitationHandler)
+
+export { invitationsRouter }

package/templates/base/src/server/routes/invitations/routes.ts

@@ -0,0 +1,69 @@
+// src/routes/invitations/routes.ts
+import { createRoute, z } from '@hono/zod-openapi'
+import {
+  CreateInvitationSchema,
+  InvitationResultSchema,
+  InvitationsListSchema,
+} from './schemas'
+import { ErrorResponseSchema, IdParamSchema } from '../schemas'
+
+export const createInvitationRoute = createRoute({
+  method: 'post',
+  path: '/',
+  tags: ['Invitations'],
+  summary: 'Create invitation or link existing user',
+  description: 'Invites a new user via email or links an existing user immediately',
+  request: {
+    body: {
+      content: { 'application/json': { schema: CreateInvitationSchema } },
+    },
+  },
+  responses: {
+    200: {
+      description: 'User linked or invitation sent',
+      content: { 'application/json': { schema: InvitationResultSchema } },
+    },
+    403: {
+      description: 'Cannot assign role higher than own',
+      content: { 'application/json': { schema: ErrorResponseSchema } },
+    },
+    409: {
+      description: 'User already in account or pending invitation exists',
+      content: { 'application/json': { schema: ErrorResponseSchema } },
+    },
+  },
+})
+
+export const listInvitationsRoute = createRoute({
+  method: 'get',
+  path: '/',
+  tags: ['Invitations'],
+  summary: 'List pending invitations',
+  description: 'Lists all pending (not accepted, not expired) invitations for the account',
+  responses: {
+    200: {
+      description: 'List of pending invitations',
+      content: { 'application/json': { schema: z.object({ data: InvitationsListSchema }) } },
+    },
+  },
+})
+
+export const revokeInvitationRoute = createRoute({
+  method: 'delete',
+  path: '/{id}',
+  tags: ['Invitations'],
+  summary: 'Revoke invitation',
+  description: 'Cancels a pending invitation',
+  request: {
+    params: IdParamSchema,
+  },
+  responses: {
+    204: {
+      description: 'Invitation revoked',
+    },
+    404: {
+      description: 'Invitation not found',
+      content: { 'application/json': { schema: ErrorResponseSchema } },
+    },
+  },
+})

package/templates/base/src/server/routes/invitations/schemas.ts

@@ -0,0 +1,39 @@
+// src/routes/invitations/schemas.ts
+import { z } from '@hono/zod-openapi'
+
+export const CreateInvitationSchema = z.object({
+  email: z.email().openapi({ description: 'Email address to invite' }),
+  role: z.enum(['ADMIN', 'MANAGER', 'EDITOR', 'AUTHOR', 'VIEWER', 'BILLING', 'ANALYTICS']).openapi({
+    description: 'Role to assign (cannot exceed your own role)',
+  }),
+})
+
+export const InvitationSchema = z.object({
+  id: z.string(),
+  email: z.email(),
+  role: z.string(),
+  expiresAt: z.string(),
+  createdAt: z.string(),
+  invitedBy: z.object({
+    id: z.string(),
+    name: z.string(),
+  }),
+})
+
+export const InvitationResultSchema = z.object({
+  linked: z.boolean(),
+  invited: z.boolean(),
+  user: z.object({
+    id: z.string(),
+    email: z.string(),
+    name: z.string(),
+  }).optional(),
+  invitation: z.object({
+    id: z.string(),
+    email: z.string(),
+    role: z.string(),
+    expiresAt: z.string(),
+  }).optional(),
+})
+
+export const InvitationsListSchema = z.array(InvitationSchema)

package/templates/base/src/server/routes/openapi.ts

@@ -0,0 +1,14 @@
+// src/server/routes/openapi.ts
+
+export const openApiConfig = {
+  openapi: '3.0.0',
+  info: {
+    title: 'Hono Boilerplate API',
+    version: '1.0.0',
+    description: 'Multi-tenant API with role-based access control. Uses session-based authentication via cookies. Login via /auth/login to start a session.',
+  },
+  servers: [
+    { url: 'http://localhost:3000', description: 'Development server' },
+  ],
+  security: [{ SessionCookie: [] }],
+} as const

package/templates/base/src/server/routes/schemas.ts

@@ -0,0 +1,53 @@
+import { z } from '@hono/zod-openapi'
+
+// Error response schema
+export const ErrorResponseSchema = z
+  .object({
+    error: z.string().openapi({ example: 'Error message' }),
+    statusCode: z.number().openapi({ example: 400 }),
+    details: z.unknown().optional(),
+  })
+  .openapi('ErrorResponse')
+
+// Pagination meta schema
+export const PaginationMetaSchema = z
+  .object({
+    currentPage: z.number().openapi({ example: 1 }),
+    limit: z.number().openapi({ example: 50 }),
+    totalItems: z.number().openapi({ example: 100 }),
+    totalPages: z.number().openapi({ example: 2 }),
+    hasPreviousPage: z.boolean().openapi({ example: false }),
+    hasNextPage: z.boolean().openapi({ example: true }),
+  })
+  .openapi('PaginationMeta')
+
+// Pagination query schema
+export const PaginationQuerySchema = z.object({
+  page: z.coerce.number().min(1).default(1).openapi({ example: 1 }),
+  limit: z.coerce.number().min(1).max(100).default(50).openapi({ example: 50 }),
+  sortBy: z.string().optional().openapi({ example: 'createdAt' }),
+  sortOrder: z.enum(['ASC', 'DESC']).default('DESC').openapi({ example: 'DESC' }),
+  query: z.string().optional().openapi({ example: 'search term' }),
+})
+
+// Create paginated response schema factory
+export const createPaginatedSchema = <T extends z.ZodType>(
+  itemSchema: T,
+  name: string
+) =>
+  z
+    .object({
+      data: z.array(itemSchema),
+      meta: PaginationMetaSchema,
+    })
+    .openapi(`Paginated${name}`)
+
+// UUID param schema
+export const IdParamSchema = z.object({
+  id: z.uuid().openapi({ example: '550e8400-e29b-41d4-a716-446655440000' }),
+})
+
+// Account header schema
+export const AccountHeaderSchema = z.object({
+  'account-id': z.uuid().openapi({ example: '550e8400-e29b-41d4-a716-446655440000' }),
+})

package/templates/base/src/server/routes/storage/__tests__/handlers.test.ts

@@ -0,0 +1,408 @@
+// src/server/routes/storage/__tests__/handlers.test.ts
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { Hono } from 'hono'
+import type { HonoEnv } from '../../../types'
+import { storage } from '../index'
+import { createMockEnv } from '../../../__tests__/setup'
+import { createUserFixture, createAccountFixture } from '../../../__tests__/fixtures'
+
+// Mock the r2-storage lib
+vi.mock('../../../lib/r2-storage', () => ({
+  generateUploadUrl: vi.fn(),
+  uploadFile: vi.fn(),
+  deleteFile: vi.fn(),
+  getFileMetadata: vi.fn(),
+}))
+
+import {
+  generateUploadUrl,
+  uploadFile,
+  deleteFile,
+  getFileMetadata,
+} from '../../../lib/r2-storage'
+
+// Test UUIDs
+const TEST_USER_ID = '550e8400-e29b-41d4-a716-446655440001'
+const TEST_ACCOUNT_ID = '550e8400-e29b-41d4-a716-446655440101'
+
+describe('Storage Routes', () => {
+  let mockEnv: ReturnType<typeof createMockEnv>
+  let mockDb: any
+  let testUser: ReturnType<typeof createUserFixture>
+  let testAccount: ReturnType<typeof createAccountFixture>
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockEnv = createMockEnv()
+
+    testUser = createUserFixture({ id: TEST_USER_ID, email: 'test@example.com' })
+    testAccount = createAccountFixture({ id: TEST_ACCOUNT_ID })
+
+    // Create mock database
+    mockDb = {
+      select: vi.fn().mockReturnThis(),
+      from: vi.fn().mockReturnThis(),
+      where: vi.fn().mockReturnThis(),
+      limit: vi.fn().mockResolvedValue([]),
+      insert: vi.fn().mockReturnThis(),
+      values: vi.fn().mockReturnThis(),
+      returning: vi.fn().mockResolvedValue([]),
+      execute: vi.fn().mockResolvedValue({ rows: [] }),
+    }
+  })
+
+  // Helper to setup authenticated app with specific role
+  function setupAuthenticatedApp(userRole = 'AUTHOR', isSuperAdmin = false) {
+    const app = new Hono<HonoEnv>()
+
+    app.use('*', async (c, next) => {
+      ;(c as any).env = mockEnv
+      c.set('db', mockDb)
+      c.set('transactionId', 'test-transaction-id')
+      c.set('ip', '127.0.0.1')
+      c.set('userAgent', 'TestAgent/1.0')
+      c.set('user', { ...testUser, isSuperAdmin })
+      c.set('accountId', testAccount.id)
+      c.set('userRole', userRole)
+      c.set('isSystemAdminAccess', isSuperAdmin)
+      await next()
+    })
+
+    app.route('/storage', storage)
+    return app
+  }
+
+  // Helper to setup app without R2 configured
+  function setupAppWithoutR2(userRole = 'AUTHOR') {
+    const app = new Hono<HonoEnv>()
+    const envWithoutR2 = { ...mockEnv, R2_BUCKET: undefined }
+
+    app.use('*', async (c, next) => {
+      ;(c as any).env = envWithoutR2
+      c.set('db', mockDb)
+      c.set('transactionId', 'test-transaction-id')
+      c.set('ip', '127.0.0.1')
+      c.set('userAgent', 'TestAgent/1.0')
+      c.set('user', testUser)
+      c.set('accountId', testAccount.id)
+      c.set('userRole', userRole)
+      c.set('isSystemAdminAccess', false)
+      await next()
+    })
+
+    app.route('/storage', storage)
+    return app
+  }
+
+  describe('POST /storage/upload-url (generateUploadUrlHandler)', () => {
+    it('should return upload URL', async () => {
+      const mockResult = {
+        url: '/api/storage/upload/images%2F1703123456789-test.jpg',
+        name: 'images/1703123456789-test.jpg',
+        publicUrl: 'https://r2-test.example.com/images/1703123456789-test.jpg',
+      }
+
+      vi.mocked(generateUploadUrl).mockReturnValue(mockResult)
+
+      const app = setupAuthenticatedApp('AUTHOR')
+
+      const res = await app.request('/storage/upload-url', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          filename: 'images/test.jpg',
+          contentType: 'image/jpeg',
+        }),
+      })
+
+      expect(res.status).toBe(200)
+      const body = await res.json()
+      expect(body.url).toBe(mockResult.url)
+      expect(body.name).toBe(mockResult.name)
+      expect(body.publicUrl).toBe(mockResult.publicUrl)
+      expect(generateUploadUrl).toHaveBeenCalledWith(
+        mockEnv.R2_BUCKET,
+        mockEnv.R2_PUBLIC_URL,
+        'images/test.jpg',
+        'image/jpeg'
+      )
+    })
+
+    it('should throw ValidationError when R2 not configured', async () => {
+      const app = setupAppWithoutR2('AUTHOR')
+
+      const res = await app.request('/storage/upload-url', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          filename: 'test.jpg',
+          contentType: 'image/jpeg',
+        }),
+      })
+
+      expect(res.status).toBe(400)
+      const body = await res.text()
+      expect(body).toContain('R2 storage is not configured')
+    })
+
+    it('should require AUTHOR role or higher', async () => {
+      const app = setupAuthenticatedApp('VIEWER')
+
+      const res = await app.request('/storage/upload-url', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          filename: 'test.jpg',
+          contentType: 'image/jpeg',
+        }),
+      })
+
+      expect(res.status).toBe(403)
+    })
+
+    it('should allow EDITOR role', async () => {
+      const mockResult = {
+        url: '/api/storage/upload/test.jpg',
+        name: 'test.jpg',
+        publicUrl: 'https://r2-test.example.com/test.jpg',
+      }
+
+      vi.mocked(generateUploadUrl).mockReturnValue(mockResult)
+
+      const app = setupAuthenticatedApp('EDITOR')
+
+      const res = await app.request('/storage/upload-url', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          filename: 'test.jpg',
+          contentType: 'image/jpeg',
+        }),
+      })
+
+      expect(res.status).toBe(200)
+    })
+  })
+
+  describe('PUT /storage/upload/{key} (uploadFileHandler)', () => {
+    it('should upload file successfully', async () => {
+      const mockR2Object = {
+        key: 'images/test.jpg',
+        size: 100,
+        httpEtag: '"abc123"',
+        uploaded: new Date(),
+      }
+
+      vi.mocked(uploadFile).mockResolvedValue(mockR2Object as any)
+
+      const app = setupAuthenticatedApp('AUTHOR')
+
+      const fileContent = new Uint8Array([0x89, 0x50, 0x4e, 0x47]) // PNG magic bytes
+      const res = await app.request('/storage/upload/images%2Ftest.jpg', {
+        method: 'PUT',
+        headers: {
+          'Content-Type': 'image/png',
+        },
+        body: fileContent,
+      })
+
+      expect(res.status).toBe(200)
+      const body = await res.json()
+      expect(body.success).toBe(true)
+      expect(body.key).toBe('images/test.jpg')
+      expect(body.publicUrl).toContain('images/test.jpg')
+      expect(uploadFile).toHaveBeenCalledWith(
+        mockEnv.R2_BUCKET,
+        'images/test.jpg',
+        expect.any(ArrayBuffer),
+        'image/png'
+      )
+    })
+
+    it('should throw ValidationError for empty body', async () => {
+      const app = setupAuthenticatedApp('AUTHOR')
+
+      const res = await app.request('/storage/upload/test.jpg', {
+        method: 'PUT',
+        headers: {
+          'Content-Type': 'image/jpeg',
+        },
+        body: new Uint8Array(0), // Empty body
+      })
+
+      expect(res.status).toBe(400)
+      const body = await res.text()
+      expect(body).toContain('Request body is empty')
+    })
+
+    it('should throw ValidationError when R2 not configured', async () => {
+      const app = setupAppWithoutR2('AUTHOR')
+
+      const fileContent = new Uint8Array([0x89, 0x50, 0x4e, 0x47])
+      const res = await app.request('/storage/upload/test.jpg', {
+        method: 'PUT',
+        headers: {
+          'Content-Type': 'image/png',
+        },
+        body: fileContent,
+      })
+
+      expect(res.status).toBe(400)
+      const body = await res.text()
+      expect(body).toContain('R2 storage is not configured')
+    })
+
+    it('should decode URL-encoded keys', async () => {
+      const mockR2Object = {
+        key: 'path/with spaces/file.jpg',
+        size: 100,
+        httpEtag: '"abc123"',
+        uploaded: new Date(),
+      }
+
+      vi.mocked(uploadFile).mockResolvedValue(mockR2Object as any)
+
+      const app = setupAuthenticatedApp('AUTHOR')
+
+      const fileContent = new Uint8Array([0x89, 0x50, 0x4e, 0x47])
+      const res = await app.request('/storage/upload/path%2Fwith%20spaces%2Ffile.jpg', {
+        method: 'PUT',
+        headers: {
+          'Content-Type': 'image/jpeg',
+        },
+        body: fileContent,
+      })
+
+      expect(res.status).toBe(200)
+      expect(uploadFile).toHaveBeenCalledWith(
+        mockEnv.R2_BUCKET,
+        'path/with spaces/file.jpg',
+        expect.any(ArrayBuffer),
+        'image/jpeg'
+      )
+    })
+  })
+
+  describe('DELETE /storage/{key} (deleteFileHandler)', () => {
+    it('should delete file', async () => {
+      const mockMetadata = {
+        key: 'test.jpg',
+        size: 100,
+        httpEtag: '"abc123"',
+        uploaded: new Date(),
+      }
+
+      vi.mocked(getFileMetadata).mockResolvedValue(mockMetadata as any)
+      vi.mocked(deleteFile).mockResolvedValue()
+
+      const app = setupAuthenticatedApp('EDITOR')
+
+      const res = await app.request('/storage/test.jpg', {
+        method: 'DELETE',
+      })
+
+      expect(res.status).toBe(204)
+      expect(getFileMetadata).toHaveBeenCalledWith(mockEnv.R2_BUCKET, 'test.jpg')
+      expect(deleteFile).toHaveBeenCalledWith(mockEnv.R2_BUCKET, 'test.jpg')
+    })
+
+    it('should throw NotFoundError for non-existent file', async () => {
+      vi.mocked(getFileMetadata).mockResolvedValue(null)
+
+      const app = setupAuthenticatedApp('EDITOR')
+
+      const res = await app.request('/storage/non-existent.jpg', {
+        method: 'DELETE',
+      })
+
+      expect(res.status).toBe(404)
+      const body = await res.text()
+      expect(body).toContain('not found')
+    })
+
+    it('should throw ValidationError when R2 not configured', async () => {
+      const app = setupAppWithoutR2('EDITOR')
+
+      const res = await app.request('/storage/test.jpg', {
+        method: 'DELETE',
+      })
+
+      expect(res.status).toBe(400)
+      const body = await res.text()
+      expect(body).toContain('R2 storage is not configured')
+    })
+
+    // Note: Role-based access control (AUTHOR/VIEWER denied) is tested via
+    // the requireRole middleware which is tested separately in middleware/auth.test.ts
+
+    it('should allow super admin to delete files', async () => {
+      const mockMetadata = {
+        key: 'test.jpg',
+        size: 100,
+        httpEtag: '"abc123"',
+        uploaded: new Date(),
+      }
+
+      vi.mocked(getFileMetadata).mockResolvedValue(mockMetadata as any)
+      vi.mocked(deleteFile).mockResolvedValue()
+
+      const app = setupAuthenticatedApp('VIEWER', true)
+
+      const res = await app.request('/storage/test.jpg', {
+        method: 'DELETE',
+      })
+
+      expect(res.status).toBe(204)
+    })
+
+    it('should allow ADMIN role', async () => {
+      const mockMetadata = {
+        key: 'test.jpg',
+        size: 100,
+        httpEtag: '"abc123"',
+        uploaded: new Date(),
+      }
+
+      vi.mocked(getFileMetadata).mockResolvedValue(mockMetadata as any)
+      vi.mocked(deleteFile).mockResolvedValue()
+
+      const app = setupAuthenticatedApp('ADMIN')
+
+      const res = await app.request('/storage/test.jpg', {
+        method: 'DELETE',
+      })
+
+      expect(res.status).toBe(204)
+    })
+
+    it('should decode URL-encoded keys for deletion', async () => {
+      const mockMetadata = {
+        key: 'folder/sub folder/file.jpg',
+        size: 100,
+        httpEtag: '"abc123"',
+        uploaded: new Date(),
+      }
+
+      vi.mocked(getFileMetadata).mockResolvedValue(mockMetadata as any)
+      vi.mocked(deleteFile).mockResolvedValue()
+
+      const app = setupAuthenticatedApp('EDITOR')
+
+      const res = await app.request('/storage/folder%2Fsub%20folder%2Ffile.jpg', {
+        method: 'DELETE',
+      })
+
+      expect(res.status).toBe(204)
+      expect(getFileMetadata).toHaveBeenCalledWith(mockEnv.R2_BUCKET, 'folder/sub folder/file.jpg')
+      expect(deleteFile).toHaveBeenCalledWith(mockEnv.R2_BUCKET, 'folder/sub folder/file.jpg')
+    })
+  })
+})