feat: add 20 research API endpoints

app/api/research/albums/route.ts

@@ -0,0 +1,23 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { getResearchAlbumsHandler } from "@/lib/research/getResearchAlbumsHandler";
+
+/**
+ * OPTIONS /api/research/albums — CORS preflight.
+ *
+ * @returns CORS-enabled 200 response
+ */
+export async function OPTIONS() {
+  return new NextResponse(null, { status: 200, headers: getCorsHeaders() });
+}
+
+/**
+ * GET /api/research/albums — Album discography for a Chartmetric artist id.
+ * Discovery by name is the caller's job via `GET /api/research`.
+ *
+ * @param request - must include numeric `artist_id` query param
+ * @returns JSON album list or error
+ */
+export async function GET(request: NextRequest) {
+  return getResearchAlbumsHandler(request);
+}

app/api/research/audience/route.ts

@@ -0,0 +1,22 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { getResearchAudienceHandler } from "@/lib/research/getResearchAudienceHandler";
+
+/**
+ * OPTIONS /api/research/audience — CORS preflight.
+ *
+ * @returns CORS-enabled 200 response
+ */
+export async function OPTIONS() {
+  return new NextResponse(null, { status: 200, headers: getCorsHeaders() });
+}
+
+/**
+ * GET /api/research/audience — Audience demographics by platform. Requires `?artist=` query param.
+ *
+ * @param request - must include `artist` query param
+ * @returns JSON audience demographics or error
+ */
+export async function GET(request: NextRequest) {
+  return getResearchAudienceHandler(request);
+}

app/api/research/career/route.ts

@@ -0,0 +1,22 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { getResearchCareerHandler } from "@/lib/research/getResearchCareerHandler";
+
+/**
+ * OPTIONS /api/research/career — CORS preflight.
+ *
+ * @returns CORS-enabled 200 response
+ */
+export async function OPTIONS() {
+  return new NextResponse(null, { status: 200, headers: getCorsHeaders() });
+}
+
+/**
+ * GET /api/research/career — Artist career history and milestones. Requires `?artist=` query param.
+ *
+ * @param request - must include `artist` query param
+ * @returns JSON career timeline or error
+ */
+export async function GET(request: NextRequest) {
+  return getResearchCareerHandler(request);
+}

app/api/research/charts/route.ts

@@ -0,0 +1,22 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { getResearchChartsHandler } from "@/lib/research/getResearchChartsHandler";
+
+/**
+ * OPTIONS /api/research/charts — CORS preflight.
+ *
+ * @returns CORS-enabled 200 response
+ */
+export async function OPTIONS() {
+  return new NextResponse(null, { status: 200, headers: getCorsHeaders() });
+}
+
+/**
+ * GET /api/research/charts — Global chart positions by platform and country. Requires `?artist=` query param.
+ *
+ * @param request - must include `artist` query param
+ * @returns JSON chart positions or error
+ */
+export async function GET(request: NextRequest) {
+  return getResearchChartsHandler(request);
+}

app/api/research/cities/route.ts

@@ -0,0 +1,22 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { getResearchCitiesHandler } from "@/lib/research/getResearchCitiesHandler";
+
+/**
+ * OPTIONS /api/research/cities — CORS preflight.
+ *
+ * @returns CORS-enabled 200 response
+ */
+export async function OPTIONS() {
+  return new NextResponse(null, { status: 200, headers: getCorsHeaders() });
+}
+
+/**
+ * GET /api/research/cities — Geographic listening data for an artist. Requires `?artist=` query param.
+ *
+ * @param request - must include `artist` query param
+ * @returns JSON city-level listener data or error
+ */
+export async function GET(request: NextRequest) {
+  return getResearchCitiesHandler(request);
+}

app/api/research/curator/route.ts

@@ -0,0 +1,22 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { getResearchCuratorHandler } from "@/lib/research/getResearchCuratorHandler";
+
+/**
+ * OPTIONS /api/research/curator — CORS preflight.
+ *
+ * @returns CORS-enabled 200 response
+ */
+export async function OPTIONS() {
+  return new NextResponse(null, { status: 200, headers: getCorsHeaders() });
+}
+
+/**
+ * GET /api/research/curator — Playlist curator details. Requires `?platform=` and `?id=` query params.
+ *
+ * @param request - must include `platform` and `id` query params
+ * @returns JSON curator profile or error
+ */
+export async function GET(request: NextRequest) {
+  return getResearchCuratorHandler(request);
+}

