@omelhorsite/sdk 0.1.0

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

@@ -0,0 +1,249 @@
+/**
+ * The `linkTrees` namespace: link-in-bio pages, their click statistics and the
+ * optional CV attached to one.
+ *
+ * A tree is public at `by_slug/:slug`, and the slug is the identity a visitor
+ * sees. Owner operations go through the record id, exactly like every other
+ * resource. The slug is also the endpoint of a paired short link, so changing
+ * it renames that link inside the same transaction and the old URL stops
+ * resolving.
+ */
+import { Resource } from "../http";
+import type { BaseRecord, FileInput, Id, RequestOptions, Timestamp } from "../types";
+/** Longest a slug may be. The shortest is 2. */
+export declare const LINK_TREE_SLUG_MAX_LENGTH = 63;
+/** Most items one tree may carry. */
+export declare const LINK_TREE_MAX_ITEMS = 30;
+/** Ceiling on the attached CV, which must also be a PDF. */
+export declare const LINK_TREE_CV_MAX_BYTES: number;
+/**
+ * One entry on a link tree.
+ *
+ * `url` must carry an `http`, `https`, `mailto`, `tel` or `sms` scheme; a bare
+ * domain is rejected by the model, not silently fixed.
+ */
+export interface LinkTreeItem {
+    /** Stable within the tree, and the key click tracking is filed under. The
+     * server mints a UUID when you leave it out, so read the tree back before
+     * calling {@link LinkTreesNamespace.trackClick}. */
+    readonly id?: string;
+    /** Up to 80 characters. */
+    readonly label: string;
+    /** Up to 1024 characters, with a scheme. */
+    readonly url: string;
+    /** Icon slug the renderer resolves. Up to 40 characters. */
+    readonly icon?: string;
+    /** Up to 200 characters. */
+    readonly description?: string;
+    /** `data:image/...` under 80 KB, for a custom icon. */
+    readonly icon_image?: string;
+}
+/**
+ * Styling of a link tree. Colours must be `#RRGGBB` and images must be
+ * `data:image/` URIs; anything else in here is dropped in silence on write.
+ */
+export interface LinkTreeTheme {
+    readonly bg_color?: string;
+    readonly text_color?: string;
+    readonly button_bg?: string;
+    readonly button_text?: string;
+    readonly button_border_color?: string;
+    readonly button_style?: "solid" | "outline" | "rounded" | "square";
+    /** Clamped to 0..8. */
+    readonly button_border_width?: number;
+    /** `data:image/...` under 1.5 MB, or `null` to clear. */
+    readonly bg_image?: string | null;
+    /** `data:image/...` under 1 MB, or `null` to clear. */
+    readonly banner_image?: string | null;
+}
+/** A link-in-bio page, owner view. */
+export interface LinkTree extends BaseRecord {
+    readonly user_id: Id;
+    /** Public path segment. Lowercase letters, digits and dashes. */
+    readonly slug: string;
+    readonly title: string;
+    readonly bio?: string | null;
+    /** The avatar, inline as a `data:image/` URI rather than a URL. */
+    readonly avatar_data_url?: string | null;
+    readonly items: LinkTreeItem[];
+    readonly theme: LinkTreeTheme;
+    /** Click counters keyed by {@link LinkTreeItem.id}. */
+    readonly clicks_by_item: Record<string, number>;
+    /** Absolute URL that downloads the CV, or `null` when none is attached. */
+    readonly cv_url: string | null;
+    readonly cv_filename: string | null;
+    /** The shareable short URL. */
+    readonly public_url: string;
+    /** Endpoint of the paired short link. Always equal to `slug`. */
+    readonly short_link_endpoint: string;
+    readonly short_link_namespace: string;
+}
+/**
+ * The visitor's view: the same page with the owner-only fields removed. Note
+ * that it carries no timestamps, so it is NOT a {@link LinkTree}.
+ */
+export interface PublicLinkTree {
+    readonly id: Id;
+    readonly slug: string;
+    readonly title: string;
+    readonly bio?: string | null;
+    readonly avatar_data_url?: string | null;
+    readonly items: LinkTreeItem[];
+    readonly theme: LinkTreeTheme;
+    readonly cv_url: string | null;
+    readonly cv_filename: string | null;
+}
+/** Arguments for creating a link tree. */
+export interface CreateLinkTreeInput {
+    /**
+     * 2 to {@link LINK_TREE_SLUG_MAX_LENGTH} characters of `[a-z0-9-]`, starting
+     * and ending alphanumeric, and never one of `new edit admin api root login
+     * logout signup signin manage`.
+     */
+    readonly slug: string;
+    /** Required: the model refuses a blank title. Up to 80 characters. */
+    readonly title: string;
+    /** Up to 280 characters. */
+    readonly bio?: string;
+    /** `data:image/...` under 500 KB. Build one with `dataUrlFromFile`. */
+    readonly avatarDataUrl?: string;
+    readonly items?: LinkTreeItem[];
+    readonly theme?: LinkTreeTheme;
+}
+/**
+ * Fields that can change afterwards. A true PATCH: only the keys you pass are
+ * touched.
+ *
+ * `items` REPLACES the whole list - there is no per-item endpoint, so read,
+ * edit the array, write it back, and accept that two concurrent editors
+ * clobber each other. Keep each item's `id` when you do, or the click counters
+ * in `clicks_by_item` stop lining up with anything.
+ */
+export interface UpdateLinkTreeInput {
+    /** Renames the paired short link; the old public URL stops resolving. */
+    readonly slug?: string;
+    readonly title?: string;
+    readonly bio?: string;
+    readonly avatarDataUrl?: string | null;
+    readonly items?: LinkTreeItem[];
+    readonly theme?: LinkTreeTheme;
+}
+/** One day of the click histogram. Always 30 entries, oldest first. */
+export interface LinkTreeDailyStat {
+    /** `YYYY-MM-DD`. */
+    readonly date: string;
+    readonly count: number;
+}
+/** One row of {@link LinkTreeStats.top_countries}. */
+export interface LinkTreeCountryStat {
+    readonly country: string;
+    readonly count: number;
+}
+/** One row of {@link LinkTreeStats.top_devices}. */
+export interface LinkTreeDeviceStat {
+    readonly device_name: string;
+    readonly count: number;
+}
+/**
+ * `GET /link_trees/:id/stats`.
+ *
+ * The totals and the histogram come from the paired short link, so they count
+ * visits to the PAGE. `clicks_by_item` comes from the tree itself and counts
+ * clicks on the links, so the two are not comparable and will not add up.
+ */
+export interface LinkTreeStats {
+    readonly total_clicks: number;
+    readonly last_click_at: Timestamp | null;
+    /** The last 30 days, one bucket per day. */
+    readonly clicks_daily: LinkTreeDailyStat[];
+    /** Up to ten, biggest first. */
+    readonly top_countries: LinkTreeCountryStat[];
+    /** Up to five, biggest first. */
+    readonly top_devices: LinkTreeDeviceStat[];
+    /** Clicks keyed by {@link LinkTreeItem.id}. */
+    readonly clicks_by_item: Record<string, number>;
+}
+/**
+ * `GET /link_trees/slug_availability`. Read `available`; `suggestions` is only
+ * present when the slug is well formed but taken.
+ */
+export interface LinkTreeSlugAvailability {
+    readonly slug: string;
+    readonly valid: boolean;
+    readonly available: boolean;
+    /** `"invalid"` for the format, `"reserved"` for the blocklist. */
+    readonly reason?: string;
+    readonly suggestions?: string[];
+}
+/** The `linkTrees` namespace, reachable as `oms.linkTrees`. */
+export declare class LinkTreesNamespace extends Resource {
+    /**
+     * `GET /link_trees` - the pages you own, most recently edited first.
+     *
+     * Not paginated and not filterable: the endpoint takes no modifiers and
+     * answers with the whole set.
+     */
+    list(options?: RequestOptions): Promise<LinkTree[]>;
+    /** `GET /link_trees/:id` - owner view, with the click counters. */
+    get(id: Id, options?: RequestOptions): Promise<LinkTree>;
+    /**
+     * `GET /link_trees/by_slug/:slug` - the visitor's view. No credential
+     * needed, and unlike the forms equivalent it counts nothing.
+     */
+    getPublic(slug: string, options?: RequestOptions): Promise<PublicLinkTree>;
+    /**
+     * `GET /link_trees/slug_availability` - whether a slug is free, with
+     * alternatives when it is not. The server is still the authority: create can
+     * lose a race and answer 400.
+     */
+    slugAvailability(slug: string, options?: RequestOptions): Promise<LinkTreeSlugAvailability>;
+    /** {@link slugAvailability} reduced to its verdict. */
+    slugAvailable(slug: string, options?: RequestOptions): Promise<boolean>;
+    /**
+     * `POST /link_trees` - creates the page and reserves its slug in one
+     * transaction.
+     *
+     * Not retried by default: a replayed create would fail on the slug being
+     * taken by its own first attempt.
+     */
+    create(input: CreateLinkTreeInput, options?: RequestOptions): Promise<LinkTree>;
+    /**
+     * `PATCH /link_trees/:id`. Only the keys you pass are touched. See the note
+     * on {@link UpdateLinkTreeInput.items}: the list is replaced wholesale.
+     */
+    update(id: Id, input: UpdateLinkTreeInput, options?: RequestOptions): Promise<LinkTree>;
+    /** `DELETE /link_trees/:id`. Takes the paired short link with it. */
+    delete(id: Id, options?: RequestOptions): Promise<void>;
+    /** `GET /link_trees/:id/stats` - page visits, and the per-item breakdown. */
+    stats(id: Id, options?: RequestOptions): Promise<LinkTreeStats>;
+    /**
+     * `PATCH /link_trees/:id/upload_cv` - attaches a PDF visitors can download.
+     *
+     * Multipart, and PDF only: another content type or anything over
+     * {@link LINK_TREE_CV_MAX_BYTES} is rejected with 400. Replaces whatever was
+     * attached before.
+     */
+    uploadCv(id: Id, file: FileInput, options?: RequestOptions): Promise<LinkTree>;
+    /** `DELETE /link_trees/:id/remove_cv` - returns the updated tree, not 204. */
+    removeCv(id: Id, options?: RequestOptions): Promise<LinkTree>;
+    /**
+     * `GET /link_trees/by_slug/:slug/cv` - downloads the attached CV.
+     *
+     * Served inline by Rails rather than redirected, so the bytes come through
+     * the API. The filename is on the record, as `cv_filename`.
+     */
+    downloadCv(slug: string, options?: RequestOptions): Promise<Blob>;
+    /**
+     * `POST /link_trees/by_slug/:slug/track_click` - records a click on one
+     * item.
+     *
+     * Only a client rendering the page itself should call this. The SDK's own
+     * read methods never track, so reading a tree does not pollute its owner's
+     * statistics.
+     *
+     * Answers 204 whatever happens - an unknown slug and an unknown item id both
+     * look like success, deliberately, so the endpoint cannot be used to probe
+     * which slugs exist.
+     */
+    trackClick(slug: string, itemId: string, options?: RequestOptions): Promise<void>;
+}

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

