@omelhorsite/sdk 0.1.0

package/dist/types/local/password.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Password and passphrase generation. Local, offline, no credential.
+ *
+ * Randomness comes from `crypto.getRandomValues`, which every target runtime
+ * has (browser, Worker, Bun, Node 19+). `Math.random` is NEVER acceptable here
+ * and no fallback to it exists: if the platform has no WebCrypto, these
+ * functions throw rather than quietly producing a guessable string.
+ *
+ * Selecting a character from an alphabet must use rejection sampling, not
+ * `random % alphabet.length`: the modulo skews the distribution towards the
+ * first `2^n mod len` characters, which is exactly the bias an attacker's
+ * dictionary is built around.
+ */
+export { EFF_LONG_WORDLIST } from "./wordlist";
+/** Which character classes a generated password may draw from. */
+export interface PasswordAlphabet {
+    /** `a-z`. Defaults to true. */
+    readonly lowercase?: boolean;
+    /** `A-Z`. Defaults to true. */
+    readonly uppercase?: boolean;
+    /** `0-9`. Defaults to true. */
+    readonly digits?: boolean;
+    /** Punctuation. Defaults to true. See {@link SYMBOLS} for what is in it. */
+    readonly symbols?: boolean;
+    /**
+     * Drop characters that are hard to tell apart when read aloud or off a
+     * screen: `0O1lI|`. Defaults to false. Costs about 0.4 bits per character at
+     * the full alphabet, which four extra characters of length more than repay.
+     */
+    readonly avoidAmbiguous?: boolean;
+    /**
+     * Extra characters to allow, beyond the classes above. Duplicates - of each
+     * other or of a class already enabled - are collapsed, so a character cannot
+     * be listed twice and skew the draw towards itself.
+     */
+    readonly extra?: string;
+}
+/** Options for {@link generatePassword}. */
+export interface GeneratePasswordOptions extends PasswordAlphabet {
+    /** Characters to produce. Defaults to 20. */
+    readonly length?: number;
+    /**
+     * Guarantee at least one character from every enabled class.
+     *
+     * Defaults to true because password policies demand it. It costs a little
+     * entropy: the result is a uniform draw from a smaller set, not from the
+     * full alphabet. {@link passwordEntropyBits} accounts for the alphabet only,
+     * so it slightly overstates a password generated this way.
+     *
+     * `extra` is not a class and is never forced.
+     */
+    readonly requireEachClass?: boolean;
+}
+/** Options for {@link generatePassphrase}. */
+export interface GeneratePassphraseOptions {
+    /** Words to join. Defaults to 5, which is the point where these get strong. */
+    readonly words?: number;
+    /** Separator between words. Defaults to `"-"`. */
+    readonly separator?: string;
+    /** Capitalise the first letter of each word. Defaults to false. */
+    readonly capitalize?: boolean;
+    /**
+     * Append a random digit to one of the words, for policies that demand one.
+     * Worth about 3.3 bits plus the choice of which word; it is a compliance
+     * feature, not a security one.
+     */
+    readonly includeNumber?: boolean;
+    /**
+     * Word list to draw from. Defaults to {@link EFF_LONG_WORDLIST}. Supply your
+     * own to generate in another language - the strength then follows YOUR list's
+     * size, so a 200-word list makes a weak passphrase however many words you ask
+     * for. Duplicate entries are not removed and would bias the draw.
+     */
+    readonly wordlist?: readonly string[];
+}
+/** How strong a password looks, for a meter in a UI. */
+export interface PasswordStrength {
+    /** Shannon entropy of the generator that could have produced it, in bits. */
+    readonly bits: number;
+    /** Coarse bucket derived from `bits`, for colouring a bar. */
+    readonly label: "very-weak" | "weak" | "fair" | "strong" | "very-strong";
+    /** Which classes appear in the string. */
+    readonly classes: {
+        readonly lowercase: boolean;
+        readonly uppercase: boolean;
+        readonly digits: boolean;
+        /** True for any character that is not an ASCII letter or digit, accents included. */
+        readonly symbols: boolean;
+    };
+    /** Distinct characters used. A long password of two characters is not long. */
+    readonly uniqueChars: number;
+}
+/**
+ * Generates a random password.
+ *
+ * ```ts
+ * generatePassword();                                  // 20 chars, all classes
+ * generatePassword({ length: 32, symbols: false });     // alphanumeric only
+ * generatePassword({ length: 16, avoidAmbiguous: true }); // safe to read aloud
+ * ```
+ *
+ * @throws {RangeError} when `length` is not a positive integer, when the
+ *   options leave no characters to draw from, or when `requireEachClass` needs
+ *   more characters than `length` allows.
+ * @throws {Error} when the runtime has no `crypto.getRandomValues`.
+ */
+export declare function generatePassword(options?: GeneratePasswordOptions): string;
+/**
+ * Generates a passphrase from a word list.
+ *
+ * ```ts
+ * generatePassphrase();                                // "cactus-mural-...-..."
+ * generatePassphrase({ words: 7, separator: " " });
+ * ```
+ *
+ * Words are drawn WITH replacement, so a word can repeat. That is deliberate:
+ * drawing without replacement would make each word depend on the ones before
+ * it and quietly lower the entropy of the phrase.
+ *
+ * @throws {RangeError} when `words` is not a positive integer or the word list
+ *   is empty.
+ * @throws {Error} when the runtime has no `crypto.getRandomValues`.
+ */
+export declare function generatePassphrase(options?: GeneratePassphraseOptions): string;
+/**
+ * Describes a password's strength.
+ *
+ * This is an ENTROPY ESTIMATE of the alphabet, not a crack-time prediction: it
+ * cannot tell that `"Password123!"` is in every dictionary on earth, and it
+ * will happily call it fair. Present it as a hint, never as a verdict, and
+ * never as a gate on what a user may choose.
+ *
+ * A passphrase is measured by its characters, not by its words, so
+ * {@link generatePassphrase} output reads as far stronger here than its real
+ * per-word entropy. Use `words * log2(wordlist.length)` for those instead.
+ */
+export declare function passwordStrength(password: string): PasswordStrength;
+/**
+ * Bits of entropy in `length` characters drawn uniformly from an alphabet of
+ * `alphabetSize`: `length * log2(alphabetSize)`.
+ *
+ * Returns `0` rather than throwing for a degenerate input (empty password, an
+ * alphabet of one character), because a one-character alphabet genuinely
+ * carries no information and a meter should show zero, not blow up.
+ */
+export declare function passwordEntropyBits(length: number, alphabetSize: number): number;
+/**
+ * Builds the character pool a {@link PasswordAlphabet} describes.
+ *
+ * Exported so a caller can show the user exactly what the generator will draw
+ * from, and so the tests can assert the ambiguity filter.
+ *
+ * Returns an empty string when the options enable nothing - it describes, it
+ * does not validate. {@link generatePassword} is where that becomes an error.
+ */
+export declare function buildAlphabet(options?: PasswordAlphabet): string;
+/**
+ * Uniform random integer in `[0, max)` from `crypto.getRandomValues`, using
+ * rejection sampling so the distribution has no modulo bias.
+ *
+ * The loop is unbounded on purpose. It rejects at most `max / 2^32` of its
+ * draws, which for every alphabet in this module is far below one in a
+ * thousand, so it terminates immediately in practice and stays correct rather
+ * than falling back to a biased answer after N tries.
+ *
+ * @throws {RangeError} when `max` is not an integer in `[1, 2^32]`.
+ * @throws {Error} when the runtime has no `crypto.getRandomValues`.
+ */
+export declare function randomInt(max: number): number;

