docs(sso): expose SSO module in the generated SDK reference

[wixysam]

Summary

The SSO module (getAccessToken, getIdToken) has complete JSDoc but was marked @internal, so it never appeared on the generated SDK reference site. This removes @internal from the SsoModule interface and SsoAccessTokenResponse so the module is included in doc generation.

• Remove @internal from SsoModule and SsoAccessTokenResponse in src/modules/sso.types.ts
• Add a leading comment to the getIdToken @example so the generator renders the import inside the code block instead of hoisting it into the code-group title

Why

getIdToken was added in #234 and shipped in 0.8.40, but because the whole module carries @internal, TypeDoc drops it during generation and neither SSO method shows up in the reference docs. The only public trace of it was in the agent-facing skills docs, which is the wrong place for SDK reference content.

Note

This un-hides the whole SSO module, so getAccessToken is published alongside getIdToken. That's intentional (they're the module's two methods) but it is a deliberate "make SSO public in the reference" decision worth a look.

Validation

• npm run build passes (tsc)
• npm test -- sso.test passes (4/4)
• npm run create-docs generates interfaces/sso.mdx correctly

The paired mintlify-docs PR with the regenerated reference page: base44-dev/mintlify-docs#expose-sso-module

🤖 Generated with Claude Code

[claude]

Claude finished @wixysam's task —— View job

---

Review: PR #240 — expose SSO module in the generated SDK reference

• Read src/modules/sso.types.ts and related context
• Assess code quality, docs correctness, and test coverage
• Post review feedback

Reviewed the diff plus the surrounding SSO/doc-generation setup. The change is small, correct, and reads cleanly. One notable gap worth confirming before merge.

---

Main finding — the sso property on asServiceRole is still @internal

In src/client.types.ts:147-150, the property that actually surfaces the module in the reference is still tagged:

/** {@link SsoModule | SSO module} for generating SSO tokens.
 * @internal
 */
sso: SsoModule;

With "excludeInternal": true in typedoc.json:12, TypeDoc drops @internal members. Removing @internal from the SsoModule interface makes the standalone interfaces/sso.mdx page generate, but the asServiceRole.sso entry point in the Base44Client type will still be hidden. So a reader browsing from the client type won't see a link to the SSO module — it'll only be reachable if the interface page is linked elsewhere.

If the intent is "SSO is fully public in the reference," you likely also want to drop @internal from the sso property here. If the intent is narrower (interface documented, but not advertised on the client), the current state is fine — but worth calling out explicitly given the PR's stated goal.

Related: createSsoModule in src/modules/sso.ts:10 is also @internal, but that's a factory function and keeping it internal is reasonable — flagging only for completeness.

Docs correctness — looks good

• Removing @internal from SsoModule and SsoAccessTokenResponse is the right lever for including the interface in generation.
• The added leading comment on the getIdToken @example (// Get the user's ID token... at sso.types.ts:55) is a sensible fix for the generator hoisting the import line into the code-group title. The getAccessToken example already has a leading comment, so this makes the two examples consistent.

Minor nits (non-blocking)

• getAccessToken example (sso.types.ts:37-38) uses response.access_token, while the module-level example (sso.types.ts:20-21) uses response.data.access_token. Since getAccessToken returns Promise<SsoAccessTokenResponse> (not an Axios response), response.access_token is the correct one — the module-level example's response.data.access_token appears inconsistent with the method signature. Not introduced by this PR, but now that this becomes public docs it's a good time to reconcile them.
• @param userid (lowercase) matches the parameter name, so that's fine.

Bugs / security / performance

• No runtime code changed; no behavioral, performance, or security impact. This is purely a JSDoc/visibility change.
• Note (informational): un-hiding the module publishes getAccessToken alongside getIdToken, as the PR description already acknowledges. No concern from a code standpoint.

Test coverage

• No test changes needed for a docs-visibility change. The PR notes npm test -- sso.test passes (4/4) and npm run create-docs generates interfaces/sso.mdx, which is the right validation for this change.

---

Summary: Approve in spirit — the change does what it says for the interface page. The one thing I'd resolve before merge is whether to also drop @internal from the asServiceRole.sso property in src/client.types.ts:147-150 so the module is actually reachable from the client reference. The response.data.access_token vs response.access_token inconsistency is a nice-to-fix while you're here.
• Branch: expose-sso-module

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/sdk@0.8.40-pr.240.92d2811

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.40-pr.240.92d2811"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "@base44/sdk": "npm:@base44-preview/sdk@0.8.40-pr.240.92d2811"
  }
}

• 📦 Preview Package: @base44-preview/sdk@0.8.40-pr.240.92d2811
• 🔗 View this commit on GitHub

---

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

[claude]

Claude finished @wixysam's task —— View job

---

Review: PR #240 — expose SSO module in the generated SDK reference

• Read current state of src/client.types.ts and src/modules/sso.types.ts
• Assess whether prior review feedback was addressed
• Post review feedback

---

Re-reviewed the current diff after the sync. The main finding from the previous review has been addressed — @internal is now gone from the asServiceRole.sso property (src/client.types.ts:147-148), so the SSO module is reachable from the client reference, not just via the standalone interface page. The change now genuinely does what the PR title says.

What's good

• src/client.types.ts:147-148 — sso property is now documented (no more @internal), fixing the reachability gap.
• src/modules/sso.types.ts — SsoModule and SsoAccessTokenResponse are public; the added leading comment on the getIdToken @example (line 55) keeps the two examples consistent and avoids the generator hoisting the import into the code-group title.
• createSsoModule staying @internal (src/modules/sso.ts:10) is fine — it's a factory, not part of the public surface.