@@ -0,0 +1,96 @@
+/**
+ * The `notepads` namespace: anonymous shared scratch pads.
+ *
+ * A pad is addressed by its slug and by nothing else. `Notepad.viewable_by`
+ * returns `none` by construction and the blueprint strips the numeric `id` from
+ * every view, precisely so that nobody can walk primary keys into other
+ * people's pads. Knowing the slug IS the whole authorisation story: anyone
+ * holding it can read AND rewrite the pad.
+ *
+ * So treat a slug as a bearer secret. Do not log it, do not put it in a URL you
+ * paste somewhere, and do not put anything in a pad you would mind a stranger
+ * reading - the slugs the server mints come from `Faker::Internet.unique.slug`,
+ * which is word-shaped and short.
+ *
+ * Pads that are still empty an hour after their last write are swept away by a
+ * background job.
+ */
+import { Resource } from "../http";
+import type { RequestOptions, Timestamp } from "../types";
+/**
+ * A shared notepad.
+ *
+ * There is no `id`: the blueprint excludes it from the default view AND from
+ * `:extended`, so this is one of the very few records in the API that does not
+ * extend `BaseRecord`. The slug is the identifier.
+ */
+export interface Notepad {
+    /** Word-shaped capability, e.g. `"quick-brown-fox"`. Treat it as a secret. */
+    readonly slug: string;
+    /** The whole document. Empty string, never `null`, for a fresh pad. */
+    readonly content: string;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    /**
+     * Endpoint of the `n/` short link the backend keeps pointing at this pad,
+     * so `https://omelhor.site/n/<endpoint>` opens it in the web tool.
+     *
+     * Only {@link NotepadsNamespace.showOrCreate} sends this field;
+     * {@link NotepadsNamespace.update} answers with the bare record.
+     */
+    readonly short_link_endpoint?: string;
+}
+/** Arguments for {@link NotepadsNamespace.showOrCreate}. */
+export interface OpenNotepadInput {
+    /**
+     * Slug to open. Omit it to mint a brand new pad - that branch is throttled
+     * per IP, so never omit it in a loop and never omit it just to poll.
+     */
+    readonly slug?: string;
+}
+/** The `notepads` namespace, reachable as `oms.notepads`. */
+export declare class NotepadsNamespace extends Resource {
+    /**
+     * `GET /notepads/show_or_create` - opens the pad with this slug, creating it
+     * if no pad has that slug yet.
+     *
+     * Fully anonymous: no credential is sent, none is needed, and one would not
+     * change the answer.
+     *
+     * Two very different calls share this one route, and they have different
+     * costs:
+     *
+     * - **with a slug** it is a plain read, cheap and unthrottled beyond the
+     *   general ceiling. This is the call a poller makes;
+     * - **without a slug** it MINTS a row, and minting is capped at **20 pads
+     *   per hour per IP** by a counter inside the controller (deliberately not in
+     *   rack-attack, so that polling reads do not spend the budget). Over the cap
+     *   the answer is `429` with the body `{"error":"rate_limited"}` and **no**
+     *   `Retry-After` header, which arrives here as an {@link OmsQuotaError}
+     *   whose `retryAfterMs` is `undefined`. Waiting is the only cure; there is
+     *   nothing to read off the response.
+     *
+     * Retries are disabled for the mint branch: every attempt would generate a
+     * DIFFERENT random slug, so a retry after a lost response leaves an orphan
+     * pad behind and hands you the wrong one. The read branch keeps the client's
+     * normal retry policy.
+     *
+     * @throws {OmsQuotaError} 429 when the per-IP creation budget is spent.
+     */
+    showOrCreate(input?: OpenNotepadInput, options?: RequestOptions): Promise<Notepad>;
+    /**
+     * `PATCH /notepads/:slug` - replaces the whole content.
+     *
+     * The `:id` path segment is the SLUG, not a database id; the controller looks
+     * the pad up by slug and then requires that same slug back as proof the
+     * caller was handed the pad rather than guessing at it.
+     *
+     * There is no diff and no merge: the last write wins, and two editors will
+     * clobber each other silently. A host that wants collaborative editing has to
+     * reconcile before calling. `content` is the only writable field.
+     *
+     * @throws {OmsApiError} 404 when no pad has that slug. Note the asymmetry
+     *   with {@link showOrCreate}, which would have created it.
+     */
+    update(slug: string, content: string, options?: RequestOptions): Promise<Notepad>;
+}

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

