npm package: @segment/prism
Description: A templating engine for generating strongly typed analytics clients across languages using the schema defined by a Tracking Plan ## Install
Author: segment
Latest version: 0.1.9

# prism

A templating engine for generating strongly typed analytics clients across languages using the schema defined by a Tracking Plan
## Install

Yarn
```
yarn global add @segment/prism
```
npm
```
npm install @segment/prism -g
```

## Run

The following will generate a client api based on the Tracking Plan with id `rs_15cyAM8Ce7hudhJ2dH50xIkywoe` at the the path defined by `outputPath`

```
prism gen-js \ 
  --id rs_15cyAM8Ce7hudhJ2dH50xIkywoe \
  --token [your_token] \
  --outputPath .
```

An API token can be obtained by navigating to the `API Keys` page for a workspace containing the Tracking Plan you intend to generate a client for:

https://app.segment.com/{your_workspace_name}/settings/api-keys

![API Keys](/api-keys.png)




To run this tool against a local Tracking Plan file, run the following command (see the file referenced by the `--inputPath` switch as an example of the format that's expected):
```
prism gen-ts \
  --inputPath src/lib/__tests__/trackingPlanFixture.json \
  --outputPath .
```
To get a description of each of the provided arguments for this command, run `prism gen-ts --help`

```
Options:
  --help        Show help                                              [boolean]
  --version     Show version number                                    [boolean]
  --id          The resource id for a Tracking Plan                     [string]
  --token       The auth token for a user                               [string]
  --outputPath  The output path for the files                           [string]
  --inputPath   The path to a local tracking plan file                  [string]
  ```


To get a list of available language targets, run `prism --help`

```
Commands:
  gen-android  Generate a strongly typed Android client from a Tracking Plan
  gen-js       Generate an analytics.js wrapper from a Tracking Plan
  gen-ts       Generate a typescript type definitions from a Tracking Plan

Options:
  --help     Show help                                                 [boolean]
  --version  Show version number                                       [boolean]
```

## Build and run locally [WIP]
From within this project directory:
```
npm install
npm run build

# The build library is now available in ./dist 

node ./dist/index.js gen-js \ 
  --id rs_15cyAM8Ce7hudhJ2dH50xIkywoe \
  --token [your_token] \
  --outputPath .
```

## Add New Language Targets

*(TODO - extend this section)*



1) Create a `gen-{your-lang-here}.ts` file in `src/commands` (see existing commands for examples to work from)

2) Export the variables `command` (the name of the command), `desc` (its description), `builder` (an object that captures the parameters your command takes -- in the majority of cases you can just re-export `builder` in `src/lib/index.ts`) and `handler` -- covered below

3) The `handler` export is the function that accepts an array of Tracking Plan events and a reference to an `api` instance -- (note the handler must be wrapped by the `getTypeTrackHandler()` function) here you can extract type information and other metadata from the events and use it to format a data payload that can be provided to the `api` instance's `render()` method

```typescript
/*
 * gen-go.ts
 */

export const handler = getTypedTrackHandler((events, api) => {
  
  const structs = transformEventsIntoGoStructs(events)
  
  return api.render('analytics', 'go', {
    structs
  })
}, command)
```

 The first argument of render specifies the name of a template file (in the case of this hypothetical go client generator, this would be a reference to a handlebars template file at `src/resources/go/analytics.hbs`) -- this works similar in spirit to an express view engine.  The name of the language in `gen-{language}` will correspond to the resource path where templates are found

 The second argument to render specifies the generated file's extension (`analytics.go`)

 A single promise must be returned from a handler -- in order to render multiple files, use a `Promise.all()` to concurrently render them to disk:

```typescript
/*
 * gen-node.ts
 */

export const handler = getTypedTrackHandler((events, api) => {
  // ...

  return Promise.all([
    api.render('package', 'json', {
      versionInfo,
      otherData
    }),
    api.render('Readme', 'md', {
      models,
      someOtherStuff
    }),
    api.render('index', 'js', {
      models
    })
  ])
}, command)
```

4) To give an idea of what a generator produces, include the ouput of your command in `samples/{language}` (TODO: standarize a source input to use for generating samples when the `--file` option lands for specifying a local json file)