@alter-ai/cli 0.8.0 → 0.9.0

package/dist/cli.js

@@ -33,7 +33,7 @@ import { join } from "path";
 // package.json
 var package_default = {
   name: "@alter-ai/cli",
-  version: "0.8.0",
+  version: "0.9.0",
   description: "Command-line interface for the Alter Vault dev portal \u2014 scripted dashboard automation.",
   type: "module",
   bin: {
@@ -76,7 +76,7 @@ var package_default = {
     keytar: "^7.9.0"
   },
   devDependencies: {
-    "@alter-ai/alter-sdk": "workspace:0.23.3",
+    "@alter-ai/alter-sdk": "workspace:0.24.0",
     "@alter-vault/shared-types": "workspace:0.0.1",
     "@alter-vault/shared-utils": "workspace:0.0.1",
     "@eslint/js": "9.39.4",
@@ -4618,7 +4618,7 @@ var AlterSDKError = class extends Error {
   constructor(message, details) {
     super(message);
     this.name = "AlterSDKError";
-    this.details = details ?? {};
+    this.details = details !== null && typeof details === "object" && !Array.isArray(details) ? details : {};
     Object.setPrototypeOf(this, new.target.prototype);
   }
   toString() {
@@ -4836,9 +4836,9 @@ var InsufficientScopeError = class _InsufficientScopeError extends BackendError
   constructor(message = "Insufficient scope", options = {}) {
     super(message, options.details);
     this.name = "InsufficientScopeError";
-    this.required = options.required ?? [];
-    this.granted = options.granted ?? [];
-    this.missing = options.missing ?? [];
+    this.required = options.required ? [...options.required] : [];
+    this.granted = options.granted ? [...options.granted] : [];
+    this.missing = options.missing ? [...options.missing] : [];
     this.scopeVersion = options.scopeVersion ?? null;
     this.currentScopeVersion = options.currentScopeVersion ?? null;
     this.scopeVersionMismatch = options.scopeVersionMismatch ?? false;
@@ -4871,7 +4871,9 @@ var InsufficientScopeError = class _InsufficientScopeError extends BackendError
    */
   static fromErrorBody(errorData) {
     return new _InsufficientScopeError(
-      typeof errorData.message === "string" ? errorData.message : "Insufficient scope",
+      // Non-empty string only (parity with `_messageOr` / Python
+      // `from_error_body`): an empty wire message is as uninformative as none.
+      typeof errorData.message === "string" && errorData.message ? errorData.message : "Insufficient scope",
       {
         // Element-level filtering: a non-array coerces to [], and non-string
         // elements inside an array are dropped (a bare cast would smuggle
@@ -5056,7 +5058,7 @@ var AgentError = class extends BackendError {
   hint;
   constructor(opts = {}) {
     const subclassCode = new.target.code;
-    super(opts.message ?? subclassCode, opts.details);
+    super(opts.message || subclassCode, opts.details);
     this.name = "AgentError";
     this.code = subclassCode;
     this.hint = opts.hint;
@@ -6796,12 +6798,13 @@ var ApprovalResult = class {
       headers: this.headers,
       body_b64: this.bodyB64,
       body_truncated: this.bodyTruncated,
-      // Included, unlike the deliberately-omitted ``durationMs``: that one is
-      // OBSERVATIONAL (how long this particular call took), while this is part
-      // of the result's meaning — the reason the provider rejected the
-      // credential. A caller serializing a failure for a log or a bug report
-      // needs the explanation to survive; the timing of that one attempt does
-      // not.
+      // Include duration_ms so JSON round-trips carry the timing metadata.
+      // The Python twin's ApprovalResult is a plain Pydantic model whose
+      // model_dump() includes EVERY public field — duration_ms and
+      // credential_hint alike — so omitting either here would make a TS
+      // JSON round-trip lossy where the Python one is not (wire-shape
+      // parity: toJSON() must serialize the same field set as model_dump()).
+      duration_ms: this.durationMs,
       credential_hint: this.credentialHint
     };
   }
@@ -8112,7 +8115,7 @@ async function _raiseForStatus(response) {
   const rawCode = body.error;
   const code = typeof rawCode === "string" ? rawCode : "";
   const rawMessage = body.message;
-  const message = typeof rawMessage === "string" ? rawMessage : `Backend error ${response.status}`;
+  const message = typeof rawMessage === "string" && rawMessage ? rawMessage : `Backend error ${response.status}`;
   const rawHint = body.hint;
   const hint = typeof rawHint === "string" ? rawHint : void 0;
   if (code === "insufficient_scope") {
@@ -8120,7 +8123,7 @@ async function _raiseForStatus(response) {
   }
   if (code === "rate_limit_exceeded") {
     throw new RateLimitError(
-      typeof body.message === "string" ? body.message : "Rate limit exceeded \u2014 retry after the window resets.",
+      typeof body.message === "string" && body.message ? body.message : "Rate limit exceeded \u2014 retry after the window resets.",
       _parseRetryAfter(response.headers.get("Retry-After"), body.retry_after),
       body,
       typeof body.scope === "string" ? body.scope : void 0,
@@ -8318,9 +8321,15 @@ var AgentsNamespace = class {
     const limit = options.limit ?? 100;
     const offset = options.offset ?? 0;
     const includeRevoked = options.includeRevoked ?? false;
+    if (!Number.isInteger(limit)) {
+      throw new AlterValueError("limit must be an integer");
+    }
     if (limit < 1 || limit > LIST_LIMIT_MAX) {
       throw new AlterValueError("limit must be between 1 and 1000");
     }
+    if (!Number.isInteger(offset)) {
+      throw new AlterValueError("offset must be an integer");
+    }
     if (offset < 0) {
       throw new AlterValueError("offset must be >= 0");
     }
@@ -8766,7 +8775,7 @@ function _optionalStringArray(raw, key, context) {
 }
 function _normalizeKeyId(value, operation) {
   if (typeof value === "string") {
-    if (value.length === 0) {
+    if (value.trim().length === 0) {
       throw new AlterValueError(`${operation}() requires a non-empty keyId`);
     }
     return value;
@@ -9468,6 +9477,26 @@ var SpansNamespace = class {
           `spans[${index}] must be a UserSpan with traceId, name, and startTime`
         );
       }
+      if (span.traceId.length < 1 || span.traceId.length > 255) {
+        throw new AlterValueError(
+          `spans[${index}].traceId must be 1\u2013255 characters`
+        );
+      }
+      if (span.name.length < 1 || span.name.length > 255) {
+        throw new AlterValueError(
+          `spans[${index}].name must be 1\u2013255 characters`
+        );
+      }
+      if (span.spanId !== void 0 && (typeof span.spanId !== "string" || span.spanId.length < 1 || span.spanId.length > 32)) {
+        throw new AlterValueError(
+          `spans[${index}].spanId must be 1\u201332 characters when provided`
+        );
+      }
+      if (span.parentSpanId !== void 0 && (typeof span.parentSpanId !== "string" || span.parentSpanId.length < 1 || span.parentSpanId.length > 32)) {
+        throw new AlterValueError(
+          `spans[${index}].parentSpanId must be 1\u201332 characters when provided`
+        );
+      }
     });
     const body = {
       spans: spans.map((span) => {
@@ -9794,8 +9823,14 @@ var FORBIDDEN_INJECTION_HEADERS2 = /* @__PURE__ */ new Set([
 function _coerceInt(value) {
   return Number.isInteger(value) && value >= 0 ? value : void 0;
 }
+var IDENTITY_SYNC_POLL_STATUS = {
+  service_unavailable: 503,
+  identity_provider_inactive: 409,
+  identity_group_name_ambiguous: 409
+};
 function _messageOr(errorData, fallback) {
-  return typeof errorData.message === "string" ? errorData.message : fallback;
+  const raw = errorData.message;
+  return typeof raw === "string" && raw ? raw : fallback;
 }
 function _errorPayload(errorData) {
   const nested = errorData.details;
@@ -9918,7 +9953,8 @@ function validateTokenInjectionMetadata(tokenData) {
   let additionalCredentials = null;
   if (additionalCredentialsRaw != null) {
     if (typeof additionalCredentialsRaw !== "object" || Array.isArray(additionalCredentialsRaw) || Object.keys(additionalCredentialsRaw).length > MAX_ADDITIONAL_CREDENTIAL_KEYS || !Object.entries(additionalCredentialsRaw).every(
-      ([key, value]) => key.length <= MAX_ADDITIONAL_CREDENTIAL_KEY_LENGTH && typeof value === "string" && value.trim().length > 0 && value.length <= MAX_ADDITIONAL_CREDENTIAL_VALUE_LENGTH && // eslint-disable-next-line no-control-regex
+      ([key, value]) => key.length <= MAX_ADDITIONAL_CREDENTIAL_KEY_LENGTH && typeof value === "string" && // pythonStrip: match the backend's Python str.strip() (see token_type).
+      pythonStrip(value).length > 0 && value.length <= MAX_ADDITIONAL_CREDENTIAL_VALUE_LENGTH && // eslint-disable-next-line no-control-regex
       !/[\r\n\x00]/.test(value)
     )) {
       throw new BackendError("Backend returned invalid additional_credentials");
@@ -10016,7 +10052,23 @@ function isValidOffsetDateTime(value) {
   const hour = Number(hourText);
   const minute = Number(minuteText);
   const second = Number(secondText);
-  if (month < 1 || month > 12 || day < 1 || day > new Date(Date.UTC(year, month, 0)).getUTCDate() || hour > 23 || minute > 59 || second > 59 || offsetHour > 23 || offsetMinute > 59) {
+  const isLeapYear = year % 4 === 0 && year % 100 !== 0 || year % 400 === 0;
+  const daysInMonth = [
+    31,
+    isLeapYear ? 29 : 28,
+    31,
+    30,
+    31,
+    30,
+    31,
+    31,
+    30,
+    31,
+    30,
+    31
+  ];
+  const maxDay = daysInMonth[month - 1] ?? 0;
+  if (year < 1 || month < 1 || month > 12 || day < 1 || day > maxDay || hour > 23 || minute > 59 || second > 59 || offsetHour > 23 || offsetMinute > 59) {
     return false;
   }
   return !Number.isNaN(Date.parse(value));
@@ -10036,7 +10088,10 @@ function validateTokenResponseContract(tokenData) {
     throw new BackendError("Backend returned an invalid access_token");
   }
   const tokenType = tokenData.token_type === void 0 ? "Bearer" : tokenData.token_type;
-  if (typeof tokenType !== "string" || tokenType.trim().length === 0 || tokenType !== tokenType.trim() || tokenType.length > 255 || // eslint-disable-next-line no-control-regex
+  if (typeof tokenType !== "string" || // pythonStrip (not .trim()): the backend normalizes with Python str.strip(),
+  // whose whitespace set differs from JS trim() at the edges (NEL/BOM/C0
+  // separators). Match the backend so the two SDKs accept/reject identically.
+  pythonStrip(tokenType).length === 0 || tokenType !== pythonStrip(tokenType) || tokenType.length > 255 || // eslint-disable-next-line no-control-regex
   /[\x00-\x1f\x7f]/.test(tokenType)) {
     throw new BackendError("Backend returned an invalid token_type");
   }
@@ -10050,7 +10105,8 @@ function validateTokenResponseContract(tokenData) {
   }
   const scopes = tokenData.scopes === void 0 ? [] : tokenData.scopes;
   if (!Array.isArray(scopes) || scopes.some(
-    (scope) => typeof scope !== "string" || scope.trim().length === 0 || scope !== scope.trim() || // eslint-disable-next-line no-control-regex
+    (scope) => typeof scope !== "string" || // pythonStrip: match the backend's Python str.strip() (see token_type).
+    pythonStrip(scope).length === 0 || scope !== pythonStrip(scope) || // eslint-disable-next-line no-control-regex
     /[\x00-\x1f\x7f]/.test(scope)
   )) {
     throw new BackendError("Backend returned invalid scopes");
@@ -10060,7 +10116,8 @@ function validateTokenResponseContract(tokenData) {
     throw new BackendError("Backend returned an invalid grant_id");
   }
   const providerId = tokenData.provider_id === void 0 ? "" : tokenData.provider_id;
-  if (typeof providerId !== "string" || providerId !== providerId.trim() || providerId.length > 255 || // eslint-disable-next-line no-control-regex
+  if (typeof providerId !== "string" || // pythonStrip: match the backend's Python str.strip() (see token_type).
+  providerId !== pythonStrip(providerId) || providerId.length > 255 || // eslint-disable-next-line no-control-regex
   /[\x00-\x1f\x7f]/.test(providerId)) {
     throw new BackendError("Backend returned an invalid provider_id");
   }
@@ -10089,7 +10146,10 @@ function isRetryErrorInfoPayload(x) {
     return false;
   }
   const e = x;
-  return typeof e.attempt === "number" && Number.isFinite(e.attempt) && e.attempt >= 1 && typeof e.error === "string" && e.error.length <= 500 && typeof e.error_type === "string" && typeof e.delay_s === "number" && Number.isFinite(e.delay_s) && e.delay_s >= 0 && (e.permanent === void 0 || typeof e.permanent === "boolean");
+  return typeof e.attempt === "number" && // Integer-only (not merely finite) — mirrors the backend Pydantic `int`
+  // schema and the Python SDK's strict `RetryErrorInfo.attempt`, so a
+  // fractional attempt (e.g. 1.5) is dropped identically in both SDKs.
+  Number.isInteger(e.attempt) && e.attempt >= 1 && typeof e.error === "string" && e.error.length <= 500 && typeof e.error_type === "string" && typeof e.delay_s === "number" && Number.isFinite(e.delay_s) && e.delay_s >= 0 && (e.permanent === void 0 || typeof e.permanent === "boolean");
 }
 var _tokenStore = /* @__PURE__ */ new WeakMap();
 var _additionalCredsStore = /* @__PURE__ */ new WeakMap();
@@ -10112,7 +10172,7 @@ function _extractAdditionalCredentials(token) {
   return _additionalCredsStore.get(token);
 }
 var _fetch;
-var SDK_VERSION = "0.23.3";
+var SDK_VERSION = "0.24.0";
 var SDK_USER_AGENT = `alter-sdk-node/${SDK_VERSION}`;
 function pyUnquote(s) {
   if (!s.includes("%")) return s;
@@ -10381,7 +10441,14 @@ var PROXY_FORBIDDEN_HEADER_NAMES = /* @__PURE__ */ new Set([
   "x-goog-authorization",
   "x-goog-iam-authorization-token",
   "x-stripe-account",
-  "x-shopify-access-token"
+  "x-shopify-access-token",
+  // Method tunnelling: OData V2 (SAP S/4HANA) and several enterprise APIs
+  // honour these as an override of the real HTTP verb. The policy gate
+  // classifies on the wire method, so a tunnelled verb would split the
+  // operation the gate names from the one the provider executes.
+  "x-http-method",
+  "x-http-method-override",
+  "x-method-override"
 ]);
 var MAX_CONTEXT_LENGTH = 4096;
 var MAX_CONTEXT_KEYS = 20;
@@ -10418,9 +10485,10 @@ function validateAndSerializeContext(context) {
         `context keys must be strings, got ${typeof k}`
       );
     }
-    if (k.length > MAX_CONTEXT_KEY_LENGTH) {
+    const keyLength = [...k].length;
+    if (keyLength > MAX_CONTEXT_KEY_LENGTH) {
       throw new AlterValueError(
-        `context key "${k.slice(0, 32)}" exceeds max length (${k.length} > ${MAX_CONTEXT_KEY_LENGTH})`
+        `context key "${k.slice(0, 32)}" exceeds max length (${keyLength} > ${MAX_CONTEXT_KEY_LENGTH})`
       );
     }
     const v = context[k];
@@ -10429,9 +10497,10 @@ function validateAndSerializeContext(context) {
         `context value for key "${k}" must be a string, got ${typeof v}`
       );
     }
-    if (v.length > MAX_CONTEXT_VALUE_LENGTH) {
+    const valueLength = [...v].length;
+    if (valueLength > MAX_CONTEXT_VALUE_LENGTH) {
       throw new AlterValueError(
-        `context value for key "${k}" exceeds max length (${v.length} > ${MAX_CONTEXT_VALUE_LENGTH})`
+        `context value for key "${k}" exceeds max length (${valueLength} > ${MAX_CONTEXT_VALUE_LENGTH})`
       );
     }
   }
@@ -10531,11 +10600,28 @@ function connectMetadataToWire(metadata) {
   }
   return wire;
 }
-var GRANT_POLICY_INPUT_KEYS = /* @__PURE__ */ new Set([
-  "expiresAt",
-  "maxTtlSeconds",
-  "defaultTtlSeconds"
-]);
+var GRANT_POLICY_CAMEL_TO_WIRE = [
+  ["expiresAt", "expires_at"],
+  ["maxTtlSeconds", "max_ttl_seconds"],
+  ["defaultTtlSeconds", "default_ttl_seconds"]
+];
+var GRANT_POLICY_INPUT_KEYS = new Set(
+  GRANT_POLICY_CAMEL_TO_WIRE.map(([camelKey]) => camelKey)
+);
+function assertParseableExpiresAt(value) {
+  if (typeof value !== "string" || value.length === 0 || Number.isNaN(Date.parse(value))) {
+    throw new AlterValueError(
+      "grantPolicy.expiresAt must be a non-empty ISO 8601 string when provided"
+    );
+  }
+}
+function assertPositiveIntegerSeconds(camelKey, value) {
+  if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+    throw new AlterValueError(
+      `grantPolicy.${camelKey} must be a positive integer (seconds) when provided`
+    );
+  }
+}
 function grantPolicyInputToWire(policy) {
   if (policy === null || typeof policy !== "object" || Array.isArray(policy)) {
     throw new AlterValueError(
@@ -10545,32 +10631,57 @@ function grantPolicyInputToWire(policy) {
   for (const key of Object.keys(policy)) {
     if (!GRANT_POLICY_INPUT_KEYS.has(key)) {
       throw new AlterValueError(
-        `grantPolicy contains unknown key "${key}" (allowed: expiresAt, maxTtlSeconds, defaultTtlSeconds). Note: keys are camelCase in the TypeScript SDK \u2014 snake_case keys like max_ttl_seconds are the Python SDK surface.`
+        `grantPolicy contains unknown key "${key}" (allowed: ${[...GRANT_POLICY_INPUT_KEYS].join(", ")}). Note: keys are camelCase in the TypeScript SDK \u2014 snake_case keys like max_ttl_seconds are the Python SDK surface.`
       );
     }
   }
   const wire = {};
-  if (policy.expiresAt !== void 0 && policy.expiresAt !== null) {
-    if (typeof policy.expiresAt !== "string" || policy.expiresAt.length === 0) {
+  for (const [camelKey, wireKey] of GRANT_POLICY_CAMEL_TO_WIRE) {
+    const value = policy[camelKey];
+    if (value === void 0 || value === null) {
+      continue;
+    }
+    if (camelKey === "expiresAt") {
+      assertParseableExpiresAt(value);
+    } else {
+      assertPositiveIntegerSeconds(camelKey, value);
+    }
+    wire[wireKey] = value;
+  }
+  return wire;
+}
+function _mintGrantPolicyToWire(policy) {
+  for (const spelling of ["defaultTtlSeconds", "default_ttl_seconds"]) {
+    if (Object.prototype.hasOwnProperty.call(policy, spelling)) {
       throw new AlterValueError(
-        "grantPolicy.expiresAt must be a non-empty ISO 8601 string when provided"
+        `grantPolicy.${spelling} is not supported on mint \u2014 a default TTL is accepted only by Connect sessions (createConnectSession / connect) and createManagedSecretGrant`
       );
     }
-    wire.expires_at = policy.expiresAt;
   }
-  for (const [camelKey, wireKey] of [
-    ["maxTtlSeconds", "max_ttl_seconds"],
-    ["defaultTtlSeconds", "default_ttl_seconds"]
-  ]) {
+  const wire = {};
+  for (const [key, value] of Object.entries(policy)) {
+    if (!GRANT_POLICY_INPUT_KEYS.has(key)) {
+      wire[key] = value;
+    }
+  }
+  for (const [camelKey, wireKey] of GRANT_POLICY_CAMEL_TO_WIRE) {
     const value = policy[camelKey];
-    if (value === void 0 || value === null) {
+    if (value === void 0) {
       continue;
     }
-    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+    if (Object.prototype.hasOwnProperty.call(policy, wireKey)) {
       throw new AlterValueError(
-        `grantPolicy.${camelKey} must be a positive integer (seconds) when provided`
+        `grantPolicy sets both "${camelKey}" and "${wireKey}" \u2014 supply exactly one spelling of the field`
       );
     }
+    if (value === null) {
+      continue;
+    }
+    if (camelKey === "expiresAt") {
+      assertParseableExpiresAt(value);
+    } else {
+      assertPositiveIntegerSeconds(camelKey, value);
+    }
     wire[wireKey] = value;
   }
   return wire;
@@ -11428,8 +11539,13 @@ ${label}:${value}`;
         };
         throw new ScopeReauthRequiredError(
           _messageOr(errorData, "Grant is missing required scopes"),
-          details.grant_id ?? void 0,
-          details.provider_id ?? void 0,
+          // `?? undefined` alone only replaces null — a NON-string grant_id /
+          // provider_id (number, object, bool) would be cast `as string` and
+          // flow through as the wrong runtime value. typeof-guard instead, to
+          // match every sibling branch in this method AND the Python SDK's
+          // `_handle_forbidden` scope_mismatch branch (isinstance → None).
+          typeof details.grant_id === "string" ? details.grant_id : void 0,
+          typeof details.provider_id === "string" ? details.provider_id : void 0,
           response.status,
           // No provider response body on this path — the backend refused at
           // /sdk/token before any provider call, so responseBody is left unset
@@ -11471,6 +11587,15 @@ ${label}:${value}`;
     }
     if (response.status === HTTP_CONFLICT) {
       const errorData = await __VaultClient.#safeParseJson(response);
+      if (errorData.error === "managed_oauth_scope_approval_required") {
+        throw new ConnectConfigError(
+          _messageOr(
+            errorData,
+            "The requested permissions require managed OAuth approval."
+          ),
+          errorData
+        );
+      }
       if (errorData.error === "token_refresh_in_progress") {
         throw new TokenRefreshInProgressError(
           _messageOr(
@@ -13350,6 +13475,16 @@ ${label}:${value}`;
    *   entry. Thrown before any wire traffic (parity with the Python SDK).
    * @throws AlterSDKError if the SDK instance is closed
    * @throws NetworkError if the connection to the backend fails
+   * @throws ConnectConfigError if the session's requested scopes exceed what
+   *   the Alter-managed OAuth client is approved for (HTTP 409
+   *   `managed_oauth_scope_approval_required`). NOT a `BackendError` — a
+   *   caller that branches only on `BackendError` leaves this uncaught.
+   *   `details` carries the whole 409 body: `details.details.provider_id` and
+   *   `details.details.unapproved_scopes` name what needs approving,
+   *   `details.remediation.action` / `.description` carry the typed remedy,
+   *   and `details.retryable` is `false`. Retrying is futile: contact Alter to
+   *   approve the scopes, or narrow the app's configured scopes to the
+   *   approved set, and only then create a new Connect session.
    * @throws BackendError if the backend rejects the request (e.g.
    *   `scope_not_allowed` when a requested scope is not in the app's Dev
    *   Portal allowlist)
@@ -13682,6 +13817,10 @@ ${label}:${value}`;
    *   authorized grant is revoked because the user's usage limits could not be
    *   applied. In the last case, `details.failed_grants` contains the typed
    *   failure data in snake_case wire form.
+   * @throws BackendError if identity synchronization could not be completed —
+   *   `statusCode` 503 (transient, with `details.retry_after_seconds`) or 409
+   *   (an operator must repair the provider; no retry hint). Not a
+   *   `ConnectFlowError`: the flow itself was fine.
    * @throws AlterSDKError if SDK is closed or session creation fails
    */
   async connect(options) {
@@ -13731,7 +13870,9 @@ ${label}:${value}`;
    * @throws ConnectTimeoutError if the local `timeoutMs` elapses, or a
    *     session observed as pending expires before Alter receives a
    *     completion callback. `details.reason` distinguishes
-   *     `poll_deadline_elapsed` from `session_expired`.
+   *     `poll_deadline_elapsed`, `session_expired`, and `rate_limited` (the
+   *     whole budget was spent backing off a throttled poll —
+   *     `details.retryAfter` carries the last hint the server gave).
    * @throws ConnectFlowError / ConnectDeniedError / ConnectConfigError
    *     for user denial, a first poll that finds an unavailable/expired
    *     session, unrecognized status, or a completed session whose every grant
@@ -13739,6 +13880,11 @@ ${label}:${value}`;
    *     total-failure error carries
    *     `details.failed_grants`; partial failures are surfaced on every
    *     returned result as `failedGrants`.
+   * @throws BackendError if identity synchronization could not be completed.
+   *     `statusCode` says whether to come back: 503 is transient contention
+   *     and `details.retry_after_seconds` carries the backoff hint, while 409
+   *     is an operator-repairable provider fault (disabled provider, duplicate
+   *     group name) that no retry will clear and which carries no hint.
    * @throws AlterSDKError if the SDK instance has been closed.
    */
   async pollConnectSession(sessionToken, options) {
@@ -13750,7 +13896,34 @@ ${label}:${value}`;
     let sawPending = false;
     while (true) {
       this.#assertNotClosed();
-      const pollResult = await this.#pollSession(sessionToken);
+      let pollResult;
+      try {
+        pollResult = await this.#pollSession(sessionToken);
+      } catch (e) {
+        if (!(e instanceof RateLimitError)) {
+          throw e;
+        }
+        const remaining2 = deadline - performance.now();
+        if (remaining2 <= 0) {
+          throw new ConnectTimeoutError(
+            `OAuth flow did not complete within ${Math.round(timeoutMs / 1e3)} seconds: polling was rate-limited for the remainder of the budget. The authorization may still have succeeded \u2014 retry the poll with a fresh timeout, or raise the API key's per-minute rate limit if Connect flows run concurrently.`,
+            {
+              timeoutMs,
+              reason: "rate_limited",
+              retryAfter: e.retryAfter
+            }
+          );
+        }
+        let backoffMs = pollIntervalMs;
+        if (typeof e.retryAfter === "number" && e.retryAfter > 0) {
+          backoffMs = Math.max(e.retryAfter * 1e3, pollIntervalMs);
+        }
+        await new Promise(
+          (resolve5) => setTimeout(resolve5, Math.min(backoffMs, remaining2))
+        );
+        this.#assertNotClosed();
+        continue;
+      }
       const pollStatus = pollResult.status;
       if (pollStatus === "completed") {
         const rawGrants = pollResult.grants;
@@ -13848,7 +14021,15 @@ ${label}:${value}`;
             }
           );
         }
-        const errorDetails = { error_code: errorCode };
+        const errorDetails = {
+          error_code: errorCode
+        };
+        const retryAfter = _coerceInt(
+          err2.retry_after_seconds
+        );
+        if (retryAfter !== void 0) {
+          errorDetails.retry_after_seconds = retryAfter;
+        }
         if (errorCode === "connect_denied") {
           throw new ConnectDeniedError(errorMessage, errorDetails);
         }
@@ -13858,10 +14039,19 @@ ${label}:${value}`;
           "invalid_client",
           "unauthorized_client",
           "provider_configuration_unavailable",
-          "shared_dev_credential_unavailable"
+          "shared_dev_credential_unavailable",
+          "managed_oauth_scope_approval_required"
         ].includes(errorCode)) {
           throw new ConnectConfigError(errorMessage, errorDetails);
         }
+        const identitySyncStatus = IDENTITY_SYNC_POLL_STATUS[errorCode];
+        if (identitySyncStatus !== void 0) {
+          throw new BackendError(
+            errorMessage,
+            errorDetails,
+            identitySyncStatus
+          );
+        }
         throw new ConnectFlowError(errorMessage, errorDetails);
       }
       if (pollStatus === "expired") {
@@ -13955,6 +14145,14 @@ ${label}:${value}`;
    *     shape (popup, mobile redirect, headless). The convenience
    *     method doesn't infer these from the error.
    * @throws AlterValueError if `error.providerId` is `undefined`.
+   * @throws ConnectConfigError if the recovery session could not be minted
+   *     because the Alter-managed OAuth client is not approved for the scopes
+   *     this app requests (HTTP 409 `managed_oauth_scope_approval_required`).
+   *     This helper forwards to `createConnectSession`, so it throws
+   *     everything that method throws — see its `@throws` list for the
+   *     `details` payload. Retrying is futile: contact Alter to approve the
+   *     scopes, or narrow the app's configured scopes to the approved set, and
+   *     only then mint a recovery session.
    */
   async createConnectSessionForError(error51, options) {
     const providerId = error51.providerId;
@@ -14096,6 +14294,11 @@ ${label}:${value}`;
    *   `pollIntervalMs` is non-finite or not greater than zero.
    * @throws AlterSDKError if the SDK is closed or the IDP returned a terminal
    *   error / the session expired.
+   * @throws BackendError if identity synchronization could not be completed.
+   *   Surfaced separately from the terminal `AlterSDKError` above precisely
+   *   because it is NOT a rejected login: `statusCode` 503 is transient
+   *   contention carrying `details.retry_after_seconds`, and 409 is an
+   *   operator-repairable provider fault that no retry will clear.
    * @throws ConnectTimeoutError if the user did not complete login in time
    *   (`details.reason` is `"poll_deadline_elapsed"`).
    */
@@ -14127,8 +14330,19 @@ ${label}:${value}`;
           });
         }
         if (pollData.status === "error") {
-          const errorMessage = pollData.error_message || "unknown error";
-          throw new AlterSDKError(`Authentication failed: ${errorMessage}`);
+          const errorMessage = typeof pollData.error_message === "string" && pollData.error_message ? pollData.error_message : "unknown error";
+          const message = `Authentication failed: ${errorMessage}`;
+          const syncCode = typeof pollData.error_code === "string" ? pollData.error_code : "";
+          const identitySyncStatus = IDENTITY_SYNC_POLL_STATUS[syncCode];
+          if (identitySyncStatus !== void 0) {
+            const details = { error_code: syncCode };
+            const retryAfter = _coerceInt(pollData.retry_after_seconds);
+            if (retryAfter !== void 0) {
+              details.retry_after_seconds = retryAfter;
+            }
+            throw new BackendError(message, details, identitySyncStatus);
+          }
+          throw new AlterSDKError(message);
         }
         if (pollData.status === "expired") {
           throw new AlterSDKError("Authentication session expired");
@@ -14145,10 +14359,13 @@ ${label}:${value}`;
         (resolve5) => setTimeout(resolve5, Math.min(pollIntervalMs, remaining))
       );
     }
-    throw new ConnectTimeoutError("Authentication timed out", {
-      timeoutMs,
-      reason: "poll_deadline_elapsed"
-    });
+    throw new ConnectTimeoutError(
+      `Authentication timed out after ${timeoutMs}ms. The user may not have completed login in the browser.`,
+      {
+        timeoutMs,
+        reason: "poll_deadline_elapsed"
+      }
+    );
   }
   /**
    * Single sign-in poll attempt (INTERNAL).
@@ -14712,12 +14929,13 @@ ${label}:${value}`;
   async #mapProxyErrorResponse(response) {
     let detail = {};
     try {
-      const errBody = await response.clone().json();
-      detail = errBody.detail || errBody || {};
+      const parsed = await response.clone().json();
+      const payloadDict = isPlainRecord(parsed) ? parsed : {};
+      detail = isPlainRecord(payloadDict.detail) ? payloadDict.detail : payloadDict;
     } catch {
     }
     const errCode = detail.error || "";
-    const msg = detail.message || `/sdk/proxy returned ${response.status}`;
+    const msg = typeof detail.message === "string" && detail.message ? detail.message : `/sdk/proxy returned ${response.status}`;
     if (errCode === "approval_denied")
       throw new ApprovalDeniedError({ message: msg });
     if (errCode === "approval_expired")
@@ -14801,11 +15019,21 @@ ${label}:${value}`;
    * @throws ApprovalExpiredError on `expired`.
    * @throws ApprovalExecutionFailedError on `failed`.
    * @throws ApprovalTimeoutError if the local wait elapses before any decision.
+   * @throws AlterValueError if `timeoutMs` is not a finite number, or
+   *   `pollIntervalMs` is non-finite or not greater than zero.
    */
   async awaitApproval(approvalId, options = {}) {
     this.#assertNotClosed();
     const timeoutMs = options.timeoutMs ?? 3e5;
     const pollIntervalMs = options.pollIntervalMs ?? 2e3;
+    if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs)) {
+      throw new AlterValueError("timeoutMs must be a finite number");
+    }
+    if (typeof pollIntervalMs !== "number" || !Number.isFinite(pollIntervalMs) || pollIntervalMs <= 0) {
+      throw new AlterValueError(
+        "pollIntervalMs must be a finite number greater than 0"
+      );
+    }
     const deadline = Date.now() + timeoutMs;
     let lastTransient = null;
     while (true) {
@@ -14831,16 +15059,16 @@ ${label}:${value}`;
             lastTransient
           );
         }
-        const sleep2 = Math.max(
-          100,
-          Math.min(pollIntervalMs, deadline - Date.now())
+        const sleep2 = Math.min(
+          pollIntervalMs,
+          Math.max(0, deadline - Date.now())
         );
         await new Promise((res) => setTimeout(res, sleep2));
         continue;
       }
       lastTransient = null;
       if (status.status === "executed" && !status.hasResult) {
-        const next = Math.max(100, deadline - Date.now());
+        const next = Math.max(0, deadline - Date.now());
         await new Promise((r) => setTimeout(r, Math.min(pollIntervalMs, next)));
         continue;
       }
@@ -14867,9 +15095,9 @@ ${label}:${value}`;
               lastTransient
             );
           }
-          const sleep2 = Math.max(
-            100,
-            Math.min(pollIntervalMs, deadline - Date.now())
+          const sleep2 = Math.min(
+            pollIntervalMs,
+            Math.max(0, deadline - Date.now())
           );
           await new Promise((res) => setTimeout(res, sleep2));
           continue;
@@ -14879,7 +15107,7 @@ ${label}:${value}`;
       if (now >= deadline) {
         throw this.#buildApprovalTimeout(approvalId, timeoutMs, lastTransient);
       }
-      const sleep = Math.max(100, Math.min(pollIntervalMs, deadline - now));
+      const sleep = Math.min(pollIntervalMs, Math.max(0, deadline - now));
       await new Promise((res) => setTimeout(res, sleep));
     }
   }
@@ -15841,11 +16069,18 @@ var App = class _App {
    * @param options.label - Required sibling address (resolution key:
    *   provider + label). Must be unique among the credential's active
    *   sibling grants.
-   * @param options.grantPolicy - Optional per-grant policy
-   *   (snake_case wire keys — e.g. `expires_at`, `max_ttl_seconds`,
-   *   `restrictions`, `requires_approval`). Validated server-side; an
-   *   invalid policy throws `BackendError` from the 422
-   *   `invalid_grant_policy` response.
+   * @param options.grantPolicy - Optional per-grant policy. `expiresAt`
+   *   and `maxTtlSeconds` are accepted in this SDK's camelCase
+   *   (validated locally and mapped to the snake_case wire keys,
+   *   exactly like `createConnectSession`); the wider policy grammar
+   *   (`restrictions`, `requires_approval`, …) uses the backend's
+   *   snake_case keys and is validated server-side — an invalid policy
+   *   throws `BackendError` from the 422 `invalid_grant_policy`
+   *   response. A default TTL is not part of the mint grammar:
+   *   `defaultTtlSeconds` / `default_ttl_seconds` throws
+   *   `AlterValueError` (it is accepted only by Connect sessions and
+   *   `createManagedSecretGrant`). Supplying both spellings of one
+   *   trio field also throws `AlterValueError`.
    * @param options.grantTags - Optional list of tag strings stored on
    *   the sibling grant.
    * @returns {@link GrantInfo} for the newly minted sibling grant
@@ -15881,7 +16116,7 @@ var App = class _App {
     }
     const wireBody = { label: options.label };
     if (options.grantPolicy !== void 0) {
-      wireBody.grant_policy = options.grantPolicy;
+      wireBody.grant_policy = _mintGrantPolicyToWire(options.grantPolicy);
     }
     if (options.grantTags !== void 0) {
       wireBody.grant_tags = options.grantTags;
@@ -16324,7 +16559,7 @@ var DEFAULT_BASE_URL = "https://backend.alterauth.com";
 var PAT_API_PREFIX = "/api/v1/dev-portal";
 var HTTP_ERROR_THRESHOLD = 400;
 var DEFAULT_TIMEOUT_MS = 3e4;
-var CLI_VERSION = "0.8.0";
+var CLI_VERSION = "0.9.0";
 var USER_AGENT = buildUserAgent();
 function buildUserAgent() {
   let osTag = "";
@@ -17330,7 +17565,7 @@ function isProviderCatalogEntry(value) {
   const v = value;
   return typeof v.id === "string" && typeof v.name === "string" && typeof v.display_name === "string" && (v.category === null || typeof v.category === "string") && (v.supports_refresh === null || typeof v.supports_refresh === "boolean") && (v.supports_pkce === null || typeof v.supports_pkce === "boolean") && (v.available_environments === void 0 || Array.isArray(v.available_environments) && v.available_environments.every(
     (environment) => environment === "production" || environment === "sandbox"
-  )) && v.available_scopes !== null && typeof v.available_scopes === "object" && !Array.isArray(v.available_scopes) && Object.values(v.available_scopes).every(
+  )) && (v.scopes_configured_on_provider === void 0 || typeof v.scopes_configured_on_provider === "boolean") && v.available_scopes !== null && typeof v.available_scopes === "object" && !Array.isArray(v.available_scopes) && Object.values(v.available_scopes).every(
     isProviderScopeCatalogEntry
   ) && (v.managed_credentials_available === void 0 || typeof v.managed_credentials_available === "boolean") && (v.managed_approved_scopes === void 0 || v.managed_approved_scopes === null || Array.isArray(v.managed_approved_scopes) && v.managed_approved_scopes.every(
     (scope) => typeof scope === "string"
@@ -18485,6 +18720,25 @@ var AuditNamespace = class {
     });
     return expectDict(body, "audit.list", 200);
   }
+  /** Provider facet values present in one app's audit events. Requires
+   *  `dashboard_audit:read`.
+   *
+   * Returns ``{providers}`` — the alphabetized distinct provider ids
+   * (OAuth provider ids, managed-secret template ids — a custom secret's
+   * name-derived slug — and IDP types) actually
+   * present on the app's audit rows; the accepted vocabulary for the
+   * ``--provider`` filters. Data-derived, never a hardcoded shortlist.
+   */
+  async providers(appId) {
+    const query = optionsToQuery({ app_id: appId });
+    const body = await this.#client._call(
+      "GET",
+      "/audit-logs/unified/providers",
+      "audit.providers",
+      { query }
+    );
+    return expectDict(body, "audit.providers", 200);
+  }
   /** List dashboard / CLI admin actions. Requires `dashboard_audit:read`.
    *
    * Returns the canonical envelope ``{items, total, limit, offset, has_more}``
@@ -35607,6 +35861,9 @@ var CONTENT_MATCH_LIMITS = {
 };
 var MAX_RULE_NAME_LEN = 120;
 var MAX_RULE_DESCRIPTION_LEN = 2e3;
+var MAX_RULES_PER_TARGET = 100;
+var MAX_DERIVED_RULES_PER_TARGET = 2;
+var MAX_POLICY_RULE_PAGE_SIZE = MAX_RULES_PER_TARGET + MAX_DERIVED_RULES_PER_TARGET;
 var HITL_NOTIFICATION_CHANNELS = ["email"];
 var HITL_LIMITS = {
   maxApprovers: 10,
@@ -37302,6 +37559,33 @@ function buildAuditCommand() {
       });
     }
   );
+  audit.command("providers").description(
+    "List the provider IDs present in an app's audit events \u2014 the values `--provider` accepts (OAuth provider ids, managed-secret template ids \u2014 a custom secret's name-derived slug \u2014 and IDP types). Derived from the audit data, so providers whose config was since deleted still appear."
+  ).option(
+    APP_FLAG,
+    "App whose audit trail to facet (ID or name; falls back to ALTER_APP_ID / the workspace pin)"
+  ).option(
+    "--output <format>",
+    "Output format: json|jsonl|table (default: table)",
+    "table"
+  ).action(async (options) => {
+    const format = coerceOutputFormat(options.output);
+    const appId = await resolveAppOrExit(options.app);
+    await withClient(async (client) => {
+      const result = await client.audit.providers(appId);
+      const providers = result["providers"];
+      if (!Array.isArray(providers) || !providers.every((p) => typeof p === "string")) {
+        err(
+          'audit.providers: response is missing the "providers" string array. This is a wire-format regression; report it to the backend team.'
+        );
+        process.exit(EXIT_ERROR);
+      }
+      const rows = providers.map((provider_id) => ({ provider_id }));
+      emit2(format, rows, [
+        { label: "PROVIDER", get: (r) => r.provider_id }
+      ]);
+    });
+  });
   audit.command("show <trace-id>").description("Show every event for one trace").option(
     "--output <format>",
     "Output format: json|jsonl|table (default: json)",
@@ -44326,8 +44610,8 @@ function buildRulesSubcommand() {
     )
   ).option(
     "--limit <n>",
-    "Page size (1-100; when omitted the backend default of 100 applies)",
-    parseBoundedInt("--limit", 1, 100)
+    `Page size (1-${MAX_POLICY_RULE_PAGE_SIZE}; when omitted the backend default of ${MAX_POLICY_RULE_PAGE_SIZE} applies)`,
+    parseBoundedInt("--limit", 1, MAX_POLICY_RULE_PAGE_SIZE)
   ).option(
     "--offset <n>",
     "Page offset (default 0)",
@@ -44761,7 +45045,8 @@ async function providerCatalogError(client, providerId, environment, credentialS
   const availableScopes = provider.available_scopes ?? {};
   if (Object.keys(availableScopes).length === 0) {
     if (scopes !== void 0 && scopes.length > 0) {
-      return `alter: provider '${providerId}' publishes no selectable scopes \u2014 omit --scopes (Alter does not send a scope parameter to it)
+      const where = provider.scopes_configured_on_provider === true ? `; its permissions are configured on the ${provider.display_name} app itself` : "";
+      return `alter: provider '${providerId}' publishes no selectable scopes \u2014 omit --scopes (Alter does not send a scope parameter to it${where})
 `;
     }
     return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alter-ai/cli",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Command-line interface for the Alter Vault dev portal — scripted dashboard automation.",
   "type": "module",
   "bin": {
@@ -43,7 +43,7 @@
     "keytar": "^7.9.0"
   },
   "devDependencies": {
-    "@alter-ai/alter-sdk": "workspace:0.23.3",
+    "@alter-ai/alter-sdk": "workspace:0.24.0",
     "@alter-vault/shared-types": "workspace:0.0.1",
     "@alter-vault/shared-utils": "workspace:0.0.1",
     "@eslint/js": "9.39.4",