feat(mega): optional storage-upgrade referral link

- VITE_MEGA_REFERRAL_URL env var (verbatim link from MEGA's referral
  dashboard); unset = no link ever rendered, so forks/deploys never
  inherit a referral code. Guarded to https mega.nz/mega.io URLs.
- Cloud page shows a disclosed upgrade link under the MEGA quota bar
  once usage reaches 80% (the bar's existing warning color).
- uploadFile maps megajs EOVERQUOTA (-17) to a typed QUOTA_EXCEEDED
  error with an actionable message instead of the raw error text.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: Gnathonic

CLAUDE.md

@@ -260,6 +260,7 @@ Create a `.env.local` file for cloud provider integration:
 VITE_GDRIVE_CLIENT_ID=your_client_id
 VITE_GDRIVE_API_KEY=your_api_key
 VITE_ONEDRIVE_CLIENT_ID=your_azure_app_client_id
+VITE_MEGA_REFERRAL_URL=https://mega.nz/aff=your_referral_code
 ```
 
 - `VITE_GDRIVE_*`: required only for Google Drive sync.
@@ -268,7 +269,12 @@ VITE_ONEDRIVE_CLIENT_ID=your_azure_app_client_id
   deploy origin as a **Single-page application** redirect URI. Scopes used:
   `Files.ReadWrite`, `offline_access`, `User.Read`. When unset, the OneDrive
   option is hidden from the cloud screen.
-- MEGA, WebDAV, and Local Folder require no env vars.
+- `VITE_MEGA_REFERRAL_URL`: optional. Paste a link from MEGA's referral
+  dashboard verbatim (must be an https mega.nz/mega.io URL, or it is ignored).
+  When set, users at ≥80% of their MEGA quota see a disclosed upgrade link on
+  the cloud page; when unset, no link is rendered. Deliberately env-scoped so
+  forks/deploys never inherit someone else's referral code.
+- MEGA, WebDAV, and Local Folder require no env vars to function.
 
 ## Testing
 

README.md

@@ -196,6 +196,9 @@ For OneDrive, register an Azure AD app ("common" authority) and add your deploy
 origin as a **Single-page application** redirect URI. When unset, the OneDrive
 option is hidden. MEGA, WebDAV, and Local Folder need no configuration.
 
+Optionally, set `VITE_MEGA_REFERRAL_URL` to a MEGA referral link to show a
+disclosed storage-upgrade link to users nearing their MEGA quota.
+
 ## 💬 Community
 
 Wanna chat with the devs? Share your hopes, dreams, and issues (with Mokuro Reader specifically)? Come join the [Mokuro Reader Discord](https://discord.gg/AU5pjjSQBw)!

src/lib/util/sync/providers/mega/mega-provider.test.ts

@@ -495,3 +495,26 @@ describe('MegaProvider ghost-node handling', () => {
     expect(Object.keys(storage.files).sort()).toEqual(['ghost', 'root']);
   });
 });
+
+describe('MegaProvider over-quota handling', () => {
+  it('uploadFile maps EOVERQUOTA to a typed QUOTA_EXCEEDED error with a friendly message', async () => {
+    const folder: any = {
+      name: 'mokuro-reader',
+      directory: true,
+      upload: vi.fn((_opts: any, _buf: any, cb: (e: Error | null, f?: any) => void) => {
+        queueMicrotask(() => cb(new Error('EOVERQUOTA (-17): Request over quota')));
+      })
+    };
+    storageState.files = { root: folder };
+    const provider = new MegaProvider();
+    await provider.whenReady();
+    await provider.login({ email: 'a@b.c', password: 'secret' });
+
+    await expect(
+      provider.uploadFile('volume-data.json', new Uint8Array([1]))
+    ).rejects.toMatchObject({
+      code: 'QUOTA_EXCEEDED',
+      message: expect.stringContaining('storage is full')
+    });
+  });
+});

src/lib/util/sync/providers/mega/mega-provider.ts

@@ -100,6 +100,12 @@ function isMegaNotFoundError(error: unknown): boolean {
   return message.includes('ENOENT') || message.includes('(-9)');
 }
 
+/** megajs surfaces a full account as `EOVERQUOTA (-17)`. */
+function isMegaOverQuotaError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.includes('EOVERQUOTA') || message.includes('(-17)');
+}
+
 /**
  * Smart retry wrapper for MEGA operations that may fail due to stale cache
  * When two devices sync back and forth, file IDs change but local cache is stale
@@ -800,6 +806,15 @@ export class MegaProvider implements SyncProvider {
 
       return fileId;
     } catch (error) {
+      // Typed QUOTA_EXCEEDED with a message users can act on, instead of
+      // megajs's raw "EOVERQUOTA (-17): Request over quota".
+      if (isMegaOverQuotaError(error)) {
+        throw new ProviderError(
+          'MEGA storage is full — free up space or upgrade your plan',
+          'mega',
+          'QUOTA_EXCEEDED'
+        );
+      }
       throw new ProviderError(
         `Failed to upload volume CBZ: ${error instanceof Error ? error.message : 'Unknown error'}`,
         'mega',

src/lib/util/sync/providers/mega/referral.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+import {
+  getMegaReferralUrl,
+  shouldOfferMegaUpgrade,
+  MEGA_UPGRADE_OFFER_THRESHOLD
+} from './referral';
+
+describe('getMegaReferralUrl', () => {
+  it('returns null when the env var is unset or empty', () => {
+    expect(getMegaReferralUrl({})).toBeNull();
+    expect(getMegaReferralUrl({ VITE_MEGA_REFERRAL_URL: '' })).toBeNull();
+    expect(getMegaReferralUrl({ VITE_MEGA_REFERRAL_URL: undefined })).toBeNull();
+  });
+
+  it('returns the URL for https MEGA domains', () => {
+    expect(getMegaReferralUrl({ VITE_MEGA_REFERRAL_URL: 'https://mega.nz/aff=AbCd1234' })).toBe(
+      'https://mega.nz/aff=AbCd1234'
+    );
+    expect(getMegaReferralUrl({ VITE_MEGA_REFERRAL_URL: 'https://mega.io/pro?aff=x' })).toBe(
+      'https://mega.io/pro?aff=x'
+    );
+  });
+
+  it('rejects non-MEGA hosts and non-https URLs (misconfiguration guard)', () => {
+    expect(getMegaReferralUrl({ VITE_MEGA_REFERRAL_URL: 'https://example.com/aff=x' })).toBeNull();
+    expect(
+      getMegaReferralUrl({ VITE_MEGA_REFERRAL_URL: 'https://mega.nz.evil.com/aff=x' })
+    ).toBeNull();
+    expect(getMegaReferralUrl({ VITE_MEGA_REFERRAL_URL: 'http://mega.nz/aff=x' })).toBeNull();
+    expect(getMegaReferralUrl({ VITE_MEGA_REFERRAL_URL: 'not a url' })).toBeNull();
+  });
+});
+
+describe('shouldOfferMegaUpgrade', () => {
+  const url = 'https://mega.nz/aff=x';
+
+  it('is false without a referral URL, without quota data, or with an unknown total', () => {
+    expect(shouldOfferMegaUpgrade({ used: 100, total: 100, available: 0 }, null)).toBe(false);
+    expect(shouldOfferMegaUpgrade(null, url)).toBe(false);
+    expect(shouldOfferMegaUpgrade({ used: 100, total: null, available: null }, url)).toBe(false);
+  });
+
+  it('is true at or above the offer threshold and false below it', () => {
+    const total = 1000;
+    const atThreshold = Math.ceil(total * MEGA_UPGRADE_OFFER_THRESHOLD);
+    expect(
+      shouldOfferMegaUpgrade({ used: atThreshold, total, available: total - atThreshold }, url)
+    ).toBe(true);
+    expect(shouldOfferMegaUpgrade({ used: total, total, available: 0 }, url)).toBe(true);
+    expect(shouldOfferMegaUpgrade({ used: 500, total, available: 500 }, url)).toBe(false);
+  });
+});

src/lib/util/sync/providers/mega/referral.ts

@@ -0,0 +1,45 @@
+import type { StorageQuota } from '../../provider-interface';
+
+/**
+ * MEGA storage-upgrade referral offer.
+ *
+ * Configured via VITE_MEGA_REFERRAL_URL (paste the link generated by MEGA's
+ * referral dashboard verbatim). When unset, no upgrade link is ever rendered —
+ * same opt-in pattern as VITE_ONEDRIVE_CLIENT_ID, so forks and deploys never
+ * inherit someone else's referral code by accident.
+ */
+
+/** Offer the upgrade once usage reaches the quota bar's warning color. */
+export const MEGA_UPGRADE_OFFER_THRESHOLD = 0.8;
+
+const MEGA_HOSTS = ['mega.nz', 'mega.io'];
+
+/**
+ * The configured referral URL, or null when unset or not an https MEGA link.
+ * The host check is a misconfiguration guard: the app should never render an
+ * "upgrade MEGA" link that leads anywhere but MEGA.
+ */
+export function getMegaReferralUrl(
+  env: Record<string, string | undefined> = import.meta.env
+): string | null {
+  const url = env?.VITE_MEGA_REFERRAL_URL;
+  if (typeof url !== 'string' || url === '') return null;
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== 'https:') return null;
+    const host = parsed.hostname.toLowerCase();
+    if (!MEGA_HOSTS.some((h) => host === h || host.endsWith(`.${h}`))) return null;
+  } catch {
+    return null;
+  }
+  return url;
+}
+
+/** True when a referral link is configured and usage is at/above the threshold. */
+export function shouldOfferMegaUpgrade(
+  quota: StorageQuota | null,
+  referralUrl: string | null
+): boolean {
+  if (!referralUrl || !quota || quota.total === null || quota.total <= 0) return false;
+  return quota.used / quota.total >= MEGA_UPGRADE_OFFER_THRESHOLD;
+}

src/lib/views/CloudView.svelte

@@ -22,10 +22,17 @@
   import { unifiedSyncService } from '$lib/util/sync/unified-sync-service';
   import { cacheManager } from '$lib/util/sync/cache-manager';
   import { isFilesystemProviderSupported } from '$lib/util/sync/providers/filesystem/feature-detect';
+  import {
+    getMegaReferralUrl,
+    shouldOfferMegaUpgrade
+  } from '$lib/util/sync/providers/mega/referral';
   import { PROVIDER_LABELS } from '$lib/util/sync/provider-display';
 
   const CLOUD_ROOT_FOLDER = 'mokuro-reader';
 
+  // MEGA upgrade referral link (null unless VITE_MEGA_REFERRAL_URL is set).
+  const megaReferralUrl = getMegaReferralUrl();
+
   // Get store references for auto-subscription
   const providerStatusStore = providerManager.status;
   const cacheIsFetchingStore = cacheManager.isFetchingState;
@@ -1137,6 +1144,21 @@
                       (storageQuota.used / storageQuota.total) * 100
                     )}% used)
                   </div>
+                  {#if currentProvider === 'mega' && shouldOfferMegaUpgrade(storageQuota, megaReferralUrl)}
+                    <div class="pt-1 text-center">
+                      <a
+                        href={megaReferralUrl}
+                        target="_blank"
+                        rel="noopener noreferrer"
+                        class="text-sm text-primary-500 hover:underline"
+                      >
+                        Running low on space? Upgrade your MEGA storage
+                      </a>
+                      <p class="text-xs text-gray-500">
+                        Referral link — supports mokuro-reader at no extra cost to you
+                      </p>
+                    </div>
+                  {/if}
                 </div>
               {:else if storageQuota && storageQuota.used > 0}
                 <p class="text-sm text-gray-300">{formatBytes(storageQuota.used)} used</p>