Fix the SDK reference at the source: em dashes, stray type pages, nav order, broken examples

[daniellekorn]

Everything the regenerated SDK reference got wrong, fixed in the JSDoc and pipeline config that produce it rather than in the generated MDX, which is overwritten on every run.

One commit per concern, so this is readable commit by commit.

#	Commit	What it fixes
1	docs(jsdoc)	37 em dashes in published JSDoc
2	docs(skill)	The skill gap that let them in
3	fix(docs-gen)	Supporting types appearing in the nav as if they were modules; actors held back
4	docs(app)	A link to a page that does not exist
5	fix(docs-gen)	Nav order restarting the alphabet partway down
6	fix(docs)	Six published examples missing their first line of code

---

1. Em dashes in published JSDoc

Base44 docs style forbids em dashes. JSDoc in src/ is published prose, so it renders straight into the reference. 37 occurrences across 13 files; seven were live.

Each is rewritten rather than mechanically swapped, preferring a comma or a sentence break over a colon. Comments only, no code changes.

2. The skill that should have caught it

The rule existed in base44-docs-writing and changelog-writing, but not in sdk-docs-writing, which is the skill governing this JSDoc. That gap is why they got in.

Beyond adding the rule, the two facts that govern all writing in that skill move to the top, where they were previously buried inside a style bullet: this JSDoc is published prose subject to the main style guide, and fixes belong in the source because generated MDX is overwritten. Also notes that colons should be rare, calls out two grammar slips that come up when rewriting an em dash away, and removes the em dashes the skill was itself using.

3. Supporting types leaking into the nav

Supporting types are meant to be appended into the page for the module that owns them, then dropped as standalone pages. appended-articles.json already does this for EntityHandler, SortField, ConnectorIntegrationType and others, which is why the nav has only ever listed modules.

The types added with connectors.callApi() (#256) and app.getPublicSettings() (#268) were registered in types-to-expose.json but never added to appended-articles.json, so they rendered as standalone pages sitting next to auth and connectors.

ConnectorApiRequest, ConnectorApiResponse, ConnectorApiResponsePhase now append into connectors; AppPublicSettingsResponse into app. The append step already unlinks the source page, so no types-to-delete-after-processing.json entry is needed.

actors is held back. A renamed module page is treated as exposed regardless of types-to-expose.json, so actors published as an 18-line page with connect(), subscribe(), send(), close() and unsubscribe() absent entirely. Suppressing it keeps that off the site until the JSDoc is written. #273 does that and is currently a draft.

4. A broken link on the new app page

AppPublicSettingsResponse carried {@link AppModule.getPublicSettings}, which resolved to AppModule.mdx#getpublicsettings. AppModule renders as app.mdx and the type is appended into that same page, so the href pointed at a file that does not exist.

The link was redundant anyway, since the type now renders directly beneath the method. A plain code reference reads the same and cannot break.

5. Nav order restarting the alphabet

The nav sorted on the full page path, so every module declared as an interface came before every module declared as a type:

agents, ai-gateway, analytics, app, app-logs, auth, connectors,
functions, sso, entities, integrations          ← alphabet restarts

Whether a module lands in TypeDoc's interfaces/ or type-aliases/ directory follows from how it happens to be declared and is invisible to a reader. Sorting on the page name gives one run:

agents, ai-gateway, analytics, app, app-logs, auth, connectors,
entities, functions, integrations, sso

Applied in both places that build a nav group.

6. Six published examples missing their first line of code

The pipeline promotes a leading // comment to the Mintlify code-block title. An example without one has its first real line of code consumed instead.

Four auth examples start with try {, so what publishes is a try block with no try, plus an orphaned closing brace:

```typescript try {                                   ← consumed as the title
  await base44.auth.inviteUser('newuser@example.com', 'user');
} catch (error) {                                      ← catch with nothing to catch

inviteUser, resetPasswordRequest, resetPassword, changePassword, and two integrations examples. Each now opens with a comment describing the example.

This commit also names a union that TypeDoc was truncating. callApi() published its query parameter as Record<string, ... | ... | ... | ... | ...>; it is now ConnectorApiQueryValue, appended into the connectors page so the definition sits alongside the method. Purely a naming change, identical accepted values, no runtime effect.

---

Deliberately not fixed: the Pick truncation

entities.list() and filter() render their return type as `Promise<Pick\<..., ...>`, which is malformed, since the trailing [] and one > are lost and the brackets do not balance.

An earlier revision patched this with a regex in file-processing.js. It was removed.

It was silently unsafe. TypeDoc's truncation drops the [], so Promise<Pick<T,K>> and Promise<Pick<T,K>[]> collapse to the same string. A regex cannot tell them apart, and hardcoding Promise<T[]> would quietly publish a wrong type for any future method returning a single picked record.

It was the wrong layer. file-processing.js already carries twelve regex patches against TypeDoc's output. A thirteenth trades a visible defect for an invisible one.

The real fix belongs in the TypeDoc plugin, alongside a look at whether those twelve can be replaced by something more durable.

What this does and does not publish

Merging this publishes nothing. manual-publish is workflow_dispatch only, preview-publish targets @base44-preview/sdk under a different name, and no workflow here pushes to mintlify-docs. These changes only affect what a future regeneration produces.

The mintlify-docs PR was closed (base44-dev/mintlify-docs#1997) and will be regenerated fresh once this lands.

Verification

• npx tsc --noEmit clean
• grep -rn '—' src/ returns nothing
• No example is losing a line to the title
• No links pointing at pages that do not exist
• Every src/ change is comment-only except the one named type in commit 6

Known and unchanged

• Locale mirrors are English. The generator copies English content into all seven locale directories verbatim, so new pages are untranslated in every non-English nav.
• Union member reordering. Several status unions flip with no semantic change. Verified as TypeDoc's own ordering, not a local toolchain artifact.
• Eleven more source examples lack a leading comment, but none currently reaches a published page.

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/sdk@0.8.46-pr.272.26d8562

Prefer not to change any import paths? Install using npm alias so your code still imports @base44/sdk:

npm i "@base44/sdk@npm:@base44-preview/sdk@0.8.46-pr.272.26d8562"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "@base44/sdk": "npm:@base44-preview/sdk@0.8.46-pr.272.26d8562"
  }
}

• 📦 Preview Package: @base44-preview/sdk@0.8.46-pr.272.26d8562
• 🔗 View this commit on GitHub

---

_{Preview published to npm registry — try new features instantly!}