@contrail/flexplm 1.5.1-alpha.c9b11be → 1.6.0-alpha.8e73fa3

package/lib/interfaces/mapping-file.d.ts

@@ -0,0 +1,783 @@
+import { FunctionTransformers, RekeyTransformers, TransformDefinition, TransformTask } from "@contrail/transform-data";
+/**
+ * One direction of a {@link MappingSection} (either `vibe2flex` or `flex2vibe`).
+ *
+ * Holds the per-direction transform pipeline plus the named lookup tables
+ * (`rekey`, `removeKey`, `valueTransform`) that the tasks in
+ * {@link DirectionalSection.transformOrder} reference by key. A REKEY task
+ * configured with `rekeyTransformersKey: 'rekey'` resolves to
+ * {@link DirectionalSection.rekey} on the same directional section.
+ *
+ * The named members below cover the conventional shape, but the section
+ * is open: each task in a pipeline resolves its config by reading the
+ * sibling property whose name is supplied by the matching `*Key` pointer
+ * on the task. That means a directional section can hold:
+ *  - additional `TransformTask[]` pipelines under names other than
+ *    `transformOrder` (selected by passing a non-default `orderKey` to
+ *    `MapFileUtil.getTransformTasks`)
+ *  - additional REKEY / REMOVE / MORPH / VALUE_TRANSFORM / CONDITIONAL
+ *    lookup tables under arbitrary names referenced by the task's
+ *    `rekeyTransformersKey`, `removeKeysKey`, `functionTransformersKey`,
+ *    or `conditionalTransformDefinitionsKey`.
+ *
+ * @example
+ * vibe2flex: {
+ *   transformOrder: [
+ *     { processor: 'VALUE_TRANSFORM', functionTransformersKey: 'valueTransform' },
+ *     { processor: 'REKEY', rekeyDelete: true, rekeyKeepEmptyValues: true, rekeyTransformersKey: 'rekey' },
+ *     { processor: 'REMOVE', removeKeysKey: 'removeKey' },
+ *   ],
+ *   rekey: { productName: 'name', custBrand: 'brand' },
+ *   valueTransform: {
+ *     itemNumber: (row) => '' + row['itemNumber'],
+ *   },
+ *   removeKey: ['patternReference', 'vibeOnlyProp'],
+ * }
+ */
+export interface DirectionalSection {
+    /**
+     * Ordered pipeline of transforms applied to each row in this direction.
+     *
+     * Each task is dispatched by its `processor` discriminator
+     * (REKEY, REMOVE, VALUE_TRANSFORM, MORPH, CONDITIONAL) and reads its
+     * configuration from the corresponding sibling property on this section
+     * (e.g. a REKEY task with `rekeyTransformersKey: 'rekey'` reads
+     * {@link DirectionalSection.rekey}).
+     *
+     * Ordering matters — tasks run top-to-bottom and operate on whatever
+     * the previous task left behind. Also there can be multiple tasks of
+     * the same processor type, as long as they have different config keys.
+     * This allows you to split up different logical steps (e.g. remove most
+     * unwanted fields before a value transform. Where the value transform
+     * needs a field to be present, but it must be removed before sending.
+     * Conventional order:
+     *  1. **REMOVE** — drop keys you don't want carried forward, while the
+     *     row is still in its input shape (so REMOVE keys match the input
+     *     system's slugs).
+     *  2. **VALUE_TRANSFORM** / **MORPH** — coerce / normalize values
+     *     while the keys are still recognizable.
+     *  3. **REKEY** — last, so the remaining keys are renamed to the
+     *     output system. After REKEY runs with `rekeyDelete: true`, the
+     *     input-side slugs are gone and any later REMOVE / VALUE_TRANSFORM
+     *     would need to be written against the output-side slugs instead.
+     *
+     * Swapping REKEY before REMOVE is a common cause of "my removeKey isn't
+     * doing anything" — by the time REMOVE runs, the keys have already
+     * been renamed.
+     *
+     * **Only processors listed in `transformOrder` actually run.** A
+     * `rekey` / `removeKey` / `valueTransform` table sitting on the
+     * directional section is inert unless a matching task references it
+     * here — defining `rekey: {...}` without a REKEY entry in
+     * `transformOrder` is silently a no-op. If a step seems to be doing
+     * nothing, check that its processor is in this list before assuming
+     * the lookup table is wrong.
+     *
+     * @example
+     * // Conventional: REMOVE → VALUE_TRANSFORM → REKEY.
+     * transformOrder: [
+     *   { processor: 'REMOVE', removeKeysKey: 'removeKey' },
+     *   { processor: 'VALUE_TRANSFORM', functionTransformersKey: 'valueTransform' },
+     *   { processor: 'REKEY', rekeyDelete: true, rekeyKeepEmptyValues: true, rekeyTransformersKey: 'rekey' },
+     * ]
+     */
+    transformOrder?: TransformTask[];
+    /**
+     * Resolves the FlexPLM object class (vibe2flex) or VibeIQ entity class
+     * (flex2vibe) for a row when it cannot be derived from the row itself.
+     *
+     * Consulted by `TypeConversionUtils.getObjectClass` /
+     * `getEntityClassFromObject` after the explicit `flexPLMObjectClass` /
+     * `vibeIQEntityClass` property and before the `TypeDefaults` fallback.
+     *
+     * @example
+     * // vibe2flex
+     * getClass: () => 'LCSRevisableEntity'
+     * // flex2vibe
+     * getClass: () => 'custom-entity'
+     */
+    getClass?: (entity: Record<string, unknown>) => string;
+    /**
+     * Resolves the FlexPLM type path (vibe2flex) or VibeIQ type path
+     * (flex2vibe) for a row when it cannot be derived from the row itself.
+     *
+     * Consulted by `TypeConversionUtils.getObjectTypePath` /
+     * `getEntityTypePathFromObject` after the explicit `flexPLMTypePath` /
+     * `vibeIQTypePath` property and before the `TypeDefaults` fallback.
+     *
+     * @example
+     * // vibe2flex
+     * getSoftType: () => 'Revisable Entity\\Product Concept'
+     * // flex2vibe
+     * getSoftType: () => 'custom-entity:styleConcept'
+     */
+    getSoftType?: (entity: Record<string, unknown>) => string;
+    /**
+     * Lookup table consumed by REKEY tasks in {@link DirectionalSection.transformOrder}.
+     *
+     * **Read each entry as `destination: 'source'`** — the property name (left)
+     * is the key written onto the row, the string value (right) is the
+     * existing key whose value is read. Each entry copies (or moves, when the
+     * task sets `rekeyDelete: true`) the value at the source key onto the
+     * destination key. Referenced by `rekeyTransformersKey` on the REKEY task.
+     *
+     * Because REKEY runs on the row in its **input** shape, the source side
+     * matches the direction's input system and the destination side matches
+     * its output system:
+     *  - Inside `vibe2flex.rekey`: `flexKey: 'vibeKey'` (vibe in → flex out).
+     *  - Inside `flex2vibe.rekey`: `vibeKey: 'flexKey'` (flex in → vibe out).
+     *
+     * @example
+     * // vibe2flex — left side is the FlexPLM key, right side is the VibeIQ key
+     * rekey: {
+     *   productName:    'name',         // flex 'productName'   ← vibe 'name'
+     *   custBrand:      'brand',        // flex 'custBrand'     ← vibe 'brand'
+     *   custStyleNumber: 'styleNumber', // flex 'custStyleNumber' ← vibe 'styleNumber'
+     * }
+     *
+     * @example
+     * // flex2vibe — left side is the VibeIQ key, right side is the FlexPLM key
+     * rekey: {
+     *   name:        'productName',     // vibe 'name'        ← flex 'productName'
+     *   brand:       'custBrand',       // vibe 'brand'       ← flex 'custBrand'
+     *   styleNumber: 'custStyleNumber', // vibe 'styleNumber' ← flex 'custStyleNumber'
+     * }
+     */
+    rekey?: RekeyTransformers;
+    /**
+     * Lookup table consumed by REMOVE tasks in {@link DirectionalSection.transformOrder}.
+     *
+     * Names of keys to delete from each row. Referenced by `removeKeysKey`
+     * on the REMOVE task.
+     *
+     * On the `vibe2flex` side, this is the **outbound filter** —
+     * {@link MappingSection.vibeOwningKeys} only governs inbound
+     * protection, so anything you want kept out of the FlexPLM payload
+     * has to be listed here. Typical entries:
+     *  - Vibe-internal fields with no FlexPLM equivalent
+     *    (`federatedId`, computed totals, planning-only properties).
+     *  - FlexPLM-owned inbound properties under their Vibe-side slug,
+     *    so they aren't echoed back to FlexPLM after a prior inbound sync.
+     *
+     * Keys are matched against the row in its **input** shape, so on
+     * `vibe2flex` list Vibe-side slugs (REMOVE runs before REKEY in the
+     * conventional ordering) and on `flex2vibe` list FlexPLM field names.
+     *
+     * `removeKey` vs {@link MappingSection.vibeOwningKeys} — different
+     * jobs, not redundant:
+     *  - `vibeOwningKeys` = **refuse to accept on inbound**.
+     *  - `vibe2flex.removeKey` = **refuse to send on outbound**.
+     *
+     * A property can belong in one, both, or neither — decide per
+     * property based on which system owns it:
+     *  - `targetIntroDate` (Vibe-owned, no Flex counterpart)
+     *    → in **both** (protect inbound, don't bother sending).
+     *  - `materialDescription` (Flex-owned, Vibe stores it after a
+     *    prior inbound sync) → in **`removeKey` only**, so the value
+     *    isn't echoed back to Flex; Flex still owns updates inbound.
+     *  - `event` (Vibe-owned, published to Flex) → in
+     *    **`vibeOwningKeys` only**; we want to keep sending it.
+     *
+     * @example
+     * // vibe2flex.removeKey — strip Vibe-internal + Flex-owned-inbound
+     * // properties before publish.
+     * removeKey: [
+     *   'federatedId',
+     *   'targetIntroDate',     // Vibe-owned, no Flex counterpart
+     *   'materialDescription', // Vibe-side slug of a Flex-owned inbound field
+     * ]
+     */
+    removeKey?: string[];
+    /**
+     * Lookup table consumed by VALUE_TRANSFORM tasks in
+     * {@link DirectionalSection.transformOrder}.
+     *
+     * Each entry's key is the property the function's return value is written
+     * to on the row; the function receives the full row plus optional
+     * dependencies. Referenced by `functionTransformersKey` on the
+     * VALUE_TRANSFORM task.
+     *
+     * @example
+     * valueTransform: {
+     *   itemNumber: (row) => {
+     *     const numValue = parseInt(row['itemNumber'], 10);
+     *     return isNaN(numValue) ? row['itemNumber'] : numValue;
+     *   },
+     * }
+     */
+    valueTransform?: Record<string, (row: Record<string, unknown>, dependencies?: unknown) => unknown>;
+    /**
+     * Lookup table consumed by MORPH tasks in {@link DirectionalSection.transformOrder}.
+     *
+     * Each entry's function receives the full row plus optional dependencies
+     * and may rewrite/augment it in place; unlike {@link DirectionalSection.valueTransform},
+     * the function key is just an identifier and is not the destination
+     * property. Referenced by `functionTransformersKey` on the MORPH task.
+     *
+     * @example
+     * morphTransform: {
+     *   morph1: (row) => {
+     *     const val = row['productStatus'];
+     *     if (val && Object.keys(val).length === 0) {
+     *       delete row['productStatus'];
+     *     }
+     *   },
+     * }
+     */
+    morphTransform?: Record<string, (row: Record<string, unknown>, dependencies?: unknown) => unknown>;
+    /**
+     * Catch-all for additional pipelines and per-processor lookup tables
+     * referenced by sibling `*Key` pointers on tasks. Each entry should be
+     * one of:
+     *  - {@link TransformTask}[] — alternate pipeline (read it by passing
+     *    its property name as `orderKey` to `MapFileUtil.getTransformTasks`)
+     *  - {@link RekeyTransformers} — `newKey` → `existingKey` map for REKEY
+     *  - `string[]` — keys to delete for REMOVE
+     *  - {@link FunctionTransformers} — Record<string, Function> for MORPH or VALUE_TRANSFORM
+     *  - {@link TransformDefinition}[] — conditional rules for CONDITIONAL
+     */
+    [key: string]: TransformTask[] | TransformDefinition[] | RekeyTransformers | FunctionTransformers | Record<string, unknown> | string[] | ((entity: Record<string, unknown>) => string) | ((entity: Record<string, unknown>) => string[]) | ((row: Record<string, unknown>, dependencies?: unknown) => unknown) | undefined;
+}
+/**
+ * Per-entity-type configuration block, keyed in the {@link MappingFile}
+ * by the section key returned from
+ * {@link TypeConversionEntry.getMapKey} (e.g. `LCSProduct`,
+ * `'Exchange Rate'`).
+ *
+ * Holds direction-agnostic settings (ownership, identifier/informational
+ * properties, creation and image-sync gates) plus the two
+ * {@link DirectionalSection}s that drive the actual data transforms.
+ *
+ * @example
+ * LCSProduct: {
+ *   // Identifier — used for lookup / create-vs-update routing.
+ *   getIdentifierProperties: () => ['styleNumber'],
+ *   // Vibe-owned attributes.
+ *   vibeOwningKeys: ['lifecycleStage', 'targetIntroDate'],
+ *   vibe2flex: {
+ *     transformOrder: [
+ *       { processor: 'REMOVE', removeKeysKey: 'removeKey' },
+ *       { processor: 'REKEY', rekeyDelete: true, rekeyKeepEmptyValues: true, rekeyTransformersKey: 'rekey' },
+ *     ],
+ *     // Strip Vibe-only / Flex-owned-inbound props before publish.
+ *     removeKey: ['federatedId'],
+ *     // destination: source -> flexKey: 'vibeKey'
+ *     rekey: { productName: 'name' },
+ *   },
+ *   flex2vibe: {
+ *     transformOrder: [
+ *       { processor: 'REKEY', rekeyDelete: true, rekeyKeepEmptyValues: true, rekeyTransformersKey: 'rekey' },
+ *     ],
+ *     // destination: source -> vibeKey: 'flexKey'
+ *     rekey: { name: 'productName' },
+ *   },
+ * }
+ */
+export interface MappingSection {
+    /**
+     * Slugs of the VibeIQ properties that VibeIQ owns. During inbound
+     * (flex2vibe) processing, any value FlexPLM tries to send for one
+     * of these slugs is ignored — the existing VibeIQ value is preserved.
+     *
+     * Scope: **inbound only**. This list does *not* filter outbound
+     * payloads — Vibe-only properties still flow to FlexPLM unless you
+     * strip them in {@link DirectionalSection.removeKey} on the
+     * `vibe2flex` side.
+     *
+     * What `vibeOwningKeys` does **not** do — reach for these fields
+     * instead:
+     *  - Strip fields from the outbound payload → use
+     *    {@link DirectionalSection.removeKey} on `vibe2flex`.
+     *  - Block inbound entity creation → use
+     *    {@link MappingSection.isInboundCreatable}.
+     *  - Drive lookup / matching / dedupe → use
+     *    {@link MappingSection.getIdentifierProperties}.
+     *  - Skip value transformations or rekeying → those run regardless;
+     *    omit the property from `rekey` / `valueTransform` if you want
+     *    it left alone.
+     *
+     * `vibeOwningKeys` vs {@link DirectionalSection.removeKey} —
+     * different jobs, not redundant:
+     *  - `vibeOwningKeys` = **refuse to accept on inbound**.
+     *  - `vibe2flex.removeKey` = **refuse to send on outbound**.
+     *
+     * A property can belong in one, both, or neither — decide per
+     * property based on which system owns it:
+     *  - `targetIntroDate` (Vibe-owned, no Flex counterpart)
+     *    → in **both** (protect inbound, don't bother sending).
+     *  - `materialDescription` (Flex-owned, Vibe stores it after a
+     *    prior inbound sync) → in **`removeKey` only**, so the value
+     *    isn't echoed back to Flex; Flex still owns updates inbound.
+     *  - `event` (Vibe-owned, published to Flex) → in
+     *    **`vibeOwningKeys` only**; we want to keep sending it.
+     *
+     * @example
+     * // Right: Vibe-owned attributes;
+     * // If Vibe owns the identifier, include it here as well.
+     * vibeOwningKeys: ['itemNumber', 'lifecycleStage', 'targetIntroDate']
+     */
+    vibeOwningKeys?: string[];
+    /**
+     * Tag identifying which identity service uniqueness pool this entity participates in.
+     * There can only be one entity with a given value for the property(defined by `getIdentifierProperties`) within the same uniqueness pool.
+     *
+     * @example
+     * uniquenessPool: 'item'
+     */
+    uniquenessPool?: string;
+    /**
+     * Gate controlling whether an inbound FlexPLM object is allowed to
+     * create a new VibeIQ entity. When the function returns `false`, the
+     * inbound row may still update an existing entity but will not create
+     * one. Consulted by `TypeConversionUtils.isInboundCreatableFromObject`;
+     * defaults to `false` when the function is absent.
+     *
+     * The function receives the inbound row, so the decision can be
+     * per-record (e.g. only allow inbound creation when a status or
+     * type-discriminator flag is set). Common patterns:
+     *  - `() => true` — FlexPLM owns creation for this entity type.
+     *  - `() => false` — VibeIQ owns creation; inbound rows can only
+     *    update existing entities.
+     *  - Conditional — inspect the row and allow / disallow per record.
+     *
+     * On the **season-link** sections (`LCSProductSeasonLink` /
+     * `LCSSKUSeasonLink`), `() => true` enables the add-to-project
+     * flow: FlexPLM-driven inbound events can add an item to a Vibe
+     * project (not just update an existing project-item).
+     * Pair with {@link MappingSection.isOutboundCreatable} returning
+     * `false` so the outbound side becomes update-only. This pattern
+     * also requires matching FlexPLM-side configuration; see the
+     * project documentation for the full setup.
+     *
+     * @example
+     * // Flex owns creation.
+     * isInboundCreatable: () => true
+     *
+     * @example
+     * // Conditional: allow inbound creation only when the row is active
+     * // and the type-path matches a class we accept from FlexPLM.
+     * isInboundCreatable: (object) => {
+     *   if (object?.['status']?.value?.toLowerCase?.() !== 'active') return false;
+     *   return object?.['flexPLMTypePath'] === 'Color\\Solid';
+     * }
+     *
+     * @example
+     * // add-to-project flow — Flex drives project-item creation.
+     * // Paired with isOutboundCreatable: () => false to make
+     * // outbound update-only.
+     * LCSProductSeasonLink: {
+     *   isInboundCreatable:  () => true,
+     *   isOutboundCreatable: () => false,
+     * }
+     */
+    isInboundCreatable?: (entity: Record<string, unknown>, context?: unknown) => boolean;
+    /**
+     * Gate controlling whether an outbound VibeIQ entity is allowed to
+     * create a new FlexPLM object. When the function returns `false`, the
+     * outbound publish becomes an update-only operation. Consulted by
+     * `TypeConversionUtils.isOutboundCreatableFromEntity`; defaults to
+     * `true` when the function is absent.
+     *
+     * On the **season-link** sections (`LCSProductSeasonLink` /
+     * `LCSSKUSeasonLink`), `() => false` converts outbound publish events
+     * to `UPDATE_ON_SEASON`: they only update an existing season-link,
+     * never create one. If the Product / Colorway isn't already on the
+     * season, **that specific event fails** while other events continue
+     * to process — the failure is per-record, not fatal to the batch.
+     *
+     * Pair with {@link MappingSection.isInboundCreatable} returning
+     * `true` to delegate add-to-project creation to FlexPLM. This pattern
+     * also requires matching FlexPLM-side configuration; see the project
+     * documentation for the full setup.
+     *
+     * @example
+     * // add-to-project flow — Vibe never adds items to seasons; Flex does.
+     * LCSProductSeasonLink: {
+     *   isInboundCreatable:  () => true,
+     *   isOutboundCreatable: () => false,   // becomes UPDATE_ON_SEASON
+     * }
+     */
+    isOutboundCreatable?: (entity: Record<string, unknown>, context?: unknown) => boolean;
+    /**
+     * Gate controlling whether image/thumbnail content should be synced
+     * from FlexPLM into VibeIQ for this entity type. Consulted by
+     * `TypeConversionUtils.syncInboundImages`; defaults to `false` when
+     * the function is absent. Typically aligned with whichever system
+     * owns creation of the entity.
+     *
+     * @example
+     * syncInboundImages: () => true
+     */
+    syncInboundImages?: (entity: Record<string, unknown>, context?: unknown) => boolean;
+    /**
+     * Gate controlling whether image/thumbnail content should be synced
+     * from VibeIQ out to FlexPLM for this entity type. Consulted by
+     * `TypeConversionUtils.syncOutboundImages`; defaults to `true` when
+     * the function is absent. Typically aligned with whichever system
+     * owns creation of the entity.
+     *
+     * @example
+     * syncOutboundImages: () => false
+     */
+    syncOutboundImages?: (entity: Record<string, unknown>, context?: unknown) => boolean;
+    /**
+     * Returns the property names that uniquely identify this entity. Used
+     * by `TypeConversionUtils.getIdentifierProperties` to drive lookup and
+     * matching when an explicit `flexPLMIdentifierProperties` /
+     * `vibeIQIdentifierProperties` is not present on the row, falling
+     * back to `TypeDefaults` when this is absent.
+     *
+     * Identifier properties are the *business key* used to answer
+     * "does this inbound payload refer to an existing entity, or do we
+     * need to create one?" The connector uses them for entity lookup,
+     * create-vs-update routing, and the deterministic targeting of
+     * retry / resend events.
+     *
+     * Inbound lookup outcomes drive routing:
+     *  - **0 matches** → row is treated as a new entity; creation
+     *    proceeds only if {@link MappingSection.isInboundCreatable}
+     *    allows it, otherwise the row is dropped.
+     *  - **1 match** → existing entity is updated.
+     *  - **>1 match** → processing fails for that row to avoid
+     *    ambiguity. Multiple matches means the identifier isn't
+     *    actually unique; fix the data or pick a tighter key rather
+     *    than letting the merge happen silently.
+     *
+     * Multiple slugs form a **composite key** — all of them must match
+     * the same existing entity for it to count as the same record. If
+     * any value differs, the row is treated as a different entity.
+     *
+     * Best practices:
+     *  - Pick the **minimum set** of slugs that uniquely identifies the
+     *    entity. Multiple slugs are treated as a composite key — all of
+     *    them must match for the lookup to succeed.
+     *  - Prefer **stable** business identifiers (item / style / season
+     *    numbers) over frequently-changing fields. Renames of an
+     *    identifier are a data-migration event, not a routine update.
+     *  - Ensure the identifier exists in **both** systems and on
+     *    historical records. If it's missing on legacy data the lookup
+     *    will silently create duplicates.
+     *
+     * When the connector app config sets
+     * `search.<entityType>.useIdentityServiceForInboundData: true` for
+     * the entity type (e.g. `item`, `color`, `custom-entity`), inbound
+     * identifier matching switches from a direct-property query to the
+     * platform identity service. This is forward-looking: enable it only
+     * after the identifier property has been configured as unique in
+     * Vibe and the historical-data backfill is complete. {@link
+     * MappingSection.uniquenessPool} declares which identity-service
+     * uniqueness pool the entity participates in.
+     *
+     * @example
+     * // Single business key
+     * getIdentifierProperties: () => ['itemNumber']
+     *
+     * @example
+     * // Composite key — both slugs must match for a row to count as the
+     * // same entity.
+     * getIdentifierProperties: () => ['seasonName', 'year']
+     */
+    getIdentifierProperties?: (entity: Record<string, unknown>) => string[];
+    /**
+     * Returns supplemental property names that should be carried alongside
+     * identifiers (e.g. display names) but do not participate in identity.
+     * Consulted by `TypeConversionUtils.getInformationalProperties` with
+     * the same lookup precedence as {@link MappingSection.getIdentifierProperties}.
+     *
+     * Purpose is **observability**, not behavior. Informational properties:
+     *  - ride along in retry / resend event payloads so the retry target
+     *    is human-readable, not just a numeric ID;
+     *  - surface in logs, error messages, and monitoring dashboards so
+     *    failures can be triaged without opening a debugger;
+     *  - give engineers and ops a way to recognize "which entity is this"
+     *    at a glance.
+     *
+     * They are **not** used for entity matching, create-vs-update routing,
+     * uniqueness enforcement, or duplicate prevention. If a property
+     * needs to influence any of those, put it in
+     * {@link MappingSection.getIdentifierProperties} instead.
+     *
+     * Prefer stable, readable, scalar fields (names, numbers). Avoid
+     * large objects, references, or frequently-changing values — they'll
+     * bloat retry payloads and clutter logs without adding clarity.
+     *
+     * @example
+     * // SKU: matched by colorwaySeqID, but log lines show the itemNumber.
+     * // "Failed to upsert SKU — colorwaySeqID=12345 itemNumber=NB-574-BLU"
+     * LCSSKU: {
+     *   getIdentifierProperties:    () => ['colorwaySeqID'],
+     *   getInformationalProperties: () => ['itemNumber'],
+     * }
+     *
+     * @example
+     * // Multiple informational properties — all carried together; none
+     * // affect matching.
+     * getInformationalProperties: () => ['itemNumber', 'skuName']
+     */
+    getInformationalProperties?: (entity: Record<string, unknown>) => string[];
+    /**
+     * Transform configuration applied when sending data from VibeIQ to FlexPLM.
+     * Pipeline runs on rows in their VibeIQ shape and produces rows in their
+     * FlexPLM shape, so inside `rekey` the destination (left) is the FlexPLM
+     * key and the source (right) is the VibeIQ key — see
+     * {@link DirectionalSection.rekey}.
+     *
+     * Responsibilities:
+     *  - Rename Vibe attribute slugs to Flex field names (`rekey`).
+     *  - Remove Vibe-only attributes from the payload
+     *    ({@link DirectionalSection.removeKey}).
+     *  - Convert / coerce values to formats FlexPLM accepts
+     *    ({@link DirectionalSection.valueTransform},
+     *    {@link DirectionalSection.morphTransform}).
+     *  - Produce a Flex-valid payload ready for publish.
+     *
+     * Note the asymmetry with `flex2vibe`: the inbound ownership and
+     * creation gates ({@link MappingSection.vibeOwningKeys},
+     * {@link MappingSection.isInboundCreatable}) do **not** apply here.
+     * `vibe2flex` is the side that *sends* Vibe data out — protecting
+     * Vibe data from being overwritten only makes sense on the inbound
+     * side. To keep Vibe-only fields from leaking outbound, list them in
+     * `removeKey`.
+     */
+    vibe2flex?: DirectionalSection;
+    /**
+     * Transform configuration applied when receiving data from FlexPLM into VibeIQ.
+     * Pipeline runs on rows in their FlexPLM shape and produces rows in their
+     * VibeIQ shape, so inside `rekey` the destination (left) is the VibeIQ
+     * key and the source (right) is the FlexPLM key — see
+     * {@link DirectionalSection.rekey}.
+     *
+     * Responsibilities:
+     *  - Rename Flex field names to Vibe attribute slugs (`rekey`).
+     *  - Normalize / coerce inbound values into Vibe-compatible formats
+     *    ({@link DirectionalSection.valueTransform},
+     *    {@link DirectionalSection.morphTransform}).
+     *  - Produce a row ready to hand to `setEntityValues()` /
+     *    inbound persistence.
+     *
+     * This is the direction where the protective gates fire:
+     *  - {@link MappingSection.vibeOwningKeys} prevents inbound rows
+     *    from overwriting Vibe-owned attributes.
+     *  - {@link MappingSection.isInboundCreatable} decides whether an
+     *    inbound row whose identifier matches nothing should create a
+     *    new Vibe entity or be dropped.
+     */
+    flex2vibe?: DirectionalSection;
+}
+/**
+ * Entry in the {@link TypeConversionSection} that maps a single source
+ * type onto the {@link MappingSection} key that should handle it.
+ *
+ * Useful for fanning a single VibeIQ `entityType` (e.g. `'custom-entity'`)
+ * out to multiple sections based on the row's `typePath`.
+ */
+export interface TypeConversionEntry {
+    /**
+     * Returns the {@link MappingFile} key whose {@link MappingSection}
+     * should be used to transform `entity`. Returning an empty string
+     * signals that no section applies and the row should be skipped.
+     *
+     * @example
+     * getMapKey: (entity) => {
+     *   switch (entity['typePath']) {
+     *     case 'custom-entity:exchangeRate': return 'Exchange Rate';
+     *     case 'custom-entity:styleConcept': return 'Style Concept Master';
+     *     default: return '';
+     *   }
+     * }
+     */
+    getMapKey: (entity: Record<string, unknown>) => string;
+}
+/**
+ * One direction of {@link TypeConversion}, keyed by the source-system
+ * type:
+ * - In `vibe2flex`, keys are VibeIQ entity types (e.g. `'custom-entity'`,
+ *   `'size-range-template'`) — see `TypeConversionUtils.getEntityType`.
+ * - In `flex2vibe`, keys are FlexPLM object classes (e.g. `LCSProduct`) —
+ *   see `TypeConversionUtils.getObjectType`.
+ */
+export interface TypeConversionSection {
+    [type: string]: TypeConversionEntry;
+}
+/**
+ * Top-level routing table that resolves a row to its
+ * {@link MappingSection} key for each direction.
+ *
+ * `TypeConversionUtils.getMapKey` / `getMapKeyFromObject` look up the
+ * row's type in the appropriate side, invoke
+ * {@link TypeConversionEntry.getMapKey}, and use the returned string
+ * as the key into the rest of the {@link MappingFile}.
+ *
+ * @example
+ * typeConversion: {
+ *   vibe2flex: {
+ *     'custom-entity': {
+ *       getMapKey: (entity) => {
+ *         switch (entity['typePath']) {
+ *           case 'custom-entity:exchangeRate': return 'Exchange Rate';
+ *           default: return '';
+ *         }
+ *       },
+ *     },
+ *     'size-range-template': {
+ *       getMapKey: () => 'size-range-template',
+ *     },
+ *   },
+ *   flex2vibe: {
+ *     LCSRevisableEntity: {
+ *       getMapKey: (object) => {
+ *         switch (object['flexPLMTypePath']) {
+ *           case 'Revisable Entity\\Exchange Rate': return 'Exchange Rate';
+ *           default: return '';
+ *         }
+ *       },
+ *     },
+ *   },
+ * }
+ */
+export interface TypeConversion {
+    /**
+     * Routes outbound VibeIQ entities to their FlexPLM mapping sections.
+     *
+     * When no entry matches the row's VibeIQ entity type, the connector
+     * falls back to looking up a section by the row's `TypeDefaults`
+     * class. The explicit `vibe2flex` entries here override that fallback
+     * and are only needed when a single VibeIQ type fans out to multiple
+     * mapping sections (e.g. `'custom-entity'` dispatched by `typePath`).
+     */
+    vibe2flex: TypeConversionSection;
+    /**
+     * Routes inbound FlexPLM objects to their VibeIQ mapping sections.
+     *
+     * When no entry matches the row's FlexPLM object class, the connector
+     * falls back to using the row's `flexPLMObjectClass` directly as the
+     * section key. Explicit `flex2vibe` entries are only needed when one
+     * FlexPLM class fans out to multiple mapping sections (e.g.
+     * `LCSLifecycleManaged` dispatched by `flexPLMTypePath`).
+     *
+     * `LCSMaterial` routing — special case: by default `LCSMaterial`
+     * maps to `custom-entity` on the VibeIQ side. To route it to
+     * `item:material` (treating materials as a subtype of `item`)
+     * instead, **both** of the following must be in place:
+     *  1. Connector app config sets
+     *     `{ "LCSMaterial": { "processAsItem": true } }`. The mapping
+     *     file alone can't change which entity type LCSMaterial maps to.
+     *  2. `flex2vibe.LCSMaterial.getMapKey` returns the name of a custom
+     *     mapping section that declares `getClass: () => 'item'` +
+     *     `getSoftType: () => 'item:material'` on its `flex2vibe` side.
+     *     The matching `vibe2flex.item.getMapKey` should route
+     *     `item:material` typePath back to the same section.
+     */
+    flex2vibe: TypeConversionSection;
+}
+/** Identifies the application and tenant that owns a {@link MappingFile}. */
+export interface OrgInfo {
+    /** This is the identifier for the application, and is used to set the owner of the mapping file */
+    appIdentifier: '@vibeiq/flexplm-connector';
+    /** The name of the organization using the mapping file. */
+    orgName: string;
+}
+interface MappingFileBase {
+    /** The information about the organization using the mapping file */
+    orgInfo: OrgInfo;
+    /** The type conversion information for the mapping file. */
+    typeConversion: TypeConversion;
+}
+/**
+ * Full mapping file driving bidirectional sync between VibeIQ and FlexPLM
+ * for a single tenant.
+ *
+ * Combines the fixed {@link MappingFileBase} fields (`orgInfo`,
+ * `typeConversion`) with an open set of {@link MappingSection} entries
+ * keyed by the strings returned from
+ * {@link TypeConversionEntry.getMapKey} (e.g. `LCSProduct`, `LCSSKU`,
+ * `'Exchange Rate'`).
+ *
+ * # Supported entity mappings
+ *
+ * The tables below describe which VibeIQ entity types and FlexPLM object
+ * classes can be synced today and what each direction does behind the
+ * scenes. "Not yet supported" entries are listed explicitly so authors
+ * know not to attempt them.
+ *
+ * ## VibeIQ → FlexPLM
+ *
+ * | VibeIQ entity type   | FlexPLM object class             | Behavior                                                                                                   |
+ * |----------------------|----------------------------------|------------------------------------------------------------------------------------------------------------|
+ * | `item`               | `LCSProduct` / `LCSSKU`          | Syncs once `lifecycleStage` is out of `concept`. Sends Primary Viewable as the thumbnail (no other images). Creates `LCSProduct` / `LCSSKU` if missing; auto-retries `LCSSKU` creation when the parent `LCSProduct` isn't ready yet. |
+ * | `color`              | `LCSColor`                       | Syncs on create / update. Sends Primary Viewable as the thumbnail. Creates `LCSColor` if missing.          |
+ * | `custom-entity`      | `LCSRevisableEntity`             | Syncs on create / update. Creates `LCSRevisableEntity` if missing. Workflows should gate on the custom-entity subtype so only the intended subtypes publish. |
+ * | `project-item`       | `LCSProductSeasonLink` / `LCSSKUSeasonLink` | Syncs on plan publish. Requires the assortment to have `publishToFlexPLM=true` and `flexPLMSeasonName` set. Adds the Product / SKU to the `LCSSeason` if not already linked. Only project-items changed since the last publish are sent (configurable to reach further back). Processing on the FlexPLM side is async via a Windchill Queue. |
+ * | `item:material`      | `LCSMaterial`                    | Supported via custom mapping section + `typeConversion`. Route `item:material` typePath to a mapping section that declares `getClass: () => 'LCSMaterial'` and `getSoftType: () => 'Material'`. See {@link TypeConversion} for the `LCSMaterial.processAsItem` config flag that pairs with this. |
+ * | `custom-entity`      | `LCSLast` / `LCSLifecycleManaged` | **Not yet supported.**                                                                                     |
+ *
+ * ## FlexPLM → VibeIQ
+ *
+ * | FlexPLM object class    | VibeIQ entity type         | Behavior                                                                                                   |
+ * |-------------------------|----------------------------|------------------------------------------------------------------------------------------------------------|
+ * | `LCSProduct`            | `item` (role: `family`)    | Configurable via mapping file to create new items; updates existing items if found. Does **not** sync the thumbnail to VibeIQ. |
+ * | `LCSSKU`                | `item` (role: `option`)    | Configurable to create new items; updates existing items. Does **not** sync the thumbnail.                 |
+ * | `LCSProductSeasonLink`  | `project-item` (`family`)  | Updates existing items if found. Can be configured to add an item to a project, including setting carried-over data — see the add-to-project flow under {@link MappingSection.isInboundCreatable}. |
+ * | `LCSSKUSeasonLink`      | `project-item` (`option`)  | Updates existing items. Add-to-project supported under the same flow.                                      |
+ * | `LCSColor`              | `color`                    | Configurable to create new colors; updates existing colors. Does **not** sync the thumbnail.               |
+ * | `LCSLast`               | `custom-entity`            | Configurable to create new custom-entities; updates existing.                                              |
+ * | `LCSLifecycleManaged`   | `custom-entity`            | Configurable to create new custom-entities; updates existing.                                              |
+ * | `LCSMaterial`           | `custom-entity` (default) or `item:material` | Default: custom-entity. To route to `item:material` instead, set `{ "LCSMaterial": { "processAsItem": true } }` in the connector app config and write a mapping section with `getClass: () => 'item'` + `getSoftType: () => 'item:material'`. Wire it via `flex2vibe.LCSMaterial.getMapKey` returning that section's name. |
+ * | `LCSRevisableEntity`    | `custom-entity`            | Configurable to create new custom-entities; updates existing.                                              |
+ * | (any)                   | `item` (direct, no link)   | **Not yet supported.**                                                                                     |
+ *
+ * @example
+ * export const mapping: MappingFile = {
+ *   orgInfo: {
+ *     appIdentifier: '@vibeiq/flexplm-connector',
+ *     orgName: 'acme',
+ *   },
+ *   typeConversion: {
+ *     vibe2flex: {
+ *       'custom-entity': {
+ *         getMapKey: (entity) => {
+ *           switch (entity['typePath']) {
+ *             case 'custom-entity:exchangeRate': return 'Exchange Rate';
+ *             default: return '';
+ *           }
+ *         },
+ *       },
+ *       'size-range-template': {
+ *         getMapKey: () => 'size-range-template',
+ *       },
+ *     },
+ *     flex2vibe: {
+ *       LCSRevisableEntity: {
+ *         getMapKey: (object) => {
+ *           switch (object['flexPLMTypePath']) {
+ *             case 'Revisable Entity\\Exchange Rate': return 'Exchange Rate';
+ *             default: return '';
+ *           }
+ *         },
+ *       },
+ *     },
+ *   },
+ *   'Exchange Rate': {
+ *     vibe2flex: {
+ *       transformOrder: [
+ *         { processor: 'REKEY', rekeyDelete: true, rekeyKeepEmptyValues: true, rekeyTransformersKey: 'rekey' },
+ *       ],
+ *       rekey: { exchangeRateDescription: 'name' },
+ *       getClass: () => 'LCSRevisableEntity',
+ *       getSoftType: () => 'Revisable Entity\\Exchange Rate',
+ *     },
+ *     flex2vibe: {
+ *       transformOrder: [
+ *         { processor: 'REKEY', rekeyDelete: true, rekeyKeepEmptyValues: true, rekeyTransformersKey: 'rekey' },
+ *       ],
+ *       rekey: { name: 'exchangeRateDescription' },
+ *       getClass: () => 'custom-entity',
+ *       getSoftType: () => 'custom-entity:exchangeRate',
+ *     },
+ *   },
+ * };
+ */
+export type MappingFile = MappingFileBase & {
+    [mapKey: string]: MappingSection | MappingFileBase[keyof MappingFileBase];
+};
+export {};