app/api/research/deep/route.ts

@@ -0,0 +1,22 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { postResearchDeepHandler } from "@/lib/research/postResearchDeepHandler";
+
+/**
+ * OPTIONS /api/research/deep — CORS preflight.
+ *
+ * @returns CORS-enabled 200 response
+ */
+export async function OPTIONS() {
+  return new NextResponse(null, { status: 200, headers: getCorsHeaders() });
+}
+
+/**
+ * POST /api/research/deep — Deep, comprehensive research with citations. Body: `{ query }`.
+ *
+ * @param request - JSON body with `query` string
+ * @returns JSON research report with citations or error
+ */
+export async function POST(request: NextRequest) {
+  return postResearchDeepHandler(request);
+}

app/api/research/discover/route.ts

@@ -0,0 +1,22 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { getResearchDiscoverHandler } from "@/lib/research/getResearchDiscoverHandler";
+
+/**
+ * OPTIONS /api/research/discover — CORS preflight.
+ *
+ * @returns CORS-enabled 200 response
+ */
+export async function OPTIONS() {
+  return new NextResponse(null, { status: 200, headers: getCorsHeaders() });
+}
+
+/**
+ * GET /api/research/discover — Discover artists by genre, country, and growth criteria. Supports `?genre=`, `?country=`, `?sort=`, `?limit=` filters.
+ *
+ * @param request - filter criteria via query params
+ * @returns JSON array of matching artists or error
+ */
+export async function GET(request: NextRequest) {
+  return getResearchDiscoverHandler(request);
+}

app/api/research/enrich/route.ts

@@ -0,0 +1,22 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { postResearchEnrichHandler } from "@/lib/research/postResearchEnrichHandler";
+
+/**
+ * OPTIONS /api/research/enrich — CORS preflight.
+ *
+ * @returns CORS-enabled 200 response
+ */
+export async function OPTIONS() {
+  return new NextResponse(null, { status: 200, headers: getCorsHeaders() });
+}
+
+/**
+ * POST /api/research/enrich — Enrich an entity with structured web research data. Body: `{ url, prompt? }`.
+ *
+ * @param request - JSON body with `url` and optional `prompt`
+ * @returns JSON enriched entity data or error
+ */
+export async function POST(request: NextRequest) {
+  return postResearchEnrichHandler(request);
+}

app/api/research/extract/route.ts

@@ -0,0 +1,22 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { postResearchExtractHandler } from "@/lib/research/postResearchExtractHandler";
+
+/**
+ * OPTIONS /api/research/extract — CORS preflight.
+ *
+ * @returns CORS-enabled 200 response
+ */
+export async function OPTIONS() {
+  return new NextResponse(null, { status: 200, headers: getCorsHeaders() });
+}
+
+/**
+ * POST /api/research/extract — Extract clean markdown from URLs. Body: `{ urls }`.
+ *
+ * @param request - JSON body with `urls` array
+ * @returns JSON extracted markdown content or error
+ */
+export async function POST(request: NextRequest) {
+  return postResearchExtractHandler(request);
+}

app/api/research/festivals/route.ts

@@ -0,0 +1,22 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { getResearchFestivalsHandler } from "@/lib/research/getResearchFestivalsHandler";
+
+/**
+ * OPTIONS /api/research/festivals — CORS preflight.
+ *
+ * @returns CORS-enabled 200 response
+ */
+export async function OPTIONS() {
+  return new NextResponse(null, { status: 200, headers: getCorsHeaders() });
+}
+
+/**
+ * GET /api/research/festivals — List of music festivals.
+ *
+ * @param request - optional filter query params
+ * @returns JSON festival list or error
+ */
+export async function GET(request: NextRequest) {
+  return getResearchFestivalsHandler(request);
+}

app/api/research/genres/route.ts

