unomi-sdk-node/README.md

Node module to interact with unomi.

# unomi-sdk-node

Node module to interact with unomi.

:::info
The uuid values used in these examples are not actual values.
:::

## Build

1. Open the folder
``` bash
cd unomi-sdk-node/
```
2. Install dependencies
``` bash
npm install
```
3. Build the module
``` bash
npm run build
```

## Connect to unomi
There are two ways to connect to unomi.

You can connect to **unomi** using the `connect` function with basic authentication:

``` javascript
import { connect } from "../node_modules/unomi-sdk-node";

const baseUrlUnomi = "https://unomi.example.com";
const baseUrlElasticsearch = "https://elasticsearch.example.com";
const username = "cdp_unomi";
const password = "F0RauuYEbz4GUwUG";

const unomisdk = connect({
    urlUnomi: baseUrlUnomi,
    urlElasticsearch: baseUrlElasticsearch,
    auth: {
        username: username,
        password: password
    }
});
```

You can also connect to **unomi** using the `connect` function with OAuth:

``` javascript
import { connect } from "../node_modules/unomi-sdk-node";

const baseUrlUnomi = "https://unomi.example.com";
const baseUrlElasticsearch = "https://elasticsearch.example.com";
const bearerToken = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c";

const unomisdk = connect({
    urlUnomi: baseUrlUnomi,
    urlElasticsearch: baseUrlElasticsearch,
    auth: {
        bearerToken: bearerToken
    }
});
```

## Functions

### Profile

#### get
Get a profile.

##### Usage
``` javascript
const profileId = <string>;

unomisdk.profile.get(profileId);
```

##### Response
``` jsonc
// success
{
    statusCode: 200,
    responseData: <object>
}

// no success
{
    statusCode: <int>,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <null>,
    response: <object>
}

// exception in module
{
    statusCode: 500,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <string>,
    response: {
        method: <string>,
        url: <string>,
        body: <object | null>,
        successStatus: <int>
    }
}
```

##### Real World Example
``` javascript
const profileId = "7461c378-c216-4697-9244-4be7257bc75c";

const profile = unomisdk.profile.get(profileId);

profile.then(data => {

    console.log(data);
    
}).catch(err => {

    console.log(err);
    
});
```

#### allUsedProperties
Get all properties that are used in profiles.

##### Usage
``` javascript
unomisdk.profile.allUsedProperties();
```

##### Response
``` jsonc
// success
{
    statusCode: 200,
    responseData: <object>
}

// no success
{
    statusCode: <int>,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <null>,
    response: <object>
}

// exception in module
{
    statusCode: 500,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <string>,
    response: {
        method: <string>,
        url: <string>,
        body: <object | null>,
        successStatus: <int>
    }
}
```

##### Real World Example
``` javascript
const properties = unomisdk.profile.allUsedProperties();

properties.then(data => {

    console.log(data);
    
}).catch(err => {

    console.log(err);
    
});
```


#### count
Get the amount of profiles currently in Unomi.

##### Usage
``` javascript
unomisdk.profile.count();
```

##### Response
``` jsonc
// success
{
    statusCode: 200,
    responseData: <int>
}

// no success
{
    statusCode: <int>,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <null>,
    response: <object>
}

// exception in module
{
    statusCode: 500,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <string>,
    response: {
        method: <string>,
        url: <string>,
        body: <object | null>,
        successStatus: <int>
    }
}
```

##### Real World Example
``` javascript
const count = unomisdk.profile.count();

count.then(data => {

    console.log(data);

}).catch(err => {

    console.log(err);

});
```

### Rule

#### getAll
Get all rules.

##### Usage
``` javascript
unomisdk.rule.getAll();
```

##### Response
``` jsonc
// success
{
    statusCode: 200,
    responseData: <object>
}

// no success
{
    statusCode: <int>,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <null>,
    response: <object>
}

// exception in module
{
    statusCode: 500,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <string>,
    response: {
        method: <string>,
        url: <string>,
        body: <object | null>,
        successStatus: <int>
    }
}
```

