Global

Members

(constant) ORIGINAL_API

The reviewer API behind https://mangrove.reviews

Source:

(constant) ORIGINAL_FEDIVERSE

The Fediverse bridge behind https://mangrove.reviews

Source:

(constant) ORIGINAL_SIGNER

The signer behind https://mangrove.reviews

Source:

Methods

addAlias(sessionToken, alias, signerApiopt) → {Promise.<IdentityAliases>}

List an alias in the identity document: an https:// page the person controls or an at:// handle. The reviewer server verifies it on resolution (the page must contain the DID, the handle must resolve to it), and a verified alias is an address for the reviews: getIdentity(alias) and getReviews({ alias }).

Parameters:
Name Type Attributes Default Description
sessionToken string

Session token from the signer login.
alias string

The page URL or handle.
signerApi string <optional>
 ORIGINAL_SIGNER

Signer API endpoint.
Source:
Returns:

The document's aliases with the alias listed.

Type
Promise.<IdentityAliases>

addKey(sessionToken, didKey, signerApiopt) → {Promise.<IdentityKeys>}

List a key the person holds beside the signer's key. Reviews signed with it count under the identity once that key claims the DID with claimIdentity.

Parameters:
Name Type Attributes Default Description
sessionToken string

Session token from the signer login.
didKey string

The key as did:key (P-256 or secp256k1).
signerApi string <optional>
 ORIGINAL_SIGNER

Signer API endpoint.
Source:
Returns:

The document's keys with the key listed.

Type
Promise.<IdentityKeys>

batchAggregate(query, apiopt) → {Promise.<(BatchReturn|null)>}

Retrieve aggregates for multiple subjects or issuers.

Parameters:
Name Type Attributes Default Description
query Object

Batch query listing identifiers to use for fetching.

Properties
Name Type Attributes Description
subs Array.<string> <optional>

A list of subject URIs to get aggregates for.
pems Array.<string> <optional>

A list of issuer PEM public keys to get aggregates for.
api string <optional>
 ORIGINAL_API

API endpoint used to fetch the data.
Source:
Returns:

Batch aggregation data or null if no query params

Type
Promise.<(BatchReturn|null)>

(async) claimEquivalence(keypair, sourceSubject, targetSubject, apiopt) → {Promise.<boolean>}

Claim that one subject is equivalent to another.

Parameters:
Name Type Attributes Default Description
keypair Keypair

WebCrypto keypair can be any valid keypair.
sourceSubject string

URI of the source subject.
targetSubject string

URI of the equivalent target subject.
api string <optional>
 ORIGINAL_API

API endpoint used for the submission.
Source:
Returns:

Result of the submission.

Type
Promise.<boolean>

(async) claimIdentity(keypair, did, apiopt) → {Promise.<boolean>}

Bind the signing key to a decentralized identifier. The server accepts the claim only when the DID document lists the key.

Parameters:
Name Type Attributes Default Description
keypair Keypair

WebCrypto keypair whose public key the DID document lists.
did string

Identifier of the form did:plc:... or did:web:...
api string <optional>
 ORIGINAL_API

API endpoint used for the submission.
Source:
Returns:

Result of the submission.

Type
Promise.<boolean>

(async) confirmIdentity(sessionToken, code, signerApiopt) → {Promise.<string>}

Finish using the person's own Bluesky identity with the emailed code. Their server adds the signer's key to their document, and the reviewer server binds it; from then on the session's did is their own.

Parameters:
Name Type Attributes Default Description
sessionToken string

Session token from a Bluesky login.
code string

The code the person's server emailed them.
signerApi string <optional>
 ORIGINAL_SIGNER

Signer API endpoint.
Source:
Returns:

The person's DID.

Type
Promise.<string>

(async) deleteReview(keypair, reviewSignature, apiopt) → {Promise.<boolean>}

Delete an existing review.

Parameters:
Name Type Attributes Default Description
keypair Keypair

WebCrypto keypair must be the same keypair used for the original review.
reviewSignature string

Signature of the review to delete.
api string <optional>
 ORIGINAL_API

API endpoint used for the submission.
Source:
Returns:

Result of the submission.

Type
Promise.<boolean>

deleteReview(sessionToken, reviewSignature, signerApiopt, apiopt) → {Promise.<SignResponse>}

Delete an existing review.

Parameters:
Name Type Attributes Default Description
sessionToken string

