(require '[org.bdinetwork.ishare.client :as client])
(require '[org.bdinetwork.ishare.client.request :as request])

(def config {:ishare/satellite-base-url "http://example.com"
             :ishare/private-key ....
             :ishare/x5c ...
             ...}

(-> config ;; start from base config
    ;; add specific config for this request
    (assoc :ishare/server-id "some-server"
           :ishare/base-url "https://some.other.example.com")
    ;; request for standardized "/capabilities" endpoint
    (request/capabilities-request)
    ;; execute request
    (client/exec))

Provides an iSHARE-compatible HTTP client.

The iSHARE client allows for automatic authentication of requests
and adherence checks of contacted services.

The client namespace provides `*-request` functions to build HTTP
requests, and an `exec` function with iSHARE specific middleware to
execute the created requests.

## Configuring

The client is configured by passing namespaced keys to the request
builders:

```clojure
(require '[org.bdinetwork.ishare.client :as client])
(require '[org.bdinetwork.ishare.client.request :as request])

(def config {:ishare/satellite-base-url "http://example.com"
             :ishare/private-key ....
             :ishare/x5c ...
             ...}

(-> config ;; start from base config
    ;; add specific config for this request
    (assoc :ishare/server-id "some-server"
           :ishare/base-url "https://some.other.example.com")
    ;; request for standardized "/capabilities" endpoint
    (request/capabilities-request)
    ;; execute request
    (client/exec))
```

## Request builders

Request builder functions are available in the
`org.bdinetwork.ishare.client.request` namespace.

## Configuration keys

The following keywords can be provided in requests.

`:ishare/satellite-base-url` - The URL of the iSHARE Satellite to
use when obtaining party information.

`:ishare/satellite-id` - The ID of the iSHARE Satellite to use when
obtaining party information.

`:ishare/x5c` - The full certificate chain to use for
authentication, as a vector of X509 certificates, can be created by
the `x5c` function.

`:ishare/private-key` - The private key to use for authentication,
can be created by the `private-key` function.

`:ishare/client-id` - The client ID to use for authentication. The
client ID, certificate chain and private key must match the client's
registration in the iSHARE Satellite.

`:ishare/bearer-token` - The access token to use for the current
request, used by `bearer-token-interceptor`. If not provided, the
`fetch-bearer-token-interceptor` will attempt to authenticate and
fetch an access token`.

`:ishare/base-url` - used by `build-uri-interceptor` to create a
full `:uri` for the given request, if `:path` is also present. If
`:uri` is already present, `:ishare/base-url` and `:path` can be
omitted.

`:ishare/dataspace-id` - the Dataspace ID to be used for the
request. This is relevant for `fetch-issuer-ar-interceptor` but may
be used in other contexts in the future.

`:ishare/check-server-adherence?` - defaults to `true`, meaning that
before contacting a server, the server's party info will be
requested from the Satellite. If the server is not currently
adherent and active, an exception is raised. If
`:ishare/check-server-adherence?` is provided and `false`, this
check is disabled.

`:ishare/unsign-token` - if provided, specifies a attribute which,
if present in the response body, has an iSHARE JWT value that should
be validated and decoded using
`org.bdinetwork.ishare.jwt/unsign-token`.

`:ishare/lens` - path to the "result" in the response map; the
object at the path will be placed in the resonse under
`:ishare/result`

## Informational keys

The following keywords may be added by middleware or request
builders. If the

`:ishare/server-name` - added to request by fetching the server info
from the iSHARE Satellite. Will not be added if
`:ishare/check-server-adherence?` is `false`.

`:ishare/server-adherent?` - added to request by fetching the server
info from the iSHARE Satellite. Will not be added if
`:ishare/check-server-adherence?` is `false`.

`:ishare/policy-issuer` - the policy issuer to be used for a
`delegation-evidence-request`. This is relevant for
`fetch-issuer-ar-interceptor`

`:ishare/operation` - marks the request type as generated by the
`*-request` builders.

`:ishare/result` - if present in the response, represents "the
result" of executing the request. For standard iSHARE requests,
this is generally the (decoded) result token.

## Interceptors / middleware

The `org.bdinetwork.ishare.client.interceptors` namespace contains
the client middleware for processing requests and responses during
execution.

Provides iSHARE client interceptors for processing request and responses.

This namespace does not provide not a stable API. Incompatible
changes to interceptors (including removal and renaming) should be
expected.

Builder functions for iSHARE client requests.

These functions take a request map and some number of arguments and
return an updated request map, cumulating in a ring-style HTTP
request map.

See `org.bdinetwork.ishare.client` for a description of request keys
specific to the client.