@iobroker/adapter-core

@iobroker/adapter-core

Version 3.4.2
Published 13 hours ago
175 kB
No dependencies
MIT license

Install

npm i @iobroker/adapter-core

yarn add @iobroker/adapter-core

pnpm add @iobroker/adapter-core

Overview

Core module to be used in ioBroker adapters. Acts as the bridge to js-controller.

Variables

variable adapter

const adapter: AdapterConstructor;

Creates a new adapter instance

variable Adapter

const Adapter: AdapterConstructor;

Creates a new adapter instance

variable commonTools

const commonTools: {
    pattern2RegEx: typeof pattern2RegEx;
    getAdapterDir: typeof getAdapterDir;
    getInstalledInfo: typeof getInstalledInfo;
    isDocker: typeof isDocker;
    getLocalAddress: typeof getLocalAddress;
    getListenAllAddress: typeof getListenAllAddress;
    isLocalAddress: typeof isLocalAddress;
    isListenAllAddress: typeof isListenAllAddress;
    password: any;
    session: any;
    zipFiles: any;
};

variable controllerDir

const controllerDir: string;

The root directory of JS-Controller

variable EXIT_CODES

const EXIT_CODES: Readonly<{
    NO_ERROR: number;
    JS_CONTROLLER_STOPPED: number;
    INVALID_ADAPTER_CONFIG: number;
    NO_ADAPTER_CONFIG_FOUND: number;
    INVALID_CONFIG_OBJECT: number;
    INVALID_ADAPTER_ID: number;
    UNCAUGHT_EXCEPTION: number;
    ADAPTER_ALREADY_RUNNING: number;
    INSTANCE_IS_DISABLED: number;
    CANNOT_GZIP_DIRECTORY: number;
    CANNOT_FIND_ADAPTER_DIR: number;
    ADAPTER_REQUESTED_TERMINATION: number;
    UNKNOWN_PACKET_NAME: number;
    ADAPTER_REQUESTED_REBUILD: number;
    CANNOT_READ_INSTANCES: number;
    NO_MULTIPLE_INSTANCES_ALLOWED: number;
    NO_MULTIPLE_INSTANCES_ALLOWED_ON_HOST: number;
    NO_CONNECTION_TO_OBJ_DB: number;
    NO_CONNECTION_TO_STATES_DB: number;
    INSTANCE_ALREADY_EXISTS: number;
    CANNOT_INSTALL_NPM_PACKET: number;
    CANNOT_EXTRACT_FROM_ZIP: number;
    INVALID_IO_PACKAGE_JSON: number;
    CANNOT_COPY_DIR: number;
    MISSING_ADAPTER_FILES: number;
    INVALID_NPM_VERSION: number;
    INVALID_NODE_VERSION: number;
    INVALID_OS: number;
    INVALID_DEPENDENCY_VERSION: number;
    INVALID_ARGUMENTS: number;
    INVALID_PASSWORD: number;
    MISSING_CONFIG_JSON: number;
    CANNOT_DELETE_NON_DELETABLE: number;
    CANNOT_GET_STATES: number;
    CANNOT_GET_REPO_LIST: number;
    START_IMMEDIATELY_AFTER_STOP: number;
}>;

Functions

function getAbsoluteDefaultDataDir

getAbsoluteDefaultDataDir: () => string;

Returns the absolute path of the data directory for the current host. On linux, this is usually /opt/iobroker/iobroker-data.

function getAbsoluteInstanceDataDir

getAbsoluteInstanceDataDir: (
    adapterObjectOrNamespace: ioBroker.Adapter | string
) => string;

Returns the absolute path of the data directory for the current adapter instance. On linux, this is usually /opt/iobroker/iobroker-data/<adapterName>.<instanceNr>
Parameter adapterObjectOrNamespace
The adapter instance or namespace string (e.g. "myAdapter.0").

function getConfig

getConfig: () => Record<string, any>;

Reads the configuration file of JS-Controller

Interfaces

interface AdapterInstance

interface AdapterInstance<
    HasObjectsCache extends boolean | undefined = undefined,
    HasStatesCache extends boolean | undefined = undefined
> extends ioBroker.Adapter {}

This type is used to include and exclude the states and objects cache from the adapter's type definition depending on the creation options

property oObjects

oObjects: HasObjectsCache extends true
    ? Exclude<ioBroker.Adapter['oObjects'], undefined>
    : undefined;

Objects cache

property oStates

oStates: HasStatesCache extends true
    ? Exclude<ioBroker.Adapter['oStates'], undefined>
    : undefined;

States cache

Type Aliases

type AdapterOptions

type AdapterOptions<
    HasObjectsCache extends boolean | undefined = undefined,
    HasStatesCache extends boolean | undefined = undefined
> = Omit<ioBroker.AdapterOptions, 'objects' | 'states'> &
    (true extends HasObjectsCache
        ? {
              objects: true;
          }
        : {
              objects?: HasObjectsCache;
          }) &
    (true extends HasStatesCache
        ? {
              states: true;
          }
        : {
              states?: HasStatesCache;
          });

