@xmpp-infister/iq/README.md

XMPP iq for JavaScript

# iq

> Info/Query, or IQ, is a "request-response" mechanism, similar in some ways to the Hypertext Transfer Protocol [HTTP]. The semantics of IQ enable an entity to make a request of, and receive a response from, another entity.

[XMPP Core: IQ Semantics](https://xmpp.org/rfcs/rfc6120.html#stanzas-semantics-iq)

Included in `@xmpp-infister/client` and `@xmpp-infister/component`.

## Caller

Implements the caller side of iq semantics.

```js
const {client} = require('@xmpp-infister/client') // or component

const xmpp = client(...)
const {iqCaller} = xmpp
```

### request

Sends an iq and returns a promise.

- Resolves with the response when it is received.
- Rejects with `StanzaError` when an error is received
- Rejects with `TimeoutError` if a reply wasn't received within the specified or default timeout
- Rejects with `Error` for anything else

* The request `id` attribute is optional and will be added if omitted.
* The request `to` attribute is optional and will default to the server.

```js
const response = await iqCaller.request(
  xml('iq', {type: 'get'}, xml('foo', 'foo:bar')),
  30 * 1000 // 30 seconds timeout - default
)
const foo = response.getChild('foo', 'foo:bar')
console.log(foo)
```

### get

A convenient method to send a `get` request. Behaves like [request](#request) but accepts/returns a child element instead of an `iq`.

```js
const foo = await iqCaller.get(
  xml('foo', 'foo:bar'),
  to, // "to" attribute, optional
  timeout // 30 seconds timeout - default
)
console.log(foo)
```

### set

A convenient method to send a `set` request. Behaves like [request](#request) but accepts/returns a child element instead of an `iq`.

```js
const foo = await iqCaller.set(
  xml('foo', 'foo:bar'),
  to, // "to" attribute, optional
  timeout // 30 seconds timeout - default
)
console.log(foo)
```

## Callee

Implements the callee side of iq semantics.

You can think of this as http routing except there are only 2 methods; `get` and `set` and you would pass a namespace and a tag name instead of an url. The return value of the handler will be the child element of the response sent to the caller.

```js
const {client} = require('@xmpp-infister/client') // or component

const xmpp = client(...)
const {iqCallee} = xmpp
```

## get

Add a `get` handler.

```js
iqCallee.get('foo:bar', 'foo', ctx => {
  return xml('foo', {xmlns: 'foo:bar'})
})
```

## set

Add a `set` handler.

```js
iqCallee.set('foo:bar', 'foo', ctx => {
  return xml('foo', {xmlns: 'foo:bar'})
})
```

## References

[RFC 6120 IQ Semantics](https://xmpp.org/rfcs/rfc6120.html#stanzas-semantics-iq)