CDP-6025: add TSDoc to public API + TypeDoc reference site by jcpsimmons · Pull Request #195 · customerio/customerio-node

jcpsimmons · 2026-05-26T23:15:25Z

Summary

Every public method on `TrackClient` and `APIClient`, every `Send*Request` builder, the `Region` exports, the `IdentifierType` / `Filter` types, and the error classes now carry TSDoc with `@param` / `@returns` / `@throws` and short usage examples where helpful. IDE hover and autocomplete pick these up automatically — no more empty hover tooltips.

Also wires up TypeDoc so the same comments power a static API reference site:

```sh
npm run docs # generates docs/ from index.ts
```

`docs/` is gitignored. Wiring this up to GitHub Pages on release is intentionally out of scope for this PR — covered separately if we want it.

What changed

`lib/track.ts` — TSDoc on `TrackClient` and all 11 public methods
`lib/api.ts` — TSDoc on `APIClient`, all 13 public methods, `DeliveryExportMetric`, `DeliveryExportRequestOptions`
`lib/api/requests.ts` — TSDoc on `SendEmailRequest` (+ `.attach()`), `SendPushRequest`, `SendSMSRequest`, `SendInboxMessageRequest`, `SendInAppRequest`
`lib/regions.ts` — TSDoc on `Region`, `RegionUS`, `RegionEU`
`lib/types.ts` — TSDoc on `IdentifierType`, `FilterOperator`, and every filter type
`lib/utils.ts` — TSDoc on `CustomerIORequestError`, `MissingParamError`, `isEmpty`, `isIdentifierType`
`package.json` — adds `typedoc` devDep + `docs` script
`typedoc.json` — config
`.gitignore` — ignores generated `docs/`

Test plan

`npm run build` — clean
`npm test` — all tests pass, nyc 100% coverage gate holds (no behavior change)
`npm run docs` — generates the reference site to `docs/` (0 errors)

Known follow-ups (not in this PR)

TypeDoc emits 14 warnings about types that are referenced in method signatures but not directly re-exported from `index.ts` (`EmailMessage`, `RequestData`, `PushRequestData`, the `Send*RequestOptions` unions). These are de-facto public but not formally exported. Surfacing them is a small API-surface change worth its own ticket.
GitHub Pages publish on release.

Note

Low Risk
Comment-only API docs plus dev tooling and export-list updates; no production logic changes.

Overview
Adds TSDoc across the public SDK surface—TrackClient, APIClient, all Send*Request builders, regions, filter/identifier types, and error helpers—with @param / @returns / @throws and examples where useful so IDE hovers are populated.

Wires TypeDoc via typedoc devDependency, npm run docs, and typedoc.json (entry index.ts, output docs/, internal types hidden from nav). Generated docs/ is gitignored.

index.ts now re-exports MissingParamError and additional request/auth/message types for consumers and the reference site. No intended runtime behavior changes.

^{Reviewed by Cursor Bugbot for commit e928f2d. Bugbot is set up for automated code reviews on this repo. Configure here.}

socket-security · 2026-05-26T23:15:43Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	typedoc@0.28.19

View full report

socket-security · 2026-05-26T23:15:45Z

Warning

Review the following alerts detected in dependencies.

According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.

Action	Severity	Alert (click "▶" to expand/collapse)
Warn		Obfuscated code: npm `entities` is 91.0% likely obfuscated Confidence: 0.91 Location: Package overview From: package-lock.json → `npm/typedoc@0.28.19` → `npm/entities@4.5.0` ℹ Read more on: This package \| This alert \| What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at `support@socket.dev`. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment `@SocketSecurity ignore npm/entities@4.5.0`. You can also ignore all packages with `@SocketSecurity ignore-all`. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Obfuscated code: npm `markdown-it` is 91.0% likely obfuscated Confidence: 0.91 Location: Package overview From: package-lock.json → `npm/typedoc@0.28.19` → `npm/markdown-it@14.2.0` ℹ Read more on: This package \| This alert \| What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at `support@socket.dev`. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment `@SocketSecurity ignore npm/markdown-it@14.2.0`. You can also ignore all packages with `@SocketSecurity ignore-all`. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report

