@omelhorsite/sdk 0.2.0 → 0.4.0

package/dist/types/resources/admin/oauthApplications.d.ts

@@ -0,0 +1,309 @@
+/** `oms.admin.oauthApplications` - the review queue and the registry of every OAuth client. Administrators only. */
+import type { OmsScope } from "../../auth/tokens";
+import { Resource } from "../../http";
+import type { RequestOptions, Timestamp } from "../../types";
+import type { OauthApplicationSummary } from "./types";
+/**
+ * A registered client as an ADMINISTRATOR sees it: same eleven keys as
+ * {@link OwnedOauthApplication}, but `approved_by` is real and the row can
+ * belong to anybody on the server.
+ */
+export interface AdminOauthApplication extends OauthApplicationSummary {
+}
+/**
+ * {@link AdminOauthApplication} plus the counters that answer "is this client
+ * live right now".
+ *
+ * Returned by every administrator action EXCEPT `index` and `pending`, which
+ * send the summary: the counters cost five aggregate queries per row and a
+ * listing does not pay for them.
+ */
+export interface AdminOauthApplicationDetail extends AdminOauthApplication {
+    /**
+     * Unrevoked AND unexpired access tokens. Note the difference from
+     * {@link AuthorizedApplication.token_count}, which counts unrevoked only: an
+     * expired-but-refreshable token counts there and not here, so this number can
+     * read `0` for a client that will be talking to the server again in a second.
+     */
+    readonly live_token_count: number;
+    /** Distinct people behind those live tokens. The blast radius of a revocation. */
+    readonly live_token_users: number;
+    /** Every token ever minted for this client, revoked and expired included. */
+    readonly total_token_count: number;
+    /** When the most recent token was minted, `null` if never. */
+    readonly last_token_at: Timestamp | null;
+    /**
+     * Device grants nobody has approved yet (`resource_owner_id IS NULL`), i.e.
+     * device flows in progress. Approved-but-uncollected grants are NOT counted
+     * here, though a revocation kills those too.
+     */
+    readonly pending_device_grants: number;
+}
+/** What {@link AdminOauthApplicationsNamespace.pending} answers with. */
+export interface AdminOauthPendingQueue {
+    /** Oldest first: it is a queue, not a feed. A newest-first queue starves its own bottom. */
+    readonly applications: AdminOauthApplication[];
+    /** `applications.length`. Sent so a badge does not have to load the array. */
+    readonly count: number;
+}
+/** Arguments for {@link AdminOauthApplicationsNamespace.register}. */
+export interface RegisterOauthApplicationInput {
+    /** Normalised then required. See {@link OAUTH_APP_NAME_MAX_LENGTH}. */
+    readonly name: string;
+    /** Unknown scopes are dropped; an empty result after filtering is a `400`. */
+    readonly scopes: readonly (OmsScope | string)[] | string;
+    /** Defaults to `false`. Every client this project ships is public. */
+    readonly confidential?: boolean;
+    /** Blank registers {@link NATIVE_LOOPBACK_REDIRECT_VALUE}. */
+    readonly redirect_uri?: string;
+}
+/** What {@link AdminOauthApplicationsNamespace.register} answers with. */
+export interface AdminOauthApplicationWithSecret {
+    readonly application: AdminOauthApplicationDetail;
+    /** Once, and `null` for a public client. See {@link OwnedOauthApplicationWithSecret}. */
+    readonly client_secret: string | null;
+}
+/** Arguments for {@link AdminOauthApplicationsNamespace.reject}. */
+export interface RejectOauthApplicationInput {
+    /**
+     * Required, non-blank, at most 500 characters. **The owner is shown this
+     * text**, so write it for them.
+     */
+    readonly reason: string;
+    /**
+     * Kill the client's live tokens as well.
+     *
+     * Opt-in, and it only decides anything for a client that was NOT approved -
+     * rejecting an APPROVED client always revokes, whatever this says, because an
+     * administrator withdrawing trust has decided the client should stop acting,
+     * not that it should stop acting eventually.
+     */
+    readonly revoke_tokens?: boolean;
+}
+/** What {@link AdminOauthApplicationsNamespace.approve} and `.reject()` answer with. */
+export interface OauthApplicationReview {
+    readonly application: AdminOauthApplicationDetail;
+    /** Present on `reject`. Absent on `approve`, which never revokes anything. */
+    readonly revoked_tokens?: number;
+}
+/** What {@link AdminOauthApplicationsNamespace.revokeTokens} answers with. */
+export interface OauthTokenRevocation {
+    readonly application: AdminOauthApplicationDetail;
+    readonly revoked_tokens: number;
+}
+/**
+ * What {@link AdminOauthApplicationsNamespace.destroy} answers with.
+ *
+ * The `client_id` is spelled **`uid`** here and `client_id` on the owner route
+ * ({@link OwnedOauthApplicationDeletion}). One value, two routes, two names,
+ * and nothing reconciles them.
+ */
+export interface AdminOauthApplicationDeletion {
+    readonly id: number;
+    /** The `client_id`. Named after the column, not after the protocol. */
+    readonly uid: string;
+    readonly revoked_tokens: number;
+}
+/**
+ * `oms.admin.oauthApplications` - **administrators only**. The review queue and
+ * the registry of every OAuth client on the server.
+ *
+ * Every method here answers `403 "Admin access required"` to a non-admin. See
+ * the namespace documentation for the exact error shape and why
+ * re-authenticating will not help.
+ *
+ * This is the other end of {@link MyOauthApplicationsNamespace}: the same
+ * table, without the ownership filter. `destroy` here deletes anybody's client
+ * and cuts off everyone using it.
+ *
+ * Together with the self-service surface, this is the ONLY way a client gets
+ * registered: dynamic client registration is off, and there is no client
+ * management under `/oauth/*`.
+ *
+ * ## Review receipts, and why a read here is not a pure read
+ *
+ * {@link list}, {@link pending} and {@link get} each record, in a server-side
+ * cache and keyed to the calling administrator, a digest of what they were just
+ * shown. {@link approve} then refuses with `409 review_stale` if the row no
+ * longer matches.
+ *
+ * That exists because approving by id approves whatever the row holds when the
+ * request lands, not what the queue rendered - and the window between a
+ * reviewer's eyes and their click belongs to the applicant, who may edit a
+ * pending client freely (they have to be able to: that is how a refused
+ * registration gets fixed). Register something innocent, wait to be read,
+ * rename it to "omelhorsite Oficial" with a redirect URI you control, and the
+ * approval lands on a client nobody reviewed.
+ *
+ * Two consequences for a client of this SDK:
+ *
+ * - **calling `approve` without having read the client first is allowed** and
+ *   behaves exactly as it would with no receipt. No receipt means no
+ *   contradiction. This layer tightens the reviewed path; the authorisation
+ *   check is the `403` above, not this;
+ * - the digest covers name, scopes, redirect URIs, `confidential` and owner. It
+ *   deliberately excludes `approval_status`, so approving twice stays
+ *   idempotent, and the receipt lasts 7 days.
+ *
+ * {@link reject} and {@link revokeTokens} are NOT gated this way on purpose:
+ * refusing or shutting down a client that changed under you is the safe
+ * direction, and a shut-down button that can refuse is how a client stays live.
+ */
+export declare class AdminOauthApplicationsNamespace extends Resource {
+    /**
+     * `GET /admin/oauth_applications` - every client on the server, newest first.
+     *
+     * No pagination and no filter. Records a review receipt for every row
+     * returned; see the class documentation.
+     *
+     * Summaries, not details: no token counters. Use {@link get} for those.
+     *
+     * @throws {OmsAuthError} 403 for a non-admin.
+     */
+    list(options?: RequestOptions): Promise<AdminOauthApplication[]>;
+    /**
+     * `GET /admin/oauth_applications/pending` - the review queue, oldest first.
+     *
+     * A separate collection route and NOT a filter on {@link list}, so an admin
+     * panel can poll one cheap indexed query without carrying the other
+     * listing's joins. Ordered by `created_at` then `id`, which makes the order
+     * total: two rows can share a timestamp, and an unstable order makes a
+     * polling panel jitter.
+     *
+     * Records a review receipt for every row returned.
+     *
+     * @throws {OmsAuthError} 403 for a non-admin.
+     */
+    pending(options?: RequestOptions): Promise<AdminOauthPendingQueue>;
+    /**
+     * `GET /admin/oauth_applications/:id` - one client, with its token counters.
+     *
+     * **`id` may be either the numeric primary key or the `client_id`.** The
+     * lookup tries the id first and falls back to the `uid`, which is what makes
+     * `oms.admin.oauthApplications.get("oms-cli")` work. The owner route has no
+     * such fallback.
+     *
+     * Records a review receipt.
+     *
+     * @throws {OmsApiError} 404 `{ "error": "not_found" }`.
+     * @throws {OmsAuthError} 403 for a non-admin.
+     */
+    get(id: number | string, options?: RequestOptions): Promise<AdminOauthApplicationDetail>;
+    /**
+     * `POST /admin/oauth_applications` - registers a client by hand, already
+     * approved.
+     *
+     * Named `register` and not `create` because it is not the counterpart of
+     * {@link MyOauthApplicationsNamespace.create}: what lands here is **born
+     * `approved`**, with `owner_id` NULL and `approved_by` set to the calling
+     * administrator. An admin registering a client IS the approval; routing them
+     * through their own queue would be theatre. It never appears in
+     * {@link pending}.
+     *
+     * **Answers `200`, not `201`**, unlike the self-service registration. Do not
+     * branch on the status.
+     *
+     * The response is the ONLY place `client_secret` ever exists. See
+     * {@link OwnedOauthApplicationWithSecret} for why there is nothing to read
+     * back later.
+     *
+     * `confidential` defaults to `false`, which is right for the clients this
+     * surface exists to register: anything that ships to end users cannot keep a
+     * secret.
+     *
+     * Retries are disabled: a replay after a lost response mints a second client
+     * with a second `client_id` and a second secret you never saw.
+     *
+     * @throws {OmsApiError} 400 (bare string) for a blank name, no known scope,
+     *   or too many redirect URIs; 422 `validation_failed` with an `errors` array
+     *   for a redirect URI this server will not register.
+     * @throws {OmsAuthError} 403 for a non-admin.
+     */
+    register(input: RegisterOauthApplicationInput, options?: RequestOptions): Promise<AdminOauthApplicationWithSecret>;
+    /**
+     * `POST /admin/oauth_applications/:id/approve` - lets the client start
+     * minting tokens.
+     *
+     * Idempotent, and it works from `rejected` as well as from `pending`: there
+     * is no separate rehabilitation action. Approving an already-approved client
+     * answers `200` and deliberately does NOT notify the owner a second time - a
+     * double click is not two decisions.
+     *
+     * **Read the class documentation on review receipts before wiring a retry
+     * around this.** If this administrator rendered the client and it changed
+     * afterwards, the answer is `409 review_stale`, and the body carries the
+     * CURRENT row under `application` so the screen can show what it turned into
+     * rather than sending someone to go and find out. Retrying that verbatim just
+     * gets the same `409`; the fix is to re-read and review again.
+     *
+     * @throws {OmsApiError} 409 `review_stale`; 404 `not_found`; 422
+     *   `validation_failed`.
+     * @throws {OmsAuthError} 403 for a non-admin.
+     */
+    approve(id: number | string, options?: RequestOptions): Promise<OauthApplicationReview>;
+    /**
+     * `POST /admin/oauth_applications/:id/reject` - refuses a registration, or
+     * pulls an approved client off the air.
+     *
+     * One action, two buttons. `pending -> rejected` is a refusal at review;
+     * `approved -> rejected` is a suspension, and there is no fourth state to put
+     * a client in.
+     *
+     * **Rejecting shuts the gate but does not by itself kill issued tokens.** A
+     * rejected client can no longer mint, refresh or exchange anything, yet
+     * access tokens already in the wild keep working until they expire - a blast
+     * radius of the two-hour token lifetime. Which is why:
+     *
+     * - `revoke_tokens: true` kills them in the same breath. Opt-in, so refusing
+     *   a never-approved registration stays the cheap, quiet operation it should
+     *   be;
+     * - a client that WAS approved has its tokens revoked regardless of the flag.
+     *
+     * `reason` is required and the OWNER sees it. Re-rejecting with the same
+     * reason is a no-op notification-wise; changing the wording notifies again.
+     *
+     * Not gated by a review receipt: shutting a client down is always the safe
+     * direction.
+     *
+     * @throws {OmsApiError} 400 `reason_required` for a blank reason; 422
+     *   `validation_failed` past 500 characters; 404 `not_found`.
+     * @throws {OmsAuthError} 403 for a non-admin.
+     */
+    reject(id: number | string, input: RejectOauthApplicationInput, options?: RequestOptions): Promise<OauthApplicationReview>;
+    /**
+     * `POST /admin/oauth_applications/:id/revoke_tokens` - kills everything the
+     * client holds, and leaves the client standing.
+     *
+     * The 3am action: the `client_id` is fine, what it is doing is not. Every
+     * live access token dies, every access grant dies, every device grant is
+     * deleted, and the client can be used for a fresh login the second
+     * afterwards. Approval is untouched.
+     *
+     * This is the whole-server version of
+     * {@link AuthorizedApplicationsNamespace.revoke}, which only ever touches the
+     * caller's own tokens. Read `live_token_users` on the detail first to know
+     * how many people you are about to sign out.
+     *
+     * @throws {OmsApiError} 404 `not_found`.
+     * @throws {OmsAuthError} 403 for a non-admin.
+     */
+    revokeTokens(id: number | string, options?: RequestOptions): Promise<OauthTokenRevocation>;
+    /**
+     * `DELETE /admin/oauth_applications/:id` - deletes anybody's client.
+     *
+     * Revokes first, then destroys, so the revocation stamps exist for the moment
+     * in between and the device grants (which hold a restricting foreign key) are
+     * cleared by hand rather than by a cascade.
+     *
+     * This is not the tidy-up that {@link MyOauthApplicationsNamespace.destroy}
+     * is. Deleting a client somebody else registered signs out everyone using it
+     * and there is no undo: the `client_id` is gone and a new registration gets a
+     * new one. {@link revokeTokens} is the reversible version.
+     *
+     * Answers `200` with a body; note the key is `uid`, not `client_id`.
+     *
+     * @throws {OmsApiError} 404 `not_found`.
+     * @throws {OmsAuthError} 403 for a non-admin.
+     */
+    destroy(id: number | string, options?: RequestOptions): Promise<AdminOauthApplicationDeletion>;
+}

