@azure/web-pubsub-express 1.0.6-alpha.20241122.1 → 1.0.6-alpha.20241126.2

package/dist/commonjs/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.47.11"
+      "packageVersion": "7.48.0"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure/web-pubsub-express",
-  "version": "1.0.6-alpha.20241122.1",
+  "version": "1.0.6-alpha.20241126.2",
   "description": "Azure Web PubSub CloudEvents handlers",
   "sdk-type": "client",
   "scripts": {

package/dist/web-pubsub-express.d.ts

@@ -1,801 +0,0 @@
-import type express from 'express-serve-static-core';
-
-/**
- * The client certificate.
- */
-export declare interface Certificate {
-    /**
-     * The thumbprint of the certificate.
-     */
-    thumbprint: string;
-}
-
-/**
- * Request for the connected event.
- */
-export declare interface ConnectedRequest {
-    /**
-     * The context of current CloudEvents request.
-     */
-    context: ConnectionContext;
-}
-
-/**
- * Response of a failed connect event.
- */
-export declare interface ConnectErrorResponse {
-    /**
-     * The error code.
-     */
-    code: 400 | 401 | 500;
-    /**
-     * The error detail.
-     */
-    detail?: string;
-}
-
-/**
- * The connection context representing the client WebSocket connection.
- */
-export declare interface ConnectionContext {
-    /**
-     * The unique identifier generated by the service of the network connection.
-     */
-    signature: string;
-    /**
-     * The hub the connection belongs to.
-     */
-    hub: string;
-    /**
-     * The Id of the connection.
-     */
-    connectionId: string;
-    /**
-     * The event name of this CloudEvents request.
-     */
-    eventName: string;
-    /**
-     * The origin this CloudEvents request comes from.
-     */
-    origin: string;
-    /**
-     * The user id of the connection.
-     */
-    userId?: string;
-    /**
-     * The subprotocol of this connection.
-     */
-    subprotocol?: string;
-    /**
-     * Get the additional states for the connection, such states are perserved throughout the lifetime of the connection.
-     */
-    states: Record<string, any>;
-    /**
-     * The type of client protocol.
-     */
-    clientProtocol: WebPubSubClientProtocol;
-    /**
-     * The MQTT properties that the client WebSocket connection has when it connects (For MQTT connection only).
-     */
-    mqtt?: MqttConnectionContextProperties;
-}
-
-/**
- * Request for the connect event.
- */
-export declare interface ConnectRequest {
-    /**
-     * The context of current CloudEvents request.
-     */
-    context: ConnectionContext;
-    /**
-     * The claims that the client WebSocket connection has when it connects.
-     */
-    claims?: Record<string, string[]>;
-    /**
-     * The query that the client WebSocket connection has when it connects.
-     * @deprecated Please use queries instead.
-     */
-    query?: Record<string, string[]>;
-    /**
-     * The queries that the client WebSocket connection has when it connects.
-     */
-    queries?: Record<string, string[]>;
-    /**
-     * The headers that the client WebSocket connection has when it connects.
-     */
-    headers?: Record<string, string[]>;
-    /**
-     * The subprotocols that the client WebSocket connection uses to do handshake.
-     */
-    subprotocols?: string[];
-    /**
-     * The client certificate info that the client WebSocket connection uses to connect.
-     */
-    clientCertificates?: Certificate[];
-}
-
-/**
- * Response of the connect event.
- */
-export declare interface ConnectResponse {
-    /**
-     * Set the groups the connection would like to join.
-     */
-    groups?: string[];
-    /**
-     * Set the roles the connection belongs to.
-     */
-    roles?: string[];
-    /**
-     * Set the userId for the connection.
-     */
-    userId?: string;
-    /**
-     * Set the subprotocol for the connection to complete WebSocket handshake.
-     */
-    subprotocol?: string;
-}
-
-/**
- * The handler to set connect event response
- */
-export declare interface ConnectResponseHandler {
-    /**
-     * Set the state of the connection
-     * @param name - The name of the state
-     * @param value - The value of the state
-     */
-    setState(name: string, value: unknown): void;
-    /**
-     * Return success response to the service.
-     * @param response - The response for the connect event.
-     */
-    success(response?: ConnectResponse | MqttConnectResponse): void;
-    /**
-     * Return failed response and the service will reject the client WebSocket connection.
-     * @param code - Code can be 400 user error, 401 unauthorized and 500 server error.
-     * @param detail - The detail of the error.
-     */
-    fail(code: 400 | 401 | 500, detail?: string): void;
-    /**
-     * Return failed response with MQTT response properties and the service will reject the client WebSocket connection.
-     * @param response - The response for the connect event which contains either default WebPubSub or MQTT response properties.
-     */
-    failWith(response: ConnectErrorResponse | MqttConnectErrorResponse): void;
-}
-
-/**
- * Request for the disconnected event.
- */
-export declare interface DisconnectedRequest {
-    /**
-     * The context of current CloudEvents request.
-     */
-    context: ConnectionContext;
-    /**
-     * The reason that the connection disconnects.
-     */
-    reason?: string;
-}
-
-/**
- * Response of an MQTT connection failure.
- */
-export declare interface MqttConnectErrorResponse {
-    /**
-     * The properties of the MQTT connection failure response.
-     */
-    mqtt: MqttConnectErrorResponseProperties;
-}
-
-/**
- * The properties of an MQTT connection failure response.
- */
-export declare interface MqttConnectErrorResponseProperties {
-    /**
-     * The MQTT connect return code.
-     */
-    code: MqttV311ConnectReturnCode | MqttV500ConnectReasonCode;
-    /**
-     * The reason string for the connection failure.
-     */
-    reason?: string;
-    /**
-     * The user properties in the response.
-     */
-    userProperties?: MqttUserProperty[];
-}
-
-/**
- * The connection context properties representing the MQTT client WebSocket connection.
- */
-export declare interface MqttConnectionContextProperties {
-    /**
-     * The unique identifier generated by the service of the network connection.
-     */
-    physicalConnectionId: string;
-    /**
-     * The unique identifier generated by the service of the MQTT session.
-     */
-    sessionId?: string;
-}
-
-/**
- * The properties of the MQTT CONNECT packet.
- */
-export declare interface MqttConnectProperties {
-    /**
-     * MQTT protocol version.
-     */
-    protocolVersion: number;
-    /**
-     * The username field in the MQTT CONNECT packet.
-     */
-    username?: string;
-    /**
-     * The password field in the MQTT CONNECT packet.
-     */
-    password?: string;
-    /**
-     * The user properties in the MQTT CONNECT packet.
-     */
-    userProperties?: MqttUserProperty[];
-}
-
-/**
- * Request for the MQTT connect event.
- */
-export declare interface MqttConnectRequest extends ConnectRequest {
-    /**
-     * The MQTT specific properties in the MQTT connect event request.
-     */
-    mqtt: MqttConnectProperties;
-}
-
-/**
- * Success respones of the connect event.
- */
-export declare interface MqttConnectResponse extends ConnectResponse {
-    /**
-     * The MQTT specific properties in a successful MQTT connection event response.
-     */
-    mqtt?: MqttConnectResponseProperties;
-}
-
-/**
- * The properties of a successful MQTT connection event response
- */
-export declare interface MqttConnectResponseProperties {
-    /**
-     * Additional diagnostic or other information provided by upstream server
-     * Now only MQTT 5.0 supports user properties
-     */
-    userProperties?: MqttUserProperty[];
-}
-
-/**
- * The properties of an MQTT disconnected event.
- */
-export declare interface MqttDisconnectedProperties {
-    /**
-     * The MQTT disconnect packet.
-     */
-    disconnectPacket: MqttDisconnectPacket;
-    /**
-     * Whether the disconnection is initiated by the client.
-     */
-    initiatedByClient: boolean;
-}
-
-/**
- * Request for the disconnected event.
- */
-export declare interface MqttDisconnectedRequest extends DisconnectedRequest {
-    /**
-     * The MQTT specific properties in the MQTT disconnected event request.
-     */
-    mqtt: MqttDisconnectedProperties;
-}
-
-/**
- * The properties of the MQTT DISCONNECT packet.
- */
-export declare interface MqttDisconnectPacket {
-    /**
-     * The MQTT disconnect return code.
-     */
-    code: MqttDisconnectReasonCode;
-    /**
-     * The user properties in the MQTT disconnect packet.
-     */
-    userProperties?: MqttUserProperty[];
-}
-
-/**
- * MQTT 5.0 Disconnect Reason Codes.
- */
-export declare enum MqttDisconnectReasonCode {
-    /**
-     * 0x00 - Normal disconnection
-     * Sent by: Client or Server
-     * Description: Close the connection normally. Do not send the Will Message.
-     */
-    NormalDisconnection = 0,
-    /**
-     * 0x04 - Disconnect with Will Message
-     * Sent by: Client
-     * Description: The Client wishes to disconnect but requires that the Server also publishes its Will Message.
-     */
-    DisconnectWithWillMessage = 4,
-    /**
-     * 0x80 - Unspecified error
-     * Sent by: Client or Server
-     * Description: The Connection is closed but the sender either does not wish to reveal the reason, or none of the other Reason Codes apply.
-     */
-    UnspecifiedError = 128,
-    /**
-     * 0x81 - Malformed Packet
-     * Sent by: Client or Server
-     * Description: The received packet does not conform to this specification.
-     */
-    MalformedPacket = 129,
-    /**
-     * 0x82 - Protocol Error
-     * Sent by: Client or Server
-     * Description: An unexpected or out of order packet was received.
-     */
-    ProtocolError = 130,
-    /**
-     * 0x83 - Implementation specific error
-     * Sent by: Client or Server
-     * Description: The packet received is valid but cannot be processed by this implementation.
-     */
-    ImplementationSpecificError = 131,
-    /**
-     * 0x87 - Not authorized
-     * Sent by: Server
-     * Description: The request is not authorized.
-     */
-    NotAuthorized = 135,
-    /**
-     * 0x89 - Server busy
-     * Sent by: Server
-     * Description: The Server is busy and cannot continue processing requests from this Client.
-     */
-    ServerBusy = 137,
-    /**
-     * 0x8B - Server shutting down
-     * Sent by: Server
-     * Description: The Server is shutting down.
-     */
-    ServerShuttingDown = 139,
-    /**
-     * 0x8D - Keep Alive timeout
-     * Sent by: Server
-     * Description: The Connection is closed because no packet has been received for 1.5 times the Keepalive time.
-     */
-    KeepAliveTimeout = 141,
-    /**
-     * 0x8E - Session taken over
-     * Sent by: Server
-     * Description: Another Connection using the same ClientID has connected causing this Connection to be closed.
-     */
-    SessionTakenOver = 142,
-    /**
-     * 0x8F - Topic Filter invalid
-     * Sent by: Server
-     * Description: The Topic Filter is correctly formed, but is not accepted by this Server.
-     */
-    TopicFilterInvalid = 143,
-    /**
-     * 0x90 - Topic Name invalid
-     * Sent by: Client or Server
-     * Description: The Topic Name is correctly formed, but is not accepted by this Client or Server.
-     */
-    TopicNameInvalid = 144,
-    /**
-     * 0x93 - Receive Maximum exceeded
-     * Sent by: Client or Server
-     * Description: The Client or Server has received more than Receive Maximum publication for which it has not sent PUBACK or PUBCOMP.
-     */
-    ReceiveMaximumExceeded = 147,
-    /**
-     * 0x94 - Topic Alias invalid
-     * Sent by: Client or Server
-     * Description: The Client or Server has received a PUBLISH packet containing a Topic Alias which is greater than the Maximum Topic Alias it sent in the CONNECT or CONNACK packet.
-     */
-    TopicAliasInvalid = 148,
-    /**
-     * 0x95 - Packet too large
-     * Sent by: Client or Server
-     * Description: The packet size is greater than Maximum Packet Size for this Client or Server.
-     */
-    PacketTooLarge = 149,
-    /**
-     * 0x96 - Message rate too high
-     * Sent by: Client or Server
-     * Description: The received data rate is too high.
-     */
-    MessageRateTooHigh = 150,
-    /**
-     * 0x97 - Quota exceeded
-     * Sent by: Client or Server
-     * Description: An implementation or administrative imposed limit has been exceeded.
-     */
-    QuotaExceeded = 151,
-    /**
-     * 0x98 - Administrative action
-     * Sent by: Client or Server
-     * Description: The Connection is closed due to an administrative action.
-     */
-    AdministrativeAction = 152,
-    /**
-     * 0x99 - Payload format invalid
-     * Sent by: Client or Server
-     * Description: The payload format does not match the one specified by the Payload Format Indicator.
-     */
-    PayloadFormatInvalid = 153,
-    /**
-     * 0x9A - Retain not supported
-     * Sent by: Server
-     * Description: The Server does not support retained messages.
-     */
-    RetainNotSupported = 154,
-    /**
-     * 0x9B - QoS not supported
-     * Sent by: Server
-     * Description: The Client specified a QoS greater than the QoS specified in a Maximum QoS in the CONNACK.
-     */
-    QosNotSupported = 155,
-    /**
-     * 0x9C - Use another server
-     * Sent by: Server
-     * Description: The Client should temporarily change its Server.
-     */
-    UseAnotherServer = 156,
-    /**
-     * 0x9D - Server moved
-     * Sent by: Server
-     * Description: The Server is moved and the Client should permanently change its server location.
-     */
-    ServerMoved = 157,
-    /**
-     * 0x9E - Shared Subscriptions not supported
-     * Sent by: Server
-     * Description: The Server does not support Shared Subscriptions.
-     */
-    SharedSubscriptionsNotSupported = 158,
-    /**
-     * 0x9F - Connection rate exceeded
-     * Sent by: Server
-     * Description: This connection is closed because the connection rate is too high.
-     */
-    ConnectionRateExceeded = 159,
-    /**
-     * 0xA0 - Maximum connect time
-     * Sent by: Server
-     * Description: The maximum connection time authorized for this connection has been exceeded.
-     */
-    MaximumConnectTime = 160,
-    /**
-     * 0xA1 - Subscription Identifiers not supported
-     * Sent by: Server
-     * Description: The Server does not support Subscription Identifiers; the subscription is not accepted.
-     */
-    SubscriptionIdentifiersNotSupported = 161,
-    /**
-     * 0xA2 - Wildcard Subscriptions not supported
-     * Sent by: Server
-     * Description: The Server does not support Wildcard Subscriptions; the subscription is not accepted.
-     */
-    WildcardSubscriptionsNotSupported = 162
-}
-
-/**
- * The properties of a user in MQTT.
- */
-export declare interface MqttUserProperty {
-    /**
-     * The name of the property.
-     */
-    name: string;
-    /**
-     * The value of the property.
-     */
-    value: string;
-}
-
-/**
- * MQTT 3.1.1 Connect Return Codes.
- */
-export declare enum MqttV311ConnectReturnCode {
-    /**
-     * 0x01: Connection refused, unacceptable protocol version
-     * The Server does not support the level of the MQTT protocol requested by the Client.
-     */
-    UnacceptableProtocolVersion = 1,
-    /**
-     * 0x02: Connection refused, identifier rejected
-     * The Client identifier is correct UTF-8 but not allowed by the Server.
-     */
-    IdentifierRejected = 2,
-    /**
-     * 0x03: Connection refused, server unavailable
-     * The Network Connection has been made but the MQTT service is unavailable.
-     */
-    ServerUnavailable = 3,
-    /**
-     * 0x04: Connection refused, bad user name or password
-     * The data in the user name or password is malformed.
-     */
-    BadUsernameOrPassword = 4,
-    /**
-     * 0x05: Connection refused, not authorized
-     * The Client is not authorized to connect.
-     */
-    NotAuthorized = 5
-}
-
-/**
- * MQTT Connect Reason Codes
- * These codes represent the reasons for the outcome of an MQTT CONNECT packet as per MQTT 5.0 specification.
- */
-export declare enum MqttV500ConnectReasonCode {
-    /**
-     * 0x80 - Unspecified error
-     * Description: The Server does not wish to reveal the reason for the failure, or none of the other Reason Codes apply.
-     */
-    UnspecifiedError = 128,
-    /**
-     * 0x81 - Malformed Packet
-     * Description: Data within the CONNECT packet could not be correctly parsed.
-     */
-    MalformedPacket = 129,
-    /**
-     * 0x82 - Protocol Error
-     * Description: Data in the CONNECT packet does not conform to this specification.
-     */
-    ProtocolError = 130,
-    /**
-     * 0x83 - Implementation specific error
-     * Description: The CONNECT is valid but is not accepted by this Server.
-     */
-    ImplementationSpecificError = 131,
-    /**
-     * 0x84 - Unsupported Protocol Version
-     * Description: The Server does not support the version of the MQTT protocol requested by the Client.
-     */
-    UnsupportedProtocolVersion = 132,
-    /**
-     * 0x85 - Client Identifier not valid
-     * Description: The Client Identifier is a valid string but is not allowed by the Server.
-     */
-    ClientIdentifierNotValid = 133,
-    /**
-     * 0x86 - Bad User Name or Password
-     * Description: The Server does not accept the User Name or Password specified by the Client.
-     */
-    BadUserNameOrPassword = 134,
-    /**
-     * 0x87 - Not authorized
-     * Description: The Client is not authorized to connect.
-     */
-    NotAuthorized = 135,
-    /**
-     * 0x88 - Server unavailable
-     * Description: The MQTT Server is not available.
-     */
-    ServerUnavailable = 136,
-    /**
-     * 0x89 - Server busy
-     * Description: The Server is busy. Try again later.
-     */
-    ServerBusy = 137,
-    /**
-     * 0x8A - Banned
-     * Description: This Client has been banned by administrative action. Contact the server administrator.
-     */
-    Banned = 138,
-    /**
-     * 0x8C - Bad authentication method
-     * Description: The authentication method is not supported or does not match the authentication method currently in use.
-     */
-    BadAuthenticationMethod = 140,
-    /**
-     * 0x90 - Topic Name invalid
-     * Description: The Will Topic Name is not malformed, but is not accepted by this Server.
-     */
-    TopicNameInvalid = 144,
-    /**
-     * 0x95 - Packet too large
-     * Description: The CONNECT packet exceeded the maximum permissible size.
-     */
-    PacketTooLarge = 149,
-    /**
-     * 0x97 - Quota exceeded
-     * Description: An implementation or administrative imposed limit has been exceeded.
-     */
-    QuotaExceeded = 151,
-    /**
-     * 0x99 - Payload format invalid
-     * Description: The Will Payload does not match the specified Payload Format Indicator.
-     */
-    PayloadFormatInvalid = 153,
-    /**
-     * 0x9A - Retain not supported
-     * Description: The Server does not support retained messages, and Will Retain was set to 1.
-     */
-    RetainNotSupported = 154,
-    /**
-     * 0x9B - QoS not supported
-     * Description: The Server does not support the QoS set in Will QoS.
-     */
-    QosNotSupported = 155,
-    /**
-     * 0x9C - Use another server
-     * Description: The Client should temporarily use another server.
-     */
-    UseAnotherServer = 156,
-    /**
-     * 0x9D - Server moved
-     * Description: The Client should permanently use another server.
-     */
-    ServerMoved = 157,
-    /**
-     * 0x9F - Connection rate exceeded
-     * Description: The connection rate limit has been exceeded.
-     */
-    ConnectionRateExceeded = 159
-}
-
-/**
- * Request for the user event.
- */
-export declare type UserEventRequest = {
-    /**
-     * The context of current CloudEvents request.
-     */
-    context: ConnectionContext;
-    /**
-     * The content data.
-     */
-    data: string;
-    /**
-     * The type of the data.
-     */
-    dataType: "text";
-} | {
-    /**
-     * The context of current CloudEvents request.
-     */
-    context: ConnectionContext;
-    /**
-     * The content data, when data type is `json`, the data is the result of JSON.parse, so the type of the data depends on user scenarios
-     */
-    data: unknown;
-    /**
-     * The type of the data.
-     */
-    dataType: "json";
-} | {
-    /**
-     * The context of current CloudEvents request.
-     */
-    context: ConnectionContext;
-    /**
-     * The content data.
-     */
-    data: ArrayBuffer;
-    /**
-     * The type of the data.
-     */
-    dataType: "binary";
-};
-
-/**
- * The handler to set user event response
- */
-export declare interface UserEventResponseHandler {
-    /**
-     * Set the state of the connection
-     * @param name - The name of the state
-     * @param value - The value of the state
-     */
-    setState(name: string, value: unknown): void;
-    /**
-     * Return success response with data to be delivered to the client WebSocket connection.
-     * @param data - The payload data to be returned to the client. Stringify the message if it is a JSON object.
-     * @param dataType - The type of the payload data.
-     */
-    success(data?: string | ArrayBuffer, dataType?: "binary" | "text" | "json"): void;
-    /**
-     * Return failed response and the service will close the client WebSocket connection.
-     * @param code - Code can be 400 user error, 401 unauthorized and 500 server error.
-     * @param detail - The detail of the error.
-     */
-    fail(code: 400 | 401 | 500, detail?: string): void;
-}
-
-/**
- * The protocol of Web PubSub Client.
- */
-export declare type WebPubSubClientProtocol = "default" | "mqtt";
-
-/**
- * The handler to handle incoming CloudEvents messages
- */
-export declare class WebPubSubEventHandler {
-    private hub;
-    /**
-     * The path this CloudEvents handler listens to
-     */
-    readonly path: string;
-    private _cloudEventsHandler;
-    /**
-     * Creates an instance of a WebPubSubEventHandler for handling incoming CloudEvents messages.
-     *
-     * Example usage:
-     * ```ts
-     * import express from "express";
-     * import { WebPubSubEventHandler } from "@azure/web-pubsub-express";
-     * const endpoint = "https://xxxx.webpubsubdev.azure.com"
-     * const handler = new WebPubSubEventHandler('chat', {
-     *   handleConnect: (req, res) => {
-     *     console.log(JSON.stringify(req));
-     *     return {};
-     *   },
-     *   onConnected: req => {
-     *     console.log(JSON.stringify(req));
-     *   },
-     *   handleUserEvent: (req, res) => {
-     *     console.log(JSON.stringify(req));
-     *     res.success("Hey " + req.data, req.dataType);
-     *    };
-     *   allowedEndpoints: [ endpoint ]
-     *  },
-     * });
-     * ```
-     *
-     * @param hub - The name of the hub to listen to
-     * @param options - Options to configure the event handler
-     */
-    constructor(hub: string, options?: WebPubSubEventHandlerOptions);
-    /**
-     * Get the middleware to process the CloudEvents requests
-     */
-    getMiddleware(): express.RequestHandler;
-}
-
-/**
- * The options for the CloudEvents handler.
- */
-export declare interface WebPubSubEventHandlerOptions {
-    /**
-     * Custom serving path for the path of the CloudEvents handler.
-     */
-    path?: string;
-    /**
-     * Handle 'connect' event, the service waits for the response to proceed.
-     */
-    handleConnect?: (connectRequest: ConnectRequest, connectResponse: ConnectResponseHandler) => void;
-    /**
-     * Handle user events, the service waits for the response to proceed.
-     */
-    handleUserEvent?: (userEventRequest: UserEventRequest, userEventResponse: UserEventResponseHandler) => void;
-    /**
-     * Event trigger for "connected" unblocking event. This is an unblocking event and the service does not wait for the response.
-     */
-    onConnected?: (connectedRequest: ConnectedRequest) => void;
-    /**
-     *
-     * Event triggers for "disconnected" unblocking event. This is an unblocking event and the service does not wait for the response.
-     */
-    onDisconnected?: (disconnectedRequest: DisconnectedRequest) => void;
-    /**
-     * If not specified, by default allow all the endpoints, otherwise only allow specified endpoints
-     */
-    allowedEndpoints?: string[];
-}
-
-export { }