##### Real World Example
``` javascript
const rules = unomisdk.rule.getAll();

rules.then(data => {

    console.log(data);
    
}).catch(err => {

    console.log(err);
    
});
```

#### get
Get a rule.

##### Usage
``` javascript
const ruleId = <string>;

unomisdk.rule.get(ruleId);
```

##### Response
``` jsonc
// success
{
    statusCode: 200,
    responseData: <object>
}

// no success
{
    statusCode: <int>,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <null>,
    response: <object>
}

// exception in module
{
    statusCode: 500,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <string>,
    response: {
        method: <string>,
        url: <string>,
        body: <object | null>,
        successStatus: <int>
    }
}
```

##### Real World Example
``` javascript
const ruleId = "ccf46960-f50f-4c63-96ea-d27530262f10";

const rule = unomisdk.rule.get(ruleId);

rule.then(data => {

    console.log(data);
    
}).catch(err => {

    console.log(err);
    
});
```

#### create
Create a rule.

##### Usage
``` javascript
const params = {
    metadata: {
        id: <string>,
        name: <string>,
        description: <string>
    },
    raiseEventOnlyOnceForSession: <boolean>,
    condition: {
        type: <string>,
        parameterValues: {
            operator : <string>,
            parameterValues: {
                eventTypeId: <string>
            }
        }
    },
    actions: [
        {
            type: <string>,
            parameterValues: {
                setPropertyName: <string>
                setPropertyValue: <string>
                setPropertyStrategy: <string>
            }
        }
    ]
};

unomisdk.rule.create(params);
```

##### Response
``` jsonc
// success
{
    statusCode: 204,
    responseData: <object>
}

// no success
{
    statusCode: <int>,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <null>,
    response: <object>
}

// exception in module
{
    statusCode: 500,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <string>,
    response: {
        method: <string>,
        url: <string>,
        body: <object | null>,
        successStatus: <int>
    }
}
```

##### Real World Example
``` javascript
const params = {
    metadata: {
        id: "setContactInfo",
        name: "Copy the received contact info to the current profile",
        description: "Copies the contact info received in a custom event called 'contactInfoSubmitted' to the current profile"
    },
    raiseEventOnlyOnceForSession: false,
    condition: {
        type: "eventTypeCondition",
        parameterValues: {
            eventTypeId: "contactInfoSubmitted"
        }
    },
    actions: [
        {
            type: "setPropertyAction",
            parameterValues: {
                setPropertyName: "properties(firstName)",
                setPropertyValue: "eventProperty::properties(firstName)",
                setPropertyStrategy: "alwaysSet"
            }
        },
        {
            type: "setPropertyAction",
            parameterValues: {
                setPropertyName: "properties(lastName)",
                setPropertyValue: "eventProperty::properties(lastName)",
                setPropertyStrategy: "alwaysSet"
            }
        },
        {
            type: "setPropertyAction",
            parameterValues: {
                setPropertyName: "properties(email)",
                setPropertyValue: "eventProperty::properties(email)",
                setPropertyStrategy: "alwaysSet"
            }
        }
    ]
};

const rule = unomisdk.rule.create(params);

rule.then(data => {

    console.log(data);
    
}).catch(err => {

    console.log(err);
    
});
```

### Segment

#### getAll
Get all segments.

##### Usage
``` javascript
const sortOrder = <string>;
const limit = <int>;
const offset = <int>;

unomisdk.segment.getAll(sortOrder, limit, offset);
```

##### Response
``` jsonc
// success
{
    statusCode: 200,
    responseData: <object>
}

// no success
{
    statusCode: <int>,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <null>,
    response: <object>
}

// exception in module
{
    statusCode: 500,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <string>,
    response: {
        method: <string>,
        url: <string>,
        body: <object | null>,
        successStatus: <int>
    }
}
```

##### Real World Example
``` javascript
const sortOrder = "asc";
const limit = 10;
const offset = 0;

const segments = unomisdk.segment.getAll(sortOrder, limit, offset);

segments.then(data => {

    console.log(data);
    
}).catch(err => {

    console.log(err);
    
});
```

