@novominteractive/ase-transport-aws-iot

AWS IoT transport for @novominteractive/anyware-stateless-client. Connects to AWS IoT Core over MQTT via WebSocket using a custom authorizer.

Installation

yarn add @novominteractive/anyware-stateless-client @novominteractive/ase-transport-aws-iot

Peer dependencies

| Package | Required | Notes | |---------|----------|-------| | @novominteractive/anyware-stateless-client | Yes | Core client |

Usage

import ASEClient from '@novominteractive/anyware-stateless-client';
import { AwsIotTransport } from '@novominteractive/ase-transport-aws-iot';

const client = new ASEClient({
  licenseKey: 'your-license-key',
  rootTopic: 'myProject/production',
  transport: new AwsIotTransport({
    authorizerName: 'AnywareAuthorizer-production',
    endpoint: 'xxxxx.iot.ca-central-1.amazonaws.com',
  }),
});

await client.connect(signedJwt);

Both authorizerName and endpoint are optional — they default to the Novom production values.

Token format

The AWS IoT transport expects a signed HS256 JWT. Use signAwsIotToken from @novominteractive/anyware-server-auth to issue one server-side:

import { signASEToken } from '@novominteractive/anyware-server-auth';

const token = await signASEToken({
  transport: 'aws-iot',
  payload: {
    subscribeTopics: ['myProject/events'],
    publishTopics:   ['myProject/commands'],
    ttlSeconds: 3600,
  },
  config: {
    secretKey:  process.env.SECRET_KEY!,
    licenseKey: 'your-license-key',
  },
});

The license key and the secret key will be issued by Novom Interactive.

Configuration

interface AwsIotTransportConfig {
  /**
   * Name of the AWS IoT custom authorizer Lambda.
   * Defaults to `'AnywareAuthorizer-production'`.
   */
  authorizerName?: string;
  /**
   * AWS IoT endpoint (`<prefix>.iot.<region>.amazonaws.com`).
   * Defaults to the Novom production endpoint.
   */
  endpoint?: string;
  /** Lifecycle event callbacks for the MQTT connection. */
  connectionHandlers?: IotConnectionHandlers;
  /**
   * MQTT last will message, published by AWS IoT if the client disconnects
   * unexpectedly. The connection token is injected under the `token` key
   * at connect time.
   */
  lastWill?: LastWillConfig;
}

interface IotConnectionHandlers {
  onInterrupt?: (error: CrtError) => any;
  onResume?: (returnCode: number, sessionPresent: boolean) => any;
  onDisconnect?: () => any;
  onError?: (error: CrtError) => any;
}

interface LastWillConfig {
  /** Full topic path for the last will message. */
  topic: string;
  /** Extra fields merged into the payload. The `token` key is reserved. */
  payload?: Record<string, string>;
}

Last will example

const transport = new AwsIotTransport({
  authorizerName: 'AnywareAuthorizer-production',
  endpoint: 'xxxxx.iot.ca-central-1.amazonaws.com',
  lastWill: {
    topic: 'myProject/production/clientDisconnected',
    payload: { clientName: 'myClient' },
  },
});