@imigueldiaz/mongodb-labeler/dist/src/LabelerServer.d.ts

A MongoDB-based labeling system for content moderation with cryptographic signing

import { MongoDBClient } from "./mongodb.js";
import { CreateLabelData, SignedLabel } from "./util/types.js";
import { ObjectId } from "mongodb";
/**
* Options for initializing a LabelerServer instance.
*
* @param did - The DID of the labeler.
* @param signingKey - The signing key of the labeler, as a base64-encoded string.
* @param mongoUri - The URI to connect to the MongoDB instance.
* @param databaseName - The name of the MongoDB database to use. Defaults to 'labeler'.
* @param collectionName - The name of the MongoDB collection to use. Defaults to 'labels'.
* @param port - The port to listen on. Defaults to 4100.
*/
export interface LabelerOptions {
    did: `did:${string}`;
    signingKey: string;
    mongoUri: string;
    databaseName?: string;
    collectionName?: string;
    port?: number;
}
/**
* LabelerServer is responsible for managing label creation, querying, and deletion
* operations. It interfaces with a MongoDB database to persist label data and uses
* cryptographic signing to ensure label authenticity.
*
* This class requires initialization with LabelerOptions, which include database
* connection details and a signing key. The server supports operations such as
* creating new labels, querying existing ones by ID, and marking labels as deleted
* by signing them with a negation flag.
*
* The labels are signed using a Secp256k1Keypair, and the signatures are stored
* in the database alongside the label data.
*/
export declare class LabelerServer {
    private readonly _db;
    get db(): MongoDBClient;
    private _signer;
    private set _setSigner(value);
    private readonly _did;
    get did(): `did:${string}`;
    private _initializeSigner;
    private _initializationError?;
    /**
    * Returns the promise that resolves when the signer is initialized.
    * @returns A promise that resolves when initialization is complete.
    * @throws {Error} If initialization failed
    */
    getInitializationPromise(): Promise<void>;
    /**
    * Creates a new instance of the LabelerServer.
    * @param options The options for the server
    * @throws {LabelerServerError} If initialization fails
    */
    constructor(options: LabelerOptions);
    /**
    * Establishes a connection to the MongoDB instance.
    *
    * This method should be called before performing any database operations
    * to ensure that the database connection is properly established.
    *
    * @throws {LabelerServerError} If the connection attempt fails
    */
    connect(): Promise<void>;
    /**
    * Close the connection to the MongoDB instance.
    *
    * This method should be called when the LabelerServer is no longer needed.
    * @throws {LabelerServerError} If closing the connection fails
    */
    close(): Promise<void>;
    /**
    * Signs a label using the server's signing key.
    */
    private _signLabel;
    /**
    * Creates a new signed label using the provided data.
    *
    * This function constructs an unsigned label with the current timestamp and
    * the source set to the provided source or the server's DID. It then signs
    * the label using the server's signing key and saves it to the database.
    *
    * @param data - The data required to create a label.
    * @param allowExpired - Whether to allow expired timestamps
    * @returns A promise that resolves to the signed label.
    * @throws {LabelerServerError} If validation fails or label creation fails
    */
    createLabel(data: CreateLabelData, allowExpired?: boolean): Promise<SignedLabel>;
    /**
    * Query all labels from the database.
    *
    * @param query - Optional query parameters
    * @returns A promise that resolves to an array of signed labels
    * @throws {LabelerServerError} If the query operation fails
    */
    queryLabels(query?: {
        exp?: string;
        allowExpired?: boolean;
    }): Promise<SignedLabel[]>;
    /**
    * Query a specific label from the database by its ID.
    *
    * @param id - The ID of the label to query.
    * @returns A promise that resolves to the signed label if found, or null if not found.
    * @throws {LabelerServerError} If the query operation fails
    */
    queryLabel(id: ObjectId): Promise<SignedLabel | null>;
    /**
    * Deletes a label from the database.
    *
    * This function first queries the label from the database to verify its existence.
    * If the label exists, it creates a new label with the same properties as the original,
    * but sets the neg field to true. It then signs the new label and saves it to the
    * database. If the label does not exist, the function does nothing.
    *
    * @param id - The ID of the label to delete.
    * @returns A promise that resolves to the signed label with negation if successful, or null if not found.
    * @throws {LabelerServerError} If the deletion operation fails
    */
    deleteLabel(id: ObjectId): Promise<SignedLabel | null>;
    /**
    * Reverses the negation of a label in the database.
    *
    * This function first queries the label from the database to verify its existence.
    * If the label exists, it creates a new label with the same properties as the original,
    * but sets the neg field to the opposite of the original. It then signs the new label.
    * If the save parameter is true, it saves the new label to the database. If the label
    * does not exist, the function does nothing.
    *
    * @param id - The ID of the label to reverse the negation of.
    * @param save - Whether to save the new label to the database. Defaults to false.
    * @returns A promise that resolves to the signed label with the reversed negation if
    * the label exists, or null if not.
    */
    reverseLabelNegation(id: ObjectId, save?: boolean): Promise<SignedLabel | null>;
    /**
    * Retrieve a limited number of labels from the database that have an ID greater than the specified cursor.
    *
    * @param cursor - The ID after which labels should be retrieved.
    * @param limit - The maximum number of labels to return.
    * @returns A promise that resolves to an array of labels with IDs greater than the cursor.
    * @throws {LabelerServerError} If the query operation fails
    */
    getLabelsAfterCursor(cursor: ObjectId, limit: number): Promise<SignedLabel[]>;
}