{"id":21702737,"url":"https://github.com/christyharagan/segment-typescript-api","last_synced_at":"2025-04-12T14:52:05.071Z","repository":{"id":41785796,"uuid":"237241423","full_name":"christyharagan/segment-typescript-api","owner":"christyharagan","description":"TypeScript API for consuming Segment.com profile, config, and HTTP tracking APIs","archived":false,"fork":false,"pushed_at":"2023-05-07T21:39:36.000Z","size":143,"stargazers_count":5,"open_issues_count":3,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-26T09:21:39.050Z","etag":null,"topics":["api","segment","segmentio","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/christyharagan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-01-30T15:20:53.000Z","updated_at":"2022-10-26T16:24:47.000Z","dependencies_parsed_at":"2024-06-21T04:16:46.686Z","dependency_job_id":"007b56ba-ce9e-4264-9372-1d861ed2477d","html_url":"https://github.com/christyharagan/segment-typescript-api","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christyharagan%2Fsegment-typescript-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christyharagan%2Fsegment-typescript-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christyharagan%2Fsegment-typescript-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christyharagan%2Fsegment-typescript-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/christyharagan","download_url":"https://codeload.github.com/christyharagan/segment-typescript-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248586257,"owners_count":21128995,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","segment","segmentio","typescript"],"created_at":"2024-11-25T21:18:47.016Z","updated_at":"2025-04-12T14:52:05.045Z","avatar_url":"https://github.com/christyharagan.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"Segment TypeScript API\n===\n\nOverview\n---\n\n[Segment](https://segment.com) provides various REST APIs with which to interact. This package provides convenient TypeScript functions for calling these APIs. The APIs covered are:\n\n * The [HTTP Tracking API](https://segment.com/docs/connections/sources/catalog/libraries/server/http-api/). This is used for non web or mobile end-points wishing to send events to Segment.\n * The [Config API](https://segment.com/docs/config-api/). This is used for creating and configuring Workspaces in Segment. Note: This isn't 100% complete. PRs are welcome.\n * The [Profile API](https://segment.com/docs/personas/profile-api/). This is used for querying the identity graph that Segment's [Personas](https://segment.com/product/personas) feature provides\n\n***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: \n```ts \ndeclare type SegmentEvents = string\ndeclare type SegmentTrackProtocol = any\n``` \nin 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](https://github.com/christyharagan/segment-typescript-definitions).\n\n\nInstall\n---\n\nInstall via NPM:\n\n```\nnpm i --save segment-typescript-api\n```\n\nor Yarn:\n\n```\nyarn install segment-typescript-api\n```\n\nUsage\n---\n\nEach API is divided into two files:\n\n * 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.\n * a ```_request``` module (e.g. ```config_request```). This contains typing definitions that define the endpoints, and a generic function for calling the endpoint.\n\nAn example:\n\n```ts\nimport * as config from 'segment-typescript-api/cjs/config_api'\n\nlet WORKSPACE_TOKEN = '123'\nlet WORKSPACE_SLUG = 'my-workspace'\n\nconfig.getWorkspace(WORKSPACE_TOKEN, WORKSPACE_SLUG).then(workspace=\u003e{\n  console.log(workspace)\n})\n```\n\nIf you're using ESNext modules, import from the ```esm``` namespace:\n\n```ts\nimport * as config from 'segment-typescript-api/esm/config_api'\n```\n\nPreview Function Usage (For commonjs)\n---\n\n```ts\nlet api = require('./cjs/config_api')\n\nconst ACCESS_TOKEN = '###' // This is a workspace access token (https://segment.com/docs/config-api/#sts=Access%20Tokens)\nconst WORK_ID = '###' // Workspace ID (found under Workspace Settings/General Settings/ID)\nconst SRC_FN_CODE = 'async function onRequest(r){let rr = await r.text(); console.log(rr)}' // This is the actual function code\nconst SRC_PAYLOAD = { // This is the test-payload to test the source function with\n  body: {}, // The HTTP body\n  headers: {}, // HTTP headers\n  queryParameters: {} // HTTP URL query parameters\n}\nconst DEST_FN_CODE = 'async function onTrack(event, settings) {console.log(event)}' // This is the actual function code\nconst 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/\n  // 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)\n  anonymousId: '23adfd82-aa0f-45a7-a756-24f2a7a4c895', // EITHER ONE OF userId OR anonymousId ARE REQUIRED (OR BOTH)\n  context: {\n    library: {\n      name: 'analytics.js',\n      version: '2.11.1'\n    },\n    page: {\n      path: '/academy/',\n      referrer: '',\n      search: '',\n      title: 'Analytics Academy',\n      url: 'https://segment.com/academy/'\n    },\n    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',\n    ip: '108.0.78.21'\n  },\n  event: 'Course Clicked', // FOR TRACK-EVENTS, THIS IS A REQUIRED FIELD\n  integrations: {},\n  messageId: 'ajs-f8ca1e4de5024d9430b3928bd8ac6b96',\n  properties: { // FOR TRACK-EVENTS, THIS IS A REQUIRED FIELD\n    title: 'Intro to Analytics'\n  },\n  receivedAt: '2015-12-12T19:11:01.266Z',\n  sentAt: '2015-12-12T19:11:01.169Z',\n  timestamp: '2015-12-12T19:11:01.249Z',\n  type: 'track', // REQUIRED FIELD; THIS SPECIFIES THE KIND OF EVENT. SEE API DOCS FOR MORE DETAILS: https://segment.com/docs/connections/spec/\n  userId: 'AiUGstSDIg', // EITHER ONE OF userId OR anonymousId ARE REQUIRED (OR BOTH)\n  originalTimestamp: '2015-12-12T19:11:01.152Z'\n}\n\napi.previewSrcFunction(ACCESS_TOKEN, WORK_ID, {\n  function: {\n    buildpack: 'boreal',\n    code: SRC_FN_CODE\n  }\n}, { payload: SRC_PAYLOAD }).then(r =\u003e {\n  console.log(r)\n})\n\napi.previewDestFunction(ACCESS_TOKEN, WORK_ID, {\n  function: {\n    buildpack: 'boreal',\n    code: DEST_FN_CODE\n  }\n}, DEST_PAYLOAD).then(r =\u003e {\n  console.log(r)\n})\n```\n\nTODO\n---\n\nPRs are welcome :)\n\n * Finish the Config API\n * 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.\n * Implement the Protocols [Debug API](https://segment.com/docs/protocols/apis-and-extensions/#debug-endpoint)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchristyharagan%2Fsegment-typescript-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchristyharagan%2Fsegment-typescript-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchristyharagan%2Fsegment-typescript-api/lists"}