@skyware/labeler/dist/LabelerServer.d.ts

A lightweight alternative to Ozone for operating an atproto labeler.

import "@atcute/ozone/lexicons";
import type { At, ComAtprotoLabelQueryLabels, ToolsOzoneModerationEmitEvent } from "@atcute/client/lexicons";
import { Client } from "@libsql/client";
import { type FastifyInstance, type FastifyListenOptions } from "fastify";
import type { CreateLabelData, ProcedureHandler, QueryHandler, SavedLabel, SubscriptionHandler } from "./util/types.js";
/**
 * Options for the {@link LabelerServer} class.
 */
export interface LabelerOptions {
    /** The DID of the labeler account. */
    did: string;
    /**
     * The private signing key used for the labeler.
     * If you don't have a key, generate and set one using {@link plcSetupLabeler}.
     */
    signingKey: string;
    /**
     * A function that returns whether a DID is authorized to create labels.
     * By default, only the labeler account is authorized.
     * @param did The DID to check.
     */
    auth?: (did: string) => boolean | Promise<boolean>;
    /**
     * The path to the SQLite `.db` database file.
     * @default labels.db
     */
    dbPath?: string;
    /**
     * The URL of the remote SQLite database.
     * If provided, {@link dbPath} is ignored.
     */
    dbUrl?: string;
    /**
     * The authentication token for the remote SQLite database.
     * Required if {@link dbUrl} is provided.
     */
    dbToken?: string;
}
export declare class LabelerServer {
    #private;
    /** The Fastify application instance. */
    app: FastifyInstance;
    /** The SQLite database instance. */
    db: Client;
    /** The DID of the labeler account. */
    did: At.DID;
    /** A function that returns whether a DID is authorized to create labels. */
    private auth;
    /** Open WebSocket connections, mapped by request NSID. */
    private connections;
    /**
     * Promise that resolves when database initialization is complete.
     * This should be awaited before any database operations.
     */
    private readonly dbInitLock?;
    /**
     * Create a labeler server.
     * @param options Configuration options.
     */
    constructor(options: LabelerOptions);
    /**
     * Initializes the database with the required schema.
     * @returns A promise that resolves when initialization is complete
     */
    private initializeDatabase;
    /**
     * Start the server.
     * @param port The port to listen on.
     * @param callback A callback to run when the server is started.
     */
    start(port: number, callback: (error: Error | null, address: string) => void): void;
    /**
     * Start the server.
     * @param options Options for the server.
     * @param callback A callback to run when the server is started.
     */
    start(options: FastifyListenOptions, callback: (error: Error | null, address: string) => void): void;
    /**
     * Stop the server.
     * @param callback A callback to run when the server is stopped.
     */
    close(callback?: () => void): void;
    /**
     * Alias for {@link LabelerServer#close}.
     * @param callback A callback to run when the server is stopped.
     */
    stop(callback?: () => void): void;
    /**
     * Insert a label into the database, emitting it to subscribers.
     * @param label The label to insert.
     * @returns The inserted label.
     */
    private saveLabel;
    /**
     * Create and insert a label into the database, emitting it to subscribers.
     * @param label The label to create.
     * @returns The created label.
     */
    createLabel(label: CreateLabelData): Promise<SavedLabel>;
    /**
     * Create and insert labels into the database, emitting them to subscribers.
     * @param subject The subject of the labels.
     * @param labels The labels to create.
     * @returns The created labels.
     */
    createLabels(subject: {
        uri: string;
        cid?: string | undefined;
    }, labels: {
        create?: Array<string>;
        negate?: Array<string>;
    }): Promise<Array<SavedLabel>>;
    /**
     * Emit a label to all subscribers.
     * @param seq The label's id.
     * @param label The label to emit.
     */
    private emitLabel;
    /**
     * Parse a user DID from an Authorization header JWT.
     * @param req The Express request object.
     */
    private parseAuthHeaderDid;
    /**
     * Handler for [com.atproto.label.queryLabels](https://github.com/bluesky-social/atproto/blob/main/lexicons/com/atproto/label/queryLabels.json).
     */
    queryLabelsHandler: QueryHandler<ComAtprotoLabelQueryLabels.Params>;
    /**
     * Handler for [com.atproto.label.subscribeLabels](https://github.com/bluesky-social/atproto/blob/main/lexicons/com/atproto/label/subscribeLabels.json).
     */
    subscribeLabelsHandler: SubscriptionHandler<{
        cursor?: string;
    }>;
    /**
     * Handler for [tools.ozone.moderation.emitEvent](https://github.com/bluesky-social/atproto/blob/main/lexicons/tools/ozone/moderation/emitEvent.json).
     */
    emitEventHandler: ProcedureHandler<ToolsOzoneModerationEmitEvent.Input>;
    /**
     * Handler for the health check endpoint.
     */
    healthHandler: QueryHandler;
    /**
     * Catch-all handler for unknown XRPC methods.
     */
    unknownMethodHandler: QueryHandler;
    /**
     * Default error handler.
     */
    errorHandler: typeof this.app.errorHandler;
    /**
     * Add a WebSocket connection to the list of subscribers for a given lexicon.
     * @param nsid The NSID of the lexicon to subscribe to.
     * @param ws The WebSocket connection to add.
     */
    private addSubscription;
    /**
     * Remove a WebSocket connection from the list of subscribers for a given lexicon.
     * @param nsid The NSID of the lexicon to unsubscribe from.
     * @param ws The WebSocket connection to remove.
     */
    private removeSubscription;
}