The bcrypt package requires native build tooling. Ensure node-gyp, Python 3, and a C++ compiler (GCC on Linux, Xcode CLT on macOS, MSVC on Windows) are available before running npm install.

Project setup

1. Copy source - Place the contents of source/ into your project root or a subdirectory (e.g., ./seerr/). The server entry point is server/index.ts.

2. Configure TypeScript path aliases - The server code uses @server/* aliases. Merge the following into your tsconfig.json:

   {
     "compilerOptions": {
       "baseUrl": ".",
       "paths": {
         "@server/*": ["server/*"],
         "@app/*": ["src/*"]
       },
       "experimentalDecorators": true,
       "emitDecoratorMetadata": true
     }
   }
   

3. Configure Babel module-alias (for Jest / runtime) - Update babel.config.js module-resolver to include the same aliases.

4. Set environment variables:

   NODE_ENV=production
   PORT=5055
   CONFIG_DIRECTORY=/app/config       # SQLite DB and settings.json location
   LOG_LEVEL=info
   

5. Database - SQLite is used via TypeORM. The data source is initialized in server/datasource.ts. No external database setup is required for development; production runs migrations automatically on start.

6. Start the server:

   npx ts-node -r tsconfig-paths/register server/index.ts
   # or after build:
   node dist/server/index.js
   

Public API

Notification (enum)

export enum Notification {
  NONE               = 0,
  MEDIA_PENDING      = 2,
  MEDIA_APPROVED     = 4,
  MEDIA_AVAILABLE    = 8,
  MEDIA_FAILED       = 16,
  TEST_NOTIFICATION  = 32,
  MEDIA_DECLINED     = 64,
  MEDIA_AUTO_APPROVED = 128,
  ISSUE_CREATED      = 256,
  ISSUE_COMMENT      = 512,
  ISSUE_RESOLVED     = 1024,
  ISSUE_REOPENED     = 2048,
  MEDIA_AUTO_REQUESTED = 4096,
}

Use this enum when registering which events a notification agent should respond to, or when checking a user's notification preferences as a bitmask.

hasNotificationType

export const hasNotificationType = (
  types: Notification | Notification[],
  value: number
): boolean;

Checks whether a bitmask value includes any of the specified types. Pass a single Notification or an array; the function combines them and performs a bitwise test. TEST_NOTIFICATION is always implicitly included.

PreparedEmail

class PreparedEmail extends Email {
  public constructor(
    settings: NotificationAgentEmail,
    pgpKey?: string
  );
}

Constructs a fully configured email-templates instance with SMTP transport derived from NotificationAgentEmail settings. Pass an ASCII-armored OpenPGP public key as pgpKey to enable encrypted outbound email. Use this when building a custom notification agent or sending transactional email outside the built-in agents.

SortOptions (type)

export type SortOptions =
  | 'popularity.asc'   | 'popularity.desc'
  | 'release_date.asc' | 'release_date.desc'
  | 'vote_average.asc' | 'vote_average.desc'
  | 'first_air_date.asc' | 'first_air_date.desc'
  // ... full union in server/api/themoviedb/index.ts

Pass as the sortBy parameter to TMDB discover endpoints. Provides type-safe sort direction strings compatible with the TMDB v3 API.

Working examples

Scenario - Check if a user's notification bitmask includes a specific event

A user record stores notification preferences as a numeric bitmask. Before dispatching, verify the user actually wants the notification type.

import {
  Notification,
  hasNotificationType,
} from './server/lib/notifications/index';

const userNotificationTypes = Notification.MEDIA_APPROVED | Notification.MEDIA_AVAILABLE;

const shouldNotify = hasNotificationType(
  [Notification.MEDIA_APPROVED, Notification.MEDIA_DECLINED],
  userNotificationTypes
);

if (shouldNotify) {
  console.log('Dispatching approval/decline notification to user.');
}

Scenario - Send a custom email using PreparedEmail

Use PreparedEmail to deliver a templated transactional email with SMTP settings sourced from getSettings().

import PreparedEmail from './server/lib/email/index';
import { getSettings } from './server/lib/settings';

async function sendWelcomeEmail(recipientEmail: string) {
  const settings = getSettings().load();
  const emailAgent = settings.notifications.agents.email;

  const email = new PreparedEmail(emailAgent.options);

  await email.send({
    template: 'welcome',          // maps to a template directory under server/templates/
    message: { to: recipientEmail },
    locals: {
      applicationUrl: settings.main.applicationUrl,
      applicationTitle: settings.main.applicationTitle,
    },
  });
}

Scenario - Register a custom notification agent

Extend the notification manager with a bespoke agent that posts to an internal webhook.

import type {
  NotificationAgent,
  NotificationPayload,
} from './server/lib/notifications/agents/agent';
import notificationManager, {
  Notification,
} from './server/lib/notifications/index';

class InternalWebhookAgent implements NotificationAgent {
  public shouldSend(): boolean {
    return true;
  }

  public async send(
    type: Notification,
    payload: NotificationPayload
  ): Promise<boolean> {
    const res = await fetch('https://internal.example.com/hook', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ type, payload }),
    });
    return res.ok;
  }
}

// Register before app.prepare() in server/index.ts
notificationManager.registerAgents([new InternalWebhookAgent()]);

File walkthrough

• .github/ - GitHub Actions workflows for CI, release, Cypress, and CodeQL scanning; also houses issue/PR templates.
• .vscode/ - Shared workspace settings and extension recommendations for consistent developer experience.
• cypress/ - E2E tests; support/index.ts declares custom commands (login, loginAsAdmin, loginAsUser) on the Cypress global namespace.
• docs/ - Full GitBook documentation tree covering installation, reverse proxy, notification channel setup, and FAQ.
• public/ - Next.js static directory: logo SVG, preview JPEG, and any other public assets served at /.
• server/ - Core backend. Subdirectories: api/ (Plex, TMDB, Radarr, Sonarr clients), entity/ (TypeORM entities), job/ (cron scheduler), lib/ (notifications, settings, cache, email), middleware/, routes/, utils/.
• snap/ - Snapcraft YAML for distributing as a Linux snap package.
• src/ - Next.js frontend: React pages, components, hooks, i18n message catalogs.
• babel.config.js - Transpilation config shared between Next.js and Jest.
• cypress.config.ts - Base URL and spec patterns for the Cypress runner.
• next.config.js - Custom webpack config, environment variable exposure, and image domain allow-listing.
• overseerr-api.yml - OpenAPI 3.0 spec; mounted by Express and served as Swagger UI at /api-docs.
• tailwind.config.js - Design system: custom colors, fonts, and content paths for PurgeCSS.
• tsconfig.json - Compiler options including path aliases, decorator support, and strict mode settings.

Common pitfalls and fixes

• bcrypt native build failure - Install node-gyp globally (npm i -g node-gyp) and ensure Python 3 and a C++ build toolchain are on PATH before npm install.
• @server/* path aliases not resolved at runtime - Register tsconfig-paths before starting the server: node -r tsconfig-paths/register dist/server/index.js; or use tsconfig-paths-webpack-plugin in your custom webpack config.
• emitDecoratorMetadata missing - TypeORM entities use decorators; tsconfig.json must have both "experimentalDecorators": true and "emitDecoratorMetadata": true or entity relations will silently break.
• CSRF errors on API routes - The server mounts csurf middleware; API clients must forward the XSRF-TOKEN cookie value as the X-CSRF-Token header, or exempt paths explicitly in server/index.ts.
• SQLite file not found on first run - CONFIG_DIRECTORY must exist and be writable before startup; the TypeORM data source constructs the DB path from this env var.
• connect-typeorm session store version mismatch - Import from connect-typeorm/out (not the package root) as shown in server/index.ts; the package does not expose a CJS default at the top level in older versions.

Vibe-coding prompt template

I have dropped the Overseerr / Seerr source into my project at `./source/`.
I have read `USAGE.md` and understand the architecture.
The upstream npm package is `user@example.com`.

Please help me integrate this source into my existing Express + TypeScript project step by step:

1. Audit my existing `tsconfig.json` and merge the `@server/*` path aliases from `source/tsconfig.json`.
2. Wire `source/server/index.ts` as the server entry point, or show me how to import only the notification subsystem (`source/server/lib/notifications/index.ts`) into my app.
3. Register the TypeORM data source from `source/server/datasource.ts` alongside my existing DB setup, avoiding conflicts.
4. Add a custom notification agent that sends events to my Slack workspace, using the `Notification` enum and `NotificationPayload` interface visible in `source/server/lib/notifications/index.ts`.
5. Show me how to call `hasNotificationType` to gate dispatching on user preferences.
6. List any environment variables I must set before the server starts.

Use only exports and APIs documented in `USAGE.md`. Do not invent new modules.

License and credit

Overseerr is released under the MIT License - see source/LICENSE for the full text. The upstream project lives at https://github.com/sct/overseerr (npm: user@example.com). Per the README, active development has moved to Seerr; consult the Seerr migration guide for continued support.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完整安装指南与集成提示词将在购买后解锁。