@aigne/doc-smith 0.9.2 → 0.9.3-beta

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.9.3-beta](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.9.2...v0.9.3-beta) (2025-11-13)
+
+
+### Features
+
+* **docs:** Enhance publishing with Discuss Kit and localized access tokens ([#301](https://github.com/AIGNE-io/aigne-doc-smith/issues/301)) ([c34f16f](https://github.com/AIGNE-io/aigne-doc-smith/commit/c34f16fdc3a07cb1408f50c5e10aa80f1c7b90cf))
+
 ## [0.9.2](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.9.2-beta...v0.9.2) (2025-11-12)
 
 ## [0.9.2-beta](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.9.1...v0.9.2-beta) (2025-11-12)

package/agents/publish/publish-docs.mjs

@@ -4,7 +4,11 @@ import { BrokerClient } from "@blocklet/payment-broker-client/node";
 import chalk from "chalk";
 import fs from "fs-extra";
 
-import { getAccessToken, getOfficialAccessToken } from "../../utils/auth-utils.mjs";
+import {
+  getAccessToken,
+  getDiscussKitMountPoint,
+  getOfficialAccessToken,
+} from "../../utils/auth-utils.mjs";
 import {
   CLOUD_SERVICE_URL_PROD,
   DISCUSS_KIT_STORE_URL,
@@ -17,6 +21,7 @@ import { deploy } from "../../utils/deploy.mjs";
 import { getGithubRepoUrl, loadConfigFromFile, saveValueToConfig } from "../../utils/utils.mjs";
 import updateBranding from "../utils/update-branding.mjs";
 import { isRemoteFile, downloadAndUploadImage } from "../../utils/file-utils.mjs";
+import { joinURL } from "ufo";
 
 const BASE_URL = process.env.DOC_SMITH_BASE_URL || CLOUD_SERVICE_URL_PROD;
 
@@ -72,13 +77,12 @@ export default async function publishDocs(
     let client = null;
     let authToken = null;
     let sessionId = null;
+    let locale = config?.locale;
 
     if (!hasInputAppUrl) {
       authToken = await getOfficialAccessToken(BASE_URL, false);
 
       sessionId = "";
-      let paymentLink = "";
-
       if (authToken) {
         client = new BrokerClient({ baseUrl: BASE_URL, authToken });
         const info = await client.checkCacheSession({
@@ -86,7 +90,6 @@ export default async function publishDocs(
           sessionId: config?.checkoutId,
         });
         sessionId = info.sessionId;
-        paymentLink = info.paymentLink;
       }
 
       const choice = await options.prompts.select({
@@ -137,7 +140,8 @@ export default async function publishDocs(
         appUrl = userInput.includes("://") ? userInput : `https://${userInput}`;
       } else if (["new-instance", "new-instance-continue"].includes(choice)) {
         // resume previous website setup
-        if (choice === "new-instance-continue") {
+        const isNewInstance = choice === "new-instance";
+        if (!isNewInstance) {
           shouldSyncBranding = config?.shouldSyncBranding ?? void 0;
           if (shouldSyncBranding !== void 0) {
             shouldWithBranding = shouldWithBranding ?? shouldSyncBranding;
@@ -165,7 +169,7 @@ export default async function publishDocs(
 
         try {
           let id = "";
-          if (choice === "new-instance-continue") {
+          if (!isNewInstance) {
             id = sessionId;
             console.log(`\nResuming your previous website setup...`);
           } else {
@@ -175,11 +179,13 @@ export default async function publishDocs(
             appUrl: homeUrl,
             token: ltToken,
             sessionId: newSessionId,
-          } = (await deploy(id, paymentLink)) || {};
+            data,
+          } = (await deploy(id, isNewInstance ? locale : undefined)) || {};
 
           sessionId = newSessionId;
           appUrl = homeUrl;
           token = ltToken;
+          locale = data?.preferredLocale || locale;
         } catch (error) {
           const errorMsg = error?.message || "Unknown error occurred";
           return { message: `${chalk.red("❌ Failed to create website:")} ${errorMsg}` };
@@ -189,9 +195,14 @@ export default async function publishDocs(
 
     appUrl = appUrl ?? CLOUD_SERVICE_URL_PROD;
 
-    console.log(`\nPublishing your documentation to ${chalk.cyan(appUrl)}\n`);
+    const appUrlInfo = new URL(appUrl);
+
+    const discussKitMountPoint = await getDiscussKitMountPoint(appUrlInfo.origin);
+    const discussKitUrl = joinURL(appUrlInfo.origin, discussKitMountPoint);
+
+    console.log(`\nPublishing your documentation to ${chalk.cyan(discussKitUrl)}\n`);
 
-    const accessToken = await getAccessToken(appUrl, token);
+    const accessToken = await getAccessToken(appUrlInfo.origin, token, locale);
 
     process.env.DOC_ROOT_DIR = docsDir;
 
@@ -211,7 +222,7 @@ export default async function publishDocs(
       const { url: uploadedImageUrl, downloadFinalPath } = await downloadAndUploadImage(
         projectInfo.icon,
         docsDir,
-        appUrl,
+        discussKitUrl,
         accessToken,
       );
       projectInfo.icon = uploadedImageUrl;
@@ -219,7 +230,7 @@ export default async function publishDocs(
     }
 
     if (shouldWithBranding) {
-      updateBranding({ appUrl, projectInfo, accessToken, finalPath });
+      updateBranding({ appUrl: discussKitUrl, projectInfo, accessToken, finalPath });
     }
 
     // Construct boardMeta object
@@ -243,7 +254,7 @@ export default async function publishDocs(
     } = await publishDocsFn({
       sidebarPath,
       accessToken,
-      appUrl,
+      appUrl: discussKitUrl,
       boardId,
       autoCreateBoard: true,
       // Pass additional project information if available
@@ -259,7 +270,7 @@ export default async function publishDocs(
     if (success) {
       // Save appUrl to config only when not using environment variable
       if (!useEnvAppUrl) {
-        await saveValueToConfig("appUrl", appUrl);
+        await saveValueToConfig("appUrl", appUrlInfo.origin);
       }
 
       // Save boardId to config if it was auto-created
@@ -286,7 +297,7 @@ export default async function publishDocs(
     // clean up tmp work dir
     await fs.rm(docsDir, { recursive: true, force: true });
   } catch (error) {
-    message = `❌ Sorry, I encountered an error while publishing your documentation: ${error.message}`;
+    message = `❌ Sorry, I encountered an error while publishing your documentation: \n\n${error.message}`;
 
     // clean up tmp work dir in case of error
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.9.2",
+  "version": "0.9.3-beta",
   "description": "AI-driven documentation generation tool built on the AIGNE Framework",
   "publishConfig": {
     "access": "public"
@@ -24,10 +24,10 @@
   "author": "Arcblock <blocklet@arcblock.io> https://github.com/blocklet",
   "license": "Elastic-2.0",
   "dependencies": {
-    "@aigne/cli": "^1.53.1-beta.4",
-    "@aigne/core": "^1.65.1-beta.3",
-    "@aigne/publish-docs": "^0.12.1",
-    "@blocklet/payment-broker-client": "^1.22.8",
+    "@aigne/cli": "^1.54.1",
+    "@aigne/core": "^1.67.0",
+    "@aigne/publish-docs": "^0.13.0",
+    "@blocklet/payment-broker-client": "^1.22.10",
     "@terrastruct/d2": "^0.1.33",
     "chalk": "^5.5.0",
     "debug": "^4.4.1",

package/utils/auth-utils.mjs

@@ -20,36 +20,44 @@ import {
   DISCUSS_KIT_DID,
   DISCUSS_KIT_STORE_URL,
   DOC_OFFICIAL_ACCESS_TOKEN,
+  PAYMENT_KIT_DID,
 } from "./constants/index.mjs";
+import { requestWithAuthToken } from "./request.mjs";
+import { withQuery } from "ufo";
 
 const WELLKNOWN_SERVICE_PATH_PREFIX = "/.well-known/service";
 
+const TIMEOUT_MINUTES = 5; // Just wait 5 min
+const FETCH_INTERVAL = 3000; // 3 seconds
+
+const RETRY_COUNT = (TIMEOUT_MINUTES * 60 * 1000) / FETCH_INTERVAL;
+
 export function getDocSmithEnvFilePath() {
   return join(homedir(), ".aigne", "doc-smith-connected.yaml");
 }
 
 /**
  * Get access token from environment, config file, or prompt user for authorization
- * @param {string} appUrl - The application URL
+ * @param {string} baseUrl - The application URL
  * @returns {Promise<string>} - The access token
  */
-export async function getAccessToken(appUrl, ltToken = "") {
-  const { hostname } = new URL(appUrl);
+async function getCachedAccessToken(baseUrl) {
+  const { hostname: targetHostname } = new URL(baseUrl);
   const DOC_SMITH_ENV_FILE = getDocSmithEnvFilePath();
 
   let accessToken =
-    process.env.DOC_SMITH_PUBLISH_ACCESS_TOKEN || process.env.DOC_DISCUSS_KIT_ACCESS_TOKEN;
+    process.env.DOC_SMITH_PUBLISH_ACCESS_TOKEN || process.env[DOC_OFFICIAL_ACCESS_TOKEN];
 
   // Check if access token exists in environment or config file
   if (!accessToken) {
     try {
       if (existsSync(DOC_SMITH_ENV_FILE)) {
         const data = await readFile(DOC_SMITH_ENV_FILE, "utf8");
-        if (data.includes("DOC_DISCUSS_KIT_ACCESS_TOKEN")) {
+        if (data.includes(DOC_OFFICIAL_ACCESS_TOKEN)) {
           // Handle empty or invalid YAML files
           const envs = data.trim() ? parse(data) : null;
-          if (envs?.[hostname]?.DOC_DISCUSS_KIT_ACCESS_TOKEN) {
-            accessToken = envs[hostname].DOC_DISCUSS_KIT_ACCESS_TOKEN;
+          if (envs?.[targetHostname]?.[DOC_OFFICIAL_ACCESS_TOKEN]) {
+            accessToken = envs[targetHostname][DOC_OFFICIAL_ACCESS_TOKEN];
           }
         }
       }
@@ -58,14 +66,13 @@ export async function getAccessToken(appUrl, ltToken = "") {
     }
   }
 
-  // If still no access token, prompt user to authorize
-  if (accessToken) {
-    return accessToken;
-  }
+  return accessToken;
+}
 
-  // Check if Discuss Kit is running at the provided URL
+export const getDiscussKitMountPoint = async (origin) => {
   try {
-    await getComponentMountPoint(appUrl, DISCUSS_KIT_DID);
+    const mountPoint = await getComponentMountPoint(origin, DISCUSS_KIT_DID);
+    return mountPoint;
   } catch (error) {
     const storeLink = chalk.cyan(DISCUSS_KIT_STORE_URL);
     if (error instanceof InvalidBlockletError) {
@@ -83,7 +90,7 @@ export async function getAccessToken(appUrl, ltToken = "") {
       );
     } else {
       throw new Error(
-        `❌ Could not connect to: ${chalk.cyan(appUrl)}\n\n` +
+        `❌ Could not connect to: ${chalk.cyan(origin)}\n\n` +
           `${chalk.bold("Possible causes:")}\n` +
           `• There may be a network issue.\n` +
           `• The server may be temporarily unavailable.\n` +
@@ -92,9 +99,24 @@ export async function getAccessToken(appUrl, ltToken = "") {
       );
     }
   }
+};
+
+/**
+ * Get access token from environment, config file, or prompt user for authorization
+ * @param {string} appUrl - The application URL
+ * @returns {Promise<string>} - The access token
+ */
+export async function getAccessToken(appUrl, ltToken = "", locale = "en") {
+  const { hostname: targetHostname, origin: targetOrigin } = new URL(appUrl);
+
+  let accessToken = await getCachedAccessToken(targetOrigin);
+
+  // If still no access token, prompt user to authorize
+  if (accessToken) {
+    return accessToken;
+  }
 
-  const DISCUSS_KIT_URL = appUrl;
-  const connectUrl = joinURL(new URL(DISCUSS_KIT_URL).origin, WELLKNOWN_SERVICE_PATH_PREFIX);
+  const connectUrl = joinURL(targetOrigin, WELLKNOWN_SERVICE_PATH_PREFIX);
 
   try {
     const result = await createConnect({
@@ -104,49 +126,63 @@ export async function getAccessToken(appUrl, ltToken = "") {
       closeOnSuccess: true,
       appName: "AIGNE DocSmith",
       appLogo: "https://docsmith.aigne.io/image-bin/uploads/9645caf64b4232699982c4d940b03b90.svg",
-      openPage: (pageUrl) => {
+      retry: RETRY_COUNT,
+      fetchInterval: FETCH_INTERVAL,
+      openPage: async (pageUrl) => {
         const url = new URL(pageUrl);
-        if ([CLOUD_SERVICE_URL_PROD, CLOUD_SERVICE_URL_STAGING].includes(url.origin) === false) {
+        const isOfficial = [CLOUD_SERVICE_URL_PROD, CLOUD_SERVICE_URL_STAGING].includes(url.origin);
+        if (!isOfficial) {
           url.searchParams.set("required_roles", "owner,admin");
         }
         if (ltToken) {
           url.searchParams.set("__lt", ltToken);
         }
+        url.searchParams.set("locale", locale);
 
-        open(url.toString());
+        let connectUrl = url.toString();
+        open(connectUrl);
+
+        try {
+          const officialBaseUrl = process.env.DOC_SMITH_BASE_URL || CLOUD_SERVICE_URL_PROD;
+          const officialAccessToken = await getOfficialAccessToken(officialBaseUrl, false);
+          if (officialAccessToken) {
+            const mountPoint = await getComponentMountPoint(officialBaseUrl, PAYMENT_KIT_DID);
+            const data = await requestWithAuthToken(
+              withQuery(joinURL(officialBaseUrl, mountPoint, "/api/tool/short-url"), {
+                url: connectUrl,
+              }),
+              {},
+              officialAccessToken,
+            );
+            connectUrl = data.url;
+          }
+        } catch {
+          // Ignore error
+        }
+
+        console.log(
+          "🔗 Please open the following URL in your browser to authorize access: ",
+          chalk.cyan(connectUrl),
+          "\n",
+        );
       },
     });
 
     accessToken = result.accessKeySecret;
     process.env.DOC_SMITH_PUBLISH_ACCESS_TOKEN = accessToken;
+    process.env[DOC_OFFICIAL_ACCESS_TOKEN] = accessToken;
 
     // Save the access token to config file
-    const aigneDir = join(homedir(), ".aigne");
-    if (!existsSync(aigneDir)) {
-      mkdirSync(aigneDir, { recursive: true });
-    }
-
-    let existingConfig = {};
-    if (existsSync(DOC_SMITH_ENV_FILE)) {
-      const fileContent = await readFile(DOC_SMITH_ENV_FILE, "utf8");
-      const parsedConfig = fileContent.trim() ? parse(fileContent) : null;
-      existingConfig = parsedConfig || {};
-    }
-
-    await writeFile(
-      DOC_SMITH_ENV_FILE,
-      stringify({
-        ...existingConfig,
-        [hostname]: {
-          DOC_DISCUSS_KIT_ACCESS_TOKEN: accessToken,
-          DOC_DISCUSS_KIT_URL: DISCUSS_KIT_URL,
-        },
-      }),
-    );
-  } catch (error) {
-    console.debug(error);
+    await saveTokenToConfigFile(targetHostname, {
+      [DOC_OFFICIAL_ACCESS_TOKEN]: accessToken,
+    });
+  } catch {
     throw new Error(
-      "Could not get an access token. Please check your network connection and try again.",
+      `${chalk.yellow("⚠️ Failed to obtain access token. This may be due to network issues or authorization timeout.")}\n\n` +
+        `${chalk.bold("💡 Solution:")}\n` +
+        `  • Step 1: Ensure your network can access the service URL: ${chalk.cyan(targetOrigin)}\n` +
+        `  • Step 2: Run ${chalk.cyan("aigne doc publish")} again\n` +
+        `  • Step 3: If prompted, select ${chalk.cyan("Resume previous website setup")} to continue from where you left off\n\n`,
     );
   }
 
@@ -158,34 +194,16 @@ export async function getAccessToken(appUrl, ltToken = "") {
  * @param {string} baseUrl - The official service URL.
  * @returns {Promise<string>} The access token.
  */
-export async function getOfficialAccessToken(baseUrl, openPage = true) {
+export async function getOfficialAccessToken(baseUrl, openPage = true, locale = "en") {
   if (!baseUrl) {
     throw new Error("The baseUrl parameter is required for getOfficialAccessToken.");
   }
 
   // Parse URL once and reuse
-  const urlObj = new URL(baseUrl);
-  const { hostname, origin } = urlObj;
-  const DOC_SMITH_ENV_FILE = getDocSmithEnvFilePath();
+  const { hostname: targetHostname, origin: targetOrigin } = new URL(baseUrl);
 
   // 1. Check environment variable
-  let accessToken = process.env[DOC_OFFICIAL_ACCESS_TOKEN];
-
-  // 2. Check config file if not in env
-  if (!accessToken) {
-    try {
-      if (existsSync(DOC_SMITH_ENV_FILE)) {
-        const data = await readFile(DOC_SMITH_ENV_FILE, "utf8");
-        // Handle empty or invalid YAML files
-        const envs = data.trim() ? parse(data) : null;
-        if (envs) {
-          accessToken = envs[hostname]?.[DOC_OFFICIAL_ACCESS_TOKEN];
-        }
-      }
-    } catch (_error) {
-      // Ignore errors
-    }
-  }
+  let accessToken = await getCachedAccessToken(targetOrigin);
 
   // If token is found, return it
   if (accessToken || !openPage) {
@@ -193,7 +211,7 @@ export async function getOfficialAccessToken(baseUrl, openPage = true) {
   }
 
   // Generate new access token
-  const connectUrl = joinURL(origin, WELLKNOWN_SERVICE_PATH_PREFIX);
+  const connectUrl = joinURL(targetOrigin, WELLKNOWN_SERVICE_PATH_PREFIX);
 
   try {
     const result = await createConnect({
@@ -201,15 +219,22 @@ export async function getOfficialAccessToken(baseUrl, openPage = true) {
       connectAction: "gen-simple-access-key",
       source: "AIGNE DocSmith connect to official service",
       closeOnSuccess: true,
+      retry: RETRY_COUNT,
+      fetchInterval: FETCH_INTERVAL,
       appName: "AIGNE DocSmith",
       appLogo: "https://docsmith.aigne.io/image-bin/uploads/9645caf64b4232699982c4d940b03b90.svg",
       openPage: (pageUrl) => {
+        const url = new URL(pageUrl);
+        if (locale) {
+          url.searchParams.set("locale", locale);
+        }
+        open(url.toString());
+
         console.log(
           "🔗 Please open the following URL in your browser to authorize access: ",
-          chalk.cyan(pageUrl),
+          chalk.cyan(url.toString()),
           "\n",
         );
-        open(pageUrl);
       },
     });
 
@@ -217,16 +242,15 @@ export async function getOfficialAccessToken(baseUrl, openPage = true) {
     process.env[DOC_OFFICIAL_ACCESS_TOKEN] = accessToken;
 
     // Save the access token to config file
-    await saveTokenToConfigFile(
-      DOC_SMITH_ENV_FILE,
-      hostname,
-      DOC_OFFICIAL_ACCESS_TOKEN,
-      accessToken,
-    );
-  } catch (error) {
-    console.debug(error);
+    await saveTokenToConfigFile(targetHostname, {
+      [DOC_OFFICIAL_ACCESS_TOKEN]: accessToken,
+    });
+  } catch {
     throw new Error(
-      "Could not get an official access token. Please check your network connection and try again.",
+      `${chalk.yellow("⚠️ Failed to obtain official access token. This may be due to network issues or authorization timeout.")}\n\n` +
+        `${chalk.bold("💡 Solution:")}\n` +
+        `  • Step 1: Ensure your network can access the official service URL: ${chalk.cyan(targetOrigin)}\n` +
+        `  • Step 2: Run ${chalk.cyan("aigne doc publish")} again\n\n`,
     );
   }
 
@@ -234,14 +258,15 @@ export async function getOfficialAccessToken(baseUrl, openPage = true) {
 }
 
 /**
- * Saves the access token to the configuration file.
+ * Saves the access token and related fields to the configuration file.
  * @param {string} configFile - The path to the config file.
  * @param {string} hostname - The hostname key.
- * @param {string} tokenKey - The token key name.
- * @param {string} tokenValue - The token value.
+ * @param {Object} fields - Fields to save (e.g., { DOC_DISCUSS_KIT_ACCESS_TOKEN: "..." }).
  */
-async function saveTokenToConfigFile(configFile, hostname, tokenKey, tokenValue) {
+async function saveTokenToConfigFile(hostname, fields) {
   try {
+    const configFile = getDocSmithEnvFilePath();
+
     const aigneDir = join(homedir(), ".aigne");
     if (!existsSync(aigneDir)) {
       mkdirSync(aigneDir, { recursive: true });
@@ -250,7 +275,6 @@ async function saveTokenToConfigFile(configFile, hostname, tokenKey, tokenValue)
     let existingConfig = {};
     if (existsSync(configFile)) {
       const fileContent = await readFile(configFile, "utf8");
-      // Handle empty or invalid YAML files
       const parsedConfig = fileContent.trim() ? parse(fileContent) : null;
       existingConfig = parsedConfig || {};
     }
@@ -259,10 +283,7 @@ async function saveTokenToConfigFile(configFile, hostname, tokenKey, tokenValue)
       configFile,
       stringify({
         ...existingConfig,
-        [hostname]: {
-          ...existingConfig[hostname],
-          [tokenKey]: tokenValue,
-        },
+        [hostname]: fields,
       }),
     );
   } catch (error) {

package/utils/deploy.mjs

@@ -14,11 +14,11 @@ const SUCCESS_MESSAGE = {
 /**
  * Deploys a new Discuss Kit Website and returns the installation URL.
  * @param {string} id - The cached checkout ID (optional).
- * @param {string} cachedUrl - The cached payment URL (optional).
+ * @param {string} locale - preferred locale
  * @returns {Promise<Object>} The deployment result with URLs.
  */
-export async function deploy(id, cachedUrl) {
-  const authToken = await getOfficialAccessToken(BASE_URL);
+export async function deploy(id, locale) {
+  const authToken = await getOfficialAccessToken(BASE_URL, true, locale);
 
   if (!authToken) {
     throw new Error("Could not get an official access token.");
@@ -30,7 +30,6 @@ export async function deploy(id, cachedUrl) {
 
   const result = await client.deploy({
     cachedCheckoutId: id,
-    cachedPaymentUrl: cachedUrl,
     needShortUrl: true,
     pageInfo: { successMessage: SUCCESS_MESSAGE },
     hooks: {
@@ -72,7 +71,7 @@ export async function deploy(id, cachedUrl) {
     },
   });
 
-  const { appUrl, homeUrl, subscriptionUrl, dashboardUrl, vendors, sessionId } = result;
+  const { appUrl, homeUrl, subscriptionUrl, dashboardUrl, vendors, sessionId, data } = result;
   const token = vendors?.[0]?.token;
 
   return {
@@ -82,5 +81,6 @@ export async function deploy(id, cachedUrl) {
     subscriptionUrl,
     token,
     sessionId,
+    data,
   };
 }

package/utils/request.mjs

@@ -1,4 +1,7 @@
 export async function requestWithAuthToken(url, options, authToken) {
+  if (!authToken) {
+    console.error("No authentication token provided");
+  }
   const response = await fetch(url, {
     ...options,
     headers: { ...options.headers, Authorization: `Bearer ${authToken}` },