sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ IoTWireless/ WirelessDevice.ts

import * as iotw from "@distilled.cloud/aws/iot-wireless";
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, createTagsList, 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 { readIotWirelessTags, sameShape, syncIotWirelessTags } from "./internal.ts";

export class WirelessDeviceUnexpectedResponse extends Data.TaggedError(
  "WirelessDeviceUnexpectedResponse",
)<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

/**
 * LoRaWAN OTAA v1.1 activation keys. The root keys (`AppKey`, `NwkKey`) are
 * secrets — wrap them with `Redacted.make(...)`.
 */
export interface OtaaV1_1Props {
  /** The AppKey root key. Secret key material. */
  AppKey?: Redacted.Redacted<string>;
  /** The NwkKey root key. Secret key material. */
  NwkKey?: Redacted.Redacted<string>;
  /** The JoinEUI identifier (public). */
  JoinEui?: string;
}

/**
 * LoRaWAN OTAA v1.0.x activation keys. The root keys (`AppKey`, `GenAppKey`)
 * are secrets — wrap them with `Redacted.make(...)`.
 */
export interface OtaaV1_0_xProps {
  /** The AppKey root key. Secret key material. */
  AppKey?: Redacted.Redacted<string>;
  /** The AppEUI identifier (public). */
  AppEui?: string;
  /** The JoinEUI identifier (public). */
  JoinEui?: string;
  /** The GenAppKey root key. Secret key material. */
  GenAppKey?: Redacted.Redacted<string>;
}

/**
 * LoRaWAN ABP v1.1 session keys. All four keys are secrets — wrap them with
 * `Redacted.make(...)`.
 */
export interface SessionKeysAbpV1_1Props {
  /** The FNwkSIntKey session key. Secret key material. */
  FNwkSIntKey?: Redacted.Redacted<string>;
  /** The SNwkSIntKey session key. Secret key material. */
  SNwkSIntKey?: Redacted.Redacted<string>;
  /** The NwkSEncKey session key. Secret key material. */
  NwkSEncKey?: Redacted.Redacted<string>;
  /** The AppSKey session key. Secret key material. */
  AppSKey?: Redacted.Redacted<string>;
}

/** LoRaWAN ABP v1.1 activation configuration. */
export interface AbpV1_1Props {
  /** The device address (public). */
  DevAddr?: string;
  /** Session keys. Secret key material. */
  SessionKeys?: SessionKeysAbpV1_1Props;
  /** The initial FCnt value. */
  FCntStart?: number;
}

/**
 * LoRaWAN ABP v1.0.x session keys. Both keys are secrets — wrap them with
 * `Redacted.make(...)`.
 */
export interface SessionKeysAbpV1_0_xProps {
  /** The NwkSKey session key. Secret key material. */
  NwkSKey?: Redacted.Redacted<string>;
  /** The AppSKey session key. Secret key material. */
  AppSKey?: Redacted.Redacted<string>;
}

/** LoRaWAN ABP v1.0.x activation configuration. */
export interface AbpV1_0_xProps {
  /** The device address (public). */
  DevAddr?: string;
  /** Session keys. Secret key material. */
  SessionKeys?: SessionKeysAbpV1_0_xProps;
  /** The initial FCnt value. */
  FCntStart?: number;
}

/**
 * LoRaWAN device configuration. Mirrors the wire shape, with the activation
 * key material typed as `Redacted` so secrets never leak into logs or state
 * diffs.
 */
export interface LoRaWANDeviceProps {
  /** The DevEUI radio identifier (public). Changing it replaces the device. */
  DevEui?: string;
  /** ID of the device profile the device uses. Updates in place. */
  DeviceProfileId?: string;
  /** ID of the service profile the device uses. Updates in place. */
  ServiceProfileId?: string;
  /** OTAA v1.1 activation keys. Changing them replaces the device. */
  OtaaV1_1?: OtaaV1_1Props;
  /** OTAA v1.0.x activation keys. Changing them replaces the device. */
  OtaaV1_0_x?: OtaaV1_0_xProps;
  /** ABP v1.1 activation configuration. Changing it replaces the device. */
  AbpV1_1?: AbpV1_1Props;
  /** ABP v1.0.x activation configuration. Changing it replaces the device. */
  AbpV1_0_x?: AbpV1_0_xProps;
  /** FPort configuration. Updates in place. */
  FPorts?: iotw.FPorts;
}

