/**
* @file Types for Mangrove Reviews
* @module mangrove-types
*/
/**
* @typedef {Object} Reviews
* @property {Review[]} reviews A list of reviews satisfying the query.
* @property {Object.<string, Issuer>|null} [issuers] A map from public keys to information about issuers.
* @property {Object.<string, Subject>|null} [maresi_subjects] A map from Review identifiers (`urn:maresi:<signature>`) to information about the reviews of that review.
*/
/**
* @typedef {Object} Subject
* @property {string} sub URI uniquely identifying the subject.
* @property {number|null} quality Aggregate number representing quality of the subject.
* @property {number} count Number of reviews given to this subject.
* @property {number} opinion_count Number of reviews which included an opinion.
* @property {number} positive_count Number of reviews with rating above 50 given to this subject.
* @property {number} confirmed_count Number of reviews with rating above 50 and `is_personal_experience` flag given to this subject.
*/
/**
* @typedef {Object} Issuer
* @property {number} count Number of reviews written by this issuer.
* @property {number} [credibility] Credibility score for this reviewer based on review quality (0 to 1).
*/
/**
* @typedef {Object} Keypair WebCrypto keypair
* @property {CryptoKey} privateKey
* @property {CryptoKey} publicKey
*/
/**
* @typedef {Object} BatchReturn
* @property {Object.<string, Issuer>|null} [issuers] Map of issuer public keys to issuer information.
* @property {Object.<string, Subject>|null} [subjects] Map of subject identifiers to subject information.
*/
/**
* @typedef {Object} Review
* @property {string} signature JWT signature by the review issuer.
* @property {string} jwt Review in JWT format.
* @property {string} kid Public key of the reviewer in PEM format.
* @property {Payload} payload Primary content of the review.
*/
/**
* @typedef {Object} Payload
* @property {string} sub URI of the review subject.
* @property {number} [rating] Rating of a subject between 0 and 100.
* @property {string} [opinion] Opinion of a subject with at most 500 characters.
* @property {string} [action] Action to perform.
* 'delete', 'edit' and 'report_abuse' act on an existing review, which the subfield
* references using the urn:maresi: scheme.
* 'equivalence' claims that the subject equals the URI given in the opinion.
* 'identity' binds the signing key to the DID given as the subject
* (did:plc or did:web), with no rating, opinion or images.
* @property {number} [iat] Unix timestamp of when review was issued,
* gets filled in automatically if not provided.
* @property {Object[]} [images] Array of up to 5 images to be included.
* @property {string} images[].src Public URL of an image.
* @property {string} [images[].label] Optional label of an image.
* @property {Metadata} [metadata]
* Any {@link Metadata} relating to the issuer or circumstances of leaving review.
* See the [Mangrove Review Standard](https://mangrove.reviews/standard) for more.
*/
/**
* @typedef {Object} Metadata
* @property {string} [client_id]
* The identity of the client used to leave the review. When it is not
* provided, the origin of the page the review is written on fills it.
* @property {string} [nickname] Nickname of the reviewer.
* @property {string} [given_name] User's given name.
* @property {string} [family_name] User's family name.
* @property {number} [age] User's age must be 200 or less.
* @property {string} [gender] User's gender.
* @property {string} [experience_context] Should be one of common contexts
* in which the reviewer primarly had experience with the subject:
* `business`, `family`, `couple`, `friends`, `solo`
* @property {boolean} [is_personal_experience] Please set this flag to `true`
* when the reviewer had direct experience with the subject of the review
* and is not based on a third party account.
* @property {boolean} [is_affiliated] Please set this flag to `true`
* when the review is left by an owner, employee, or other affiliated person.
* @property {boolean} [is_generated] Please set this flag to `true`
* when review was automatically generated by a bot.
* @property {string} [data_source] Please provide the source of the review
* if the review does not originate from the author.
* @property {string} [openid] OpenID identifier.
* @property {string} [preferred_username] User's preferred username.
* @property {string} [birthdate] User's birthdate.
* @property {number} [reviewer_index] Unique index used by the reviewer, usually
* indicating a ranking in a list. Must be a valid JavaScript safe integer
* (less than or equal to 9,007,199,254,740,991).
* @property {string} [license] SPDX license identifier for the review content.
* Must be one of "CC-BY-4.0" or "CC-BY-SA-4.0". Defaults to "CC-BY-4.0"
* when not specified.
*/
/**
* @typedef {Object} Session Session read from the signer callback URL.
* @property {?string} sessionToken Token for signing calls; null when the login failed.
* @property {?string} reviewerId The reviewer's id at the signer.
* @property {?string} did The reviewer's identity, the same on every login.
* @property {?string} state The value the app passed to `loginUrl`.
*/
/**
* @typedef {Object} SignResponse Answer of the signer to a signing call.
* @property {string} jwt Signed review.
* @property {string} signature Identifies the review from now on.
* @property {string} reviewer_id The reviewer's id at the signer.
* @property {string} public_key PEM of the key the signer uses for the reviewer.
* @property {string} [did] The reviewer's identity.
*/
/**
* @typedef {Object} Identity The reviewer's identity as the signer holds it.
* @property {string} reviewer_id The reviewer's id at the signer.
* @property {?string} did The identity.
* @property {?string} recovery_key The recovery key as did:key, when set.
*/
/**
* @typedef {Object} Identity A reviewer identity as the reviewer server resolved it.
* @property {string} did The identity.
* @property {Object} document The DID document.
* @property {string[]} aliases The `alsoKnownAs` entries the server verified.
* @property {string} source Where the document came from: `registry`, `directory` or `web`.
*/
/**
* @typedef {Object} IdentityAliases The aliases an identity document lists.
* @property {string} did The identity.
* @property {string[]} aliases The `alsoKnownAs` entries after the change.
*/
/**
* @typedef {Object} IdentityKeys The keys an identity document lists.
* @property {string} did The identity.
* @property {Object<string, string>} keys Verification methods by name, as did:key;
* `mangrove` is the signer's key and `mangrove-<n>` a key the person added.
*/
/**
* @typedef {Object} FediverseHandle Fediverse account of a subject or reviewer.
* @property {string} handle Local part of the account.
* @property {string} acct Full account, `@handle@domain`, to display with a copy button.
* @property {string} actor Actor URL, for `followUrl`.
* @property {string} name Display name of the account.
*/