@viu/emporix-sdk 3.1.0 → 3.2.0

package/dist/index.d.ts

@@ -3311,7 +3311,7 @@ type McpToolConfigResponse = {
  */
 type McpToolRequest = {
     /**
-     * Unique name of the tool. Must not contain whitespace characters.
+     * Unique name of the tool. Must contain only letters, numbers, and underscores.
      */
     name: string;
     /**
@@ -3335,7 +3335,7 @@ type McpToolRequest = {
  */
 type McpToolResponse = {
     /**
-     * Unique name of the tool.
+     * Unique name of the tool. Contains only letters, numbers, and underscores.
      */
     name?: string;
     /**
@@ -8932,13 +8932,22 @@ type ImportConfig$1 = {
      */
     sourceConnId?: string;
     /**
-     * Whether delta (incremental) runs are enabled.
+     * Whether AI-assisted mapping suggestions are enabled for the configuration.
      */
-    deltaEnabled?: boolean;
+    aiEnabled?: boolean;
     /**
      * Whether the configuration is active.
      */
     enabled?: boolean;
+    /**
+     * Incremented on every change to the configuration.
+     */
+    version?: number;
+    healthThresholds?: HealthThresholds;
+    /**
+     * The identifier of the user who created the configuration.
+     */
+    createdBy?: string;
     /**
      * When the configuration was created.
      */
@@ -8982,6 +8991,57 @@ type ImportStream$1 = {
      * How the stream contributes to the target.
      */
     mode?: 'STANDALONE' | 'COMPOSITE_CHILD' | 'COMPOSITE_MERGE';
+    /**
+     * The source field whose value is tracked as the delta watermark. A delta run extracts only the records whose value is newer than the last run's.
+     */
+    deltaField?: string;
+    /**
+     * How the delta field's values are formatted, so they can be compared correctly.
+     */
+    deltaFieldFormat?: 'DATE' | 'UNIX_SECONDS' | 'UNIX_MILLIS';
+    /**
+     * For a composite child stream, the name of the stream it contributes to.
+     */
+    compositeParent?: string;
+    /**
+     * For a composite child stream, the source field holding its parent's key.
+     */
+    linkingField?: string;
+    /**
+     * For a composite child stream, the parent attribute its records are embedded into.
+     */
+    embedAttribute?: string;
+    /**
+     * How a composite child's records reach the parent object.
+     */
+    childStrategy?: 'EMBED' | 'PATCH';
+    /**
+     * How an existing target object is updated. `PATCH` changes only the mapped fields and preserves everything else; `REPLACE_PUT` replaces the whole object, so fields this import does not manage are cleared.
+     */
+    writeStrategy?: 'PATCH' | 'MERGE_PUT' | 'REPLACE_PUT';
+    /**
+     * A source field whose value routes each record to a different target type, as defined by `discriminatorMap`.
+     */
+    discriminatorField?: string;
+    /**
+     * Maps a discriminator value to the target type that receives those records.
+     */
+    discriminatorMap?: {
+        [key: string]: string;
+    };
+    /**
+     * Whether the stream reacts to its target objects being deleted outside the import.
+     */
+    targetDeleteSubscriptionEnabled?: boolean;
+    /**
+     * What happens when a record deleted in the target is seen in the source again.
+     */
+    onTargetReappear?: 'IGNORE' | 'READD';
+    healthThresholds?: HealthThresholds;
+    /**
+     * When the stream was created.
+     */
+    createdAt?: string;
     /**
      * Whether the stream is active.
      */
@@ -9084,6 +9144,26 @@ type ImportRun$1 = {
      * A terminal status message, typically set on failure.
      */
     message?: string;
+    /**
+     * When the run retries another run's failed records, the identifier of that original run.
+     */
+    retryOfRunId?: string;
+    /**
+     * Whether the run rewrote every record, bypassing the skip-if-unchanged check.
+     */
+    force?: boolean;
+    /**
+     * Whether the run only extracted, mapped, and validated, writing nothing to the target. A dry run legitimately reports zero for every counter, so this distinguishes it from a run that wrote nothing because it failed.
+     */
+    dryRun?: boolean;
+    /**
+     * Whether cancellation has been requested for a run that is still finishing.
+     */
+    cancelRequested?: boolean;
+    /**
+     * For a dry run, how many mapped records were kept as a sample.
+     */
+    dryRunSampleSize?: number;
 };
 /**
  * Run stream progress
@@ -9267,10 +9347,318 @@ type ImportedRecord$1 = {
      */
     importedAt?: string;
 };
+/**
+ * Health thresholds
+ *
+ * The limits that decide whether a stream is reported as `GREEN`, `AMBER`, or `RED`. Each field is optional and resolves independently. An unset field falls back through the hierarchy, from the most specific level to the least specific: stream, configuration, tenant, then the built-in default.
+ */
+type HealthThresholds = {
+    /**
+     * The share of failed records (0..1) at or above which the stream is `AMBER`.
+     */
+    failureRatioAmber?: number;
+    /**
+     * The share of failed records (0..1) at or above which the stream is `RED`.
+     */
+    failureRatioRed?: number;
+    /**
+     * The age threshold, in hours, for the stream's newest data. The stream is `AMBER` when the data's age reaches or exceeds this threshold.
+     */
+    staleAmberHours?: number;
+    /**
+     * The age threshold, in hours, for the stream's newest data. The stream is `RED` when the data's age reaches or exceeds this threshold.
+     */
+    staleRedHours?: number;
+    /**
+     * Whether a failed most-recent run makes the stream `RED` regardless of the other limits.
+     */
+    failedRunIsRed?: boolean;
+};
+/**
+ * Tenant health thresholds
+ *
+ * The tenant-wide thresholds, together with the built-in defaults they fall back to.
+ */
+type HealthSettings = {
+    thresholds?: HealthThresholds;
+    builtInDefaults?: HealthThresholds;
+};
+/**
+ * Job group
+ *
+ * A named set of import configurations, used to scope the import statistics.
+ */
+type JobGroup = {
+    /**
+     * The job group identifier.
+     */
+    id?: string;
+    /**
+     * The job group name. Unique within the tenant.
+     */
+    name?: string;
+    /**
+     * The configurations in the group.
+     */
+    configIds?: Array<string>;
+    /**
+     * When the group was created.
+     */
+    createdAt?: string;
+    /**
+     * When the group was last changed.
+     */
+    updatedAt?: string;
+};
+/**
+ * Import limits
+ *
+ * The import limits that apply to the tenant.
+ */
+type ImportLicense$1 = {
+    /**
+     * The maximum number of records a single run may write per target type. Records beyond the limit are skipped and the run finishes as `PARTIAL`.
+     */
+    maxRecordsPerEntity?: number;
+    /**
+     * The maximum number of runs that may be active at once for the tenant. A run requested beyond this limit is rejected with `429`.
+     */
+    maxConcurrentImports?: number;
+    /**
+     * The number of records written to the target per request.
+     */
+    batchSize?: number;
+    /**
+     * The number of target writes performed in parallel.
+     */
+    workers?: number;
+};
+/**
+ * Statistics summary
+ *
+ * Headline totals for the window. Rates are fractions between 0 and 1.
+ */
+type ImportStatsSummary = {
+    /**
+     * The number of runs started in the window.
+     */
+    totalRuns?: number;
+    /**
+     * The number of runs that finished successfully.
+     */
+    succeeded?: number;
+    /**
+     * The number of runs that finished with some records failing.
+     */
+    partial?: number;
+    /**
+     * The number of runs that failed.
+     */
+    failed?: number;
+    /**
+     * The number of runs that were cancelled.
+     */
+    cancelled?: number;
+    /**
+     * The number of source records read.
+     */
+    recordsRead?: number;
+    /**
+     * The number of target objects created.
+     */
+    created?: number;
+    /**
+     * The number of target objects updated.
+     */
+    updated?: number;
+    /**
+     * The number of records skipped because nothing had changed.
+     */
+    skipped?: number;
+    /**
+     * The number of target objects deleted.
+     */
+    deleted?: number;
+    /**
+     * The number of records that could not be imported.
+     */
+    failedRecords?: number;
+    /**
+     * The share of runs that finished successfully.
+     */
+    successRate?: number;
+    /**
+     * The share of records that failed.
+     */
+    failureRate?: number;
+    /**
+     * The share of processed records that resulted in a deletion.
+     */
+    deletionRate?: number;
+    /**
+     * The share of records skipped as unchanged.
+     */
+    skipRate?: number;
+    /**
+     * The mean duration of a finished run, in seconds.
+     */
+    avgRunDurationSec?: number;
+    /**
+     * The mean number of objects created per run.
+     */
+    avgCreatedPerRun?: number;
+    /**
+     * The mean number of objects updated per run.
+     */
+    avgUpdatedPerRun?: number;
+    /**
+     * The number of distinct target objects currently held by the imports in scope.
+     */
+    distinctEntities?: number;
+    /**
+     * The number of runs currently in progress.
+     */
+    activeRuns?: number;
+};
+/**
+ * Statistics time bucket
+ *
+ * One bucket of the time series, in UTC.
+ */
+type ImportStatsPoint = {
+    /**
+     * The start of the bucket.
+     */
+    bucket?: string;
+    runs?: number;
+    succeeded?: number;
+    failed?: number;
+    recordsRead?: number;
+    created?: number;
+    updated?: number;
+    deleted?: number;
+    skipped?: number;
+    failedRecords?: number;
+};
+/**
+ * Stream health
+ *
+ * The health of one stream over the window, and the thresholds the verdict used.
+ */
+type ImportStreamHealth = {
+    streamId?: string;
+    /**
+     * The configuration the stream belongs to.
+     */
+    configId?: string;
+    name?: string;
+    /**
+     * The target type the stream writes to.
+     */
+    targetType?: string;
+    /**
+     * The status of the stream's most recent run.
+     */
+    lastRunStatus?: string;
+    lastRunAt?: string;
+    /**
+     * The number of seconds since the stream last detected new data.
+     */
+    watermarkAgeSeconds?: number;
+    /**
+     * The share of the stream's records that failed in the window.
+     */
+    failureRatio?: number;
+    /**
+     * The stream's health verdict.
+     */
+    health?: 'GREEN' | 'AMBER' | 'RED';
+    thresholds?: ImportEffectiveThresholds;
+};
+/**
+ * Effective thresholds
+ *
+ * The threshold values the verdict was actually computed with, after resolving every level.
+ */
+type ImportEffectiveThresholds = {
+    failureRatioAmber?: number;
+    failureRatioRed?: number;
+    staleAmberHours?: number;
+    staleRedHours?: number;
+    failedRunIsRed?: boolean;
+    /**
+     * Whether any level overrides the built-in defaults.
+     */
+    customised?: boolean;
+};
+/**
+ * Named count
+ */
+type ImportStatsNamedCount = {
+    streamId?: string;
+    name?: string;
+    count?: number;
+};
+/**
+ * Error bucket
+ *
+ * A count of errors sharing the same stage and code.
+ */
+type ImportStatsErrorBucket = {
+    /**
+     * The pipeline stage the error occurred in.
+     */
+    stage?: string;
+    errorCode?: string;
+    count?: number;
+};
+/**
+ * Stream changes
+ *
+ * The counts of streams added and removed during the time window.
+ */
+type ImportStreamChanges = {
+    added?: number;
+    removed?: number;
+    /**
+     * When stream tracking began for the tenant. Streams created before this point are not counted, so a window reaching further back is not comparable.
+     */
+    trackingSince?: string;
+    series?: Array<{
+        bucket?: string;
+        added?: number;
+        removed?: number;
+    }>;
+};
+/**
+ * Import statistics
+ *
+ * Aggregated import metrics for the requested window and scope. A section that was not requested via the `sections` parameter is returned as `null`.
+ */
+type ImportStats$1 = {
+    summary?: ImportStatsSummary;
+    /**
+     * Activity per time bucket, ordered oldest first and gap-free.
+     */
+    series?: Array<ImportStatsPoint>;
+    /**
+     * The health of each stream in scope.
+     */
+    streamHealth?: Array<ImportStreamHealth>;
+    /**
+     * The streams with the most errors during the time window, ordered by error count in descending order.
+     */
+    topFailingStreams?: Array<ImportStatsNamedCount>;
+    /**
+     * The most common errors in the window, grouped by stage and code.
+     */
+    errorBreakdown?: Array<ImportStatsErrorBucket>;
+    streamChanges?: ImportStreamChanges;
+};
 type PostImporttoolTriggerRunData = {
     body?: {
         /**
-         * The run mode. Defaults to `DELTA`.
+         * The run mode. When omitted, defaults to `DELTA`.
          */
         mode?: 'FULL' | 'DELTA';
         /**
@@ -9329,6 +9717,47 @@ type GetImporttoolSearchDataRecordsData = {
     };
     url: '/importtool/{tenant}/data/records';
 };
+type GetImporttoolStatsData = {
+    body?: never;
+    path: {
+        /**
+         * The tenant you want to access.
+         *
+         */
+        tenant: string;
+    };
+    query?: {
+        /**
+         * Restricts the statistics to a single configuration.
+         */
+        configId?: string;
+        /**
+         * Restricts the statistics to several configurations, as a comma-separated list of identifiers. Ignored when `configId` is given.
+         */
+        configIds?: string;
+        /**
+         * Restricts the statistics to a single stream. Takes precedence over the configuration filters.
+         */
+        streamId?: string;
+        /**
+         * The start of the window, as an ISO-8601 instant. When omitted, defaults to 30 days ago.
+         */
+        from?: string;
+        /**
+         * The end of the window, as an ISO-8601 instant. Exclusive. When omitted, defaults to now.
+         */
+        to?: string;
+        /**
+         * The bucket size of the returned time series.
+         */
+        granularity?: 'DAY' | 'WEEK' | 'MONTH';
+        /**
+         * A comma-separated list of the sections to compute: `TOTALS`, `STREAMS`, `ERRORS`, `CHANGES`. When omitted, defaults to all sections. A section not requested through the `sections` parameter is returned as `null`.
+         */
+        sections?: string;
+    };
+    url: '/importtool/{tenant}/stats';
+};
 
 /**
  * Public types for the Import Service — stable names aliased over the
@@ -9357,7 +9786,11 @@ type ImportCancelResult = CancelResult;
 type ImportErrorRecord = ErrorRecord;
 /** A record that was imported, with its keys, stored fields and last outcome. */
 type ImportedRecord = ImportedRecord$1;
-/** Body for `triggerRun`: `{ mode?, dryRun? }`. `mode` defaults to `DELTA` server-side. */
+/**
+ * Body for `triggerRun`: `{ mode?, dryRun?, force? }`. `mode` defaults to
+ * `DELTA` server-side; `force` rewrites every extracted record, bypassing the
+ * skip-if-unchanged idempotency.
+ */
 type ImportRunInput = NonNullable<PostImporttoolTriggerRunData["body"]>;
 /** Lifecycle status of an {@link ImportRun}. */
 type ImportRunStatus = NonNullable<ImportRun["status"]>;
@@ -9420,6 +9853,23 @@ type ImportPage<T> = PaginatedItems<T> & {
     /** Total number of pages. */
     totalPages: number;
 };
+/**
+ * Aggregated import analytics: totals, a time series, an error breakdown and
+ * per-stream health. Every section is optional — the `sections` filter decides
+ * which ones the service computes.
+ */
+type ImportStats = ImportStats$1;
+/** Query for {@link ImportsService.stats}. All filters optional. */
+type ImportStatsQuery = Omit<NonNullable<GetImporttoolStatsData["query"]>, never>;
+/** One dashboard job group: a configuration and the runs grouped under it. */
+type ImportJobGroup = JobGroup;
+/**
+ * The tenant's health thresholds — the error rates above which a stream counts
+ * as degraded or failing in {@link ImportStats}.
+ */
+type ImportHealthThresholds = HealthSettings;
+/** The tenant's import limits and current consumption. */
+type ImportLicense = ImportLicense$1;
 
 /** One-based paging options, shared by every paginated import endpoint. */
 interface ImportPageOptions {
@@ -9525,6 +9975,59 @@ declare class ImportService {
     searchRecords(opts: SearchImportedRecordsOptions, auth?: AuthContext): Promise<ImportPage<ImportedRecord>>;
     /** Search the imported records produced by one stream. */
     searchStreamRecords(streamId: string, opts?: SearchStreamRecordsOptions, auth?: AuthContext): Promise<ImportPage<ImportedRecord>>;
+    /**
+     * Aggregated import analytics.
+     *
+     * Every section is optional in the response, and `sections` is what decides
+     * which the service computes — asking for all of them on a tenant with a long
+     * history is the expensive call, so name the ones you render.
+     *
+     * `from` / `to` are ISO timestamps. Omitted, the service picks its own window;
+     * do not assume it is «everything».
+     *
+     * **Preview upstream**: the contract may change without a major bump.
+     */
+    stats(query?: ImportStatsQuery, auth?: AuthContext): Promise<ImportStats>;
+    /**
+     * The dashboard's job groups: configurations with their runs grouped under
+     * them.
+     *
+     * Named after the path rather than the summary («Retrieving job groups»)
+     * because the resource lives under `/dashboard` and is shaped for that view —
+     * a caller wanting plain run history wants {@link listRuns}.
+     *
+     * **Preview upstream**: the contract may change without a major bump.
+     */
+    listJobGroups(auth?: AuthContext): Promise<ImportJobGroup[]>;
+    /**
+     * The tenant's health thresholds — the error rates above which a stream counts
+     * as degraded or failing in {@link stats}.
+     *
+     * Read-only here: changing them needs `importtool.import_manage`, which this
+     * service does not cover.
+     *
+     * **Preview upstream**: the contract may change without a major bump.
+     */
+    getHealthThresholds(auth?: AuthContext): Promise<ImportHealthThresholds>;
+    /**
+     * The tenant's import limits and current consumption.
+     *
+     * **Preview upstream**: the contract may change without a major bump.
+     */
+    getLicense(auth?: AuthContext): Promise<ImportLicense>;
+    /**
+     * Retry only the failed records of a finished run.
+     *
+     * Returns a **new** run — the retry is its own run with `retry: true`, not a
+     * mutation of the original. Poll it with {@link getRun} or follow it with
+     * {@link streamRun} exactly as you would a triggered run.
+     *
+     * Not retried on a 5xx, for the same reason {@link triggerRun} is not: a POST
+     * that timed out may already have queued the retry.
+     *
+     * **Preview upstream**: the contract may change without a major bump.
+     */
+    retryRun(runId: string, auth?: AuthContext): Promise<ImportRun>;
 }
 
 type BaseUnit = {

package/dist/index.js

@@ -945,7 +945,7 @@ var HttpClient = class {
 };
 
 // package.json
-var version = "3.1.0";
+var version = "3.2.0";
 
 // src/version.ts
 var SDK_VERSION = version;
@@ -4464,6 +4464,91 @@ var ImportService = class {
     });
     return toPage(wire, args);
   }
+  // ─── Analytics and retry (upstream release 2026-08-26) ─────────────────────
+  /**
+   * Aggregated import analytics.
+   *
+   * Every section is optional in the response, and `sections` is what decides
+   * which the service computes — asking for all of them on a tenant with a long
+   * history is the expensive call, so name the ones you render.
+   *
+   * `from` / `to` are ISO timestamps. Omitted, the service picks its own window;
+   * do not assume it is «everything».
+   *
+   * **Preview upstream**: the contract may change without a major bump.
+   */
+  async stats(query = {}, auth2 = SERVICE22) {
+    return this.ctx.http.request({
+      method: "GET",
+      path: `${this.base()}/stats`,
+      query: { ...query },
+      auth: auth2
+    });
+  }
+  /**
+   * The dashboard's job groups: configurations with their runs grouped under
+   * them.
+   *
+   * Named after the path rather than the summary («Retrieving job groups»)
+   * because the resource lives under `/dashboard` and is shaped for that view —
+   * a caller wanting plain run history wants {@link listRuns}.
+   *
+   * **Preview upstream**: the contract may change without a major bump.
+   */
+  async listJobGroups(auth2 = SERVICE22) {
+    return this.ctx.http.request({
+      method: "GET",
+      path: `${this.base()}/dashboard/job-groups`,
+      auth: auth2
+    });
+  }
+  /**
+   * The tenant's health thresholds — the error rates above which a stream counts
+   * as degraded or failing in {@link stats}.
+   *
+   * Read-only here: changing them needs `importtool.import_manage`, which this
+   * service does not cover.
+   *
+   * **Preview upstream**: the contract may change without a major bump.
+   */
+  async getHealthThresholds(auth2 = SERVICE22) {
+    return this.ctx.http.request({
+      method: "GET",
+      path: `${this.base()}/settings/health-thresholds`,
+      auth: auth2
+    });
+  }
+  /**
+   * The tenant's import limits and current consumption.
+   *
+   * **Preview upstream**: the contract may change without a major bump.
+   */
+  async getLicense(auth2 = SERVICE22) {
+    return this.ctx.http.request({
+      method: "GET",
+      path: `${this.base()}/license`,
+      auth: auth2
+    });
+  }
+  /**
+   * Retry only the failed records of a finished run.
+   *
+   * Returns a **new** run — the retry is its own run with `retry: true`, not a
+   * mutation of the original. Poll it with {@link getRun} or follow it with
+   * {@link streamRun} exactly as you would a triggered run.
+   *
+   * Not retried on a 5xx, for the same reason {@link triggerRun} is not: a POST
+   * that timed out may already have queued the retry.
+   *
+   * **Preview upstream**: the contract may change without a major bump.
+   */
+  async retryRun(runId, auth2 = SERVICE22) {
+    return this.ctx.http.request({
+      method: "POST",
+      path: `${this.base()}/runs/${encodeURIComponent(runId)}/retry`,
+      auth: auth2
+    });
+  }
 };
 
 // src/services/unit-handling.ts