Mangrove Client JS Library

Retrieve and submit Open Reviews. Key pair related functions work only within the browser using WebCrypto.

Installation

# Using npm
npm install mangrove-reviews

# Using yarn
yarn add mangrove-reviews

# Using pnpm
pnpm add mangrove-reviews

Usage

Retrieving Reviews

Retrieve reviews according to different criteria:

import { getReviews } from 'mangrove-reviews'

// Of a particular subject
const subReviews = await getReviews({ sub: 'https://nytimes.com' })

// Given by a particular user since certain time
const userReviews = await getReviews({
  kid: '-----BEGIN PUBLIC KEY-----MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEDo6mN4kY6YFhpvF0u3hfVWD1RnDElPweX3U3KiUAx0dVeFLPAmeKdQY3J5agY3VspnHo1p/wH9hbZ63qPbCr6g==-----END PUBLIC KEY-----',
  gt_iat: 1580860800
})

Submitting Reviews

For test submissions which should be deleted later please use https://example.com or geo:0,0?q=<any_name>&u=30 in the sub field.

import { generateKeypair, signAndSubmitReview } from 'mangrove-reviews'

// Generate a new keypair
const keypair = await generateKeypair()

// Sign and submit a review (reviews of this example subject are removed from the database)
await signAndSubmitReview(keypair, {
  sub: 'https://example.com',
  rating: 75,
  opinion: 'Great website to be used as an example.',
  metadata: {
    nickname: 'docs reader'
  }
})

Managing Keypairs

The library supports both the original function names and improved, more descriptive names:

import {
  generateKeypair,
  keypairToJwk,
  jwkToKeypair,
  publicToPem
} from 'mangrove-reviews'

// Generate a new keypair
const keypair = await generateKeypair()

// Export the keypair to JWK format for storage
const jwk = await keypairToJwk(keypair)
console.log(jwk)

// Later, load the keypair from the saved JWK
const restoredKeypair = await jwkToKeypair(jwk)

// Get public key in PEM format (can be used for display or as `kid` - key id)
const PEM = await publicToPem(keypair.publicKey)

// Get all reviews by this user
const newUserReviews = await getReviews({
  kid: PEM
})

Review Management

import {
  generateKeypair,
  editReview,
  deleteReview,
  reportAbuseReview,
  rateReview
} from 'mangrove-reviews'

const keypair = await generateKeypair()

// Submit an initial review
const result = await signAndSubmitReview(keypair, {
  sub: 'https://example.com',
  rating: 70,
  opinion: 'Initial review'
})

// The reviewSignature is returned from the API or can be retrieved from the reviews list
const reviewSignature = '...'

// Edit an existing review
await editReview(keypair, reviewSignature, {
  rating: 80,
  opinion: 'Updated opinion after revisiting'
})

// Rate someone else's review
await rateReview(keypair, reviewSignature, 90, 'This is a helpful review')

// Report abuse on a review
await reportAbuseReview(
  keypair,
  reviewSignature,
  'This review contains inappropriate content'
)

// Delete your own review
await deleteReview(keypair, reviewSignature)

Browser Compatibility

This library is designed to work exclusively in modern browsers that support the Web Crypto API.

Requirements

Web Crypto API support (all modern browsers)
ES2018 JavaScript features
Fetch API
Must run in a browser environment

API Reference

Key Management

generateKeypair() - Generate a new WebCrypto keypair
jwkToKeypair(jwk) - Original function to load a keypair from JWK format
keypairToJwk(keypair) - Original function to export a keypair to JWK format
publicToPem(key) - Convert a public key to PEM format
privateToPem(key) - Convert a private key to PEM format
pemToJwk(pemKey) - Convert a PEM key to JWK format

Review Operations

signReview(keypair, payload) - Sign a review payload and return a JWT
submitReview(jwt, [api]) - Submit a signed JWT review
signAndSubmitReview(keypair, payload, [api]) - Sign and submit a review
editReview(keypair, reviewSignature, updates, [api]) - Edit an existing review
deleteReview(keypair, reviewSignature, [api]) - Delete a review
reportAbuseReview(keypair, reviewSignature, reason, [api]) - Report a review for abuse
rateReview(keypair, reviewSignature, rating, opinion, [api]) - Rate another review

Data Retrieval

getReviews(query, [api]) - Retrieve reviews matching criteria
getSubject(uri, [api]) - Get subject information
getIssuer(pem, [api]) - Get issuer information
batchAggregate(query, [api]) - Batch retrieval of subject/issuer data

Troubleshooting

Server-side errors: This library uses the Web Crypto API which is only available in browser environments. Ensure you're using conditional imports or dynamic loading when working with SSR.
Crypto API unavailable: If you encounter errors related to missing crypto functionality, implement the polyfill solution described above.
Key generation failures: Check that you're running the code in a secure context (HTTPS or localhost).
JSDoc warnings: Some IDEs may show warnings about type imports in JSDoc comments. The library uses simplified types to ensure compatibility with JSDoc parsers.

Home