package/dist/types/local/qr.d.ts

@@ -0,0 +1,127 @@
+/**
+ * QR code encoding. Local, offline, no credential.
+ *
+ * This module encodes a payload into a module matrix and renders it as SVG.
+ * That is the whole isolate-safe surface: SVG is text, so it works in a Worker,
+ * in the CLI and in a browser alike.
+ *
+ * Raster output (PNG, JPEG) is deliberately NOT here. It needs a canvas or an
+ * image encoder, neither of which every target runtime has, and the host
+ * already knows which it owns. Hand the host the matrix or the SVG and let it
+ * rasterise.
+ *
+ * Encoding a QR symbol correctly (mode selection, Reed-Solomon over GF(256),
+ * mask scoring against the four penalty rules) is not something to hand-roll,
+ * so the encoder is `uqr`: MIT, zero runtime dependencies, pure TypeScript, and
+ * it imports no `node:*` builtin and touches no DOM - which is why it, rather
+ * than the older `qrcode-generator`, is the one dependency the core has. The
+ * rendering below is ours, because `uqr`'s own `renderSVG` emits one `<rect>`
+ * per module and offers no margin, shape or transparency control.
+ *
+ * Note the split of responsibilities with `oms.dynamicQrs`: this module draws
+ * the image, that namespace manages the redirect the image points at. For a
+ * dynamic code, encode `oms.dynamicQrs.publicUrl(qr)` here - never `qr.url`, or
+ * the whole point of a re-pointable code is lost.
+ */
+/** Error-correction level. Higher survives more damage and more logo. */
+export type QrErrorCorrection = "L" | "M" | "Q" | "H";
+/** Options for {@link encodeQr}. */
+export interface EncodeQrOptions {
+    /** Defaults to `"M"`. Use `"H"` when a logo covers the middle. */
+    readonly ecc?: QrErrorCorrection;
+    /**
+     * Force a symbol version (1 to 40). Omit to let the encoder pick the
+     * smallest that fits, which is almost always what you want. Forcing a
+     * version that the payload does not fit in is a {@link RangeError}, not a
+     * silent upgrade.
+     */
+    readonly version?: number;
+}
+/** An encoded QR symbol, as a square grid of modules. */
+export interface QrMatrix {
+    /** Modules per side, quiet zone excluded. `21 + 4 * (version - 1)`. */
+    readonly size: number;
+    /**
+     * Row-major, `size * size` entries. `true` is a dark module.
+     *
+     * Flat rather than nested so it can be walked without allocating a row array
+     * per line; index `y * size + x`.
+     */
+    readonly modules: ReadonlyArray<boolean>;
+    readonly version: number;
+    readonly ecc: QrErrorCorrection;
+}
+/** Options for {@link qrToSvg}. */
+export interface QrSvgOptions {
+    /**
+     * Quiet zone in modules. Defaults to 4, which is what the specification
+     * requires; scanners genuinely fail without it.
+     */
+    readonly margin?: number;
+    /** Dark module colour. Defaults to `"#000000"`. */
+    readonly color?: string;
+    /**
+     * Light module colour. Defaults to `"#ffffff"`. Pass `"transparent"` for a
+     * background-free symbol; contrast is then the caller's problem, and a dark
+     * symbol on a dark page does not scan.
+     */
+    readonly background?: string;
+    /**
+     * Pixel size of the `width`/`height` attributes. Omit to emit a `viewBox`
+     * only, which scales to whatever box it is dropped into.
+     */
+    readonly size?: number;
+    /**
+     * Module shape. `"square"` is the safe default; `"rounded"` and `"dots"`
+     * shrink the effective dark area and can push a low-ECC symbol below what a
+     * phone camera will read. Raise `ecc` when you use them.
+     */
+    readonly shape?: "square" | "rounded" | "dots";
+}
+/**
+ * Encodes a payload into a QR matrix.
+ *
+ * ```ts
+ * const qr = encodeQr("https://omelhor.site/abc");
+ * qr.size;                       // 25 for a version-2 symbol
+ * qr.modules[y * qr.size + x];   // true where the module is dark
+ * ```
+ *
+ * The matrix carries NO quiet zone: {@link qrToSvg} adds one, and a caller
+ * rendering the matrix by hand must add its own or the symbol will not scan.
+ *
+ * @param data The payload. A URL, plain text, a `WIFI:` string, whatever. The
+ *   encoder picks the mode (numeric, alphanumeric, byte) that fits it best.
+ * @throws {RangeError} when the payload does not fit at the requested version
+ *   and error-correction level, or when `version` is outside 1-40.
+ */
+export declare function encodeQr(data: string, options?: EncodeQrOptions): QrMatrix;
+/**
+ * Renders a matrix, or a payload, as an SVG document string.
+ *
+ * ```ts
+ * const svg = qrToSvg("https://omelhor.site/abc", { ecc: "H", size: 512 });
+ * ```
+ *
+ * Passing a payload string encodes it first, so {@link EncodeQrOptions} is
+ * accepted here too; passing an already-encoded {@link QrMatrix} ignores those
+ * fields, because the symbol is already fixed.
+ *
+ * Colours are escaped before they reach an attribute. They routinely come from
+ * a `DynamicQrSettings` bag that a user typed, and an unescaped `"` there would
+ * let that user close the attribute and write markup of their own into a page
+ * that inlines the result.
+ *
+ * @throws {RangeError} propagated from {@link encodeQr}, or when `margin` or
+ *   `size` is negative.
+ */
+export declare function qrToSvg(input: QrMatrix | string, options?: QrSvgOptions & EncodeQrOptions): string;
+/**
+ * Same as {@link qrToSvg}, wrapped in a `data:image/svg+xml` URI ready for an
+ * `<img src>` or a CSS background.
+ *
+ * Percent-encoded rather than base64: `btoa` is not on every runtime this core
+ * targets, the encoding survives being pasted into a stylesheet, and it stays
+ * readable in a diff.
+ */
+export declare function qrToDataUri(input: QrMatrix | string, options?: QrSvgOptions & EncodeQrOptions): string;