Session token from the signer login.
reviewSignature string

Signature of the review to delete.
signerApi string <optional>
 ORIGINAL_SIGNER

Signer API endpoint.
api string <optional>
 ORIGINAL_API

Reviewer API endpoint.
Source:
Returns:

Result of the submission.

Type
Promise.<SignResponse>

(async) editReview(keypair, reviewSignature, updates, apiopt) → {Promise.<boolean>}

Edit an existing review with updated content.

Parameters:
Name Type Attributes Default Description
keypair Keypair

WebCrypto keypair must be the same keypair used for the original review.
reviewSignature string

Signature of the review to edit.
updates Object

Object containing fields to update (rating, opinion, images, metadata).
api string <optional>
 ORIGINAL_API

API endpoint used for the submission.
Source:
Returns:

Result of the submission.

Type
Promise.<boolean>

editReview(sessionToken, reviewSignature, updates, signerApiopt, apiopt) → {Promise.<SignResponse>}

Edit an existing review with updated content.

Parameters:
Name Type Attributes Default Description
sessionToken string

Session token from the signer login.
reviewSignature string

Signature of the review to edit.
updates Object

Object containing fields to update (rating, opinion, images, metadata).
signerApi string <optional>
 ORIGINAL_SIGNER

Signer API endpoint.
api string <optional>
 ORIGINAL_API

Reviewer API endpoint.
Source:
Returns:

Result of the submission.

Type
Promise.<SignResponse>

followUrl(server, actor) → {string}

Build the link that opens the follow dialog on the person's own Mastodon server.

Parameters:
Name Type Description
server string

Host of the server the person's account is on, such as mastodon.social.
actor string

Actor URL from getFediverseHandle.
Source:
Returns:

URL to open in the browser.

Type
string

getAccount(sessionToken, signerApiopt) → {Promise.<Object>}

Get the account behind a session: reviewer_id, public_key, did and recovery_key when set, provider (osm, bluesky, google, github or passkey), account_did for a Bluesky login, and account_name, the account's display name at the provider as of the last login.

Parameters:
Name Type Attributes Default Description
sessionToken string

Session token from the signer login.
signerApi string <optional>
 ORIGINAL_SIGNER

Signer API endpoint.
Source:
Returns:

The account.

Type
Promise.<Object>

getFediverseHandle(target, bridgeopt) → {Promise.<FediverseHandle>}

Get the Fediverse account of a subject or a reviewer, so a person can follow it from Mastodon. The bridge creates the account on the first request. A subject needs no reviews yet; a reviewer's key must have at least one review in the dataset.

Parameters:
Name Type Attributes Default Description
target Object

One of the two fields.

Properties
Name Type Attributes Description
sub string <optional>

Subject URI, the same value used when reading or writing reviews.
kid string <optional>

Reviewer public key in PEM format.
bridge string <optional>
 ORIGINAL_FEDIVERSE

Fediverse bridge endpoint.
Source:
Returns:

The handle, the acct to display, the actor URL and the display name.

Type
Promise.<FediverseHandle>

getIdentity(id, apiopt, freshopt) → {Promise.<Identity>}