This type augments the ioBroker Adapter options to accept two generics for the objects and states cache

Namespaces

namespace Credentials

module 'build/esm/credentials.d.ts' {}

Central credential storage for ioBroker.
Credentials are stored as objects with IDs like system.credentials.<name>, e.g. system.credentials.anthropic. The admin adapter provides the UI to manage them (Settings -> Credentials) and a JsonConfig component credential so adapters can let the user pick a credential by ID in the instance configuration.
All information lives in native: - native.type - the credential type (email, cloud, ai, custom) - a pure category used for filtering - native.version - version of the data format (for future migrations) - native.encryptedFields - names of the fields in native that are stored encrypted with the system secret - all other keys in native are the credential fields themselves
Every credential has one of two forms: - login: a login and a password field (password encrypted) - key: a single key field (encrypted), e.g. an API key
This module is intentionally free of Node.js imports so it can also be consumed by browser builds (admin UI, json-config).

variable CREDENTIAL_FORMS

const CREDENTIAL_FORMS: Record<CredentialForm, CredentialFieldDefinition[]>;

Registry of the two credential forms and their fields. This is the single source of truth - the admin UI renders its dialogs from it.

variable CREDENTIAL_META_FIELDS

const CREDENTIAL_META_FIELDS: string[];

Keys in native that are reserved for metadata and are not credential fields

variable CREDENTIALS_PREFIX

const CREDENTIALS_PREFIX: string;

Prefix of all credential object IDs

variable CREDENTIALS_VERSION

const CREDENTIALS_VERSION: number;

Current version of the credential data format

function getCredentialForm

getCredentialForm: (values: Record<string, any>) => CredentialForm;

Detects the form of a credential from its fields.
Parameter values
The credential fields (e.g. CredentialInfo.values)

function getCredentials

getCredentials: <T extends Record<string, any> = CustomCredentials>(
    adapter: ioBroker.Adapter,
    id: string
) => Promise<CredentialInfo<T>>;

Reads one credential and decrypts all encrypted fields with the system secret.
Parameter adapter
The adapter instance
Parameter id
The credential ID, e.g. system.credentials.anthropic (usually taken from the instance configuration where the user selected it via the credential JsonConfig component)

function listCredentials

listCredentials: (
    adapter: ioBroker.Adapter,
    type?: CredentialType | (string & {})
) => Promise<CredentialListEntry[]>;

Lists all stored credentials (without decrypting any secrets).
Parameter adapter
The adapter instance
Parameter type
Optional: only list credentials of this type, e.g. 'ai'

function subscribeCredentials

subscribeCredentials: <T extends Record<string, any> = CustomCredentials>(
    adapter: ioBroker.Adapter,
    id: string,
    handler: (id: string, credentials: CredentialInfo<T> | null) => void
) => Promise<() => Promise<void>>;

Subscribes to changes of one credential, so the adapter can e.g. reconnect when the user edits the credential in the admin UI.
Parameter adapter
The adapter instance
Parameter id
The credential ID, e.g. system.credentials.anthropic
Parameter handler
Called with the decrypted credential on every change, or with null if the credential was deleted
Returns
A function that unsubscribes again

interface CredentialFieldDefinition

interface CredentialFieldDefinition {}

Description of one field of a credential form

property encrypted

encrypted?: boolean;

The field is stored encrypted with the system secret

property name

name: string;

Attribute name in the object's native

property required

required?: boolean;

The field must be filled

property type

type: 'text' | 'password';

How the field should be rendered and validated

interface CredentialInfo

interface CredentialInfo<T extends Record<string, any> = CustomCredentials> {}

A credential with all encrypted fields decrypted

property id

id: string;

Object ID, e.g. system.credentials.anthropic

property name

name: string;

Display name from common.name

property type

type: CredentialType | (string & {});

Credential type, e.g. 'ai'

property values

values: T;

The credential fields with all encrypted fields decrypted

interface CredentialListEntry

interface CredentialListEntry {}

One entry of the credential list (without any secrets)

property id

id: string;

Object ID, e.g. system.credentials.anthropic

property name

name: string;

Display name from common.name

property type

type: CredentialType | (string & {});

Credential type, e.g. 'ai'

interface KeyCredentials

interface KeyCredentials {}

Fields of a credential with the key form, e.g. an API key

property key

key: string;

The key (decrypted)

interface LoginPasswordCredentials

interface LoginPasswordCredentials {}

Fields of a credential with the login form

login: string;

User name / account / e-mail address

property password

password: string;

Password (decrypted)

type CredentialForm

type CredentialForm = 'login' | 'key';

The two forms a credential can have: login/password or a single key

type CredentialType

type CredentialType = 'email' | 'cloud' | 'ai' | 'custom';

Categories of credentials (stored in native.type)

type CustomCredentials

type CustomCredentials = Record<string, string | number | boolean>;

Fields of any credential

namespace I18n

module 'build/esm/i18n.d.ts' {}

