@viu/emporix-sdk 3.3.1 → 3.4.1

package/dist/index.d.cts

@@ -2124,7 +2124,7 @@ type IdResponse$1 = {
 /**
  * Type which the schema should be assigned to. Can be one of the predefined values or any custom schema type id.
  */
-type SchemaType = 'AVAILABILITY' | 'CART' | 'CART_ITEM' | 'CATEGORY' | 'COMPANY' | 'COUPON' | 'CUSTOMER' | 'CUSTOMER_ADDRESS' | 'LOCATION' | 'ORDER' | 'ORDER_ENTRY' | 'PRODUCT' | 'QUOTE' | 'RETURN' | 'PRICE_LIST' | 'SITE' | 'CUSTOM_ENTITY' | 'VENDOR' | 'MEDIA';
+type SchemaType = 'AVAILABILITY' | 'CART' | 'CART_ITEM' | 'CATEGORY' | 'COMPANY' | 'COUPON' | 'CUSTOMER' | 'CUSTOMER_ADDRESS' | 'LOCATION' | 'ORDER' | 'ORDER_ENTRY' | 'PRODUCT' | 'QUOTE' | 'RETURN' | 'PRICE_LIST' | 'SITE' | 'CUSTOM_ENTITY' | 'VENDOR' | 'VENDOR_LOCATION' | 'MEDIA';
 /**
  * Type of the attribute.
  *
@@ -9116,6 +9116,33 @@ type ImportRun$1 = {
      * What triggered the run.
      */
     trigger?: 'MANUAL' | 'SCHEDULED';
+    /**
+     * Dry-run only. A sample of the mapped records that would be written, so the mapping can be previewed without a real import. Absent on normal runs.
+     */
+    dryRunSample?: Array<{
+        /**
+         * The stream that produced the sample record.
+         */
+        stream?: string;
+        /**
+         * The resolved target type the record would be written to.
+         */
+        targetType?: string;
+        /**
+         * The record's natural/deterministic key.
+         */
+        key?: string;
+        /**
+         * The mapped target fields that would be written.
+         */
+        fields?: {
+            [key: string]: unknown;
+        };
+    }>;
+    /**
+     * What requested the run. The `origin` value from the trigger request, or the `trigger` value when `origin` was omitted. Use this field to distinguish a dashboard run from a run started by an integration scenario. The field is absent on runs recorded before it existed.
+     */
+    origin?: string;
     /**
      * The run status.
      */
@@ -9727,6 +9754,14 @@ type PostImporttoolTriggerRunData = {
          * When `true`, every extracted record is rewritten, even if unchanged. It bypasses the idempotency `skip-if-unchanged` check. Use it to force target IDs and values to be rewritten.
          */
         force?: boolean;
+        /**
+         * Dry-run only. How many mapped records to sample per stream for the preview returned as `dryRunSample`. Clamped to 1-100; defaults to 25.
+         */
+        sampleSize?: number;
+        /**
+         * What requested this run. Examples: `Dashboard`, an integration scenario name, or a scheduler name. The `trigger` field records only `MANUAL` or `SCHEDULED`. Use `origin` when more than one system calls this endpoint. If you omit `origin` or send a blank value, the service stores the `trigger` value. The service rejects values longer than 40 characters and values that contain control characters. It does not shorten them.
+         */
+        origin?: string;
     };
     path: {
         /**
@@ -9832,7 +9867,19 @@ type ImportConfig = ImportConfig$1;
 type ImportStream = ImportStream$1;
 /** A cron schedule for a configuration. `cron` is a six-field Spring expression. */
 type ImportSchedule = Schedule;
-/** An import run with its reconciled counters. */
+/**
+ * An import run with its reconciled counters.
+ *
+ * Two counters describe the **source feed** rather than the import: a run can
+ * report `SUCCEEDED` while `duplicateKeys` (source rows repeating a key already
+ * imported in the run — only the last survives) and `unresolvedParents` (child
+ * records whose parent was not found, distinct from `skipped`, which means
+ * already up to date) hide real data loss from the pass/fail counters.
+ *
+ * `dryRunSample` carries the previewed records on a dry run and is absent on a
+ * normal one. `origin` echoes what asked for the run, and is absent on runs
+ * recorded before that field existed.
+ */
 type ImportRun = ImportRun$1;
 /** Per-stream progress within a run. */
 type ImportRunStream = ImportRunStream$1;
@@ -9845,9 +9892,19 @@ 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?, force? }`. `mode` defaults to
- * `DELTA` server-side; `force` rewrites every extracted record, bypassing the
- * skip-if-unchanged idempotency.
+ * Body for `triggerRun`: `{ mode?, dryRun?, force?, sampleSize?, origin? }`.
+ *
+ * - `mode` defaults to `DELTA` server-side.
+ * - `force` rewrites every extracted record, bypassing the skip-if-unchanged
+ *   idempotency.
+ * - `sampleSize` is **dry-run only**: how many mapped records to sample per
+ *   stream into the run's `dryRunSample`. Clamped to 1–100, defaults to 25.
+ * - `origin` is free text naming *what* asked for the run (`"Dashboard"`, an
+ *   integration scenario, your own scheduler), as opposed to `trigger`, which
+ *   only ever records `MANUAL` or `SCHEDULED`. Omitted or blank, the service
+ *   stores the `trigger` value instead. **Over 40 characters or containing
+ *   control characters is rejected, not shortened** — a truncated label in an
+ *   audit trail is worse than a refused request.
  */
 type ImportRunInput = NonNullable<PostImporttoolTriggerRunData["body"]>;
 /** Lifecycle status of an {@link ImportRun}. */
@@ -9988,13 +10045,58 @@ declare class ImportService {
      * a normal result rather than an error.
      */
     getSchedule(configId: string, auth?: AuthContext): Promise<ImportSchedule | null>;
-    /** Create or replace a configuration's schedule. */
+    /**
+     * Create or replace a configuration's schedule.
+     *
+     * **`cron` is a six-field Spring expression** (`second minute hour
+     * day-of-month month day-of-week`). The familiar five-field `"0 * * * *"` is
+     * not «hourly» here, it is invalid, and the service answers `400` rather than
+     * storing it — which it used to do, leaving a schedule that silently never
+     * fired.
+     *
+     * A `404` means no configuration with that id, so there is nothing to
+     * schedule. Use {@link deleteSchedule} to clear a schedule that outlived its
+     * configuration.
+     */
     setSchedule(configId: string, input: ImportSchedule, auth?: AuthContext): Promise<ImportSchedule>;
+    /**
+     * Remove a configuration's schedule. It then runs only when triggered.
+     *
+     * **Idempotent, and deliberately not gated on the configuration existing.**
+     * Removing a schedule that is not there also resolves — and unlike
+     * {@link setSchedule}, this does not require the configuration to exist. That
+     * is the point: a schedule left behind by a deleted configuration is exactly
+     * what needs removing, so refusing those would leave them with no way out.
+     *
+     * The service answers `204`, so this resolves to `void` rather than to the
+     * removed schedule.
+     */
+    deleteSchedule(configId: string, auth?: AuthContext): Promise<void>;
     /**
      * Trigger a run. `mode` defaults to `DELTA` server-side; `dryRun: true` maps
      * and validates without writing to the target.
      *
+     * A dry run can also hand back what it *would* have written: pass
+     * `sampleSize` (1–100, default 25) and read the run's `dryRunSample`. Set
+     * `origin` to name what asked for the run — `trigger` only distinguishes
+     * `MANUAL` from `SCHEDULED`, so without it a dashboard click and an
+     * integration scenario are indistinguishable in the history. Note the service
+     * **rejects** an `origin` over 40 characters instead of shortening it.
+     *
      * Not retried on a 5xx: a POST that timed out may already have queued a run.
+     *
+     * @example
+     * ```ts
+     * // Preview the mapping without writing anything.
+     * const run = await client.imports.triggerRun(configId, {
+     *   dryRun: true,
+     *   sampleSize: 5,
+     *   origin: "Dashboard",
+     * });
+     * for (const row of run.dryRunSample ?? []) {
+     *   console.log(row.stream, row.targetType, row.key, row.fields);
+     * }
+     * ```
      */
     triggerRun(configId: string, input?: ImportRunInput, auth?: AuthContext): Promise<ImportRun>;
     /** List a configuration's runs, newest first. */

package/dist/index.d.ts

@@ -2124,7 +2124,7 @@ type IdResponse$1 = {
 /**
  * Type which the schema should be assigned to. Can be one of the predefined values or any custom schema type id.
  */
-type SchemaType = 'AVAILABILITY' | 'CART' | 'CART_ITEM' | 'CATEGORY' | 'COMPANY' | 'COUPON' | 'CUSTOMER' | 'CUSTOMER_ADDRESS' | 'LOCATION' | 'ORDER' | 'ORDER_ENTRY' | 'PRODUCT' | 'QUOTE' | 'RETURN' | 'PRICE_LIST' | 'SITE' | 'CUSTOM_ENTITY' | 'VENDOR' | 'MEDIA';
+type SchemaType = 'AVAILABILITY' | 'CART' | 'CART_ITEM' | 'CATEGORY' | 'COMPANY' | 'COUPON' | 'CUSTOMER' | 'CUSTOMER_ADDRESS' | 'LOCATION' | 'ORDER' | 'ORDER_ENTRY' | 'PRODUCT' | 'QUOTE' | 'RETURN' | 'PRICE_LIST' | 'SITE' | 'CUSTOM_ENTITY' | 'VENDOR' | 'VENDOR_LOCATION' | 'MEDIA';
 /**
  * Type of the attribute.
  *
@@ -9116,6 +9116,33 @@ type ImportRun$1 = {
      * What triggered the run.
      */
     trigger?: 'MANUAL' | 'SCHEDULED';
+    /**
+     * Dry-run only. A sample of the mapped records that would be written, so the mapping can be previewed without a real import. Absent on normal runs.
+     */
+    dryRunSample?: Array<{
+        /**
+         * The stream that produced the sample record.
+         */
+        stream?: string;
+        /**
+         * The resolved target type the record would be written to.
+         */
+        targetType?: string;
+        /**
+         * The record's natural/deterministic key.
+         */
+        key?: string;
+        /**
+         * The mapped target fields that would be written.
+         */
+        fields?: {
+            [key: string]: unknown;
+        };
+    }>;
+    /**
+     * What requested the run. The `origin` value from the trigger request, or the `trigger` value when `origin` was omitted. Use this field to distinguish a dashboard run from a run started by an integration scenario. The field is absent on runs recorded before it existed.
+     */
+    origin?: string;
     /**
      * The run status.
      */
@@ -9727,6 +9754,14 @@ type PostImporttoolTriggerRunData = {
          * When `true`, every extracted record is rewritten, even if unchanged. It bypasses the idempotency `skip-if-unchanged` check. Use it to force target IDs and values to be rewritten.
          */
         force?: boolean;
+        /**
+         * Dry-run only. How many mapped records to sample per stream for the preview returned as `dryRunSample`. Clamped to 1-100; defaults to 25.
+         */
+        sampleSize?: number;
+        /**
+         * What requested this run. Examples: `Dashboard`, an integration scenario name, or a scheduler name. The `trigger` field records only `MANUAL` or `SCHEDULED`. Use `origin` when more than one system calls this endpoint. If you omit `origin` or send a blank value, the service stores the `trigger` value. The service rejects values longer than 40 characters and values that contain control characters. It does not shorten them.
+         */
+        origin?: string;
     };
     path: {
         /**
@@ -9832,7 +9867,19 @@ type ImportConfig = ImportConfig$1;
 type ImportStream = ImportStream$1;
 /** A cron schedule for a configuration. `cron` is a six-field Spring expression. */
 type ImportSchedule = Schedule;
-/** An import run with its reconciled counters. */
+/**
+ * An import run with its reconciled counters.
+ *
+ * Two counters describe the **source feed** rather than the import: a run can
+ * report `SUCCEEDED` while `duplicateKeys` (source rows repeating a key already
+ * imported in the run — only the last survives) and `unresolvedParents` (child
+ * records whose parent was not found, distinct from `skipped`, which means
+ * already up to date) hide real data loss from the pass/fail counters.
+ *
+ * `dryRunSample` carries the previewed records on a dry run and is absent on a
+ * normal one. `origin` echoes what asked for the run, and is absent on runs
+ * recorded before that field existed.
+ */
 type ImportRun = ImportRun$1;
 /** Per-stream progress within a run. */
 type ImportRunStream = ImportRunStream$1;
@@ -9845,9 +9892,19 @@ 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?, force? }`. `mode` defaults to
- * `DELTA` server-side; `force` rewrites every extracted record, bypassing the
- * skip-if-unchanged idempotency.
+ * Body for `triggerRun`: `{ mode?, dryRun?, force?, sampleSize?, origin? }`.
+ *
+ * - `mode` defaults to `DELTA` server-side.
+ * - `force` rewrites every extracted record, bypassing the skip-if-unchanged
+ *   idempotency.
+ * - `sampleSize` is **dry-run only**: how many mapped records to sample per
+ *   stream into the run's `dryRunSample`. Clamped to 1–100, defaults to 25.
+ * - `origin` is free text naming *what* asked for the run (`"Dashboard"`, an
+ *   integration scenario, your own scheduler), as opposed to `trigger`, which
+ *   only ever records `MANUAL` or `SCHEDULED`. Omitted or blank, the service
+ *   stores the `trigger` value instead. **Over 40 characters or containing
+ *   control characters is rejected, not shortened** — a truncated label in an
+ *   audit trail is worse than a refused request.
  */
 type ImportRunInput = NonNullable<PostImporttoolTriggerRunData["body"]>;
 /** Lifecycle status of an {@link ImportRun}. */
@@ -9988,13 +10045,58 @@ declare class ImportService {
      * a normal result rather than an error.
      */
     getSchedule(configId: string, auth?: AuthContext): Promise<ImportSchedule | null>;
-    /** Create or replace a configuration's schedule. */
+    /**
+     * Create or replace a configuration's schedule.
+     *
+     * **`cron` is a six-field Spring expression** (`second minute hour
+     * day-of-month month day-of-week`). The familiar five-field `"0 * * * *"` is
+     * not «hourly» here, it is invalid, and the service answers `400` rather than
+     * storing it — which it used to do, leaving a schedule that silently never
+     * fired.
+     *
+     * A `404` means no configuration with that id, so there is nothing to
+     * schedule. Use {@link deleteSchedule} to clear a schedule that outlived its
+     * configuration.
+     */
     setSchedule(configId: string, input: ImportSchedule, auth?: AuthContext): Promise<ImportSchedule>;
+    /**
+     * Remove a configuration's schedule. It then runs only when triggered.
+     *
+     * **Idempotent, and deliberately not gated on the configuration existing.**
+     * Removing a schedule that is not there also resolves — and unlike
+     * {@link setSchedule}, this does not require the configuration to exist. That
+     * is the point: a schedule left behind by a deleted configuration is exactly
+     * what needs removing, so refusing those would leave them with no way out.
+     *
+     * The service answers `204`, so this resolves to `void` rather than to the
+     * removed schedule.
+     */
+    deleteSchedule(configId: string, auth?: AuthContext): Promise<void>;
     /**
      * Trigger a run. `mode` defaults to `DELTA` server-side; `dryRun: true` maps
      * and validates without writing to the target.
      *
+     * A dry run can also hand back what it *would* have written: pass
+     * `sampleSize` (1–100, default 25) and read the run's `dryRunSample`. Set
+     * `origin` to name what asked for the run — `trigger` only distinguishes
+     * `MANUAL` from `SCHEDULED`, so without it a dashboard click and an
+     * integration scenario are indistinguishable in the history. Note the service
+     * **rejects** an `origin` over 40 characters instead of shortening it.
+     *
      * Not retried on a 5xx: a POST that timed out may already have queued a run.
+     *
+     * @example
+     * ```ts
+     * // Preview the mapping without writing anything.
+     * const run = await client.imports.triggerRun(configId, {
+     *   dryRun: true,
+     *   sampleSize: 5,
+     *   origin: "Dashboard",
+     * });
+     * for (const row of run.dryRunSample ?? []) {
+     *   console.log(row.stream, row.targetType, row.key, row.fields);
+     * }
+     * ```
      */
     triggerRun(configId: string, input?: ImportRunInput, auth?: AuthContext): Promise<ImportRun>;
     /** List a configuration's runs, newest first. */

package/dist/index.js

@@ -945,7 +945,7 @@ var HttpClient = class {
 };
 
 // package.json
-var version = "3.3.1";
+var version = "3.4.1";
 
 // src/version.ts
 var SDK_VERSION = version;
@@ -4330,7 +4330,19 @@ var ImportService = class {
     });
     return res ?? null;
   }
