@smarthome.exchange/integrations 0.2.0 → 2.0.0

package/ts/core/classes.nativeintegrationowner.ts

@@ -0,0 +1,297 @@
+import { NativeHomeAdmission, type INativeAdmissionContext, type INativeHomeAdmissionOptions } from './classes.nativehomeadmission.js';
+import type { IConfigFlowContext, IIntegrationSetupContext } from './types.js';
+
+export interface INativeIntegrationOwnerOptions extends INativeHomeAdmissionOptions {
+  /** Shared limit for pending operations, runtimes, and retained cleanup resources. Defaults to 16. */
+  readonly capacity?: number;
+}
+
+export interface INativeOperationLease {
+  readonly context: INativeAdmissionContext;
+  readonly signal: AbortSignal;
+  assertOpen(): void;
+  /** Register immediately after allocation, before invoking initialization or other foreign callbacks. */
+  own(cleanupArg: () => Promise<void>): void;
+  close(): Promise<void>;
+}
+
+export interface INativeSetupLease extends INativeOperationLease {
+  /** Transfers this operation's cleanup ownership to the returned runtime. */
+  promoteToRuntime(): void;
+}
+
+interface INativeResource {
+  readonly cleanup: () => Promise<void>;
+  status: 'idle' | 'pending' | 'closed' | 'failed';
+  promise?: Promise<void>;
+}
+
+interface INativeScopeState {
+  readonly lifetime: AbortController;
+  readonly leases: Set<NativeIntegrationLease>;
+  readonly operations: Set<Promise<unknown>>;
+  closed: boolean;
+  closePromise?: Promise<void>;
+  retryPromise?: Promise<void>;
+}
+
+const scopeState = (): INativeScopeState => ({ lifetime: new AbortController(), leases: new Set(), operations: new Set(), closed: false });
+
+class NativeIntegrationLease implements INativeSetupLease {
+  readonly #state: NativeOwnerState;
+  readonly #scope: INativeScopeState;
+  readonly #runtimeAllowed: boolean;
+  readonly #lifetime = new AbortController();
+  readonly #resources = new Set<INativeResource>();
+  readonly context: INativeAdmissionContext;
+  readonly signal: AbortSignal;
+  #pending = true;
+  #promoted = false;
+  #closed = false;
+  #closePromise?: Promise<void>;
+
+  constructor(stateArg: NativeOwnerState, scopeArg: INativeScopeState, contextArg: INativeAdmissionContext, runtimeAllowedArg: boolean) {
+    this.#state = stateArg;
+    this.#scope = scopeArg;
+    this.#runtimeAllowed = runtimeAllowedArg;
+    this.context = contextArg;
+    this.signal = AbortSignal.any([stateArg.lifetime.signal, scopeArg.lifetime.signal, this.#lifetime.signal,
+      ...(contextArg.abortSignal ? [contextArg.abortSignal] : [])]);
+    // Abort owns cleanup as well as cancellation; rejected cleanup remains on this retained lease.
+    this.signal.addEventListener('abort', () => { void this.close().catch(() => undefined); }, { once: true });
+  }
+
+  public get promoted(): boolean { return this.#promoted; }
+  public get weight(): number { return Math.max(1, [...this.#resources].filter((resource) => resource.status !== 'closed').length); }
+  public get failed(): boolean { return [...this.#resources].some((resource) => resource.status === 'failed'); }
+
+  public assertOpen(): void {
+    if (this.#closed || this.#state.closed || this.#scope.closed) throw new Error('Native admission lease is closed.');
+    this.signal.throwIfAborted();
+  }
+
+  public own(cleanupArg: () => Promise<void>): void {
+    this.assertOpen();
+    if (typeof cleanupArg !== 'function') throw new TypeError('Native cleanup must be a function.');
+    if ([...this.#resources].filter((resource) => resource.status !== 'closed').length > 0) this.#state.assertCapacity();
+    this.#resources.add({ cleanup: cleanupArg, status: 'idle' });
+  }
+
+  public promoteToRuntime(): void {
+    this.assertOpen();
+    if (!this.#runtimeAllowed || !this.#pending) throw new Error('Only an admitted pending setup can become a runtime.');
+    if (!this.#resources.size) throw new Error('A native runtime must retain an owned cleanup handle.');
+    this.#promoted = true;
+  }
+
+  public finish(): void { this.#pending = false; this.#releaseIfClosed(); }
+
+  public close(): Promise<void> {
+    if (!this.#closePromise) {
+      this.#closed = true;
+      this.#closePromise = Promise.resolve().then(() => this.#drain(false));
+      this.#lifetime.abort(new Error('Native admission lease is closed.'));
+    }
+    return this.#closePromise;
+  }
+
+  public retryCleanup(): Promise<void> { return this.#drain(true); }
+
+  async #drain(retryArg: boolean): Promise<void> {
+    const results = await Promise.allSettled([...this.#resources].map((resource) => {
+      if (retryArg && resource.status === 'failed') resource.promise = undefined;
+      if (!resource.promise) {
+        resource.status = 'pending';
+        resource.promise = Promise.resolve().then(() => resource.cleanup()).then(() => {
+          resource.status = 'closed';
+        }, (errorArg: unknown) => {
+          resource.status = 'failed';
+          throw errorArg;
+        });
+      }
+      return resource.promise;
+    }));
+    this.#releaseIfClosed();
+    const failures = results.filter((result): result is PromiseRejectedResult => result.status === 'rejected').map((result) => result.reason as unknown);
+    if (failures.length) throw new AggregateError(failures, 'Native resource cleanup failed; handles remain owned for explicit retry.');
+  }
+
+  #releaseIfClosed(): void {
+    if (!this.#pending && this.#closed && [...this.#resources].every((resource) => resource.status === 'closed')) {
+      this.#state.release(this, this.#scope);
+    }
+  }
+}
+
+class NativeOwnerState {
+  readonly admission: NativeHomeAdmission;
+  readonly lifetime = new AbortController();
+  readonly root = scopeState();
+  readonly #capacity: number;
+  readonly #leases = new Set<NativeIntegrationLease>();
+  readonly #scopes = new Set<INativeScopeState>([this.root]);
+  closed = false;
+  #closePromise?: Promise<void>;
+  #retryPromise?: Promise<void>;
+
+  constructor(domainArg: string, optionsArg: INativeIntegrationOwnerOptions) {
+    if (!optionsArg || (Object.getPrototypeOf(optionsArg) !== Object.prototype && Object.getPrototypeOf(optionsArg) !== null)) {
+      throw new TypeError('Native owner options must be a plain data object.');
+    }
+    for (const key of Reflect.ownKeys(optionsArg)) {
+      const descriptor = Object.getOwnPropertyDescriptor(optionsArg, key);
+      if ((key !== 'homeId' && key !== 'capacity') || !descriptor || !descriptor.enumerable || !('value' in descriptor)) {
+        throw new TypeError('Native owner options contain an unsupported field or accessor.');
+      }
+    }
+    this.#capacity = optionsArg.capacity ?? 16;
+    if (!Number.isSafeInteger(this.#capacity) || this.#capacity < 1) throw new RangeError('Native owner capacity must be a positive safe integer.');
+    this.admission = new NativeHomeAdmission(domainArg, { homeId: optionsArg.homeId });
+  }
+
+  public assertOpen(scopeArg: INativeScopeState): void {
+    if (this.closed || scopeArg.closed) throw new Error('Native integration owner/scope is closed.');
+  }
+
+  public assertCapacity(): void {
+    if ([...this.#leases].reduce((count, lease) => count + lease.weight, 0) >= this.#capacity) {
+      throw new Error(`Native integration ownership capacity reached: ${this.#capacity}.`);
+    }
+  }
+
+  public createScope(): INativeScopeState {
+    this.assertOpen(this.root);
+    if (this.#scopes.size > this.#capacity) throw new Error('Native config-flow scope capacity reached.');
+    const scope = scopeState();
+    this.#scopes.add(scope);
+    return scope;
+  }
+
+  public admit(scopeArg: INativeScopeState, contextArg: IIntegrationSetupContext | IConfigFlowContext, configHomeIdArg?: string): INativeAdmissionContext {
+    this.assertOpen(scopeArg);
+    return this.admission.admit(contextArg, configHomeIdArg);
+  }
+
+  public run<TResult>(scopeArg: INativeScopeState, contextArg: IIntegrationSetupContext | IConfigFlowContext,
+    configHomeIdArg: string | undefined, workArg: (leaseArg: INativeSetupLease) => Promise<TResult>, runtimeArg: boolean): Promise<TResult> {
+    this.assertOpen(scopeArg);
+    if (typeof workArg !== 'function') throw new TypeError('Native operation must be a function.');
+    if (runtimeArg && typeof configHomeIdArg !== 'string') throw new TypeError('Native setup requires configuration homeId.');
+    this.assertCapacity();
+    const context = this.admission.admit(contextArg, configHomeIdArg);
+    const lease = new NativeIntegrationLease(this, scopeArg, context, runtimeArg);
+    this.#leases.add(lease);
+    scopeArg.leases.add(lease);
+    // Publish ownership and work before invoking any caller callback.
+    const operation = Promise.resolve().then(async () => {
+      try {
+        lease.assertOpen();
+        const result = await workArg(lease);
+        if (runtimeArg) {
+          // Returning a live runtime is a new admission; a completed flow effect is already accepted.
+          lease.assertOpen();
+          if (!lease.promoted) throw new Error('Native setup must transfer its cleanup lease to the returned runtime.');
+        }
+        if (!runtimeArg) await lease.close();
+        return result;
+      } catch (errorArg) {
+        try { await lease.close(); }
+        catch (cleanupErrorArg) { throw new AggregateError([errorArg, cleanupErrorArg], 'Native operation and cleanup failed.'); }
+        throw errorArg;
+      } finally { lease.finish(); }
+    });
+    scopeArg.operations.add(operation);
+    void operation.then(() => scopeArg.operations.delete(operation), () => scopeArg.operations.delete(operation));
+    return operation;
+  }
+
+  public release(leaseArg: NativeIntegrationLease, scopeArg: INativeScopeState): void {
+    this.#leases.delete(leaseArg);
+    scopeArg.leases.delete(leaseArg);
+  }
+
+  public closeScope(scopeArg: INativeScopeState): Promise<void> {
+    if (!scopeArg.closePromise) {
+      scopeArg.closed = true;
+      scopeArg.closePromise = Promise.resolve().then(async () => {
+        await this.#drain([scopeArg]);
+        this.#scopes.delete(scopeArg);
+      });
+      for (const lease of scopeArg.leases) void lease.close().catch(() => undefined);
+      scopeArg.lifetime.abort(new Error('Native config-flow scope is closed.'));
+    }
+    return scopeArg.closePromise;
+  }
+
+  public close(): Promise<void> {
+    if (!this.#closePromise) {
+      this.closed = true;
+      for (const scope of this.#scopes) scope.closed = true;
+      this.#closePromise = Promise.resolve().then(() => this.#drain([...this.#scopes]));
+      for (const lease of this.#leases) void lease.close().catch(() => undefined);
+      this.lifetime.abort(new Error('Native integration owner is closed.'));
+      for (const scope of this.#scopes) scope.lifetime.abort(this.lifetime.signal.reason);
+    }
+    return this.#closePromise;
+  }
+
+  public retryCleanup(scopeArg?: INativeScopeState): Promise<void> {
+    const existing = scopeArg ? scopeArg.retryPromise : this.#retryPromise;
+    if (existing) return existing;
+    const retry = Promise.resolve().then(async () => {
+      const leases = [...(scopeArg ? scopeArg.leases : this.#leases)].filter((lease) => lease.failed);
+      const results = await Promise.allSettled(leases.map((lease) => lease.retryCleanup()));
+      const errors = results.filter((result): result is PromiseRejectedResult => result.status === 'rejected').map((result) => result.reason as unknown);
+      if (errors.length) throw new AggregateError(errors, 'Explicit native cleanup retry failed.');
+      for (const scope of this.#scopes) {
+        if (scope !== this.root && scope.closed && !scope.leases.size && !scope.operations.size) this.#scopes.delete(scope);
+      }
+    });
+    if (scopeArg) scopeArg.retryPromise = retry;
+    else this.#retryPromise = retry;
+    const settled = (): void => { if (scopeArg) scopeArg.retryPromise = undefined; else this.#retryPromise = undefined; };
+    void retry.then(settled, settled);
+    return retry;
+  }
+
+  async #drain(scopesArg: INativeScopeState[]): Promise<void> {
+    const cleanup = scopesArg.flatMap((scope) => [...scope.leases].map((lease) => lease.close()));
+    const operations = scopesArg.flatMap((scope) => [...scope.operations]);
+    const [results] = await Promise.all([Promise.allSettled(cleanup), Promise.allSettled(operations)]);
+    // Operation failures are delivered to their callers; owner close owns joining and cleanup failures.
+    const finalResults = await Promise.allSettled(scopesArg.flatMap((scope) => [...scope.leases].map((lease) => lease.close())));
+    const errors = [...results, ...finalResults].filter((result): result is PromiseRejectedResult => result.status === 'rejected').map((result) => result.reason as unknown);
+    if (errors.length) throw new AggregateError([...new Set(errors)], 'Native owner cleanup failed; resources remain retained.');
+  }
+}
+
+/** A terminal child scope shares owner home admission and resource capacity. */
+export class NativeIntegrationScope {
+  readonly #state: NativeOwnerState;
+  readonly #scope: INativeScopeState;
+  constructor(stateArg: NativeOwnerState, scopeArg: INativeScopeState) { this.#state = stateArg; this.#scope = scopeArg; }
+  public admit(contextArg: IConfigFlowContext, configHomeIdArg?: string): INativeAdmissionContext {
+    return this.#state.admit(this.#scope, contextArg, configHomeIdArg);
+  }
+  public run<TResult>(contextArg: IConfigFlowContext, configHomeIdArg: string | undefined,
+    workArg: (leaseArg: INativeOperationLease) => Promise<TResult>): Promise<TResult> {
+    return this.#state.run(this.#scope, contextArg, configHomeIdArg, workArg, false);
+  }
+  public close(): Promise<void> { return this.#state.closeScope(this.#scope); }
+  public retryCleanup(): Promise<void> { return this.#state.retryCleanup(this.#scope); }
+}
+
+/** Owns native admission, in-flight work, runtimes and failed cleanup without replaying transport work. */
+export class NativeIntegrationOwner {
+  readonly #state: NativeOwnerState;
+  constructor(domainArg: string, optionsArg: INativeIntegrationOwnerOptions = {}) { this.#state = new NativeOwnerState(domainArg, optionsArg); }
+  public get admission(): NativeHomeAdmission { return this.#state.admission; }
+  public get signal(): AbortSignal { return this.#state.lifetime.signal; }
+  public runSetup<TResult>(contextArg: IIntegrationSetupContext, configHomeIdArg: string,
+    workArg: (leaseArg: INativeSetupLease) => Promise<TResult>): Promise<TResult> {
+    return this.#state.run(this.#state.root, contextArg, configHomeIdArg, workArg, true);
+  }
+  public createFlowScope(): NativeIntegrationScope { return new NativeIntegrationScope(this.#state, this.#state.createScope()); }
+  public close(): Promise<void> { return this.#state.close(); }
+  public retryCleanup(): Promise<void> { return this.#state.retryCleanup(); }
+}

package/ts/core/index.ts

@@ -9,3 +9,5 @@ export * from './classes.runtimemanager.js';
 export * from './classes.simplelocalintegration.js';
 export * from './errors.js';
 export * from './types.js';
+export * from './classes.nativehomeadmission.js';
+export * from './classes.nativeintegrationowner.js';

package/ts/core/types.ts

@@ -1,4 +1,5 @@
 import * as plugins from '../plugins.js';
+import type { NoSqlConfigStore } from './classes.configstore.js';
 
 export type TDiscoverySource =
   | 'mdns'
@@ -34,11 +35,22 @@ export interface INetworkInterface {
   internal: boolean;
 }
 
+export interface IConfigStoreOperationOptions {
+  /** A prepared caller-owned transaction supplies the database deadline. */
+  session?: plugins.nosqldb.SmartdataSession;
+}
+
+export interface IConfigStoreScope {
+  readonly homeId: string;
+  readonly integrationDomain: string;
+}
+
 export interface IConfigStore {
-  get<TValue>(keyArg: string): Promise<TValue | undefined>;
-  set<TValue>(keyArg: string, valueArg: TValue): Promise<void>;
-  delete(keyArg: string): Promise<void>;
-  list(prefixArg?: string): Promise<string[]>;
+  getScope?(): IConfigStoreScope;
+  get<TValue>(keyArg: string, optionsArg?: IConfigStoreOperationOptions): Promise<TValue | undefined>;
+  set<TValue>(keyArg: string, valueArg: TValue, optionsArg?: IConfigStoreOperationOptions): Promise<void>;
+  delete(keyArg: string, optionsArg?: IConfigStoreOperationOptions): Promise<void>;
+  list(prefixArg?: string, optionsArg?: IConfigStoreOperationOptions): Promise<string[]>;
 }
 
 export interface IDiscoveryContext {
@@ -101,11 +113,18 @@ export interface IDiscoveryDescriptorOptions {
 }
 
 export interface IIntegrationSetupContext {
+  /** Explicit owning home selected by the embedding host, never by device configuration. */
+  readonly homeId?: string;
   logger?: ILogger;
   configStore?: IConfigStore;
   abortSignal?: AbortSignal;
 }
 
+export interface INativeIntegrationSetupContext extends IIntegrationSetupContext {
+  readonly homeId: string;
+  readonly configStore?: NoSqlConfigStore;
+}
+
 export type TEntityPlatform =
   | 'light'
   | 'switch'
@@ -200,8 +219,16 @@ export interface IConfigFlowField {
 }
 
 export interface IConfigFlowContext {
+  /** Explicit owning home selected by the embedding host. This is not an authentication token. */
+  readonly homeId?: string;
   logger?: ILogger;
   configStore?: IConfigStore;
+  abortSignal?: AbortSignal;
+}
+
+export interface INativeConfigFlowContext extends IConfigFlowContext {
+  readonly homeId: string;
+  readonly configStore?: NoSqlConfigStore;
 }
 
 export interface IConfigFlowStep<TConfig = unknown> {

package/ts/index.ts

@@ -417,12 +417,14 @@ import { SoundtouchIntegration } from './integrations/soundtouch/index.js';
 import { SqueezeboxIntegration } from './integrations/squeezebox/index.js';
 import { SynologyDsmIntegration } from './integrations/synology_dsm/index.js';
 import { SynologySrmIntegration } from './integrations/synology_srm/index.js';
+import { HomeAssistantTasmotaIntegration } from './integrations/tasmota/index.js';
 import { TomatoIntegration } from './integrations/tomato/index.js';
 import { TplinkIntegration } from './integrations/tplink/index.js';
 import { TplinkLteIntegration } from './integrations/tplink_lte/index.js';
 import { TplinkOmadaIntegration } from './integrations/tplink_omada/index.js';
 import { TradfriIntegration } from './integrations/tradfri/index.js';
 import { TransmissionIntegration } from './integrations/transmission/index.js';
+import { TuyaIntegration } from './integrations/tuya/index.js';
 import { TwinklyIntegration } from './integrations/twinkly/index.js';
 import { UbusIntegration } from './integrations/ubus/index.js';
 import { UnifiIntegration } from './integrations/unifi/index.js';
@@ -460,6 +462,7 @@ import { ZhaIntegration } from './integrations/zha/index.js';
 import { ZiggoMediaboxXlIntegration } from './integrations/ziggo_mediabox_xl/index.js';
 import { ZoneminderIntegration } from './integrations/zoneminder/index.js';
 import { ZwaveJsIntegration } from './integrations/zwave_js/index.js';
+import { Zigbee2MqttIntegration } from './integrations/zigbee2mqtt/index.js';
 import { generatedHomeAssistantPortIntegrations } from './integrations/generated/index.js';
 import { IntegrationRegistry } from './core/index.js';
 
@@ -879,12 +882,14 @@ export const integrations = [
   new SqueezeboxIntegration(),
   new SynologyDsmIntegration(),
   new SynologySrmIntegration(),
+  new HomeAssistantTasmotaIntegration(),
   new TomatoIntegration(),
   new TplinkIntegration(),
   new TplinkLteIntegration(),
   new TplinkOmadaIntegration(),
   new TradfriIntegration(),
   new TransmissionIntegration(),
+  new TuyaIntegration(),
   new TwinklyIntegration(),
   new UbusIntegration(),
   new UnifiIntegration(),
@@ -910,6 +915,7 @@ export const integrations = [
   new WiimIntegration(),
   new WizIntegration(),
   new WledIntegration(),
+  new Zigbee2MqttIntegration(),
   new WolfSmartsetIntegration(),
   new XiaomiMiioIntegration(),
   new YamahaIntegration(),