import * as mi from "@distilled.cloud/aws/iot-managed-integrations";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, hasAlchemyTags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Redacted from "effect/Redacted";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import { syncManagedIntegrationsTags, toTagRecord, unwrapSensitive } from "./internal.ts";
export class ManagedThingUnexpectedResponse extends Data.TaggedError(
"ManagedThingUnexpectedResponse",
)<{
readonly message: string;
readonly cause?: unknown;
}> {}
export interface ManagedThingProps {
/**
* Role of the device in Managed integrations: a `CONTROLLER` onboards and
* controls devices; a `DEVICE` is an endpoint. Changing the role replaces
* the managed thing.
*/
role: mi.Role;
/**
* Authentication material used to onboard the device (e.g. the payload of
* a Wi-Fi setup or Zigbee QR bar code). This is a device-onboarding
* credential — wrap it with `Redacted.make(...)`. Create-only — changing
* it replaces the managed thing.
*/
authenticationMaterial: Redacted.Redacted<string>;
/**
* Type of the authentication material.
* E.g. `WIFI_SETUP_QR_BAR_CODE`, `ZIGBEE_QR_BAR_CODE`, `ZWAVE_QR_BAR_CODE`.
* Create-only — changing it replaces the managed thing.
*/
authenticationMaterialType: mi.AuthMaterialType;
/**
* Display name of the managed thing. If omitted, a unique name is generated
* from the app, stage, and logical ID.
*/
name?: string;
/**
* Identifier of the credential locker used by the managed thing.
*/
credentialLockerId?: string;
/**
* Owner of the managed thing.
*/
owner?: string;
/**
* Serial number of the device.
*/
serialNumber?: string;
/**
* Brand of the device.
*/
brand?: string;
/**
* Model of the device.
*/
model?: string;
/**
* Classification of the managed thing.
*/
classification?: string;
/**
* Capability report of the device.
*/
capabilityReport?: mi.CapabilityReport;
/**
* Metadata key-value pairs for the managed thing.
*/
metaData?: Record<string, string>;
/**
* User-defined tags to apply to the managed thing.
*/
tags?: Record<string, string>;
}
export interface ManagedThing extends Resource<
"AWS.IoTManagedIntegrations.ManagedThing",
ManagedThingProps,
{
/** Service-generated identifier of the managed thing. */
managedThingId: string;
/** ARN of the managed thing. */
managedThingArn: string;
/** Display name of the managed thing. */
managedThingName: string;
/** Role of the device (CONTROLLER or DEVICE). */
role: mi.Role;
/** Provisioning status of the managed thing. */
provisioningStatus: mi.ProvisioningStatus | undefined;
/** Tags applied to the managed thing (user + internal). */
tags: Record<string, string>;
},
never,
Providers
> {}
/**
* An AWS IoT Managed Integrations managed thing — the cloud representation of
* a device (or controller) onboarded through Managed integrations, carrying
* its identity, protocol, and capability data model.
*
* Creating a managed thing requires real device onboarding material (e.g. a
* Wi-Fi Simple Setup or Zigbee QR bar code payload). IoT Managed Integrations
* is a regional service available in a limited set of regions (e.g.
* `eu-west-1`, `ca-central-1`).
*
* ### Creating Managed Things
* **Example:** Controller from a Wi-Fi Setup QR Code
* ```typescript
* const thing = yield* ManagedThing("Hub", {
* role: "CONTROLLER",
* authenticationMaterial: Redacted.make(wifiSetupQrCodePayload),
* authenticationMaterialType: "WIFI_SETUP_QR_BAR_CODE",
* });
* ```
*
* **Example:** Device with a Credential Locker
* ```typescript
* const locker = yield* CredentialLocker("DeviceCredentials", {});
* const thing = yield* ManagedThing("Sensor", {
* role: "DEVICE",
* authenticationMaterial: Redacted.make(zigbeeQrCodePayload),
* authenticationMaterialType: "ZIGBEE_QR_BAR_CODE",
* credentialLockerId: locker.credentialLockerId,
* serialNumber: "SN-0001",
* });
* ```
*
* @resource
*/
export const ManagedThing = Resource<ManagedThing>("AWS.IoTManagedIntegrations.ManagedThing");
export const ManagedThingProvider = () =>
Provider.effect(
ManagedThing,
Effect.gen(function* () {
const toName = (id: string, props: { name?: string } = {}) =>
props.name ? Effect.succeed(props.name) : createPhysicalName({ id, maxLength: 64 });
const observeById = (identifier: string) =>
mi
.getManagedThing({ Identifier: identifier })
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
// Recover an existing managed thing by display name when no Id is
// cached (e.g. after a state persistence failure).
const findByName = Effect.fn(function* (name: string) {
const summary = yield* mi.listManagedThings.items({}).pipe(
Stream.filter((item) => item.Name === name),
Stream.take(1),
Stream.runCollect,
Effect.map((chunk) => Array.from(chunk)[0]),
);
if (summary?.Id === undefined) return undefined;
return yield* observeById(summary.Id);
});
const toAttributes = Effect.fn(function* (thing: mi.GetManagedThingResponse) {
if (
thing.Id === undefined ||
thing.Arn === undefined ||
thing.Name === undefined ||
thing.Role === undefined
) {
return yield* new ManagedThingUnexpectedResponse({
message: "managed thing response is missing Id, Arn, Name, or Role",
});
}
return {
managedThingId: thing.Id,
managedThingArn: thing.Arn,
managedThingName: thing.Name,
role: thing.Role,
provisioningStatus: thing.ProvisioningStatus,
tags: toTagRecord(thing.Tags),
};
});
return {
stables: ["managedThingId", "managedThingArn"],
diff: Effect.fn(function* ({ olds, news }) {
if (!isResolved(news)) return;
if (olds === undefined) return;
// Role and authentication material are create-only.
if (
olds.role !== news.role ||
Redacted.value(olds.authenticationMaterial) !==
Redacted.value(news.authenticationMaterial) ||
olds.authenticationMaterialType !== news.authenticationMaterialType
) {
return { action: "replace" } as const;
}
}),
read: Effect.fn(function* ({ id, olds, output }) {
const thing =
output?.managedThingId !== undefined
? yield* observeById(output.managedThingId)
: yield* findByName(yield* toName(id, olds ?? {}));
if (thing === undefined) return undefined;
const attrs = yield* toAttributes(thing);
return (yield* hasAlchemyTags(id, attrs.tags)) ? attrs : Unowned(attrs);
}),
reconcile: Effect.fn(function* ({ id, news, output, session }) {
const name = yield* toName(id, news);
const internalTags = yield* createInternalTags(id);
const desiredTags = { ...internalTags, ...news.tags };
// Observe — cloud state is authoritative; output is only an Id cache.
let thing =
output?.managedThingId !== undefined
? yield* observeById(output.managedThingId)
: yield* findByName(name);
// Ensure — create if missing.
if (thing === undefined) {
const created = yield* mi.createManagedThing({
Role: news.role,
AuthenticationMaterial: news.authenticationMaterial,
AuthenticationMaterialType: news.authenticationMaterialType,
Name: name,
CredentialLockerId: news.credentialLockerId,
Owner: news.owner,
SerialNumber: news.serialNumber,
Brand: news.brand,
Model: news.model,
Classification: news.classification,
CapabilityReport: news.capabilityReport,
MetaData: news.metaData,
Tags: desiredTags,
});
if (created.Id === undefined) {
return yield* new ManagedThingUnexpectedResponse({
message: `failed to create managed thing '${name}'`,
});
}
thing = yield* observeById(created.Id);
if (thing === undefined) {
return yield* new ManagedThingUnexpectedResponse({
message: `managed thing '${created.Id}' vanished after create`,
});
}
} else if (thing.Id !== undefined) {
// Sync mutable, observable fields — apply only the delta.
const observed = {
name: thing.Name,
credentialLockerId: thing.CredentialLockerId,
owner: unwrapSensitive(thing.Owner),
serialNumber: unwrapSensitive(thing.SerialNumber),
brand: unwrapSensitive(thing.Brand),
model: unwrapSensitive(thing.Model),
classification: unwrapSensitive(thing.Classification),
};
const desired = {
name,
credentialLockerId: news.credentialLockerId,
owner: news.owner,
serialNumber: news.serialNumber,
brand: news.brand,
model: news.model,
classification: news.classification,
};
const changed = (Object.keys(desired) as (keyof typeof desired)[]).filter(
(key) => desired[key] !== undefined && desired[key] !== observed[key],
);
if (changed.length > 0) {
yield* mi.updateManagedThing({
Identifier: thing.Id,
Name: name,
CredentialLockerId: news.credentialLockerId,
Owner: news.owner,
SerialNumber: news.serialNumber,
Brand: news.brand,
Model: news.model,
Classification: news.classification,
MetaData: news.metaData,
});
thing = yield* observeById(thing.Id);
if (thing === undefined) {
return yield* new ManagedThingUnexpectedResponse({
message: `managed thing '${name}' vanished during update`,
});
}
}
}
// Sync tags — diff against OBSERVED cloud tags.
if (thing.Arn !== undefined) {
yield* syncManagedIntegrationsTags(thing.Arn, toTagRecord(thing.Tags), desiredTags);
}
const attrs = yield* toAttributes(thing);
yield* session.note(attrs.managedThingArn);
return { ...attrs, tags: desiredTags };
}),
// Enumerate every managed thing in the account/region; fetch each one
// to resolve tags (summaries omit them).
list: () =>
Effect.gen(function* () {
const summaries = yield* mi.listManagedThings.items({}).pipe(
Stream.runCollect,
Effect.map((chunk) => Array.from(chunk)),
);
const things = yield* Effect.forEach(
summaries.filter(
(s): s is mi.ManagedThingSummary & { Id: string } => s.Id !== undefined,
),
(summary) => observeById(summary.Id),
{ concurrency: 5 },
);
return yield* Effect.forEach(
things.filter((thing): thing is mi.GetManagedThingResponse => thing !== undefined),
toAttributes,
);
}),
delete: Effect.fn(function* ({ output }) {
yield* mi
.deleteManagedThing({ Identifier: output.managedThingId })
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
}),
};
}),
);