@crowdin/app-project-module 2.1.0 → 2.2.0

package/out/index.d.ts

@@ -6,6 +6,7 @@ export { getRequestCredentialsMasker, postRequestCredentialsMasker, maskKey };
 export * from './types';
 export { Cron } from './util/cron';
 export { express };
+export { reportInsight as reportAdvisorInsight } from './modules/advisor-inspector/report-insight';
 export declare const metadataStore: CrowdinMetadataStore;
 export declare function createApp(clientConfig: ClientConfig): void;
 export declare function addCrowdinEndpoints(app: Express, clientConfig: Config | ClientConfig): CrowdinAppUtilities;

package/out/index.js

@@ -48,7 +48,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.metadataStore = exports.express = exports.maskKey = exports.postRequestCredentialsMasker = exports.getRequestCredentialsMasker = void 0;
+exports.metadataStore = exports.reportAdvisorInsight = exports.express = exports.maskKey = exports.postRequestCredentialsMasker = exports.getRequestCredentialsMasker = void 0;
 exports.createApp = createApp;
 exports.addCrowdinEndpoints = addCrowdinEndpoints;
 const logsFormatter = __importStar(require("@crowdin/logs-formatter"));
@@ -90,6 +90,7 @@ const spellCheckApp = __importStar(require("./modules/custom-spell-check"));
 const aiProvider = __importStar(require("./modules/ai-provider"));
 const aiPromptProvider = __importStar(require("./modules/ai-prompt-provider"));
 const editorRightPanelApp = __importStar(require("./modules/editor-right-panel"));
+const advisorInspector = __importStar(require("./modules/advisor-inspector"));
 const externalQaCheck = __importStar(require("./modules/external-qa-check"));
 const fileProcessingApps = __importStar(require("./modules/file-processing"));
 const integrationApp = __importStar(require("./modules/integration"));
@@ -110,6 +111,8 @@ const automationAction = __importStar(require("./modules/automation-action"));
 const authGuard = __importStar(require("./modules/auth-guard"));
 const subscription_1 = require("./util/subscription");
 __exportStar(require("./types"), exports);
