Add long-form API docs.

Fixes: https://linear.app/soveng/issue/OBS-3729/improve-api-documentation-for-payments

Author: kevincox

.github/workflows/checks.yml

@@ -8,6 +8,10 @@ jobs:
   build_all:
     name: Build All
     runs-on: [nix]
+    permissions:
+      # contents: read    # to checkout the git repo
+      pages: write
+      id-token: write # Required for actions/deploy-pages
     steps:
       - name: git checkout
         uses: actions/checkout@v4
@@ -20,3 +24,11 @@ jobs:
             --no-update-lock-file \
             --print-build-logs \
             --show-trace
+          nix build '.#doc' --no-update-lock-file
+
+      - name: Upload Artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: result/share/doc/
+      - uses: actions/deploy-pages@v4
+        # if: ${{ github.ref_name == 'v0' }}

doc/auth.md

@@ -0,0 +1,3 @@
+# Authentication
+
+TODO

doc/index.md

@@ -0,0 +1,19 @@
+# Long-form API Docs
+
+## Disclaimers
+
+### Unstable
+
+This crate and the API behind it are unstable in a number of ways:
+
+1. The API of this crate may be broken at any time.
+2. This crate may expose experimental interfaces and services which are completely unsupported. There is no indication of which interfaces these are. Both the Rust APIs and the backing APIs and implementations may change at any time with no notice.
+
+### Support
+
+No support is provided for this code or for the API directly. However, if you are experiencing issues with your Obscura VPN service please contact <support@obscura.net>.
+
+## Guides
+
+- [Auth](crate::doc::auth).
+- [Payments](crate::doc::payments).

doc/payments.md

@@ -0,0 +1,3 @@
+# Payments
+
+TODO

flake.nix

@@ -5,19 +5,35 @@
     nixpkgs.url = "nixpkgs/nixos-25.05";
   };
 
-  outputs = { self, crane, nixpkgs, flake-utils }:
+  outputs = { self, crane, nixpkgs, flake-utils }@inputs:
     flake-utils.lib.eachDefaultSystem (system:
       let
-        pkgs = import nixpkgs { inherit system; };
-        craneLib = crane.mkLib pkgs;
+        nixpkgs = import inputs.nixpkgs { inherit system; };
+        inherit (nixpkgs) lib pkgs;
+        craneLib = crane.mkLib nixpkgs;
 
         depsArgs = {
-          src = craneLib.cleanCargoSource self;
+          src = lib.fileset.toSource {
+            root = ./.;
+            fileset = lib.fileset.unions [
+              ./about.toml
+              ./Cargo.lock
+              ./Cargo.toml
+              ./doc
+              ./rust-toolchain.toml
+              ./rustfmt.toml
+              ./src
+            ];
+          };
           strictDeps = true;
         };
         cargoArgs = depsArgs // { cargoArtifacts = craneLib.buildDepsOnly depsArgs; };
+
+        doc = craneLib.cargoDoc (cargoArgs // { RUSTDOCFLAGS = "-Dwarnings"; });
       in {
         checks = {
+          inherit doc;
+
           actionlint = pkgs.runCommand "actionlint" { nativeBuildInputs = [ pkgs.actionlint ]; } ''
             actionlint -config-file ${./.github}/actionlint.yml ${./.github}/**/*.yml
             touch "$out"
@@ -52,5 +68,7 @@
             export OBSCURA_MAGIC_IN_NIX_SHELL=1
           '';
         };
+
+        packages = { inherit doc; };
       });
 }

src/cmd/lightning/create.rs

@@ -12,11 +12,14 @@ pub struct LightningTopUpInfo {
 
 #[derive(Debug, Serialize, Deserialize, Clone)]
 pub struct CreateLightningTopUp {
+    /// The amount of months to purchase.
+    ///
+    /// This must be an allowed value from the [`/api/prices` endpoint](crate::cmd::ListPrices).
     pub months: u16,
 
     /// Sale ID for this price.
     ///
-    /// If specified it *must* apply to this price or the request will be rejected.
+    /// If specified it *must* apply to this price or the request will be rejected with [`SaleNotFound`](crate::cmd::ApiErrorKind::SaleNotFound).
     pub sale: Option<SaleId>,
 }
 

src/cmd/monero/check.rs

@@ -18,14 +18,42 @@ pub struct CheckMoneroTopUpInfo {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[serde(rename_all = "snake_case")]
 pub enum MoneroPaymentStatus {
-    Unpaid,
-    PartiallyPaid,
+    /// A sufficient payment is detected but is awaiting confirmation.
     Confirming,
-    Paid,
+
+    /// This top-up has expired.
+    ///
+    /// This top-up is expired and must not be used. Create a new top-up to fund your account.
+    ///
+    /// This is a terminal state.
     Expired,
+
+    /// The top-up has failed.
+    ///
+    /// This is a terminal state. Contact support to see if we can help you.
     Failed,
+
+    /// The top-up has succeeded.
+    ///
+    /// The account has been credited.
+    ///
+    /// This is a terminal state.
+    Paid,
+
+    /// A payment is detected but it isn't sufficient.
+    ///
+    /// This is a terminal state. Contact support to see if we can help you.
+    PartiallyPaid,
+
+    /// Base state, no activity detected.
+    Unpaid,
 }
 
+/// A Monero top-up ID
+///
+/// This is used both in the API and can be used when contacting support. This is the main payment reference and should be retained in case any issues come up.
+///
+/// The first 4 characters can be used when contacting support, the full ID must be used with the API.
 #[derive(Debug, Serialize, Deserialize, Clone)]
 pub struct MoneroTopUpId(pub String);
 

src/cmd/monero/create.rs

@@ -12,7 +12,16 @@ pub struct MoneroTopUpInfo {
 
 #[derive(Debug, Serialize, Deserialize, Clone)]
 pub struct CreateMoneroTopUp {
+    /// The amount of months to purchase.
+    ///
+    /// This must be at least 3 and an allowed value from the [`/api/prices` endpoint](crate::cmd::ListPrices).
+    ///
+    // TODO: https://linear.app/soveng/issue/OBS-3809/indicate-in-api-what-month-amounts-are-allowed-for-monero
     pub months: u16,
+
+    /// Sale ID for this price.
+    ///
+    /// If specified it *must* apply to this price or the request will be rejected with [`SaleNotFound`](crate::cmd::ApiErrorKind::SaleNotFound).
     pub sale: Option<SaleId>,
 }
 

src/doc.rs

@@ -0,0 +1,6 @@
+#![doc = include_str!("../doc/index.md")]
+
+#[doc = include_str!("../doc/auth.md")]
+pub mod auth {}
+#[doc = include_str!("../doc/payments.md")]
+pub mod payments {}

src/lib.rs

@@ -3,6 +3,8 @@ extern crate core;
 
 pub mod check;
 pub mod cmd;
+pub mod doc;
+pub mod time;
 pub mod token;
 pub mod types;
 pub mod wg_conf;