feat(storage): point a full trial account at the upgrade rather than at nothing

Being told "storage limit exceeded" when the limit is the free trial's three
gigabytes is a dead end. The account is not full because it stores a lot; it is
capped because it has not subscribed, and deleting files buys back very little.

The refusal now says which ceiling it is and carries its own error code, so the
toast can offer a link to the billing settings on the trial ceiling and stay
quiet on the paid one, where subscribing changes nothing.

The code had to survive the trip to the toast, which meant the upload helpers
throwing something that carries it rather than a bare Error. Two places were
dropping the server's message on the floor entirely: adding a version reported
"Failed to initialize upload" whatever the server said, and every asset upload
in the pane rewrote its own failure text.

lib/api-response.ts

@@ -67,6 +67,12 @@ export const ErrorCode = {
 
   // Storage errors
   STORAGE_LIMIT_EXCEEDED: 'STORAGE_LIMIT_EXCEEDED',
+  /**
+   * Out of room because the account has not paid, rather than because the plan
+   * is full. Its own code so the client can offer the upgrade, which is the
+   * actual remedy here and is no help at all on the paid ceiling.
+   */
+  TRIAL_STORAGE_LIMIT_EXCEEDED: 'TRIAL_STORAGE_LIMIT_EXCEEDED',
 } as const;
 
 /**
@@ -175,4 +181,13 @@ export const apiErrors = {
   storageExceeded: (
     message = 'Storage limit exceeded. Please delete some files to free up space.'
   ) => errorResponse(message, HttpStatus.INSUFFICIENT_STORAGE, ErrorCode.STORAGE_LIMIT_EXCEEDED),
+
+  /**
+   * The same 507, for an account that is out of room because it is on the free
+   * trial. Telling this caller to delete files is advice that does not apply:
+   * they have three gigabytes because they have not subscribed, not because they
+   * have filled two hundred.
+   */
+  trialStorageExceeded: (message: string) =>
+    errorResponse(message, HttpStatus.INSUFFICIENT_STORAGE, ErrorCode.TRIAL_STORAGE_LIMIT_EXCEEDED),
 };

lib/client/api-error.ts

@@ -0,0 +1,101 @@
+// What a failed API call is worth showing the person who made it.
+//
+// Every route answers with `{ error, code? }`, and the code is the part that
+// says whether there is anything the caller can do. Losing it on the way to a
+// toast is how a full trial account ends up reading "Failed to upload" and
+// trying the same upload again.
+
+import { toast } from 'sonner';
+
+/** The machine-readable half of an error response. Mirrors ErrorCode in lib/api-response.ts. */
+export const API_ERROR_CODES = {
+  /** Out of room because the account has not subscribed, not because the plan is full. */
+  TRIAL_STORAGE_LIMIT_EXCEEDED: 'TRIAL_STORAGE_LIMIT_EXCEEDED',
+} as const;
+
+export interface ApiErrorPayload {
+  error?: string;
+  code?: string;
+}
+
+/**
+ * A failure that came back from our own API, with the code still attached.
+ *
+ * The upload helpers throw rather than return, so without this the code is gone
+ * by the time anything is in a position to show it.
+ */
+export class ApiRequestError extends Error {
+  readonly code: string | null;
+
+  constructor(message: string, code?: string | null) {
+    super(message);
+    this.name = 'ApiRequestError';
+    this.code = code ?? null;
+  }
+}
+
+/** Builds the error to throw from a parsed `{ error, code }` body. */
+export function apiRequestError(
+  payload: ApiErrorPayload | null,
+  fallback: string
+): ApiRequestError {
+  return new ApiRequestError(payload?.error || fallback, payload?.code);
+}
+
+function codeOf(source: unknown): string | null {
+  if (source instanceof ApiRequestError) return source.code;
+  if (source && typeof source === 'object' && 'code' in source) {
+    const code = (source as ApiErrorPayload).code;
+    return typeof code === 'string' ? code : null;
+  }
+  return null;
+}
+
+function messageOf(source: unknown, fallback: string): string {
+  if (source instanceof Error) return source.message || fallback;
+  if (source && typeof source === 'object' && 'error' in source) {
+    const message = (source as ApiErrorPayload).error;
+    if (typeof message === 'string' && message) return message;
+  }
+  return fallback;
+}
+
+export interface ToastApiErrorOptions {
+  /** Prepended as `${prefix}: ${message}`, for per-file failures in a batch. */
+  prefix?: string;
+}
+
+/**
+ * Shows an API failure, with a way out attached when there is one.
+ *
+ * Takes either a parsed response body or a thrown error, so the same call works
+ * whether the caller checked `res.ok` itself or caught what an upload helper
+ * threw. On the trial storage ceiling it adds a link to the billing settings,
+ * because subscribing is the only thing that makes the upload possible and the
+ * uploader has no way to know that from "storage limit exceeded".
+ */
+export function toastApiError(
+  source: unknown,
+  fallback: string,
+  options: ToastApiErrorOptions = {}
+): void {
+  const message = messageOf(source, fallback);
+  const text = options.prefix ? `${options.prefix}: ${message}` : message;
+
+  if (codeOf(source) === API_ERROR_CODES.TRIAL_STORAGE_LIMIT_EXCEEDED) {
+    toast.error(text, {
+      // Longer than a plain error: this one is asking for a decision rather than
+      // just reporting, and it disappears under the cursor at the usual timing.
+      duration: 12000,
+      action: {
+        label: 'See plans',
+        onClick: () => {
+          window.location.href = '/settings';
+        },
+      },
+    });
+    return;
+  }
+
+  toast.error(text);
+}

