@docmana/sdk 0.3.4 → 0.4.0

package/dist/cli.mjs

@@ -61,7 +61,14 @@ var DocmanaAbortError = class extends DocmanaError {
     super(message, { code: "aborted" });
   }
 };
-function errorFromResponse(status, message, requestId) {
+var DocmanaRateLimitError = class extends DocmanaError {
+  retryAfterMs;
+  constructor(message, opts = {}) {
+    super(message, { ...opts, code: "rate_limited" });
+    this.retryAfterMs = opts.retryAfterMs;
+  }
+};
+function errorFromResponse(status, message, requestId, retryAfterMs) {
   const opts = { status, requestId };
   switch (status) {
     case 400:
@@ -72,6 +79,8 @@ function errorFromResponse(status, message, requestId) {
       return new DocmanaPermissionError(message, opts);
     case 404:
       return new DocmanaNotFoundError(message, opts);
+    case 429:
+      return new DocmanaRateLimitError(message, { ...opts, retryAfterMs });
     default:
       return new DocmanaError(message, opts);
   }
@@ -159,29 +168,33 @@ var TokenManager = class {
 
 // src/config.ts
 var DEFAULTS = {
-  apiBaseUrl: "https://api.docmana.ai",
   tokenEndpoint: "https://4fe70f5b-e013-4f65-9fa7-3109a33beba5.ciamlogin.com/4fe70f5b-e013-4f65-9fa7-3109a33beba5/oauth2/v2.0/token",
   scope: "api://d781e6ba-cc08-4618-8099-ad968abd2b9e/.default",
   timeoutMs: 3e5,
-  pollIntervalMs: 2e3
+  pollIntervalMs: 2e3,
+  pollMaxIntervalMs: 1e4
 };
 function resolveConfig(config) {
-  if (!config.clientId) throw new Error("DocmanaConfig.clientId is required");
-  if (!config.clientSecret) throw new Error("DocmanaConfig.clientSecret is required");
-  const apiBaseUrl = (config.apiBaseUrl ?? DEFAULTS.apiBaseUrl).replace(/\/+$/, "");
+  if (!config.apiBaseUrl) throw new Error("DocmanaConfig.apiBaseUrl is required");
+  if (!config.accessToken && !config.getAccessToken) {
+    throw new Error("DocmanaConfig.accessToken or DocmanaConfig.getAccessToken is required");
+  }
+  const apiBaseUrl = normalizeApiBaseUrl(config.apiBaseUrl);
   return {
-    clientId: config.clientId,
-    clientSecret: config.clientSecret,
     apiBaseUrl,
-    tokenEndpoint: config.tokenEndpoint ?? DEFAULTS.tokenEndpoint,
-    scope: config.scope ?? DEFAULTS.scope,
+    accessToken: config.accessToken,
+    getAccessToken: config.getAccessToken,
     timeoutMs: config.timeoutMs ?? DEFAULTS.timeoutMs,
     pollIntervalMs: config.pollIntervalMs ?? DEFAULTS.pollIntervalMs,
+    pollMaxIntervalMs: config.pollMaxIntervalMs ?? DEFAULTS.pollMaxIntervalMs,
     fetchImpl: config.fetch ?? fetch,
-    headers: config.headers ?? {},
-    tokenCache: config.tokenCache
+    headers: config.headers ?? {}
   };
 }
+function normalizeApiBaseUrl(value) {
+  const trimmed = value.replace(/\/+$/, "");
+  return /\/v\d+$/i.test(trimmed) ? trimmed : `${trimmed}/v1`;
+}
 
 // src/http/http-client.ts
 var HttpClient = class {
@@ -201,19 +214,23 @@ var HttpClient = class {
   }
   async requestRaw(method, path, options = {}) {
     let res = await this.send(method, path, options);
-    if (res.status === 401) {
-      this.opts.tokenManager.invalidate();
-      res = await this.send(method, path, options);
+    if (res.status === 401 && this.opts.getAccessToken) {
+      res = await this.send(method, path, options, true);
     }
     if (!res.ok) {
       const requestId = res.headers.get("x-request-id") ?? void 0;
       const message = await this.extractMessage(res);
-      throw errorFromResponse(res.status, message, requestId);
+      throw errorFromResponse(
+        res.status,
+        message,
+        requestId,
+        parseRetryAfterMs(res.headers.get("retry-after"))
+      );
     }
     return res;
   }
-  async send(method, path, options) {
-    const token = await this.opts.tokenManager.getToken();
+  async send(method, path, options, forceRefresh = false) {
+    const token = await this.resolveToken(forceRefresh);
     const url = new URL(this.opts.apiBaseUrl + path);
     for (const [k, v] of Object.entries(options.query ?? {})) url.searchParams.set(k, v);
     const headers = {
@@ -235,6 +252,13 @@ var HttpClient = class {
       throw err;
     }
   }
+  async resolveToken(forceRefresh) {
+    const token = this.opts.getAccessToken ? await this.opts.getAccessToken(forceRefresh ? { forceRefresh: true } : void 0) : this.opts.accessToken;
+    if (!token) {
+      throw new DocmanaError("Missing Docmana access token", { code: "auth_missing" });
+    }
+    return token;
+  }
   async extractMessage(res) {
     try {
       const data = await res.clone().json();
@@ -244,6 +268,18 @@ var HttpClient = class {
     }
   }
 };
+function parseRetryAfterMs(value) {
+  if (!value) return void 0;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) {
+    return seconds * 1e3;
+  }
+  const retryAt = Date.parse(value);
+  if (!Number.isNaN(retryAt)) {
+    return Math.max(0, retryAt - Date.now());
+  }
+  return void 0;
+}
 
 // src/files/resolve-input.ts
 import { readFile } from "fs/promises";
@@ -275,16 +311,19 @@ async function streamToBuffer(stream) {
   for await (const chunk of stream) chunks.push(Buffer.from(chunk));
   return Buffer.concat(chunks);
 }
+function toBlobBytes(bytes) {
+  return new Uint8Array(bytes);
+}
 async function resolveOne(input, fallbackName) {
   if (typeof input === "string" || isPathInput(input)) {
     const path = typeof input === "string" ? input : input.path;
     const data = await readFile(path);
     const filename = basename(path);
-    return { data: new Blob([data]), filename, contentType: contentTypeFor(filename) };
+    return { data: new Blob([toBlobBytes(data)]), filename, contentType: contentTypeFor(filename) };
   }
   if (input instanceof Uint8Array) {
     return {
-      data: new Blob([input]),
+      data: new Blob([toBlobBytes(input)]),
       filename: fallbackName,
       contentType: contentTypeFor(fallbackName)
     };
@@ -292,7 +331,7 @@ async function resolveOne(input, fallbackName) {
   if (isReadable(input)) {
     const buf = await streamToBuffer(input);
     return {
-      data: new Blob([buf]),
+      data: new Blob([toBlobBytes(buf)]),
       filename: fallbackName,
       contentType: contentTypeFor(fallbackName)
     };
@@ -306,38 +345,43 @@ async function resolveInputs(input) {
   return Promise.all(list.map((item) => resolveOne(item, fallback)));
 }
 
-// src/api/upload.ts
-async function uploadFiles(http, parts, signal) {
+// src/api/run-flow.ts
+async function runFlow(http, flowId, parts, signal, useDraftVersion = false, context, callbackUrl, language) {
   const form = new FormData();
   for (const part of parts) {
     form.append("files", new File([part.data], part.filename, { type: part.contentType }));
   }
-  const res = await http.requestJson("POST", "/upload", { body: form, signal });
-  return [res.id];
-}
-
-// src/api/run-flow.ts
-async function runFlow(http, flowId, uuidFiles, signal, once = false, context) {
-  const path = once ? `/flows/run_once_flow/${flowId}` : `/flows/run_flow/${flowId}`;
-  const body = { uuid_files: uuidFiles };
-  if (context !== void 0) body.json_context = context;
-  const res = await http.requestJson("POST", path, {
-    query: { async_mode: "true" },
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify(body),
-    signal
-  });
-  return res.execution_result_id;
+  if (context !== void 0) form.append("json_context", JSON.stringify(context));
+  if (callbackUrl !== void 0) form.append("callback_url", callbackUrl);
+  if (language !== void 0) form.append("language", language);
+  if (useDraftVersion) form.append("useDraftVersion", "true");
+  return http.requestJson(
+    "POST",
+    `/flows/${flowId}/execute-async`,
+    { body: form, signal }
+  );
 }
 
 // src/api/execution-status.ts
 async function getStatus(http, executionResultId, signal) {
-  return http.requestJson("GET", `/flows/execution-status/${executionResultId}`, { signal });
+  const res = await http.requestRaw("GET", `/executions/${executionResultId}/status`, { signal });
+  const text = await res.text();
+  const body = text ? JSON.parse(text) : { status: "" };
+  const pollAfterMs = parsePositiveInt(res.headers.get("x-poll-after"));
+  return pollAfterMs === void 0 ? body : { ...body, pollAfterMs };
+}
+function parsePositiveInt(value) {
+  if (!value) return void 0;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : void 0;
 }
 
 // src/api/execution-result.ts
-async function getResult(http, executionResultId, signal) {
-  return http.requestJson("GET", `/flows/execution-result/${executionResultId}`, { signal });
+async function getResult(http, executionResultId, signal, language) {
+  return http.requestJson("GET", `/executions/${executionResultId}/result`, {
+    query: language ? { language } : void 0,
+    signal
+  });
 }
 
 // src/polling/poll.ts
@@ -347,166 +391,42 @@ async function pollUntilTerminal(opts) {
   const sleep = opts.sleep ?? defaultSleep;
   const start = Date.now();
   const elapsed = opts.elapsed ?? (() => Date.now() - start);
+  const random = opts.random ?? Math.random;
+  let fallbackAttempt = 0;
   for (; ; ) {
     if (opts.signal?.aborted) throw new DocmanaAbortError("Polling aborted");
-    const status = await opts.check();
+    let result;
+    try {
+      result = normalizePollResult(await opts.check());
+    } catch (err) {
+      if (!(err instanceof DocmanaRateLimitError)) throw err;
+      if (elapsed() >= opts.timeoutMs) {
+        throw new DocmanaTimeoutError(`Execution did not finish within ${opts.timeoutMs}ms`);
+      }
+      await sleep(err.retryAfterMs ?? opts.intervalMs);
+      continue;
+    }
+    const { status } = result;
     if (TERMINAL.has(status)) return status;
     if (elapsed() >= opts.timeoutMs) {
       throw new DocmanaTimeoutError(`Execution did not finish within ${opts.timeoutMs}ms`);
     }
-    await sleep(opts.intervalMs);
+    const fallbackDelay = fullJitterDelay(
+      opts.intervalMs,
+      opts.maxIntervalMs,
+      fallbackAttempt,
+      random
+    );
+    fallbackAttempt += 1;
+    await sleep(result.nextDelayMs ?? fallbackDelay);
   }
 }
-
-// src/mappers/mapper.ts
-function extractNodeFields(rawNode, targetLanguage) {
-  const metadataFields = /* @__PURE__ */ new Set([
-    "node_id",
-    "node_name",
-    "node_type",
-    "feature_name",
-    "running_time",
-    "status",
-    "score",
-    "feedback",
-    "translations",
-    "tokens",
-    "input_tokens",
-    "output_tokens",
-    "errors",
-    "mana",
-    "model",
-    "tool_calls",
-    "prompt_id",
-    "prompt",
-    "prompt_name",
-    "label",
-    "scoreDescription",
-    "score_description",
-    "result",
-    "documentType"
-  ]);
-  let sourceObj = rawNode;
-  if (targetLanguage) {
-    const translations = rawNode.translations;
-    if (!translations || !translations[targetLanguage]) {
-      throw new DocmanaError(
-        `Translation for language '${targetLanguage}' is missing on node '${rawNode.node_name || rawNode.node_id}'`,
-        { code: "translation_missing", status: 400 }
-      );
-    }
-    sourceObj = translations[targetLanguage];
-  }
-  const dynamicFields = {};
-  for (const [key, value] of Object.entries(sourceObj)) {
-    if (!metadataFields.has(key)) {
-      dynamicFields[key] = value;
-    }
-  }
-  const sdkNode = {
-    status: rawNode.status || "Unknown"
-  };
-  if (rawNode.errors && rawNode.errors.length > 0) {
-    sdkNode.errors = rawNode.errors;
-  }
-  const nodeType = rawNode.node_type || "";
-  const isScoreNode = /^(Validation|Classification|CrossValidation|Conclusion|Finish)$/i.test(
-    nodeType
-  );
-  if (isScoreNode && rawNode.score !== void 0 && rawNode.score !== null) {
-    sdkNode.score = rawNode.score;
-  }
-  const feedback = sourceObj.feedback ?? rawNode.feedback;
-  if (feedback !== void 0 && feedback !== null) {
-    sdkNode.feedback = feedback;
-  }
-  if (Object.keys(dynamicFields).length > 0) {
-    sdkNode.data = dynamicFields;
-  }
-  return sdkNode;
+function normalizePollResult(result) {
+  return typeof result === "string" ? { status: result } : result;
 }
-function mapExecutionResult(raw, targetLanguage) {
-  const sdkResult = {
-    status: raw.status || "Unknown",
-    executionId: String(raw.execution_id || raw.executionResultId || raw.execution_result_id || ""),
-    documents: {
-      mappings: []
-    }
-  };
-  if (raw.errors && raw.errors.length > 0) {
-    sdkResult.errors = raw.errors;
-  }
-  const results = raw.results || [];
-  for (const item of results) {
-    const isDocSpecific = !!item.document;
-    if (isDocSpecific && item.document) {
-      const docReq = item.document;
-      const docKey = docReq.doc_key || "unknown_doc";
-      const docName = docReq.name || "";
-      sdkResult.documents.mappings.push({
-        name: docName,
-        reference: docKey
-      });
-      const docResult = {
-        status: item.status || docReq.status || "Unknown",
-        extractions: {},
-        validations: {}
-      };
-      const nodeResults = item.node_results || [];
-      for (const node of nodeResults) {
-        const nodeType = node.node_type || "";
-        const nodeName = node.node_name || node.node_id || "unknown_node";
-        if (/^Classification$/i.test(nodeType)) {
-          const mappedNode = extractNodeFields(node, targetLanguage);
-          if (!docResult.classifications) {
-            docResult.classifications = {};
-          }
-          docResult.classifications[nodeName] = mappedNode;
-        } else if (/^MetadataExtraction$/i.test(nodeType)) {
-          docResult.metadataExtraction = extractNodeFields(node, targetLanguage);
-        } else if (/^Extraction$/i.test(nodeType)) {
-          if (docResult.extractions) {
-            docResult.extractions[nodeName] = extractNodeFields(node, targetLanguage);
-          }
-        } else if (/^Validation$/i.test(nodeType)) {
-          if (docResult.validations) {
-            docResult.validations[nodeName] = extractNodeFields(node, targetLanguage);
-          }
-        }
-      }
-      if (docResult.extractions && Object.keys(docResult.extractions).length === 0) {
-        delete docResult.extractions;
-      }
-      if (docResult.validations && Object.keys(docResult.validations).length === 0) {
-        delete docResult.validations;
-      }
-      sdkResult.documents[docKey] = docResult;
-    } else {
-      const nodeResults = item.node_results || [];
-      for (const node of nodeResults) {
-        const nodeType = node.node_type || "";
-        const nodeName = node.node_name || node.node_id || "unknown_node";
-        if (/^CrossValidation$/i.test(nodeType)) {
-          if (!sdkResult.crossValidations) {
-            sdkResult.crossValidations = {};
-          }
-          sdkResult.crossValidations[nodeName] = extractNodeFields(
-            node,
-            targetLanguage
-          );
-        } else if (/^(Conclusion|Finish)$/i.test(nodeType)) {
-          if (!sdkResult.conclusions) {
-            sdkResult.conclusions = {};
-          }
-          sdkResult.conclusions[nodeName] = extractNodeFields(
-            node,
-            targetLanguage
-          );
-        }
-      }
-    }
-  }
-  return sdkResult;
+function fullJitterDelay(intervalMs, maxIntervalMs, attempt, random) {
+  const capDelay = Math.min(maxIntervalMs, intervalMs * 2 ** attempt);
+  return Math.round(intervalMs + random() * (capDelay - intervalMs));
 }
 
 // src/client.ts
@@ -515,46 +435,79 @@ var Docmana = class {
   http;
   constructor(config) {
     this.config = resolveConfig(config);
-    const tokenManager = new TokenManager({
-      clientId: this.config.clientId,
-      clientSecret: this.config.clientSecret,
-      tokenEndpoint: this.config.tokenEndpoint,
-      scope: this.config.scope,
-      fetchImpl: this.config.fetchImpl,
-      tokenCache: this.config.tokenCache
-    });
     this.http = new HttpClient({
       apiBaseUrl: this.config.apiBaseUrl,
       fetchImpl: this.config.fetchImpl,
-      tokenManager,
+      accessToken: this.config.accessToken,
+      getAccessToken: this.config.getAccessToken,
       headers: this.config.headers
     });
   }
   async runFlowAsync(flowId, input) {
     const parts = await resolveInputs(input);
-    const fileIds = await uploadFiles(this.http, parts, input.signal);
-    const executionResultId = await runFlow(
+    return runFlow(
       this.http,
       flowId,
-      fileIds,
+      parts,
       input.signal,
-      input.once ?? false,
-      input.context
+      input.useDraftVersion ?? false,
+      input.context,
+      void 0,
+      input.language
+    );
+  }
+  async runFlowWithCallback(flowId, input) {
+    const parts = await resolveInputs(input);
+    return runFlow(
+      this.http,
+      flowId,
+      parts,
+      input.signal,
+      input.useDraftVersion ?? false,
+      input.context,
+      input.callbackUrl,
+      input.language
     );
-    return { executionResultId, fileIds };
   }
   async getStatus(executionResultId, signal) {
     return getStatus(this.http, executionResultId, signal);
   }
   async getResult(executionResultId, signal, language) {
-    const rawResult = await getResult(this.http, executionResultId, signal);
-    return mapExecutionResult(rawResult, language);
+    return getResult(this.http, executionResultId, signal, language);
   }
   async runFlow(flowId, input) {
     const { executionResultId } = await this.runFlowAsync(flowId, input);
+    let attempt = 0;
+    const startedAt = Date.now();
     await pollUntilTerminal({
-      check: async () => (await this.getStatus(executionResultId, input.signal)).status,
+      check: async () => {
+        attempt += 1;
+        try {
+          const statusResult = await this.getStatus(executionResultId, input.signal);
+          const status = statusResult.status;
+          const nextPollAfterMs = this.isTerminalStatus(status) ? void 0 : statusResult.pollAfterMs;
+          input.onPoll?.({
+            executionResultId,
+            status,
+            attempt,
+            elapsedMs: Date.now() - startedAt,
+            nextPollAfterMs
+          });
+          return { status, nextDelayMs: nextPollAfterMs };
+        } catch (err) {
+          if (err instanceof DocmanaRateLimitError) {
+            input.onRateLimit?.({
+              executionResultId,
+              attempt,
+              elapsedMs: Date.now() - startedAt,
+              retryAfterMs: err.retryAfterMs ?? input.pollIntervalMs ?? this.config.pollIntervalMs
+            });
+          }
+          throw err;
+        }
+      },
       intervalMs: input.pollIntervalMs ?? this.config.pollIntervalMs,
+      maxIntervalMs: input.pollMaxIntervalMs ?? this.config.pollMaxIntervalMs,
       timeoutMs: input.timeoutMs ?? this.config.timeoutMs,
       signal: input.signal
     });
@@ -568,6 +521,9 @@ var Docmana = class {
     }
     return result;
   }
+  isTerminalStatus(status) {
+    return status === "Completed" || status === "Failed";
+  }
 };
 
 // src/cli.ts
@@ -638,7 +594,7 @@ function buildProgram(env, io, clientFactory, deps) {
   const flow = program.command("flow").description(HELP.flow).action(() => {
     io.stdout(flow.helpInformation());
   });
-  flow.command("run").description(HELP.run).argument("<flow-id>", "Docmana flow id").requiredOption("--files <csv>", "Comma-separated file paths to upload").option("--client-id <id>", "OAuth2 client id; defaults to DOCMANA_CLIENT_ID").option("--client-secret <secret>", "OAuth2 client secret; defaults to DOCMANA_CLIENT_SECRET").option("--api-url <url>", "Docmana API base URL; defaults to DOCMANA_API_URL").option("--token-url <url>", "OAuth2 token endpoint; defaults to DOCMANA_TOKEN_URL").option("--scope <scope>", "OAuth2 scope; defaults to DOCMANA_SCOPE").option("--organisation <id>", "Docmana organisation id; defaults to DOCMANA_ORGANISATION").option("--config <path>", `Config file path; defaults to ./${DEFAULT_CONFIG_FILE}`).option("--token-cache <path>", `Token cache path; defaults to ./${DEFAULT_TOKEN_CACHE_FILE}`).option("--json", "Print the raw JSON result").option("--language <lang>", "Translate output to specified language").action(async (flowId, options) => {
+  flow.command("run").description(HELP.run).argument("<flow-id>", "Docmana flow id").requiredOption("--files <csv>", "Comma-separated file paths to upload").option("--api-url <url>", "Consumer API base URL; defaults to DOCMANA_API_URL").option("--access-token <token>", "Bearer token; defaults to DOCMANA_ACCESS_TOKEN").option("--config <path>", `Config file path; defaults to ./${DEFAULT_CONFIG_FILE}`).option("--token-cache <path>", `Token cache path; defaults to ./${DEFAULT_TOKEN_CACHE_FILE}`).option("--json", "Print the raw JSON result").option("--language <lang>", "Translate output to specified language").option("--draft", "Run the current draft flow version").action(async (flowId, options) => {
     await runFlowCommand(flowId, options, env, io, clientFactory, deps);
   });
   const config = program.command("config").description(HELP.config).action(() => {
@@ -653,46 +609,35 @@ async function runFlowCommand(flowId, options, env, io, clientFactory, deps) {
   try {
     const files = parseFiles(options.files);
     const cliConfig = await loadCliConfig(options.config, getCwd(deps), Boolean(options.config));
-    const clientId = firstNonEmpty(options.clientId, env.DOCMANA_CLIENT_ID, cliConfig.clientId);
-    const clientSecret = firstNonEmpty(
-      options.clientSecret,
-      env.DOCMANA_CLIENT_SECRET,
-      cliConfig.clientSecret
-    );
-    const organisation = firstNonEmpty(
-      options.organisation,
-      env.DOCMANA_ORGANISATION,
-      cliConfig.organisation
-    );
     const apiBaseUrl = firstNonEmpty(options.apiUrl, env.DOCMANA_API_URL, cliConfig.apiBaseUrl);
-    const tokenEndpoint = firstNonEmpty(
-      options.tokenUrl,
-      env.DOCMANA_TOKEN_URL,
-      cliConfig.tokenEndpoint
-    );
-    const scope = firstNonEmpty(options.scope, env.DOCMANA_SCOPE, cliConfig.scope);
-    if (!clientId)
-      throw new CliUsageError("Missing client id. Use --client-id or DOCMANA_CLIENT_ID.");
-    if (!clientSecret) {
-      throw new CliUsageError(
-        "Missing client secret. Use --client-secret or DOCMANA_CLIENT_SECRET."
-      );
-    }
-    if (!organisation) {
-      throw new CliUsageError("Missing organisation. Use --organisation or DOCMANA_ORGANISATION.");
+    if (!apiBaseUrl) {
+      throw new CliUsageError("Missing API base URL. Use --api-url or DOCMANA_API_URL.");
     }
+    const tokenCache = createFileTokenCache(
+      resolveTokenCachePath(options.tokenCache, getCwd(deps))
+    );
+    const accessToken = firstNonEmpty(options.accessToken, env.DOCMANA_ACCESS_TOKEN) ?? await resolveFlowAccessToken(env, cliConfig, tokenCache, deps, io);
     const client = clientFactory({
-      clientId,
-      clientSecret,
       apiBaseUrl,
-      tokenEndpoint,
-      scope,
-      headers: { "X-Selected-Organization": organisation },
-      tokenCache: createFileTokenCache(resolveTokenCachePath(options.tokenCache, getCwd(deps)))
+      accessToken
     });
     const result = await client.runFlow(flowId, {
       files: files.map((path) => ({ path })),
-      language: options.language
+      language: options.language,
+      useDraftVersion: options.draft === true,
+      onPoll: (event) => {
+        const nextPoll = event.nextPollAfterMs === void 0 ? "" : `, next poll in ${formatElapsedSeconds(event.nextPollAfterMs)}`;
+        io.stderr(
+          `Polling execution ${event.executionResultId}: ${event.status} (attempt ${event.attempt}, elapsed ${formatElapsedSeconds(event.elapsedMs)}${nextPoll})
+`
+        );
+      },
+      onRateLimit: (event) => {
+        io.stderr(
+          `Polling execution ${event.executionResultId}: rate limited (attempt ${event.attempt}, retrying in ${formatElapsedSeconds(event.retryAfterMs)})
+`
+        );
+      }
     });
     if (options.json) {
       io.stdout(`${JSON.stringify(result, null, 2)}
@@ -722,10 +667,38 @@ async function runFlowCommand(flowId, options, env, io, clientFactory, deps) {
     throw err;
   }
 }
+async function resolveFlowAccessToken(env, cliConfig, tokenCache, deps, io) {
+  const cached = await readFreshCachedToken(tokenCache);
+  if (cached) return cached;
+  const clientId = firstNonEmpty(env.DOCMANA_CLIENT_ID, cliConfig.clientId);
+  const clientSecret = firstNonEmpty(env.DOCMANA_CLIENT_SECRET, cliConfig.clientSecret);
+  if (!clientId || !clientSecret) {
+    throw new CliUsageError(
+      "Missing access token. Use --access-token, DOCMANA_ACCESS_TOKEN, docmana login, or configure OAuth credentials."
+    );
+  }
+  const tokenManager = new TokenManager({
+    clientId,
+    clientSecret,
+    tokenEndpoint: firstNonEmpty(env.DOCMANA_TOKEN_URL, cliConfig.tokenEndpoint) ?? DEFAULTS.tokenEndpoint,
+    scope: firstNonEmpty(env.DOCMANA_SCOPE, cliConfig.scope) ?? DEFAULTS.scope,
+    fetchImpl: deps.fetch ?? fetch,
+    tokenCache
+  });
+  const token = await tokenManager.getToken();
+  io.stderr("Generated new access token and updated the token cache.\n");
+  return token;
+}
+async function readFreshCachedToken(tokenCache) {
+  const cached = await tokenCache.read().catch(() => null);
+  if (!cached || Date.now() >= cached.expiresAt) return void 0;
+  return cached.accessToken;
+}
 async function loginCommand(options, env, io, deps) {
   const auth = await resolveAuthConfig(options, env, deps);
   const tokenCachePath = resolveTokenCachePath(options.tokenCache, getCwd(deps));
   const tokenCache = createFileTokenCache(tokenCachePath);
+  const hadFreshCachedToken = Boolean(await readFreshCachedToken(tokenCache));
   const tokenManager = new TokenManager({
     clientId: auth.clientId,
     clientSecret: auth.clientSecret,
@@ -736,6 +709,9 @@ async function loginCommand(options, env, io, deps) {
   });
   await tokenManager.getToken();
   const cached = await tokenCache.read();
+  if (!hadFreshCachedToken) {
+    io.stdout("Generated new access token and updated the token cache.\n");
+  }
   io.stdout(`Logged in. Token cached at ${tokenCachePath}
 `);
   if (cached) io.stdout(formatTokenExpiry(cached.expiresAt));
@@ -774,7 +750,7 @@ async function configInitCommand(options, io, deps) {
   try {
     const config = {
       apiBaseUrl: await prompt("API base URL", {
-        defaultValue: existing.apiBaseUrl ?? DEFAULTS.apiBaseUrl
+        defaultValue: existing.apiBaseUrl
       }),
       tokenEndpoint: await prompt("OAuth2 token endpoint", {
         defaultValue: existing.tokenEndpoint ?? DEFAULTS.tokenEndpoint
@@ -782,9 +758,6 @@ async function configInitCommand(options, io, deps) {
       scope: await prompt("OAuth2 scope", {
         defaultValue: existing.scope ?? DEFAULTS.scope
       }),
-      organisation: await prompt("Organisation", {
-        defaultValue: existing.organisation
-      }),
       clientId: await prompt("Client id", {
         defaultValue: existing.clientId
       }),
@@ -833,7 +806,6 @@ function normalizeCliConfig(config) {
     apiBaseUrl: stringValue(config.apiBaseUrl),
     tokenEndpoint: stringValue(config.tokenEndpoint),
     scope: stringValue(config.scope),
-    organisation: stringValue(config.organisation),
     clientId: stringValue(config.clientId),
     clientSecret: stringValue(config.clientSecret)
   };
@@ -909,6 +881,9 @@ function formatPrompt(label, options) {
   const defaultHint = options.defaultValue && !options.secret ? ` [${options.defaultValue}]` : options.defaultValue && options.secret ? " [current value hidden]" : "";
   return `${label}${defaultHint}: `;
 }
+function formatElapsedSeconds(elapsedMs) {
+  return `${Math.floor(elapsedMs / 1e3)}s`;
+}
 async function readStdinLines() {
   let input = "";
   for await (const chunk of process.stdin) input += String(chunk);