export interface WirelessDeviceProps {
  /**
   * The wireless technology the device uses. Changing the type replaces the
   * device.
   */
  type: "LoRaWAN" | "Sidewalk";
  /**
   * Name of the destination that routes the device's uplink messages. Can be
   * changed in place.
   */
  destinationName: string;
  /**
   * Name of the wireless device. If omitted, a deterministic physical name
   * is generated from the app, stage, and logical ID. Can be changed in
   * place.
   */
  name?: string;
  /**
   * Human-readable description of the device.
   */
  description?: string;
  /**
   * LoRaWAN device configuration: `DevEui`, the device/service profile IDs,
   * and the activation keys (`OtaaV1_0_x`, `OtaaV1_1`, `AbpV1_0_x`,
   * `AbpV1_1`). The `DevEui` and activation keys are the device's radio
   * identity — changing them replaces the device; the profile IDs and
   * `FPorts` update in place. Key material is secret — wrap each key with
   * `Redacted.make(...)`.
   */
  loRaWAN?: LoRaWANDeviceProps;
  /**
   * Whether position solving is enabled for the device (`Enabled` or
   * `Disabled`).
   */
  positioning?: iotw.PositioningConfigStatus;
  /**
   * Amazon Sidewalk device configuration. Changing the manufacturing serial
   * number replaces the device.
   */
  sidewalk?: iotw.SidewalkCreateWirelessDevice;
  /**
   * Tags applied to the device. Alchemy ownership tags are merged in
   * automatically.
   */
  tags?: Record<string, string>;
}

export interface WirelessDevice extends Resource<
  "AWS.IoTWireless.WirelessDevice",
  WirelessDeviceProps,
  {
    /** Server-assigned ID of the wireless device. */
    wirelessDeviceId: string;
    /** ARN of the wireless device. */
    wirelessDeviceArn: string;
    /** Name of the wireless device. */
    wirelessDeviceName: string;
    /** The wireless technology the device uses. */
    type: iotw.WirelessDeviceType;
    /** Name of the destination routing the device's uplinks. */
    destinationName: string;
  },
  never,
  Providers
> {}

/**
 * An AWS IoT Core for LoRaWAN (or Amazon Sidewalk) wireless device — the
 * cloud registration of a physical radio, wired to a {@link Destination}
 * for uplink routing and to a {@link DeviceProfile} / {@link ServiceProfile}
 * pair for its radio parameters.
 *
 * The device's radio identity (`type`, `DevEui`, activation keys) is
 * immutable — changing it replaces the device. The name, description,
 * destination, positioning, profile references, and tags update in place.
 * ### Creating Devices
 * **Example:** OTAA v1.0.x LoRaWAN Device
 * ```typescript
 * import * as IoTWireless from "@alchemy.run/aws/IoTWireless";
 *
 * const device = yield* IoTWireless.WirelessDevice("Sensor", {
 *   type: "LoRaWAN",
 *   destinationName: destination.destinationName,
 *   loRaWAN: {
 *     DevEui: "1122334455667788",
 *     DeviceProfileId: deviceProfile.deviceProfileId,
 *     ServiceProfileId: serviceProfile.serviceProfileId,
 *     OtaaV1_0_x: {
 *       AppKey: Redacted.make("00112233445566778899aabbccddeeff"),
 *       AppEui: "8877665544332211",
 *     },
 *   },
 * });
 * ```
 *
 * **Example:** Repoint a device at a different destination
 * ```typescript
 * const device = yield* IoTWireless.WirelessDevice("Sensor", {
 *   type: "LoRaWAN",
 *   destinationName: otherDestination.destinationName, // updates in place
 *   loRaWAN: { ... },
 * });
 * ```
 *
 * @resource
 */
export const WirelessDevice = Resource<WirelessDevice>("AWS.IoTWireless.WirelessDevice");

const unwrap = (value: Redacted.Redacted<string> | undefined) =>
  value === undefined ? undefined : Redacted.value(value);

/**
 * Convert the Redacted-keyed LoRaWAN prop shape to the plain wire shape the
 * IoT Wireless API expects.
 */
