@omelhorsite/sdk 0.1.0

package/dist/types/client.d.ts

@@ -0,0 +1,133 @@
+/**
+ * `Oms` - the single entry point of the SDK.
+ *
+ * Everything a caller can do hangs off one instance, grouped into namespaces by
+ * domain. This is the object a model sees first in code mode, so the namespace
+ * names are part of the contract: `oms.tools.transcription.create(...)` has to
+ * be guessable without reading a page of docs.
+ *
+ * Constructing it is cheap and does no I/O: it builds an {@link ApiClient} and
+ * the namespace objects, nothing else.
+ */
+import { AuthNamespace } from "./auth/index";
+import type { TokenSet } from "./auth/tokens";
+import { ApiClient, type TokenProvider } from "./http";
+import { type LocalNamespace } from "./local/index";
+import { AccountNamespace } from "./resources/account";
+import { ChestsNamespace } from "./resources/chests";
+import { DynamicQrsNamespace } from "./resources/dynamicQrs";
+import { FormsNamespace } from "./resources/forms";
+import { IpLookupNamespace } from "./resources/ipLookup";
+import { JobsNamespace } from "./resources/jobs";
+import { LinkTreesNamespace } from "./resources/linkTrees";
+import { NotepadsNamespace } from "./resources/notepads";
+import { ShortLinksNamespace } from "./resources/shortLinks";
+import { StorageNamespace } from "./resources/storage";
+import { TicketsNamespace } from "./resources/tickets";
+import { ToolsNamespace } from "./resources/tools/index";
+import type { FetchLike, RetryOptions } from "./types";
+/**
+ * Anything accepted as a credential by {@link Oms}.
+ *
+ * A bare string is either kind of bearer token the API takes: a legacy opaque
+ * `Session` UUID or an OAuth access token. A function is called on every
+ * request. A {@link TokenProvider} additionally gets a chance to refresh on a
+ * 401 - see `auth/tokens.ts`.
+ */
+export type OmsCredential = string | TokenProvider | (() => string | null | Promise<string | null>) | null;
+/** Constructor options for {@link Oms}. */
+export interface OmsOptions {
+    /**
+     * The credential. Omit it for an anonymous client: several endpoints (short
+     * links, notepads, chests, the captcha-gated tools, ip lookup) work without
+     * one, at a smaller daily quota.
+     */
+    readonly token?: OmsCredential;
+    /**
+     * A provider that can refresh itself. Mutually exclusive with `token`;
+     * passing both throws. Build one with `refreshingTokenProvider`.
+     */
+    readonly tokens?: TokenProvider;
+    /** API root. Defaults to `https://backend.omelhorsite.pt`. */
+    readonly baseUrl?: string;
+    /**
+     * The fetch to talk through. Defaults to `globalThis.fetch`. Injecting one is
+     * how a Worker adds a cache, how a test swaps in a double, and how the CLI
+     * adds a proxy - the SDK never patches a global.
+     */
+    readonly fetch?: FetchLike;
+    /** Headers merged into every request, below per-call headers. */
+    readonly headers?: Record<string, string>;
+    /** Default deadline for one call including its retries. `0` disables it. */
+    readonly timeoutMs?: number;
+    /** Default backoff policy, or `false` to never retry. */
+    readonly retry?: RetryOptions | false;
+    /** Value for the `X-Oms-Client` header, e.g. `"oms-cli/0.3.1"`. */
+    readonly clientName?: string;
+}
+/**
+ * The omelhorsite API client.
+ *
+ * ```ts
+ * import { Oms } from "@omelhorsite/sdk";
+ *
+ * const oms = new Oms({ token: "..." });
+ * const me = await oms.account.me();
+ * const link = await oms.shortLinks.create({ url: "https://example.com" });
+ * ```
+ *
+ * Isolate-safe: no `node:*`, no environment, no stdout. A file is always a
+ * value (`Blob` / `Uint8Array` / `ReadableStream`), never a path.
+ */
+export declare class Oms {
+    /**
+     * The transport. Public on purpose: an endpoint the SDK has not wrapped yet
+     * is still reachable with `oms.http.get("/some/path")`, which beats forking
+     * the SDK to add one call.
+     */
+    readonly http: ApiClient;
+    /** Signing in, refreshing, revoking, and the RFC 8628 device grant. */
+    readonly auth: AuthNamespace;
+    /** The signed-in user, their profile, and their usage report. */
+    readonly account: AccountNamespace;
+    /** Support tickets and their message threads. */
+    readonly tickets: TicketsNamespace;
+    /** The virtual filesystem: nodes, uploads, downloads, sharing grants. */
+    readonly storage: StorageNamespace;
+    /** Short links and their click statistics. */
+    readonly shortLinks: ShortLinksNamespace;
+    /** Anonymous shared notepads. */
+    readonly notepads: NotepadsNamespace;
+    /** QR codes whose target can be changed after printing. */
+    readonly dynamicQrs: DynamicQrsNamespace;
+    /** Geolocation and network metadata for an IP address. */
+    readonly ipLookup: IpLookupNamespace;
+    /** Ephemeral drop boxes for passing files between devices. */
+    readonly chests: ChestsNamespace;
+    /** Hosted forms and their submissions. */
+    readonly forms: FormsNamespace;
+    /** Link-in-bio pages and their click statistics. */
+    readonly linkTrees: LinkTreesNamespace;
+    /** Background jobs: listing, polling and watching. There is no cancel. */
+    readonly jobs: JobsNamespace;
+    /** The metered media tools, each with its own daily quota. */
+    readonly tools: ToolsNamespace;
+    /**
+     * Pure client-side helpers that touch no network and need no credential
+     * (password generation, QR encoding). Also exported standalone as `local`,
+     * for a caller who wants them without building a client.
+     */
+    readonly local: LocalNamespace;
+    constructor(options?: OmsOptions);
+    /** The API root this client talks to, with no trailing slash. */
+    get baseUrl(): string;
+    /**
+     * A copy of this client with a different credential, sharing nothing else.
+     *
+     * Cheaper and safer than mutating: a token swap mid-flight would let an
+     * in-progress request finish under the wrong identity.
+     */
+    withToken(token: OmsCredential): Oms;
+    /** Convenience over {@link withToken} for an OAuth {@link TokenSet}. */
+    withTokenSet(tokens: TokenSet): Oms;
+}

