@viu/emporix-sdk 3.1.1 → 3.2.0

package/dist/index.d.cts

@@ -9374,6 +9374,287 @@ type HealthThresholds = {
      */
     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?: {
         /**
@@ -9436,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
@@ -9464,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"]>;
@@ -9527,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 {
@@ -9632,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 = {