#### get
Get a segment.

##### Usage
``` javascript
const segmentId = <string>;

unomisdk.segment.get(segmentId);
```

##### Response
``` jsonc
// success
{
    statusCode: 200,
    responseData: <object>
}

// no success
{
    statusCode: <int>,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <null>,
    response: <object>
}

// exception in module
{
    statusCode: 500,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <string>,
    response: {
        method: <string>,
        url: <string>,
        body: <object | null>,
        successStatus: <int>
    }
}
```

##### Real World Example
``` javascript
const segmentId = "63d58612-51ed-479a-adaf-7258ea4c17a8";

const segment = unomisdk.segment.get(segmentId);

segment.then(data => {

    console.log(data);
    
}).catch(err => {

    console.log(err);
    
});
```

##### Note
The object in `responseData` will have the following structure:

``` javascript
const segment = {
    name: <string>,
    description: <string>,
    scope: <string>,
    tags: <string[]>,
    systemTags: <string[]>,
    operator: <string>,
    subConditions: [
        {
            propertyName:? <string>,
            comparisonOperator?: <string>,
            propertyValue?: <string | int | string[] | int[] | null>,
            matchType?: <string>,
            segments?: Array<string>,
            conditionType: <string>
        }
    ]
};
```

The conditionType of the subCondition will determine which properties the subCondition will have:
* profilePropertyCondition:
    * propertyName
    * comparisonOperator
    * propertyValue
* profileSegmentCondition:
    * matchType
    * segments

#### create
Create a segment.

##### note
This sdk also supports relative dates in unomi segment subConditions.

The prefix "dateExpr::" needs to be added to the propertyValue value when a date expression needs to be used. This prefix is necessary due to how validation works in this sdk. Otherwise the sdk would not know the difference between "now" in the context of text and "now" in the context of dates. This prefix is removed before sending the validated segment to unomi.

Here is an example for profiles whose "da__created" profile property is newer than 5 days ago:

```
subConditions: [
    {
        propertyName: "capture_properties.da__created",
        comparisonOperator: "greaterThan",
        propertyValue: "dateExpr::now-5d",
        conditionType: "profilePropertyCondition"
    }
]
```

The conditionType you use will determine which properties you have to use:
* profilePropertyCondition:
    * propertyName
    * comparisonOperator
    * propertyValue
* profileSegmentCondition:
    * matchType
    * segments

Nested subconditions don't work in this endpoint. Subconditions can only go one layer deep.

##### Usage
``` javascript
const params = {
    name: <string>,
    description: <string>,
    scope: <string>,
    tags: <string[]>,
    systemTags: <string[]>,
    operator: <string>,
    subConditions: [
        {
            propertyName?: <string>,
            comparisonOperator?: <string>,
            propertyValue?: <string | int | boolean | string[] | int[] | null>,
            matchType?: <string>,
            segments?: Array<string>,
            conditionType: <string>
        }
    ]
}

unomisdk.segment.create(params);
```

##### Response
``` jsonc
// success
{
    statusCode: 204,
    responseData: <object>
}

// no success
{
    statusCode: <int>,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <null>,
    response: <object>
}

// exception in module
{
    statusCode: 500,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <string>,
    response: {
        method: <string>,
        url: <string>,
        body: <object | null>,
        successStatus: <int>
    }
}
```

##### Real World Example
``` javascript
const params = {
    name: "Marketeer",
    description: "Lorem ipsum dolor sit amet ...",
    scope: "459e18cb-348f-466f-811a-fdc4a296592f",
    tags: ["tech", "work", "manage"],
    systemTags: ["manual"],
    operator: "or",
    subConditions: [
        {
            propertyName: "classificationUuid",
            comparisonOperator: "equals",
            propertyValue: "3bb3e3b0-4285-11ea-aaef-0800200c9a66",
            conditionType: "profilePropertyCondition"
        },
        {
            propertyName: "nbOfVisits",
            comparisonOperator: "between",
            propertyValue: [10, 30],
            conditionType: "profilePropertyCondition"
        },
        {
            matchType: "in",
            segments: ["1d600a47-12a7-4ac7-8797-645ebb07341d"],
            conditionType: "profileSegmentCondition"
        }
    ]
};

const segment = unomisdk.segment.create(params);

segment.then(data => {

    console.log(data);
    
}).catch(err => {

    console.log(err);
    
});
```

