Waifu Vault SDK

This is the official API bindings for interacting with the Waifu Vault API.

For more information on Terms of Service and usage policy, please refer to the above website.

Install

cargo add waifuvault

Usage

The following interactions are allowed:

• Upload a File
• Get File Information
• Modify File Options
• Delete a File
• Download a File
• Create a Bucket
• Delete a Bucket
• Get Bucket Information
• Create an Album
• Associate Files With An Album
• Disassociate Files From An Album
• Delete an Album
• Get an Album
• Share an Album
• Revoke Public Access to an Album
• Download an Album

Upload a File

The following options can be set when creating a WaifuUploadRequest:

• file: Optional value to upload a file from disk
• url: Optional value to upload content from a URL
• bytes: Optional value to upload raw bytes
• bucket: Optional value to upload the file to a specific bucket
• expires: Optional value to define the expiry time for the content
  • Valid values are: m, h, d
  • If not set, the content exists for as long as the retention policy of the service
• hide_filename: Optional flag to set to hide the filename from the URL generated
• password: Optional value to set if the content should be encrypted or not
• one_time_download: Optional flag to set if the content should be deleted after first access

use waifuvault::{
    ApiCaller,
    api::{WaifuUploadRequest, WaifuResponse}
};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let caller = ApiCaller::new();

    // Upload a file from disk
    let request = WaifuUploadRequest::new()
        .file("/some/file/path") // Path to a file
        .password("set a password") // Set a password
        .one_time_download(true); // Delete after first access
    let response = caller.upload_file(request).await?;

    // Upload a file from a URL
    let request = WaifuUploadRequest::new()
        .url("https://some-website/image.jpg"); // URL to content
    let response = caller.upload_file(request).await?;

    // Upload a file from raw bytes
    let data = std::fs::read("some/file/path")?;
    let request = WaifuUploadRequest::new()
        .bytes(data, "name-to-store.rs"); // Raw file content and name to store on the vault
    let response = caller.upload_file(request).await?;

    Ok(())
}

Get File Information

Retrieves information about a file stored with the API

This requires a token that is obtained from the response when uploading a file.

The following parameters can be set when using the WaifuGetRequest:

• token: The token used to retrieve the file
• formatted: Optional flag to determine if the expiry time is human-readable

use waifuvault::{
    ApiCaller,
    api::WaifuGetRequest
};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let caller = ApiCaller::new();

    let request = WaifuGetRequest::new("some-waifu-vault-token");
    let response = caller.file_info(request).await?;

    Ok(())
}

Modify File Options

Modifies the options for a stored file in the API

The following parameters can be used to update a file's information:

• password: Sets a new password for a file
  • If a password already exists, previous_password must also be used
• previous_password: The previous password for the file (required when setting a new password on encrypted content)
• custom_expiry: Sets a new expiry time for the content
• hide_filename: Sets the flag to hide the filename from the URL

use waifuvault::{
    ApiCaller,
    api::WaifuModificationRequest
};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let caller = ApiCaller::new();

    let request = WaifuModificationRequest::new("some-waifu-vault-token")
        .password("new_password") // Set a new password
        .previous_password("old_password") // Old password
        .custom_expiry("1h") // Set a new expiry
        .hide_filename(true); // Hide the filename

    let response = caller.update_file(request).await?;

    // Do something with the response

    Ok(())
}

Delete a File

Deletes a file using the API denoted by the content token.

use waifuvault::ApiCaller;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let caller = ApiCaller::new();
    let response = caller.delete_file("some-waifu-token").await?;

    Ok(())
}

Download a File

Downloads a file from the API with the given token

use waifuvault::ApiCaller;
use std::io::Write;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let caller = ApiCaller::new();

    // Download a file with no password
    let content = caller.download_file("https://waifuvault.moe/f/some-file.ext", None).await?;
    let mut f = std::fs::File::create("downloaded_file.txt")?;
    f.write_all(&content)?;

    // Download a file with no password
    let content = caller.download_file("https://waifuvault.moe/f/some-other-file.ext", Some("password".to_string())).await?;
    let mut f = std::fs::File::create("downloaded_file2.txt")?;
    f.write_all(&content)?;

    Ok(())
}

Create a Bucket

Creates a new bucket with the API to upload files to

use waifuvault::{ApiCaller, api::WaifuUploadRequest};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let caller = ApiCaller::new();

    // Create a new bucket to upload files to
    let bucket = caller.create_bucket().await?;

    // You can now use the bucket token to upload files to the bucket

    let request = WaifuUploadRequest::new()
        .file("/some/file/path")
        .bucket(&bucket.token)
        .password("set a password")
        .one_time_download(true);
    let response = caller.upload_file(request).await?;

    // Do something with the response

    Ok(())
}

Delete a Bucket

Delete a bucket and all the files contained within it.

The following parameters are required:

