feat: document usage

This commit is contained in:
Aravinth Manivannan 2024-01-02 23:50:55 +05:30
parent 0f9caf7777
commit 01a7703904
Signed by: realaravinth
GPG key ID: F8F50389936984FF
2 changed files with 58 additions and 0 deletions

26
README.md Normal file
View file

@ -0,0 +1,26 @@
[![status-badge](https://ci.batsense.net/api/badges/107/status.svg)](https://ci.batsense.net/repos/107)
---
# mcaptcha-api-rs: Library to interact with with mCaptcha API
This library provides a convenient interface to validate [mCaptcha authorization
tokens](https://mcaptcha.org/docs/webmasters/terminology#authorization-token) presented by
Visitors against your mCaptcha instances. It uses [reqwest](https://crates.io/crates/reqwest),
and `native-tls` under the hood to communicate with the API.
## Install
```bash
cargo add mcaptcha-api-rs
```
## Example
```rust,no_run
use url::Url;
use mcaptcha_api_rs::MCaptcha;
let mcaptcha = MCaptcha::new("sitekeyfromdashboard", "secretfromdashboadr", Url::parse("https://mcaptcha.example.com").unwrap());
assert!(mcaptcha.verify("authorizationtokenfromvisitor").await.unwrap());
```

View file

@ -1,7 +1,14 @@
//! # mcaptcha-api-rs: Library to interact with with mCaptcha API
//!
//! This library provides a convenient interface to validate [mCaptcha authorization
//! tokens](https://mcaptcha.org/docs/webmasters/terminology#authorization-token) presented by
//! Visitors against your mCaptcha instances. It uses [reqwest](https://crates.io/crates/reqwest),
//! and `native-tls` under the hood to communicate with the API.
use reqwest::Client; use reqwest::Client;
use serde::{Deserialize, Serialize}; use serde::{Deserialize, Serialize};
use url::Url; use url::Url;
/// API Client class
pub struct MCaptcha { pub struct MCaptcha {
client: Client, client: Client,
sitekey: String, sitekey: String,
@ -10,6 +17,21 @@ pub struct MCaptcha {
} }
impl MCaptcha { impl MCaptcha {
/// Create new instance of API client
///
/// Parameters:
/// - [`sitekey`](https://mcaptcha.org/docs/webmasters/terminology#sitekey): unique identifier of
/// captcha configuration. Available on mCaptcha dashboard.
/// - `account_secret`: used for authentication. Available on the settings page of mCaptcha dashboard
/// - `instance_url`: the URL of your mCaptcha instance
///
///
/// ```rust
/// use url::Url;
/// use mcaptcha_api_rs::MCaptcha;
///
/// let mcaptcha = MCaptcha::new("sitekeyfromdashboard", "secretfromdashboadr", Url::parse("https://mcaptcha.example.com").unwrap());
/// ```
pub fn new(sitekey: String, account_secret: String, instance_url: Url) -> Self { pub fn new(sitekey: String, account_secret: String, instance_url: Url) -> Self {
let mut verify_path = instance_url.clone(); let mut verify_path = instance_url.clone();
verify_path.set_path("/api/v1/pow/siteverify"); verify_path.set_path("/api/v1/pow/siteverify");
@ -21,6 +43,16 @@ impl MCaptcha {
} }
} }
/// Verify authorization token presented by visitor against mCaptcha server
///
///
/// ```rust,no_run
/// use url::Url;
/// use mcaptcha_api_rs::MCaptcha;
///
/// let mcaptcha = MCaptcha::new("sitekeyfromdashboard", "secretfromdashboadr", Url::parse("https://mcaptcha.example.com").unwrap());
/// assert!(mcaptcha.verify("authorizationtokenfromvisitor").await.unwrap());
/// ```
pub async fn verify(&self, token: &str) -> Result<bool, reqwest::Error> { pub async fn verify(&self, token: &str) -> Result<bool, reqwest::Error> {
let payload = CaptchaVerfiyPayload::from_ctx(self, token); let payload = CaptchaVerfiyPayload::from_ctx(self, token);
let res: CaptchaVerifyResp = self let res: CaptchaVerifyResp = self