lib/client/project-video-upload.ts

@@ -3,6 +3,7 @@
 import { resolvePublicBunnyCdnHostname } from '@/lib/bunny-cdn';
 import { cleanupPendingR2VideoUpload, uploadVideoToR2 } from '@/lib/client/r2-video-upload';
 import type { DirectUploadProvider } from '@/components/video-page/types';
+import { apiRequestError } from '@/lib/client/api-error';
 
 export const VIDEO_FILE_EXTENSIONS = ['mp4', 'webm', 'ogg', 'mov', 'm4v', 'mkv'];
 
@@ -143,7 +144,7 @@ export async function uploadProjectVideo(
       } | null;
 
       if (!createResponse.ok) {
-        throw new Error(createPayload?.error || 'Failed to create video');
+        throw apiRequestError(createPayload, 'Failed to create video');
       }
 
       pendingCleanup = null;
@@ -171,7 +172,7 @@ export async function uploadProjectVideo(
     } | null;
 
     if (!initResponse.ok || !initPayload?.data) {
-      throw new Error(initPayload?.error || 'Failed to initialize upload');
+      throw apiRequestError(initPayload, 'Failed to initialize upload');
     }
 
     const { videoId, libraryId, signature, expirationTime, uploadToken } = initPayload.data;
@@ -243,7 +244,7 @@ export async function uploadProjectVideo(
     } | null;
 
     if (!createResponse.ok) {
-      throw new Error(createPayload?.error || 'Failed to create video');
+      throw apiRequestError(createPayload, 'Failed to create video');
     }
 
     pendingCleanup = null;

lib/client/r2-asset-video-upload.ts

@@ -1,4 +1,5 @@
 import { captureVideoThumbnail } from '@/lib/client/video-thumbnail';
+import { apiRequestError } from '@/lib/client/api-error';
 import { uploadBytesWithProgress, type UploadProgressHandler } from '@/lib/client/r2-video-upload';
 
 export type R2AssetVideoInitResponse = {
@@ -39,7 +40,7 @@ export async function initR2AssetVideoUpload(
     error?: string;
   } | null;
   if (!initRes.ok || !initPayload?.data) {
-    throw new Error(initPayload?.error || 'Failed to initialize video upload');
+    throw apiRequestError(initPayload, 'Failed to initialize video upload');
   }
 
   return initPayload.data;

lib/client/r2-video-upload.ts

@@ -1,4 +1,5 @@
 import { captureVideoThumbnail } from '@/lib/client/video-thumbnail';
+import { apiRequestError } from '@/lib/client/api-error';
 import {
   getMultipartProgressPercent,
   getPartByteRange,
@@ -151,7 +152,7 @@ async function completeMultipartUpload(
 
   if (!res.ok) {
     const payload = (await res.json().catch(() => null)) as { error?: string } | null;
-    throw new Error(payload?.error || 'Failed to complete multipart upload');
+    throw apiRequestError(payload, 'Failed to complete multipart upload');
   }
 }
 
@@ -243,7 +244,7 @@ export async function initR2VideoUpload(
     error?: string;
   } | null;
   if (!initRes.ok || !initPayload?.data) {
-    throw new Error(initPayload?.error || 'Failed to initialize video upload');
+    throw apiRequestError(initPayload, 'Failed to initialize video upload');
   }
 
   return initPayload.data;