package/dist/types/local/wordlist.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The word list {@link generatePassphrase} draws from by default.
+ *
+ * This is the EFF "long" list: 7776 words (6^5, one per five-dice roll),
+ * published for exactly this purpose. Every entry is lowercase, at least three
+ * characters, and no entry shares its first three characters with another,
+ * which is what makes a passphrase unambiguous to type and to read back over a
+ * phone. Four entries carry a hyphen ("drop-down", "felt-tip", "t-shirt",
+ * "yo-yo"), so do not assume the separator cannot appear inside a word.
+ *
+ * 7776 words is log2(7776) = 12.925 bits per word, so the default five-word
+ * passphrase carries about 64.6 bits - stronger than a ten-character random
+ * password over the full printable alphabet, and far easier to remember.
+ *
+ * Source: https://www.eff.org/files/2016/07/18/eff_large_wordlist.txt
+ * License: CC-BY-3.0 (Electronic Frontier Foundation).
+ *
+ * It lives in its own module because it is 60 KB of data and it would bury the
+ * few dozen lines of actual logic in `password.ts`. Nothing here is
+ * platform-specific, so it is isolate-safe like the rest of `local/`.
+ *
+ * This file is DATA, copied verbatim from `frontend/lib/crypto/wordlist.ts` -
+ * the same list the web app's vault draws from. Keep the two in step rather
+ * than editing either by hand.
+ */
+export declare const EFF_LONG_WORDLIST: readonly string[];