package/dist/types/errors.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Error taxonomy for the omelhorsite SDK.
+ *
+ * Every failure that leaves the SDK is an {@link OmsError}. Callers are meant to
+ * branch on the class (or on {@link OmsApiError.status}), never on message text -
+ * the backend renders human strings in several shapes and they change.
+ *
+ * The API answers with at least four different error body shapes, so anything
+ * that reads an error body must go through {@link normalizeErrorBody}:
+ *
+ * - a bare JSON string:            `"Image too large"`            (ResponseHelpers)
+ * - a sentence from ActiveModel:   `"Name can't be blank and ..."` (error_messages)
+ * - an object with `error`:        `{"error":"rate_limited","retry_after":37}`
+ * - an object of field errors:     `{"errors":{"url":["is invalid"]}}`
+ * - plain text / HTML:             short-link 404 pages, proxy errors
+ */
+/** Machine-readable code carried by every SDK error. */
+export type OmsErrorCode = "api_error" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "invalid_request" | "quota_exceeded" | "rate_limited" | "server_error" | "timeout" | "aborted" | "network" | "unsupported" | "unknown";
+/** Extra context attached to an error, useful for logs and for the CLI. */
+export interface OmsErrorContext {
+    /** HTTP method of the failing request, when there was one. */
+    readonly method?: string;
+    /** Absolute URL of the failing request, with the query string. */
+    readonly url?: string;
+    /** How many attempts were spent before giving up (1 means no retry). */
+    readonly attempts?: number;
+    /** The underlying failure, when this error wraps another one. */
+    readonly cause?: unknown;
+}
+/**
+ * Base class for everything the SDK throws.
+ *
+ * `instanceof OmsError` is the one check that is always safe; the subclasses
+ * narrow the reason.
+ */
+export declare class OmsError extends Error {
+    /**
+     * This class's own name, as a LITERAL.
+     *
+     * `this.name = new.target.name` would be the obvious way to do this and it
+     * is wrong here: `bun build --minify` renames the classes, so the shipped
+     * `oms` binary reported `name: "A"` in its JSON error envelope while a dev
+     * run reported `OmsNetworkError`. A minifier renames identifiers, never
+     * string literals or property names, so a static literal survives the build.
+     *
+     * Every subclass shadows this, and `new.target` is the constructor that was
+     * actually called, so a subclass still reports its own name without
+     * repeating the assignment.
+     */
+    static readonly errorName: string;
+    /** Stable machine-readable reason. Safe to switch on. */
+    readonly code: OmsErrorCode;
+    /** HTTP method of the failing request, when the error came from one. */
+    readonly method: string | undefined;
+    /** Absolute URL of the failing request, when the error came from one. */
+    readonly url: string | undefined;
+    /** Attempts spent before the error was raised. `1` means it was not retried. */
+    readonly attempts: number | undefined;
+    constructor(message: string, code?: OmsErrorCode, context?: OmsErrorContext);
+    /**
+     * Whether retrying the exact same call could plausibly succeed. The
+     * {@link ApiClient} already retries what it is allowed to retry; this is for
+     * callers deciding whether to surface a "try again" affordance.
+     */
+    get retryable(): boolean;
+    /** Plain object for logging. Never includes the token. */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * The API answered, and the answer was an error status.
+ *
+ * `body` is the RAW parsed body exactly as the server sent it (string, array,
+ * object or `undefined`). It is deliberately untyped: read it when you know the
+ * endpoint, use `message` otherwise.
+ */
+export declare class OmsApiError extends OmsError {
+    static readonly errorName: string;
+    /** HTTP status code. */
+    readonly status: number;
+    /** Raw parsed response body. Untouched by the normalizer. */
+    readonly body: unknown;
+    /** Response headers, lowercased keys. Useful for `retry-after` / request ids. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** Per-field validation messages, when the body carried any. */
+    readonly fieldErrors: Readonly<Record<string, string[]>> | undefined;
+    constructor(message: string, options: {
+        status: number;
+        body?: unknown;
+        headers?: Record<string, string>;
+        code?: OmsErrorCode;
+        fieldErrors?: Record<string, string[]>;
+    } & OmsErrorContext);
+    get retryable(): boolean;
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * 401 or 403: the credential is missing, expired, or not allowed to do this.
+ *
+ * The CLI turns this into "run `oms auth login`"; the MCP server turns it into
+ * a device-flow prompt.
+ */
+export declare class OmsAuthError extends OmsApiError {
+    static readonly errorName: string;
+    /** True for 401 (no/blown credential), false for 403 (credential is fine, act is not). */
+    get authenticationRequired(): boolean;
+}
+/**
+ * 429, or a documented daily-quota rejection.
+ *
+ * Two different producers land here and they do not look alike:
+ * rack-attack answers `{"error":"rate_limited","retry_after":37}` with a
+ * `Retry-After` header, while a controller quota gate answers a bare string
+ * such as `"Daily edit quota reached (5/day)"` with no header at all. Read
+ * {@link retryAfterMs}; it is `undefined` in the second case.
+ */
+export declare class OmsQuotaError extends OmsApiError {
+    static readonly errorName: string;
+    /** Milliseconds to wait before retrying, when the server said. */
+    readonly retryAfterMs: number | undefined;
+    constructor(message: string, options: {
+        status: number;
+        body?: unknown;
+        headers?: Record<string, string>;
+        code?: OmsErrorCode;
+        retryAfterMs?: number;
+    } & OmsErrorContext);
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * The request did not finish inside its deadline, or the caller's
+ * `AbortSignal` fired.
+ *
+ * `code` is `"timeout"` for a deadline the SDK enforced and `"aborted"` when
+ * the caller's own signal aborted; check it before reporting a fault.
+ */
+export declare class OmsTimeoutError extends OmsError {
+    static readonly errorName: string;
+    /** The deadline that expired, in milliseconds, when there was one. */
+    readonly timeoutMs: number | undefined;
+    constructor(message: string, options?: {
+        timeoutMs?: number;
+        aborted?: boolean;
+    } & OmsErrorContext);
+    get retryable(): boolean;
+}
+/**
+ * `fetch` itself rejected: DNS, TLS, connection reset, offline. No HTTP status
+ * exists because no response was ever received, so a retry is always safe for
+ * a read and usually safe for a write that never left the machine.
+ */
+export declare class OmsNetworkError extends OmsError {
+    static readonly errorName: string;
+    constructor(message: string, context?: OmsErrorContext);
+}
+/** Maps an HTTP status onto the coarse machine code. */
+export declare function codeForStatus(status: number): OmsErrorCode;
+/** Result of running an arbitrary error body through {@link normalizeErrorBody}. */
+export interface NormalizedError {
+    /** A single human sentence. Never empty. */
+    readonly message: string;
+    /** A code the server named itself (`{"error":"rate_limited"}`), if any. */
+    readonly serverCode: string | undefined;
+    /** Per-field messages, when the body was shaped like ActiveModel errors. */
+    readonly fieldErrors: Record<string, string[]> | undefined;
+}
+/**
+ * Turns any error body the backend can produce into one sentence plus whatever
+ * structure was recoverable. This is the ONLY place that guesses at body
+ * shapes; resource modules must not re-implement it.
+ *
+ * Handles, in order: `undefined`/`null`, string (including a JSON-encoded
+ * string), array of anything, `{error}`, `{errors}` as array or as a field map,
+ * `{message}`, `{detail}`, `{title}`, and finally an opaque object (stringified
+ * and truncated).
+ *
+ * @param body Raw parsed body. Pass exactly what the transport read.
+ * @param fallback Sentence to use when nothing readable could be found.
+ */
+export declare function normalizeErrorBody(body: unknown, fallback?: string): NormalizedError;
+/**
+ * Reads a `Retry-After` header. RFC 9110 allows both delay-seconds and an
+ * HTTP-date; rack-attack sends seconds, but a proxy in front may not.
+ *
+ * @returns Milliseconds to wait, or `undefined` when the header is absent or junk.
+ */
+export declare function parseRetryAfter(value: string | null | undefined, now?: number): number | undefined;
+/**
+ * Builds the right {@link OmsApiError} subclass for a response the SDK already
+ * read. The transport calls this; resource modules never do.
+ *
+ * @param status HTTP status code.
+ * @param body Raw parsed body, exactly as read.
+ * @param context Method, URL, attempt count and response headers.
+ */
+export declare function apiErrorFromResponse(status: number, body: unknown, context?: OmsErrorContext & {
+    headers?: Record<string, string>;
+}): OmsApiError;
+/**
+ * Wraps an unknown thrown value as an {@link OmsError} without losing it.
+ * Anything already an OmsError is returned untouched.
+ */
+export declare function toOmsError(thrown: unknown, context?: OmsErrorContext): OmsError;

package/dist/types/http.d.ts

@@ -0,0 +1,204 @@
+/**
+ * The transport. Every request the SDK makes goes through {@link ApiClient}.
+ *
+ * Isolate-safe by construction: it imports nothing, reads no environment, and
+ * calls `fetch`, `AbortController`, `FormData`, `Blob` and `setTimeout` only -
+ * all of which a Cloudflare Worker provides. `fetch` itself is injected, so a
+ * host can wrap it (proxy, cache, test double) without patching a global.
+ */
+import { type FetchLike, type FileInput, type FileOutput, type QueryParams, type RequestOptions, type ResolvedRetry, type RetryOptions } from "./types";
+/** Production API root. Override only for a local backend or a test double. */
+export declare const DEFAULT_BASE_URL = "https://backend.omelhorsite.pt";
+/**
+ * Supplies the bearer token for each request.
+ *
+ * Implementations live in `auth/tokens.ts`. The transport never stores a token
+ * itself: it asks the provider on every request, so a refresh that happened
+ * elsewhere is picked up without rebuilding the client.
+ */
+export interface TokenProvider {
+    /**
+     * Current access token, or `null` when the caller is anonymous. May be async
+     * so an implementation can refresh an expired token before answering.
+     */
+    getToken(): string | null | Promise<string | null>;
+    /**
+     * Called once when the API answers 401 with the token this provider just
+     * gave. An implementation that can refresh should do so and return `true`;
+     * the transport then retries the request exactly once. Returning `false` (or
+     * not implementing this) lets the {@link OmsAuthError} propagate.
+     */
+    onUnauthorized?(): boolean | Promise<boolean>;
+}
+/** Anything accepted where a token is expected. */
+export type TokenLike = string | TokenProvider | (() => string | null | Promise<string | null>) | null | undefined;
+/** Constructor options for {@link ApiClient}. */
+export interface ApiClientOptions {
+    /** API root. Defaults to {@link DEFAULT_BASE_URL}. */
+    readonly baseUrl?: string;
+    /** Injected fetch. Defaults to the ambient `globalThis.fetch`. */
+    readonly fetch?: FetchLike;
+    /** Where the bearer token comes from. */
+    readonly tokens?: TokenProvider;
+    /** Headers merged into every request, below per-call headers. */
+    readonly headers?: Record<string, string>;
+    /** Default deadline for one call, retries included. `0` disables it. */
+    readonly timeoutMs?: number;
+    /** Default backoff policy, or `false` to never retry. */
+    readonly retry?: RetryOptions | false;
+    /**
+     * Value for the `X-Oms-Client` header, e.g. `"oms-cli/0.3.1"`. The SDK does
+     * not touch `User-Agent`: browsers forbid setting it and it tells us nothing
+     * a dedicated header does not.
+     */
+    readonly clientName?: string;
+}
+/** Body accepted by `post`/`patch`. `undefined` sends no body at all. */
+export type JsonBody = unknown;
+/** One field of a multipart form. */
+export type FormFieldValue = string | number | boolean | FileInput | null | undefined;
+/**
+ * Fields of a multipart form. An array value is appended once per entry with a
+ * `[]` suffix, which is how Rails reads a list (`clips[]`).
+ */
+export type FormFields = Record<string, FormFieldValue | FormFieldValue[]>;
+/** Options for a request that carries a query string. */
+export interface GetOptions extends RequestOptions {
+    readonly query?: QueryParams;
+}
+/**
+ * HTTP client for the omelhorsite API.
+ *
+ * Retry policy, deliberately narrow:
+ * - a `fetch` rejection (DNS, TLS, reset) is retried;
+ * - `5xx` is retried;
+ * - `429` is retried, waiting exactly what `Retry-After` asked for;
+ * - every other `4xx` fails immediately, on any method.
+ *
+ * The policy applies to all verbs, `POST` included. That is the documented
+ * behaviour, and it means a `POST` that the server processed before dying with
+ * a 502 can be replayed. Pass `retry: false` on any create where a duplicate
+ * is worse than a failure.
+ */
+export declare class ApiClient {
+    /** API root with no trailing slash. */
+    readonly baseUrl: string;
+    private readonly fetchImpl;
+    private readonly tokens;
+    private readonly baseHeaders;
+    private readonly timeoutMs;
+    private readonly retry;
+    constructor(options?: ApiClientOptions);
+    /** `GET`, parsed as JSON. */
+    get<T>(path: string, options?: GetOptions): Promise<T>;
+    /** `POST` with a JSON body, parsed as JSON. */
+    post<T>(path: string, body?: JsonBody, options?: GetOptions): Promise<T>;
+    /** `PATCH` with a JSON body, parsed as JSON. */
+    patch<T>(path: string, body?: JsonBody, options?: GetOptions): Promise<T>;
+    /** `PUT` with a JSON body, parsed as JSON. */
+    put<T>(path: string, body?: JsonBody, options?: GetOptions): Promise<T>;
+    /**
+     * `DELETE`, parsed as JSON. The API answers `204 No Content` for most
+     * destroys, which arrives here as `undefined`; type such calls as
+     * `delete<void>(...)`.
+     */
+    delete<T>(path: string, options?: GetOptions): Promise<T>;
+    /**
+     * `POST` a `multipart/form-data` body, parsed as JSON. Use this for every
+     * endpoint that takes an upload through Rails (the tools). Storage uploads
+     * do NOT go through here - they are presigned and go straight to the object
+     * store; see `resources/storage/upload.ts`.
+     *
+     * A {@link FileInput} carrying a `ReadableStream` is buffered into memory
+     * before it can be appended, because `FormData` has no streaming entry.
+     */
+    postForm<T>(path: string, fields: FormFields, options?: GetOptions): Promise<T>;
+    /**
+     * Escape hatch: performs the request and hands back the raw `Response`
+     * without reading it, so a caller can stream (`response.body`) a zip, a
+     * media file or an SSE endpoint. Retry and auth still apply.
+     *
+     * The caller owns the body and must consume or cancel it.
+     */
+    raw(method: string, path: string, options?: GetOptions & {
+        body?: BodyInit;
+    }): Promise<Response>;
+    /**
+     * `GET` that reads the whole response as a {@link FileOutput}, taking the
+     * filename from `Content-Disposition` when the server sent one.
+     */
+    download(path: string, options?: GetOptions): Promise<FileOutput>;
+    /** Absolute URL for a path, with the query string applied. */
+    url(path: string, query?: QueryParams): string;
+    private requestJson;
+    /** Performs the request, applying auth, deadline and the retry policy. */
+    private send;
+    private buildInit;
+    private resolveToken;
+}
+/**
+ * Base class for every resource namespace.
+ *
+ * Resource modules extend this instead of writing their own constructor, so
+ * every namespace is built the same way and `client.ts` can instantiate them
+ * uniformly.
+ */
+export declare abstract class Resource {
+    protected readonly http: ApiClient;
+    constructor(http: ApiClient);
+}
+/**
+ * Encodes query parameters the way Rails parses them.
+ *
+ * - `{ page: 2 }`                     -> `page=2`
+ * - `{ ids: ["a", "b"] }`             -> `ids%5B%5D=a&ids%5B%5D=b`
+ * - `{ search: { status: "open" } }`  -> `search%5Bstatus%5D=open`
+ * - `undefined` / `null` values are dropped, never sent as an empty string.
+ */
+export declare function encodeQuery(params: QueryParams): string;
+/**
+ * Builds the `modifiers[page]` string the backend expects (`"2:100"`).
+ * Page size is clamped to the server maximum so a caller cannot silently ask
+ * for more and get 500 back without knowing.
+ */
+export declare function pageModifier(page?: number, pageSize?: number): string;
+/** Turns a {@link FormFields} bag into a `FormData`, buffering any streams. */
+export declare function buildFormData(fields: FormFields): Promise<FormData>;
+/** Narrows an unknown form value to a {@link FileInput}. */
+export declare function isFileInput(value: unknown): value is FileInput;
+/** Fills in whatever a partial {@link RetryOptions} left out. */
+export declare function resolveRetry(options: RetryOptions | undefined): ResolvedRetry;
+/** Exponential backoff for `attempt` (1-based), with optional jitter. */
+export declare function backoffDelay(attempt: number, retry: ResolvedRetry): number;
+/**
+ * Waits, but wakes early and rejects if the caller's signal aborts. Uses only
+ * `setTimeout`, which a Worker isolate provides.
+ */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * Combines a deadline with the caller's signal into one signal.
+ *
+ * Written by hand rather than with `AbortSignal.any` + `AbortSignal.timeout`
+ * so the SDK runs on any runtime that has plain `AbortController`.
+ */
+export declare function createDeadline(timeoutMs: number, signal: AbortSignal | undefined): {
+    signal: AbortSignal;
+    dispose(): void;
+    timedOut(): boolean;
+};
+/** Response headers as a plain object with lowercased keys. */
+export declare function headerRecord(headers: Headers): Record<string, string>;
+/**
+ * Reads a successful response.
+ *
+ * `204` and an empty body both come back as `undefined`. A non-JSON body is
+ * returned as text, because a handful of endpoints answer `text/plain`.
+ */
+export declare function readJson(response: Response): Promise<unknown>;
+/** Reads an error response without ever throwing on a malformed body. */
+export declare function readErrorBody(response: Response): Promise<unknown>;
+/**
+ * Pulls the filename out of a `Content-Disposition` header, preferring the
+ * RFC 5987 `filename*` form when both are present.
+ */
+export declare function filenameFromDisposition(header: string | null): string | undefined;

package/dist/types/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `@omelhorsite/sdk` - the TypeScript client for the omelhorsite API.
+ *
+ * ```ts
+ * import { Oms } from "@omelhorsite/sdk";
+ *
+ * const oms = new Oms({ token: process.env.OMS_TOKEN }); // in HOST code, not here
+ * const link = await oms.shortLinks.create({ url: "https://example.com" });
+ * ```
+ *
+ * This package is the product; the CLI and the MCP server are two clients of
+ * it. Three rules make that work, and they are not negotiable:
+ *
+ * 1. It runs in a Cloudflare-Worker-class isolate. No `node:*`, no `process`,
+ *    no filesystem, no stdout. `fetch` is injectable through the constructor.
+ * 2. Files are values - `Blob`, `Uint8Array`, `ReadableStream` - never paths.
+ *    Turning a path into bytes is the host's job.
+ * 3. The TYPES are the public interface. In code mode a model reads the `.d.ts`
+ *    and nothing else, so a name or a JSDoc line carries as much weight as the
+ *    behaviour behind it.
+ *
+ * Everything is re-exported flat. There is no deep-import path into `src/`,
+ * so internals can move without breaking a caller.
+ */
+export * from "./auth/index";
+export * from "./client";
+export * from "./errors";
+export * from "./http";
+export * from "./local/index";
+export * from "./resources/index";
+export * from "./types";
+import { Oms } from "./client";
+export default Oms;

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

@@ -0,0 +1,42 @@
+/**
+ * The `local` namespace: tools that run entirely on the caller's side.
+ *
+ * Two of the site's tools never touch the API - the password generator and the
+ * QR renderer - and there is no reason to make a network round trip to use
+ * them from the SDK. They live here, grouped so they are discoverable next to
+ * everything else, and reachable BOTH as `oms.local.password.generate(...)` and
+ * as a bare `import { generatePassword } from "@omelhorsite/sdk"`.
+ *
+ * Nothing in here takes an {@link ApiClient}, so nothing in here can be a
+ * {@link Resource}. That is the tell: if a function needs a credential or a
+ * base URL, it belongs under `resources/`, not here.
+ *
+ * Re-exports every sibling module so nobody has to touch this file again.
+ */
+import { generatePassphrase, generatePassword, passwordEntropyBits, passwordStrength } from "./password";
+import { encodeQr, qrToDataUri, qrToSvg } from "./qr";
+export * from "./password";
+export * from "./qr";
+/**
+ * The grouped form, mounted on the client as `oms.local`.
+ *
+ * Frozen: it is shared by every client instance, so a mutation would leak
+ * across them.
+ */
+export declare const local: Readonly<{
+    /** Password and passphrase generation, backed by WebCrypto. */
+    password: Readonly<{
+        generate: typeof generatePassword;
+        passphrase: typeof generatePassphrase;
+        strength: typeof passwordStrength;
+        entropyBits: typeof passwordEntropyBits;
+    }>;
+    /** QR encoding and SVG rendering. */
+    qr: Readonly<{
+        encode: typeof encodeQr;
+        toSvg: typeof qrToSvg;
+        toDataUri: typeof qrToDataUri;
+    }>;
+}>;
+/** Type of the grouped {@link local} namespace. */
+export type LocalNamespace = typeof local;