@contrail/flexplm 1.6.0-alpha.6f15d4e → 1.6.0-alpha.8e73fa3

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

@@ -44,10 +44,41 @@ export interface DirectionalSection {
      * (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: 'REKEY', rekeyDelete: true, rekeyKeepEmptyValues: true, rekeyTransformersKey: 'rekey' },
      *   { processor: 'REMOVE', removeKeysKey: 'removeKey' },
+     *   { processor: 'VALUE_TRANSFORM', functionTransformersKey: 'valueTransform' },
+     *   { processor: 'REKEY', rekeyDelete: true, rekeyKeepEmptyValues: true, rekeyTransformersKey: 'rekey' },
      * ]
      */
     transformOrder?: TransformTask[];
@@ -119,8 +150,42 @@ export interface DirectionalSection {
      * 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
-     * removeKey: ['patternReference', 'vibeOnlyProp']
+     * // 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[];
     /**
@@ -185,12 +250,17 @@ export interface DirectionalSection {
  *
  * @example
  * LCSProduct: {
- *   vibeOwningKeys: ['itemNumber', 'lifecycleStage'],
+ *   // 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' },
  *   },
@@ -205,12 +275,46 @@ export interface DirectionalSection {
  */
 export interface MappingSection {
     /**
-     * These are the slugs of the properties that the VibeIQ system owns.  So
-     * even if data comes in from an external source, it is ignored and the
-     * values are not overwritten.
+     * 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
-     * vibeOwningKeys: ['itemNumber', 'lifecycleStage']
+     * // Right: Vibe-owned attributes;
+     * // If Vibe owns the identifier, include it here as well.
+     * vibeOwningKeys: ['itemNumber', 'lifecycleStage', 'targetIntroDate']
      */
     vibeOwningKeys?: string[];
     /**
@@ -228,8 +332,43 @@ export interface MappingSection {
      * 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;
     /**
@@ -239,8 +378,24 @@ export interface MappingSection {
      * `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
-     * isOutboundCreatable: () => false
+     * // 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;
     /**
@@ -272,8 +427,55 @@ export interface MappingSection {
      * `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[];
     /**
@@ -282,8 +484,35 @@ export interface MappingSection {
      * 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
-     * getInformationalProperties: () => ['longName']
+     * // 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[];
     /**
@@ -292,6 +521,23 @@ export interface MappingSection {
      * 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;
     /**
@@ -300,6 +546,21 @@ export interface MappingSection {
      * 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;
 }
@@ -375,9 +636,38 @@ export interface TypeConversionSection {
  * }
  */
 export interface TypeConversion {
-    /** Routes outbound VibeIQ entities to their FlexPLM mapping sections. */
+    /**
+     * 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. */
+    /**
+     * 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}. */
@@ -403,6 +693,39 @@ interface MappingFileBase {
  * {@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: {

package/lib/publish/base-process-publish-assortment.d.ts

@@ -86,8 +86,10 @@ export declare class BaseProcessPublishAssortment {
     getResultsCount(events: any): any;
     private sendEvents;
     private sendToFlexPLM;
+    private buildPublishError;
     private saveToLocalFile;
     private handleVibeIQFile;
+    private sendPublishPayloadEvent;
     private getCurrentDateString;
     getItemFamilyChanges(pcd: PublishChangeData, changeDetail: any, assortmentItemFullChangeMap: Map<string, any>, assortmentItemDeleteMap: Map<string, any>): Map<string, ItemFamilyChanges>;
     getEventsForPublishChangeData(publishChangeData: PublishChangeData): Promise<SeasonalPayload[]>;

package/lib/publish/base-process-publish-assortment.js

@@ -595,14 +595,37 @@ class BaseProcessPublishAssortment {
         }
     }
     async sendToFlexPLM(events, eventType) {
-        const asyncEvent = {
+        const outboundPublishEvent = {
             taskId: this.config.taskId,
             eventType,
             objectClass: 'LCSSeason',
             events
         };
         const flexPLMConnect = new flexplm_connect_1.FlexPLMConnect(this.config);
-        return await flexPLMConnect.sendToFlexPLM(asyncEvent);
+        const [sendResult, eventResult] = await Promise.allSettled([
+            flexPLMConnect.sendToFlexPLM(outboundPublishEvent),
+            this.sendPublishPayloadEvent(outboundPublishEvent)
+        ]);
+        if (sendResult.status === 'rejected' || eventResult.status === 'rejected') {
+            throw this.buildPublishError(sendResult, eventResult, outboundPublishEvent);
+        }
+        const result = sendResult.value;
+        const isResultObject = typeof result === 'object' && result !== null;
+        return isResultObject
+            ? { ...result, outboundPublishEvent }
+            : { result, outboundPublishEvent };
+    }
+    buildPublishError(sendResult, eventResult, outboundPublishEvent) {
+        const baseReason = sendResult.status === 'rejected' ? sendResult.reason : eventResult.reason;
+        const error = baseReason instanceof Error ? baseReason : new Error(String(baseReason));
+        error.outboundPublishEvent = outboundPublishEvent;
+        error.sendToFlexPLMResult = sendResult.status === 'fulfilled'
+            ? sendResult.value
+            : { error: sendResult.reason?.message ?? String(sendResult.reason) };
+        error.sendPublishPayloadEventResult = eventResult.status === 'fulfilled'
+            ? eventResult.value
+            : { error: eventResult.reason?.message ?? String(eventResult.reason) };
+        return error;
     }
     async saveToLocalFile(events, eventType) {
         let results = {};
@@ -614,15 +637,16 @@ class BaseProcessPublishAssortment {
             const eventDirName = 'events-output';
             const fileName = `${path.sep}${eventDirName}${path.sep}events-${dateString}.json`;
             fileHandle = await fsPromise.open('.' + fileName, 'a');
-            const asyncEvent = {
+            const outboundPublishEvent = {
                 taskId: this.config.taskId,
                 eventType,
                 objectClass: 'LCSSeason',
                 events
             };
-            await fileHandle.writeFile(JSON.stringify(asyncEvent));
+            await fileHandle.writeFile(JSON.stringify(outboundPublishEvent));
             results = {
                 message: 'Successfully Saved File',
+                outboundPublishEvent,
                 fileLocation: dirName + fileName
             };
         }
@@ -638,7 +662,7 @@ class BaseProcessPublishAssortment {
         const eventBuffer = Buffer.from(JSON.stringify(events), 'utf-8');
         const fileName = 'ASYNC_PUBLISH_SEASON-events.json';
         const uploadFile = await new sdk_1.Files().createAndUploadFileFromBuffer(eventBuffer, 'application/json', fileName, null, this.TTL);
-        const asyncEvent = {
+        const outboundPublishEvent = {
             taskId: this.config.taskId,
             eventType,
             objectClass: 'LCSSeason',
@@ -648,15 +672,46 @@ class BaseProcessPublishAssortment {
         };
         if (sendMode === 'vibeiqfile') {
             const flexPLMConnect = new flexplm_connect_1.FlexPLMConnect(this.config);
-            return await flexPLMConnect.sendToFlexPLM(asyncEvent);
+            const [sendResult, eventResult] = await Promise.allSettled([
+                flexPLMConnect.sendToFlexPLM(outboundPublishEvent),
+                this.sendPublishPayloadEvent(outboundPublishEvent)
+            ]);
+            if (sendResult.status === 'rejected' || eventResult.status === 'rejected') {
+                throw this.buildPublishError(sendResult, eventResult, outboundPublishEvent);
+            }
+            const result = sendResult.value;
+            const isResultObject = typeof result === 'object' && result !== null;
+            return isResultObject
+                ? { ...result, outboundPublishEvent }
+                : { result, outboundPublishEvent };
         }
         else {
+            await this.sendPublishPayloadEvent(outboundPublishEvent);
             return {
                 message: 'Successfully Uploaded File.',
-                asyncEvent
+                outboundPublishEvent
             };
         }
     }
+    async sendPublishPayloadEvent(outboundPublishEvent) {
+        console.info('sendPublishPayloadEvent()');
+        let initialEvent = {};
+        if (this.config?.event) {
+            initialEvent = (typeof this.config?.event === 'string')
+                ? JSON.parse(this.config?.event)
+                : this.config?.event;
+        }
+        const eventBody = {
+            originSystemType: 'VibeIQ',
+            objectClass: 'AssortmentPublishedToFlexPLM',
+            outboundPublishEvent,
+            initialEvent
+        };
+        await new sdk_1.Entities().create({
+            entityName: 'external-event',
+            object: eventBody
+        });
+    }
     getCurrentDateString() {
         const d = new Date();
         return '' + d.getUTCFullYear()

package/lib/publish/base-process-publish-assortment.spec.js

@@ -9,6 +9,7 @@ const sdk_1 = require("@contrail/sdk");
 const type_conversion_utils_1 = require("../util/type-conversion-utils");
 const map_utils_1 = require("../util/map-utils");
 const item_family_changes_1 = require("../interfaces/item-family-changes");
+const flexplm_connect_1 = require("../util/flexplm-connect");
 let federatedId = '';
 jest.mock('../util/data-converter', () => {
     return {
@@ -31,6 +32,13 @@ jest.mock('../util/federation', () => {
 });
 let entityObject = {};
 let getOptionsObject = {};
+let createCallArg = undefined;
+let fileUploadCalls = [];
+let fileUploadResult = {
+    id: 'file-123',
+    downloadUrl: 'https://download.url',
+    adminDownloadUrl: 'https://admin.download.url'
+};
 jest.mock('@contrail/sdk', () => {
     return {
         Entities: class {
@@ -38,6 +46,18 @@ jest.mock('@contrail/sdk', () => {
                 getOptionsObject = _getOtionsObject;
                 return entityObject;
             }
+            create(arg) {
+                createCallArg = arg;
+                return Promise.resolve({});
+            }
+        },
+        Files: class {
+            createAndUploadFileFromBuffer(buffer, mimeType, fileName, _x, ttl) {
+                fileUploadCalls.push({ buffer, mimeType, fileName, ttl });
+                return Promise.resolve(fileUploadResult);
+            }
+        },
+        Request: class {
         }
     };
 });
@@ -1686,3 +1706,195 @@ describe('getEventsForItemFamilyChanges - conditional eventType', () => {
         expect(type_conversion_utils_1.TypeConversionUtils.isOutboundCreatableFromEntity).toHaveBeenNthCalledWith(2, undefined, mapFileUtil, colorProjectItem, { item: itemData, assortment });
     });
 });
+describe('sendToFlexPLM / handleVibeIQFile / sendPublishPayloadEvent', () => {
+    const config = {
+        taskId: 'task-abc',
+        event: '{"sourceEventId":"src-1"}'
+    };
+    const mapFileUtil = new transform_data_1.MapFileUtil(new sdk_1.Entities());
+    const dc = new data_converter_1.DataConverter(config, mapFileUtil);
+    const events = [{ objectClass: 'LCSProductSeasonLink' }];
+    const eventType = 'ASYNC_PUBLISH_SEASON';
+    beforeEach(() => {
+        createCallArg = undefined;
+        fileUploadCalls = [];
+        fileUploadResult = {
+            id: 'file-123',
+            downloadUrl: 'https://download.url',
+            adminDownloadUrl: 'https://admin.download.url'
+        };
+    });
+    afterEach(() => {
+        jest.restoreAllMocks();
+    });
+    it('should merge outboundPublishEvent into result and call sendPublishPayloadEvent in parallel', async () => {
+        const bppa = new base_process_publish_assortment_1.BaseProcessPublishAssortment(config, dc, mapFileUtil);
+        const flexResponse = { status: 200, data: { ok: true } };
+        let flexResolved = false;
+        let eventResolved = false;
+        const spyFlex = jest.spyOn(flexplm_connect_1.FlexPLMConnect.prototype, 'sendToFlexPLM')
+            .mockImplementation(async () => {
+            await new Promise(r => setTimeout(r, 5));
+            flexResolved = true;
+            return flexResponse;
+        });
+        const spyEvent = jest.spyOn(bppa, 'sendPublishPayloadEvent')
+            .mockImplementation(async () => {
+            await new Promise(r => setTimeout(r, 5));
+            eventResolved = true;
+        });
+        const result = await bppa.sendToFlexPLM(events, eventType);
+        expect(spyFlex).toHaveBeenCalledTimes(1);
+        expect(spyEvent).toHaveBeenCalledTimes(1);
+        expect(flexResolved).toBe(true);
+        expect(eventResolved).toBe(true);
+        const passedOutboundPublishEvent = spyFlex.mock.calls[0][0];
+        expect(passedOutboundPublishEvent.taskId).toBe('task-abc');
+        expect(passedOutboundPublishEvent.eventType).toBe(eventType);
+        expect(passedOutboundPublishEvent.objectClass).toBe('LCSSeason');
+        expect(passedOutboundPublishEvent.events).toBe(events);
+        expect(spyEvent).toHaveBeenCalledWith(passedOutboundPublishEvent);
+        expect(result).toEqual({ ...flexResponse, outboundPublishEvent: passedOutboundPublishEvent });
+    });
+    it('sendToFlexPLM throws when flexPLMConnect.sendToFlexPLM fails, attaching outboundPublishEvent and both results', async () => {
+        const bppa = new base_process_publish_assortment_1.BaseProcessPublishAssortment(config, dc, mapFileUtil);
+        const flexError = new Error('flex failed');
+        const eventResponse = { eventOk: true };
+        jest.spyOn(flexplm_connect_1.FlexPLMConnect.prototype, 'sendToFlexPLM').mockRejectedValue(flexError);
+        jest.spyOn(bppa, 'sendPublishPayloadEvent').mockResolvedValue(eventResponse);
+        await expect(bppa.sendToFlexPLM(events, eventType)).rejects.toMatchObject({
+            message: 'flex failed',
+            outboundPublishEvent: expect.objectContaining({ taskId: 'task-abc', eventType, objectClass: 'LCSSeason', events }),
+            sendToFlexPLMResult: { error: 'flex failed' },
+            sendPublishPayloadEventResult: eventResponse
+        });
+    });
+    it('sendToFlexPLM throws when sendPublishPayloadEvent fails, with flex result attached', async () => {
+        const bppa = new base_process_publish_assortment_1.BaseProcessPublishAssortment(config, dc, mapFileUtil);
+        const flexResponse = { status: 200 };
+        const eventError = new Error('event failed');
+        jest.spyOn(flexplm_connect_1.FlexPLMConnect.prototype, 'sendToFlexPLM').mockResolvedValue(flexResponse);
+        jest.spyOn(bppa, 'sendPublishPayloadEvent').mockRejectedValue(eventError);
+        await expect(bppa.sendToFlexPLM(events, eventType)).rejects.toMatchObject({
+            message: 'event failed',
+            outboundPublishEvent: expect.objectContaining({ taskId: 'task-abc', eventType }),
+            sendToFlexPLMResult: flexResponse,
+            sendPublishPayloadEventResult: { error: 'event failed' }
+        });
+    });
+    it('sendToFlexPLM throws the flexPLMConnect error when both fail', async () => {
+        const bppa = new base_process_publish_assortment_1.BaseProcessPublishAssortment(config, dc, mapFileUtil);
+        const flexError = new Error('flex failed');
+        const eventError = new Error('event failed');
+        jest.spyOn(flexplm_connect_1.FlexPLMConnect.prototype, 'sendToFlexPLM').mockRejectedValue(flexError);
+        jest.spyOn(bppa, 'sendPublishPayloadEvent').mockRejectedValue(eventError);
+        await expect(bppa.sendToFlexPLM(events, eventType)).rejects.toBe(flexError);
+        expect(flexError.outboundPublishEvent).toBeDefined();
+        expect(flexError.sendToFlexPLMResult).toEqual({ error: 'flex failed' });
+        expect(flexError.sendPublishPayloadEventResult).toEqual({ error: 'event failed' });
+    });
+    it('handleVibeIQFile (vibeiqfile) throws when flexPLMConnect.sendToFlexPLM fails, with both results attached', async () => {
+        const bppa = new base_process_publish_assortment_1.BaseProcessPublishAssortment(config, dc, mapFileUtil);
+        const flexError = new Error('flex failed');
+        const eventResponse = { eventOk: true };
+        jest.spyOn(flexplm_connect_1.FlexPLMConnect.prototype, 'sendToFlexPLM').mockRejectedValue(flexError);
+        jest.spyOn(bppa, 'sendPublishPayloadEvent').mockResolvedValue(eventResponse);
+        await expect(bppa.handleVibeIQFile(events, eventType, 'vibeiqfile')).rejects.toMatchObject({
+            message: 'flex failed',
+            outboundPublishEvent: expect.objectContaining({ eventsFileId: 'file-123' }),
+            sendToFlexPLMResult: { error: 'flex failed' },
+            sendPublishPayloadEventResult: eventResponse
+        });
+    });
+    it('handleVibeIQFile (vibeiqfile) throws when sendPublishPayloadEvent fails, with flex result attached', async () => {
+        const bppa = new base_process_publish_assortment_1.BaseProcessPublishAssortment(config, dc, mapFileUtil);
+        const flexResponse = { status: 200 };
+        const eventError = new Error('event failed');
+        jest.spyOn(flexplm_connect_1.FlexPLMConnect.prototype, 'sendToFlexPLM').mockResolvedValue(flexResponse);
+        jest.spyOn(bppa, 'sendPublishPayloadEvent').mockRejectedValue(eventError);
+        await expect(bppa.handleVibeIQFile(events, eventType, 'vibeiqfile')).rejects.toMatchObject({
+            message: 'event failed',
+            outboundPublishEvent: expect.objectContaining({ eventsFileId: 'file-123' }),
+            sendToFlexPLMResult: flexResponse,
+            sendPublishPayloadEventResult: { error: 'event failed' }
+        });
+    });
+    it('handleVibeIQFile (vibeiqfile) throws the flexPLMConnect error when both fail', async () => {
+        const bppa = new base_process_publish_assortment_1.BaseProcessPublishAssortment(config, dc, mapFileUtil);
+        const flexError = new Error('flex failed');
+        const eventError = new Error('event failed');
+        jest.spyOn(flexplm_connect_1.FlexPLMConnect.prototype, 'sendToFlexPLM').mockRejectedValue(flexError);
+        jest.spyOn(bppa, 'sendPublishPayloadEvent').mockRejectedValue(eventError);
+        await expect(bppa.handleVibeIQFile(events, eventType, 'vibeiqfile')).rejects.toBe(flexError);
+        expect(flexError.sendToFlexPLMResult).toEqual({ error: 'flex failed' });
+        expect(flexError.sendPublishPayloadEventResult).toEqual({ error: 'event failed' });
+    });
+    it('should merge outboundPublishEvent into FlexPLM result and call sendPublishPayloadEvent when mode is vibeiqfile', async () => {
+        const bppa = new base_process_publish_assortment_1.BaseProcessPublishAssortment(config, dc, mapFileUtil);
+        const flexResponse = { status: 200, data: { ok: true } };
+        const spyFlex = jest.spyOn(flexplm_connect_1.FlexPLMConnect.prototype, 'sendToFlexPLM')
+            .mockResolvedValue(flexResponse);
+        const spyEvent = jest.spyOn(bppa, 'sendPublishPayloadEvent')
+            .mockResolvedValue(undefined);
+        const result = await bppa.handleVibeIQFile(events, eventType, 'vibeiqfile');
+        expect(fileUploadCalls).toHaveLength(1);
+        expect(fileUploadCalls[0].fileName).toBe('ASYNC_PUBLISH_SEASON-events.json');
+        expect(fileUploadCalls[0].mimeType).toBe('application/json');
+        const passedOutboundPublishEvent = spyFlex.mock.calls[0][0];
+        expect(passedOutboundPublishEvent.taskId).toBe('task-abc');
+        expect(passedOutboundPublishEvent.eventType).toBe(eventType);
+        expect(passedOutboundPublishEvent.objectClass).toBe('LCSSeason');
+        expect(passedOutboundPublishEvent.eventsFileId).toBe('file-123');
+        expect(passedOutboundPublishEvent.eventsDownloadLink).toBe('https://download.url');
+        expect(passedOutboundPublishEvent.eventsAdminDownloadLink).toBe('https://admin.download.url');
+        expect(spyFlex).toHaveBeenCalledTimes(1);
+        expect(spyEvent).toHaveBeenCalledTimes(1);
+        expect(spyEvent).toHaveBeenCalledWith(passedOutboundPublishEvent);
+        expect(result).toEqual({ ...flexResponse, outboundPublishEvent: passedOutboundPublishEvent });
+    });
+    it('should skip FlexPLM but still call sendPublishPayloadEvent when mode is vibeiqfile-dontsendtoflexplm', async () => {
+        const bppa = new base_process_publish_assortment_1.BaseProcessPublishAssortment(config, dc, mapFileUtil);
+        const spyFlex = jest.spyOn(flexplm_connect_1.FlexPLMConnect.prototype, 'sendToFlexPLM')
+            .mockResolvedValue({});
+        const spyEvent = jest.spyOn(bppa, 'sendPublishPayloadEvent')
+            .mockResolvedValue(undefined);
+        const result = await bppa.handleVibeIQFile(events, eventType, 'vibeiqfile-dontsendtoflexplm');
+        expect(spyFlex).not.toHaveBeenCalled();
+        expect(spyEvent).toHaveBeenCalledTimes(1);
+        const passedOutboundPublishEvent = spyEvent.mock.calls[0][0];
+        expect(passedOutboundPublishEvent.eventsFileId).toBe('file-123');
+        expect(result).toEqual({
+            message: 'Successfully Uploaded File.',
+            outboundPublishEvent: passedOutboundPublishEvent
+        });
+    });
+    it('should create an external-event with initialEvent parsed from config', async () => {
+        const bppa = new base_process_publish_assortment_1.BaseProcessPublishAssortment(config, dc, mapFileUtil);
+        const outboundPublishEvent = { foo: 'bar' };
+        await bppa.sendPublishPayloadEvent(outboundPublishEvent);
+        expect(createCallArg).toEqual({
+            entityName: 'external-event',
+            object: {
+                originSystemType: 'VibeIQ',
+                objectClass: 'AssortmentPublishedToFlexPLM',
+                outboundPublishEvent,
+                initialEvent: { sourceEventId: 'src-1' }
+            }
+        });
+    });
+    it('should default initialEvent to {} when config has no event', async () => {
+        const bareConfig = { taskId: 'task-x' };
+        const bppa = new base_process_publish_assortment_1.BaseProcessPublishAssortment(bareConfig, dc, mapFileUtil);
+        const outboundPublishEvent = { hello: 'world' };
+        await bppa.sendPublishPayloadEvent(outboundPublishEvent);
+        expect(createCallArg).toEqual({
+            entityName: 'external-event',
+            object: {
+                originSystemType: 'VibeIQ',
+                objectClass: 'AssortmentPublishedToFlexPLM',
+                outboundPublishEvent,
+                initialEvent: {}
+            }
+        });
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrail/flexplm",
-  "version": "1.6.0-alpha.6f15d4e",
+  "version": "1.6.0-alpha.8e73fa3",
   "description": "Library used for integration with flexplm.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -12,7 +12,8 @@
     "scripts/copy-template.js"
   ],
   "scripts": {
-    "build": "tsc && node scripts/copy-template.js",
+    "build": "tsc; node scripts/copy-template.js",
+    "build:win": "tsc && node scripts/copy-template.js",
     "format": "prettier --write \"src/**/*.ts\" \"src/**/*.js\"",
     "lint": "tslint -p tsconfig.json",
     "test": "jest",