diff --git a/src/connection.js b/src/connection.js index cadd3a4..9c06946 100644 --- a/src/connection.js +++ b/src/connection.js @@ -28,6 +28,134 @@ import Bosh from './bosh.js'; import WorkerWebsocket from './worker-websocket.js'; import Websocket from './websocket.js'; +/** + * @typedef {import("./sasl.js").default} SASLMechanism + * @typedef {import("./request.js").default} Request + * + * @typedef {Object} ConnectionOptions + * @property {Cookies} [cookies] + * Allows you to pass in cookies that will be included in HTTP requests. + * Relevant to both the BOSH and Websocket transports. + * + * The passed in value must be a map of cookie names and string values. + * + * > { "myCookie": { + * > "value": "1234", + * > "domain": ".example.org", + * > "path": "/", + * > "expires": expirationDate + * > } + * > } + * + * Note that cookies can't be set in this way for domains other than the one + * that's hosting Strophe (i.e. cross-domain). + * Those cookies need to be set under those domains, for example they can be + * set server-side by making a XHR call to that domain to ask it to set any + * necessary cookies. + * @property {SASLMechanism[]} [mechanisms] + * Allows you to specify the SASL authentication mechanisms that this + * instance of Connection (and therefore your XMPP client) will support. + * + * The value must be an array of objects with {@link SASLMechanism} + * prototypes. + * + * If nothing is specified, then the following mechanisms (and their + * priorities) are registered: + * + * Mechanism Priority + * ------------------------ + * SCRAM-SHA-512 72 + * SCRAM-SHA-384 71 + * SCRAM-SHA-256 70 + * SCRAM-SHA-1 60 + * PLAIN 50 + * OAUTHBEARER 40 + * X-OAUTH2 30 + * ANONYMOUS 20 + * EXTERNAL 10 + * + * @property {boolean} [explicitResourceBinding] + * If `explicitResourceBinding` is set to `true`, then the XMPP client + * needs to explicitly call {@link Connection.bind} once the XMPP + * server has advertised the `urn:ietf:propertys:xml:ns:xmpp-bind` feature. + * + * Making this step explicit allows client authors to first finish other + * stream related tasks, such as setting up an XEP-0198 Stream Management + * session, before binding the JID resource for this session. + * + * @property {'ws'|'wss'} [protocol] + * _Note: This option is only relevant to Websocket connections, and not BOSH_ + * + * If you want to connect to the current host with a WebSocket connection you + * can tell Strophe to use WebSockets through the "protocol" option. + * Valid values are `ws` for WebSocket and `wss` for Secure WebSocket. + * So to connect to "wss://CURRENT_HOSTNAME/xmpp-websocket" you would call + * + * const conn = new Strophe.Connection( + * "/xmpp-websocket/", + * {protocol: "wss"} + * ); + * + * Note that relative URLs _NOT_ starting with a "/" will also include the path + * of the current site. + * + * Also because downgrading security is not permitted by browsers, when using + * relative URLs both BOSH and WebSocket connections will use their secure + * variants if the current connection to the site is also secure (https). + * + * @property {string} [worker] + * _Note: This option is only relevant to Websocket connections, and not BOSH_ + * + * Set this option to URL from where the shared worker script should be loaded. + * + * To run the websocket connection inside a shared worker. + * This allows you to share a single websocket-based connection between + * multiple Connection instances, for example one per browser tab. + * + * The script to use is the one in `src/shared-connection-worker.js`. + * + * @property {boolean} [sync] + * Used to control whether BOSH HTTP requests will be made synchronously or not. + * The default behaviour is asynchronous. If you want to make requests + * synchronous, make "sync" evaluate to true. + * + * > const conn = new Strophe.Connection("/http-bind/", {sync: true}); + * + * You can also toggle this on an already established connection. + * + * > conn.options.sync = true; + * + * @property {string[]} [customHeaders] + * Used to provide custom HTTP headers to be included in the BOSH HTTP requests. + * + * @property {boolean} [keepalive] + * Used to instruct Strophe to maintain the current BOSH session across + * interruptions such as webpage reloads. + * + * It will do this by caching the sessions tokens in sessionStorage, and when + * "restore" is called it will check whether there are cached tokens with + * which it can resume an existing session. + * + * @property {boolean} [withCredentials] + * Used to indicate wether cookies should be included in HTTP requests (by default + * they're not). + * Set this value to `true` if you are connecting to a BOSH service + * and for some reason need to send cookies to it. + * In order for this to work cross-domain, the server must also enable + * credentials by setting the `Access-Control-Allow-Credentials` response header + * to "true". For most usecases however this setting should be false (which + * is the default). + * Additionally, when using `Access-Control-Allow-Credentials`, the + * `Access-Control-Allow-Origin` header can't be set to the wildcard "*", but + * instead must be restricted to actual domains. + * + * @property {string} [contentType] + * Used to change the default Content-Type, which is "text/xml; charset=utf-8". + * Can be useful to reduce the amount of CORS preflight requests that are sent + * to the server. + */ + + /** * _Private_ variable Used to store plugin names that need * initialization during Connection construction. @@ -35,11 +163,6 @@ import Websocket from './websocket.js'; */ const connectionPlugins = {}; -/** - * @typedef {import("./sasl.js").default} SASLMechanism - * @typedef {import("./request.js").default} Request - */ - /** * **XMPP Connection manager** * @@ -73,129 +196,6 @@ class Connection { * @typedef {Cookie|Object.} Cookies */ - /** - * @typedef {Object} ConnectionOptions - * @property {Cookies} [cookies] - * Allows you to pass in cookies that will be included in HTTP requests. - * Relevant to both the BOSH and Websocket transports. - * - * The passed in value must be a map of cookie names and string values. - * - * > { "myCookie": { - * > "value": "1234", - * > "domain": ".example.org", - * > "path": "/", - * > "expires": expirationDate - * > } - * > } - * - * Note that cookies can't be set in this way for domains other than the one - * that's hosting Strophe (i.e. cross-domain). - * Those cookies need to be set under those domains, for example they can be - * set server-side by making a XHR call to that domain to ask it to set any - * necessary cookies. - * @property {SASLMechanism[]} [mechanisms] - * Allows you to specify the SASL authentication mechanisms that this - * instance of Connection (and therefore your XMPP client) will support. - * - * The value must be an array of objects with {@link SASLMechanism} - * prototypes. - * - * If nothing is specified, then the following mechanisms (and their - * priorities) are registered: - * - * Mechanism Priority - * ------------------------ - * SCRAM-SHA-512 72 - * SCRAM-SHA-384 71 - * SCRAM-SHA-256 70 - * SCRAM-SHA-1 60 - * PLAIN 50 - * OAUTHBEARER 40 - * X-OAUTH2 30 - * ANONYMOUS 20 - * EXTERNAL 10 - * - * @property {boolean} [explicitResourceBinding] - * If `explicitResourceBinding` is set to `true`, then the XMPP client - * needs to explicitly call {@link Connection.bind} once the XMPP - * server has advertised the `urn:ietf:propertys:xml:ns:xmpp-bind` feature. - * - * Making this step explicit allows client authors to first finish other - * stream related tasks, such as setting up an XEP-0198 Stream Management - * session, before binding the JID resource for this session. - * - * @property {'ws'|'wss'} [protocol] - * _Note: This option is only relevant to Websocket connections, and not BOSH_ - * - * If you want to connect to the current host with a WebSocket connection you - * can tell Strophe to use WebSockets through the "protocol" option. - * Valid values are `ws` for WebSocket and `wss` for Secure WebSocket. - * So to connect to "wss://CURRENT_HOSTNAME/xmpp-websocket" you would call - * - * const conn = new Strophe.Connection( - * "/xmpp-websocket/", - * {protocol: "wss"} - * ); - * - * Note that relative URLs _NOT_ starting with a "/" will also include the path - * of the current site. - * - * Also because downgrading security is not permitted by browsers, when using - * relative URLs both BOSH and WebSocket connections will use their secure - * variants if the current connection to the site is also secure (https). - * - * @property {string} [worker] - * _Note: This option is only relevant to Websocket connections, and not BOSH_ - * - * Set this option to URL from where the shared worker script should be loaded. - * - * To run the websocket connection inside a shared worker. - * This allows you to share a single websocket-based connection between - * multiple Connection instances, for example one per browser tab. - * - * The script to use is the one in `src/shared-connection-worker.js`. - * - * @property {boolean} [sync] - * Used to control whether BOSH HTTP requests will be made synchronously or not. - * The default behaviour is asynchronous. If you want to make requests - * synchronous, make "sync" evaluate to true. - * - * > const conn = new Strophe.Connection("/http-bind/", {sync: true}); - * - * You can also toggle this on an already established connection. - * - * > conn.options.sync = true; - * - * @property {string[]} [customHeaders] - * Used to provide custom HTTP headers to be included in the BOSH HTTP requests. - * - * @property {boolean} [keepalive] - * Used to instruct Strophe to maintain the current BOSH session across - * interruptions such as webpage reloads. - * - * It will do this by caching the sessions tokens in sessionStorage, and when - * "restore" is called it will check whether there are cached tokens with - * which it can resume an existing session. - * - * @property {boolean} [withCredentials] - * Used to indicate wether cookies should be included in HTTP requests (by default - * they're not). - * Set this value to `true` if you are connecting to a BOSH service - * and for some reason need to send cookies to it. - * In order for this to work cross-domain, the server must also enable - * credentials by setting the `Access-Control-Allow-Credentials` response header - * to "true". For most usecases however this setting should be false (which - * is the default). - * Additionally, when using `Access-Control-Allow-Credentials`, the - * `Access-Control-Allow-Origin` header can't be set to the wildcard "*", but - * instead must be restricted to actual domains. - * - * @property {string} [contentType] - * Used to change the default Content-Type, which is "text/xml; charset=utf-8". - * Can be useful to reduce the amount of CORS preflight requests that are sent - * to the server. - */ /** * Create and initialize a {@link Connection} object. diff --git a/src/index.js b/src/index.js index 518d90a..66e38bf 100644 --- a/src/index.js +++ b/src/index.js @@ -184,5 +184,6 @@ globalThis.$iq = $iq; globalThis.$msg = $msg; globalThis.$pres = $pres; globalThis.Strophe = Strophe; +globalThis.toStanza = toStanza; export { Builder, $build, $iq, $msg, $pres, Strophe, Stanza, stx, toStanza, Request }; diff --git a/src/stanza.js b/src/stanza.js index 4f4fecf..34bcaf9 100644 --- a/src/stanza.js +++ b/src/stanza.js @@ -16,7 +16,6 @@ export function toStanza(string, throwErrorIfInvalidNS) { } const node = doc.firstElementChild; - if ( ['message', 'iq', 'presence'].includes(node.nodeName.toLowerCase()) && node.namespaceURI !== 'jabber:client' && @@ -33,13 +32,12 @@ export function toStanza(string, throwErrorIfInvalidNS) { } /** - * A Stanza represents a XML element used in XMPP (commonly referred to as - * stanzas). + * A Stanza represents a XML element used in XMPP (commonly referred to as stanzas). */ export class Stanza { /** - * @param { string[] } strings - * @param { any[] } values + * @param {string[]} strings + * @param {any[]} values */ constructor(strings, values) { this.strings = strings; @@ -47,7 +45,7 @@ export class Stanza { } /** - * @return { string } + * @return {string} */ toString() { this.string = @@ -61,7 +59,7 @@ export class Stanza { } /** - * @return { Element } + * @return {Element} */ tree() { this.node = this.node ?? toStanza(this.toString(), true); @@ -73,8 +71,8 @@ export class Stanza { * Tagged template literal function which generates {@link Stanza } objects * @example stx`${show}` * - * @param { string[] } strings - * @param { ...any } values + * @param {string[]} strings + * @param {...any} values */ export function stx(strings, ...values) { return new Stanza(strings, values); diff --git a/src/types/connection.d.ts b/src/types/connection.d.ts index 7aa12cc..5a76f84 100644 --- a/src/types/connection.d.ts +++ b/src/types/connection.d.ts @@ -1,10 +1,145 @@ export default Connection; export type SASLMechanism = import("./sasl.js").default; export type Request = import("./request.js").default; -/** - * @typedef {import("./sasl.js").default} SASLMechanism - * @typedef {import("./request.js").default} Request - */ +export type ConnectionOptions = { + /** + * Allows you to pass in cookies that will be included in HTTP requests. + * Relevant to both the BOSH and Websocket transports. + * + * The passed in value must be a map of cookie names and string values. + * + * > { "myCookie": { + * > "value": "1234", + * > "domain": ".example.org", + * > "path": "/", + * > "expires": expirationDate + * > } + * > } + * + * Note that cookies can't be set in this way for domains other than the one + * that's hosting Strophe (i.e. cross-domain). + * Those cookies need to be set under those domains, for example they can be + * set server-side by making a XHR call to that domain to ask it to set any + * necessary cookies. + */ + cookies?: { + [x: string]: string; + } | { + [x: string]: { + [x: string]: string; + }; + }; + /** + * Allows you to specify the SASL authentication mechanisms that this + * instance of Connection (and therefore your XMPP client) will support. + * + * The value must be an array of objects with {@link SASLMechanism}prototypes. + * + * If nothing is specified, then the following mechanisms (and their + * priorities) are registered: + * + * Mechanism Priority + * ------------------------ + * SCRAM-SHA-512 72 + * SCRAM-SHA-384 71 + * SCRAM-SHA-256 70 + * SCRAM-SHA-1 60 + * PLAIN 50 + * OAUTHBEARER 40 + * X-OAUTH2 30 + * ANONYMOUS 20 + * EXTERNAL 10 + */ + mechanisms?: SASLMechanism[]; + /** + * If `explicitResourceBinding` is set to `true`, then the XMPP client + * needs to explicitly call {@link Connection.bind} once the XMPP + * server has advertised the `urn:ietf:propertys:xml:ns:xmpp-bind` feature. + * + * Making this step explicit allows client authors to first finish other + * stream related tasks, such as setting up an XEP-0198 Stream Management + * session, before binding the JID resource for this session. + */ + explicitResourceBinding?: boolean; + /** + * _Note: This option is only relevant to Websocket connections, and not BOSH_ + * + * If you want to connect to the current host with a WebSocket connection you + * can tell Strophe to use WebSockets through the "protocol" option. + * Valid values are `ws` for WebSocket and `wss` for Secure WebSocket. + * So to connect to "wss://CURRENT_HOSTNAME/xmpp-websocket" you would call + * + * const conn = new Strophe.Connection( + * "/xmpp-websocket/", + * {protocol: "wss"} + * ); + * + * Note that relative URLs _NOT_ starting with a "/" will also include the path + * of the current site. + * + * Also because downgrading security is not permitted by browsers, when using + * relative URLs both BOSH and WebSocket connections will use their secure + * variants if the current connection to the site is also secure (https). + */ + protocol?: "ws" | "wss"; + /** + * _Note: This option is only relevant to Websocket connections, and not BOSH_ + * + * Set this option to URL from where the shared worker script should be loaded. + * + * To run the websocket connection inside a shared worker. + * This allows you to share a single websocket-based connection between + * multiple Connection instances, for example one per browser tab. + * + * The script to use is the one in `src/shared-connection-worker.js`. + */ + worker?: string; + /** + * Used to control whether BOSH HTTP requests will be made synchronously or not. + * The default behaviour is asynchronous. If you want to make requests + * synchronous, make "sync" evaluate to true. + * + * > const conn = new Strophe.Connection("/http-bind/", {sync: true}); + * + * You can also toggle this on an already established connection. + * + * > conn.options.sync = true; + */ + sync?: boolean; + /** + * Used to provide custom HTTP headers to be included in the BOSH HTTP requests. + */ + customHeaders?: string[]; + /** + * Used to instruct Strophe to maintain the current BOSH session across + * interruptions such as webpage reloads. + * + * It will do this by caching the sessions tokens in sessionStorage, and when + * "restore" is called it will check whether there are cached tokens with + * which it can resume an existing session. + */ + keepalive?: boolean; + /** + * Used to indicate wether cookies should be included in HTTP requests (by default + * they're not). + * Set this value to `true` if you are connecting to a BOSH service + * and for some reason need to send cookies to it. + * In order for this to work cross-domain, the server must also enable + * credentials by setting the `Access-Control-Allow-Credentials` response header + * to "true". For most usecases however this setting should be false (which + * is the default). + * Additionally, when using `Access-Control-Allow-Credentials`, the + * `Access-Control-Allow-Origin` header can't be set to the wildcard "*", but + * instead must be restricted to actual domains. + */ + withCredentials?: boolean; + /** + * Used to change the default Content-Type, which is "text/xml; charset=utf-8". + * Can be useful to reduce the amount of CORS preflight requests that are sent + * to the server. + */ + contentType?: string; +}; /** * **XMPP Connection manager** * @@ -43,129 +178,6 @@ declare class Connection { * @typedef {Object.} Cookie * @typedef {Cookie|Object.} Cookies */ - /** - * @typedef {Object} ConnectionOptions - * @property {Cookies} [cookies] - * Allows you to pass in cookies that will be included in HTTP requests. - * Relevant to both the BOSH and Websocket transports. - * - * The passed in value must be a map of cookie names and string values. - * - * > { "myCookie": { - * > "value": "1234", - * > "domain": ".example.org", - * > "path": "/", - * > "expires": expirationDate - * > } - * > } - * - * Note that cookies can't be set in this way for domains other than the one - * that's hosting Strophe (i.e. cross-domain). - * Those cookies need to be set under those domains, for example they can be - * set server-side by making a XHR call to that domain to ask it to set any - * necessary cookies. - * @property {SASLMechanism[]} [mechanisms] - * Allows you to specify the SASL authentication mechanisms that this - * instance of Connection (and therefore your XMPP client) will support. - * - * The value must be an array of objects with {@link SASLMechanism} - * prototypes. - * - * If nothing is specified, then the following mechanisms (and their - * priorities) are registered: - * - * Mechanism Priority - * ------------------------ - * SCRAM-SHA-512 72 - * SCRAM-SHA-384 71 - * SCRAM-SHA-256 70 - * SCRAM-SHA-1 60 - * PLAIN 50 - * OAUTHBEARER 40 - * X-OAUTH2 30 - * ANONYMOUS 20 - * EXTERNAL 10 - * - * @property {boolean} [explicitResourceBinding] - * If `explicitResourceBinding` is set to `true`, then the XMPP client - * needs to explicitly call {@link Connection.bind} once the XMPP - * server has advertised the `urn:ietf:propertys:xml:ns:xmpp-bind` feature. - * - * Making this step explicit allows client authors to first finish other - * stream related tasks, such as setting up an XEP-0198 Stream Management - * session, before binding the JID resource for this session. - * - * @property {'ws'|'wss'} [protocol] - * _Note: This option is only relevant to Websocket connections, and not BOSH_ - * - * If you want to connect to the current host with a WebSocket connection you - * can tell Strophe to use WebSockets through the "protocol" option. - * Valid values are `ws` for WebSocket and `wss` for Secure WebSocket. - * So to connect to "wss://CURRENT_HOSTNAME/xmpp-websocket" you would call - * - * const conn = new Strophe.Connection( - * "/xmpp-websocket/", - * {protocol: "wss"} - * ); - * - * Note that relative URLs _NOT_ starting with a "/" will also include the path - * of the current site. - * - * Also because downgrading security is not permitted by browsers, when using - * relative URLs both BOSH and WebSocket connections will use their secure - * variants if the current connection to the site is also secure (https). - * - * @property {string} [worker] - * _Note: This option is only relevant to Websocket connections, and not BOSH_ - * - * Set this option to URL from where the shared worker script should be loaded. - * - * To run the websocket connection inside a shared worker. - * This allows you to share a single websocket-based connection between - * multiple Connection instances, for example one per browser tab. - * - * The script to use is the one in `src/shared-connection-worker.js`. - * - * @property {boolean} [sync] - * Used to control whether BOSH HTTP requests will be made synchronously or not. - * The default behaviour is asynchronous. If you want to make requests - * synchronous, make "sync" evaluate to true. - * - * > const conn = new Strophe.Connection("/http-bind/", {sync: true}); - * - * You can also toggle this on an already established connection. - * - * > conn.options.sync = true; - * - * @property {string[]} [customHeaders] - * Used to provide custom HTTP headers to be included in the BOSH HTTP requests. - * - * @property {boolean} [keepalive] - * Used to instruct Strophe to maintain the current BOSH session across - * interruptions such as webpage reloads. - * - * It will do this by caching the sessions tokens in sessionStorage, and when - * "restore" is called it will check whether there are cached tokens with - * which it can resume an existing session. - * - * @property {boolean} [withCredentials] - * Used to indicate wether cookies should be included in HTTP requests (by default - * they're not). - * Set this value to `true` if you are connecting to a BOSH service - * and for some reason need to send cookies to it. - * In order for this to work cross-domain, the server must also enable - * credentials by setting the `Access-Control-Allow-Credentials` response header - * to "true". For most usecases however this setting should be false (which - * is the default). - * Additionally, when using `Access-Control-Allow-Credentials`, the - * `Access-Control-Allow-Origin` header can't be set to the wildcard "*", but - * instead must be restricted to actual domains. - * - * @property {string} [contentType] - * Used to change the default Content-Type, which is "text/xml; charset=utf-8". - * Can be useful to reduce the amount of CORS preflight requests that are sent - * to the server. - */ /** * Create and initialize a {@link Connection} object. * @@ -182,285 +194,9 @@ declare class Connection { * @param {string} service - The BOSH or WebSocket service URL. * @param {ConnectionOptions} options - A object containing configuration options */ - constructor(service: string, options?: { - /** - * Allows you to pass in cookies that will be included in HTTP requests. - * Relevant to both the BOSH and Websocket transports. - * - * The passed in value must be a map of cookie names and string values. - * - * > { "myCookie": { - * > "value": "1234", - * > "domain": ".example.org", - * > "path": "/", - * > "expires": expirationDate - * > } - * > } - * - * Note that cookies can't be set in this way for domains other than the one - * that's hosting Strophe (i.e. cross-domain). - * Those cookies need to be set under those domains, for example they can be - * set server-side by making a XHR call to that domain to ask it to set any - * necessary cookies. - */ - cookies?: { - [x: string]: string; - } | { - [x: string]: { - [x: string]: string; - }; - }; - /** - * Allows you to specify the SASL authentication mechanisms that this - * instance of Connection (and therefore your XMPP client) will support. - * - * The value must be an array of objects with {@link SASLMechanism}prototypes. - * - * If nothing is specified, then the following mechanisms (and their - * priorities) are registered: - * - * Mechanism Priority - * ------------------------ - * SCRAM-SHA-512 72 - * SCRAM-SHA-384 71 - * SCRAM-SHA-256 70 - * SCRAM-SHA-1 60 - * PLAIN 50 - * OAUTHBEARER 40 - * X-OAUTH2 30 - * ANONYMOUS 20 - * EXTERNAL 10 - */ - mechanisms?: SASLMechanism[]; - /** - * If `explicitResourceBinding` is set to `true`, then the XMPP client - * needs to explicitly call {@link Connection.bind} once the XMPP - * server has advertised the `urn:ietf:propertys:xml:ns:xmpp-bind` feature. - * - * Making this step explicit allows client authors to first finish other - * stream related tasks, such as setting up an XEP-0198 Stream Management - * session, before binding the JID resource for this session. - */ - explicitResourceBinding?: boolean; - /** - * _Note: This option is only relevant to Websocket connections, and not BOSH_ - * - * If you want to connect to the current host with a WebSocket connection you - * can tell Strophe to use WebSockets through the "protocol" option. - * Valid values are `ws` for WebSocket and `wss` for Secure WebSocket. - * So to connect to "wss://CURRENT_HOSTNAME/xmpp-websocket" you would call - * - * const conn = new Strophe.Connection( - * "/xmpp-websocket/", - * {protocol: "wss"} - * ); - * - * Note that relative URLs _NOT_ starting with a "/" will also include the path - * of the current site. - * - * Also because downgrading security is not permitted by browsers, when using - * relative URLs both BOSH and WebSocket connections will use their secure - * variants if the current connection to the site is also secure (https). - */ - protocol?: "ws" | "wss"; - /** - * _Note: This option is only relevant to Websocket connections, and not BOSH_ - * - * Set this option to URL from where the shared worker script should be loaded. - * - * To run the websocket connection inside a shared worker. - * This allows you to share a single websocket-based connection between - * multiple Connection instances, for example one per browser tab. - * - * The script to use is the one in `src/shared-connection-worker.js`. - */ - worker?: string; - /** - * Used to control whether BOSH HTTP requests will be made synchronously or not. - * The default behaviour is asynchronous. If you want to make requests - * synchronous, make "sync" evaluate to true. - * - * > const conn = new Strophe.Connection("/http-bind/", {sync: true}); - * - * You can also toggle this on an already established connection. - * - * > conn.options.sync = true; - */ - sync?: boolean; - /** - * Used to provide custom HTTP headers to be included in the BOSH HTTP requests. - */ - customHeaders?: string[]; - /** - * Used to instruct Strophe to maintain the current BOSH session across - * interruptions such as webpage reloads. - * - * It will do this by caching the sessions tokens in sessionStorage, and when - * "restore" is called it will check whether there are cached tokens with - * which it can resume an existing session. - */ - keepalive?: boolean; - /** - * Used to indicate wether cookies should be included in HTTP requests (by default - * they're not). - * Set this value to `true` if you are connecting to a BOSH service - * and for some reason need to send cookies to it. - * In order for this to work cross-domain, the server must also enable - * credentials by setting the `Access-Control-Allow-Credentials` response header - * to "true". For most usecases however this setting should be false (which - * is the default). - * Additionally, when using `Access-Control-Allow-Credentials`, the - * `Access-Control-Allow-Origin` header can't be set to the wildcard "*", but - * instead must be restricted to actual domains. - */ - withCredentials?: boolean; - /** - * Used to change the default Content-Type, which is "text/xml; charset=utf-8". - * Can be useful to reduce the amount of CORS preflight requests that are sent - * to the server. - */ - contentType?: string; - }); + constructor(service: string, options?: ConnectionOptions); service: string; - options: { - /** - * Allows you to pass in cookies that will be included in HTTP requests. - * Relevant to both the BOSH and Websocket transports. - * - * The passed in value must be a map of cookie names and string values. - * - * > { "myCookie": { - * > "value": "1234", - * > "domain": ".example.org", - * > "path": "/", - * > "expires": expirationDate - * > } - * > } - * - * Note that cookies can't be set in this way for domains other than the one - * that's hosting Strophe (i.e. cross-domain). - * Those cookies need to be set under those domains, for example they can be - * set server-side by making a XHR call to that domain to ask it to set any - * necessary cookies. - */ - cookies?: { - [x: string]: string; - } | { - [x: string]: { - [x: string]: string; - }; - }; - /** - * Allows you to specify the SASL authentication mechanisms that this - * instance of Connection (and therefore your XMPP client) will support. - * - * The value must be an array of objects with {@link SASLMechanism}prototypes. - * - * If nothing is specified, then the following mechanisms (and their - * priorities) are registered: - * - * Mechanism Priority - * ------------------------ - * SCRAM-SHA-512 72 - * SCRAM-SHA-384 71 - * SCRAM-SHA-256 70 - * SCRAM-SHA-1 60 - * PLAIN 50 - * OAUTHBEARER 40 - * X-OAUTH2 30 - * ANONYMOUS 20 - * EXTERNAL 10 - */ - mechanisms?: SASLMechanism[]; - /** - * If `explicitResourceBinding` is set to `true`, then the XMPP client - * needs to explicitly call {@link Connection.bind} once the XMPP - * server has advertised the `urn:ietf:propertys:xml:ns:xmpp-bind` feature. - * - * Making this step explicit allows client authors to first finish other - * stream related tasks, such as setting up an XEP-0198 Stream Management - * session, before binding the JID resource for this session. - */ - explicitResourceBinding?: boolean; - /** - * _Note: This option is only relevant to Websocket connections, and not BOSH_ - * - * If you want to connect to the current host with a WebSocket connection you - * can tell Strophe to use WebSockets through the "protocol" option. - * Valid values are `ws` for WebSocket and `wss` for Secure WebSocket. - * So to connect to "wss://CURRENT_HOSTNAME/xmpp-websocket" you would call - * - * const conn = new Strophe.Connection( - * "/xmpp-websocket/", - * {protocol: "wss"} - * ); - * - * Note that relative URLs _NOT_ starting with a "/" will also include the path - * of the current site. - * - * Also because downgrading security is not permitted by browsers, when using - * relative URLs both BOSH and WebSocket connections will use their secure - * variants if the current connection to the site is also secure (https). - */ - protocol?: "ws" | "wss"; - /** - * _Note: This option is only relevant to Websocket connections, and not BOSH_ - * - * Set this option to URL from where the shared worker script should be loaded. - * - * To run the websocket connection inside a shared worker. - * This allows you to share a single websocket-based connection between - * multiple Connection instances, for example one per browser tab. - * - * The script to use is the one in `src/shared-connection-worker.js`. - */ - worker?: string; - /** - * Used to control whether BOSH HTTP requests will be made synchronously or not. - * The default behaviour is asynchronous. If you want to make requests - * synchronous, make "sync" evaluate to true. - * - * > const conn = new Strophe.Connection("/http-bind/", {sync: true}); - * - * You can also toggle this on an already established connection. - * - * > conn.options.sync = true; - */ - sync?: boolean; - /** - * Used to provide custom HTTP headers to be included in the BOSH HTTP requests. - */ - customHeaders?: string[]; - /** - * Used to instruct Strophe to maintain the current BOSH session across - * interruptions such as webpage reloads. - * - * It will do this by caching the sessions tokens in sessionStorage, and when - * "restore" is called it will check whether there are cached tokens with - * which it can resume an existing session. - */ - keepalive?: boolean; - /** - * Used to indicate wether cookies should be included in HTTP requests (by default - * they're not). - * Set this value to `true` if you are connecting to a BOSH service - * and for some reason need to send cookies to it. - * In order for this to work cross-domain, the server must also enable - * credentials by setting the `Access-Control-Allow-Credentials` response header - * to "true". For most usecases however this setting should be false (which - * is the default). - * Additionally, when using `Access-Control-Allow-Credentials`, the - * `Access-Control-Allow-Origin` header can't be set to the wildcard "*", but - * instead must be restricted to actual domains. - */ - withCredentials?: boolean; - /** - * Used to change the default Content-Type, which is "text/xml; charset=utf-8". - * Can be useful to reduce the amount of CORS preflight requests that are sent - * to the server. - */ - contentType?: string; - }; + options: ConnectionOptions; jid: string; domain: string; features: Element; diff --git a/src/types/index.d.ts b/src/types/index.d.ts index 668ffcf..afd7f9d 100644 --- a/src/types/index.d.ts +++ b/src/types/index.d.ts @@ -159,7 +159,7 @@ export const Strophe: { }): void; xmlGenerator(): Document; xmlTextNode(text: string): Text; - xmlHtmlNode(html: string): XMLDocument; + xmlHtmlNode(text: string): XMLDocument; xmlElement(name: string, attrs?: Array> | { [x: string]: string | number; } | string | number, text?: string | number): Element; diff --git a/src/types/stanza.d.ts b/src/types/stanza.d.ts index 5937470..016c9a1 100644 --- a/src/types/stanza.d.ts +++ b/src/types/stanza.d.ts @@ -8,29 +8,28 @@ export function toStanza(string: string, throwErrorIfInvalidNS?: boolean): Eleme * Tagged template literal function which generates {@link Stanza } objects * @example stx`${show}` * - * @param { string[] } strings - * @param { ...any } values + * @param {string[]} strings + * @param {...any} values */ export function stx(strings: string[], ...values: any[]): Stanza; /** - * A Stanza represents a XML element used in XMPP (commonly referred to as - * stanzas). + * A Stanza represents a XML element used in XMPP (commonly referred to as stanzas). */ export class Stanza { /** - * @param { string[] } strings - * @param { any[] } values + * @param {string[]} strings + * @param {any[]} values */ constructor(strings: string[], values: any[]); strings: string[]; values: any[]; /** - * @return { string } + * @return {string} */ toString(): string; string: any; /** - * @return { Element } + * @return {Element} */ tree(): Element; node: any; diff --git a/src/types/utils.d.ts b/src/types/utils.d.ts index f5424f1..60ab1ea 100644 --- a/src/types/utils.d.ts +++ b/src/types/utils.d.ts @@ -52,10 +52,10 @@ export function xmlGenerator(): Document; export function xmlTextNode(text: string): Text; /** * Creates an XML DOM node. - * @param {string} html - The content of the html node. + * @param {string} text - The contents of the XML element. * @return {XMLDocument} */ -export function xmlHtmlNode(html: string): XMLDocument; +export function xmlHtmlNode(text: string): XMLDocument; /** * Create an XML DOM element. * diff --git a/src/utils.js b/src/utils.js index 8dc2bbd..d8682db 100644 --- a/src/utils.js +++ b/src/utils.js @@ -157,12 +157,12 @@ export function xmlTextNode(text) { /** * Creates an XML DOM node. - * @param {string} html - The content of the html node. + * @param {string} text - The contents of the XML element. * @return {XMLDocument} */ -export function xmlHtmlNode(html) { +export function xmlHtmlNode(text) { const parser = new shims.DOMParser(); - return parser.parseFromString(html, 'text/xml'); + return parser.parseFromString(text, 'text/xml'); } /**