@segment/prism

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

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

/*
 * 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:

/*
 * 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)