+var report_insight_1 = require("./modules/advisor-inspector/report-insight");
+Object.defineProperty(exports, "reportAdvisorInsight", { enumerable: true, get: function () { return report_insight_1.reportInsight; } });
 exports.metadataStore = {
     getMetadata: (id) => {
         return storage.getStorage().getMetadata(id);
@@ -257,6 +260,7 @@ function addCrowdinEndpoints(app, clientConfig) {
     aiProvider.register({ config, app });
     aiPromptProvider.register({ config, app });
     externalQaCheck.register({ config, app });
+    advisorInspector.register({ config, app });
     webhooks.register({ config, app });
     workflowStepType.register({ config, app });
     aiRequestProcessors.register({ config, app });

package/out/modules/advisor-inspector/handlers/recheck.d.ts

@@ -0,0 +1,4 @@
+import { Response } from 'express';
+import { AdvisorInspectorModule } from '../types';
+import { CrowdinClientRequest } from '../../../types';
+export default function handle(inspector: AdvisorInspectorModule, moduleKey: string): (req: import("express").Request | CrowdinClientRequest, res: Response, next: Function) => void;

package/out/modules/advisor-inspector/handlers/recheck.js

@@ -0,0 +1,44 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = handle;
+const util_1 = require("../../../util");
+const logger_1 = require("../../../util/logger");
+function handle(inspector, moduleKey) {
+    return (0, util_1.runAsyncWrapper)((req, res) => __awaiter(this, void 0, void 0, function* () {
+        const body = req.body;
+        (0, logger_1.log)(`Received advisor-inspector recheck nudge: ${JSON.stringify(body)}`);
+        // Ack first — BE expects a fast 2xx; the callback runs after the response flushes.
+        res.send({ data: { accepted: true } });
+        // Capture context locals BEFORE scheduling — Express may recycle `req` post-response.
+        const projectId = body.projectId;
+        const inspectorId = body.inspectorKey;
+        const crowdinId = req.crowdinContext.crowdinId;
+        const context = req.crowdinContext;
+        const client = req.crowdinApiClient;
+        // queueMicrotask is universal (works on Node AND Cloudflare Workers; setImmediate is Node-only).
+        queueMicrotask(() => __awaiter(this, void 0, void 0, function* () {
+            try {
+                yield inspector.onRecheck({
+                    projectId,
+                    moduleKey,
+                    inspectorId,
+                    crowdinId,
+                    client,
+                    context,
+                });
+            }
+            catch (e) {
+                (0, logger_1.log)(`advisor-inspector onRecheck error: ${(0, logger_1.getErrorMessage)(e)}`);
+            }
+        }));
+    }));
+}

package/out/modules/advisor-inspector/index.d.ts

@@ -0,0 +1,6 @@
+import { Express } from 'express';
+import { Config } from '../../types';
+export declare function register({ config, app }: {
+    config: Config;
+    app: Express;
+}): void;

package/out/modules/advisor-inspector/index.js

@@ -0,0 +1,35 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const crowdin_client_1 = require("../../middlewares/crowdin-client");
+const json_response_1 = require("../../middlewares/json-response");
+const render_ui_module_1 = __importDefault(require("../../middlewares/render-ui-module"));
+const ui_module_1 = __importDefault(require("../../middlewares/ui-module"));
+const recheck_1 = __importDefault(require("./handlers/recheck"));
+const key_1 = require("./key");
+function register({ config, app }) {
+    if (!config.advisorInspector) {
+        return;
+    }
+    const items = config.advisorInspector;
+    const isSingle = items.length === 1;
+    for (const [index, inspector] of items.entries()) {
+        const key = (0, key_1.resolveAdvisorInspectorKey)(config, inspector, index, isSingle);
+        const base = `/advisor-inspector/${key}`;
+        // Recheck nudge endpoint (BE → app, fire-and-forget).
+        // checkSubscriptionExpiration=false: nudges are platform traffic; 402-ing here
+        // would mask the async flow. App-paid features should gate inside onRecheck.
+        app.post(`${base}/recheck`, json_response_1.handle, (0, crowdin_client_1.handle)({
+            config,
+            optional: false,
+            checkSubscriptionExpiration: false,
+            moduleKey: key,
+        }), (0, recheck_1.default)(inspector, key));
+        if (inspector.uiPath || inspector.formSchema) {
+            app.use(`${base}/iframe`, (0, ui_module_1.default)({ config, moduleType: key }), (0, render_ui_module_1.default)(Object.assign(Object.assign({}, inspector), { key }), config));
+        }
+    }
+}

package/out/modules/advisor-inspector/key.d.ts

@@ -0,0 +1,4 @@
+import { AdvisorInspectorModule } from './types';
+export declare function resolveAdvisorInspectorKey(config: {
+    identifier: string;
+}, item: AdvisorInspectorModule, index: number, isSingle: boolean): string;

package/out/modules/advisor-inspector/key.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveAdvisorInspectorKey = resolveAdvisorInspectorKey;
+const normalize_module_1 = require("../../util/normalize-module");
+function resolveAdvisorInspectorKey(config, item, index, isSingle) {
+    return (0, normalize_module_1.resolveInstanceKey)({
+        identifier: config.identifier,
+        suffix: 'advisor-inspector',
+        item,
+        index,
+        isSingle,
+    });
+}

package/out/modules/advisor-inspector/report-insight.d.ts

@@ -0,0 +1,3 @@
+import { Config } from '../../types';
+import { ReportInsightArgs } from './types';
+export declare function reportInsight(config: Config, args: ReportInsightArgs): Promise<void>;

package/out/modules/advisor-inspector/report-insight.js

@@ -0,0 +1,61 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reportInsight = reportInsight;
+const axios_1 = __importDefault(require("axios"));
+const storage_1 = require("../../storage");
+const connection_1 = require("../../util/connection");
+const logger_1 = require("../../util/logger");
+function buildBody(args) {
+    var _a, _b;
+    return Object.assign(Object.assign(Object.assign({ outcome: args.outcome }, (args.checkedAt !== undefined && { checkedAt: args.checkedAt })), { metrics: (_a = args.metrics) !== null && _a !== void 0 ? _a : [], recommendations: (_b = args.recommendations) !== null && _b !== void 0 ? _b : [] }), (args.payload !== undefined && { payload: args.payload }));
+}
+function put(url_1, body_1, token_1) {
+    return __awaiter(this, arguments, void 0, function* (url, body, token, timeoutMs = 300000) {
+        yield axios_1.default.put(url, body, {
+            headers: { Authorization: `Bearer ${token}` },
+            timeout: timeoutMs,
+        });
+    });
+}
+function isUnauthorized(e) {
+    const response = e === null || e === void 0 ? void 0 : e.response;
+    return !!response && response.status === 401;
+}
+function reportInsight(config, args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const credentials = yield (0, storage_1.getStorage)().getCrowdinCredentials(args.crowdinId);
+        if (!credentials) {
+            throw new Error(`reportInsight: no credentials for crowdinId=${args.crowdinId}`);
+        }
+        const body = buildBody(args);
+        const initial = yield (0, connection_1.prepareCrowdinClient)({ config, credentials, autoRenew: true });
+        let token = initial.token;
+        const url = `${initial.client.url}/projects/${args.projectId}` +
+            `/applications/${config.identifier}` +
+            `/modules/${args.moduleKey}/advisors/insights`;
+        try {
+            yield put(url, body, token, args.timeoutMs);
+        }
+        catch (e) {
+            if (isUnauthorized(e)) {
+                ({ token } = yield (0, connection_1.prepareCrowdinClient)({ config, credentials, autoRenew: true }));
+                yield put(url, body, token, args.timeoutMs);
+                return;
+            }
+            (0, logger_1.log)(`reportInsight PUT failed: ${(0, logger_1.getErrorMessage)(e)}`);
+            throw e;
+        }
+    });
+}

package/out/modules/advisor-inspector/types.d.ts

@@ -0,0 +1,59 @@
+import Crowdin from '@crowdin/crowdin-api-client';
+import { CrowdinContextInfo, Environments, ModuleKey, UiModule } from '../../types';
+export type AdvisorInspectorSeverity = 'high' | 'medium' | 'low';
+export type AdvisorInspectorRefreshPolicy = 'hourly' | 'daily';
+export type AdvisorInspectorCategory = 'context';
+export type AdvisorInspectorOutcome = 'flagged' | 'clear' | 'not_applicable';
+export interface AdvisorInspectorMetric {
+    key: string;
+    value: number;
+    unit?: 'percent' | 'count';
+    /** Comparison baseline shown in the UI */
+    threshold?: number;
+    tone?: 'default' | 'success' | 'danger';
+    checkedAt?: string;
+}
+export interface AdvisorInspectorRecommendation {
+    id: string;
+    primary?: boolean;
+    params?: Record<string, unknown>;
+}
+export interface AdvisorInspectorRecheckArgs {
+    projectId: number;
+    moduleKey: string;
+    /** prefixed, BE-supplied (e.g. 'app:my-app:daily-llm-check') */
+    inspectorId: string;
+    crowdinId: string;
+    client?: Crowdin;
+    context: CrowdinContextInfo;
+}
+export interface AdvisorInspectorRecheckRequest {
+    projectId: number;
+    inspectorKey: string;
+}
+export interface ReportInsightArgs {
+    crowdinId: string;
+    projectId: number;
+    moduleKey: string;
+    outcome: AdvisorInspectorOutcome;
+    metrics?: AdvisorInspectorMetric[];
+    recommendations?: AdvisorInspectorRecommendation[];
+    /**
+     * Free-form payload surfaced to the FE iframe via `formData`. BE requires an array
+     * (PHP-style — indexed or associative) and rejects raw scalars.
+     */
+    payload?: unknown[] | Record<string, unknown>;
+    /** RFC3339; BE defaults to now() and clamps if >1h future / >7d past */
+    checkedAt?: string;
+    /** PUT request timeout in ms; default 300_000 (5 minutes) */
+    timeoutMs?: number;
+}
+export interface AdvisorInspectorModule extends Environments, ModuleKey, UiModule {
+    title: string;
+    /** Optional summary line; ≤70 chars */
+    summary?: string;
+    severity: AdvisorInspectorSeverity;
+    category: AdvisorInspectorCategory;
+    refreshPolicy: AdvisorInspectorRefreshPolicy;
+    onRecheck: (args: AdvisorInspectorRecheckArgs) => Promise<void>;
+}

package/out/modules/advisor-inspector/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/out/modules/manifest.js

@@ -9,6 +9,7 @@ const api_1 = require("./api/api");
 const util_2 = require("./workflow-step-type/util");
 const index_1 = require("./automation-action/util/index");
 const ai_request_processors_1 = require("./ai-request-processors");
+const key_1 = require("./advisor-inspector/key");
 function normalizeEnvironments(environments) {
     if (Array.isArray(environments)) {
         return environments;
@@ -475,6 +476,20 @@ function handle(config) {
             return Object.assign(Object.assign({ key, name: item.name || config.name, description: item.description || config.description, runQaCheckUrl: `${base}/validate` }, (item.batchSize ? { getBatchSizeUrl: `${base}/batch-size` } : {})), (uiModule ? { url: `${base}/settings/` + (uiModule.fileName || 'index.html') } : {}));
         });
     }
+    if (config.advisorInspector) {
+        config.advisorInspector = config.advisorInspector.map((item) => (Object.assign({}, item)));
+        const items = config.advisorInspector;
+        const isSingle = items.length === 1;
+        modules['advisor-inspector'] = items.map((item, index) => {
+            const key = (0, key_1.resolveAdvisorInspectorKey)(config, item, index, isSingle);
+            item.key = key;
+            const base = `/advisor-inspector/${key}`;
+            const hasIframe = !!(item.uiPath || item.formSchema);
+            return Object.assign(Object.assign(Object.assign(Object.assign({ key, name: item.name || config.name, title: item.title }, (item.summary && { summary: item.summary })), { severity: item.severity, category: item.category, refreshPolicy: item.refreshPolicy, recheckUrl: `${base}/recheck` }), (hasIframe && {
+                url: `${base}/iframe/${item.fileName || 'index.html'}`,
+            })), (item.environments && { environments: normalizeEnvironments(item.environments) }));
+        });
+    }
     if (config.workflowStepType) {
         // prevent possible overrides of the other modules
         config.workflowStepType = config.workflowStepType.map((workflowStep) => (Object.assign({}, workflowStep)));

package/out/types.d.ts

@@ -17,6 +17,7 @@ import { Webhook } from './modules/webhooks/types';
 import { WorkflowStepTypeModule } from './modules/workflow-step-type/types';
 import { AiRequestProcessorModule, AiStreamProcessorModule } from './modules/ai-request-processors/types';
 import { AutomationActionModule } from './modules/automation-action/types';
+import { AdvisorInspectorModule } from './modules/advisor-inspector/types';
 import { AuthGuardModule } from './modules/auth-guard/types';
 import { Cron } from './util/cron';
 import { PostgreStorageConfig } from './storage/drizzle/postgresql';
@@ -276,6 +277,11 @@ export interface ClientConfig extends ImagePath {
      * qa check module
      */
     externalQaCheck?: (ExternalQaCheckModule & ImagePath)[];
+    /**
+     * Advisor inspector module — app-provided checks surfaced in the Crowdin Advisor.
+     * Receives recheck nudges from BE and pushes results via reportAdvisorInsight().
+     */
+    advisorInspector?: AdvisorInspectorModule[];
     /**
      * webhook modules
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crowdin/app-project-module",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Module that generates for you all common endpoints for serving standalone Crowdin App",
   "main": "out/index.js",
   "types": "out/index.d.ts",