package/dist/types/resources/account.d.ts

@@ -0,0 +1,296 @@
+/**
+ * The `account` namespace: the signed-in user, other users' public profiles,
+ * the usage report behind the quota bars, and the sessions a credential can
+ * see.
+ *
+ * `GET /account` is the canonical "who am I" call and the cheapest way to check
+ * that a stored credential is still alive.
+ */
+import { type ApiClient, Resource } from "../http";
+import type { BaseRecord, FileInput, Id, Paginated, PageParams, RequestOptions, Timestamp } from "../types";
+/**
+ * A user as the API renders them.
+ *
+ * Most fields are conditional: the blueprint hides `email` and `gender` unless
+ * they are public or you are the owner or an administrator, and hides
+ * `group`, `last_seen_at`, `sessions_count` and `deactivated_at` from everyone
+ * but an administrator. An absent key therefore means "not visible to you",
+ * never "empty".
+ */
+export interface User extends BaseRecord {
+    /** Stable identifier. This is the OIDC `sub` claim. Never key on the handle. */
+    readonly id: Id;
+    /** Login name. Mutable: display it, do not store it as a foreign key. */
+    readonly handle: string;
+    readonly name?: string | null;
+    readonly bio?: string | null;
+    /** ISO 3166-1 alpha-2, as the user set it. */
+    readonly country_code?: string | null;
+    readonly email_is_public?: boolean;
+    readonly gender_is_public?: boolean;
+    readonly library_public?: boolean;
+    readonly library_name?: string | null;
+    readonly library_description?: string | null;
+    /** Visible when public, or to the owner and administrators. */
+    readonly email?: string | null;
+    /** Visible when public, or to the owner and administrators. */
+    readonly gender?: string | null;
+    /** Privilege group, e.g. `"admin"`. Owner and administrators only. */
+    readonly group?: string | null;
+    /** Owner and administrators only. */
+    readonly allowed_to_use_spotify?: boolean;
+    /** Owner and administrators only: whether friends see this user's playback. */
+    readonly share_listening?: boolean;
+    /** Administrators only. */
+    readonly last_seen_at?: Timestamp | null;
+    /** Administrators only. */
+    readonly sessions_count?: number;
+    /** Administrators only. Non-null once the account is deactivated. */
+    readonly deactivated_at?: Timestamp | null;
+}
+/**
+ * The `:profile` view: everything in {@link User} plus the social counters.
+ * Returned by `profile`, `byHandle`, `follow` and `unfollow`.
+ */
+export interface UserProfile extends User {
+    readonly followers_count: number;
+    readonly following_count: number;
+    /** Whether the CALLER follows this user. `false` for an anonymous caller. */
+    readonly is_following: boolean;
+    /** `created_at` again, as an explicit ISO-8601 string. */
+    readonly member_since: Timestamp;
+}
+/** One hit from {@link AccountNamespace.search}. Deliberately three fields. */
+export interface UserSearchResult {
+    readonly id: Id;
+    readonly handle: string;
+    readonly name?: string | null;
+}
+/**
+ * Fields a user may change on their own account.
+ *
+ * Anything not listed here is dropped in silence and the call still answers
+ * 200, so compare the returned {@link User} rather than trusting the status.
+ * The avatar is not here: it is multipart, through
+ * {@link AccountNamespace.updatePicture}.
+ */
+export interface UpdateAccountInput {
+    readonly handle?: string;
+    readonly name?: string;
+    readonly bio?: string;
+    readonly countryCode?: string;
+    readonly emailIsPublic?: boolean;
+    readonly genderIsPublic?: boolean;
+    readonly gender?: string;
+    readonly libraryPublic?: boolean;
+    readonly libraryName?: string;
+    readonly libraryDescription?: string;
+    /** Whether friends may see what you are listening to. */
+    readonly shareListening?: boolean;
+}
+/** One extension bucket of {@link AccountStorageUsage.top_extensions}. */
+export interface AccountExtensionUsage {
+    /** Lowercased extension with no dot, or `""` for a file that has none. */
+    readonly ext: string;
+    readonly count: number;
+    readonly bytes: number;
+}
+/** One row of {@link AccountStorageUsage.biggest_files}. */
+export interface AccountBiggestFile {
+    readonly id: Id;
+    readonly name: string;
+    readonly size: number;
+    readonly parent_id: Id | null;
+}
+/** One row of {@link AccountStorageUsage.biggest_folders}. */
+export interface AccountBiggestFolder {
+    readonly id: Id;
+    readonly name: string;
+    /** Sum of the file descendants, computed live. */
+    readonly size: number;
+}
+/** The storage section of {@link AccountUsage}. */
+export interface AccountStorageUsage {
+    readonly used_bytes: number;
+    /** The account's own ceiling, not the global default. */
+    readonly max_bytes: number;
+    readonly file_count: number;
+    readonly directory_count: number;
+    /** Up to six, biggest first. */
+    readonly top_extensions: AccountExtensionUsage[];
+    /** Up to five, biggest first. */
+    readonly biggest_files: AccountBiggestFile[];
+    /** Up to five direct children of the home folder, biggest first. */
+    readonly biggest_folders: AccountBiggestFolder[];
+}
+/**
+ * `GET /account/usage`: what the account has spent, per area.
+ *
+ * This is a bespoke report, not the daily tool quotas - each metered tool
+ * reports its own ceiling through its `quota()` call. There is also a row
+ * ceiling (250 000 nodes) that this report does not carry.
+ */
+export interface AccountUsage {
+    readonly user: {
+        readonly id: Id;
+        readonly handle: string;
+        readonly name: string | null;
+    };
+    readonly storage: AccountStorageUsage;
+    readonly music: {
+        readonly songs: number;
+        readonly playlists: number;
+        readonly play_events_total: number;
+        readonly play_events_30d: number;
+    };
+    readonly tickets: {
+        readonly open: number;
+        readonly closed: number;
+    };
+    readonly messages: {
+        readonly sent_30d: number;
+        readonly received_30d: number;
+        readonly unread: number;
+    };
+    readonly short_links: {
+        readonly total: number;
+        readonly total_clicks: number;
+    };
+}
+/**
+ * One sign-in. The token itself is never rendered here: it is handed out once,
+ * at `POST /sessions`, and never again.
+ */
+export interface AccountSession extends BaseRecord {
+    readonly user_id: Id;
+    readonly ip_address?: string | null;
+    readonly user_agent?: string | null;
+    /** Caller-set label, e.g. `"laptop"`. */
+    readonly name?: string | null;
+    /** Caller-set kind, e.g. `"cli"`. `"teapot"` suppresses login alerts. */
+    readonly device_type?: string | null;
+    readonly description?: string | null;
+    /** Rewritten on every authenticated request this session makes. */
+    readonly last_used_at?: Timestamp | null;
+    /** The owner, rendered inline. */
+    readonly user?: User;
+}
+/** Filters for {@link AccountSessionsNamespace.list}. */
+export interface ListAccountSessionsParams extends PageParams {
+    /** Administrators only: someone else's sessions. */
+    readonly userId?: Id;
+}
+/** Fields that can change on a session after it exists. */
+export interface UpdateAccountSessionInput {
+    readonly name?: string;
+    /** `"teapot"` silences the login and activity alerts for this session. */
+    readonly deviceType?: string;
+    readonly description?: string;
+}
+/**
+ * Sessions of the current credential, reachable as `oms.account.sessions`.
+ *
+ * A session is the legacy credential: an opaque UUID with no scopes and no
+ * expiry. Every login mints a new row, so a client that signs in on each
+ * invocation fills this list up; persist the token instead.
+ */
+export declare class AccountSessionsNamespace extends Resource {
+    /**
+     * `GET /sessions` - your sessions, one row per sign-in. An administrator
+     * sees everyone's and can narrow with `userId`.
+     */
+    list(params?: ListAccountSessionsParams, options?: RequestOptions): Promise<Paginated<AccountSession>>;
+    /** `GET /sessions/mine` - the session the current credential resolves to. */
+    current(options?: RequestOptions): Promise<AccountSession>;
+    /**
+     * `PATCH /sessions/:id` - renames a session, or relabels its device.
+     *
+     * This is the only session call that honours the `:id` in the path.
+     */
+    update(id: Id, input: UpdateAccountSessionInput, options?: RequestOptions): Promise<AccountSession>;
+    /**
+     * `DELETE /sessions/:id` - ends the session THIS credential is using.
+     *
+     * There is no argument on purpose. The endpoint never reads the `:id` in the
+     * path: it destroys `Current.session`, whatever id you send. Revoking
+     * another device's session is not possible through the API today, and a
+     * method that appeared to do it would silently log the caller out instead.
+     *
+     * After this resolves the credential is dead; build a new client with a new
+     * token rather than reusing this one.
+     *
+     * Costs a `GET /sessions/mine` first. The real id is sent even though the
+     * endpoint ignores it, so the call stays correct if that is ever fixed.
+     */
+    revokeCurrent(options?: RequestOptions): Promise<void>;
+}
+/** The `account` namespace, reachable as `oms.account`. */
+export declare class AccountNamespace extends Resource {
+    /** Sessions: listing, relabelling, and ending the current one. */
+    readonly sessions: AccountSessionsNamespace;
+    constructor(http: ApiClient);
+    /**
+     * `GET /account` - the user the current credential belongs to.
+     *
+     * @throws {OmsAuthError} 401 when the credential is missing or dead.
+     */
+    me(options?: RequestOptions): Promise<User>;
+    /**
+     * `PATCH /users/:id` against your own id. Pass only the fields you are
+     * changing; the API leaves the rest alone.
+     *
+     * Costs an extra `GET /account` first, because the endpoint is addressed by
+     * id and the SDK holds no identity of its own. Unknown fields are dropped in
+     * silence, so read the returned {@link User} to see what actually changed.
+     */
+    update(input: UpdateAccountInput, options?: RequestOptions): Promise<User>;
+    /**
+     * `PATCH /users/:id` with a multipart body - replaces the avatar.
+     *
+     * The image is re-encoded server-side and capped at 1024px, so send the
+     * original rather than a thumbnail. Costs an extra `GET /account`, same as
+     * {@link update}.
+     */
+    updatePicture(picture: FileInput, options?: RequestOptions): Promise<User>;
+    /**
+     * `GET /account/usage` - consumption per area, for the bars the CLI prints
+     * before starting an expensive job.
+     */
+    usage(options?: RequestOptions): Promise<AccountUsage>;
+    /** `GET /users/:id` - another user, by stable id. Requires a credential. */
+    get(id: Id, options?: RequestOptions): Promise<User>;
+    /**
+     * `GET /users/by_handle/:handle` - the public profile of a handle. Works
+     * anonymously. Handles are mutable, so resolve once and keep the id.
+     */
+    byHandle(handle: string, options?: RequestOptions): Promise<UserProfile>;
+    /**
+     * `GET /users/:id/profile` - the public profile with follow counters. Works
+     * anonymously, and accepts a handle in place of an id.
+     */
+    profile(id: Id, options?: RequestOptions): Promise<UserProfile>;
+    /**
+     * `GET /users/search` - handle and name substring search, for a picker.
+     *
+     * Answers an empty list for a query under two characters, and never more
+     * than eight hits: it is a lookup, not an enumeration, and there is no
+     * paging. Throttled to 30 a minute per IP even when authenticated.
+     */
+    search(query: string, options?: RequestOptions): Promise<UserSearchResult[]>;
+    /**
+     * `GET /users/:id/picture` - the avatar bytes.
+     *
+     * Answers 302 towards object storage and `fetch` follows it; the platform
+     * drops `Authorization` on the cross-origin hop, so the credential never
+     * reaches the storage host. Answers 404 when the user has no avatar.
+     */
+    picture(id: Id, options?: RequestOptions): Promise<Blob>;
+    /** `POST /users/:id/follow` - returns the followed user's updated profile. */
+    follow(id: Id, options?: RequestOptions): Promise<UserProfile>;
+    /**
+     * `DELETE /users/:id/follow` - returns the unfollowed user's updated
+     * profile. Idempotent: unfollowing someone you do not follow still answers
+     * 200.
+     */
+    unfollow(id: Id, options?: RequestOptions): Promise<UserProfile>;
+}