const toWireLoRaWAN = (loRaWAN: LoRaWANDeviceProps | undefined): iotw.LoRaWANDevice | undefined =>
  loRaWAN === undefined
    ? undefined
    : {
        DevEui: loRaWAN.DevEui,
        DeviceProfileId: loRaWAN.DeviceProfileId,
        ServiceProfileId: loRaWAN.ServiceProfileId,
        OtaaV1_1:
          loRaWAN.OtaaV1_1 === undefined
            ? undefined
            : {
                AppKey: unwrap(loRaWAN.OtaaV1_1.AppKey),
                NwkKey: unwrap(loRaWAN.OtaaV1_1.NwkKey),
                JoinEui: loRaWAN.OtaaV1_1.JoinEui,
              },
        OtaaV1_0_x:
          loRaWAN.OtaaV1_0_x === undefined
            ? undefined
            : {
                AppKey: unwrap(loRaWAN.OtaaV1_0_x.AppKey),
                AppEui: loRaWAN.OtaaV1_0_x.AppEui,
                JoinEui: loRaWAN.OtaaV1_0_x.JoinEui,
                GenAppKey: unwrap(loRaWAN.OtaaV1_0_x.GenAppKey),
              },
        AbpV1_1:
          loRaWAN.AbpV1_1 === undefined
            ? undefined
            : {
                DevAddr: loRaWAN.AbpV1_1.DevAddr,
                FCntStart: loRaWAN.AbpV1_1.FCntStart,
                SessionKeys:
                  loRaWAN.AbpV1_1.SessionKeys === undefined
                    ? undefined
                    : {
                        FNwkSIntKey: unwrap(loRaWAN.AbpV1_1.SessionKeys.FNwkSIntKey),
                        SNwkSIntKey: unwrap(loRaWAN.AbpV1_1.SessionKeys.SNwkSIntKey),
                        NwkSEncKey: unwrap(loRaWAN.AbpV1_1.SessionKeys.NwkSEncKey),
                        AppSKey: unwrap(loRaWAN.AbpV1_1.SessionKeys.AppSKey),
                      },
              },
        AbpV1_0_x:
          loRaWAN.AbpV1_0_x === undefined
            ? undefined
            : {
                DevAddr: loRaWAN.AbpV1_0_x.DevAddr,
                FCntStart: loRaWAN.AbpV1_0_x.FCntStart,
                SessionKeys:
                  loRaWAN.AbpV1_0_x.SessionKeys === undefined
                    ? undefined
                    : {
                        NwkSKey: unwrap(loRaWAN.AbpV1_0_x.SessionKeys.NwkSKey),
                        AppSKey: unwrap(loRaWAN.AbpV1_0_x.SessionKeys.AppSKey),
                      },
              },
        FPorts: loRaWAN.FPorts,
      };

/** The parts of a LoRaWAN device spec that form its immutable radio identity. */
const loRaWANIdentity = (loRaWAN: iotw.LoRaWANDevice | undefined) => ({
  DevEui: loRaWAN?.DevEui,
  OtaaV1_0_x: loRaWAN?.OtaaV1_0_x,
  OtaaV1_1: loRaWAN?.OtaaV1_1,
  AbpV1_0_x: loRaWAN?.AbpV1_0_x,
  AbpV1_1: loRaWAN?.AbpV1_1,
});