package/dist/types/resources/admin/quotas.d.ts

@@ -0,0 +1,114 @@
+/** `oms.admin.quotas` - another person's quota ceilings. Administrators only. */
+import type { QuotaPeriod, QuotaResource, QuotaUnit } from "../quotas";
+import { Resource } from "../../http";
+import type { Id, RequestOptions } from "../../types";
+/**
+ * How an override behaves.
+ *
+ * - `"default"` DELETES the override row, so the person falls back to the
+ *   catalogue default. It does not write a number equal to the default, which
+ *   matters the day a default changes;
+ * - `"unlimited"` writes an override with a NULL value, which the server reads
+ *   as no ceiling at all;
+ * - `"limit"` writes the number in `value`.
+ */
+export type AdminQuotaOverrideMode = "default" | "unlimited" | "limit";
+/** One change to apply. See {@link AdminQuotasNamespace.update}. */
+export interface AdminQuotaOverride {
+    readonly resource: QuotaResource | string;
+    readonly mode: AdminQuotaOverrideMode;
+    /** Required for `"limit"`, ignored otherwise. Must be `>= 0` and fit in a signed 64-bit integer. */
+    readonly value?: number;
+}
+/** The stored override behind a {@link AdminUserQuotaEntry}, if there is one. */
+export interface AdminQuotaOverrideState {
+    /** The number, or `null` when the override means unlimited. */
+    readonly value: number | null;
+    /** `true` exactly when `value` is `null`. */
+    readonly unlimited: boolean;
+}
+/**
+ * One resource, for one person, as an administrator sees it.
+ *
+ * This is the ordinary quota entry that `oms.quotas.list()` returns, plus the
+ * two keys that only make sense while editing: what the default WOULD be, and
+ * what is currently overriding it.
+ */
+export interface AdminUserQuotaEntry {
+    readonly resource: QuotaResource | string;
+    readonly unit: QuotaUnit | string;
+    readonly period: QuotaPeriod | string;
+    /** Consumption right now, in `unit`. */
+    readonly used: number;
+    /** The effective ceiling, or `null` when unlimited. */
+    readonly limit: number | null;
+    /** `limit - used`, floored at zero. `null` when unlimited. */
+    readonly remaining: number | null;
+    readonly unlimited: boolean;
+    /** The catalogue default for a signed-in user. What `"default"` mode restores. */
+    readonly user_default: number;
+    /** The stored override, or `null` when there is none and the default applies. */
+    readonly override: AdminQuotaOverrideState | null;
+}
+/** What {@link AdminQuotasNamespace} returns. */
+export interface AdminUserQuotas {
+    readonly user_id: Id;
+    readonly handle: string;
+    /**
+     * **Every** resource in the catalogue, including the storage and music
+     * ceilings. Unlike the anonymous answer from `oms.quotas.list()`, nothing is
+     * left out here. Look entries up by `resource`, never by position.
+     */
+    readonly quotas: AdminUserQuotaEntry[];
+    /**
+     * Legacy twin of the `music_storage_bytes` entry's `limit`, `null` when
+     * unlimited. Kept for older clients that read it. Prefer the catalogue
+     * entry; this key is on its way out.
+     */
+    readonly music_storage_limit_bytes: number | null;
+}
+/**
+ * `oms.admin.quotas` - **administrators only**. Another person's ceilings.
+ *
+ * The person's own view of the same numbers is `oms.quotas.list()`, which needs
+ * no privilege and cannot change anything.
+ */
+export declare class AdminQuotasNamespace extends Resource {
+    /**
+     * `GET /admin/users/:user/quotas` - the full catalogue for one person.
+     *
+     * **`user` may be a user id OR a handle.** The lookup tries the id first and
+     * then the handle, downcased, which is why an admin tool can take whatever
+     * was typed into a search box.
+     *
+     * @throws {OmsApiError} 404 `"User not found"` (a bare JSON string).
+     * @throws {OmsAuthError} 403 for a non-admin.
+     */
+    get(user: Id | string, options?: RequestOptions): Promise<AdminUserQuotas>;
+    /**
+     * `PUT /admin/users/:user/quotas` - applies a batch of overrides.
+     *
+     * **`PUT`, not `PATCH`.** The server accepts either verb for this update;
+     * this SDK sends `PUT`.
+     *
+     * **The batch is NOT atomic, and this is the thing to design around.** The
+     * server loops over `overrides` and writes each one as it goes, with no
+     * transaction around the loop: a bad entry in the middle answers `400` with
+     * everything BEFORE it already written and everything after it untouched. So
+     * a failed call leaves a partial state, and the only reliable way to know
+     * what landed is the answer to a fresh {@link get}. Validate the batch
+     * yourself before sending it, or send one override per call.
+     *
+     * Passing an empty `overrides` array is a legal no-op and a cheap way to read
+     * the quotas back, though {@link get} is the honest way to do that.
+     *
+     * The response is the full, reloaded catalogue, so there is no need to follow
+     * this with a read on the success path.
+     *
+     * @throws {OmsApiError} 400 `"Unknown resource: x"`, `"Invalid mode: x"`, or
+     *   `"Invalid value for x"` for a negative number or one past the signed
+     *   64-bit ceiling. All three are bare JSON strings. 404 `"User not found"`.
+     * @throws {OmsAuthError} 403 for a non-admin.
+     */
+    update(user: Id | string, overrides: readonly AdminQuotaOverride[], options?: RequestOptions): Promise<AdminUserQuotas>;
+}

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

