Skip to content

TypeScript API for consuming Segment.com profile, config, and HTTP tracking APIs

License

Notifications You must be signed in to change notification settings

christyharagan/segment-typescript-api

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

17 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Segment TypeScript API

Overview

Segment provides various REST APIs with which to interact. This package provides convenient TypeScript functions for calling these APIs. The APIs covered are:

  • The HTTP Tracking API. This is used for non web or mobile end-points wishing to send events to Segment.
  • The Config API. This is used for creating and configuring Workspaces in Segment. Note: This isn't 100% complete. PRs are welcome.
  • The Profile API. This is used for querying the identity graph that Segment's Personas feature provides

Important: If you plan on consuming the HTTP Tracking API via TypeScript, you must define the types SegmentTrackProtocol and SegmentEvents. This is used for strongly typing track calls. If no defined schema exists, simply setting:

declare type SegmentEvents = string
declare type SegmentTrackProtocol = any

in some .d.ts file will suffice. There are also optional SegmentIdentifyProtocol and SegmentIdentifyProtocol interfaces (for strongly typing identify and group calls). For more information see Segment TypeScript Definitions.

Install

Install via NPM:

npm i --save segment-typescript-api

or Yarn:

yarn install segment-typescript-api

Usage

Each API is divided into two files:

  • a _api module (e.g. config_api). This contains an easy-to-use API for calling each endpoint. This is probably the what you want to consume.
  • a _request module (e.g. config_request). This contains typing definitions that define the endpoints, and a generic function for calling the endpoint.

An example:

import * as config from 'segment-typescript-api/cjs/config_api'

let WORKSPACE_TOKEN = '123'
let WORKSPACE_SLUG = 'my-workspace'

config.getWorkspace(WORKSPACE_TOKEN, WORKSPACE_SLUG).then(workspace=>{
  console.log(workspace)
})

If you're using ESNext modules, import from the esm namespace:

import * as config from 'segment-typescript-api/esm/config_api'

Preview Function Usage (For commonjs)

let api = require('./cjs/config_api')

const ACCESS_TOKEN = '###' // This is a workspace access token (https://segment.com/docs/config-api/#sts=Access%20Tokens)
const WORK_ID = '###' // Workspace ID (found under Workspace Settings/General Settings/ID)
const SRC_FN_CODE = 'async function onRequest(r){let rr = await r.text(); console.log(rr)}' // This is the actual function code
const SRC_PAYLOAD = { // This is the test-payload to test the source function with
  body: {}, // The HTTP body
  headers: {}, // HTTP headers
  queryParameters: {} // HTTP URL query parameters
}
const DEST_FN_CODE = 'async function onTrack(event, settings) {console.log(event)}' // This is the actual function code
const DEST_PAYLOAD = { // This is the test-payload to test the destination function with. Check out the examples in any of the APIs: https://segment.com/docs/connections/spec/
  // This is a complete example. You would only need to populate the fields that your function would actually use (although some are required; see comments)
  anonymousId: '23adfd82-aa0f-45a7-a756-24f2a7a4c895', // EITHER ONE OF userId OR anonymousId ARE REQUIRED (OR BOTH)
  context: {
    library: {
      name: 'analytics.js',
      version: '2.11.1'
    },
    page: {
      path: '/academy/',
      referrer: '',
      search: '',
      title: 'Analytics Academy',
      url: 'https://segment.com/academy/'
    },
    userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/46.0.2490.86 Safari/537.36',
    ip: '108.0.78.21'
  },
  event: 'Course Clicked', // FOR TRACK-EVENTS, THIS IS A REQUIRED FIELD
  integrations: {},
  messageId: 'ajs-f8ca1e4de5024d9430b3928bd8ac6b96',
  properties: { // FOR TRACK-EVENTS, THIS IS A REQUIRED FIELD
    title: 'Intro to Analytics'
  },
  receivedAt: '2015-12-12T19:11:01.266Z',
  sentAt: '2015-12-12T19:11:01.169Z',
  timestamp: '2015-12-12T19:11:01.249Z',
  type: 'track', // REQUIRED FIELD; THIS SPECIFIES THE KIND OF EVENT. SEE API DOCS FOR MORE DETAILS: https://segment.com/docs/connections/spec/
  userId: 'AiUGstSDIg', // EITHER ONE OF userId OR anonymousId ARE REQUIRED (OR BOTH)
  originalTimestamp: '2015-12-12T19:11:01.152Z'
}

api.previewSrcFunction(ACCESS_TOKEN, WORK_ID, {
  function: {
    buildpack: 'boreal',
    code: SRC_FN_CODE
  }
}, { payload: SRC_PAYLOAD }).then(r => {
  console.log(r)
})

api.previewDestFunction(ACCESS_TOKEN, WORK_ID, {
  function: {
    buildpack: 'boreal',
    code: DEST_FN_CODE
  }
}, DEST_PAYLOAD).then(r => {
  console.log(r)
})

TODO

PRs are welcome :)

  • Finish the Config API
  • Document the API calls. Currently, the user has to reference the docs to understand what each call does. This info should be included as JSDocs.
  • Implement the Protocols Debug API

About

TypeScript API for consuming Segment.com profile, config, and HTTP tracking APIs

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published