export const WirelessDeviceProvider = () =>
  Provider.effect(
    WirelessDevice,
    Effect.gen(function* () {
      const createName = Effect.fn(function* (id: string, props: { name?: string }) {
        return props.name ?? (yield* createPhysicalName({ id, maxLength: 256 }));
      });

      const getBy = (identifier: string, type: iotw.WirelessDeviceIdType) =>
        iotw
          .getWirelessDevice({ Identifier: identifier, IdentifierType: type })
          .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));

      const observe = Effect.fn(function* (
        output: WirelessDevice["Attributes"] | undefined,
        props: WirelessDeviceProps,
      ) {
        if (output?.wirelessDeviceId !== undefined) {
          const found = yield* getBy(output.wirelessDeviceId, "WirelessDeviceId");
          if (found !== undefined) return found;
        }
        // Recover identity by the device's radio identifier when state was
        // lost — the DevEui / Sidewalk serial is unique per account.
        if (props.loRaWAN?.DevEui !== undefined) {
          return yield* getBy(props.loRaWAN.DevEui, "DevEui");
        }
        if (props.sidewalk?.SidewalkManufacturingSn !== undefined) {
          return yield* getBy(props.sidewalk.SidewalkManufacturingSn, "SidewalkManufacturingSn");
        }
        return undefined;
      });

      const toAttrs = Effect.fn(function* (device: iotw.GetWirelessDeviceResponse, name: string) {
        if (device.Id === undefined || device.Arn === undefined) {
          return yield* new WirelessDeviceUnexpectedResponse({
            message: `IoT Wireless device '${name}' returned without Id/Arn`,
          });
        }
        return {
          wirelessDeviceId: device.Id,
          wirelessDeviceArn: device.Arn,
          wirelessDeviceName: device.Name ?? name,
          type: device.Type ?? "LoRaWAN",
          destinationName: device.DestinationName ?? "",
        };
      });

      return WirelessDevice.Provider.of({
        stables: ["wirelessDeviceId", "wirelessDeviceArn", "type"],

        list: () =>
          iotw.listWirelessDevices.pages({}).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk)
                .flatMap((page) => page.WirelessDeviceList ?? [])
                .flatMap((d) =>
                  d.Id !== undefined && d.Arn !== undefined
                    ? [
                        {
                          wirelessDeviceId: d.Id,
                          wirelessDeviceArn: d.Arn,
                          wirelessDeviceName: d.Name ?? d.Id,
                          type: d.Type ?? "LoRaWAN",
                          destinationName: d.DestinationName ?? "",
                        },
                      ]
                    : [],
                ),
            ),
          ),

        read: Effect.fn(function* ({ id, olds, output }) {
          const props = olds ?? { type: "LoRaWAN", destinationName: "" };
          const name = output?.wirelessDeviceName ?? (yield* createName(id, props));
          const device = yield* observe(output, props);
          if (device === undefined) return undefined;
          const attrs = yield* toAttrs(device, name);
          const tags = yield* readIotWirelessTags(attrs.wirelessDeviceArn);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),

        // The wireless technology and the radio identity (DevEui, activation
        // keys, Sidewalk serial) are create-only. Name, description,
        // destination, positioning, and profile references update in place.
        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news)) return undefined;
          if (olds !== undefined && olds.type !== news.type) {
            return { action: "replace" } as const;
          }
          if (
            !sameShape(
              loRaWANIdentity(toWireLoRaWAN(olds?.loRaWAN)),
              loRaWANIdentity(toWireLoRaWAN(news.loRaWAN)),
            )
          ) {
            return { action: "replace" } as const;
          }
          if (olds?.sidewalk?.SidewalkManufacturingSn !== news.sidewalk?.SidewalkManufacturingSn) {
            return { action: "replace" } as const;
          }
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const name = output?.wirelessDeviceName ?? (yield* createName(id, news));
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...news.tags, ...internalTags };

          // 1. OBSERVE — cloud state is authoritative; output is an id cache.
          let device = yield* observe(output, news);

          // 2. ENSURE — create if missing; a Conflict means the radio
          //    identity is already registered, so re-observe by it.
          if (device === undefined) {
            yield* session.note(`creating wireless device ${name}`);
            const created = yield* iotw
              .createWirelessDevice({
                Type: news.type,
                Name: name,
                Description: news.description,
                DestinationName: news.destinationName,
                LoRaWAN: toWireLoRaWAN(news.loRaWAN),
                Positioning: news.positioning,
                Sidewalk: news.sidewalk,
                Tags: createTagsList(desiredTags),
              })
              .pipe(Effect.catchTag("ConflictException", () => Effect.undefined));
            device =
              created?.Id !== undefined
                ? yield* getBy(created.Id, "WirelessDeviceId")
                : yield* observe(undefined, news);
          }
          if (device === undefined) {
            return yield* new WirelessDeviceUnexpectedResponse({
              message: `IoT Wireless device '${name}' not found after create`,
            });
          }
          const attrs = yield* toAttrs(device, name);

          // 3. SYNC — apply the mutable-aspect delta from OBSERVED state.
          const nameDelta = device.Name !== name;
          const descriptionDelta =
            news.description !== undefined && device.Description !== news.description;
          const destinationDelta = device.DestinationName !== news.destinationName;
          const positioningDelta =
            news.positioning !== undefined && device.Positioning !== news.positioning;
          const profileDelta =
            news.loRaWAN !== undefined &&
            (device.LoRaWAN?.DeviceProfileId !== news.loRaWAN.DeviceProfileId ||
              device.LoRaWAN?.ServiceProfileId !== news.loRaWAN.ServiceProfileId ||
              !sameShape(device.LoRaWAN?.FPorts, news.loRaWAN.FPorts));
          if (
            nameDelta ||
            descriptionDelta ||
            destinationDelta ||
            positioningDelta ||
            profileDelta
          ) {
            yield* iotw.updateWirelessDevice({
              Id: attrs.wirelessDeviceId,
              Name: name,
              Description: news.description,
              DestinationName: news.destinationName,
              Positioning: news.positioning,
              LoRaWAN:
                news.loRaWAN === undefined
                  ? undefined
                  : {
                      DeviceProfileId: news.loRaWAN.DeviceProfileId,
                      ServiceProfileId: news.loRaWAN.ServiceProfileId,
                      FPorts: news.loRaWAN.FPorts,
                    },
            });
          }

          // 3b. SYNC tags — diff against OBSERVED cloud tags.
          yield* syncIotWirelessTags(attrs.wirelessDeviceArn, desiredTags);

          // 4. RETURN fresh attributes.
          const final = yield* getBy(attrs.wirelessDeviceId, "WirelessDeviceId");
          if (final === undefined) {
            return yield* new WirelessDeviceUnexpectedResponse({
              message: `IoT Wireless device '${name}' vanished during update`,
            });
          }
          yield* session.note(attrs.wirelessDeviceId);
          return yield* toAttrs(final, name);
        }),

        delete: Effect.fn(function* ({ output }) {
          yield* iotw.deleteWirelessDevice({ Id: output.wirelessDeviceId }).pipe(
            Effect.asVoid,
            Effect.catchTag("ResourceNotFoundException", () => Effect.void),
          );
        }),
      });
    }),
  );