@bsv/overlay-express/dist/types/src/OverlayExpress.d.ts

BSV Blockchain Overlay Express

import express from 'express';
import { Engine, LookupService, TopicManager, Advertiser } from '@bsv/overlay';
import { ChainTracker, Broadcaster, OverlayBroadcastFacilitator } from '@bsv/sdk';
import Knex from 'knex';
import { Db } from 'mongodb';
import { type UIConfig } from './makeUserInterface.js';
/**
 * Knex database migration.
 */
interface Migration {
    name?: string;
    up: (knex: Knex.Knex) => Promise<void>;
    down?: (knex: Knex.Knex) => Promise<void>;
}
/**
 * Configuration options that map to Engine constructor parameters.
 */
export interface EngineConfig {
    chainTracker?: ChainTracker | 'scripts only';
    shipTrackers?: string[];
    slapTrackers?: string[];
    broadcaster?: Broadcaster;
    advertiser?: Advertiser;
    syncConfiguration?: Record<string, string[] | 'SHIP' | false>;
    logTime?: boolean;
    logPrefix?: string;
    throwOnBroadcastFailure?: boolean;
    overlayBroadcastFacilitator?: OverlayBroadcastFacilitator;
    suppressDefaultSyncAdvertisements?: boolean;
}
/**
 * OverlayExpress class provides an Express-based server for hosting Overlay Services.
 * It allows configuration of various components like databases, topic managers, and lookup services.
 * It encapsulates an Express application and provides methods to start the server.
 */
export default class OverlayExpress {
    name: string;
    privateKey: string;
    advertisableFQDN: string;
    app: express.Application;
    port: number;
    logger: typeof console;
    knex: Knex.Knex;
    migrationsToRun: Migration[];
    mongoDb: Db;
    network: 'main' | 'test';
    chainTracker: ChainTracker | 'scripts only';
    engine: Engine;
    managers: Record<string, TopicManager>;
    services: Record<string, LookupService>;
    enableGASPSync: boolean;
    arcApiKey: string | undefined;
    verboseRequestLogging: boolean;
    webUIConfig: UIConfig;
    engineConfig: EngineConfig;
    private readonly adminToken;
    /**
     * Constructs an instance of OverlayExpress.
     * @param name - The name of the service
     * @param privateKey - Private key used for signing advertisements
     * @param advertisableFQDN - The fully qualified domain name where this service is available. Does not include "https://".
     * @param adminToken - Optional. An administrative Bearer token used to protect admin routes.
     *                     If not provided, a random token will be generated at runtime.
     */
    constructor(name: string, privateKey: string, advertisableFQDN: string, adminToken?: string);
    /**
     * Returns the current admin token in case you need to programmatically retrieve or display it.
     */
    getAdminToken(): string;
    /**
     * Configures the port on which the server will listen.
     * @param port - The port number
     */
    configurePort(port: number): void;
    /**
     * Configures the web user interface
     * @param config - Web UI configuration options
     */
    configureWebUI(config: UIConfig): void;
    /**
     * Configures the logger to be used by the server.
     * @param logger - A logger object (e.g., console)
     */
    configureLogger(logger: typeof console): void;
    /**
     * Configures the BSV Blockchain network to be used ('main' or 'test').
     * By default, it re-initializes chainTracker as a WhatsOnChain for that network.
     * @param network - The network ('main' or 'test')
     */
    configureNetwork(network: 'main' | 'test'): void;
    /**
     * Configures the ChainTracker to be used.
     * If 'scripts only' is used, it implies no full SPV chain tracking in the Engine.
     * @param chainTracker - An instance of ChainTracker or 'scripts only'
     */
    configureChainTracker(chainTracker?: ChainTracker | 'scripts only'): void;
    /**
     * Configures the ARC API key.
     * @param apiKey - The ARC API key
     */
    configureArcApiKey(apiKey: string): void;
    /**
     * Enables or disables GASP synchronization (high-level setting).
     * This is a broad toggle that can be overridden or customized through syncConfiguration.
     * @param enable - true to enable, false to disable
     */
    configureEnableGASPSync(enable: boolean): void;
    /**
     * Enables or disables verbose request logging.
     * @param enable - true to enable, false to disable
     */
    configureVerboseRequestLogging(enable: boolean): void;
    /**
     * Configure Knex (SQL) database connection.
     * @param config - Knex configuration object, or MySQL connection string (e.g. mysql://overlayAdmin:overlay123@mysql:3306/overlay).
     */
    configureKnex(config: Knex.Knex.Config | string): Promise<void>;
    /**
     * Configures the MongoDB database connection.
     * @param connectionString - MongoDB connection string
     */
    configureMongo(connectionString: string): Promise<void>;
    /**
     * Configures a Topic Manager.
     * @param name - The name of the Topic Manager
     * @param manager - An instance of TopicManager
     */
    configureTopicManager(name: string, manager: TopicManager): void;
    /**
     * Configures a Lookup Service.
     * @param name - The name of the Lookup Service
     * @param service - An instance of LookupService
     */
    configureLookupService(name: string, service: LookupService): void;
    /**
     * Configures a Lookup Service using Knex (SQL) database.
     * @param name - The name of the Lookup Service
     * @param serviceFactory - A factory function that creates a LookupService instance using Knex
     */
    configureLookupServiceWithKnex(name: string, serviceFactory: (knex: Knex.Knex) => {
        service: LookupService;
        migrations: Migration[];
    }): void;
    /**
     * Configures a Lookup Service using MongoDB.
     * @param name - The name of the Lookup Service
     * @param serviceFactory - A factory function that creates a LookupService instance using MongoDB
     */
    configureLookupServiceWithMongo(name: string, serviceFactory: (mongoDb: Db) => LookupService): void;
    /**
     * Advanced configuration method for setting or overriding any
     * Engine constructor parameters via an EngineConfig object.
     *
     * Example usage:
     *   configureEngineParams({
     *     logTime: true,
     *     throwOnBroadcastFailure: true,
     *     overlayBroadcastFacilitator: new MyCustomFacilitator()
     *   })
     *
     * These fields will be respected when we finally build/configure the Engine
     * in the `configureEngine()` method below.
     */
    configureEngineParams(params: EngineConfig): void;
    /**
     * Configures the Overlay Engine itself.
     * By default, auto-configures SHIP and SLAP unless autoConfigureShipSlap = false
     * Then it merges in any advanced engine config from `this.engineConfig`.
     *
     * @param autoConfigureShipSlap - Whether to auto-configure SHIP and SLAP services (default: true)
     */
    configureEngine(autoConfigureShipSlap?: boolean): Promise<void>;
    /**
     * Ensures that Knex is configured.
     * @throws Error if Knex is not configured
     */
    private ensureKnex;
    /**
     * Ensures that MongoDB is configured.
     * @throws Error if MongoDB is not configured
     */
    private ensureMongo;
    /**
     * Ensures that the Overlay Engine is configured.
     * @throws Error if the Engine is not configured
     */
    private ensureEngine;
    /**
     * Starts the Express server.
     * Sets up routes and begins listening on the configured port.
     */
    start(): Promise<void>;
}
export {};
//# sourceMappingURL=OverlayExpress.d.ts.map