@edge-base/server 0.2.5 → 0.2.6

package/src/routes/admin.ts

@@ -362,7 +362,7 @@ adminRoute.onError((err, c) => {
     return c.json(err.toJSON(), err.code as 400);
   }
   console.error('Admin Dashboard unhandled error:', err);
-  return c.json({ code: 500, message: 'Internal server error.' }, 500);
+  return c.json({ code: 500, message: 'Admin dashboard request failed unexpectedly. Check the worker logs for the original exception.' }, 500);
 });
 
 // ─────────────────────────────────────────────
@@ -2133,7 +2133,12 @@ api.openapi(adminImportTable, async (c) => {
       }
     } catch (err) {
       for (let j = 0; j < chunk.length; j++) {
-        errors.push({ row: i + j, message: err instanceof Error ? err.message : 'Unknown error' });
+        errors.push({
+          row: i + j,
+          message: err instanceof Error
+            ? err.message
+            : 'Import failed with an unexpected admin API error. Check worker logs for details.',
+        });
       }
     }
   }
@@ -3436,7 +3441,7 @@ api.openapi(adminDestroyApp, async (c) => {
       const label = `D1 ${r.name}`;
       const result = await cfApi(accountId, apiToken, 'DELETE', `/d1/database/${r.id}`);
       if (result.ok) deleted.push(label);
-      else failed.push({ resource: label, error: result.error ?? 'Unknown error' });
+      else failed.push({ resource: label, error: result.error ?? 'Unknown Cloudflare API error while deleting this resource.' });
     }
   }
 
@@ -3446,7 +3451,7 @@ api.openapi(adminDestroyApp, async (c) => {
       const label = `Vectorize ${indexName}`;
       const result = await cfApi(accountId, apiToken, 'DELETE', `/vectorize/v2/indexes/${indexName}`);
       if (result.ok) deleted.push(label);
-      else failed.push({ resource: label, error: result.error ?? 'Unknown error' });
+      else failed.push({ resource: label, error: result.error ?? 'Unknown Cloudflare API error while deleting this resource.' });
     }
   }
 
@@ -3455,7 +3460,7 @@ api.openapi(adminDestroyApp, async (c) => {
       const label = `Hyperdrive ${r.name}`;
       const result = await cfApi(accountId, apiToken, 'DELETE', `/hyperdrive/configs/${r.id}`);
       if (result.ok) deleted.push(label);
-      else failed.push({ resource: label, error: result.error ?? 'Unknown error' });
+      else failed.push({ resource: label, error: result.error ?? 'Unknown Cloudflare API error while deleting this resource.' });
     }
   }
 
@@ -3492,7 +3497,7 @@ api.openapi(adminDestroyApp, async (c) => {
       // Turnstile uses zone-level API, not account
       const result = await cfApi(accountId, apiToken, 'DELETE', `/challenges/widgets/${r.id}`);
       if (result.ok) deleted.push(label);
-      else failed.push({ resource: label, error: result.error ?? 'Unknown error' });
+      else failed.push({ resource: label, error: result.error ?? 'Unknown Cloudflare API error while deleting this resource.' });
     }
   }
 