#### update
Update a segment.

##### note
This sdk also supports relative dates in unomi segment subConditions.

The prefix "dateExpr::" needs to be added to the propertyValue value when a date expression needs to be used. This prefix is necessary due to how validation works in this sdk. Otherwise the sdk would not know the difference between "now" in the context of text and "now" in the context of dates. This prefix is removed before sending the validated segment to unomi.

Here is an example for profiles whose "da__created" profile property is newer than 5 days ago:

```
subConditions: [
    {
        propertyName: "capture_properties.da__created",
        comparisonOperator: "greaterThan",
        propertyValue: "dateExpr::now-5d",
        conditionType: "profilePropertyCondition"
    }
]
```

The conditionType you use will determine which properties you have to use:
* profilePropertyCondition:
    * propertyName
    * comparisonOperator
    * propertyValue
* profileSegmentCondition:
    * matchType
    * segments

Nested subconditions don't work in this endpoint. Subconditions can only go one layer deep.

##### Usage
``` javascript
const params = {
    id: <string>,
    name: <string>,
    description: <string>,
    scope: <string>,
    tags: <string[]>,
    systemTags: <string[]>,
    operator: <string>,
    subConditions: [
        {
            propertyName?: <string>,
            comparisonOperator?: <string>,
            propertyValue?: <string | int | boolean | string[] | int[] | null>,
            matchType?: <string>,
            segments?: Array<string>,
            conditionType: <string>

        }
    ]
}

unomisdk.segment.update(params);
```

##### Response
``` jsonc
// success
{
    statusCode: 204,
    responseData: <object>
}

// no success
{
    statusCode: <int>,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <null>,
    response: <object>
}

// exception in module
{
    statusCode: 500,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <string>,
    response: {
        method: <string>,
        url: <string>,
        body: <object | null>,
        successStatus: <int>
    }
}
```

##### Real World Example
``` javascript
const params = {
    id: "63d58612-51ed-479a-adaf-7258ea4c17a8",
    name: "Marketeer",
    description: "Lorem ipsum dolor sit amet ...",
    scope: "459e18cb-348f-466f-811a-fdc4a296592f",
    tags: ["tech", "work", "manage", "umami"],
    systemTags: ["manual"],
    operator: "or",
    subConditions: [
        {
            propertyName: "classificationUuid",
            comparisonOperator: "equals",
            propertyValue: "3bb3e3b0-4285-11ea-aaef-0800200c9a66",
            conditionType: "profilePropertyCondition"
        },
        {
            propertyName: "nbOfVisits",
            comparisonOperator: "between",
            propertyValue: [10, 30],
            conditionType: "profilePropertyCondition"
        },
        {
            propertyName: "firstVisit",
            comparisonOperator: "greaterThanOrEqualTo",
            propertyValue: "2020-04-20",
            conditionType: "profilePropertyCondition"
        },
        {
            matchType: "in",
            segments: ["1d600a47-12a7-4ac7-8797-645ebb07341d"],
            conditionType: "profileSegmentCondition"
        }
    ]
};

const segment = unomisdk.segment.update(params);

segment.then(data => {

    console.log(data);
    
}).catch(err => {

    console.log(err);
    
});
```

#### delete
Delete a segment.

##### Usage
``` javascript
const segmentId = <string>;

unomisdk.segment.delete(segmentId);
```

##### Response
``` jsonc
// success
{
    statusCode: 200,
    responseData: <object>
}

// no success
{
    statusCode: <int>,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <null>,
    response: <object>
}

// exception in module
{
    statusCode: 500,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <string>,
    response: {
        method: <string>,
        url: <string>,
        body: <object | null>,
        successStatus: <int>
    }
}
```

