@useatlas/create 0.0.6 → 0.0.7

package/templates/nextjs-standalone/src/api/routes/slack.ts

@@ -1,17 +1,20 @@
 /**
  * Slack integration routes.
  *
- * - POST /api/slack/commands  — slash command handler (/atlas)
- * - POST /api/slack/events   — Events API (thread follow-ups, url_verification)
- * - GET  /api/slack/install   — OAuth install redirect
- * - GET  /api/slack/callback  — OAuth callback
+ * - POST /api/v1/slack/commands  — slash command handler (/atlas)
+ * - POST /api/v1/slack/events   — Events API (thread follow-ups, url_verification)
+ * - POST /api/v1/slack/interactions — Block action interactions
+ * - GET  /api/v1/slack/install   — OAuth install redirect
+ * - GET  /api/v1/slack/callback  — OAuth callback
  *
  * POST routes verify Slack request signatures. OAuth routes use Slack's
  * server-to-server code exchange. The slash command acks within 3 seconds
  * and processes the query asynchronously.
  */
 
-import { Hono } from "hono";
+import { OpenAPIHono, createRoute } from "@hono/zod-openapi";
+import { validationHook } from "./validation-hook";
+import { z } from "zod";
 import { executeAgentQuery } from "@atlas/api/lib/agent-query";
 import { createLogger } from "@atlas/api/lib/logger";
 import { checkRateLimit } from "@atlas/api/lib/auth/middleware";
@@ -23,10 +26,11 @@ import { getBotToken, saveInstallation } from "@atlas/api/lib/slack/store";
 import { getConversationId, setConversationId } from "@atlas/api/lib/slack/threads";
 import { createConversation, addMessage, getConversation, generateTitle } from "@atlas/api/lib/conversations";
 import { SENSITIVE_PATTERNS } from "@atlas/api/lib/security";
+import { ErrorSchema } from "./shared-schemas";
 
 const log = createLogger("slack");
 
-const slack = new Hono();
+const slack = new OpenAPIHono({ defaultHook: validationHook });
 
 // --- Verify Slack signature ---
 
@@ -60,12 +64,152 @@ function scrubError(message: string): string {
   return message;
 }
 
-// --- POST /api/slack/commands ---
+// ---------------------------------------------------------------------------
+// Route definitions
+// ---------------------------------------------------------------------------
 
