nextly 0.0.1 → 0.0.2-alpha.0

package/dist/api/media-handlers.mjs

@@ -0,0 +1,437 @@
+import {
+  readJsonBody
+} from "../chunk-VQJQHVEV.mjs";
+import {
+  nextlyValidationFromZod
+} from "../chunk-GJNSJU4S.mjs";
+import "../chunk-VWF3JO32.mjs";
+import {
+  withErrorHandler
+} from "../chunk-TO5AFLVQ.mjs";
+import {
+  getCachedNextly,
+  getNextly
+} from "../chunk-P7NH2OSC.mjs";
+import "../chunk-2OALJTK6.mjs";
+import "../chunk-VJ66NCL4.mjs";
+import "../chunk-R6JJQHFC.mjs";
+import "../chunk-X23WKS3Z.mjs";
+import {
+  getService
+} from "../chunk-X7TXCYYN.mjs";
+import "../chunk-YZNBLFIW.mjs";
+import "../chunk-FQULBZ53.mjs";
+import "../chunk-67GXH6PR.mjs";
+import "../chunk-2TFX4ND3.mjs";
+import "../chunk-W4MGXIRR.mjs";
+import {
+  UpdateMediaInputSchema,
+  UploadMediaInputSchema
+} from "../chunk-NSEFNNU4.mjs";
+import "../chunk-3FA7FKAV.mjs";
+import "../chunk-AGJ6F2T3.mjs";
+import "../chunk-KIMNCZGV.mjs";
+import "../chunk-AK6Z23OX.mjs";
+import "../chunk-INV7QKLG.mjs";
+import "../chunk-GZ6DCQKC.mjs";
+import "../chunk-SBACDPNX.mjs";
+import "../chunk-RJLLGGPG.mjs";
+import "../chunk-V4EQTOA4.mjs";
+import "../chunk-I4JMR3UR.mjs";
+import "../chunk-XZKLBMN6.mjs";
+import "../chunk-IZWPRDC3.mjs";
+import "../chunk-DNNG377Z.mjs";
+import "../chunk-5HMZ644B.mjs";
+import "../chunk-W5KKPZT5.mjs";
+import "../chunk-56WO4WX7.mjs";
+import {
+  withTimezoneFormatting
+} from "../chunk-2W3DVD7S.mjs";
+import "../chunk-TS7GHTG2.mjs";
+import "../chunk-H26B4FYG.mjs";
+import "../chunk-DP3G27G5.mjs";
+import "../chunk-DV6WVX2Q.mjs";
+import "../chunk-UJ2IMJ4W.mjs";
+import "../chunk-EGXBZCGC.mjs";
+import "../chunk-G2AA4QLC.mjs";
+import "../chunk-4MJLT6PZ.mjs";
+import {
+  respondAction,
+  respondData,
+  respondDoc,
+  respondList,
+  respondMutation
+} from "../chunk-IUDOC7N7.mjs";
+import "../chunk-LAZXX4HR.mjs";
+import "../chunk-D5HQBNUB.mjs";
+import {
+  NextlyError
+} from "../chunk-NRUWQ5Z7.mjs";
+import "../chunk-VTJADRO3.mjs";
+import "../chunk-5APFUGAD.mjs";
+import "../chunk-7P6ASYW6.mjs";
+
+// src/api/media-handlers.ts
+import { z } from "zod";
+var handlerConfig;
+async function getMediaService() {
+  if (handlerConfig?.config) {
+    await getNextly(handlerConfig);
+  } else {
+    await getCachedNextly();
+  }
+  return getService("mediaService");
+}
+function createRequestContext() {
+  return {};
+}
+function createAuthenticatedContext(userId) {
+  return {
+    user: {
+      id: userId,
+      email: `${userId}@api.local`,
+      role: "user",
+      permissions: []
+    }
+  };
+}
+function parseMediaRoute(path, method) {
+  const segments = path || [];
+  if (segments.length === 0) {
+    if (method === "GET") return { type: "list-media" };
+    if (method === "POST") return { type: "upload-media" };
+    return { type: "not-found" };
+  }
+  if (segments[0] === "folders") {
+    if (segments.length === 1) {
+      if (method === "GET") return { type: "list-folders" };
+      if (method === "POST") return { type: "create-folder" };
+      return { type: "not-found" };
+    }
+    if (segments[1] === "root" && segments[2] === "contents") {
+      if (method === "GET") return { type: "get-root-contents" };
+      return { type: "not-found" };
+    }
+    if (segments.length === 3 && segments[2] === "contents") {
+      if (method === "GET")
+        return { type: "get-folder-contents", folderId: segments[1] };
+      return { type: "not-found" };
+    }
+    if (segments.length === 2) {
+      if (method === "GET")
+        return { type: "get-folder", folderId: segments[1] };
+      if (method === "PATCH")
+        return { type: "update-folder", folderId: segments[1] };
+      if (method === "DELETE")
+        return { type: "delete-folder", folderId: segments[1] };
+      return { type: "not-found" };
+    }
+    return { type: "not-found" };
+  }
+  if (segments.length === 2 && segments[1] === "move") {
+    if (method === "PATCH") return { type: "move-media", mediaId: segments[0] };
+    return { type: "not-found" };
+  }
+  if (segments.length === 1) {
+    if (method === "GET") return { type: "get-media", mediaId: segments[0] };
+    if (method === "PATCH")
+      return { type: "update-media", mediaId: segments[0] };
+    if (method === "DELETE")
+      return { type: "delete-media", mediaId: segments[0] };
+    return { type: "not-found" };
+  }
+  return { type: "not-found" };
+}
+function throwUnmatchedRoute(path, method) {
+  throw NextlyError.notFound({
+    logContext: {
+      path: path ?? [],
+      method,
+      reason: "unmatched-media-route"
+    }
+  });
+}
+async function handleListMedia(request) {
+  const mediaService = await getMediaService();
+  const { searchParams } = new URL(request.url);
+  const context = createRequestContext();
+  const folderIdParam = searchParams.get("folderId");
+  const options = {
+    page: searchParams.get("page") ? Number(searchParams.get("page")) : 1,
+    limit: searchParams.get("limit") ? Number(searchParams.get("limit")) : 24,
+    search: searchParams.get("search") || void 0,
+    type: searchParams.get("type") || void 0,
+    folderId: folderIdParam === "root" ? "root" : folderIdParam || void 0,
+    sortBy: searchParams.get("sortBy") || "uploadedAt",
+    sortOrder: searchParams.get("sortOrder") || "desc"
+  };
+  const result = await mediaService.listMedia(options, context);
+  const page = options.page ?? 1;
+  const limit = Math.max(1, options.limit ?? 24);
+  const total = result.pagination.total;
+  const totalPages = limit > 0 ? Math.ceil(total / limit) : 0;
+  return respondList(result.data, {
+    total,
+    page,
+    limit,
+    totalPages,
+    hasNext: page < totalPages,
+    hasPrev: page > 1
+  });
+}
+async function handleUploadMedia(request) {
+  const mediaService = await getMediaService();
+  const formData = await request.formData();
+  const file = formData.get("file");
+  const uploadedBy = formData.get("uploadedBy");
+  const folderId = formData.get("folderId");
+  const errors = [];
+  if (!file) {
+    errors.push({
+      path: "file",
+      code: "REQUIRED",
+      message: "file is required."
+    });
+  }
+  if (!uploadedBy) {
+    errors.push({
+      path: "uploadedBy",
+      code: "REQUIRED",
+      message: "uploadedBy is required."
+    });
+  }
+  if (errors.length > 0) {
+    throw NextlyError.validation({ errors });
+  }
+  const fileEnsured = file;
+  const uploadedByEnsured = uploadedBy;
+  const arrayBuffer = await fileEnsured.arrayBuffer();
+  const buffer = Buffer.from(arrayBuffer);
+  const input = {
+    file: buffer,
+    filename: fileEnsured.name,
+    mimeType: fileEnsured.type,
+    size: fileEnsured.size,
+    uploadedBy: uploadedByEnsured
+  };
+  try {
+    UploadMediaInputSchema.parse(input);
+  } catch (err) {
+    if (err instanceof z.ZodError) throw nextlyValidationFromZod(err);
+    throw err;
+  }
+  const context = createAuthenticatedContext(uploadedByEnsured);
+  const mediaFile = await mediaService.upload(
+    {
+      buffer,
+      filename: fileEnsured.name,
+      mimeType: fileEnsured.type,
+      size: fileEnsured.size,
+      folderId: folderId || void 0
+    },
+    context
+  );
+  return respondMutation("Media uploaded.", mediaFile, { status: 201 });
+}
+async function handleGetMedia(mediaId) {
+  const mediaService = await getMediaService();
+  const context = createRequestContext();
+  const mediaFile = await mediaService.findById(mediaId, context);
+  return respondDoc(mediaFile);
+}
+async function handleUpdateMedia(request, mediaId) {
+  const mediaService = await getMediaService();
+  const body = await readJsonBody(request);
+  let validated;
+  try {
+    validated = UpdateMediaInputSchema.parse(body);
+  } catch (err) {
+    if (err instanceof z.ZodError) throw nextlyValidationFromZod(err);
+    throw err;
+  }
+  const context = createRequestContext();
+  const mediaFile = await mediaService.update(mediaId, validated, context);
+  return respondMutation("Media updated.", mediaFile);
+}
+async function handleDeleteMedia(mediaId) {
+  const mediaService = await getMediaService();
+  const context = createRequestContext();
+  await mediaService.delete(mediaId, context);
+  return respondAction("Media deleted.", { id: mediaId });
+}
+async function handleMoveMedia(request, mediaId) {
+  const mediaService = await getMediaService();
+  const body = await readJsonBody(request);
+  const folderId = body.folderId;
+  const context = createRequestContext();
+  await mediaService.moveToFolder(mediaId, folderId ?? null, context);
+  return respondAction("Media moved.", { id: mediaId, folderId: folderId ?? null });
+}
+async function handleListFolders(request) {
+  const mediaService = await getMediaService();
+  const context = createRequestContext();
+  const { searchParams } = new URL(request.url);
+  const root = searchParams.get("root") === "true";
+  const parentId = searchParams.get("parentId");
+  const folders = root || !parentId ? await mediaService.listRootFolders(context) : await mediaService.listSubfolders(parentId, context);
+  return respondData({ folders });
+}
+async function handleCreateFolder(request) {
+  const mediaService = await getMediaService();
+  const body = await readJsonBody(request);
+  const { createdBy, ...folderInput } = body;
+  const errors = [];
+  if (!createdBy) {
+    errors.push({
+      path: "createdBy",
+      code: "REQUIRED",
+      message: "createdBy is required."
+    });
+  }
+  if (!folderInput.name) {
+    errors.push({
+      path: "name",
+      code: "REQUIRED",
+      message: "name is required."
+    });
+  }
+  if (errors.length > 0) {
+    throw NextlyError.validation({ errors });
+  }
+  const context = createAuthenticatedContext(createdBy);
+  const folder = await mediaService.createFolder(
+    folderInput,
+    context
+  );
+  return respondMutation("Folder created.", folder, { status: 201 });
+}
+async function handleGetFolder(folderId) {
+  const mediaService = await getMediaService();
+  const context = createRequestContext();
+  const folder = await mediaService.findFolderById(folderId, context);
+  return respondDoc(folder);
+}
+async function handleUpdateFolder(request, folderId) {
+  const mediaService = await getMediaService();
+  const body = await readJsonBody(request);
+  const context = createRequestContext();
+  const folder = await mediaService.updateFolder(folderId, body, context);
+  return respondMutation("Folder updated.", folder);
+}
+async function handleDeleteFolder(request, folderId) {
+  const mediaService = await getMediaService();
+  const context = createRequestContext();
+  const { searchParams } = new URL(request.url);
+  const deleteContents = searchParams.get("deleteContents") === "true";
+  await mediaService.deleteFolder(folderId, deleteContents, context);
+  return respondAction("Folder deleted.", { id: folderId });
+}
+async function handleGetFolderContents(folderId) {
+  const mediaService = await getMediaService();
+  const context = createRequestContext();
+  const contents = await mediaService.getFolderContents(folderId, context);
+  return respondData(contents);
+}
+async function handleGetRootContents() {
+  const mediaService = await getMediaService();
+  const context = createRequestContext();
+  const contents = await mediaService.getFolderContents(null, context);
+  return respondData(contents);
+}
+function createMediaHandlers(options) {
+  if (options?.config) {
+    handlerConfig = { config: options.config };
+  }
+  return {
+    GET: withErrorHandler(
+      async (request, ctx) => {
+        const resolvedParams = await ctx.params;
+        const route = parseMediaRoute(resolvedParams.path, "GET");
+        let response;
+        switch (route.type) {
+          case "list-media":
+            response = await handleListMedia(request);
+            break;
+          case "get-media":
+            response = await handleGetMedia(route.mediaId);
+            break;
+          case "list-folders":
+            response = await handleListFolders(request);
+            break;
+          case "get-folder":
+            response = await handleGetFolder(route.folderId);
+            break;
+          case "get-folder-contents":
+            response = await handleGetFolderContents(route.folderId);
+            break;
+          case "get-root-contents":
+            response = await handleGetRootContents();
+            break;
+          default:
+            throwUnmatchedRoute(resolvedParams.path, "GET");
+        }
+        return withTimezoneFormatting(response);
+      }
+    ),
+    POST: withErrorHandler(
+      async (request, ctx) => {
+        const resolvedParams = await ctx.params;
+        const route = parseMediaRoute(resolvedParams.path, "POST");
+        let response;
+        switch (route.type) {
+          case "upload-media":
+            response = await handleUploadMedia(request);
+            break;
+          case "create-folder":
+            response = await handleCreateFolder(request);
+            break;
+          default:
+            throwUnmatchedRoute(resolvedParams.path, "POST");
+        }
+        return withTimezoneFormatting(response);
+      }
+    ),
+    PATCH: withErrorHandler(
+      async (request, ctx) => {
+        const resolvedParams = await ctx.params;
+        const route = parseMediaRoute(resolvedParams.path, "PATCH");
+        let response;
+        switch (route.type) {
+          case "update-media":
+            response = await handleUpdateMedia(request, route.mediaId);
+            break;
+          case "move-media":
+            response = await handleMoveMedia(request, route.mediaId);
+            break;
+          case "update-folder":
+            response = await handleUpdateFolder(request, route.folderId);
+            break;
+          default:
+            throwUnmatchedRoute(resolvedParams.path, "PATCH");
+        }
+        return withTimezoneFormatting(response);
+      }
+    ),
+    DELETE: withErrorHandler(
+      async (request, ctx) => {
+        const resolvedParams = await ctx.params;
+        const route = parseMediaRoute(resolvedParams.path, "DELETE");
+        let response;
+        switch (route.type) {
+          case "delete-media":
+            response = await handleDeleteMedia(route.mediaId);
+            break;
+          case "delete-folder":
+            response = await handleDeleteFolder(request, route.folderId);
+            break;
+          default:
+            throwUnmatchedRoute(resolvedParams.path, "DELETE");
+        }
+        return withTimezoneFormatting(response);
+      }
+    )
+  };
+}
+export {
+  createMediaHandlers
+};

