nextly 0.0.1 → 0.0.2-alpha.0

package/dist/api/health.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Health Check Route Handlers for Next.js
+ *
+ * These route handlers can be re-exported in your Next.js application to provide
+ * a production-ready health check endpoint at /api/health.
+ *
+ * @example
+ * ```typescript
+ * // In your Next.js app: app/api/health/route.ts
+ * export { GET, HEAD } from 'nextly/api/health';
+ * ```
+ *
+ * @module api/health
+ */
+/**
+ * GET handler for health check endpoint.
+ *
+ * Returns the current database/runtime health as a bare object body via
+ * `respondData`. The body merges the database probe with the package
+ * version and process uptime so monitoring dashboards have a
+ * non-Boolean-only payload to assert against (spec §5.1 rule 3 / §7.7).
+ * When the underlying check reports `ok: false`, the handler throws a 503
+ * `SERVICE_UNAVAILABLE` `NextlyError` so the route boundary serializes it
+ * as `application/problem+json`. The unhealthy detail (latency, dialect,
+ * error string) is logged via `logContext` rather than echoed to the
+ * public response; anonymous monitoring scrapers should not learn
+ * implementation specifics.
+ *
+ * Response Codes:
+ * - 200 OK: Database is healthy. Body:
+ *   `{ ok, version, uptime, timestamp, database }`.
+ * - 503 Service Unavailable: Database is unreachable or unhealthy. Body:
+ *   `{ error: { code: "SERVICE_UNAVAILABLE", message, requestId } }`.
+ *
+ * @example
+ * ```bash
+ * curl http://localhost:3000/api/health
+ * # => {"ok":true,"version":"0.0.142","uptime":123,"timestamp":"...","database":{...}}
+ * ```
+ */
+declare const GET: (_request: Request) => Promise<Response>;
+/**
+ * HEAD handler for lightweight health check.
+ *
+ * Returns only the HTTP status code and headers without body content. Useful
+ * for monitoring systems that only need to verify the endpoint is responding.
+ * HEAD is intentionally not wrapped in `withErrorHandler` because the wrapper
+ * always emits a JSON body on the error path, which violates HEAD semantics
+ * (per RFC 9110 HEAD responses must not include a body). Unexpected throws
+ * propagate to Next.js's runtime; in production this surfaces as a 500 with
+ * no body, matching the pre-migration behavior.
+ *
+ * `X-Request-Id` is set so log lines emitted by `healthCheck()` can be
+ * correlated to a probe even though HEAD bypasses the route boundary.
+ *
+ * Response Codes:
+ * - 200 OK: Database is healthy
+ * - 503 Service Unavailable: Database is unhealthy
+ *
+ * @example
+ * ```bash
+ * curl -I http://localhost:3000/api/health
+ * # => HTTP/1.1 200 OK
+ * ```
+ */
+declare function HEAD(request: Request): Promise<Response>;
+
+export { GET, HEAD };

package/dist/api/health.mjs

