Merge pull request #94 from Sovereign-Engineering/payment-docs

Add long-form API docs.

Author: kevincox

.github/workflows/checks.yml

@@ -8,9 +8,13 @@ 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
+        uses: actions/checkout@v6
 
       - name: Build Nix
         shell: bash
@@ -20,3 +24,10 @@ jobs:
             --no-update-lock-file \
             --print-build-logs \
             --show-trace
+          nix build '.#doc' --no-update-lock-file
+
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: result/share/doc/
+      - uses: actions/deploy-pages@v5
+        if: ${{ github.ref_name == 'v0' }}

doc/account-creation.md

@@ -0,0 +1,16 @@
+# Account Creation
+
+Account creation is implicit.
+
+Follow these steps:
+
+## Generate an Account Number
+
+About account numbers: [Account Number](crate::types::AccountId)
+
+1. Generate a securely random 19-digit integer string (with leading zeros as appropriate).
+1. Calculate and append the [Verhoeff check digit](https://en.wikipedia.org/wiki/Verhoeff_algorithm).
+
+## Create the Account
+
+Use the [`AcquireToken`](crate::token::AcquireToken) call to validate the Account Number and availability of new accounts.

doc/auth.md

@@ -0,0 +1,9 @@
+# Authentication
+
+Authentication is a simple process.
+
+1. [Create an account](crate::doc::account_creation).
+2. [Exchange Account Number for an auth token](crate::token::AcquireToken).
+3. [Make requests with the auth token.](crate::token::AcquireToken2Output::auth_token)
+
+While some endpoints don't currently require auth it is recommended to provide an auth token on every request (other than the auth request itself). This may enable more favourable rate limiting, higher quality responses and avoid blocks.

doc/error.md

@@ -0,0 +1,7 @@
+# Obscura API Errors
+
+When something goes wrong the API returns an error following HTTP conventions. 4xx for client errors and 5xx for server errors.
+
+The error body will contain an [`ApiErrorBody`](crate::cmd::ApiErrorBody) structure.
+
+In general 4xx errors should not be retried without taking corrective action. 5xx errors can be retried with exponential backoff and jitter. Each error code has documentation about acceptable retry behaviour.

doc/index.md

@@ -0,0 +1,14 @@
+# 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>.

doc/payments.md

@@ -0,0 +1,50 @@
+# Payments
+
+This is a guide to how to use the Obscura API to create and fund accounts.
+
+<div class="warning">
+
+This API is only officially supported for our partners. If you are interested in partnering with Obscura please contact <support@obscura.net>.
+
+</div>
+
+## Background Information
+
+This documentation will be critical to understanding how to manage funding.
+
+- [Account Number](crate::types::AccountId)
+- [Authentication](crate::doc::auth)
+- [Errors](crate::doc::error)
+- [Making Requests](crate::doc::requests)
+
+## Example Flows
+
+These are some example flows that highlight how the API can be used for common integration patterns. The links go to reference documentation.
+
+### One-Click Top-Up
+
+If you are a crypto wallet and would like to let your user easily subscribe to Obscura the flow would look something like this:
+
+1. Request the user's Account Number.
+1. [Fetch the account info](crate::cmd::GetAccountInfo) to validate the current status. If the account is already [`active`](crate::types::AccountInfo::active) check the [`current_expiry`](crate::types::AccountInfo::current_expiry) field. If it is `None` or far in the future then inform the user about the time left and confirm they do want to top-up now.
+1. [Fetch the prices](crate::cmd::ListPrices) and ask the user to select the desired package.
+1. Generate an invoice ([Monero](crate::cmd::CreateMoneroTopUp) or [Lightning](crate::cmd::CreateLightningTopUp)) and confirm the crypto price with the user.
+1. Record the ID ([Monero](crate::cmd::MoneroTopUpInfo::id) or [Lightning](crate::cmd::LightningTopUpInfo::id)) for the user. This is their payment reference if they ever need to contact support.
+1. Pay the invoice.
+1. Poll the check status API ([Monero](crate::cmd::CheckMoneroTopUp) or [Lightning](crate::cmd::CheckLightningTopUp)).
+1. Let the user know when their account is funded.
+
+### Auto Top-up
+
+While none of the supported currencies support native subscriptions a wallet could help the user avoid forgetting to fund their account.
+
+1. Request the user's Account Number.
+1. [Fetch the account info](crate::cmd::GetAccountInfo) to validate the current status.
+	- If the account is not [`active`](crate::types::AccountInfo::active) then the user will be making the first payment to fund the account immediately.
+1. Poll the account info. Daily is a reasonable rate.
+1. Wait until [`current_expiry`](crate::types::AccountInfo::current_expiry) is soon (how soon is user preference).
+1. Notify the user that their account is expiring, or with user authorization automatically perform a top-up.
+1. [Fetch the prices](crate::cmd::ListPrices) and determine the appropriate package.
+1. Generate an invoice ([Monero](crate::cmd::CreateMoneroTopUp) or [Lightning](crate::cmd::CreateLightningTopUp)) and confirm the price is within the user's authorized parameters.
+1. Pay the invoice.
+1. Poll the check status API ([Monero](crate::cmd::CheckMoneroTopUp) or [Lightning](crate::cmd::CheckLightningTopUp)) and notify the user if the payment isn't processed in an appropriate time period.

doc/requests.md

@@ -0,0 +1,29 @@
+# Making Obscura API Requests
+
+The Obscura API is served at <https://v1.api.prod.obscura.net/api/>.
+
+## Rust Definitions
+
+The API is described via Rust types in the [obscuravpn-api](https://github.com/Sovereign-Engineering/obscuravpn-api) crate.
+
+These docs contain cross-referenced links to all API calls including the request and response types.
+
+Each API endpoint (other than [the authentication endpoint](crate::doc::auth)) implements the [`Cmd`](crate::cmd::Cmd) trait. You can find a list of all API endpoints by checking [Implementors](crate::cmd::Cmd#implementors) on that page.
+
+This trait specifies the key information of the API call.
+
+- The type `Cmd` is implemented on is the request body.
+	- For GET queries it is serialized as URL parameters.
+		- For example: [`ListPrices::code`](crate::cmd::ListPrices::code) becomes `?code=xxx`.
+	- Otherwise it is serialized as JSON and sent in the request body.
+		- For example: [`CreateLightningTopUp`](crate::cmd::CreateLightningTopUp) is sent as the request body `{"months":1}`.
+- The [`PATH`](crate::cmd::Cmd::PATH) constant indicates the URL path.
+	- For example [`GetAccountInfo`](crate::cmd::GetAccountInfo) has a `PATH` of `"account"`. Which means that the request should be made to <https://v1.api.prod.obscura.net/api/account>.
+- The [`METHOD`](crate::cmd::Cmd::METHOD) constant indicates the HTTP method to use.
+	- For example [`GetAccountInfo`](crate::cmd::GetAccountInfo) has a `METHOD` of `GET`.
+
+## Other Key Docs
+
+- [Authentication](crate::doc::auth)
+- [Errors](crate::doc::error)
+- [User-Agent Requirements](crate::doc::user_agent)

doc/user-agent.md

@@ -0,0 +1,12 @@
+# User Agent Requirements
+
+It is important for us to know who is hitting our API so that we can reach out about any concerns or in extreme cases block the requests until issues can be resolved. Having a specific User-Agent may also allow us to exclude you from wider protection measures.
+
+Your user-agent should contain the following info:
+
+1. Your identity. Preferably a URL such as `example.com`. Allows us to get in touch.
+1. A version number that increases. This allows us to block or specially handle old clients without blocking fixed clients. Ideally this number increases as you make releases, but it is also fine to just hardcode a number and increment it whenever you make important fixes.
+
+For example: `example.com/1.23` is a great `User-Agent` if you own `example.com`.
+
+**DO NOT** put end-user info into the User-Agent as it will be recorded for a short period of time for operational reasons.

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/account/delete.rs

@@ -11,5 +11,5 @@ impl Cmd for DeleteAccount {
     type Output = DeleteAccountOutput;
 
     const METHOD: http::Method = http::Method::DELETE;
-    const PATH: &'static str = super::PATH;
+    const PATH: &'static str = "account";
 }