package/dist/api/media.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Media API Route Handlers for Next.js
+ *
+ * These route handlers can be re-exported in your Next.js application to provide
+ * media management endpoints at /api/media.
+ *
+ * **IMPORTANT:** For storage plugins (S3, Vercel Blob, etc.) to work, you must
+ * initialize Nextly with your config before these routes are called. The recommended
+ * approach is to use Next.js instrumentation:
+ *
+ * ```typescript
+ * // src/instrumentation.ts
+ * export async function register() {
+ *   if (process.env.NEXT_RUNTIME === "nodejs") {
+ *     const { getNextly } = await import("nextly");
+ *     const nextlyConfig = (await import("./nextly.config")).default;
+ *     await getNextly({ config: nextlyConfig });
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // In your Next.js app: app/api/media/route.ts
+ * export { GET, POST } from 'nextly/api/media';
+ *
+ * // In your Next.js app: app/api/media/[id]/route.ts
+ * export { getMediaById as GET, updateMedia as PATCH, deleteMedia as DELETE } from 'nextly/api/media';
+ * ```
+ *
+ * @module api/media
+ */
+/**
+ * GET handler for listing media with pagination, search, and filters.
+ *
+ * Query Parameters:
+ * - page: Page number (default: 1)
+ * - limit: Items per page (default: 24)
+ * - search: Search query for filename, altText
+ * - type: Filter by media type (image, video, audio, document, other)
+ * - folderId: Filter by folder ("root" for root-level media)
+ * - sortBy: Sort field (uploadedAt, filename, size)
+ * - sortOrder: Sort direction (asc, desc)
+ *
+ * Response: `{ items: Media[], meta: { total, page, limit, totalPages,
+ * hasNext, hasPrev } }` per the canonical respondList shape.
+ */
+declare const GET: (request: Request) => Promise<Response>;
+/**
+ * POST handler for uploading media files.
+ *
+ * Accepts multipart/form-data with a 'file' field and metadata.
+ * Automatically processes images (thumbnails, dimensions).
+ *
+ * Form Data:
+ * - file: File to upload (required)
+ * - uploadedBy: User ID (required)
+ * - folderId: Optional folder to upload into.
+ *
+ * Response: `{ message, item: Media }` (status 201).
+ */
+declare const POST: (request: Request) => Promise<Response>;
+/**
+ * GET handler for fetching a single media item by ID.
+ *
+ * Response: bare `Media` (respondDoc). 404 surface emits canonical
+ * `application/problem+json` with `code: "NOT_FOUND"`.
+ */
+declare function getMediaById(request: Request, ctx: {
+    params: Promise<{
+        id: string;
+    }>;
+}): Promise<Response>;
+/**
+ * PATCH handler for updating media metadata.
+ *
+ * Accepts JSON with metadata updates (altText, caption, tags).
+ *
+ * Request Body:
+ * - altText: Optional alt text
+ * - caption: Optional caption
+ * - tags: Optional tags array
+ *
+ * Response: `{ message, item: Media }`.
+ */
+declare function updateMedia(request: Request, ctx: {
+    params: Promise<{
+        id: string;
+    }>;
+}): Promise<Response>;
+/**
+ * DELETE handler for deleting media files.
+ *
+ * Removes media from both storage and database.
+ *
+ * Response: `{ message, id }` (respondAction; service returns void).
+ */
+declare function deleteMedia(request: Request, ctx: {
+    params: Promise<{
+        id: string;
+    }>;
+}): Promise<Response>;
+/**
+ * PATCH handler for moving media to a folder
+ *
+ * Path: /api/media/[id]/move
+ * Body: { folderId: string | null }
+ *
+ * Response: `{ message, id, folderId }` (respondAction; service returns void).
+ */
+declare function moveMediaToFolder(request: Request, ctx: {
+    params: Promise<{
+        id: string;
+    }>;
+}): Promise<Response>;
+
+export { GET, POST, deleteMedia, getMediaById, moveMediaToFolder, updateMedia };