@@ -0,0 +1,67 @@
+import {
+  withErrorHandler
+} from "../chunk-TO5AFLVQ.mjs";
+import {
+  readOrGenerateRequestId
+} from "../chunk-67GXH6PR.mjs";
+import "../chunk-2TFX4ND3.mjs";
+import "../chunk-W4MGXIRR.mjs";
+import {
+  respondData
+} from "../chunk-IUDOC7N7.mjs";
+import {
+  healthCheck
+} from "../chunk-LAZXX4HR.mjs";
+import "../chunk-D5HQBNUB.mjs";
+import {
+  NextlyError
+} from "../chunk-NRUWQ5Z7.mjs";
+import "../chunk-7P6ASYW6.mjs";
+
+// src/api/health.ts
+var PACKAGE_VERSION = (
+  // eslint-disable-next-line turbo/no-undeclared-env-vars
+  typeof process !== "undefined" && process.env?.npm_package_version || "unknown"
+);
+function readUptimeSeconds() {
+  if (typeof process === "undefined" || typeof process.uptime !== "function") {
+    return 0;
+  }
+  return Math.floor(process.uptime());
+}
+var HEALTH_CHECK_CACHE_SECONDS = typeof process !== "undefined" && process.env?.HEALTH_CHECK_CACHE_SECONDS ? Number(process.env.HEALTH_CHECK_CACHE_SECONDS) : 60;
+var HEALTH_CACHE_CONTROL = `public, max-age=${HEALTH_CHECK_CACHE_SECONDS}, stale-while-revalidate=30`;
+var GET = withErrorHandler(async (_request) => {
+  const health = await healthCheck();
+  if (!health.ok) {
+    throw NextlyError.serviceUnavailable({
+      logMessage: "Health check failed",
+      logContext: { health }
+    });
+  }
+  return respondData(
+    {
+      ...health,
+      version: PACKAGE_VERSION,
+      uptime: readUptimeSeconds()
+    },
+    {
+      headers: { "Cache-Control": HEALTH_CACHE_CONTROL }
+    }
+  );
+});
+async function HEAD(request) {
+  const requestId = readOrGenerateRequestId(request);
+  const health = await healthCheck();
+  return new Response(null, {
+    status: health.ok ? 200 : 503,
+    headers: {
+      "Cache-Control": HEALTH_CACHE_CONTROL,
+      "X-Request-Id": requestId
+    }
+  });
+}
+export {
+  GET,
+  HEAD
+};

package/dist/api/index.d.ts

@@ -0,0 +1,54 @@
+import { O as OnErrorHook } from '../_dts-chunks/on-error.d-CHIKWNxd.d.ts';
+import '../errors/index.d.ts';
+
+type WithErrorHandlerOptions = {
+    /** Per-call observability hook. Fired before the global hook. */
+    onError?: OnErrorHook;
+    /** Public message used when wrapping unknown errors. Default: generic. */
+    internalErrorMessage?: string;
+};
+/**
+ * HTTP boundary wrapper for Next.js App Router Route Handlers.
+ *
+ * Responsibilities (in order, per spec §11.2):
+ * 1. Read or generate a Stripe-style `requestId` for this request.
+ * 2. Run the handler.
+ * 3. On thrown values: pass Next.js sentinel errors (`redirect`, `notFound`,
+ *    dynamic-API bailouts) through `unstable_rethrow` first.
+ * 4. Otherwise classify: `NextlyError` directly, `DbError` via the safety
+ *    net, anything else wrapped as `NextlyError.internal`.
+ * 5. Log the classified error.
+ * 6. Fire the per-call `onError` hook, then the global one. Hook failures
+ *    are logged but never poison the response.
+ * 7. Serialize via `toResponseJSON(requestId)` with `application/problem+json`
+ *    content type, the response status, and `X-Request-Id`. `Retry-After`
+ *    is set for `RATE_LIMITED`.
+ *
+ * Generic over `TArgs` so it transparently supports both static handlers
+ * (`(req)`) and dynamic-segment handlers (`(req, { params })`).
+ */
+declare function withErrorHandler<TArgs extends unknown[]>(handler: (...args: TArgs) => Promise<Response>, options?: WithErrorHandlerOptions): (...args: TArgs) => Promise<Response>;
+
+/**
+ * Stripe-style request IDs (`req_<16 base32 chars>`) for the unified error
+ * system. Generated at the boundary by withErrorHandler / withAction unless
+ * an upstream proxy already set `x-request-id` (or one of the cloud-provider
+ * variants Vercel and Cloudflare emit), in which case we honor it so a
+ * single user request shares one id across all hops.
+ *
+ * Format: `req_` prefix + 16 chars of RFC 4648 base32-lowercase. 10 random
+ * bytes provide 80 bits of entropy — uniquely identifying every request at
+ * any reasonable scale.
+ *
+ * Works in both Node and Edge runtimes (uses Web Crypto's
+ * `crypto.getRandomValues`).
+ */
+declare function generateRequestId(): string;
+/**
+ * Read an upstream-set request id, falling back to a freshly generated one.
+ * Header precedence (most-specific first): `x-request-id` (our convention) >
+ * `x-vercel-id` (Vercel) > `cf-ray` (Cloudflare).
+ */
+declare function readOrGenerateRequestId(req: Request): string;
+
+export { generateRequestId, readOrGenerateRequestId, withErrorHandler };