@throws

Every public method on TrackClient and APIClient, every send-request builder class, the Region exports, the IdentifierType/Filter types, and the error classes now carry TSDoc with @param/@returns/@throws and short usage examples where helpful. IDE hover and autocomplete pick these up automatically. Adds typedoc as a devDependency with a typedoc.json config and an npm run docs script that emits a static reference site to docs/ (gitignored). Setting up GitHub Pages publishing is out of scope for this PR.

Adds type re-exports from index.ts for the de-facto public types that were referenced by method signatures but not formally part of the SDK exports: RequestData, PushRequestData, the Send*RequestOptions unions, and the *Message types. Users can now import these to type their own variables (e.g. function args that wrap the SDK). Also lists the remaining internal helper types (APIDefaults, TrackDefaults, Recipients, the With/Without union components, etc.) in typedoc.intentionallyNotExported so the doc generator runs warning-free. TypeDoc now reports 0 warnings, 0 errors. All tests still pass at 100% coverage.

mike-engel

Now that the pipelines client has been merged, that also needs to be covered here as well

mike-engel · 2026-06-02T11:48:45Z

 export * from './lib/types';
-export { CustomerIORequestError } from './lib/utils';
+export { CustomerIORequestError, MissingParamError } from './lib/utils';
+export type { RequestData, PushRequestData, BasicAuth, BearerAuth, RequestAuth } from './lib/request';


I'm not sure they need to be exported

mike-engel · 2026-06-02T11:51:03Z

+   *
+   * @param filters Filter expression (segment / attribute / and / or / not).
+   * @returns The parsed JSON response body, including the new export's id.
+   * @throws {MissingParamError} If `filters` is empty.


Suggested change

* @throws {MissingParamError} If `filters` is empty.

* @throws {MissingParamError} If `filters` is `null` or `undefined`.

mike-engel · 2026-06-02T11:52:24Z

+   *   send email messages; `created_at` is required for time-based segmentation.
+   * @returns The parsed JSON response body.
+   * @throws {MissingParamError} If `customerId` is empty.
+   * @throws {CustomerIORequestError} On non-2xx API responses.


This should be documented on all methods, or none (probably none, and documented at a more general/global level)

jcpsimmons marked this pull request as ready for review May 26, 2026 23:34

Dr.J added 2 commits June 1, 2026 14:52

jcpsimmons force-pushed the cdp-6025-tsdoc-typedoc branch from 7e6d7cc to e928f2d Compare June 1, 2026 21:55

mike-engel reviewed Jun 2, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CDP-6025: add TSDoc to public API + TypeDoc reference site#195

CDP-6025: add TSDoc to public API + TypeDoc reference site#195
jcpsimmons wants to merge 2 commits into
mainfrom
cdp-6025-tsdoc-typedoc

jcpsimmons commented May 26, 2026 •

edited by cursor Bot

Loading

Uh oh!

socket-security Bot commented May 26, 2026 •

edited

Loading

Uh oh!

socket-security Bot commented May 26, 2026 •

edited

Loading

Uh oh!

mike-engel left a comment

Uh oh!

mike-engel Jun 2, 2026

Uh oh!

mike-engel Jun 2, 2026

Uh oh!

mike-engel Jun 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	* @throws {MissingParamError} If `filters` is empty.
	* @throws {MissingParamError} If `filters` is `null` or `undefined`.

Conversation

jcpsimmons commented May 26, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What changed

Test plan

Known follow-ups (not in this PR)

Uh oh!

socket-security Bot commented May 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

socket-security Bot commented May 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mike-engel left a comment

Choose a reason for hiding this comment

Uh oh!

mike-engel Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

mike-engel Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

mike-engel Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jcpsimmons commented May 26, 2026 •

edited by cursor Bot

Loading

socket-security Bot commented May 26, 2026 •

edited

Loading

socket-security Bot commented May 26, 2026 •

edited

Loading