{"id":21702749,"url":"https://github.com/christyharagan/segment-typescript-definitions","last_synced_at":"2025-03-20T16:29:43.223Z","repository":{"id":70276988,"uuid":"237212738","full_name":"christyharagan/segment-typescript-definitions","owner":"christyharagan","description":"Typescript definitions for Segment.com's spec, analytics.js, and custom sources and destinations","archived":false,"fork":false,"pushed_at":"2022-07-29T12:59:56.000Z","size":25,"stargazers_count":4,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-27T22:12:41.420Z","etag":null,"topics":["analyticsjs","segment","typescript-definitions"],"latest_commit_sha":null,"homepage":"","language":null,"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-30T12:54:13.000Z","updated_at":"2022-10-26T16:25:29.000Z","dependencies_parsed_at":"2023-02-24T09:30:31.724Z","dependency_job_id":null,"html_url":"https://github.com/christyharagan/segment-typescript-definitions","commit_stats":{"total_commits":15,"total_committers":3,"mean_commits":5.0,"dds":0.1333333333333333,"last_synced_commit":"b2fd479c4e45270af8fc3f40197b3eb230686efe"},"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-definitions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christyharagan%2Fsegment-typescript-definitions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christyharagan%2Fsegment-typescript-definitions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christyharagan%2Fsegment-typescript-definitions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/christyharagan","download_url":"https://codeload.github.com/christyharagan/segment-typescript-definitions/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244649523,"owners_count":20487444,"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":["analyticsjs","segment","typescript-definitions"],"created_at":"2024-11-25T21:18:59.976Z","updated_at":"2025-03-20T16:29:43.192Z","avatar_url":"https://github.com/christyharagan.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"Segment TypeScript Definitions\n===\n\nOverview\n---\n\nThis library provides TypeScript definitions for the following [Segment](https://segment.com) libraries and APIs:\n\n * [common.d.ts](./segment-common.d.ts). This provides definitions for [the Segment spec](https://segment.com/docs/connections/spec/): This is a basis for all of Segment's APIs and SDKs.\n * [analytics.d.ts](./segment-analytics.d.ts). This provides definitions for [Analytics.js](https://github.com/segmentio/analytics.js/)\n * [custom-source.d.ts](./segment-sources.d.ts). This provides definitions for [Custom Sources](https://segment.com/docs/connections/sources/custom-sources/)\n * [custom-destination.d.ts](./segment-destinations.d.ts). This provides definitions for [Custom Destinations](https://segment.com/docs/connections/destinations/custom-destinations/)\n\nImportant Notes\n---\n\n\n***Important:*** ```segment-sources.d.ts``` consumers  must define the type ```SegmentObjectDefinition```. This is used for typing calls against the *set* method. If no defined schema exists, simply setting \n```ts \ndeclare type SegmentObjectDefinition = any\n``` \nin some ```.d.ts``` file will suffice.\n\nInstall\n---\n\nInstall via NPM:\n\n```\nnpm i --save segment-typescript-definitions\n```\n\nor Yarn:\n\n```\nyarn install segment-typescript-definitions\n```\n\n\nUsage\n---\n\nTo import the definitions, your code should look something like:\n\n```ts\nimport 'segment-typescript-definitions/common'\n```\n\nThen depending on which environment you're targeting will depend on what other definition you pull in (see the following sections for more details).\n\n***Important!*** All users must define the types ```SegmentIdentifyProtocol```, ```SegmentGroupProtocol```, ```SegmentTrackProtocol```, ```SegmentTrackProtocolUnion``` and ```SegmentEvents```. This is used for typing *track*, *identify* and *group* calls. If no defined schema exists, simply setting (in some ```.d.ts``` file within the project scope): \n```ts \ndeclare type SegmentIdentifyProtocol = object\ndeclare type SegmentGroupProtocol = object\n\ndeclare type SegmentEvents = string\ndeclare type SegmentTrackProtocol\u003cE extends SegmentEvents\u003e = object\n\ndeclare type SegmentTrackProtocolUnion = object\n``` \nOtherwise:\n\n * ```SegmentIdentifyProtocol``` should be an object definition\n * ```SegmentGroupProtocol``` should be an object definition\n * ```SegmentEvents``` should be a string union, listing all ```track``` event names\n * ```SegmentTrackProtocol``` should be a [conditional type](https://www.typescriptlang.org/docs/handbook/advanced-types.html#conditional-types) mapping each event name to its event properties\n * ```SegmentTrackProtocolUnion``` should be a [discriminated union](https://www.typescriptlang.org/docs/handbook/advanced-types.html#discriminated-unions).\n \n An example would be: \n\n```ts\ndeclare type SegmentIdentifyProtocol = {\n  email: string\n  name: string\n  consents_to_email_marketing: boolean\n}\n\ndeclare type SegmentGroupProtocol = {\n  org_name: string\n}\n\ndeclare type SegmentEvents = 'Product Viewed' | 'Product Purchased'\ndeclare type SegmentTrackProtocol\u003cE extends SegmentEvents\u003e = E extends 'Product Viewed' ? ProductViewed : E extends 'Product Purchased' ? ProductPurchased : never\n\ndeclare type SegmentTrackProtocolUnion = {\n  event: 'Product Viewed',\n  properties: ProductViewed\n} | {\n  event: 'Product Purchased',\n  properties: ProductPurchased\n}\n\ndeclare type ProductViewed = {\n  product_id: number\n  product_image_url: string\n}\n\ndeclare type ProductPurchased = {\n  product_id: number\n  quantity: number\n}\n```\n\nThe conditional type form solves for when the track event is an output (e.g. via an ```analytics.track``` call), where-as the discriminated unions are for when the track event in an input (e.g. as input to a custom destination function). Sadly, TypeScript does not yet allow us to choose one form for both scenarios.\n\nIn order to automatically generate ```SegmentTrackProtocol```, ```SegmentIdentifyProtocol```, and ```SegmentGroupProtocol``` from Segment's Protocol tracking plans, consider using [Segment TSD Generator](https://www.github.com/christyharagan/segment-tsd-generator). Note: this just generates typing definitions to make consuming the raw APIs easier. If you want a more full-featured approach, consider using [TypeWriter](https://github.com/segmentio/typewriter).\n\n### Analytics.JS\n\nFor general information on using Analytics.JS see the [docs](https://segment.com/docs/connections/sources/catalog/libraries/website/javascript/). To consume the definitions, define a TypeScript definition file within your source directory that looks like:\n\n```ts\n/// \u003creference path=\"../node_modules/segment-typescript-definitions/common.d.ts\"/\u003e\n/// \u003creference path=\"../node_modules/segment-typescript-definitions/analytics.d.ts\"/\u003e\n```\n\nBeyond that, nothing else should change in how you consume the library.\n\n### Custom Sources\n\nFor a full fledged local development of Segment Functions, consider using [Segment Sloth](https://www.github.com/christyharagan/segment-sloth).\n\nFor general information on writing a custom source see the [docs](https://segment.com/docs/connections/sources/custom-sources/).\n\nIn order to use the definitions, you'll need to manually include some extra typing information in your custom source function. First, define a TypeScript definition file in your source directory that looks like:\n\n```ts\n/// \u003creference path=\"../node_modules/segment-typescript-definitions/common.d.ts\"/\u003e\n/// \u003creference path=\"../node_modules/segment-typescript-definitions/custom-source.d.ts\"/\u003e\n```\n\nFor your function itself, define a TypeScript file that looks like:\n\n```ts\ndeclare type SegmentObjectDefinition = {/*...*/} // See \"important\" note below for details\n\nasync function onRequest(request:SegmentSourceRequest, settings:SegmentSettings) {\n    Segment.group({\n      userId: 'My Id',\n      groupId: 'My Group'\n    })\n}\n```\n\n***Important:*** Users must define the type ```SegmentObjectDefinition```. This is used for typing calls against the *set* method. If no defined schema exists, simply setting \n```ts \ndeclare type SegmentObjectDefinition = any\n``` \n\nIf you wish to have full typings for all included dependencies, include the following packages:\n\n * @types/atob\n * @types/btoa\n * aws-sdk\n * form-data\n * @types/lodash\n * @types/node\n * @types/node-fetch\n * @types/oauth\n * @types/xml\n\n### Custom Destinations\n\nFor a full fledged local development of Segment Functions, consider using [Segment Sloth](https://www.github.com/christyharagan/segment-sloth).\n\nFor general information on writing a custom source see the [docs](https://segment.com/docs/connections/destinations/custom-destinations/).\n\nHowever, in order to use the definitions, you'll need to manually include some extra typing information in your custom source function. First, define a TypeScript definition file in your source directory that looks like:\n\n```ts\n/// \u003creference path=\"../node_modules/segment-typescript-definitions/common.d.ts\"/\u003e\n/// \u003creference path=\"../node_modules/segment-typescript-definitions/custom-destination.d.ts\"/\u003e\n```\n\nFor your function itself, define a TypeScript file that looks like:\n\n```ts\nasync function onTrack(event:SegmentTrackEvent, settings: SegmentSettings) {\n  //...\n}\n\nasync function onIdentify(event:SegmentIdentifyEvent, settings: SegmentSettings) {\n  //...\n}\n\nasync function onGroup(event:SegmentGroupEvent, settings: SegmentSettings) {\n  //...\n}\n\nasync function onPage(event:SegmentPageEvent, settings: SegmentSettings) {\n  //...\n}\n\nasync function onAlias(event:SegmentAliasEvent, settings: SegmentSettings) {\n  //...\n}\n\nasync function onScreen(event:SegmentScreenEvent, settings: SegmentSettings) {\n  //...\n}\n```\n\nIf you wish to have full typings for all included dependencies, include the following packages:\n\n * @types/atob\n * @types/btoa\n * aws-sdk\n * @types/lodash\n * @types/node\n * @types/node-fetch\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchristyharagan%2Fsegment-typescript-definitions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchristyharagan%2Fsegment-typescript-definitions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchristyharagan%2Fsegment-typescript-definitions/lists"}