package/dist/api/index.mjs

@@ -0,0 +1,16 @@
+import {
+  withErrorHandler
+} from "../chunk-TO5AFLVQ.mjs";
+import {
+  generateRequestId,
+  readOrGenerateRequestId
+} from "../chunk-67GXH6PR.mjs";
+import "../chunk-2TFX4ND3.mjs";
+import "../chunk-W4MGXIRR.mjs";
+import "../chunk-NRUWQ5Z7.mjs";
+import "../chunk-7P6ASYW6.mjs";
+export {
+  generateRequestId,
+  readOrGenerateRequestId,
+  withErrorHandler
+};

package/dist/api/media-bulk.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Bulk Media API Route Handlers for Next.js
+ *
+ * These route handlers provide bulk operations for media management.
+ * Supports bulk upload and bulk delete with parallel processing.
+ *
+ * IMPORTANT: Before using these routes, you must initialize the service layer by calling
+ * `registerServices()` during your application startup.
+ *
+ * Wire shape:
+ *   - DELETE returns the canonical respondBulk envelope:
+ *     `{ message, items, errors }` where items are minimal `{id}` records
+ *     for deleted files and errors are id-keyed PerItemError entries.
+ *   - POST returns the canonical respondBulkUpload envelope:
+ *     `{ message, items, errors }` where items are full MediaFile records
+ *     for newly-uploaded files and errors are positional BulkUploadError
+ *     entries (`{ index, filename, code, message }`).
+ *
+ * Per-item failures are first-class data in the body's `errors` array
+ * (HTTP 200). 4xx is reserved for malformed requests (e.g. empty input,
+ * all entries failed input validation before the service was reached).
+ *
+ * @example
+ * ```typescript
+ * // In your Next.js app: app/api/media/bulk/route.ts
+ * export { POST, DELETE } from 'nextly/api/media-bulk';
+ * ```
+ *
+ * @module api/media-bulk
+ */
+/**
+ * POST handler for bulk media upload.
+ *
+ * Uploads multiple files. Provides detailed per-file results, positional
+ * (index + filename) for failures since uploads have no client-supplied id.
+ *
+ * Request Body (JSON):
+ * {
+ *   files: Array<{
+ *     file: string (base64),
+ *     filename: string,
+ *     mimeType: string,
+ *     size: number,
+ *     uploadedBy: string
+ *   }>,
+ *   uploadedBy?: string,
+ * }
+ *
+ * Response: canonical respondBulkUpload envelope `{ message, items, errors }`.
+ * Items are full MediaFile records for newly-uploaded files; errors are
+ * positional BulkUploadError entries. Pre-upload validation failures fold
+ * into the same `errors` array (no parallel `validationErrors` field;
+ * unified failure list). Status 200 for partial-success.
+ *
+ * 4xx applies only to fully-malformed requests: empty `files` array, or
+ * every entry failed input validation (no useful service work to do).
+ */
+declare const POST: (request: Request) => Promise<Response>;
+/**
+ * DELETE handler for bulk media deletion.
+ *
+ * Response: canonical respondBulk envelope `{ message, items, errors }`.
+ * Items are minimal `{id}` records (the files are gone); errors are
+ * id-keyed PerItemError entries. Status 200 for partial-success; 400
+ * only for an empty/malformed `mediaIds` array.
+ *
+ * Request Body (JSON):
+ * {
+ *   mediaIds: string[]
+ * }
+ */
+declare const DELETE: (request: Request) => Promise<Response>;
+
+export { DELETE, POST };

package/dist/api/media-bulk.mjs

