fix: accept + in package versions

Author: danielroe

CONTRIBUTING.md

@@ -110,6 +110,59 @@ The connector will check your npm authentication, generate a connection token, a
 - We care about good types – never cast things to `any` 💪
 - Validate rather than just assert
 
+### Server API patterns
+
+#### Input validation with Valibot
+
+Use Valibot schemas from `#shared/schemas/` to validate API inputs. This ensures type safety and provides consistent error messages:
+
+```typescript
+import * as v from 'valibot'
+import { PackageRouteParamsSchema } from '#shared/schemas/package'
+
+// In your handler:
+const { packageName, version } = v.parse(PackageRouteParamsSchema, {
+  packageName: rawPackageName,
+  version: rawVersion,
+})
+```
+
+#### Error handling with `handleApiError`
+
+Use the `handleApiError` utility for consistent error handling in API routes. It re-throws H3 errors (like 404s) and wraps other errors with a fallback message:
+
+```typescript
+import { ERROR_NPM_FETCH_FAILED } from '#shared/utils/constants'
+
+try {
+  // API logic...
+} catch (error: unknown) {
+  handleApiError(error, {
+    statusCode: 502,
+    message: ERROR_NPM_FETCH_FAILED,
+  })
+}
+```
+
+#### URL parameter parsing with `parsePackageParams`
+
+Use `parsePackageParams` to extract package name and version from URL segments:
+
+```typescript
+const pkgParamSegments = getRouterParam(event, 'pkg')?.split('/') ?? []
+const { rawPackageName, rawVersion } = parsePackageParams(pkgParamSegments)
+```
+
+This handles patterns like `/pkg`, `/pkg/v/1.0.0`, `/@scope/pkg`, and `/@scope/pkg/v/1.0.0`.
+
+#### Constants
+
+Define error messages and other string constants in `#shared/utils/constants.ts` to ensure consistency across the codebase:
+
+```typescript
+export const ERROR_NPM_FETCH_FAILED = 'Failed to fetch package from npm registry.'
+```
+
 ### Import order
 
 1. Type imports first (`import type { ... }`)

server/api/registry/readme/[...pkg].get.ts

@@ -2,7 +2,7 @@ import * as v from 'valibot'
 import { PackageRouteParamsSchema } from '#shared/schemas/package'
 import {
   CACHE_MAX_AGE_ONE_HOUR,
-  ERROR_README_FETCH_FAILED,
+  NPM_MISSING_README_SENTINEL,
   ERROR_NPM_FETCH_FAILED,
 } from '#shared/utils/constants'
 
@@ -72,7 +72,7 @@ export default defineCachedEventHandler(
       }
 
       // If no README in packument, try fetching from jsdelivr (package tarball)
-      if (!readmeContent || readmeContent === ERROR_README_FETCH_FAILED) {
+      if (!readmeContent || readmeContent === NPM_MISSING_README_SENTINEL) {
         readmeContent = (await fetchReadmeFromJsdelivr(packageName, version)) ?? undefined
       }
 

shared/schemas/package.ts

@@ -16,12 +16,12 @@ export const PackageNameSchema = v.pipe(
 
 /**
  * Enforces a SemVer-like pattern to prevent directory traversal or complex injection attacks
- * includes: alphanumeric, dots, underscores, and dashes
+ * includes: alphanumeric, dots, underscores, dashes, and plus signs (for build metadata)
  */
 export const VersionSchema = v.pipe(
   v.string(),
   v.nonEmpty('Version is required'),
-  v.regex(/^[a-z0-9._-]+$/i, 'Invalid version format'),
+  v.regex(/^[a-z0-9._+-]+$/i, 'Invalid version format'),
 )
 
 /**

shared/utils/constants.ts

@@ -6,12 +6,11 @@ export const CACHE_MAX_AGE_ONE_YEAR = 60 * 60 * 24 * 365
 // API Strings
 export const NPM_REGISTRY = 'https://registry.npmjs.org'
 export const ERROR_PACKAGE_ANALYSIS_FAILED = 'Failed to analyze package.'
-export const ERROR_PACKAGE_VERSION_FAILED = 'Version is required.'
 export const ERROR_PACKAGE_VERSION_AND_FILE_FAILED = 'Version and file path are required.'
 export const ERROR_PACKAGE_REQUIREMENTS_FAILED =
   'Package name, version, and file path are required.'
 export const ERROR_FILE_LIST_FETCH_FAILED = 'Failed to fetch file list.'
 export const ERROR_CALC_INSTALL_SIZE_FAILED = 'Failed to calculate install size.'
-export const ERROR_README_FETCH_FAILED = 'ERROR: No README data found!'
+export const NPM_MISSING_README_SENTINEL = 'ERROR: No README data found!'
 export const ERROR_JSR_FETCH_FAILED = 'Failed to fetch package from JSR registry.'
 export const ERROR_NPM_FETCH_FAILED = 'Failed to fetch package from npm registry.'