-  /** Create or replace a configuration's schedule. */
+  /**
+   * Create or replace a configuration's schedule.
+   *
+   * **`cron` is a six-field Spring expression** (`second minute hour
+   * day-of-month month day-of-week`). The familiar five-field `"0 * * * *"` is
+   * not «hourly» here, it is invalid, and the service answers `400` rather than
+   * storing it — which it used to do, leaving a schedule that silently never
+   * fired.
+   *
+   * A `404` means no configuration with that id, so there is nothing to
+   * schedule. Use {@link deleteSchedule} to clear a schedule that outlived its
+   * configuration.
+   */
   async setSchedule(configId, input, auth2 = SERVICE22) {
     return this.ctx.http.request({
       method: "PUT",
@@ -4339,11 +4351,50 @@ var ImportService = class {
       auth: auth2
     });
   }
+  /**
+   * Remove a configuration's schedule. It then runs only when triggered.
+   *
+   * **Idempotent, and deliberately not gated on the configuration existing.**
+   * Removing a schedule that is not there also resolves — and unlike
+   * {@link setSchedule}, this does not require the configuration to exist. That
+   * is the point: a schedule left behind by a deleted configuration is exactly
+   * what needs removing, so refusing those would leave them with no way out.
+   *
+   * The service answers `204`, so this resolves to `void` rather than to the
+   * removed schedule.
+   */
+  async deleteSchedule(configId, auth2 = SERVICE22) {
+    await this.ctx.http.request({
+      method: "DELETE",
+      path: `${this.base()}/configs/${encodeURIComponent(configId)}/schedule`,
+      auth: auth2
+    });
+  }
   /**
    * Trigger a run. `mode` defaults to `DELTA` server-side; `dryRun: true` maps
    * and validates without writing to the target.
    *
+   * A dry run can also hand back what it *would* have written: pass
+   * `sampleSize` (1–100, default 25) and read the run's `dryRunSample`. Set
+   * `origin` to name what asked for the run — `trigger` only distinguishes
+   * `MANUAL` from `SCHEDULED`, so without it a dashboard click and an
+   * integration scenario are indistinguishable in the history. Note the service
+   * **rejects** an `origin` over 40 characters instead of shortening it.
+   *
    * Not retried on a 5xx: a POST that timed out may already have queued a run.
+   *
+   * @example
+   * ```ts
+   * // Preview the mapping without writing anything.
+   * const run = await client.imports.triggerRun(configId, {
+   *   dryRun: true,
+   *   sampleSize: 5,
+   *   origin: "Dashboard",
+   * });
+   * for (const row of run.dryRunSample ?? []) {
+   *   console.log(row.stream, row.targetType, row.key, row.fields);
+   * }
+   * ```
    */
   async triggerRun(configId, input = {}, auth2 = SERVICE22) {
     return this.ctx.http.request({