@kleora-io/core 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Kleora
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,44 @@
+# `@kleora-io/core`
+
+The code the Kleora CLI ([`@kleora-io/cli`](../cli)) and the Kleora MCP server
+(`@kleora-io/mcp`) share:
+
+- **the credential store**: the refresh token in the OS keychain (through the
+  optional `@napi-rs/keyring`), falling back to a mode-`0600` file under the
+  user's config directory. Never an environment variable, never a command-line
+  argument;
+- **the device-grant client** (RFC 8628): start an authorization, poll for the
+  token, refresh it, revoke it (RFC 7009);
+- **issuer discovery**: the issuer a device grant runs against is what the
+  deployment reports at `GET /api/v1/platform`, unless one is given explicitly;
+- **the session**: one profile's credential lifecycle, with the access token
+  held in memory only;
+- **a generic management API client**: a thin `fetch` wrapper that calls one
+  operation of the management API with the caller's own bearer token, with
+  bounded `Retry-After` handling and a cap on concurrent requests;
+- **the error types** both tools throw and render, including the RFC 9457
+  problem document as `ApiError`.
+
+Each tool keeps its own configuration, `User-Agent`, OAuth client, keychain
+service and config directory. They share the code, never a stored credential.
+
+This is a library for building Kleora's own local tools. If you are integrating
+Kleora into an application, you want one of the SDKs instead
+(`@kleora-io/node`, `@kleora-io/browser`, `@kleora-io/nuxt`); Kleora's
+documentation is at https://kleora.io/en/docs.
+
+## Install
+
+```bash
+npm install @kleora-io/core
+```
+
+Node 20 or newer, ESM only.
+
+## Versioning
+
+`@kleora-io/core` and `@kleora-io/cli` are released together from
+[`kleora-io/kleora-cli`](https://github.com/kleora-io/kleora-cli) and carry the
+same version.
+
+Licensed under Apache-2.0; see `LICENSE`.

package/dist/index.d.ts

@@ -0,0 +1,363 @@
+/**
+ * The error shapes the two local tools throw and pass through.
+ *
+ * Declared here rather than imported from `@kleora-io/node`: neither tool
+ * depends on any published SDK. The tools have no database connection and no
+ * service credential of their own, and the same isolation argument applies to
+ * code: a process that administers a person's whole
+ * Account should not inherit behaviour from a package meant for verifying
+ * end-user tokens in someone else's backend).
+ *
+ * One copy, not two, and that is a correctness requirement rather than
+ * tidiness: the MCP server and the CLI both render these, and a second
+ * `ApiError` in the dependency graph would make `instanceof` lie in whichever
+ * of them imported the other's.
+ */
+/** Base class for everything these packages throw. */
+declare class KleoraToolError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string, options?: ErrorOptions);
+}
+/**
+ * What `ApiError` carries beyond `type`/`status`/`detail` — the same shape
+ * `@kleora-io/node` calls `ProblemDetails`.
+ */
+interface ProblemDetails {
+    /** The RFC 9457 document exactly as it arrived, extension members included. */
+    document: Record<string, unknown>;
+    /** `Retry-After` in seconds, falling back to the document's `retry_after`. */
+    retryAfter: number | null;
+    requestId: string | undefined;
+}
+/**
+ * An RFC 9457 problem document from the management API, passed through with
+ * its `type`, `title`, `detail` and `status`.
+ */
+declare class ApiError extends KleoraToolError {
+    readonly type: string;
+    readonly title: string | undefined;
+    readonly status: number;
+    readonly detail: string | undefined;
+    readonly problem: ProblemDetails;
+    constructor(type: string, status: number, title: string | undefined, detail: string | undefined, problem: ProblemDetails);
+    /** The RFC 9457 document, verbatim plus its four standard fields. */
+    toProblemDocument(): Record<string, unknown>;
+}
+/**
+ * The management API could not be reached at all — refused, timed out, DNS
+ * failure. Deliberately distinguishable from a permission failure: an agent
+ * or a script must not read an outage as "you cannot do that".
+ */
+declare class ManagementApiUnreachable extends KleoraToolError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * The person denied the device approval (RFC 8628 `access_denied`). Surfaced
+ * plainly; nothing is stored.
+ */
+declare class AuthorizationDenied extends KleoraToolError {
+    constructor();
+}
+
+/** One stored credential, keyed by profile. */
+interface CredentialStore {
+    get(profile: string): Promise<string | null>;
+    set(profile: string, refreshToken: string): Promise<void>;
+    delete(profile: string): Promise<void>;
+    /** For `kleora_whoami` and diagnostics — never the secret itself. */
+    readonly backend: 'keychain' | 'file';
+}
+/**
+ * Which store a tool is asking for. The two tools deliberately do **not**
+ * share a stored credential and cannot: a refresh token is bound to the
+ * OAuth client it was issued to, and each tool is its own client. What they
+ * share is this code.
+ *
+ * A single `~/.kleora` directory would be tidier and is deliberately not
+ * done — moving a live credential store makes every existing MCP user sign in
+ * again for no benefit they can see.
+ */
+interface CredentialStoreOptions {
+    /** The keychain service name: `kleora-mcp` or `kleora-cli`. */
+    service: string;
+    /** Where the `0600` fallback lives: `~/.kleora-mcp` or `~/.kleora-cli`. */
+    configDir: string;
+}
+/** `~/.<name>`; overridable for tests, never by a flag a person sets. */
+declare function defaultConfigDir(name: string): string;
+/**
+ * Tries the OS keychain via `@napi-rs/keyring` (an optional dependency); falls
+ * back to the file store the moment
+ * loading it, or any one call to it, fails. A Linux box with no secret
+ * service running is the ordinary case this exists for, not an edge case:
+ * the fallback has to work as well as the keychain does, not merely exist.
+ */
+declare function createCredentialStore({ service, configDir, }: CredentialStoreOptions): Promise<CredentialStore>;
+/**
+ * A `0600` file per profile under `configDir`. `mode` on `writeFileSync` is
+ * still subject to the process umask, so every write is followed by an
+ * explicit `chmodSync` — the guarantee is the final permission bits, not
+ * merely the flag passed to the syscall that created the file.
+ */
+declare class FileCredentialStore implements CredentialStore {
+    #private;
+    readonly backend = "file";
+    constructor(dir: string);
+    get(profile: string): Promise<string | null>;
+    set(profile: string, refreshToken: string): Promise<void>;
+    delete(profile: string): Promise<void>;
+}
+
+interface DeviceAuthorization {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete: string;
+    expiresIn: number;
+    interval: number;
+}
+interface Tokens {
+    accessToken: string;
+    refreshToken: string | undefined;
+    expiresIn: number;
+}
+/** RFC 8628 section 3.2 / RFC 6749 section 5.2 error codes this module distinguishes. */
+type OAuthErrorCode = 'authorization_pending' | 'slow_down' | 'access_denied' | 'expired_token' | 'invalid_grant' | 'unauthorized_client' | 'other';
+declare class OAuthError extends Error {
+    readonly code: OAuthErrorCode;
+    constructor(code: OAuthErrorCode, description: string | undefined);
+}
+interface DeviceGrantOptions {
+    issuer: string;
+    clientId: string;
+    /**
+     * `kleora-mcp/{version}` or `kleora-cli/{version}`. Passed in rather than
+     * read from a constant here, because this module is shared and the whole
+     * value of the two tools having their own OAuth client is that an audit event
+     * can say which of them acted — a shared `User-Agent` would undo half of that
+     * in the request log.
+     */
+    userAgent: string;
+    fetch: typeof globalThis.fetch;
+}
+/** RFC 8628 sections 3.1–3.2: `POST /oauth/device_authorization`. */
+declare function startDeviceAuthorization({ issuer, clientId, userAgent, fetch: fetchImpl, }: DeviceGrantOptions): Promise<DeviceAuthorization>;
+/**
+ * One poll of `POST /oauth/token` with
+ * `urn:ietf:params:oauth:grant-type:device_code`. Throws `OAuthError` for
+ * every RFC 8628 poll outcome that is not success — the caller
+ * (`session.ts`) is what turns `authorization_pending` into "not an error,
+ * this is the sign-in".
+ */
+declare function pollDeviceToken({ issuer, clientId, deviceCode, userAgent, fetch: fetchImpl, }: DeviceGrantOptions & {
+    deviceCode: string;
+}): Promise<Tokens>;
+/** `grant_type=refresh_token`, for a stored credential. The refresh token rotates on every use. */
+declare function refreshAccessToken({ issuer, clientId, refreshToken, userAgent, fetch: fetchImpl, }: DeviceGrantOptions & {
+    refreshToken: string;
+}): Promise<Tokens>;
+/**
+ * RFC 7009 section 2.1: `POST /oauth/revoke` with the refresh token, which
+ * revokes its whole rotation family and writes one
+ * `refresh_token.revoked` audit event.
+ *
+ * This is the server-side half of "uninstalling leaves no live credential
+ * behind": deleting the stored token alone would leave the
+ * authorization itself alive and refreshable by anyone who had copied the
+ * file. An unknown or already-dead token answers `200` with no effect
+ * (RFC 7009 section 2.2), so calling this twice is not an error.
+ */
+declare function revokeRefreshToken({ issuer, clientId, refreshToken, userAgent, fetch: fetchImpl, }: DeviceGrantOptions & {
+    refreshToken: string;
+}): Promise<void>;
+
+declare const PLATFORM_PATH = "/api/v1/platform";
+interface IssuerDiscoveryOptions {
+    /** The management API's origin, e.g. `https://api.kleora.io`, no trailing slash. */
+    baseUrl: string;
+    userAgent: string;
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * `GET {baseUrl}/api/v1/platform` → its `issuer`, without a trailing slash.
+ *
+ * Every failure is a `ManagementApiUnreachable` naming the URL it asked, because
+ * the only thing a person can do about any of them is check the base URL or
+ * pass the issuer explicitly — and the message says both.
+ */
+declare function discoverIssuer({ baseUrl, userAgent, fetch: fetchImpl, }: IssuerDiscoveryOptions): Promise<string>;
+/**
+ * The issuer to use, asked for at most once: `explicit` when given, otherwise
+ * whatever `discoverIssuer` answers.
+ *
+ * Lazy on purpose. A command that never reaches the issuer — anything run
+ * under an API key, `--help`, a usage error — makes no discovery request, and a
+ * long-lived MCP server makes one per process rather than one per tool call. A
+ * failed discovery is not remembered, so the next call asks again.
+ */
+declare function issuerResolver(explicit: string | undefined, options: IssuerDiscoveryOptions): () => Promise<string>;
+
+interface SessionOptions {
+    /**
+     * The platform issuer, or a function that finds it (`issuerResolver`). A
+     * function is called only when a request to the issuer is actually about to
+     * be made, so a session that never refreshes never asks.
+     */
+    issuer: string | (() => Promise<string>);
+    clientId: string;
+    profile: string;
+    store: CredentialStore;
+    /** `kleora-mcp/{version}` or `kleora-cli/{version}`. */
+    userAgent: string;
+    fetch?: typeof globalThis.fetch;
+    /** Access tokens are treated as expired this many seconds early. */
+    clockSkewSeconds?: number;
+}
+type SessionState = {
+    status: 'ready';
+    accessToken: string;
+} | {
+    status: 'authorization_required';
+    verificationUri: string;
+    verificationUriComplete: string;
+    userCode: string;
+    message: string;
+} | {
+    status: 'denied';
+};
+type NotReadyState = Exclude<SessionState, {
+    status: 'ready';
+}>;
+/**
+ * Thrown by the `getAccessToken` callback a `ManagementClient` is built
+ * with, when the session is not `ready`. The MCP server catches this and
+ * turns it into a tool result that says "not an error — this is the sign-in"
+ * rather than letting it surface as a protocol-level failure.
+ */
+declare class SessionNotReady extends Error {
+    readonly state: NotReadyState;
+    constructor(state: NotReadyState);
+}
+declare class Session {
+    #private;
+    constructor(options: SessionOptions);
+    /**
+     * The access token to call the management API with, or the instructions to
+     * show the person instead of a result: "not an error — this is the
+     * sign-in."
+     */
+    ensureAccessToken(): Promise<SessionState>;
+    /**
+     * An access token from the **stored** credential only — never starting a
+     * device flow.
+     *
+     * This is the CLI's entry point rather than `ensureAccessToken` above, and
+     * the difference is a deliberate behavioural split rather than a
+     * convenience. With no credential for the profile, a CLI command says so
+     * and names `kleora login`, exiting `3`. **It does not start a device flow
+     * unbidden**: an interactive sign-in in the middle of a piped command is a
+     * hang.
+     *
+     * An MCP host, by contrast, has a place to show a verification URL and a
+     * turn to show it on, which is why `ensureAccessToken` may begin one there.
+     * `null` means "nothing stored, or what was stored is dead and has been
+     * deleted" — both of which the caller answers with the same sentence.
+     */
+    accessTokenFromStoredCredential(): Promise<string | null>;
+    /** Forces the next call to re-authorise, even if a token is cached in memory. */
+    invalidate(): void;
+}
+
+/** What this client needs to know about an operation in order to call it. */
+interface Operation {
+    readonly operationId: string;
+    readonly method: 'get' | 'post' | 'put' | 'patch' | 'delete';
+    readonly path: string;
+    readonly pathParams: readonly string[];
+    readonly queryParams: readonly string[];
+    readonly hasBody: boolean;
+}
+interface ManagementClientOptions {
+    baseUrl: string;
+    /** Resolves to a fresh bearer token for every call — never cached here. */
+    getAccessToken: () => Promise<string>;
+    /** `kleora-mcp/{version}` or `kleora-cli/{version}`. */
+    userAgent: string;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+    /**
+     * Concurrent requests this client will have in flight at once: a small
+     * number, deliberately. A host that fires several tool calls at once, or a
+     * `--all` walk, must not turn a local tool into a burst against the
+     * account's own limits.
+     */
+    maxConcurrent?: number;
+    /**
+     * Called once per attempt, for the CLI's `--debug`, which prints the
+     * request method, path, status, duration and `X-Request-Id` of every call
+     * to stderr. It is
+     * handed no credential and no body, which is what makes `--debug` output
+     * safe to paste into a support reply.
+     */
+    onTrace?: (trace: RequestTrace) => void;
+}
+/** What `--debug` prints. Deliberately carries nothing secret. */
+interface RequestTrace {
+    method: string;
+    /** Path and query only — never the `Authorization` header, never a body. */
+    path: string;
+    /** `null` when nothing answered at all. */
+    status: number | null;
+    durationMs: number;
+    requestId: string | undefined;
+    /** Set when the request failed before a status existed. */
+    error?: string;
+}
+interface CallOptions {
+    /**
+     * Extra request headers: `Idempotency-Key` on a write, `X-Request-Id` when
+     * the caller wants to correlate one. **Never a credential** — the only
+     * `Authorization` header this client sends is the one it builds from
+     * `getAccessToken`, and it is applied after these so a caller cannot
+     * replace it.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Whether repeating this request is safe after a `429`. Defaults to `true`.
+     * A non-idempotent `POST` is never retried without an `Idempotency-Key`, so
+     * a caller making a keyless `POST` passes `false`.
+     */
+    idempotent?: boolean;
+}
+/** A response, body included as the bytes that arrived. */
+interface RawResponse {
+    status: number;
+    /**
+     * The body exactly as it arrived, unparsed. The CLI's `--json` prints the
+     * response body as it arrived, not a re-serialisation of a parsed object,
+     * which is what lets an older CLI against a newer API pass
+     * through fields it has never heard of.
+     */
+    text: string;
+    headers: Headers;
+}
+interface OperationArgs {
+    [name: string]: unknown;
+}
+declare class ManagementClient {
+    #private;
+    readonly baseUrl: string;
+    constructor(options: ManagementClientOptions);
+    /**
+     * Calls one operation and parses the body. `args` is a flat argument
+     * object; this method is what splits it back into path, query and body using
+     * the operation's own metadata — never a lookup this package invents.
+     */
+    call(operation: Operation, args: OperationArgs, options?: CallOptions): Promise<unknown>;
+    /** The same call, with the body left as the bytes that arrived. */
+    request(operation: Operation, args: OperationArgs, options?: CallOptions): Promise<RawResponse>;
+}
+/** `Retry-After` in seconds, from either the delta-seconds or the HTTP-date form. */
+declare function retryAfterSeconds(response: Response): number | null;
+
+export { ApiError, AuthorizationDenied, type CallOptions, type CredentialStore, type CredentialStoreOptions, type DeviceAuthorization, type DeviceGrantOptions, FileCredentialStore, type IssuerDiscoveryOptions, KleoraToolError, ManagementApiUnreachable, ManagementClient, type ManagementClientOptions, type NotReadyState, OAuthError, type OAuthErrorCode, type Operation, type OperationArgs, PLATFORM_PATH, type ProblemDetails, type RawResponse, type RequestTrace, Session, SessionNotReady, type SessionOptions, type SessionState, type Tokens, createCredentialStore, defaultConfigDir, discoverIssuer, issuerResolver, pollDeviceToken, refreshAccessToken, retryAfterSeconds, revokeRefreshToken, startDeviceAuthorization };