@nextlyhq/storage-vercel-blob 0.0.2-alpha.6 → 0.0.2-alpha.62

package/dist/index.cjs

@@ -2,6 +2,433 @@
 
 var blob = require('@vercel/blob');
 
+// src/adapter.ts
+
+// ../nextly/dist/chunk-SAEVUREH.mjs
+function isDbError(err) {
+  if (!err || typeof err !== "object") return false;
+  const obj = err;
+  return obj.name === "DbError" && typeof obj.kind === "string";
+}
+var NEXTLY_ERROR_STATUS = {
+  VALIDATION_ERROR: 400,
+  INVALID_INPUT: 400,
+  AUTH_REQUIRED: 401,
+  AUTH_INVALID_CREDENTIALS: 401,
+  TOKEN_EXPIRED: 401,
+  FORBIDDEN: 403,
+  // The schema builder is off in this environment (production by default).
+  // Separate from FORBIDDEN: the caller's permissions are not the problem.
+  BUILDER_DISABLED: 403,
+  NOT_FOUND: 404,
+  CONFLICT: 409,
+  DUPLICATE: 409,
+  RATE_LIMITED: 429,
+  PAYLOAD_TOO_LARGE: 413,
+  UNSUPPORTED_MEDIA_TYPE: 415,
+  // 422: understood, well-formed, and refused on a rule the caller can act on.
+  // Deliberately NOT added to CANONICAL_CODE_FOR_STATUS -- that list drives the
+  // status -> code direction, where 422 stays mapped to INVALID_INPUT.
+  BUSINESS_RULE_VIOLATION: 422,
+  INTERNAL_ERROR: 500,
+  DATABASE_ERROR: 500,
+  EXTERNAL_SERVICE_ERROR: 502,
+  SERVICE_UNAVAILABLE: 503,
+  // Outbound-fetch safety (utils/validate-external-url): a URL refused for SSRF
+  // safety, and a fetch that timed out / exceeded the size cap / failed to decode.
+  EXTERNAL_URL_BLOCKED: 400,
+  EXTERNAL_REQUEST_FAILED: 502,
+  FILENAME_INVALID: 400,
+  EXTENSION_BLOCKED: 400,
+  MIME_BLOCKED: 415,
+  MIME_NOT_ALLOWED: 415,
+  SIZE_EXCEEDED: 413,
+  MAGIC_BYTE_MISMATCH: 400,
+  SVG_SANITIZATION_FAILED: 400,
+  UNSUPPORTED_FOR_BACKEND: 415,
+  // Plan B — schema bookkeeping consolidation.
+  NEXTLY_LEGACY_BOOKKEEPING_DETECTED: 409,
+  NEXTLY_UPGRADE_TABLE_NAME_COLLISION: 409,
+  NEXTLY_UPGRADE_IN_PROGRESS: 409,
+  // Plan C2 — nextly migrate phases.
+  NEXTLY_MIGRATE_LOCK_BUSY: 409,
+  NEXTLY_BASELINE_LOCK_NOT_HELD: 409,
+  NEXTLY_RESOLVE_LOCK_NOT_HELD: 409,
+  // Boot refused to serve: the migrate lock stayed held past the wait deadline,
+  // so this process never established whether the schema matches the code. 503
+  // rather than 409 — a load balancer should take the instance out of rotation
+  // and retry it, which is exactly the recovery this refusal wants.
+  NEXTLY_BOOT_MIGRATIONS_NOT_RUN: 503,
+  // Still running rather than refused. 503 for the same reason: retry shortly.
+  NEXTLY_BOOT_MIGRATIONS_PENDING: 503,
+  NEXTLY_CORE_DESTRUCTIVE_REFUSED: 409,
+  NEXTLY_MIGRATION_DRIFT: 409,
+  NEXTLY_MIGRATION_APPLY_FAILED: 500,
+  // Plan C3 — migrate:resolve recovery command.
+  NEXTLY_MIGRATION_FILE_MISSING: 404,
+  NEXTLY_MIGRATION_SNAPSHOT_MISSING: 404,
+  NEXTLY_MIGRATION_RESOLVE_DRIFT: 409,
+  NEXTLY_MIGRATION_RESOLVE_PRECONDITION: 409,
+  // Plan D — UI schema support.
+  NEXTLY_UI_SCHEMA_INVALID: 400,
+  NEXTLY_SCHEMA_SLUG_COLLISION: 409,
+  NEXTLY_SCHEMA_RELATION_TARGET_MISSING: 400,
+  // Plugin platform (P2b) — schema extend (contributes.extend) + relations (D15).
+  NEXTLY_SCHEMA_EXTEND_TARGET_UNKNOWN: 400,
+  NEXTLY_SCHEMA_EXTEND_FIELD_DUPLICATE: 409,
+  NEXTLY_SCHEMA_CROSS_PLUGIN_RELATION: 409,
+  // Plugin platform (P2c) — framework remap (.rename()).
+  NEXTLY_SCHEMA_RENAME_UNKNOWN_TARGET: 400,
+  // Plugin platform — a declared admin.clientConfig that cannot be delivered
+  // to the browser, refused at boot rather than serialized mangled.
+  NEXTLY_PLUGIN_CLIENT_CONFIG_INVALID: 500,
+  // Plugin platform — a contributed admin widget that cannot be delivered to
+  // the browser. Refused at boot because it is serialized into the ONE
+  // `/api/admin-meta/workspace` payload: a value `JSON.stringify` throws on
+  // fails that request for every admin, not just the widget's own card.
+  NEXTLY_PLUGIN_ADMIN_WIDGET_INVALID: 500,
+  // Plugin platform (P0) — boot-time plugin dependency/version resolution.
+  PLUGIN_RESOLUTION_ERROR: 500,
+  // Plugin platform (P4) — contributes.routes collection (D25).
+  NEXTLY_ROUTE_COLLISION: 409,
+  NEXTLY_ROUTE_INVALID_PATH: 400,
+  // An email transport whose library is an optional peer dependency the host
+  // has not installed. 503 rather than 500: the request is not malformed and
+  // nothing is broken, the install simply cannot carry it out yet, and the
+  // remedy is one command on the server rather than a change by the caller.
+  NEXTLY_EMAIL_TRANSPORT_UNAVAILABLE: 503,
+  // The tooling that compiles `nextly.config.ts` is an optional peer the host
+  // has not installed. 503 rather than 500 for the same reason as the mail
+  // transport above: nothing is broken and the request is not malformed, the
+  // install simply cannot carry it out until one command is run.
+  NEXTLY_CONFIG_TOOLING_UNAVAILABLE: 503
+};
+var CANONICAL_CODE_FOR_STATUS = [
+  "VALIDATION_ERROR",
+  "AUTH_REQUIRED",
+  "FORBIDDEN",
+  "NOT_FOUND",
+  "CONFLICT",
+  "PAYLOAD_TOO_LARGE",
+  "UNSUPPORTED_MEDIA_TYPE",
+  "RATE_LIMITED",
+  "EXTERNAL_SERVICE_ERROR",
+  "SERVICE_UNAVAILABLE"
+];
+({
+  ...Object.fromEntries(
+    CANONICAL_CODE_FOR_STATUS.map((code) => [NEXTLY_ERROR_STATUS[code], code])
+  )});
+var DB_ERROR_MAPPING = {
+  "unique-violation": {
+    code: "DUPLICATE",
+    statusCode: 409,
+    publicMessage: "Resource already exists."
+  },
+  "fk-violation": {
+    code: "VALIDATION_ERROR",
+    statusCode: 400,
+    publicMessage: "Referenced record does not exist."
+  },
+  "not-null-violation": {
+    code: "VALIDATION_ERROR",
+    statusCode: 400,
+    publicMessage: "A required field is missing."
+  },
+  constraint: {
+    code: "VALIDATION_ERROR",
+    statusCode: 400,
+    publicMessage: "The provided data violates a constraint."
+  },
+  deadlock: {
+    code: "CONFLICT",
+    statusCode: 409,
+    publicMessage: "The operation could not be completed. Please retry."
+  },
+  "serialization-failure": {
+    code: "CONFLICT",
+    statusCode: 409,
+    publicMessage: "The operation could not be completed. Please retry."
+  },
+  timeout: {
+    code: "DATABASE_ERROR",
+    statusCode: 500,
+    publicMessage: "The operation timed out. Please try again."
+  },
+  "connection-lost": {
+    code: "DATABASE_ERROR",
+    statusCode: 500,
+    publicMessage: "A temporary database error occurred. Please try again."
+  },
+  syntax: {
+    code: "INTERNAL_ERROR",
+    statusCode: 500,
+    publicMessage: "An unexpected error occurred."
+  },
+  internal: {
+    code: "INTERNAL_ERROR",
+    statusCode: 500,
+    publicMessage: "An unexpected error occurred."
+  }
+};
+var NEXTLY_ERROR_BRAND = Symbol.for("nextly/NextlyError");
+function hasBrand(value) {
+  if (value === null || typeof value !== "object" && typeof value !== "function") {
+    return false;
+  }
+  return value[NEXTLY_ERROR_BRAND] === true;
+}
+var NextlyError = class _NextlyError extends Error {
+  code;
+  statusCode;
+  publicMessage;
+  publicData;
+  messageKey;
+  logMessage;
+  logContext;
+  cause;
+  timestamp;
+  constructor(opts) {
+    super(opts.publicMessage);
+    this.name = "NextlyError";
+    this.code = opts.code;
+    this.publicMessage = opts.publicMessage;
+    this.publicData = opts.publicData;
+    this.messageKey = opts.messageKey;
+    this.logMessage = opts.logMessage;
+    this.logContext = opts.logContext;
+    this.cause = opts.cause;
+    this.timestamp = /* @__PURE__ */ new Date();
+    this.statusCode = _NextlyError.resolveStatusCode(opts);
+    Error.captureStackTrace?.(this, _NextlyError);
+  }
+  static {
+    _NextlyError.prototype[NEXTLY_ERROR_BRAND] = true;
+  }
+  static resolveStatusCode(opts) {
+    if (typeof opts.statusCode === "number") return opts.statusCode;
+    if (opts.code in NEXTLY_ERROR_STATUS) {
+      return NEXTLY_ERROR_STATUS[opts.code];
+    }
+    return 500;
+  }
+  /** HTTP-safe JSON. Strips logMessage / logContext / cause / stack. */
+  toResponseJSON(requestId) {
+    const json = {
+      code: String(this.code),
+      message: this.publicMessage,
+      requestId
+    };
+    if (this.messageKey) json.messageKey = this.messageKey;
+    if (this.publicData !== void 0) json.data = this.publicData;
+    return json;
+  }
+  /** Operator-facing JSON for log lines. Includes everything. */
+  toLogJSON(requestId) {
+    return {
+      code: this.code,
+      statusCode: this.statusCode,
+      publicMessage: this.publicMessage,
+      messageKey: this.messageKey,
+      logMessage: this.logMessage,
+      logContext: this.logContext,
+      cause: this.cause ? {
+        name: this.cause.name,
+        message: this.cause.message,
+        stack: this.cause.stack
+      } : void 0,
+      timestamp: this.timestamp.toISOString(),
+      requestId
+    };
+  }
+  // ────────────────────────────────────────────────────────────────────
+  // Static factories — the recommended throw site for every common case.
+  // Public messages here follow the §13.8 rubric: complete sentence,
+  // generic, no identifiers, no value echoing, no policy hints.
+  // ────────────────────────────────────────────────────────────────────
+  static invalidCredentials(opts) {
+    return new _NextlyError({
+      code: "AUTH_INVALID_CREDENTIALS",
+      publicMessage: "Invalid email or password.",
+      logMessage: "Login failed",
+      logContext: opts?.logContext
+    });
+  }
+  static authRequired(opts) {
+    return new _NextlyError({
+      code: "AUTH_REQUIRED",
+      publicMessage: "Authentication required.",
+      logContext: opts?.logContext
+    });
+  }
+  /**
+   * Distinct from `authRequired`: the caller was authenticated but the
+   * session token expired. Clients key on the TOKEN_EXPIRED *code* to
+   * silently refresh and retry rather than redirecting to login; the public
+   * message stays the generic spec §13.6 string ("Authentication required.")
+   * so the wire never reveals the session state — same as `authRequired`.
+   */
+  static tokenExpired(opts) {
+    return new _NextlyError({
+      code: "TOKEN_EXPIRED",
+      publicMessage: "Authentication required.",
+      logContext: opts?.logContext
+    });
+  }
+  static notFound(opts) {
+    return new _NextlyError({
+      code: "NOT_FOUND",
+      publicMessage: opts?.message ?? "Not found.",
+      cause: opts?.cause,
+      logContext: opts?.logContext
+    });
+  }
+  static forbidden(opts) {
+    return new _NextlyError({
+      code: "FORBIDDEN",
+      publicMessage: "You don't have permission to perform this action.",
+      cause: opts?.cause,
+      logContext: opts?.logContext
+    });
+  }
+  /**
+   * A call the caller got wrong, where naming the mistake IS the value of the
+   * error.
+   *
+   * The only factory that takes its public message from the caller. The
+   * generic messages elsewhere exist so an HTTP response cannot leak internal
+   * detail; this one is for arguments and configuration a developer controls
+   * and must be told about — a missing option, an unusable combination — where
+   * `internal()` would reduce the one useful sentence to "An unexpected error
+   * occurred." Do not pass user-supplied data through it.
+   */
+  static invalidInput(opts) {
+    return new _NextlyError({
+      code: "INVALID_INPUT",
+      publicMessage: opts.message,
+      logContext: opts.logContext
+    });
+  }
+  static validation(opts) {
+    return new _NextlyError({
+      code: "VALIDATION_ERROR",
+      publicMessage: "Validation failed.",
+      publicData: { errors: opts.errors },
+      cause: opts.cause,
+      logContext: opts.logContext
+    });
+  }
+  static conflict(opts) {
+    return new _NextlyError({
+      code: "CONFLICT",
+      publicMessage: opts?.message ?? "The resource has changed since you last loaded it. Please refresh and try again.",
+      cause: opts?.cause,
+      logContext: { reason: opts?.reason, ...opts?.logContext }
+    });
+  }
+  static duplicate(opts) {
+    return new _NextlyError({
+      code: "DUPLICATE",
+      publicMessage: "Resource already exists.",
+      logContext: opts?.logContext
+    });
+  }
+  static rateLimited(opts) {
+    return new _NextlyError({
+      code: "RATE_LIMITED",
+      publicMessage: "Too many requests. Please try again later.",
+      publicData: opts?.retryAfterSeconds !== void 0 ? { retryAfterSeconds: opts.retryAfterSeconds } : void 0,
+      logContext: opts?.logContext
+    });
+  }
+  static internal(opts) {
+    return new _NextlyError({
+      code: "INTERNAL_ERROR",
+      publicMessage: "An unexpected error occurred.",
+      cause: opts?.cause,
+      logContext: opts?.logContext
+    });
+  }
+  // Accepts an optional `logMessage` override so callers (e.g. the health
+  // route) can record a specific operator narrative ("Health check failed")
+  // while the public message stays canonical per spec §13.8.5.
+  static serviceUnavailable(opts) {
+    return new _NextlyError({
+      code: "SERVICE_UNAVAILABLE",
+      publicMessage: opts?.publicMessage ?? "Service unavailable. Please try again later.",
+      logMessage: opts?.logMessage,
+      cause: opts?.cause,
+      logContext: opts?.logContext
+    });
+  }
+  /**
+   * Convert a DbError (or arbitrary unknown thrown by the DB layer) to a
+   * NextlyError with a generic public message and rich logContext. Used by
+   * `withDbErrors` for auto-conversion (Pattern A) and by services that
+   * catch DB errors at boundaries (Pattern B). Spec §8.2 mapping table.
+   *
+   * Never leaks DB driver text, constraint names, or table names into
+   * `publicMessage`. All DB context goes into `logContext`. The original
+   * DbError is preserved as `cause`.
+   */
+  static fromDatabaseError(error) {
+    if (isDbError(error)) {
+      const mapping = DB_ERROR_MAPPING[error.kind];
+      const logContext = {
+        dbKind: error.kind,
+        dialect: error.dialect
+      };
+      if (error.code !== void 0) logContext.dbCode = error.code;
+      if (error.meta !== void 0) logContext.meta = error.meta;
+      return new _NextlyError({
+        code: mapping.code,
+        statusCode: mapping.statusCode,
+        publicMessage: mapping.publicMessage,
+        logMessage: "Database error",
+        logContext,
+        cause: error
+      });
+    }
+    return new _NextlyError({
+      code: "INTERNAL_ERROR",
+      statusCode: 500,
+      publicMessage: "An unexpected error occurred.",
+      logMessage: "Non-DbError passed to fromDatabaseError",
+      cause: error instanceof Error ? error : void 0,
+      logContext: error instanceof Error ? void 0 : { value: String(error) }
+    });
+  }
+  // ────────────────────────────────────────────────────────────────────
+  // Type guards. Structural rather than `instanceof` so they survive
+  // package-boundary mismatches (one consumer's NextlyError is a
+  // different module instance from another's).
+  // ────────────────────────────────────────────────────────────────────
+  static is(err) {
+    return hasBrand(err);
+  }
+  static isCode(err, code) {
+    return hasBrand(err) && err.code === code;
+  }
+  static isNotFound(err) {
+    return _NextlyError.isCode(err, "NOT_FOUND");
+  }
+  static isValidation(err) {
+    return _NextlyError.isCode(err, "VALIDATION_ERROR");
+  }
+  static isAuthRequired(err) {
+    return _NextlyError.isCode(err, "AUTH_REQUIRED");
+  }
+  static isForbidden(err) {
+    return _NextlyError.isCode(err, "FORBIDDEN");
+  }
+  static isConflict(err) {
+    return _NextlyError.isCode(err, "CONFLICT");
+  }
+  static isRateLimited(err) {
+    return _NextlyError.isCode(err, "RATE_LIMITED");
+  }
+};
+
 // src/adapter.ts
 var VercelBlobStorageAdapter = class {
   /**
@@ -47,14 +474,25 @@ var VercelBlobStorageAdapter = class {
     const mimeType = (options.contentType || options.mimeType || "").toLowerCase().trim();
     const filename = (options.filename || "").toLowerCase();
     const ext = filename.includes(".") ? filename.slice(filename.lastIndexOf(".") + 1) : "";
-    const isSvg = mimeType === "image/svg+xml" || ext === "svg" || ext === "svgz";
     const isHtml = mimeType === "text/html" || mimeType === "application/xhtml+xml" || ext === "html" || ext === "htm" || ext === "xhtml";
-    if (isSvg || isHtml) {
-      const kind = isSvg ? "SVG" : "HTML";
-      throw new Error(
-        `[nextly/storage-vercel-blob] ${kind} uploads are rejected on Vercel Blob \u2014 the platform cannot serve them with attachment-disposition or a restrictive CSP, so they would be stored XSS. Use the S3 / R2 adapter for ${kind} files, or convert to a raster format (PNG/WebP).`
-      );
+    if (isHtml) {
+      throw NextlyError.validation({
+        errors: [
+          {
+            path: "file",
+            code: "UNSUPPORTED_FOR_BACKEND",
+            message: "HTML files cannot be hosted on Vercel Blob. Use the S3 or R2 adapter, or upload as another format."
+          }
+        ],
+        logContext: {
+          adapter: "vercel-blob",
+          claimedMimeType: options.mimeType,
+          reason: "vercel-blob-rejects-html",
+          filename: options.filename
+        }
+      });
     }
+    const isSvg = mimeType === "image/svg+xml" || ext === "svg" || ext === "svgz";
     const pathname = this.buildPathname(options.filename, options.folder);
     const result = await blob.put(pathname, buffer, {
       access: this.resolvedConfig.access,
@@ -63,8 +501,9 @@ var VercelBlobStorageAdapter = class {
       addRandomSuffix: this.resolvedConfig.addRandomSuffix,
       cacheControlMaxAge: this.resolvedConfig.cacheControlMaxAge
     });
+    const url = isSvg && options.contentDisposition === "attachment" ? result.downloadUrl : result.url;
     return {
-      url: result.url,
+      url,
       path: result.url
     };
   }