@@ -3503,7 +3508,7 @@ api.openapi(adminDestroyApp, async (c) => {
     if (result.ok) {
       deleted.push(label);
     } else {
-      failed.push({ resource: label, error: result.error ?? 'Unknown error' });
+      failed.push({ resource: label, error: result.error ?? 'Unknown Cloudflare API error while deleting this resource.' });
     }
   }
 
@@ -3513,7 +3518,7 @@ api.openapi(adminDestroyApp, async (c) => {
       const label = `KV ${r.name}`;
       const result = await cfApi(accountId, apiToken, 'DELETE', `/storage/kv/namespaces/${r.id}`);
       if (result.ok) deleted.push(label);
-      else failed.push({ resource: label, error: result.error ?? 'Unknown error' });
+      else failed.push({ resource: label, error: result.error ?? 'Unknown Cloudflare API error while deleting this resource.' });
     }
   }
 

package/src/routes/analytics-api.ts

@@ -29,10 +29,10 @@ function requireServiceKey(c: { env: Env; req: { header: (name: string) => strin
   const constraintCtx = buildConstraintCtx(c.env as never, c.req);
   const { result } = validateKey(provided, 'analytics:*:*:*', config, c.env as never, undefined, constraintCtx);
   if (result === 'missing') {
-    throw new EdgeBaseError(403, 'Service Key required for analytics queries.');
+    throw new EdgeBaseError(403, 'X-EdgeBase-Service-Key is required for analytics queries.');
   }
   if (result === 'invalid') {
-    throw new EdgeBaseError(401, 'Invalid Service Key.');
+    throw new EdgeBaseError(401, 'Invalid X-EdgeBase-Service-Key for analytics queries.');
   }
 }
 
@@ -107,7 +107,7 @@ analyticsApi.openapi(trackEvents, async (c) => {
   try {
     body = await c.req.json();
   } catch {
-    throw new EdgeBaseError(400, 'Invalid JSON body.');
+    throw new EdgeBaseError(400, 'Invalid JSON body for analytics tracking. Send application/json with { events: [...] }.');
   }
 
   const events = body.events;

package/src/routes/auth.ts

@@ -1238,7 +1238,7 @@ authRoute.openapi(signinAnonymous, async (c) => {
 
     const user = await authService.getUserById(db, userId);
     if (user) {
-      syncUserPublic(c.env, c.executionCtx, userId, authService.buildPublicUserData(user));
+      await syncUserPublic(c.env, c.executionCtx, userId, authService.buildPublicUserData(user), true);
 
       return c.json({
         user: authService.sanitizeUser(user),

package/src/routes/backup.ts

@@ -86,7 +86,7 @@ backupRoute.onError((err, c) => {
     return c.json(err.toJSON(), err.code as 400);
   }
   console.error('Backup API error:', err);
-  return c.json({ code: 500, message: 'Internal server error.' }, 500);
+  return c.json({ code: 500, message: 'Backup operation failed unexpectedly. Check the worker logs for the original exception.' }, 500);
 });
 
 // ─── DO Name Helpers ───

package/src/routes/d1.ts

@@ -22,6 +22,10 @@ import { zodDefaultHook, d1BodySchema, jsonResponseSchema, errorResponseSchema }
 
 export const d1Route = new OpenAPIHono<HonoEnv>({ defaultHook: zodDefaultHook });
 
+function invalidD1JsonMessage(): string {
+  return 'Invalid JSON body. Send application/json with { query, params? }.';
+}
+
 /**
  * POST /api/d1/:database
  * Body: { query: string, params?: unknown[] }
@@ -51,12 +55,12 @@ d1Route.openapi(executeD1Query, async (c) => {
   try {
     body = await c.req.json();
   } catch {
-    return c.json({ code: 400, message: 'Invalid JSON body' }, 400);
+    return c.json({ code: 400, message: invalidD1JsonMessage() }, 400);
   }
 
   const { query, params } = body;
   if (!query || typeof query !== 'string') {
-    return c.json({ code: 400, message: 'query is required' }, 400);
+    return c.json({ code: 400, message: "Missing required field 'query'. Send the SQL string in the request body." }, 400);
   }
 
   // §2 Allowlist: validate database is declared in config
@@ -76,16 +80,19 @@ d1Route.openapi(executeD1Query, async (c) => {
     buildConstraintCtx(c.env, c.req),
   );
   if (skResult === 'missing') {
-    return c.json({ code: 403, message: 'Service Key required to access D1' }, 403);
+    return c.json({ code: 403, message: `X-EdgeBase-Service-Key is required to execute raw SQL on D1 database '${nameParam}'.` }, 403);
   }
   if (skResult === 'invalid') {
-    return c.json({ code: 401, message: 'Unauthorized. Invalid Service Key.' }, 401);
+    return c.json({ code: 401, message: `Invalid X-EdgeBase-Service-Key for D1 database '${nameParam}'.` }, 401);
   }
 
   // §1 Env type — dynamic binding access via type assertion
   const binding = (c.env as unknown as Record<string, unknown>)[d1Config.binding] as D1Database | undefined;
   if (!binding) {
-    return c.json({ code: 500, message: `D1 binding '${d1Config.binding}' not available.` }, 500);
+    return c.json({
+      code: 500,
+      message: `D1 binding '${d1Config.binding}' is unavailable. Check the binding name in edgebase.config.ts and wrangler.toml.`,
+    }, 500);
   }
 
   // Execute D1 query — all SQL allowed (DDL included), ? bind variables enforced
@@ -103,7 +110,7 @@ d1Route.openapi(executeD1Query, async (c) => {
       },
     });
   } catch (err) {
-    const message = err instanceof Error ? err.message : 'D1 query execution failed';
-    throw new EdgeBaseError(400, message);
+    const message = err instanceof Error ? err.message : 'Unknown D1 query error';
+    throw new EdgeBaseError(400, `D1 query failed for '${nameParam}': ${message}`);
   }
 });

package/src/routes/database-live.ts

@@ -26,6 +26,10 @@ import {
 
 export const databaseLiveRoute = new OpenAPIHono<HonoEnv>({ defaultHook: zodDefaultHook });
 
+function invalidDatabaseLiveJsonMessage(): string {
+  return 'Invalid JSON body for database-live broadcast. Send application/json with { channel, event, payload? }.';
+}
+
 const MAX_PENDING_PER_IP = 5;
 const PENDING_TTL_SECONDS = 60;
 const dbLiveQuerySchema = z.object({
@@ -269,15 +273,15 @@ databaseLiveRoute.openapi(databaseLiveBroadcast, async (c) => {
   try {
     body = await c.req.json();
   } catch {
-    return c.json({ code: 400, message: 'Invalid JSON body' }, 400);
+    return c.json({ code: 400, message: invalidDatabaseLiveJsonMessage() }, 400);
   }
 
   const { channel, event, payload } = body;
   if (!channel || typeof channel !== 'string') {
-    return c.json({ code: 400, message: 'channel is required' }, 400);
+    return c.json({ code: 400, message: "Missing required field 'channel' for database-live broadcast." }, 400);
   }
   if (!event || typeof event !== 'string') {
-    return c.json({ code: 400, message: 'event is required' }, 400);
+    return c.json({ code: 400, message: "Missing required field 'event' for database-live broadcast." }, 400);
   }
 
   // Service Key required AND validated
@@ -291,10 +295,10 @@ databaseLiveRoute.openapi(databaseLiveBroadcast, async (c) => {
     buildConstraintCtx(c.env, c.req),
   );
   if (skResult === 'missing') {
-    return c.json({ code: 403, message: 'Service Key required for server broadcast' }, 403);
+    return c.json({ code: 403, message: `X-EdgeBase-Service-Key is required to broadcast to database-live channel '${channel}'.` }, 403);
   }
   if (skResult === 'invalid') {
-    return c.json({ code: 401, message: 'Unauthorized. Invalid Service Key.' }, 401);
+    return c.json({ code: 401, message: `Invalid X-EdgeBase-Service-Key for database-live channel '${channel}'.` }, 401);
   }
 
   // Route broadcast through the DatabaseLiveDO hub
@@ -308,7 +312,10 @@ databaseLiveRoute.openapi(databaseLiveBroadcast, async (c) => {
   }));
 
   if (!doResponse.ok) {
-    return c.json({ code: doResponse.status, message: 'Broadcast failed' }, doResponse.status as 400 | 500);
+    return c.json({
+      code: doResponse.status,
+      message: `Broadcast to database-live channel '${channel}' failed for event '${event}'.`,
+    }, doResponse.status as 400 | 500);
   }
 
   return c.json({ ok: true });

package/src/routes/kv.ts

@@ -20,6 +20,14 @@ import { zodDefaultHook, kvBodySchema, jsonResponseSchema, errorResponseSchema }
 
 export const kvRoute = new OpenAPIHono<HonoEnv>({ defaultHook: zodDefaultHook });
 
+function invalidKvJsonMessage(): string {
+  return 'Invalid JSON body. Send application/json with a KV operation payload like { action, key, value }.';
+}
+
+function missingKvFieldMessage(field: string, action: string): string {
+  return `Missing required field '${field}' for KV action '${action}'.`;
+}
+
 function normalizeKvBindingError(action: string, error: unknown): EdgeBaseError {
   const message = error instanceof Error ? error.message : String(error);
   const lowered = message.toLowerCase();
@@ -75,12 +83,12 @@ kvRoute.openapi(kvOperation, async (c) => {
   try {
     body = await c.req.json();
   } catch {
-    return c.json({ code: 400, message: 'Invalid JSON body' }, 400);
+    return c.json({ code: 400, message: invalidKvJsonMessage() }, 400);
   }
 
   const { action } = body;
   if (!action || !['get', 'set', 'delete', 'list'].includes(action)) {
-    return c.json({ code: 400, message: "action must be one of: 'get', 'set', 'delete', 'list'" }, 400);
+    return c.json({ code: 400, message: "Invalid KV action. Expected one of: 'get', 'set', 'delete', 'list'." }, 400);
   }
 
   // §2 Allowlist: validate namespace is declared in config
@@ -105,28 +113,31 @@ kvRoute.openapi(kvOperation, async (c) => {
     buildConstraintCtx(c.env, c.req),
   );
   if (skResult === 'missing') {
-    return c.json({ code: 403, message: 'Service Key required to access KV' }, 403);
+    return c.json({ code: 403, message: `X-EdgeBase-Service-Key is required to access KV namespace '${nameParam}'.` }, 403);
   }
   if (skResult === 'invalid') {
-    return c.json({ code: 401, message: 'Unauthorized. Invalid Service Key.' }, 401);
+    return c.json({ code: 401, message: `Invalid X-EdgeBase-Service-Key for KV namespace '${nameParam}'.` }, 401);
   }
 
   // §1 Env type — dynamic binding access via type assertion
   const binding = (c.env as unknown as Record<string, unknown>)[kvConfig.binding] as KVNamespace | undefined;
   if (!binding) {
-    return c.json({ code: 500, message: `KV binding '${kvConfig.binding}' not available.` }, 500);
+    return c.json({
+      code: 500,
+      message: `KV binding '${kvConfig.binding}' is unavailable. Check the binding name in edgebase.config.ts and wrangler.toml.`,
+    }, 500);
   }
 
   // Execute KV operation
   switch (action) {
     case 'get': {
-      if (!body.key) return c.json({ code: 400, message: 'key is required for get' }, 400);
+      if (!body.key) return c.json({ code: 400, message: missingKvFieldMessage('key', 'get') }, 400);
       const value = await binding.get(body.key);
       return c.json({ value });
     }
     case 'set': {
-      if (!body.key) return c.json({ code: 400, message: 'key is required for set' }, 400);
-      if (body.value === undefined) return c.json({ code: 400, message: 'value is required for set' }, 400);
+      if (!body.key) return c.json({ code: 400, message: missingKvFieldMessage('key', 'set') }, 400);
+      if (body.value === undefined) return c.json({ code: 400, message: missingKvFieldMessage('value', 'set') }, 400);
       const putOptions: KVNamespacePutOptions = {};
       if (body.ttl) putOptions.expirationTtl = body.ttl;
       try {
@@ -137,7 +148,7 @@ kvRoute.openapi(kvOperation, async (c) => {
       return c.json({ ok: true });
     }
     case 'delete': {
-      if (!body.key) return c.json({ code: 400, message: 'key is required for delete' }, 400);
+      if (!body.key) return c.json({ code: 400, message: missingKvFieldMessage('key', 'delete') }, 400);
       try {
         await binding.delete(body.key);
       } catch (error) {
@@ -162,6 +173,6 @@ kvRoute.openapi(kvOperation, async (c) => {
       });
     }
     default:
-      return c.json({ code: 400, message: 'Unknown action' }, 400);
+      return c.json({ code: 400, message: `Unsupported KV action '${action}'.` }, 400);
   }
 });

package/src/routes/oauth.ts

@@ -86,7 +86,7 @@ oauthRoute.onError((err, c) => {
     return c.json(err.toJSON(), err.code as 400);
   }
   console.error('OAuth unhandled error:', err);
-  return c.json({ code: 500, message: 'OAuth error.' }, 500);
+  return c.json({ code: 500, message: 'OAuth flow failed unexpectedly. Check the worker logs for the original exception.' }, 500);
 });
 
 // ─── Helpers ───