@mantyx/sdk 0.9.0 → 0.10.0

package/dist/index.cjs

@@ -32,17 +32,23 @@ var index_exports = {};
 __export(index_exports, {
   AgentSession: () => AgentSession,
   DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
+  DEFAULT_OAUTH_BASE_URL: () => DEFAULT_OAUTH_BASE_URL,
+  DEFAULT_REFRESH_SKEW_MS: () => DEFAULT_REFRESH_SKEW_MS,
   MantyxAuthError: () => MantyxAuthError,
   MantyxClient: () => MantyxClient,
   MantyxError: () => MantyxError,
   MantyxNetworkError: () => MantyxNetworkError,
+  MantyxOAuthClient: () => MantyxOAuthClient,
+  MantyxOAuthError: () => MantyxOAuthError,
   MantyxParseError: () => MantyxParseError,
   MantyxRunError: () => MantyxRunError,
+  MantyxScopeError: () => MantyxScopeError,
   MantyxToolError: () => MantyxToolError,
   SDK_VERSION: () => SDK_VERSION,
   defineLocalA2A: () => defineLocalA2A,
   defineLocalMcp: () => defineLocalMcp,
   defineLocalTool: () => defineLocalTool,
+  generatePkceVerifier: () => generatePkceVerifier,
   isLocalA2ATool: () => isLocalA2ATool,
   isLocalMcpServer: () => isLocalMcpServer,
   isLocalTool: () => isLocalTool,
@@ -51,6 +57,7 @@ __export(index_exports, {
   mantyxPluginTool: () => mantyxPluginTool,
   mantyxTool: () => mantyxTool,
   parseRunOutput: () => parseRunOutput,
+  pkceChallenge: () => pkceChallenge,
   readSseStream: () => readSseStream,
   toToolParametersWire: () => toToolParametersWire,
   zodToJsonSchema: () => zodToJsonSchema
@@ -80,11 +87,23 @@ var MantyxNetworkError = class extends MantyxError {
   }
 };
 var MantyxAuthError = class extends MantyxError {
-  constructor(message = "Invalid or missing API key") {
+  constructor(message = "Invalid or missing API key / OAuth access token") {
     super(message, { code: "unauthorized", status: 401 });
     this.name = "MantyxAuthError";
   }
 };
+var MantyxScopeError = class extends MantyxError {
+  /**
+   * Scope(s) the route demanded. Always at least one entry; usually
+   * exactly one. New routes may demand more scopes in the future.
+   */
+  requiredScopes;
+  constructor(message, requiredScopes) {
+    super(message, { code: "insufficient_scope", status: 403 });
+    this.name = "MantyxScopeError";
+    this.requiredScopes = [...requiredScopes];
+  }
+};
 var MantyxToolError = class extends MantyxError {
   toolName;
   constructor(toolName, message) {
@@ -98,11 +117,23 @@ var MantyxToolError = class extends MantyxError {
 var MantyxRunError = class extends MantyxError {
   runId;
   subtype;
-  constructor(runId, subtype, message) {
+  /** See {@link MantyxRunErrorInit.errorClass}. */
+  errorClass;
+  /** See {@link MantyxRunErrorInit.finishReason}. */
+  finishReason;
+  /** See {@link MantyxRunErrorInit.partialText}. */
+  partialText;
+  /** See {@link MantyxRunErrorInit.retryable}. */
+  retryable;
+  constructor(runId, subtype, message, init = {}) {
     super(message, { code: subtype });
     this.name = "MantyxRunError";
     this.runId = runId;
     this.subtype = subtype;
+    this.errorClass = init.errorClass;
+    this.finishReason = init.finishReason;
+    this.partialText = init.partialText;
+    this.retryable = init.retryable;
   }
 };
 var MantyxParseError = class extends MantyxError {
@@ -623,9 +654,7 @@ var DEFAULT_BASE_URL = "https://app.mantyx.io";
 var MantyxClient = class {
   options;
   constructor(opts) {
-    if (!opts.apiKey || typeof opts.apiKey !== "string") {
-      throw new MantyxError("apiKey is required");
-    }
+    const { credential, tokenSource } = resolveCredential(opts);
     if (!opts.workspaceSlug || typeof opts.workspaceSlug !== "string") {
       throw new MantyxError("workspaceSlug is required");
     }
@@ -636,11 +665,12 @@ var MantyxClient = class {
       );
     }
     this.options = {
-      apiKey: opts.apiKey,
+      apiKey: credential,
       workspaceSlug: opts.workspaceSlug,
       baseUrl: (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, ""),
       fetch: f,
-      timeoutMs: opts.timeoutMs ?? 6e4
+      timeoutMs: opts.timeoutMs ?? 6e4,
+      tokenSource
     };
   }
   // -------------------------------------------------------------- Models
@@ -758,7 +788,13 @@ var MantyxClient = class {
         }
       } else if (ev.type === "error") {
         const e = ev;
-        throw new MantyxRunError(runId, e.code ?? "error", e.error);
+        const subtype = e.errorClass ?? e.code ?? "error";
+        throw new MantyxRunError(runId, subtype, e.error, {
+          ...e.errorClass !== void 0 ? { errorClass: e.errorClass } : {},
+          ...e.finishReason !== void 0 ? { finishReason: e.finishReason } : {},
+          ...typeof e.partialText === "string" ? { partialText: e.partialText } : {},
+          ...typeof e.retryable === "boolean" ? { retryable: e.retryable } : {}
+        });
       } else if (ev.type === "cancelled") {
         throw new MantyxRunError(runId, "cancelled", "Run was cancelled");
       }
@@ -770,19 +806,7 @@ var MantyxClient = class {
     let lastSeq = 0;
     while (true) {
       const reqUrl = lastSeq > 0 ? `${url}?lastSeq=${lastSeq}` : url;
-      const res = await this.options.fetch(reqUrl, {
-        method: "GET",
-        headers: {
-          ...this.authHeaders(),
-          Accept: "text/event-stream",
-          ...lastSeq > 0 ? { "Last-Event-ID": String(lastSeq) } : {}
-        },
-        ...signal ? { signal } : {}
-      }).catch((err) => {
-        throw new MantyxNetworkError(`Failed to open SSE stream: ${err.message}`, {
-          cause: err
-        });
-      });
+      const res = await this.openSseStream(reqUrl, lastSeq, signal);
       if (!res.ok) {
         throw await this.errorFromResponse(res);
       }
@@ -885,18 +909,72 @@ var MantyxClient = class {
   absoluteUrl(path) {
     return `${this.options.baseUrl}/api/v1/workspaces/${encodeURIComponent(this.options.workspaceSlug)}${path}`;
   }
-  authHeaders() {
-    return { Authorization: `Bearer ${this.options.apiKey}` };
+  /**
+   * Resolve the bearer credential to send on the next request. With a
+   * static `apiKey` / `accessToken` this is a synchronous reach into
+   * `options.apiKey`; with a {@link TokenSource} it delegates so the
+   * source can refresh expired access tokens before we hit the wire.
+   *
+   * The `reason` is forwarded to the source verbatim. Pass
+   * `"unauthorized"` immediately after a 401 so the source forces a
+   * refresh rather than handing back its (now-invalid) cached value.
+   */
+  async resolveBearer(reason = "initial") {
+    if (this.options.tokenSource) return this.options.tokenSource(reason);
+    return this.options.apiKey;
+  }
+  /**
+   * Open an SSE stream against `reqUrl` with at-most-one refresh +
+   * retry on 401. The caller is responsible for the subsequent
+   * `readSseStream` loop; this helper only handles the initial GET.
+   * Mid-stream 401s propagate as `MantyxNetworkError` from the read
+   * loop and trigger a reconnect via the outer `while` in
+   * {@link streamRunEvents}.
+   */
+  async openSseStream(reqUrl, lastSeq, signal) {
+    const openOnce = async (reason) => {
+      const auth = await this.authHeaders(reason);
+      return this.options.fetch(reqUrl, {
+        method: "GET",
+        headers: {
+          ...auth,
+          Accept: "text/event-stream",
+          ...lastSeq > 0 ? { "Last-Event-ID": String(lastSeq) } : {}
+        },
+        ...signal ? { signal } : {}
+      }).catch((err) => {
+        throw new MantyxNetworkError(`Failed to open SSE stream: ${err.message}`, {
+          cause: err
+        });
+      });
+    };
+    const res = await openOnce("initial");
+    if (res.status === 401 && this.options.tokenSource !== null) {
+      try {
+        await res.text();
+      } catch {
+      }
+      return openOnce("unauthorized");
+    }
+    return res;
+  }
+  async authHeaders(reason = "initial") {
+    const bearer = await this.resolveBearer(reason);
+    return { Authorization: `Bearer ${bearer}` };
   }
   async request(args) {
+    return this.requestWithRetry(args, "initial");
+  }
+  async requestWithRetry(args, reason) {
     const url = this.absoluteUrl(args.path);
     const ctrl = new AbortController();
     const t = setTimeout(() => ctrl.abort(), args.timeoutMs ?? this.options.timeoutMs);
     try {
+      const auth = await this.authHeaders(reason);
       const res = await this.options.fetch(url, {
         method: args.method,
         headers: {
-          ...this.authHeaders(),
+          ...auth,
           ...args.body !== void 0 ? { "Content-Type": "application/json" } : {},
           Accept: "application/json"
         },
@@ -909,6 +987,14 @@ var MantyxClient = class {
         throw new MantyxNetworkError(`Network error: ${err.message}`, { cause: err });
       });
       if (!res.ok) {
+        if (res.status === 401 && this.options.tokenSource !== null && reason === "initial") {
+          try {
+            await res.text();
+          } catch {
+          }
+          clearTimeout(t);
+          return this.requestWithRetry(args, "unauthorized");
+        }
         throw await this.errorFromResponse(res);
       }
       const text = await res.text();
@@ -929,7 +1015,12 @@ var MantyxClient = class {
     } catch {
     }
     if (res.status === 401) {
-      return new MantyxAuthError(body.error ?? "Invalid API key");
+      return new MantyxAuthError(body.error ?? "Invalid API key or OAuth access token");
+    }
+    if (res.status === 403 && (body.error === "insufficient_scope" || body.code === "insufficient_scope")) {
+      const required = parseRequiredScopes(body.required, res.headers.get("WWW-Authenticate"));
+      const msg = required.length > 0 ? `Missing OAuth scope${required.length > 1 ? "s" : ""}: ${required.join(", ")}` : "OAuth access token is missing a required scope";
+      return new MantyxScopeError(msg, required);
     }
     return new MantyxError(body.error ?? `HTTP ${res.status}`, {
       code: body.code ?? `http_${res.status}`,
@@ -1295,24 +1386,342 @@ function parseRunOutput(result, validator) {
 function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
+function resolveCredential(opts) {
+  const apiKey = typeof opts.apiKey === "string" ? opts.apiKey : "";
+  const accessToken = typeof opts.accessToken === "string" ? opts.accessToken : "";
+  const tokenSource = typeof opts.tokenSource === "function" ? opts.tokenSource : null;
+  const provided = [apiKey ? "apiKey" : "", accessToken ? "accessToken" : "", tokenSource ? "tokenSource" : ""].filter((s) => s.length > 0);
+  if (provided.length > 1) {
+    throw new MantyxError(
+      `Pass exactly one of \`apiKey\`, \`accessToken\`, or \`tokenSource\` \u2014 got ${provided.join(" + ")}.`
+    );
+  }
+  if (provided.length === 0) {
+    throw new MantyxError(
+      "One of `apiKey` (workspace API key), `accessToken` (OAuth access token), or `tokenSource` (dynamic credential provider) is required"
+    );
+  }
+  return {
+    credential: apiKey || accessToken,
+    tokenSource
+  };
+}
+function parseRequiredScopes(bodyRequired, wwwAuthenticate) {
+  if (Array.isArray(bodyRequired)) {
+    return bodyRequired.filter((s) => typeof s === "string" && s.length > 0);
+  }
+  if (typeof bodyRequired === "string" && bodyRequired.length > 0) {
+    return [bodyRequired];
+  }
+  if (typeof wwwAuthenticate === "string") {
+    const m = /scope="([^"]+)"/i.exec(wwwAuthenticate);
+    if (m && m[1]) {
+      return m[1].split(/\s+/).filter((s) => s.length > 0);
+    }
+  }
+  return [];
+}
+
+// src/oauth.ts
+var import_node_buffer = require("buffer");
+var import_node_crypto = require("crypto");
+var DEFAULT_OAUTH_BASE_URL = "https://app.mantyx.io";
+var DEFAULT_REFRESH_SKEW_MS = 6e4;
+var MantyxOAuthError = class extends MantyxError {
+  oauthError;
+  oauthErrorDescription;
+  constructor(oauthError, oauthErrorDescription, status) {
+    const message = oauthErrorDescription ? `OAuth ${oauthError}: ${oauthErrorDescription}` : `OAuth ${oauthError}`;
+    super(message, { code: oauthError, status });
+    this.name = "MantyxOAuthError";
+    this.oauthError = oauthError;
+    this.oauthErrorDescription = oauthErrorDescription;
+  }
+};
+var MantyxOAuthClient = class {
+  clientId;
+  baseUrl;
+  clientSecret;
+  fetchImpl;
+  timeoutMs;
+  constructor(opts) {
+    if (!opts.clientId) {
+      throw new MantyxError("`clientId` is required for MantyxOAuthClient");
+    }
+    if (!opts.clientSecret) {
+      throw new MantyxError("`clientSecret` is required for MantyxOAuthClient");
+    }
+    const f = opts.fetch ?? globalThis.fetch;
+    if (typeof f !== "function") {
+      throw new MantyxError(
+        "Global fetch is not available; pass a custom `fetch` implementation in MantyxOAuthClientOptions."
+      );
+    }
+    this.clientId = opts.clientId;
+    this.clientSecret = opts.clientSecret;
+    this.baseUrl = (opts.baseUrl ?? DEFAULT_OAUTH_BASE_URL).replace(/\/+$/, "");
+    this.fetchImpl = f;
+    this.timeoutMs = opts.timeoutMs ?? 3e4;
+  }
+  /**
+   * Swap an authorization-code + PKCE verifier for the initial
+   * `{access_token, refresh_token}` pair. Call this exactly once per
+   * sign-in after the browser/native redirect lands back on your
+   * `redirectUri` with a `code` parameter. Persist the returned
+   * `refreshToken` against the user record — it is long-lived and
+   * non-rotating per `docs/oauth.md` §"Token lifetimes & lifecycle".
+   */
+  async exchangeAuthorizationCode(opts) {
+    return this.token({
+      grant_type: "authorization_code",
+      code: opts.code,
+      redirect_uri: opts.redirectUri,
+      code_verifier: opts.codeVerifier
+    });
+  }
+  /**
+   * Mint a fresh access token from a stored refresh token. The
+   * returned `refreshToken` is identical to the input — the field is
+   * surfaced for symmetry with {@link exchangeAuthorizationCode} only.
+   *
+   * On `400 invalid_grant` the refresh token has been revoked (or its
+   * grant / app was deleted); the SDK surfaces a
+   * {@link MantyxOAuthError} and callers must drive a fresh sign-in.
+   */
+  async refresh(opts) {
+    if (!opts.refreshToken) {
+      throw new MantyxError("`refreshToken` is required for MantyxOAuthClient.refresh");
+    }
+    const body = {
+      grant_type: "refresh_token",
+      refresh_token: opts.refreshToken
+    };
+    const scope = normalizeScope(opts.scope);
+    if (scope !== void 0) body.scope = scope;
+    return this.token(body);
+  }
+  /**
+   * Request a workspace-scoped access token without a user via the
+   * `client_credentials` grant. Available only on private OAuth apps
+   * that were registered with `allowsClientCredentials: true`. No
+   * refresh token is issued; re-call this method whenever a new
+   * access token is needed.
+   */
+  async clientCredentials(opts = {}) {
+    const body = {
+      grant_type: "client_credentials"
+    };
+    const scope = normalizeScope(opts.scope);
+    if (scope !== void 0) body.scope = scope;
+    return this.token(body);
+  }
+  /**
+   * Revoke an access or refresh token (RFC 7009). The server always
+   * returns 200, even for unknown tokens. Revoking a **refresh**
+   * token kills the refresh and every live access token tied to its
+   * grant; revoking an **access** token kills only that one.
+   */
+  async revoke(opts) {
+    if (!opts.token) {
+      throw new MantyxError("`token` is required for MantyxOAuthClient.revoke");
+    }
+    await this.formPost("/api/oauth/revoke", {
+      token: opts.token
+    });
+  }
+  /**
+   * Build a long-lived {@link TokenSource} that re-mints access
+   * tokens from the supplied refresh token. Pass the returned source
+   * to `new MantyxClient({ tokenSource, workspaceSlug, ... })`. The
+   * source caches the access token in-memory and refreshes
+   * proactively when the cached value is within `refreshSkewMs` of
+   * `expiresAt`, or eagerly when `MantyxClient` reports a 401.
+   */
+  refreshTokenSource(opts) {
+    if (!opts.refreshToken) {
+      throw new MantyxError("`refreshToken` is required for MantyxOAuthClient.refreshTokenSource");
+    }
+    const skew = opts.refreshSkewMs ?? DEFAULT_REFRESH_SKEW_MS;
+    const cache = { token: opts.initialToken, inflight: null };
+    const refreshToken = opts.refreshToken;
+    return makeTokenSource(cache, skew, async () => {
+      return this.refresh({ refreshToken, scope: opts.scope });
+    });
+  }
+  /**
+   * Build a long-lived {@link TokenSource} backed by the
+   * `client_credentials` grant. On every refresh the source re-mints
+   * a workspace-scoped access token by calling the token endpoint
+   * with `grant_type=client_credentials`. Available only on private
+   * apps with `allowsClientCredentials: true`.
+   */
+  clientCredentialsTokenSource(opts = {}) {
+    const skew = opts.refreshSkewMs ?? DEFAULT_REFRESH_SKEW_MS;
+    const cache = { token: void 0, inflight: null };
+    return makeTokenSource(cache, skew, async () => {
+      return this.clientCredentials({ scope: opts.scope });
+    });
+  }
+  // -------------------------------------------------------------- internals
+  /**
+   * POST `application/x-www-form-urlencoded` to `/api/oauth/token` and
+   * decode the {@link OAuthToken} response. Always injects `client_id`
+   * + `client_secret` from the constructor.
+   */
+  async token(body) {
+    const res = await this.formPost("/api/oauth/token", body);
+    let parsed = {};
+    try {
+      parsed = await res.json();
+    } catch {
+      throw new MantyxOAuthError(
+        "invalid_response",
+        "Token endpoint returned a non-JSON response",
+        res.status
+      );
+    }
+    const accessToken = typeof parsed.access_token === "string" ? parsed.access_token : "";
+    if (!accessToken) {
+      throw new MantyxOAuthError(
+        "invalid_response",
+        "Token endpoint response is missing `access_token`",
+        res.status
+      );
+    }
+    const expiresIn = typeof parsed.expires_in === "number" ? parsed.expires_in : 3600;
+    return {
+      accessToken,
+      refreshToken: typeof parsed.refresh_token === "string" ? parsed.refresh_token : void 0,
+      tokenType: typeof parsed.token_type === "string" ? parsed.token_type : "Bearer",
+      expiresIn,
+      expiresAt: Date.now() + expiresIn * 1e3,
+      scope: typeof parsed.scope === "string" ? parsed.scope : void 0
+    };
+  }
+  async formPost(path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const params = new URLSearchParams({
+      ...body,
+      client_id: this.clientId,
+      client_secret: this.clientSecret
+    });
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), this.timeoutMs);
+    let res;
+    try {
+      res = await this.fetchImpl(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          Accept: "application/json"
+        },
+        body: params.toString(),
+        signal: ctrl.signal
+      });
+    } catch (err) {
+      if (ctrl.signal.aborted) {
+        throw new MantyxNetworkError(`OAuth request timed out after ${this.timeoutMs}ms`);
+      }
+      throw new MantyxNetworkError(`OAuth network error: ${err.message}`, {
+        cause: err
+      });
+    } finally {
+      clearTimeout(t);
+    }
+    if (!res.ok) {
+      let errBody = {};
+      try {
+        errBody = await res.json();
+      } catch {
+      }
+      const oauthError = typeof errBody.error === "string" ? errBody.error : `http_${res.status}`;
+      const desc = typeof errBody.error_description === "string" ? errBody.error_description : void 0;
+      throw new MantyxOAuthError(oauthError, desc, res.status);
+    }
+    return res;
+  }
+};
+function generatePkceVerifier(length = 64) {
+  if (length < 43 || length > 128) {
+    throw new MantyxError("PKCE code_verifier length must be in [43, 128]");
+  }
+  const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~";
+  const bytes = (0, import_node_crypto.randomBytes)(length);
+  let out = "";
+  for (let i = 0; i < length; i++) {
+    out += ALPHABET[bytes[i] % ALPHABET.length];
+  }
+  return out;
+}
+function pkceChallenge(verifier) {
+  const hash = (0, import_node_crypto.createHash)("sha256").update(verifier, "utf8").digest();
+  return import_node_buffer.Buffer.from(hash).toString("base64").replace(/=+$/, "").replace(/\+/g, "-").replace(/\//g, "_");
+}
+function makeTokenSource(cache, skewMs, mint) {
+  return async (reason = "initial") => {
+    if (reason !== "unauthorized" && cache.token && !isExpiring(cache.token, skewMs)) {
+      return cache.token.accessToken;
+    }
+    if (cache.inflight) {
+      const t = await cache.inflight;
+      if (reason === "unauthorized" && t === cache.token) {
+      } else {
+        return t.accessToken;
+      }
+    }
+    cache.inflight = mint().then(
+      (t) => {
+        cache.token = t;
+        return t;
+      },
+      (err) => {
+        throw err;
+      }
+    );
+    try {
+      const t = await cache.inflight;
+      return t.accessToken;
+    } finally {
+      cache.inflight = null;
+    }
+  };
+}
+function isExpiring(token, skewMs) {
+  return token.expiresAt - Date.now() <= skewMs;
+}
+function normalizeScope(scope) {
+  if (scope === void 0) return void 0;
+  if (typeof scope === "string") {
+    const trimmed = scope.trim();
+    return trimmed.length > 0 ? trimmed : void 0;
+  }
+  const joined = scope.filter((s) => typeof s === "string" && s.length > 0).join(" ");
+  return joined.length > 0 ? joined : void 0;
+}
 
 // src/version.ts
-var SDK_VERSION = "0.9.0";
+var SDK_VERSION = "0.10.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AgentSession,
   DEFAULT_BASE_URL,
+  DEFAULT_OAUTH_BASE_URL,
+  DEFAULT_REFRESH_SKEW_MS,
   MantyxAuthError,
   MantyxClient,
   MantyxError,
   MantyxNetworkError,
+  MantyxOAuthClient,
+  MantyxOAuthError,
   MantyxParseError,
   MantyxRunError,
+  MantyxScopeError,
   MantyxToolError,
   SDK_VERSION,
   defineLocalA2A,
   defineLocalMcp,
   defineLocalTool,
+  generatePkceVerifier,
   isLocalA2ATool,
   isLocalMcpServer,
   isLocalTool,
@@ -1321,6 +1730,7 @@ var SDK_VERSION = "0.9.0";
   mantyxPluginTool,
   mantyxTool,
   parseRunOutput,
+  pkceChallenge,
   readSseStream,
   toToolParametersWire,
   zodToJsonSchema