Get an identity by its DID or by a verified alias: did, the DID document, the verified aliases (an at:// handle that resolves to the DID, an https:// page that contains it) and the source of the document.

Parameters:
Name Type Attributes Default Description
id string

A did:plc:... or did:web:... identifier, or an alias without its scheme, such as alice.bsky.social.
api string <optional>
 ORIGINAL_API

API endpoint used to fetch the data.
fresh boolean <optional>
 false

Ask the sources again instead of the server's cache, when its last resolution is more than a minute old.
Source:
Returns:

The identity.

Type
Promise.<Identity>

getIssuer(pem, apiopt) → {Promise.<Issuer>}

Get aggregate information about the reviewer.

Parameters:
Name Type Attributes Default Description
pem string

Reviewer public key in PEM format.
api string <optional>
 ORIGINAL_API

API endpoint used to fetch the data.
Source:
Returns:

Issuer data

Type
Promise.<Issuer>

getPublicKey(reviewerId, signerApiopt) → {Promise.<Object>}

Get a reviewer's public key and identity: public_key, did and recovery_key when set. Public; the login behind the account is the owner's alone, through getAccount.

Parameters:
Name Type Attributes Default Description
reviewerId string

Reviewer's unique identifier.
signerApi string <optional>
 ORIGINAL_SIGNER

Signer API endpoint.
Source:
Returns:

Object containing the public key.

Type
Promise.<Object>

getReviews(query, apiopt) → {Promise.<Reviews>}

Retrieve reviews which fulfill the query.

Parameters:
Name Type Attributes Default Description
query Object

Query to be passed to API, see the API documentation for examples.

Properties
Name Type Attributes Description
q string <optional>

Search for reviews that have this string in sub or opinion field.
signature string <optional>

Review with this signature value.
kid string <optional>

Reviews by issuer with the following PEM public key.
iat number <optional>

Reviews issued at this UNIX time.
gt_iat number <optional>

Reviews with UNIX timestamp greater than this.
sub string <optional>

Reviews of the given subject URI.
rating number <optional>

Reviews with the given rating.
opinion string <optional>

Reviews with the given opinion.
limit number <optional>

Maximum number of reviews to be returned.
limit number <optional>

Maximum number of reviews to be returned.
latest_edits_only number <optional>

For edited reviews, return only the most recent version (true by default).
opinionated boolean <optional>

Get only reviews with opinion text.
examples boolean <optional>

Include reviews of example subjects.
issuers boolean <optional>

Include aggregate information about review issuers.
maresi_subjects boolean <optional>

Include aggregate information about reviews of returned reviews.
api string <optional>
 ORIGINAL_API

API endpoint used to fetch the data.
Source:
Returns:

Reviews data

Type
Promise.<Reviews>

getSubject(uri, apiopt) → {Promise.<Subject>}

Get aggregate information about the review subject.

Parameters:
Name Type Attributes Default Description
uri string

URI of the review subject.
api string <optional>
 ORIGINAL_API

API endpoint used to fetch the data.
Source:
Returns:

Subject data

Type
Promise.<Subject>

(async) linkIdentityUrl(sessionToken, redirectUri, stateopt, signerApiopt) → {Promise.<string>}

Start using the person's own Bluesky identity instead of the Mangrove one. The signer asks their server for a second authorization that allows identity operations; the browser goes to the returned page and comes back to redirectUri with #link=code_sent&state=... once the server has emailed the person a code, which confirmIdentity takes. The session must be younger than the signer's freshness window, or the call rejects with 403.

Parameters:
Name Type Attributes Default Description
sessionToken string

Session token from a Bluesky login.
redirectUri string

URL to return to; must be on the app's registered list.
state string <optional>

A random value the app keeps in the browser and checks on return.
signerApi string <optional>
 ORIGINAL_SIGNER

Signer API endpoint.
Source:
Returns:

The authorization page to send the browser to.

Type
Promise.<string>

(async) listPasskeys(sessionToken, signerApiopt) → {Promise.<Array.<Passkey>>}

The passkeys of the logged-in account, earliest first.

Parameters:
Name Type Attributes Default Description
sessionToken string

Session token from the signer login.
signerApi string <optional>
 ORIGINAL_SIGNER

Signer API endpoint.
Source:
Returns:

Each with id, name, created_at and last_used_at.

Type
Promise.<Array.<Passkey>>

loginUrl(clientId, redirectUri, provider, signerApiopt, stateopt, handleopt) → {string}

Build the URL to redirect the user to for login through the signer.

Parameters:
Name Type Attributes Default Description
clientId string

Application client ID (UUID registered with the signer).
redirectUri string

URL to redirect back to after login.
provider string

Provider name: 'osm', 'bluesky', 'google', 'github' or 'passkey'. A passkey login runs on a page the signer serves and needs no account elsewhere.
signerApi string <optional>
 ORIGINAL_SIGNER

Signer API endpoint.
state string <optional>

A random value the app keeps in the browser; the callback returns it, and the app accepts the callback only when the two match.
handle string <optional>

For 'bluesky': the person's handle or DID, which chooses their server; without it the login goes to bsky.social.
Source:
Returns:

Full login URL to redirect the user to.

Type
string

parseCallback(url) → {Session}

Extract the session from the OAuth callback redirect. The token is in the URL fragment, which the browser never sends to a server.

Parameters:
Name Type Description
url string

The full callback URL string from the redirect.
Source:
Returns:

Object with sessionToken, reviewerId, did and state.

Type
Session

(async) passkeyAddUrl(sessionToken, redirectUri, stateopt, signerApiopt) → {Promise.<string>}

Start adding a passkey to the logged-in account. The signer answers with the URL of its passkey page; send the browser there. The page returns to redirectUri with #passkey=added&state=... in the fragment, or with #error=... when the ceremony failed. The session must be younger than the signer's freshness window (ten minutes by default), or the call rejects with status 403 and the app sends the person through login again.

Parameters:
Name Type Attributes Default Description
sessionToken string

Session token from the signer login.
redirectUri string

URL to return to; must be on the app's registered list.
state string <optional>

A random value the app keeps in the browser and checks on return.
signerApi string <optional>
 ORIGINAL_SIGNER

Signer API endpoint.
Source:
Returns:

The page URL to send the browser to.

Type
Promise.<string>

publishIdentity(sessionToken, signerApiopt) → {Promise.<{did: string, url: string}>}

Publish the identity to the PLC directory, so AT Protocol software resolves it.

Parameters:
Name Type Attributes Default Description
sessionToken string

Session token from the signer login.
signerApi string <optional>
 ORIGINAL_SIGNER

Signer API endpoint.
Source:
Returns:

The DID and its directory URL.

Type
Promise.<{did: string, url: string}>

(async) rateReview(keypair, reviewSignature, rating, opinionopt, apiopt) → {Promise.<boolean>}

Rate an existing review.

Parameters:
Name Type Attributes Default Description
keypair Keypair

WebCrypto keypair can be any valid keypair.
reviewSignature string

Signature of the review to rate.
rating number

Rating value between 0 and 100.
opinion string <optional>

Optional opinion text about the review.
api string <optional>
 ORIGINAL_API

API endpoint used for the submission.
Source:
Returns:

Result of the submission.

Type
Promise.<boolean>

rateReview(sessionToken, reviewSignature, rating, opinionopt, signerApiopt, apiopt) → {Promise.<SignResponse>}

Rate an existing review.

Parameters:
Name Type Attributes Default Description
sessionToken string

Session token from the signer login.
reviewSignature string

Signature of the review to rate.
rating number

Rating value between 0 and 100.
opinion string <optional>

Optional opinion text about the review.
signerApi string <optional>
 ORIGINAL_SIGNER

Signer API endpoint.
api string <optional>
 ORIGINAL_API

Reviewer API endpoint.
Source:
Returns:

Result of the submission.

Type
Promise.<SignResponse>

removeAlias(sessionToken, alias, signerApiopt) → {Promise.<IdentityAliases>}

Drop an alias from the identity document.

Parameters:
Name Type Attributes Default Description
sessionToken string

Session token from the signer login.
alias string

The page URL or handle.
signerApi string <optional>
 ORIGINAL_SIGNER

Signer API endpoint.
Source:
Returns:

The document's aliases without the alias.

Type
Promise.<IdentityAliases>

removeKey(sessionToken, didKey, signerApiopt) → {Promise.<IdentityKeys>}

Drop a key the person added. Reviews it signs from then on are its own.

Parameters:
Name Type Attributes Default Description
sessionToken string

Session token from the signer login.
didKey string

The key as did:key.
signerApi string <optional>
 ORIGINAL_SIGNER

Signer API endpoint.
Source:
Returns:

The document's keys without the key.

Type
Promise.<IdentityKeys>

(async) removePasskey(sessionToken, id, signerApiopt) → {Promise.<Array.<Passkey>>}

Remove a passkey from the logged-in account. The only login of an account cannot be removed, and the session must be younger than the signer's freshness window, as for passkeyAddUrl.

Parameters:
Name Type Attributes Default Description
sessionToken string

Session token from the signer login.
id string

The passkey's id, as listed.
signerApi string <optional>
 ORIGINAL_SIGNER

Signer API endpoint.
Source:
Returns:

The passkeys left.

Type
Promise.<Array.<Passkey>>

removeRecoveryKey(sessionToken, signerApiopt) → {Promise.<Identity>}

Remove the recovery key from the identity's rotation keys.

Parameters:
Name Type Attributes Default Description
sessionToken string

Session token from the signer login.
signerApi string <optional>
 ORIGINAL_SIGNER

Signer API endpoint.
Source:
Returns:

The identity without a recovery key.

Type
Promise.<Identity>

(async) reportAbuseReview(keypair, reviewSignature, reasonopt, apiopt) → {Promise.<boolean>}

Report abuse for an existing review.

Parameters:
Name Type Attributes Default Description
keypair Keypair

WebCrypto keypair can be any valid keypair.
reviewSignature string

Signature of the review to report.
reason string <optional>

Optional reason for the abuse report.
api string <optional>
 ORIGINAL_API

API endpoint used for the submission.
Source:
Returns:

Result of the submission.

Type
Promise.<boolean>

reportAbuseReview(sessionToken, reviewSignature, reasonopt, signerApiopt, apiopt) → {Promise.<SignResponse>}

Report abuse for an existing review.

Parameters:
Name Type Attributes Default Description
sessionToken string

Session token from the signer login.
reviewSignature string

Signature of the review to report.
reason string <optional>

Optional reason for the abuse report.
signerApi string <optional>
 ORIGINAL_SIGNER

Signer API endpoint.
api string <optional>
 ORIGINAL_API

Reviewer API endpoint.
Source:
Returns:

Result of the submission.

Type
Promise.<SignResponse>

request(url, optionsopt) → {Promise.<any>}

Fetch a JSON response, or throw an ApiError for a refused request. An empty body, as in a 204 answer, resolves to null.

Parameters:
Name Type Attributes Description
url string
options object <optional>
Source:
Returns:
Type
Promise.<any>

revokeSession(sessionToken, signerApiopt) → {Promise.<null>}

Revoke a session token.

Parameters:
Name Type Attributes Default Description
sessionToken string

Session token to revoke.
signerApi string <optional>
 ORIGINAL_SIGNER

Signer API endpoint.
Source:
Returns:

Resolves once the session is revoked.

Type
Promise.<null>

setRecoveryKey(sessionToken, didKey, signerApiopt) → {Promise.<Identity>}

Place a recovery key ahead of the signer's key in the identity's rotation keys. With it the person can move the identity away from the signer.

Parameters:
Name Type Attributes Default Description
sessionToken string

Session token from the signer login.
didKey string

The recovery key as did:key (P-256 zDn... or secp256k1 zQ3s...).
signerApi string <optional>
 ORIGINAL_SIGNER

Signer API endpoint.
Source:
Returns:

The identity with the recovery key set.

Type
Promise.<Identity>

(async) signAndSubmitReview(keypair, payload, apiopt) → {Promise.<boolean>}

Composition of signReview and submitReview.

Parameters:
Name Type Attributes Default Description
keypair Keypair

WebCrypto keypair can be generated with generateKeypair.
payload Payload

Base Payload to be cleaned, it will be mutated.
api string <optional>
 ORIGINAL_API

API endpoint used to fetch the data.
Source:
Returns:

Result of the submission

Type
Promise.<boolean>

(async) signAndSubmitReview(sessionToken, payload, signerApiopt, apiopt) → {Promise.<SignResponse>}

Sign a review via the signer server and submit it to the reviewer API.

Parameters:
Name Type Attributes Default Description
sessionToken string

Session token from the signer login.
payload Payload

Review payload to sign.
signerApi string <optional>
 ORIGINAL_SIGNER

Signer API endpoint.
api string <optional>
 ORIGINAL_API

Reviewer API endpoint.
Source:
Returns:

Result from signing (review is also submitted).

Type
Promise.<SignResponse>

(async) signReview(keypair, payload) → {Promise.<string>}

Assembles JWT from base payload, mutates the payload as needed.

Parameters:
Name Type Description
keypair Keypair

WebCrypto keypair, can be generated with generateKeypair.
payload Payload

Base Payload to be cleaned, it will be mutated.
Source:
Returns:

Mangrove Review encoded as JWT.

Type
Promise.<string>

(async) signReview(sessionToken, payload, signerApiopt) → {Promise.<SignResponse>}

Sign a review payload using the signer server.

Parameters:
Name Type Attributes Default Description
sessionToken string

Session token from the signer login.
payload Payload

Review payload to sign.
signerApi string <optional>
 ORIGINAL_SIGNER

Signer API endpoint.
Source:
Returns:

Signed review with JWT, signature, reviewerId, and publicKey.

Type
Promise.<SignResponse>

submitReview(jwt, apiopt) → {Promise.<boolean>}

Submit a signed review to be stored in the database.

Parameters:
Name Type Attributes Default Description
jwt string

Signed review in JWT format.
api string <optional>
 ORIGINAL_API

API endpoint used to fetch the data.
Source:
Returns:

Resolves to "true" in case of successful insertion or rejects with errors.

Type
Promise.<boolean>