hexasync-cli-nodejs

TL;DR

https://github.com/hexasync-saas/hexasync-cli-nodejs/assets/103476940/4dde436b-6c83-4c32-9264-8c2cb653a4f7

Example Template Code

• https://github.com/hexasync-saas/templates/tree/hexasync-demos/demos/ecwid/standalone
• https://github.com/hexasync-saas/templates/tree/hexasync-demos/demos/tiktokshop-V2/ecwid

Installation

npm run build-and-install

Setup

hexasync-cli-nodejs -sc
? Please enter the value: <File path to your config "hexasync-cli.yaml">

hexasync-cli-nodejs -soot
? Please enter the value: <File path to your repository "official-templates" you have cloned>

Compose

cd <Template folder>
hexasync-cli-nodejs -c ./partials

Commands

Compose

demos/
└── ecwid/
    └── standalone/
        ├── partials
        ├── local.env
        └── output.yaml

cd demos/ecwid/standalone
hexasync-cli-nodejs -c ./partials

Set "hexasync-cli.yaml" config file path

/config/
├── .zshrc
├── .nvm
├── hexasync-cli.yaml
├── .npmrc
└── ...

hexasync-cli-nodejs -sc /config/hexasync-cli.yaml

Set "official-templates" repository file path

/config/
└── CODE/
    ├── hso.dashboard
    ├── templates
    ├── official-templates
    ├── profiles.api
    └── ...

hexasync-cli-nodejs -soot /config/CODE/official-templates

How to using merge code feature?

See use cases in these code

• https://github.com/hexasync-saas/templates/tree/hexasync-demos/demos/ecwid/standalone
• https://github.com/hexasync-saas/templates/tree/hexasync-demos/demos/tiktokshop-V2/ecwid

Template Directives supported by Composer

• Beside properties of ProfileDefinition, there are directives defined by the Composer for serving features.
• These directives is used in compose-time only, not included in the final code

usings

• Define using which code in official-templates

# template: demos/tiktokshop-V2/ecwid/partials/usings.yaml

usings:
  - key: tiktokshop-V2
    type: OFFLINE
    metadata:
      type: FOLDER
      path: /tiktokshop-V2/partials
      filePathFilterPattern:
        flags: i
        exclude: (StockDataPusher|Utility|Delete|UpdateDeliveredPusher)
  - key: ecwid
    type: OFFLINE
    metadata:
      type: FOLDER
      path: /ecwid/partials
      filePathFilterPattern:
        flags: i
        exclude: (Stock|OrderStatus)
  - key: generic
    type: OFFLINE
    metadata:
      type: FOLDER
      path: /generic/partials
  - key: hexasync
    type: OFFLINE
    metadata:
      type: FOLDER
      path: /hexasync/partials

variables

• Supported define variables locally inside any files, no need of global preserved variables.yaml files. These code will be hoisted in compose-time

# templates: demos/tiktokshop-V2/ecwid/partials/components/compositions/transformations/Order/SalesOrder/SalesOrderTrackingInformationEcwidToTikTokShopTransformation.yaml

variables:
  '**SalesOrderTrackingInformationEcwidToTikTokShopTransformationObjectId**': '236eab02-5358-4720-a2b2-a0467d8b7ff8'

objectAssociations:
  '**EcwidOrderTrackingInformationDataObjectId**':
    pusher:
      id: '**TikTokShopShipPackagePusherId**' # Defined in `official-templates: tiktokshop-V2/partials/tasks/variables/common/Order/SalesOrder.yaml`

startupTasks:
  - key: ENABLE_ORDER_TRACKING_INFORMATION_SYNC_ECWID_TO_TIKTOKSHOP
    targetType: SCHEDULER
    targetId: '**EcwidOrderTrackingInformationDataObjectId**'
    metadata:
      scheduler_expression: '0/15 * * ? * * *'
      is_enabled: true
      is_running: true

validators

• Same concept as validations in ProfileDefinition. But the syntax provide way to refactor
• In final code, will be composed to validations

# templates: demos/tiktokshop-V2/ecwid/partials/components/compositions/transformations/Product/ProductEcwidToTikTokShopTransformation.yaml

variables:
  '**EcwidProductDataValidatorId**': '9729074e-de61-4e80-8a9f-0c3f9bca5dd1'

validators:
  - id: '**EcwidProductDataValidatorId**'
    usings:
      # Defined in `official-templates`, not `templates`, because `TikTokShopActiveProductDataPusher` require Product data to satisfy the same validations
      # Below define `columns` for mapping the correct name defined in TikTokShop validator to be Ecwid property name
      # See the `official-templates` code below
      - '**TikTokShopActiveProductDataPusherValidatorId**'
    columns:
      - id: 4bbfcb53-e172-4426-b3cb-5627ebb323b0
        metadata:
          field_name: sku
      - id: 0cb420ec-b14e-4cdb-8e1d-3dd0e89dd398
        metadata:
          field_name: name
    # ... and more ...