@@ -0,0 +1,248 @@
+/**
+ * The `shortLinks` namespace: URL shortening plus per-link click statistics.
+ *
+ * This module is the reference implementation of the resource pattern. Every
+ * other resource in the SDK is shaped exactly like it, and CONTRACT.md quotes
+ * it verbatim. Change the pattern here and change it everywhere, or do not
+ * change it at all.
+ *
+ * Creating a link works anonymously; listing, editing and statistics need a
+ * credential. Creation is the most tightly throttled write in the whole API -
+ * see {@link ShortLinksNamespace.create} before you spend one.
+ */
+import { Resource } from "../http";
+import { type BaseRecord, type Id, type JsonObject, type PageParams, type Paginated, type RequestOptions, type Timestamp } from "../types";
+/** Public host that fronts `short_links#follow`. See {@link ShortLinksNamespace.shortUrl}. */
+export declare const SHORT_LINK_BASE_URL = "https://omelhor.site";
+/**
+ * Primary key of a short link.
+ *
+ * Short links predate the string ids the rest of the API uses: the table still
+ * has an integer primary key, so the JSON carries a **number** here while the
+ * `user_id` right next to it is a string. Every method accepts either form and
+ * interpolates it into the path, so a caller never has to care.
+ */
+export type ShortLinkId = Id | number;
+/** One recorded visit to a short link. */
+export interface ShortLinkClick {
+    readonly id: number;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    /** ISO 3166-1 alpha-2 resolved from the visitor's IP, or `null`. */
+    readonly country: string | null;
+    /** Browser or app name parsed from the user agent, or `null`. */
+    readonly device_name: string | null;
+}
+/**
+ * A short link.
+ *
+ * `Omit<BaseRecord, "id">` rather than a plain `extends BaseRecord`: see
+ * {@link ShortLinkId} for why the identifier is a number on this one table.
+ */
+export interface ShortLink extends Omit<BaseRecord, "id"> {
+    /** Integer primary key. See {@link ShortLinkId}. */
+    readonly id: number;
+    /** The destination the link redirects to. */
+    readonly url: string;
+    /** The path segment after the domain, e.g. `"my-talk"`. */
+    readonly endpoint: string;
+    /**
+     * Namespace the endpoint lives under. User links have `null` or `""`; the
+     * internal tools reserve `"n"` (notepads), `"c"` (chests), `"ss"` (storage
+     * shares), `"qr"` (dynamic QR), `"f"` (forms) and `"t"` (link trees). That
+     * is why {@link ShortLink} and `DynamicQr` are separate resources even
+     * though both are rows in the same table.
+     */
+    readonly namespace: string | null;
+    /** Owner, or `null` for a link created anonymously. */
+    readonly user_id: Id | null;
+    /**
+     * EVERY click ever recorded, inlined by the blueprint - not a count, not a
+     * page. A link with 50 000 visits sends 50 000 objects here. Use
+     * {@link ShortLinksNamespace.stats} for anything analytical and treat this
+     * field as a payload hazard, not as a feature.
+     */
+    readonly short_link_clicks?: ShortLinkClick[];
+    /** The owner rendered inline (the same shape `oms.account` returns), or `null`. */
+    readonly user?: JsonObject | null;
+}
+/** One day of the click histogram. */
+export interface ShortLinkDailyClicks {
+    /** `YYYY-MM-DD`. */
+    readonly date: string;
+    readonly count: number;
+}
+/** Clicks grouped by the visitor's country. */
+export interface ShortLinkCountryClicks {
+    /** ISO 3166-1 alpha-2 as it was stored at click time. */
+    readonly country: string;
+    readonly count: number;
+}
+/** Clicks grouped by the visitor's browser or app. */
+export interface ShortLinkDeviceClicks {
+    readonly device_name: string;
+    readonly count: number;
+}
+/**
+ * `GET /short_links/:id/stats`, and the identical body
+ * `GET /dynamic_qrs/:id/stats` returns.
+ *
+ * Five keys, always all five. There is no referrer breakdown and no unique
+ * visitor count: the backend stores neither.
+ */
+export interface ShortLinkStats {
+    readonly total_clicks: number;
+    /** Timestamp of the most recent click, or `null` when there has never been one. */
+    readonly last_click_at: Timestamp | null;
+    /**
+     * Exactly 30 entries, oldest first, ending today. Days with no clicks are
+     * present with `count: 0`, so the series is safe to plot without gap
+     * filling. The window is FIXED server-side; there is no way to ask for
+     * another one.
+     */
+    readonly clicks_daily: ShortLinkDailyClicks[];
+    /** Top 10 countries by clicks, descending. Rows with no country are excluded. */
+    readonly top_countries: ShortLinkCountryClicks[];
+    /** Top 5 devices by clicks, descending. Rows with no device are excluded. */
+    readonly top_devices: ShortLinkDeviceClicks[];
+}
+/** Arguments for creating a short link. */
+export interface CreateShortLinkInput {
+    /**
+     * Absolute destination URL. Must be `http` or `https` and must parse against
+     * `URI::DEFAULT_PARSER`; anything else is a 400, not a silent rewrite.
+     */
+    readonly url: string;
+    /**
+     * Requested endpoint. Omit it and the server mints a random alphanumeric one
+     * (4 characters, growing until it finds a free one). A taken endpoint comes
+     * back as a 400, never as a silent rename.
+     *
+     * Anonymous callers may pick an endpoint too - the server only generates one
+     * when the field is blank.
+     */
+    readonly endpoint?: string;
+}
+/** Fields that can change after a link exists. */
+export interface UpdateShortLinkInput {
+    readonly url?: string;
+    readonly endpoint?: string;
+}
+/** Filters for {@link ShortLinksNamespace.list}. */
+export interface ListShortLinksParams extends PageParams {
+    /**
+     * Narrow to one owner, sent as `exact_search[user_id]`.
+     *
+     * The listing is already scoped to the caller server-side, so this can only
+     * ever narrow your own links to yourself or to nothing. It exists because
+     * the web app sends it; there is no admin escape hatch here.
+     */
+    readonly userId?: Id;
+}
+/** The `shortLinks` namespace, reachable as `oms.shortLinks`. */
+export declare class ShortLinksNamespace extends Resource {
+    /**
+     * `GET /short_links` - the links you own, newest first.
+     *
+     * Only user-managed links are listed: anything in a system namespace
+     * (notepads, chests, dynamic QR, forms, link trees) is filtered out server
+     * side, so a dynamic QR will never show up here. Use `oms.dynamicQrs.list()`
+     * for those.
+     *
+     * The endpoint has NO default ordering of its own, which would make paging
+     * non-deterministic, so the SDK always sends one (`created_at:desc` unless
+     * you override `order`).
+     *
+     * Beware {@link ShortLink.short_link_clicks}: every row carries its full
+     * click history. A page of 500 busy links is a very large response.
+     *
+     * @throws {OmsAuthError} 401 when anonymous.
+     */
+    list(params?: ListShortLinksParams, options?: RequestOptions): Promise<Paginated<ShortLink>>;
+    /**
+     * `POST /short_links` - shortens a URL.
+     *
+     * **Rate limit, read this before you spend one:** rack-attack allows
+     * **10 creations per hour per IP** (`short_links_create/ip`), and the rule
+     * is keyed by IP for EVERYONE - being signed in does not buy you a bigger
+     * budget. The 11th call in an hour answers `429` with a `Retry-After` header
+     * measured in whatever is left of that hour, which arrives here as an
+     * {@link OmsQuotaError} with `retryAfterMs` set. An agent that shortens URLs
+     * in a loop will burn the whole hour's budget in about a second, so batch the
+     * decision, not the calls.
+     *
+     * Retries are disabled by default for exactly two reasons: a replayed `POST`
+     * after a 502 mints a SECOND link, and the transport's 429 handling honours
+     * `Retry-After` literally, which here means sleeping for up to an hour inside
+     * one call. Pass `retry` explicitly if you want either behaviour back.
+     *
+     * Works anonymously, in which case the link has no owner and cannot be
+     * listed, edited or measured afterwards - the endpoint string is the only
+     * handle you will ever have on it. Capture the response.
+     *
+     * @throws {OmsQuotaError} 429 once the hourly budget is spent.
+     * @throws {OmsApiError} 400 when `endpoint` is taken or `url` is not an
+     *   `http`/`https` URL. The body is a plain sentence, so read `message`.
+     */
+    create(input: CreateShortLinkInput, options?: RequestOptions): Promise<ShortLink>;
+    /**
+     * `PATCH /short_links/:id` - repoints a link or renames its endpoint.
+     *
+     * Renaming frees the old endpoint immediately, and every printed or shared
+     * copy of it stops working. There is no redirect from the old name.
+     *
+     * @throws {OmsAuthError} 401 when anonymous.
+     * @throws {OmsApiError} 404 when the link is not yours, 400 on a taken
+     *   endpoint or an invalid URL.
+     */
+    update(id: ShortLinkId, input: UpdateShortLinkInput, options?: RequestOptions): Promise<ShortLink>;
+    /**
+     * `DELETE /short_links/:id`. The endpoint becomes free again immediately and
+     * the recorded clicks go with it.
+     *
+     * @throws {OmsApiError} 404 when the link is not yours.
+     */
+    delete(id: ShortLinkId, options?: RequestOptions): Promise<void>;
+    /**
+     * `GET /short_links/:id/stats` - totals plus a fixed 30-day daily histogram.
+     *
+     * The window is not configurable: the backend always buckets the last 30
+     * days. For anything else, read {@link ShortLink.short_link_clicks} off the
+     * record and bucket it yourself - at the cost noted on that field.
+     *
+     * @throws {OmsAuthError} 401 when anonymous (checked before the lookup, so an
+     *   anonymous caller cannot probe which ids exist).
+     * @throws {OmsApiError} 404 when the link is not yours.
+     */
+    stats(id: ShortLinkId, options?: RequestOptions): Promise<ShortLinkStats>;
+    /**
+     * Finds one of YOUR links by its endpoint, without counting a click.
+     *
+     * The public `follow` route records a visit before it redirects, so using it
+     * to read a destination would quietly corrupt the owner's statistics. The
+     * API offers no read-by-endpoint, and `search[endpoint]` is not on the
+     * allowlist (an unknown filter key is a 400, not a wider result), so the only
+     * honest implementation is to page through your own listing and match
+     * locally. That has three consequences worth knowing:
+     *
+     * - it needs a credential, and it only ever finds links you own;
+     * - it cannot see a system-namespace endpoint (`qr/...`, `n/...`), because
+     *   the listing filters those out;
+     * - it costs one request per {@link RESOLVE_PAGE_SIZE} links you own, and
+     *   gives up after {@link RESOLVE_MAX_PAGES} pages.
+     *
+     * @throws {OmsError} with `code === "not_found"` when no owned link carries
+     *   that endpoint. Nothing was requested by id, so this is not an HTTP 404.
+     */
+    resolve(endpoint: string, options?: RequestOptions): Promise<ShortLink>;
+    /**
+     * The public URL a link is served from. Pure string building, no request.
+     *
+     * The API hands back an `endpoint`, never the address people actually click,
+     * so this fills the gap - including for the system namespaces, whose links
+     * live one segment deeper.
+     */
+    shortUrl(link: Pick<ShortLink, "endpoint" | "namespace">): string;
+    /** One page of the listing. Shared by {@link list} and {@link resolve}. */
+    private fetchPage;
+}