Worth reconciling now that this is public docs

1. Example inconsistency for access_token (docs correctness).
The module-level example still uses response.data.access_token (sso.types.ts:21), while the method-level example uses response.access_token (sso.types.ts:38). Given getAccessToken returns Promise<SsoAccessTokenResponse> (not an Axios response), response.access_token is the correct form. The response.data.access_token at line 21 will read incorrectly to users copying from the now-public reference — recommend aligning it to response.access_token.

2. Potential real type/runtime mismatch in getAccessToken (informational, pre-existing).
In src/modules/sso.ts:18-21, getAccessToken does return axios.get(url) directly and is typed as Promise<SsoAccessTokenResponse>. Compare with the connectors module (src/modules/connectors.ts:36-41), which unwraps and returns response.access_token and needs @ts-expect-error casts because the response shape differs from the declared type. The SSO version returns the raw axios result without unwrapping and without a cast. If there's a response interceptor that unwraps .data, this may happen to work at runtime, but the typing/return shape here is worth confirming — especially since:

• the type says SsoAccessTokenResponse ({ access_token: string }), and
• the public example at sso.types.ts:38 reads response.access_token.

If the interceptor unwraps .data, then line 21's response.data.access_token in the module example is definitely wrong. Confirming the interceptor behavior resolves both this and finding #1 together. This is pre-existing and not introduced by the PR, but it becomes user-facing once the module is public.

Bugs / security / performance

• No runtime code changed in this PR (pure JSDoc/visibility change) — no behavioral, performance, or security impact.
• Un-hiding the module publishes getAccessToken alongside getIdToken, which the PR description already flags as intentional. No concern from a code standpoint.

Test coverage

• Appropriate for a docs-visibility change — no new tests needed. PR notes npm test -- sso.test (4/4) and npm run create-docs generating interfaces/sso.mdx, which is the right validation.

---

Summary: Looks good to merge — the prior blocking concern (client sso property still @internal) is resolved. The only nice-to-fix is the response.data.access_token vs response.access_token inconsistency at sso.types.ts:21 vs :38, which ties into confirming the axios unwrap behavior in sso.ts. Neither is a blocker for a docs-only PR.

• Branch: expose-sso-module
View job

[claude]

Claude finished @wixysam's task —— View job

---

Review: PR #240 — expose SSO module in the generated SDK reference

• Read current state of changed files
• Verify axios unwrap behavior (resolves the access_token questions)
• Post review feedback

---

Re-reviewed the current state. The prior blocking concern (client sso property still @internal) is resolved — src/client.types.ts:147-148 now documents sso without @internal, so the module is reachable from the client reference. The change genuinely does what the PR title says.

I also confirmed the axios unwrap behavior, which settles the two open questions from earlier reviews.

Axios unwrap confirmed — and it changes the verdict on the examples

The response interceptor returns response.data directly (src/utils/axios-client.ts:238). So inside the modules, axios.get(url) resolves to the response body, not the full Axios response. This means:

• getAccessToken (src/modules/sso.ts:18-21) does return axios.get(url), which resolves to { access_token } — matching the declared Promise<SsoAccessTokenResponse>. Typing is effectively correct at runtime (the connectors module needs @ts-expect-error only because it further unwraps to a bare string; SSO returns the object as-is, so no cast is needed). ✅
• Therefore the method-level examples are correct and the module-level example is wrong:
  • sso.types.ts:40 — const { access_token } = await ...getAccessToken(...) ✅ correct
  • sso.types.ts:21 (from earlier reviews) — response.data.access_token ❌ would be undefined at runtime, since the resolved value is already the body

One fix worth making before this becomes public docs

Module-level example uses response.data.access_token — given the interceptor already unwraps .data, copying this from the now-public reference would break for users. It should be access_token (or response.access_token) to match getAccessToken's actual return shape. This is pre-existing, not introduced by the PR, but it becomes user-facing the moment the module is published. Recommend aligning it while you're here.

(Note: the current diff for sso.types.ts shown above no longer contains a module-level @example block — if that block was already removed in this branch, this point is moot and everything is consistent. Worth a quick confirm.)

What's good

• src/modules/sso.types.ts — SsoModule and SsoAccessTokenResponse are now public; the leading comment on the getIdToken @example (line 63) keeps the two examples consistent and stops the generator from hoisting the import into the code-group title.
• createSsoModule staying @internal (src/modules/sso.ts:10) is correct — it's a factory, not part of the public surface.
• JSDoc is thorough and accurate: the userid constraint, the refresh behavior difference between getAccessToken (auto-refresh) and getIdToken (never refreshed), and the service-role-only note are all clearly documented.

Bugs / security / performance

• No runtime code changed in this PR — pure JSDoc/visibility change. No behavioral, performance, or security impact.
• Un-hiding the module publishes getAccessToken alongside getIdToken, which the PR description flags as intentional. No concern.

Test coverage

• Appropriate for a docs-visibility change — no new tests needed. PR notes npm test -- sso.test (4/4) and npm run create-docs generating interfaces/sso.mdx, which is the right validation.

---

Summary: Looks good to merge — the change does what it claims and the typing/runtime shape is sound (verified against the interceptor). The only nice-to-fix is any lingering response.data.access_token in a module-level example, which would be wrong given the .data unwrap; if that block is already gone from this branch, there's nothing left to reconcile. Not a blocker for a docs-only PR.

• Branch: expose-sso-module • View job