objectAssociations:
  '**EcwidProductDataObjectId**':
    pusher:
      id: '**TikTokShopActiveProductDataPusherId**'
    validator:
      id: '**EcwidProductDataValidatorId**'

# official-templates: tiktokshop-V2/partials/pushers/Product/TikTokShopActiveProductDataPusher.yaml

validators:
  - id: '**TikTokShopActiveProductDataPusherValidatorId**'
    columns:
      - id: 4bbfcb53-e172-4426-b3cb-5627ebb323b0
        type: NOT_EMPTY
        metadata:
          field_name: seller_sku
      - id: 0cb420ec-b14e-4cdb-8e1d-3dd0e89dd398
        type: MIN_LENGTH
        metadata:
          field_name: product_name
          value: '25'
    # ... and more ...

# template output: demos/tiktokshop-V2/ecwid/output.yaml

validations:
  4e857bc8-78ed-4e17-aebd-fab5fedebae2:
    - id: 4bbfcb53-e172-4426-b3cb-5627ebb323b0
      type: NOT_EMPTY
      metadata:
        field_name: sku
      index: 0
    - id: 0cb420ec-b14e-4cdb-8e1d-3dd0e89dd398
      type: MIN_LENGTH
      metadata:
        field_name: name
        value: '25'

customs

• Use to create custom component from existing ProfileDefinition property and Composer directives (HOC pattern)
• FEATURE IS IN DEVELOPMENT...

Common Errors & Guidance

YAMLParseError: Map keys must be unique at line 97, column 1

1. Check if any key, id, GUID defined is duplicated. Common case is declare PullerId/ObjectId/PusherId copy/paste but forgot to generate random UUID
2. Check if in a single file, declare duplicate fields, i.e: objects, pullers, ...

objects:
  - id: "**EcwidProductDataObjectId**"
    ignoreRemoval: true
    dependencies:
      IMAGE:
        dependedOn: "**ProductImageEcwidToTikTokShopTransformationObjectId**"
        type: KEYS
        data:
          nullable: false
          constraints:
            - synced
          keys:
            product_id: product_id


objects:
  - id: "**ProductEcwidToTikTokShopTransformationObjectId**"
    valueTableName: "**ProductEcwidToTikTokShopTransformationObjectTableName**"
    name: "**ProductEcwidToTikTokShopTransformationObjectName**"
    ignoreRemoval: true

TypeError: Cannot read properties of undefined (reading 'filter')

Check if current folder contain reserved folder partials

For Developers

Debugging

npm run debugger:sample-template # Using `mocks/sample-template`
npm run debugger:real-template # Path to specific `templates` folder

Merge mechanism based entirely on id/key of Array/Object

• For key, user has inputed into
• For id, DO NOT CODE IN COMPOSER TO AUTOGENERATE uuid FOR IT.

Checking if a key exists in a JavaScript object

https://stackoverflow.com/questions/1098040/checking-if-a-key-exists-in-a-javascript-object

• Always use obj.hasOwnProperty("key") +) 95.52% performance --> Not fastest but acceptable +) Clarible syntax

• This syntax is check empty value, not meaning check if key exists: obj[key]. Also, this syntax is not clarible

Useful Breakpoints

DeepMergeHelper.ts > if (typeof sourceElem !== "object")

sourceElem?.id == '**EcwidProductDataPullerId**'

compose.ts > _convertTemplateToProfile()

key === "<template/profile key name>"

CLI Design

Primary

https://blog.logrocket.com/building-typescript-cli-node-js-commander/

Secondary

• https://blog.logrocket.com/creating-a-cli-tool-with-node-js/

Currently choose "Caught Exceptions"/"Uncaught Exceptions" before run the script will cause debugger to be hang

Bugs

Chalk.js version 5 ESM

• https://stackoverflow.com/questions/70309135/chalk-error-err-require-esm-require-of-es-module

Useful command

Script execute & read

chmod u+r+x <script_file_name>.sh

{ "username": "[email protected]", "password": "8F%!2pKNGGfsyPa3s7!6TkE^@6CQ$KZ7*CL&DtiHibbr485rWd7ZUXN8uC$TMqJ", "clientId": "a50554b3-1e9b-44e6-b349-88f35a9871de", "clientSecret": "365adf1f-6df8-41c8-b540-ad1c8b9baac4" "redirectUri": "http://localhost:5000" }