@@ -0,0 +1,196 @@
+import {
+  readJsonBody
+} from "../chunk-VQJQHVEV.mjs";
+import "../chunk-VWF3JO32.mjs";
+import {
+  withErrorHandler
+} from "../chunk-TO5AFLVQ.mjs";
+import {
+  getService,
+  isServicesRegistered
+} 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 {
+  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 "../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 {
+  respondBulk,
+  respondBulkUpload
+} 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-bulk.ts
+function getMediaService() {
+  if (!isServicesRegistered()) {
+    throw NextlyError.serviceUnavailable({
+      logMessage: "Media bulk handler called before registerServices()",
+      logContext: {
+        hint: "Call registerServices() before mounting media-bulk routes. See https://nextlyhq.com/docs/initialization"
+      }
+    });
+  }
+  return getService("mediaService");
+}
+function createAuthenticatedContext(userId) {
+  if (!userId) return {};
+  return {
+    user: {
+      id: userId,
+      email: `${userId}@api.local`,
+      role: "user",
+      permissions: []
+    }
+  };
+}
+var POST = withErrorHandler(
+  async (request) => {
+    const mediaService = getMediaService();
+    const body = await readJsonBody(request);
+    const filesInput = body.files;
+    const uploadedBy = typeof body.uploadedBy === "string" ? body.uploadedBy : void 0;
+    if (!Array.isArray(filesInput) || filesInput.length === 0) {
+      throw NextlyError.validation({
+        errors: [
+          {
+            path: "files",
+            code: "required_array",
+            message: "files must be a non-empty array."
+          }
+        ]
+      });
+    }
+    const validatedFiles = [];
+    const failures = [];
+    for (let i = 0; i < filesInput.length; i++) {
+      const file = filesInput[i];
+      const filename = file.filename || `file-${i}`;
+      let buffer;
+      if (typeof file.file === "string") {
+        buffer = Buffer.from(file.file, "base64");
+      } else if (Buffer.isBuffer(file.file)) {
+        buffer = file.file;
+      } else {
+        failures.push({
+          index: i,
+          filename,
+          code: "VALIDATION_ERROR",
+          message: "Invalid file format."
+        });
+        continue;
+      }
+      const parseResult = UploadMediaInputSchema.safeParse({
+        file: buffer,
+        filename: file.filename,
+        mimeType: file.mimeType,
+        size: file.size || buffer.length,
+        uploadedBy: file.uploadedBy || uploadedBy
+      });
+      if (!parseResult.success) {
+        failures.push({
+          index: i,
+          filename,
+          code: "VALIDATION_ERROR",
+          message: "Validation failed."
+        });
+      } else {
+        validatedFiles.push({
+          buffer,
+          filename: file.filename,
+          mimeType: file.mimeType,
+          size: file.size || buffer.length,
+          originalIndex: i
+        });
+      }
+    }
+    if (validatedFiles.length === 0) {
+      throw NextlyError.validation({
+        errors: failures.map((f) => ({
+          path: `files[${f.index}]`,
+          code: "INVALID_FILE",
+          message: f.message
+        })),
+        logContext: { totalFiles: filesInput.length }
+      });
+    }
+    const firstFile = filesInput[0];
+    const userId = firstFile.uploadedBy || uploadedBy || null;
+    const context = createAuthenticatedContext(userId);
+    const serviceInputs = validatedFiles.map(({ originalIndex: _, ...rest }) => rest);
+    const result = await mediaService.bulkUpload(serviceInputs, context);
+    for (const f of result.failures) {
+      const original = validatedFiles[f.index];
+      failures.push({
+        index: original?.originalIndex ?? f.index,
+        filename: f.filename,
+        code: f.code,
+        message: f.message
+      });
+    }
+    const totalRequested = filesInput.length;
+    const successCount = result.successCount;
+    const message = failures.length === 0 ? `Uploaded ${successCount} ${successCount === 1 ? "file" : "files"}.` : `Uploaded ${successCount} of ${totalRequested} files.`;
+    return respondBulkUpload(message, result.successes, failures);
+  }
+);
+var DELETE = withErrorHandler(
+  async (request) => {
+    const mediaService = getMediaService();
+    const body = await readJsonBody(request);
+    const mediaIds = body.mediaIds;
+    if (!Array.isArray(mediaIds) || mediaIds.length === 0) {
+      throw NextlyError.validation({
+        errors: [
+          {
+            path: "mediaIds",
+            code: "required_array",
+            message: "mediaIds must be a non-empty array."
+          }
+        ]
+      });
+    }
+    const context = {};
+    const result = await mediaService.bulkDelete(mediaIds, context);
+    const message = result.failures.length === 0 ? `Deleted ${result.successCount} ${result.successCount === 1 ? "file" : "files"}.` : `Deleted ${result.successCount} of ${result.total} files.`;
+    return respondBulk(message, result.successes, result.failures);
+  }
+);
+export {
+  DELETE,
+  POST
+};