@@ -0,0 +1,22 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { getResearchGenresHandler } from "@/lib/research/getResearchGenresHandler";
+
+/**
+ * OPTIONS /api/research/genres — CORS preflight.
+ *
+ * @returns CORS-enabled 200 response
+ */
+export async function OPTIONS() {
+  return new NextResponse(null, { status: 200, headers: getCorsHeaders() });
+}
+
+/**
+ * GET /api/research/genres — All available genre IDs and names.
+ *
+ * @param request - no required query params
+ * @returns JSON genre list or error
+ */
+export async function GET(request: NextRequest) {
+  return getResearchGenresHandler(request);
+}

app/api/research/insights/route.ts

@@ -0,0 +1,22 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { getResearchInsightsHandler } from "@/lib/research/getResearchInsightsHandler";
+
+/**
+ * OPTIONS /api/research/insights — CORS preflight.
+ *
+ * @returns CORS-enabled 200 response
+ */
+export async function OPTIONS() {
+  return new NextResponse(null, { status: 200, headers: getCorsHeaders() });
+}
+
+/**
+ * GET /api/research/insights — Noteworthy highlights and trending metrics for an artist. Requires `?artist=` query param.
+ *
+ * @param request - must include `artist` query param
+ * @returns JSON insights data or error
+ */
+export async function GET(request: NextRequest) {
+  return getResearchInsightsHandler(request);
+}

app/api/research/instagram-posts/route.ts

@@ -0,0 +1,22 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { getResearchInstagramPostsHandler } from "@/lib/research/getResearchInstagramPostsHandler";
+
+/**
+ * OPTIONS /api/research/instagram-posts — CORS preflight.
+ *
+ * @returns CORS-enabled 200 response
+ */
+export async function OPTIONS() {
+  return new NextResponse(null, { status: 200, headers: getCorsHeaders() });
+}
+
+/**
+ * GET /api/research/instagram-posts — Recent Instagram posts for an artist. Requires `?artist=` query param.
+ *
+ * @param request - must include `artist` query param
+ * @returns JSON Instagram posts or error
+ */
+export async function GET(request: NextRequest) {
+  return getResearchInstagramPostsHandler(request);
+}

app/api/research/lookup/route.ts

@@ -0,0 +1,22 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { getResearchLookupHandler } from "@/lib/research/getResearchLookupHandler";
+
+/**
+ * OPTIONS /api/research/lookup — CORS preflight.
+ *
+ * @returns CORS-enabled 200 response
+ */
+export async function OPTIONS() {
+  return new NextResponse(null, { status: 200, headers: getCorsHeaders() });
+}
+
+/**
+ * GET /api/research/lookup — Resolve a Spotify artist URL to cross-platform IDs. Requires `?url=` query param.
+ *
+ * @param request - must include `url` query param (Spotify URL)
+ * @returns JSON cross-platform IDs or error
+ */
+export async function GET(request: NextRequest) {
+  return getResearchLookupHandler(request);
+}

app/api/research/metrics/route.ts

@@ -0,0 +1,22 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { getResearchMetricsHandler } from "@/lib/research/getResearchMetricsHandler";
+
+/**
+ * OPTIONS /api/research/metrics — CORS preflight.
+ *
+ * @returns CORS-enabled 200 response
+ */
+export async function OPTIONS() {
+  return new NextResponse(null, { status: 200, headers: getCorsHeaders() });
+}
+
+/**
+ * GET /api/research/metrics — Platform-specific streaming and social metrics. Requires `?artist=` and `?source=` query params.
+ *
+ * @param request - must include `artist` and `source` query params
+ * @returns JSON metrics data or error
+ */
+export async function GET(request: NextRequest) {
+  return getResearchMetricsHandler(request);
+}

app/api/research/milestones/route.ts

@@ -0,0 +1,22 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { getResearchMilestonesHandler } from "@/lib/research/getResearchMilestonesHandler";
+
+/**
+ * OPTIONS /api/research/milestones — CORS preflight.
+ *
+ * @returns CORS-enabled 200 response
+ */
+export async function OPTIONS() {
+  return new NextResponse(null, { status: 200, headers: getCorsHeaders() });
+}
+
+/**
+ * GET /api/research/milestones — Artist activity feed: playlist adds, chart entries, events. Requires `?artist=` query param.
+ *
+ * @param request - must include `artist` query param
+ * @returns JSON milestone activity feed or error
+ */
+export async function GET(request: NextRequest) {
+  return getResearchMilestonesHandler(request);
+}