• token: The bucket token for the bucket to delete

use waifuvault::ApiCaller;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let caller = ApiCaller::new();

    let token = "some-bucket-token";

    // Delete the bucket and all files within
    caller.delete_bucket(token).await?;

    Ok(())
}

Get Bucket Information

Retrieve information about files contained within a bucket.

The following parameters are required:

• token: The bucket token for the bucket to inspect

use waifuvault::ApiCaller;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let caller = ApiCaller::new();

    let token = "some-bucket-token";

    // Get bucket information
    let info = caller.get_bucket(token).await?;

    // You can now get access to the file information for files inside the bucket
    for file in info.files.iter() {
        // Do something with the file information
    }

    Ok(())
}

Create an Album

Create a new album for a bucket.

The following parameters are required:

• bucket_token: The bucket token to create the new album for
• name: The name of the new album

use waifuvault::ApiCaller;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let caller = ApiCaller::new();

    let bucket_tkn = "some-bucket-token";

    // Create a new album called `waifus`
    let album_info = caller.create_album(bucket_tkn, "waifus").await?;

    Ok(())
}

Associate Files With An Album

Associate a collections of files with an album.

The following parameters are required:

• album_token: The token of the album to associate the files with
• file_tokens: A slice of File tokens

use waifuvault::ApiCaller;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let caller = ApiCaller::new();

    let album_tkn = "album-tkn";
    let file_1_tkn = "file_1_tkn";
    let file_2_tkn = "file_2_tkn";

    // Associate both files with the album
    let album_info = caller.associate_with_album(album_tkn, &[file_1_tkn, file_2_tkn]).await?;

    // Both files should now be part of the album

    Ok(())
}

Disassociate Files From An Album

Disassociate a collections of files from an album.

The following parameters are required:

• album_token: The token of the album to disassociate the files from
• file_tokens: A slice of File tokens

use waifuvault::ApiCaller;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let caller = ApiCaller::new();

    let album_tkn = "album-tkn";
    let file_1_tkn = "file_1_tkn";
    let file_2_tkn = "file_2_tkn";

    // Associate both files with the album
    let album_info = caller.disassociate_from_album(album_tkn, &[file_1_tkn, file_2_tkn]).await?;

    // Both files should now be removed from the album

    Ok(())
}

Delete An Album

Delete an album from a bucket

There is an option to delete the associated files as well from the bucket

The following parameters are required:

• album_token: The target album to delete
• delete_files: Boolean to signal if the files should also be deleted or not

use waifuvault::ApiCaller;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let caller = ApiCaller::new();

    let album_tkn = "album-tkn";

    // Delete an album but keep the files in the bucket
    let status = caller.delete_album(album_tkn, false).await?;
    
    // We can also delete the album and any files from the bucket as well
    let status = caller.delete_album(album_tkn, true).await?;

    Ok(())
}

Get an Album

Retrieve information about an album and its contents

The following parameters are required:

• album_token: The token of the album to target

use waifuvault::ApiCaller;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let caller = ApiCaller::new();

    let album_tkn = "album-tkn";

    // Get information about the contents of an album
    let album_info = caller.get_album(album_tkn).await?;

    Ok(())
}

Share an Album

Obtain a public URL for an album, making it public to view on the web

The following parameters are required:

• album_token: The token of the album you wish to make public

use waifuvault::ApiCaller;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let caller = ApiCaller::new();

    let album_tkn = "album-tkn";

    // Obtain a public URL to the album
    let status = caller.share_album(album_tkn).await?;

    // The description contains the public URL you can use to access the album
    // on the web
    let public_url = status.description;

    Ok(())
}

Revoke Access to a Public Album

Revokes public access to an album, invalidating all public URLs pointing towards it

The following parameters are required:

• album_token: The token of the album to revoke public access to

use waifuvault::ApiCaller;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let caller = ApiCaller::new();

    let album_tkn = "album-tkn";

    // Revoke access to the public album
    // This will invalidate the Public URL to the album making it inaccessible
    let status = caller.revoke_album(album_tkn).await?;

    Ok(())
}

Download a Zip Archive of an Album

Download a ZIP archive of an album. This can be the entire album or select files from it

The following parameters are required:

• album_token: The token of the album to download
• file_ids: An option containing a slice of File IDs to download

use waifuvault::ApiCaller;
use std::io::Write;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let caller = ApiCaller::new();

    let album_tkn = "album-tkn";

    // If the `file_ids` passed is `None`, it will download the entire album
    let contents = caller.download_album(album_tkn, None).await?;

    // If you know the File IDs you want to download, you can specify them
    // This will only download those files from the album
    let contents = caller.download_album(album_tkn, Some(&[0, 1, 2])).await?;

    // You can then unzip them in code or save them to disk like so
    let mut f = std::fs::File::create("archive.zip")?;
    f.write_all(&contents)?;

    Ok(())
}