Init internationalization
Parameter rootDir
The path, where i18n directory is located
Parameter languageOrAdapter
The adapter instance or the language to use

variable _default

const _default: {
    init: typeof init;
    translate: typeof translate;
    getTranslatedObject: typeof getTranslatedObject;
    t: typeof translate;
};

variable t

const t: (key: string, ...args: (string | number | boolean)[]) => string;

Alias shortcut for translate function

function getTranslatedObject

getTranslatedObject: (
    key: string,
    ...args: (string | number | boolean | null)[]
) => ioBroker.Translated;

Get translation as ioBroker.Translated object
Parameter key
Word to translate
Parameter args
Optional parameters to replace %s

function init

init: (
    rootDir: string,
    languageOrAdapter: ioBroker.Adapter | ioBroker.Languages
) => Promise<void>;

Init internationalization
Parameter rootDir
The path, where i18n directory is located
Parameter languageOrAdapter
The adapter instance or the language to use

function translate

translate: (
    key: string,
    ...args: (string | number | boolean | null)[]
) => string;

Get translation as one string
Parameter key
Word to translate
Parameter args
Optional parameters to replace %s

namespace TokenRefresher

module 'build/esm/TokenRefresher.d.ts' {}

Token structure

class TokenRefresher

class TokenRefresher {}

TokenRefresher class manages OAuth2 access tokens for an ioBroker adapter.

constructor

constructor(adapter: ioBroker.Adapter, serviceName: string, stateName?: string);

Creates an instance of TokenRefresher.
Parameter adapter
Instance of ioBroker adapter
Parameter serviceName
Name of the service for which the tokens are managed, e.g., 'spotify', 'dropbox', etc.
Parameter stateName
Optional name of the state where tokens are stored. Defaults to 'oauth2Tokens' and that will store tokens in ADAPTER.X.oauth2Tokens.

property TOKEN_REFRESH_THRESHOLD_MS

static TOKEN_REFRESH_THRESHOLD_MS: number;

Threshold in milliseconds before the access token expires to trigger a refresh

method destroy

destroy: () => void;

Destroys the TokenRefresher instance, clearing any timeouts and stopping state subscriptions.

method getAccessToken

getAccessToken: () => Promise<string | undefined>;

Returns the access token if it is valid and not expired.

method onStateChange

onStateChange: (id: string, state: ioBroker.State | null | undefined) => void;

This method is called when the state changes for the token.
Parameter id
ID of the state that changed
Parameter state
Value

interface AccessTokens

interface AccessTokens {}

Token structure

property access_token

access_token: string;

The access token used for authentication

property access_token_expires_on

access_token_expires_on: string;

The date and time when the access token expires, in ISO format

property expires_in

expires_in: number;

Interval in seconds, when access token will expire

property ext_expires_in

ext_expires_in: number;

Extended expiration time in seconds, when the access token will expire

property refresh_token

refresh_token: string;

The refresh token used to obtain a new access token

property scope

scope: string;

Scopes

property token_type

token_type: 'Bearer';

Type

Package Files (6)

Dependencies (0)

No dependencies.

Dev Dependencies (17)

Peer Dependencies (1)

@iobroker/types

Badge

To add a badge like this oneto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@iobroker/adapter-core.

Markdown

[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@iobroker/adapter-core)

HTML

<a href="https://www.jsdocs.io/package/@iobroker/adapter-core"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>

Updated just now.
Package analyzed in 2712 ms.
Missing or incorrect documentation? Open an issue for this package.

@iobroker/adapter-core

Install

Overview

Index

Variables

Functions

Interfaces

Type Aliases

Namespaces

Variables

variable adapter

variable Adapter

variable commonTools

variable controllerDir

variable EXIT_CODES

Functions

function getAbsoluteDefaultDataDir

function getAbsoluteInstanceDataDir

Parameter adapterObjectOrNamespace

function getConfig

Interfaces

interface AdapterInstance

property oObjects

property oStates

Type Aliases

type AdapterOptions

Namespaces

namespace Credentials

variable CREDENTIAL_FORMS

variable CREDENTIAL_META_FIELDS

variable CREDENTIALS_PREFIX

variable CREDENTIALS_VERSION

function getCredentialForm

Parameter values

function getCredentials

Parameter adapter

Parameter id

function listCredentials

Parameter adapter

Parameter type

function subscribeCredentials

Parameter adapter

Parameter id

Parameter handler

Returns

interface CredentialFieldDefinition

property encrypted

property name

property required

property type

interface CredentialInfo

property id

property name

property type

property values

interface CredentialListEntry

property id

property name

property type

interface KeyCredentials

property key

interface LoginPasswordCredentials

property login

property password

type CredentialForm

type CredentialType

type CustomCredentials

namespace I18n

Parameter rootDir

Parameter languageOrAdapter

variable _default

variable t

function getTranslatedObject

Parameter key

Parameter args

function init

Parameter rootDir

Parameter languageOrAdapter

function translate

Parameter key