package/dist/api/media-folders.d.ts

@@ -0,0 +1,112 @@
+import { NextRequest } from 'next/server';
+
+/**
+ * Media Folders API Route Handlers
+ *
+ * Next.js App Router compatible handlers for folder management operations.
+ * Re-export these handlers in your app's API routes.
+ *
+ * **IMPORTANT:** For storage plugins to work, initialize Nextly with your config
+ * via instrumentation.ts before these routes are called.
+ *
+ * @example
+ * ```typescript
+ * // app/api/media/folders/route.ts
+ * export { GET, POST } from 'nextly/api/media-folders';
+ *
+ * // app/api/media/folders/[id]/route.ts
+ * export { getFolderById as GET, updateFolder as PATCH, deleteFolder as DELETE } from 'nextly/api/media-folders';
+ *
+ * // app/api/media/folders/[id]/contents/route.ts
+ * export { getFolderContents as GET } from 'nextly/api/media-folders';
+ *
+ * // app/api/media/folders/root/contents/route.ts
+ * export { getRootFolderContents as GET } from 'nextly/api/media-folders';
+ * ```
+ */
+
+/**
+ * GET /api/media/folders
+ *
+ * List folders with optional filtering:
+ * - ?root=true - List only root folders (no parent)
+ * - ?parentId=xxx - List subfolders of a specific parent
+ *
+ * Response: `{ "folders": Folder[] }` (non-paginated; respondData with a
+ * named field).
+ */
+declare const GET: (request: NextRequest) => Promise<Response>;
+/**
+ * POST /api/media/folders
+ *
+ * Create a new folder
+ *
+ * Request Body:
+ * - name: string (required)
+ * - description?: string
+ * - color?: string
+ * - icon?: string
+ * - parentId?: string | null
+ * - createdBy: string (required)
+ *
+ * Response: `{ "message", "item": Folder }` (status 201).
+ */
+declare const POST: (request: NextRequest) => Promise<Response>;
+/**
+ * GET /api/media/folders/[id]
+ *
+ * Get folder by ID
+ */
+declare function getFolderById(request: NextRequest, routeContext: {
+    params: Promise<{
+        id: string;
+    }>;
+}): Promise<Response>;
+/**
+ * PATCH /api/media/folders/[id]
+ *
+ * Update folder metadata
+ *
+ * Request Body:
+ * - name?: string
+ * - description?: string
+ * - color?: string
+ * - icon?: string
+ * - parentId?: string | null
+ */
+declare function updateFolder(request: NextRequest, routeContext: {
+    params: Promise<{
+        id: string;
+    }>;
+}): Promise<Response>;
+/**
+ * DELETE /api/media/folders/[id]
+ *
+ * Delete folder
+ * Query params: ?deleteContents=true/false
+ *
+ * Response: `{ "message", "id" }` (respondAction; service returns void).
+ */
+declare function deleteFolder(request: NextRequest, routeContext: {
+    params: Promise<{
+        id: string;
+    }>;
+}): Promise<Response>;
+/**
+ * GET /api/media/folders/[id]/contents
+ *
+ * Get folder contents (subfolders + media files)
+ */
+declare function getFolderContents(request: NextRequest, routeContext: {
+    params: Promise<{
+        id: string;
+    }>;
+}): Promise<Response>;
+/**
+ * GET /api/media/folders/root/contents
+ *
+ * Get root folder contents (folders + media without a folder)
+ */
+declare const getRootFolderContents: (_request: NextRequest) => Promise<Response>;
+
+export { GET, POST, deleteFolder, getFolderById, getFolderContents, getRootFolderContents, updateFolder };