@@ -0,0 +1,201 @@
+/** `oms.admin.shortLinks` - every public short link and its traffic. Administrators only. */
+import { Resource } from "../../http";
+import type { Id, RequestOptions, Timestamp } from "../../types";
+import type { AdminDailyCount } from "./types";
+/** Compact owner object on an admin short link row. `null` for an anonymous link. */
+export interface AdminShortLinkOwner {
+    readonly id: Id;
+    readonly name: string;
+    readonly handle: string;
+}
+/**
+ * A short link as the admin tool sees it.
+ *
+ * This is NOT the shape the ordinary `shortLinks` namespace returns. The
+ * differences are load-bearing:
+ *
+ * - there is **no `updated_at`**, uniquely on this surface;
+ * - there is **no `short_link_clicks` array**. The ordinary shape inlines EVERY
+ *   click ever recorded, which is a payload hazard on a busy link; here it is
+ *   replaced by the two aggregates below;
+ * - the full user record is replaced by the compact {@link AdminShortLinkOwner}.
+ */
+export interface AdminShortLink {
+    /**
+     * Primary key, and an **integer**: `short_links` kept a bigint primary key
+     * while the `user_id` next to it is a string.
+     */
+    readonly id: number;
+    readonly url: string;
+    readonly endpoint: string;
+    /**
+     * Always `null` or `""` on this surface: the listing, the drilldown and the
+     * delete are all scoped to non-namespaced links so that private chest,
+     * notepad and storage-share URLs never surface here.
+     * {@link AdminShortLinksNamespace.namespaces} is the one exception and it
+     * only returns counts.
+     */
+    readonly namespace: string | null;
+    /** Owner id, or `null` for a link created anonymously. */
+    readonly user_id: Id | null;
+    readonly owner: AdminShortLinkOwner | null;
+    readonly created_at: Timestamp;
+    /** Total clicks. Computed per page in one grouped query, not per row. */
+    readonly click_count: number;
+    readonly last_click_at: Timestamp | null;
+}
+/** Filters for {@link AdminShortLinksNamespace.list}. */
+export interface ListAdminShortLinksParams {
+    /**
+     * `"auth"` for links with an owner, `"anon"` for links without one. Any other
+     * value, including omitting it, means both.
+     */
+    readonly owner?: "auth" | "anon" | "all";
+    /**
+     * Case-insensitive substring matched against the endpoint OR the destination
+     * URL.
+     *
+     * **A plain top-level string, not the `search[column]` bucket the rest of
+     * this API uses.** The server reads `search` as a plain string here, so
+     * sending a bucket would be read as a hash and match nothing.
+     */
+    readonly search?: string;
+}
+/**
+ * A page of {@link AdminShortLinksNamespace.list}.
+ *
+ * Not a {@link Paginated}, because there is nothing to page through: see
+ * {@link AdminShortLinkPage.limit}.
+ */
+export interface AdminShortLinkPage {
+    /** At most {@link AdminShortLinkPage.limit} rows, newest first. */
+    readonly items: AdminShortLink[];
+    /** How many links match the filter in total. Frequently larger than `items.length`. */
+    readonly total: number;
+    /**
+     * The hard server-side cap, currently 100.
+     *
+     * **There is no pagination on this endpoint and no way to reach row 101.**
+     * When `total > limit` the rest is simply unreachable through this route; the
+     * only way to find a specific link beyond the cap is to narrow
+     * {@link ListAdminShortLinksParams.search} until it fits.
+     */
+    readonly limit: number;
+}
+/** What {@link AdminShortLinksNamespace.stats} answers with. */
+export interface AdminShortLinkStats {
+    /** Non-namespaced links only, like everything else on this surface. */
+    readonly total_links: number;
+    readonly total_clicks: number;
+    readonly clicks_last_24h: number;
+    readonly clicks_last_7d: number;
+    readonly zero_click_count: number;
+    /** Already a percentage, `0` to `100`, one decimal. Not a fraction. */
+    readonly zero_click_percent: number;
+    /** Rounded to two decimals. `0` when there are no links. */
+    readonly avg_clicks_per_link: number;
+    readonly creations_daily: AdminDailyCount[];
+    readonly clicks_daily: AdminDailyCount[];
+}
+/** One row of {@link AdminShortLinksNamespace.namespaces}. */
+export interface AdminShortLinkNamespaceCount {
+    /**
+     * `null` for user links, or one of the reserved tool namespaces: `"n"`
+     * notepads, `"c"` chests, `"ss"` storage shares, `"qr"` dynamic QR, `"f"`
+     * forms, `"t"` link trees.
+     */
+    readonly namespace: string | null;
+    readonly count: number;
+}
+/** Clicks grouped by country, on the admin drilldown. */
+export interface AdminShortLinkCountryCount {
+    /** ISO 3166-1 alpha-2 as stored at click time. */
+    readonly country: string;
+    readonly count: number;
+}
+/** Clicks grouped by browser or app, on the admin drilldown. */
+export interface AdminShortLinkDeviceCount {
+    readonly device_name: string;
+    readonly count: number;
+}
+/**
+ * What {@link AdminShortLinksNamespace.get} answers with.
+ *
+ * Note what is NOT here: no `total_clicks` and no `last_click_at` at the top
+ * level. The drilldown leaves the totals out because the same two numbers are
+ * already on `link`. Read them from there.
+ */
+export interface AdminShortLinkDetail {
+    readonly link: AdminShortLink;
+    readonly clicks_daily: AdminDailyCount[];
+    /** Top 10 countries by clicks, descending. Rows with no country are excluded. */
+    readonly top_countries: AdminShortLinkCountryCount[];
+    /** Top 5 devices by clicks, descending. Rows with no device are excluded. */
+    readonly top_devices: AdminShortLinkDeviceCount[];
+}
+/**
+ * `oms.admin.shortLinks` - **administrators only**. Every public short link and
+ * its traffic.
+ *
+ * The unprivileged half is `oms.shortLinks`, which only ever shows the caller's
+ * own links. This one shows everybody's, anonymous ones included, which is the
+ * point: an anonymous short link has no owner to report it.
+ *
+ * **Scoped to non-namespaced links throughout.** Links minted by the internal
+ * tools (notepads, chests, storage shares, dynamic QR, forms, link trees) carry
+ * a namespace and are excluded from {@link list}, {@link get}, {@link stats}
+ * and {@link destroy}, so an admin panel cannot accidentally surface a private
+ * chest URL. {@link namespaces} is the deliberate exception and returns nothing
+ * but counts.
+ */
+export declare class AdminShortLinksNamespace extends Resource {
+    /**
+     * `GET /admin/short_links` - the newest 100 matching links.
+     *
+     * Read {@link AdminShortLinkPage.limit} before building a table on this: the
+     * cap is hard and there is no page parameter.
+     *
+     * @throws {OmsAuthError} 403 for a non-admin.
+     */
+    list(params?: ListAdminShortLinksParams, options?: RequestOptions): Promise<AdminShortLinkPage>;
+    /**
+     * `GET /admin/short_links/stats` - server-wide totals and two 30 day series.
+     *
+     * @throws {OmsAuthError} 403 for a non-admin.
+     */
+    stats(options?: RequestOptions): Promise<AdminShortLinkStats>;
+    /**
+     * `GET /admin/short_links/namespaces` - how many links each namespace holds.
+     *
+     * The ONE call on this surface that looks past the non-namespaced scope, and
+     * even so it only ever returns counts, never a row. User links come first
+     * (`namespace: null`), then the reserved namespaces alphabetically.
+     *
+     * @throws {OmsAuthError} 403 for a non-admin.
+     */
+    namespaces(options?: RequestOptions): Promise<AdminShortLinkNamespaceCount[]>;
+    /**
+     * `GET /admin/short_links/:id` - one link with its traffic breakdown.
+     *
+     * @throws {OmsApiError} 404 `{ "error": "not_found" }` - which is also the
+     *   answer for a link that exists but carries a namespace, since those are
+     *   out of scope here.
+     * @throws {OmsAuthError} 403 for a non-admin.
+     */
+    get(id: number | string, options?: RequestOptions): Promise<AdminShortLinkDetail>;
+    /**
+     * `DELETE /admin/short_links/:id` - deletes anybody's short link.
+     *
+     * Answers `200` with `{ id }`, not `204`. The clicks go with it.
+     *
+     * The link stops resolving immediately and there is no undo: the endpoint
+     * becomes free again and somebody else can claim it, which is worth
+     * remembering before deleting something that was printed or posted.
+     *
+     * @throws {OmsApiError} 404 `not_found`, namespaced links included.
+     * @throws {OmsAuthError} 403 for a non-admin.
+     */
+    destroy(id: number | string, options?: RequestOptions): Promise<{
+        readonly id: number;
+    }>;
+}