##### Real World Example
``` javascript
const segmentId = "63d58612-51ed-479a-adaf-7258ea4c17a8";

const segment = unomisdk.segment.delete(segmentId);

segment.then(data => {

    console.log(data);
    
}).catch(err => {

    console.log(err);
    
});
```

#### profileCount
Get the amount of profiles in a specified segment or array of segments.

##### Usage
``` javascript
const params = {
    segments: <string[]>,
    operator: <string>
}

unomisdk.segment.profileCount(params);
```

##### Response
``` jsonc
// success
{
    statusCode: 200,
    responseData: <string>
}

// no success
{
    statusCode: <int>,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <null>,
    response: <object>
}

// exception in module
{
    statusCode: 500,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <string>,
    response: {
        method: <string>,
        url: <string>,
        body: <object | null>,
        successStatus: <int>
    }
}
```

##### Real World Example
``` javascript
const params = {
    segments: ["c91a600f-df5c-4c16-b8f8-f0c036f7b09a", "bbbdef55-bbac-4e76-a7b7-86a5fbd57161"],
    operator: "and"
}

const profileCount = unomisdk.segment.profileCount(params);

profileCount.then(data => {

    console.log(data);

}).catch(err => {

    console.log(err);

});
```

### ComparisonOperator

#### getAll
Get all comparisonOperators.

##### Documentation
Link to documentation: https://hackmd.io/qbR7MYX6SxutO4Jespn1QA

:::info
The object structure you see in the documentation is what actually gets sent to unomi. When you use this module, the object **you** send is what you see in the example of the segment create and update function.
:::

##### Usage
``` javascript
unomisdk.comparisonOperator.getAll();
```

##### Response
``` jsonc
// success
{
    statusCode: 200,
    responseData: <object>
}

// no success
{
    statusCode: <int>,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <null>,
    response: <object>
}

// exception in module
{
    statusCode: 500,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <string>,
    response: {
        method: <string>,
        url: <string>,
        body: <object | null>,
        successStatus: <int>
    }
}
```

##### Real World Example
``` javascript
const comparisonOperators = unomisdk.comparisonOperator.getAll();

comparisonOperators.then(data => {

    console.log(data);
    
}).catch(err => {

    console.log(err);
    
});
```


### MatchType

#### getAll
Get all matchTypes.
(These are used for profileSegmentConditions.)

##### Documentation
Link to documentation: https://hackmd.io/qbR7MYX6SxutO4Jespn1QA

:::info
The object structure you see in the documentation is what actually gets sent to unomi. When you use this module, the object **you** send is what you see in the example of the segment create and update function.
:::

##### Usage
``` javascript
unomisdk.matchType.getAll();
```

##### Response
``` jsonc
// success
{
    statusCode: 200,
    responseData: <object>
}

// no success
{
    statusCode: <int>,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <null>,
    response: <object>
}

// exception in module
{
    statusCode: 500,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <string>,
    response: {
        method: <string>,
        url: <string>,
        body: <object | null>,
        successStatus: <int>
    }
}
```

##### Real World Example
``` javascript
const matchTypes = unomisdk.matchType.getAll();

matchTypes.then(data => {

    console.log(data);
    
}).catch(err => {

    console.log(err);
    
});
```

### DateExpression

#### isValid
Validate a given date expression.  
Returns a true or false.  
true if the date expression is a valid date expression.  
false if the date expression is not a valid date expression.

You can find some supported formats in comments in the code in the following file: "src/utils/validation.ts" at the "isValidDateExpression" function.

##### Note
More about date expressions can be found in the elasticsearch documentation: https://www.elastic.co/guide/en/elasticsearch/reference/7.x/common-options.html#date-math

##### Usage
``` javascript
const dateExpr = <string>

unomisdk.dateExpression.isValid(dateExpr);
```

##### Response
``` jsonc
// valid date expression
true

// invalid date expression
false
```

##### Real World Example
``` javascript
const dateExpr = "now+1y/y"

const isValidDateExpr = unomisdk.dateExpression.isValid(dateExpr);
```