-slack.post("/commands", async (c) => {
+const SlackCommandResponseSchema = z.object({
+  response_type: z.string(),
+  text: z.string(),
+});
+
+const SlackOkResponseSchema = z.object({
+  ok: z.boolean(),
+});
+
+const SlackEventResponseSchema = z.record(z.string(), z.unknown());
+
+const commandsRoute = createRoute({
+  method: "post",
+  path: "/commands",
+  tags: ["Slack"],
+  summary: "Slack slash command",
+  description:
+    "Handles Slack slash commands (/atlas). Acks within 3 seconds and processes the query asynchronously. " +
+    "Requires SLACK_SIGNING_SECRET. Request signature is verified via x-slack-signature header.",
+  responses: {
+    200: {
+      description: "Immediate acknowledgment (processing continues asynchronously)",
+      content: { "application/json": { schema: SlackCommandResponseSchema } },
+    },
+    401: {
+      description: "Invalid Slack signature",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+  },
+});
+
+const eventsRoute = createRoute({
+  method: "post",
+  path: "/events",
+  tags: ["Slack"],
+  summary: "Slack Events API",
+  description:
+    "Handles Slack Events API callbacks including url_verification challenges and thread follow-up messages. " +
+    "Bot messages are ignored to prevent loops. Request signature is verified via x-slack-signature header.",
+  responses: {
+    200: {
+      description: "Event acknowledged",
+      content: { "application/json": { schema: SlackEventResponseSchema } },
+    },
+    400: {
+      description: "Invalid JSON body",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+    401: {
+      description: "Invalid Slack signature",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+  },
+});
+
+const interactionsRoute = createRoute({
+  method: "post",
+  path: "/interactions",
+  tags: ["Slack"],
+  summary: "Slack block action interactions",
+  description:
+    "Handles Slack block_actions interactions (approve/deny action prompts). " +
+    "Acks immediately and processes the action asynchronously. " +
+    "Request signature is verified via x-slack-signature header.",
+  responses: {
+    200: {
+      description: "Interaction acknowledged",
+      content: { "application/json": { schema: SlackOkResponseSchema } },
+    },
+    400: {
+      description: "Missing or invalid payload",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+    401: {
+      description: "Invalid Slack signature",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+  },
+});
+
+const installRoute = createRoute({
+  method: "get",
+  path: "/install",
+  tags: ["Slack"],
+  summary: "Slack OAuth install redirect",
+  description:
+    "Redirects to the Slack OAuth authorization page. Requires SLACK_CLIENT_ID to be configured.",
+  responses: {
+    302: {
+      description: "Redirect to Slack OAuth authorization page",
+    },
+    501: {
+      description: "OAuth not configured",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+  },
+});
+
+const callbackRoute = createRoute({
+  method: "get",
+  path: "/callback",
+  tags: ["Slack"],
+  summary: "Slack OAuth callback",
+  description:
+    "Handles the OAuth callback from Slack, exchanges the code for a bot token, and saves the installation. " +
+    "Returns HTML on success or failure.",
+  request: {
+    query: z.object({
+      code: z.string().openapi({ description: "OAuth authorization code" }),
+      state: z.string().openapi({ description: "CSRF state parameter" }),
+    }),
+  },
+  responses: {
+    200: {
+      description: "Installation successful (HTML response)",
+      content: { "text/html": { schema: z.string() } },
+    },
+    400: {
+      description: "Invalid or expired state, or missing code",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+    500: {
+      description: "Installation failed (HTML response)",
+      content: { "text/html": { schema: z.string() } },
+    },
+    501: {
+      description: "OAuth not configured",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+
+// --- POST /api/v1/slack/commands ---
+
+slack.openapi(commandsRoute, async (c) => {
   const { valid, body } = await verifyRequest(c);
   if (!valid) {
-    return c.json({ error: "Invalid signature" }, 401);
+    return c.json({ error: "invalid_signature", message: "Invalid signature" }, 401);
   }
 
   const params = new URLSearchParams(body);
@@ -79,7 +223,7 @@ slack.post("/commands", async (c) => {
     return c.json({
       response_type: "ephemeral",
       text: "Usage: `/atlas <your question>`\nExample: `/atlas how many active users last month?`",
-    });
+    }, 200);
   }
 
   log.info({ channelId, userId, teamId, question: text.slice(0, 100) }, "Slash command received");
@@ -96,7 +240,7 @@ slack.post("/commands", async (c) => {
             await fetch(responseUrl, {
               method: "POST",
               headers: { "Content-Type": "application/json" },
-              body: JSON.stringify({ response_type: "ephemeral", text: "Atlas is not configured for this workspace. Ask an admin to install via /api/slack/install." }),
+              body: JSON.stringify({ response_type: "ephemeral", text: "Atlas is not configured for this workspace. Ask an admin to install via /api/v1/slack/install." }),
               signal: AbortSignal.timeout(10_000),
             });
           } catch (urlErr) {
@@ -209,12 +353,12 @@ slack.post("/commands", async (c) => {
   return c.json({
     response_type: "in_channel",
     text: `:hourglass_flowing_sand: Processing your question...`,
-  });
+  }, 200);
 });
 
-// --- POST /api/slack/events ---
+// --- POST /api/v1/slack/events ---
 
-slack.post("/events", async (c) => {
+slack.openapi(eventsRoute, async (c) => {
   const { valid, body } = await verifyRequest(c);
 
   let payload: Record<string, unknown>;
@@ -222,27 +366,27 @@ slack.post("/events", async (c) => {
     payload = JSON.parse(body);
   } catch (err) {
     log.warn({ err: err instanceof Error ? err.message : String(err) }, "Slack events received non-JSON body");
-    return c.json({ error: "Invalid JSON" }, 400);
+    return c.json({ error: "invalid_json", message: "Invalid JSON" }, 400);
   }
 
   if (!valid) {
-    return c.json({ error: "Invalid signature" }, 401);
+    return c.json({ error: "invalid_signature", message: "Invalid signature" }, 401);
   }
 
   // Handle url_verification challenge (signature verified above)
   if (payload.type === "url_verification") {
-    return c.json({ challenge: payload.challenge });
+    return c.json({ challenge: payload.challenge }, 200);
   }
 
   if (payload.type === "event_callback") {
     const event = payload.event as Record<string, unknown> | undefined;
     if (!event) {
-      return c.json({ ok: true });
+      return c.json({ ok: true }, 200);
     }
 
     // Ignore bot messages to prevent loops
     if (event.bot_id) {
-      return c.json({ ok: true });
+      return c.json({ ok: true }, 200);
     }
 
     const eventType = event.type as string;
@@ -365,34 +509,35 @@ slack.post("/events", async (c) => {
     }
   }
 
-  return c.json({ ok: true });
+  return c.json({ ok: true }, 200);
 });
 
-// --- POST /api/slack/interactions ---
+// --- POST /api/v1/slack/interactions ---
 
-slack.post("/interactions", async (c) => {
+slack.openapi(interactionsRoute, async (c) => {
   const { valid, body } = await verifyRequest(c);
   if (!valid) {
-    return c.json({ error: "Invalid signature" }, 401);
+    return c.json({ error: "invalid_signature", message: "Invalid signature" }, 401);
   }
 
   // Slack sends interactions as URL-encoded form with a "payload" JSON field
   const params = new URLSearchParams(body);
   const payloadStr = params.get("payload");
   if (!payloadStr) {
-    return c.json({ error: "Missing payload" }, 400);
+    return c.json({ error: "missing_payload", message: "Missing payload" }, 400);
   }
 
   let payload: Record<string, unknown>;
   try {
     payload = JSON.parse(payloadStr);
-  } catch {
-    return c.json({ error: "Invalid payload JSON" }, 400);
+  } catch (err) {
+    log.warn({ err: err instanceof Error ? err.message : String(err) }, "Failed to parse block_actions payload JSON");
+    return c.json({ error: "invalid_payload", message: "Invalid payload JSON" }, 400);
   }
 
   if (payload.type !== "block_actions") {
     log.debug({ type: payload.type }, "Acked non-block_actions Slack interaction type");
-    return c.json({ ok: true });
+    return c.json({ ok: true }, 200);
   }
 
   const actions = payload.actions as Array<{
@@ -401,7 +546,7 @@ slack.post("/interactions", async (c) => {
   }> | undefined;
 
   if (!actions?.length) {
-    return c.json({ ok: true });
+    return c.json({ ok: true }, 200);
   }
 
   const responseUrl = (payload.response_url as string) ?? "";
@@ -524,54 +669,62 @@ slack.post("/interactions", async (c) => {
     );
   });
 
-  return c.json({ ok: true });
+  return c.json({ ok: true }, 200);
 });
 
-// --- OAuth CSRF state ---
+// --- OAuth CSRF state (shared DB-backed store) ---
 
-const pendingOAuthStates = new Map<string, number>();
-setInterval(() => {
-  const now = Date.now();
-  for (const [state, expiry] of pendingOAuthStates) {
-    if (now > expiry) pendingOAuthStates.delete(state);
-  }
-}, 600_000).unref();
+import { saveOAuthState, consumeOAuthState } from "@atlas/api/lib/auth/oauth-state";
 
-// --- GET /api/slack/install ---
+// --- GET /api/v1/slack/install ---
 
-slack.get("/install", (c) => {
+slack.openapi(installRoute, async (c) => {
   const clientId = process.env.SLACK_CLIENT_ID;
   if (!clientId) {
-    return c.json({ error: "OAuth not configured" }, 501);
+    return c.json({ error: "oauth_not_configured", message: "OAuth not configured" }, 501);
+  }
+
+  // Extract orgId from session if available
+  let orgId: string | undefined;
+  try {
+    const authResult = c.get("authResult" as never) as
+      | { user?: { activeOrganizationId?: string } }
+      | undefined;
+    orgId = authResult?.user?.activeOrganizationId ?? undefined;
+  } catch (err) {
+    log.debug(
+      { err: err instanceof Error ? err.message : String(err) },
+      "authResult not available on Slack install route",
+    );
   }
 
   const state = crypto.randomUUID();
-  pendingOAuthStates.set(state, Date.now() + 600_000);
+  await saveOAuthState(state, { orgId, provider: "slack" });
 
   const scopes = "commands,chat:write,app_mentions:read";
   const url = `https://slack.com/oauth/v2/authorize?client_id=${clientId}&scope=${scopes}&state=${state}`;
   return c.redirect(url);
 });
 
-// --- GET /api/slack/callback ---
+// --- GET /api/v1/slack/callback ---
 
-slack.get("/callback", async (c) => {
+slack.openapi(callbackRoute, async (c) => {
   const clientId = process.env.SLACK_CLIENT_ID;
   const clientSecret = process.env.SLACK_CLIENT_SECRET;
 
   if (!clientId || !clientSecret) {
-    return c.json({ error: "OAuth not configured" }, 501);
+    return c.json({ error: "oauth_not_configured", message: "OAuth not configured" }, 501);
   }
 
   const state = c.req.query("state");
-  if (!state || !pendingOAuthStates.has(state)) {
-    return c.json({ error: "Invalid or expired state parameter" }, 400);
+  const oauthState = state ? await consumeOAuthState(state) : null;
+  if (!oauthState) {
+    return c.json({ error: "invalid_state", message: "Invalid or expired state parameter" }, 400);
   }
-  pendingOAuthStates.delete(state);
 
   const code = c.req.query("code");
   if (!code) {
-    return c.json({ error: "Missing code parameter" }, 400);
+    return c.json({ error: "missing_code", message: "Missing code parameter" }, 400);
   }
 
   const result = await slackAPI("oauth.v2.access", "", {
@@ -582,18 +735,22 @@ slack.get("/callback", async (c) => {
 
   if (!result.ok) {
     log.error({ error: result.error }, "OAuth exchange failed");
-    return c.json({ error: "OAuth failed" }, 400);
+    return c.json({ error: "oauth_failed", message: "OAuth failed" }, 400);
   }
 
   const data = result as unknown as Record<string, unknown>;
-  const team = data.team as { id?: string } | undefined;
+  const team = data.team as { id?: string; name?: string } | undefined;
   const accessToken = (data.access_token as string) ?? "";
   const teamId = team?.id ?? "";
+  const teamName = team?.name ?? null;
 
   if (teamId && accessToken) {
     try {
-      await saveInstallation(teamId, accessToken);
-      log.info({ teamId }, "Slack installation saved");
+      // Use orgId from the OAuth state (set during /install)
+      const orgId = oauthState.orgId;
+
+      await saveInstallation(teamId, accessToken, { orgId, workspaceName: teamName ?? undefined });
+      log.info({ teamId, orgId, teamName }, "Slack installation saved");
     } catch (saveErr) {
       log.error({ err: saveErr instanceof Error ? saveErr.message : String(saveErr), teamId }, "Failed to save Slack installation");
       return c.html("<html><body><h1>Installation Failed</h1><p>Could not save the installation. Please try again.</p></body></html>", 500);

package/templates/nextjs-standalone/src/api/routes/suggestions.ts

@@ -0,0 +1,233 @@
+/**
+ * User-facing query suggestion routes.
+ *
+ * GET  /api/v1/suggestions?table=<name>[&table=<name>][&limit=N]
+ *   — contextual suggestions for one or more tables, ordered by score DESC.
+ *
+ * GET  /api/v1/suggestions/popular[?limit=N]
+ *   — top suggestions across all tables, ordered by score DESC.
+ *
+ * POST /api/v1/suggestions/:id/click
+ *   — track engagement (fire-and-forget, always returns 204).
+ */
+
+import { OpenAPIHono, createRoute } from "@hono/zod-openapi";
+import { Effect } from "effect";
+import { runEffect } from "@atlas/api/lib/effect/hono";
+import { RequestContext, AuthContext } from "@atlas/api/lib/effect/services";
+import { validationHook } from "./validation-hook";
+import { z } from "zod";
+import { createLogger } from "@atlas/api/lib/logger";
+import {
+  hasInternalDB,
+  getSuggestionsByTables,
+  getPopularSuggestions,
+  incrementSuggestionClick,
+} from "@atlas/api/lib/db/internal";
+import { toQuerySuggestion } from "@atlas/api/lib/learn/suggestion-helpers";
+import { ErrorSchema, parsePagination } from "./shared-schemas";
+import { standardAuth, requestContext, type AuthEnv } from "./middleware";
+
+const log = createLogger("suggestions");
+
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+
+const SuggestionsResponseSchema = z.object({
+  suggestions: z.array(z.record(z.string(), z.unknown())),
+  total: z.number().int(),
+});
+
+
+// ---------------------------------------------------------------------------
+// Route definitions
+// ---------------------------------------------------------------------------
+
+const listSuggestionsRoute = createRoute({
+  method: "get",
+  path: "/",
+  tags: ["Suggestions"],
+  summary: "Get contextual suggestions",
+  description:
+    "Returns query suggestions for one or more tables, ordered by score. Requires at least one 'table' query parameter.",
+  request: {
+    query: z.object({
+      // `table` is intentionally omitted — it's a repeatable array param (?table=a&table=b)
+      // that Zod's string() can't validate. Parsed manually via c.req.queries("table").
+      limit: z.string().optional().openapi({
+        param: { name: "limit", in: "query" },
+        description: "Maximum number of suggestions to return (1-50, default 10).",
+        example: "10",
+      }),
+    }),
+  },
+  responses: {
+    200: {
+      description: "List of suggestions",
+      content: { "application/json": { schema: SuggestionsResponseSchema } },
+    },
+    400: {
+      description: "Missing table parameter",
+      content: { "application/json": { schema: z.object({ error: z.string() }) } },
+    },
+    401: {
+      description: "Authentication required",
+      content: { "application/json": { schema: z.record(z.string(), z.unknown()) } },
+    },
+    403: {
+      description: "Forbidden — insufficient permissions",
+      content: { "application/json": { schema: z.record(z.string(), z.unknown()) } },
+    },
+    429: {
+      description: "Rate limit exceeded",
+      content: { "application/json": { schema: z.record(z.string(), z.unknown()) } },
+    },
+    500: {
+      description: "Internal server error",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+  },
+});
+
+const listPopularRoute = createRoute({
+  method: "get",
+  path: "/popular",
+  tags: ["Suggestions"],
+  summary: "Get popular suggestions",
+  description:
+    "Returns the top query suggestions across all tables, ordered by score.",
+  request: {
+    query: z.object({
+      limit: z.string().optional().openapi({
+        param: { name: "limit", in: "query" },
+        description: "Maximum number of suggestions to return (1-50, default 10).",
+        example: "10",
+      }),
+    }),
+  },
+  responses: {
+    200: {
+      description: "List of popular suggestions",
+      content: { "application/json": { schema: SuggestionsResponseSchema } },
+    },
+    401: {
+      description: "Authentication required",
+      content: { "application/json": { schema: z.record(z.string(), z.unknown()) } },
+    },
+    403: {
+      description: "Forbidden — insufficient permissions",
+      content: { "application/json": { schema: z.record(z.string(), z.unknown()) } },
+    },
+    429: {
+      description: "Rate limit exceeded",
+      content: { "application/json": { schema: z.record(z.string(), z.unknown()) } },
+    },
+    500: {
+      description: "Internal server error",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+  },
+});
+
+const trackClickRoute = createRoute({
+  method: "post",
+  path: "/{id}/click",
+  tags: ["Suggestions"],
+  summary: "Track suggestion click",
+  description:
+    "Tracks user engagement with a suggestion. Fire-and-forget — always returns 204 on success.",
+  request: {
+    params: z.object({
+      id: z.string().openapi({ param: { name: "id", in: "path" }, example: "suggestion-id" }),
+    }),
+  },
+  responses: {
+    204: {
+      description: "Click tracked (fire-and-forget)",
+    },
+    401: {
+      description: "Authentication required",
+      content: { "application/json": { schema: z.record(z.string(), z.unknown()) } },
+    },
+    403: {
+      description: "Forbidden — insufficient permissions",
+      content: { "application/json": { schema: z.record(z.string(), z.unknown()) } },
+    },
+    429: {
+      description: "Rate limit exceeded",
+      content: { "application/json": { schema: z.record(z.string(), z.unknown()) } },
+    },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Router
+// ---------------------------------------------------------------------------
+
+export const suggestions = new OpenAPIHono<AuthEnv>({ defaultHook: validationHook });
+
+suggestions.use(standardAuth);
+suggestions.use(requestContext);
+
+// GET / — contextual suggestions by table
+suggestions.openapi(listSuggestionsRoute, async (c) => {
+  return runEffect(c, Effect.gen(function* () {
+    const { orgId } = yield* AuthContext;
+
+    if (!hasInternalDB()) {
+      return c.json({ suggestions: [], total: 0 }, 200);
+    }
+
+    const tables = c.req.queries("table") ?? [];
+    if (tables.length === 0) {
+      return c.json({ error: "At least one 'table' query parameter is required" }, { status: 400 });
+    }
+
+    const { limit } = parsePagination(c, { limit: 10, maxLimit: 50 });
+    const resolvedOrgId = orgId ?? null;
+
+    const rows = yield* Effect.promise(() => getSuggestionsByTables(resolvedOrgId, tables, limit));
+    return c.json({ suggestions: rows.map(toQuerySuggestion), total: rows.length }, 200);
+  }), { label: "fetch suggestions" });
+});
+
+// GET /popular — top suggestions across all tables
+suggestions.openapi(listPopularRoute, async (c) => {
+  return runEffect(c, Effect.gen(function* () {
+    const { orgId } = yield* AuthContext;
+
+    if (!hasInternalDB()) {
+      return c.json({ suggestions: [], total: 0 }, 200);
+    }
+
+    const { limit } = parsePagination(c, { limit: 10, maxLimit: 50 });
+    const resolvedOrgId = orgId ?? null;
+
+    const rows = yield* Effect.promise(() => getPopularSuggestions(resolvedOrgId, limit));
+    return c.json({ suggestions: rows.map(toQuerySuggestion), total: rows.length }, 200);
+  }), { label: "fetch suggestions" });
+});
+
+// POST /:id/click — track engagement
+suggestions.openapi(trackClickRoute, async (c) => {
+  return runEffect(c, Effect.gen(function* () {
+    const { requestId } = yield* RequestContext;
+    const { orgId } = yield* AuthContext;
+
+    const resolvedOrgId = orgId ?? null;
+    const { id } = c.req.valid("param");
+
+    // Fire-and-forget: always return 204
+    try {
+      incrementSuggestionClick(id, resolvedOrgId);
+    } catch (err) {
+      log.warn(
+        { err: err instanceof Error ? err.message : String(err), requestId },
+        "Click tracking failed",
+      );
+    }
+
+    return c.body(null, 204);
+  }), { label: "track suggestion click" });
+});