# Mixgather

![NPM](https://img.shields.io/npm/l/mixgather)
![NPM](https://img.shields.io/npm/v/mixgather)
![GitHub Workflow Status](https://github.com/rct-ai/mixgather/actions/workflows/release.yml/badge.svg?branch=main)

"I am a product log maker, so I write logs day by day."

## Installation
```
$ yarn add mixgather
```

## Usage

### 1. Init - Required
``` typescript
import mixgather from 'mixgather'

async inSomeSetupHook() {
  // ...other setup
  await mixgather.init({
    debug: process.env.NODE_ENV !== 'production',
    google: {
      id: 'G-XXXX'
    },
    mixpanel: {
      token: 'xxxxxx'
    }
  })
  // ...integrate track with router hooks
}

```

The init step is async, we should track after finishing it.

### 2. Track - Core
``` typescript
// Pages
mixgather.page('/path')
mixgather.page('/profile', 'User Home')

// Events
mixgather.event('some_action')
mixgather.event('el_clicked', {
  property: 'value'
})

// Screens
mixgather.screen('screen_name')
mixgather.screen('modal_name')
```

### 3. User - Optional
Set the `userMeta` on the gathers:

``` typescript
mixgather.setUser({ id: 'xxxxx', ...otherProps })
```

if id is `null`, will remove the current user.

### 4. Global Property - Optional

``` typescript
mixgather.setProperty({ appName: 'xxxxx', ...others })
```

if property value is `null`, will remove the property.

### Get Vendors

Sometimes, we need to run vendor-spec APIs, getting $vendor sdk is necessary.

``` typescript
const gatherName = 'mixpanel' // 'google'
mixgather.getGather(gatherName).$vendor
```

## Development

### Run Example in Local

```
$ yarn dev
```

It starts a server at http://localhost:1234.

### Reset Package Name

1. `git clone git@github.com:rct-ai/mixgather.git`
2. `cd mixgather`
3. `yarn`
4. `yarn setup`

### Node.js, npm and/or yarn version

The lib relies on [volta](https://volta.sh/) to ensure node version to be consistent across developers. It's also used in the GitHub workflow file.

### Typescript

Leverages [esbuild](https://github.com/evanw/esbuild) for blazing fast builds, but keeps `tsc` to generate `.d.ts` files.
Generates two builds to support both ESM and CJS.

Commands:

- `build`: runs typechecking then generates CJS, ESM and `d.ts` files in the `build/` directory
- `clean`: removes the `build/` directory
- `type:dts`: only generates `d.ts`
- `type:check`: only run typechecking
- `type:build`: only generates CJS and ESM

### Tests

Mixgather uses [ava](https://github.com/avajs/ava) and [esbuild-register](https://github.com/egoist/esbuild-register) so that there is no need to compile before the tests start running. The coverage is done through [nyc](https://github.com/istanbuljs/nyc).

Commands:

- `test`: runs ava test runner
- `test:coverage`: runs ava test runner and generates coverage reports

### Format & lint

This template relies on the combination of [eslint](https://github.com/eslint/eslint) — through [typescript-eslint](https://github.com/typescript-eslint/typescript-eslint) for linting and [prettier](https://github.com/prettier/prettier) for formatting.
It also uses [cspell](https://github.com/streetsidesoftware/cspell) to ensure spelling

Commands:

- `format`: runs prettier with automatic fixing
- `format:check`: runs prettier without automatic fixing (used in CI)
- `lint`: runs eslint with automatic fixing
- `lint:check`: runs eslint without automatic fixing (used in CI)
- `spell:check`: runs spellchecking

### Releasing

Under the hood, this library uses [semantic-release](https://github.com/semantic-release/semantic-release) and [commitizen](https://github.com/commitizen/cz-cli).
The goal is to avoid manual release process. Using `semantic-release` will automatically create a github release (hence tags) as well as an npm release.
Based on your commit history, `semantic-release` will automatically create a patch, feature or breaking release.

Commands:

- `cz`: interactive CLI that helps you generate a proper git commit message, using [commitizen](https://github.com/commitizen/cz-cli)
- `semantic-release`: triggers a release (used in CI)