tjbot-ce 3.0.1

package/dist/tjbot.d.ts

@@ -0,0 +1,317 @@
+/**
+ * Copyright 2016-2025 IBM Corp. All Rights Reserved.
+ * Copyright 2026-present TJBot Contributors. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { TJBotConfigSchema } from './config/config-types.js';
+import { TJBotConfig } from './config/tjbot-config.js';
+import { RPiHardwareDriver } from './rpi-drivers/index.js';
+import { Hardware } from './utils/index.js';
+import { ModelType } from './utils/model-registry.js';
+import { FaceDetectionMetadata, ImageClassificationResult, ImageDescriptionResult, ObjectDetectionResult } from './vision/index.js';
+/**
+ * Class representing a TJBot
+ */
+declare class TJBot {
+    /**
+     * TJBot library version
+     * @readonly
+     */
+    static VERSION: string;
+    /**
+     * Singleton instance
+     * @private
+     */
+    private static instance;
+    /**
+     * Hardware list
+     * @readonly
+     */
+    static Hardware: typeof Hardware;
+    /**
+     * TJBot configuration
+     */
+    config: TJBotConfig;
+    /**
+     * Raspberry Pi model on which TJBot is running
+     * @example "Raspberry Pi 5"
+     */
+    rpiModel: string;
+    /**
+     * Raspberry Pi hardware driver
+     */
+    rpiDriver: RPiHardwareDriver;
+    /**
+     * Cache of the colors recognized by TJBot
+     */
+    private _shineColors;
+    /**
+     * Flag to track if TJBot has been initialized
+     */
+    private _initialized;
+    /**
+     * Promise for in-flight cleanup operation, if any.
+     */
+    private _cleanupPromise;
+    /**
+     * Guard to ensure process lifecycle hooks are installed only once.
+     */
+    private _processHooksInstalled;
+    /**
+     * Private constructor.
+     * @private
+     */
+    private constructor();
+    /**
+     * Get the singleton instance of TJBot.
+     * @returns {TJBot} The singleton TJBot instance
+     * @public
+     */
+    static getInstance(): TJBot;
+    /**
+     * Get recipe-specific configuration. This method can be used before calling `TJBot.getInstance().initialize()`
+     * in case a recipe needs to dynamically determine which hardware components should be configured.
+     * @param {string=} recipeConfigPath (optional) Path to recipe configuration file (default: recipe.toml in current working directory)
+     * @return {Record<string, unknown>} The recipe configuration as a key-value object. If no recipe configuration file is found, returns an empty object.
+     *
+     */
+    static getRecipeConfig(recipeConfigPath?: string): Record<string, unknown>;
+    /**
+     * Initialize TJBot with configuration. Can be called multiple times to reconfigure.
+     * Performs cleanup of previous initialization, loads configuration, detects hardware,
+     * initializes all configured hardware and AI models eagerly.
+     * @param {Partial<TJBotConfigSchema>=} overrideConfig (optional) Configuration object to overlay on top of loaded config.
+     * @param {string=} recipeConfigPath (optional) Path to recipe configuration file (default: recipe.toml in current working directory)
+     * @throws {TJBotError} if configuration file cannot be loaded, is invalid, or cleanup fails
+     * @public
+     */
+    initialize(overrideConfig?: Partial<TJBotConfigSchema>, recipeConfigPath?: string): Promise<TJBot>;
+    /**
+     * Initialize hardware devices
+     * @private
+     */
+    private initializeHardware;
+    /**
+     * Eagerly initialize local AI models (STT, TTS, Vision) if configured
+     * @private
+     */
+    private initializeAIModels;
+    /**
+     * Clean up all resources. Called automatically before re-initialization.
+     * @throws {TJBotError} if cleanup fails
+     * @private
+     */
+    private cleanup;
+    /**
+     * Install process lifecycle hooks so TJBot hardware resources are cleaned up
+     * automatically when a recipe exits or is interrupted.
+     */
+    private installProcessCleanupHooks;
+    /**
+     * Best-effort automatic cleanup path used by process lifecycle hooks.
+     * Uses a timeout in fatal/signal scenarios so process termination does not hang.
+     */
+    private runLifecycleCleanup;
+    /**
+     * Change the level of TJBot's logging.
+     * @param {string} level Logging level (see Winston's [list of logging levels](https://github.com/winstonjs/winston?tab=readme-ov-file#using-logging-levels))
+     * @public
+     */
+    setLogLevel(level: string): void;
+    /**
+     * Assert that TJBot is able to perform a specified capability.
+     * @private
+     * @param {string} capability The capability assert (see TJBot.prototype.capabilities).
+     */
+    private assertCapability;
+    /**
+     * Sleep for the specified number of seconds.
+     * @param sec Number of seconds to sleep
+     */
+    sleep(sec: number): Promise<void>;
+    /** ------------------------------------------------------------------------ */
+    /** LOCAL AI/ML MODELS                                                       */
+    /** ------------------------------------------------------------------------ */
+    /**
+     * List the AI/ML models on this device.
+     * @returns {string[]} Array of installed model keys
+     */
+    getLocalModels(modelType?: ModelType, installedOnly?: boolean): string[];
+    /** ------------------------------------------------------------------------ */
+    /** LISTEN                                                                   */
+    /** ------------------------------------------------------------------------ */
+    /**
+     * Listen for a spoken utterance (offline mode - returns transcript).
+     * @returns {Promise<string>} The transcribed text
+     * @throws {TJBotError} if the microphone hardware is not initialized
+     * @public
+     */
+    listen(): Promise<string>;
+    /**
+     * Listen for a spoken utterance (streaming mode - uses callbacks).
+     * @param onPartialResult Callback for partial transcription results
+     * @param onFinalResult Callback for final transcription result
+     * @returns {Promise<void>} Promise that resolves when transcription completes
+     * @throws {TJBotError} if the microphone hardware is not initialized
+     * @public
+     */
+    listen(onPartialResult: (text: string) => void, onFinalResult: (text: string) => void): Promise<void>;
+    /** ------------------------------------------------------------------------ */
+    /** SEE                                                                      */
+    /** ------------------------------------------------------------------------ */
+    /**
+     * Capture an image and return it as a buffer.
+     * @return {Promise<Buffer>} The captured image as a buffer.
+     * @throws {TJBotError} if the camera hardware is not initialized
+     * @public
+     */
+    see(): Promise<Buffer>;
+    /**
+     * Capture an image and save it in the given path.
+     * @param  {string=} filePath (optional) Path at which to save the photo file. If not
+     * specified, photo will be saved in a temp location.
+     * @return {string} Path at which the photo was saved.
+     * @throws {TJBotError} if the camera hardware is not initialized
+     * @public
+     */
+    look(filePath?: string): Promise<string>;
+    /**
+     * Detect objects in an image using the configured vision engine.
+     * @param {Buffer|string} image Image buffer or file path
+     * @returns {Promise<ObjectDetectionResult[]>}
+     */
+    detectObjects(image: Buffer | string): Promise<ObjectDetectionResult[]>;
+    /**
+     * Classify an image using the configured vision engine.
+     * @param {Buffer|string} image Image buffer or file path
+     * @returns {Promise<ImageClassificationResult[]>}
+     */
+    classifyImage(image: Buffer | string): Promise<ImageClassificationResult[]>;
+    /**
+     * Detect faces in an image using the configured vision engine.
+     * @param {Buffer|string} image Image buffer or file path
+     * @returns {Promise<{isFaceDetected: boolean, metadata: FaceDetectionMetadata[]}>}
+     */
+    detectFaces(image: Buffer | string): Promise<{
+        isFaceDetected: boolean;
+        metadata: FaceDetectionMetadata[];
+    }>;
+    /**
+     * Describe an image using the configured vision engine (Azure only).
+     * @param {Buffer|string} image Image buffer or file path
+     * @returns {Promise<ImageDescriptionResult>}
+     */
+    describeImage(image: Buffer | string): Promise<ImageDescriptionResult>;
+    /** ------------------------------------------------------------------------ */
+    /** SHINE                                                                    */
+    /** ------------------------------------------------------------------------ */
+    /**
+     * Change the color of the LED.
+     * @param {string} color The color to shine the LED. May be specified in a number of
+     * formats, including: hexadecimal, (e.g. "0xF12AC4", "11FF22", "#AABB24"), "on", "off",
+     * or may be a named color in the `colornames` package. Hexadecimal colors
+     * follow an #RRGGBB format.
+     * @returns {Promise<void>} A promise that resolves when the LED color has been set.
+     * @see {@link https://github.com/timoxley/colornames|Colornames} for a list of color names.
+     * @throws {TJBotError} if the LED hardware is not initialized or if color is invalid
+     * @public
+     */
+    shine(color: string): Promise<void>;
+    /**
+     * Pulse the LED a single time.
+     * @param {string} color The color to shine the LED. May be specified in a number of
+     * formats, including: hexadecimal, (e.g. "0xF12AC4", "11FF22", "#AABB24"), "on", "off",
+     * or may be a named color in the `colornames` package. Hexadecimal colors
+     * follow an #RRGGBB format.
+     * @param {float=} duration The duration the pulse should last. The duration should be in
+     * the range [0.5, 2.0] seconds.
+     * @returns {Promise<void>} A promise that resolves when the LED pulse animation completes.
+     * @see {@link https://github.com/timoxley/colornames|Colornames} for a list of color names.
+     * @throws {TJBotError} if the LED hardware is not initialized, color is invalid, or duration exceeds 2.0 seconds
+     * @public
+     */
+    pulse(color: string, duration?: number): Promise<void>;
+    /**
+     * Get the list of all colors recognized by TJBot.
+     * @return {array} List of all named colors recognized by `shine()` and `pulse()`.
+     * @public
+     */
+    shineColors(): string[];
+    /**
+     * Get a random color.
+     * @return {string} Random named color.
+     * @public
+     */
+    randomColor(): string;
+    /** ------------------------------------------------------------------------ */
+    /** SPEAK                                                                    */
+    /** ------------------------------------------------------------------------ */
+    /**
+     * Speak a message.
+     * @param {string} message The message to speak.
+     * @throws {TJBotError} if the speaker hardware is not initialized
+     * @public
+     */
+    speak(message: string): Promise<void>;
+    /**
+     * Play a sound at the specified path.
+     * @param {string} soundFile The path to the sound file to be played.
+     * @public
+     */
+    play(soundFile: string): Promise<void>;
+    /** ------------------------------------------------------------------------ */
+    /** WAVE                                                                     */
+    /** ------------------------------------------------------------------------ */
+    /**
+     * Moves TJBot's arm all the way back. If this method doesn't move the arm all the way back, the servo motor stop point defined in TJBot.Servo.ARM_BACK may need to be overridden. Valid servo values are in the range [500, 2300].
+     * @throws {TJBotError} if the servo hardware is not initialized
+     * @returns {Promise<void>} Resolves when the arm is fully back.
+     * @example tj.armBack()
+     * @public
+     */
+    armBack(): Promise<void>;
+    /**
+     * Raises TJBot's arm. If this method doesn't move the arm all the way back, the servo motor stop point defined in TJBot.Servo.ARM_UP may need to be overridden. Valid servo values are in the range [500, 2300].
+     * @throws {TJBotError} if the servo hardware is not initialized
+     * @returns {Promise<void>} Resolves when the arm is fully raised.
+     * @example tj.raiseArm()
+     * @public
+     */
+    raiseArm(): Promise<void>;
+    /**
+     * Lowers TJBot's arm. If this method doesn't move the arm all the way back, the servo motor stop point defined in TJBot.Servo.ARM_DOWN may need to be overridden. Valid servo values are in the range [500, 2300].
+     * @throws {TJBotError} if the servo hardware is not initialized
+     * @returns {Promise<void>} Resolves when the arm is fully lowered.
+     * @example tj.lowerArm()
+     * @public
+     */
+    lowerArm(): Promise<void>;
+    /**
+     * Waves TJBots's arm once.
+     * @throws {TJBotError} if the servo hardware is not initialized
+     * @returns {Promise<void>} Resolves when the wave is complete.
+     * @example tj.wave()
+     * @public
+     */
+    wave(): Promise<void>;
+}
+/** ------------------------------------------------------------------------ */
+/** MODULE EXPORTS                                                           */
+/** ------------------------------------------------------------------------ */
+/**
+ * Export TJBot!
+ */
+export { TJBot };
+export default TJBot;
+//# sourceMappingURL=tjbot.d.ts.map

package/dist/tjbot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tjbot.d.ts","sourceRoot":"","sources":["../src/tjbot.ts"],"names":[],"mappings":"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"}