/**
 * @license
 * Copyright 2022-2026 Matter.js Authors
 * SPDX-License-Identifier: Apache-2.0
 */
import { CertificateAuthority } from "#certificate/CertificateAuthority.js";
import { DiscoveryData } from "#common/Scanner.js";
import { Fabric } from "#fabric/Fabric.js";
import { ControllerCommissioningFlow, ControllerCommissioningFlowOptions } from "#peer/ControllerCommissioningFlow.js";
import { ExchangeManager } from "#protocol/ExchangeManager.js";
import { NodeSession } from "#session/NodeSession.js";
import { SessionManager } from "#session/SessionManager.js";
import { ClassExtends, ConnectionlessTransportSet, Duration, Environment, Environmental, MaybePromise, ServerAddress } from "@matter/general";
import { NodeId } from "@matter/types";
import { PeerAddress } from "./PeerAddress.js";
import { PeerSet } from "./PeerSet.js";
import { PeerTimingParameters } from "./PeerTimingParameters.js";
/**
 * General commissioning options.
 */
export interface CommissioningOptions extends Partial<ControllerCommissioningFlowOptions> {
    /** The fabric into which to commission. */
    fabric: Fabric;
    /** The node ID to assign (the commissioner assigns a random node ID if omitted) */
    nodeId?: NodeId;
    /** Passcode to use for commissioning. */
    passcode: number;
    /**
     * Commissioning completion callback
     *
     * This optional callback allows the caller to complete commissioning once PASE commissioning completes.  If it does
     * not throw, the commissioner considers commissioning complete.
     */
    finalizeCommissioning?: (peerAddress: PeerAddress, discoveryData?: DiscoveryData) => MaybePromise<void>;
    /**
     * Commissioning Flow Implementation as class that extends the official implementation to use for commissioning.
     * Defaults to the matter.js default implementation {@link ControllerCommissioningFlow}.
     */
    commissioningFlowImpl?: ClassExtends<ControllerCommissioningFlow>;
    /**
     * Timing overrides for the step-18 CASE reconnect.
     *
     * After commissioning completes, the commissioner establishes the first operational CASE session.  The device is
     * known to be freshly online at this point, so tighter timing is appropriate.  Any fields provided here are merged
     * on top of the global {@link PeerSet.timing} for that single connection only.
     */
    caseConnectionTiming?: Partial<PeerTimingParameters>;
}
/**
 * Configuration for commissioning a previously discovered node.
 */
export interface LocatedNodeCommissioningOptions extends CommissioningOptions {
    addresses: ServerAddress[];
    discoveryData?: DiscoveryData;
    /**
     * Overall wall-clock budget for PASE establishment across all candidate addresses.
     * Defaults to 30 seconds.
     */
    timeout?: Duration;
    /**
     * Abort signal for cancellation.  When fired during PASE establishment, cancels the attempt.
     * In parallel commissioning scenarios this is used to cancel other candidates once one wins.
     */
    abort?: AbortSignal;
    /**
     * Called immediately after PASE is established, before the main commissioning flow begins.
     *
     * Return `true` to proceed with commissioning (this candidate won the race).
     * Return `false` to abort — the PASE session is closed and commissioning is skipped.
     *
     * This is the hook used by {@link CommissioningDiscovery} for multi-candidate parallel flows:
     * the first candidate to establish PASE returns `true` and signals the others (via {@link abort})
     * to stop.  Any candidate that establishes PASE after another has already won returns `false` here
     * and cleans up.  In the single-device located-node path this callback is unnecessary and need not
     * be provided.
     */
    continueCommissioningAfterPase?: () => boolean;
}
/**
 * Options for establishing a PASE session with a device whose address(es) are already known.
 *
 * Use this when you have at least one address for the device (from a prior discovery, a QR code, or a
 * pre-configured address).  For pure mDNS/BLE discovery without known addresses, use {@link PaseDiscovery}.
 */
export interface EstablishPaseOptions {
    /** One or more addresses at which the device may be reached. All are tried in parallel. */
    addresses: ServerAddress[];
    /** Discovery metadata associated with the device (used for logging and passed through to the caller). */
    discoveryData?: DiscoveryData;
    /** PASE passcode for the device. */
    passcode: number;
    /** Overall timeout for PASE establishment across all addresses. Defaults to 30 seconds. */
    timeout?: Duration;
    /** External abort signal that, when fired, cancels all in-flight PASE attempts. */
    abort?: AbortSignal;
    /**
     * Atomic gate for parallel PASE racing.
     *
     * Called immediately after PASE is established (before any further work).  Return `true` to claim this
     * PASE session as the winner.  Return `false` if another candidate already won — this session is closed
     * cleanly without proceeding.
     *
     * When omitted, the first successful PASE session is always accepted.
     */
    continueAfterPase?: () => boolean;
}
/** Result returned by {@link ControllerCommissioner.establishPase}. */
export interface EstablishPaseResult {
    paseSession: NodeSession;
    discoveryData?: DiscoveryData;
}
/**
 * Interfaces {@link ControllerCommissioner} with other components.
 */
export interface ControllerCommissionerContext {
    peers: PeerSet;
    transports: ConnectionlessTransportSet;
    sessions: SessionManager;
    exchanges: ExchangeManager;
    ca: CertificateAuthority;
    environment: Environment;
}
/**
 * Commissions other nodes onto a fabric.
 */
export declare class ControllerCommissioner {
    #private;
    constructor(context: ControllerCommissionerContext);
    static [Environmental.create](env: Environment): ControllerCommissioner;
    /**
     * Commission a previously discovered node.
     */
    commission(options: LocatedNodeCommissioningOptions): Promise<PeerAddress>;
    /**
     * Establishes a PASE session with a known device without running a commissioning flow.
     *
     * All provided addresses are tried in parallel.  The first to complete PASE wins; the rest are cancelled
     * via an abort signal.  A credential failure (wrong passcode) on any address immediately cancels all
     * other in-flight attempts for this device.
     */
    establishPase(options: EstablishPaseOptions): Promise<EstablishPaseResult>;
}
//# sourceMappingURL=ControllerCommissioner.d.ts.map