@ffschrattenecker/tm1-mcp-server 6.0.0

package/dist/tm1-client/services/process-service.d.ts

@@ -0,0 +1,278 @@
+import type { CompileResult, DataSource, IgnoredColumn, Process, ProcessCheckInput, ProcessCode, ProcessParameter, ProcessResult, ProcessVariable } from "../../types.js";
+import type { RequestOptions, TM1HttpClient } from "../http.js";
+import { type NameFilterOpts, type Paged, type PageOpts } from "./odata-page.js";
+/** Variables of a process together with the datasource columns it ignores. */
+export interface ProcessVariableLayout {
+    variables: ProcessVariable[];
+    /** Columns set to "Ignore"; empty when the process has none. */
+    ignoredColumns: IgnoredColumn[];
+    /** Raw `VariablesUIData`, for callers that write it back unchanged. */
+    variablesUIData?: string[];
+}
+export interface ProcessListOpts extends NameFilterOpts {
+    /** Set to slice server-side. Only legal when every active filter is in NameFilterOpts. */
+    page?: PageOpts;
+}
+export declare class ProcessService {
+    private readonly http;
+    /**
+     * Index into `CALLGRAPH_QUERY_SHAPES` that this connection answered, or
+     * `null` while unprobed — the same tri-state verdict `BatchService.supported`
+     * keeps, for the same reason. Probing costs up to four full `/Processes`
+     * scans, so it must be paid once per connection and not once per callgraph
+     * build (P7).
+     */
+    private callgraphShape;
+    constructor(http: TM1HttpClient);
+    /**
+     * List all TI processes with their parameters. Falls back to
+     * Name-only when v11 rejects the inline Parameters select.
+     * GET /api/v1/Processes?$select=Name,Parameters
+     */
+    list(): Promise<Process[]>;
+    /**
+     * Paged variant: with `page` set the slice happens server-side
+     * (`$orderby=Name&$top&$skip&$count=true`) and the return carries the
+     * post-`$filter` total. `total` is undefined if the server omitted
+     * `@odata.count` — fall back to an unpaged fetch then.
+     */
+    list(opts: ProcessListOpts & {
+        page: PageOpts;
+    }): Promise<Paged<Process>>;
+    /**
+     * Execute a TI process with optional parameters. opts.timeoutMs overrides
+     * the 30s default for long-running TI runs.
+     * POST /api/v1/Processes('{name}')/tm1.ExecuteWithReturn?$expand=ErrorLogFile
+     */
+    execute(processName: string, params?: Record<string, string | number>, opts?: RequestOptions): Promise<ProcessResult>;
+    /**
+     * Persist in-memory cube data to disk — SaveDataAll (all cubes) or
+     * CubeSaveData (single cube). The REST API exposes no native SaveData
+     * action ($metadata verified), so this routes through the service-root
+     * ExecuteProcessWithReturn (available since 11.3) with an unbound TI
+     * process — no persistent process object is created. v11-only: both TI
+     * functions are removed in v12 (cloud engine persists automatically).
+     * POST /api/v1/ExecuteProcessWithReturn
+     */
+    saveData(cubeName?: string, opts?: RequestOptions): Promise<ProcessResult>;
+    /**
+     * Get the parameters of a TI process.
+     * GET /api/v1/Processes('{name}')/Parameters
+     */
+    getParameters(processName: string): Promise<ProcessParameter[]>;
+    /**
+     * Create a new empty TI process.
+     * POST /api/v1/Processes with body {"Name": "..."}
+     * Throws CONFLICT (409) if a process with the same name already exists.
+     */
+    create(name: string): Promise<void>;
+    /**
+     * Cheap existence probe: a single GET with $select=Name (404 → false)
+     * instead of list(), which pulls every process plus its parameters just to
+     * check one name. Rethrows anything that isn't NOT_FOUND.
+     */
+    exists(name: string): Promise<boolean>;
+    /**
+     * Copy a TI process to a new name. Strips read-only / server-managed fields
+     * before re-POSTing to avoid TM1 rejecting the body.
+     */
+    copy(sourceName: string, targetName: string): Promise<void>;
+    /**
+     * The two UI-only properties TM1 stores but does not declare: `UIData`
+     * (Architect cube/data action settings) and `VariablesUIData` (per-column
+     * state, including which columns are ignored). Both have to be named in
+     * `$select`; a server that rejects the query shape yields an empty result
+     * rather than an error, since neither is required to use the process.
+     */
+    getUIData(processName: string): Promise<{
+        uiData?: string;
+        variablesUIData?: string[];
+    }>;
+    /**
+     * Run the callgraph fetch against the query shape this connection accepts,
+     * discovering it on first use.
+     *
+     * The discovery loop used to catch EVERY error and move on to the next,
+     * broader query. That turned an expired session, a request timeout or a
+     * security denial into three more full-collection scans (~4 × 30 s worst
+     * case, P7) and — worse — let a later shape that happened to answer mask the
+     * real first error (K6/T-9). Two guards now bound it:
+     *
+     *   - `rethrowIfSystemicOrDenied` — transport/auth/timeout failures and
+     *     permission denials leave immediately. A denial in particular must never
+     *     become an empty process list: the callgraph would cache "this model has
+     *     no processes" as truth.
+     *   - `isUnsupportedQueryShape` — of what is left, only TM1 refusing the
+     *     query shape justifies asking again in another form.
+     */
+    private fetchCallgraphBody;
+    /**
+     * Fetch every TI process with code AND parameter metadata for callgraph
+     * indexing. Single round trip once the connection's usable OData query shape
+     * is known — see `fetchCallgraphBody` for the discovery rules.
+     */
+    fetchForCallgraph(includeControl?: boolean): Promise<Array<{
+        name: string;
+        prolog: string;
+        metadata: string;
+        data: string;
+        epilog: string;
+        parameters: string[];
+        parameterDefaults: Map<string, string>;
+    }>>;
+    /**
+     * Bulk-fetch code for every TI process in a single round trip.
+     * GET /api/v1/Processes?$select=Name,PrologProcedure,...
+     * Control processes (Name starts with `}`) excluded unless includeControl=true.
+     *
+     * With `top` set the cap is pushed server-side ($top + $orderby=Name for
+     * stable ordering + $count=true) and the return carries the server-side
+     * total matching the filter so callers can report truncation honestly.
+     */
+    getAllCode(includeControl?: boolean): Promise<Array<ProcessCode & {
+        name: string;
+        hasSecurityAccess: boolean;
+    }>>;
+    getAllCode(includeControl: boolean, top: number): Promise<{
+        items: Array<ProcessCode & {
+            name: string;
+            hasSecurityAccess: boolean;
+        }>;
+        /** Server-side total ($count=true); undefined when the server omitted @odata.count. */
+        total: number | undefined;
+    }>;
+    /**
+     * Get the code of all four tabs of a TI process.
+     * GET /api/v1/Processes('{name}')
+     */
+    getCode(processName: string): Promise<ProcessCode>;
+    /**
+     * Read deploy-relevant entity metadata not covered by getCode/params/
+     * vars/datasource. Currently only HasSecurityAccess (functional elevation).
+     * GET /api/v1/Processes('{name}')?$select=HasSecurityAccess
+     */
+    getDeployMeta(processName: string): Promise<{
+        hasSecurityAccess: boolean;
+    }>;
+    /**
+     * Update one or more code tabs of a TI process (partial update).
+     * PATCH /api/v1/Processes('{name}') with only the tabs to update.
+     */
+    updateCode(processName: string, code: Partial<ProcessCode>): Promise<void>;
+    /**
+     * Read the whole process code as TM1's native `#region <Tab>` / `#endregion`
+     * blob. GET /api/v1/Processes('{name}')/Code/$value (text/plain). Empty tabs
+     * are omitted by the server; newlines are CRLF.
+     */
+    getCodeBlob(processName: string): Promise<string>;
+    /**
+     * Write the whole process code from a native `#region` blob. PATCH
+     * /api/v1/Processes('{name}') { Code }. The server parses the region markers
+     * and does a FULL replace of all four tabs — tabs whose region is absent are
+     * cleared. `$value` PUT is not supported by TM1, so this JSON PATCH is the
+     * only write path.
+     */
+    updateCodeBlob(processName: string, blob: string): Promise<void>;
+    /**
+     * Set HasSecurityAccess flag on process.
+     * PATCH /api/v1/Processes('{name}') { HasSecurityAccess }.
+     */
+    updateSecurityAccess(processName: string, hasSecurityAccess: boolean): Promise<void>;
+    /**
+     * Get the data source configuration of a TI process.
+     * GET /api/v1/Processes('{name}') and extract the DataSource field.
+     */
+    /**
+     * Read a process datasource. The ODBC password is redacted by default so it
+     * cannot reach the caller or the model; `includeSecrets` returns it verbatim
+     * and is meant for export paths that write straight to a file.
+     *
+     * Measured on 11.8: the value on the wire is a server-bound ciphertext
+     * (`W0br…==`) that TM1 stores unchanged when written back, so it survives a
+     * round trip on the same instance but decrypts to nothing on another one.
+     * TM1 v12 returns the password in plain text.
+     */
+    getDataSource(processName: string, opts?: {
+        includeSecrets?: boolean;
+    }): Promise<DataSource>;
+    /**
+     * Bulk-fetch the datasource of every process in one OData call, projected to
+     * the few fields data-flow analysis needs (type + source object). Credentials
+     * are never selected. Used by tm1_trace_data_flow to detect view-sourced reads
+     * that leave no CellGet in the code and so never reach the reference index.
+     * GET /api/v1/Processes?$select=Name,DataSource
+     */
+    listDataSources(includeControl?: boolean): Promise<Array<{
+        name: string;
+        type: string;
+        sourceName?: string;
+        view?: string;
+        subset?: string;
+    }>>;
+    /**
+     * Update the data source configuration of a TI process.
+     * PATCH /api/v1/Processes('{name}') with DataSource object.
+     */
+    updateDataSource(processName: string, dataSource: DataSource): Promise<void>;
+    /**
+     * Get the variables (column-mapped names) of a TI process.
+     * GET /api/v1/Processes('{name}')/Variables
+     */
+    getVariables(processName: string): Promise<ProcessVariable[]>;
+    /**
+     * Variables PLUS the columns the process ignores, in one request.
+     *
+     * `Variables` alone is an incomplete picture of the datasource: a column set
+     * to "Ignore" carries no variable and is simply absent from the list, which
+     * is why the remaining positions have gaps. The ignore flag lives in
+     * `VariablesUIData` — one entry per source column, undeclared in $metadata on
+     * both versions, so it must be named in `$select`.
+     *
+     * GET /api/v1/Processes('{name}')?$select=Variables,VariablesUIData
+     */
+    getVariableLayout(processName: string): Promise<ProcessVariableLayout>;
+    /**
+     * Variables of every process, in ONE request.
+     *
+     * `Variables` is a complex-typed property, not a navigation collection, so
+     * the process list can carry it directly — no `$expand`, and no follow-up
+     * call per process. `getVariables` above answers the same question for a
+     * single process and stays the right tool when that is all you need.
+     *
+     * The difference is not cosmetic: asking per process costs one round trip
+     * each, which on a 221-process model measured as 221 extra requests against
+     * a single 147 KB one. Whole-model analyses (audit_complexity) use this.
+     *
+     * GET /api/v1/Processes?$select=Name,Variables
+     */
+    getAllVariables(includeControl?: boolean): Promise<Map<string, ProcessVariable[]>>;
+    /**
+     * Update the variables of a TI process (column-name mapping for ASCII/ODBC sources).
+     * Required after setting an ASCII DataSource.
+     * PATCH /api/v1/Processes('{name}') with Variables array.
+     */
+    updateVariables(processName: string, vars: ProcessVariable[], variablesUIData?: string[]): Promise<void>;
+    /**
+     * Update the parameters of a TI process.
+     * PATCH /api/v1/Processes('{name}') with Parameters array.
+     */
+    updateParameters(processName: string, params: ProcessParameter[]): Promise<void>;
+    /**
+     * Delete a TI process.
+     * DELETE /api/v1/Processes('{name}')
+     */
+    delete(processName: string): Promise<void>;
+    /**
+     * Compile a saved TI process to check syntax without executing it.
+     * POST /api/v1/Processes('{name}')/tm1.Compile
+     */
+    compile(processName: string): Promise<CompileResult>;
+    /**
+     * Validate a TI process WITHOUT saving it on the server. Mirrors tm1py's
+     * compile_process_with_body. Returns CompileResult identical to compile()
+     * for callers that already handle that shape.
+     * POST /api/v1/CompileProcess body { Process: <full process body> }
+     */
+    check(input: ProcessCheckInput): Promise<CompileResult>;
+}
+//# sourceMappingURL=process-service.d.ts.map