Repository navigation
Sync TypeScript Server SDK docs - #830
Conversation
…256 webhook helpers
…prefabs, and Relay reference to 3.7.1
…g, and requireArgs
Devon-White
left a comment
Devon-White
left a comment
There was a problem hiding this comment.
I checked every changed reference page against the v3.7.1 tag (875e6e2, the commit sdk-source-sync.json now records) and the published @signalwire/sdk@3.7.1. I type-checked every TypeScript block in the PR under tsc --strict and checked platform behavior in mod_openai, mod_infrastructure and prime-rails. Most of it holds up. Six things should change before this merges. The first two are coordination; the rest are wrong content.
Must change before merge
1. The pin bump and the new "Pins match the reference" rule conflict with #908. #908 unpins Server SDK installs in every guide and replaces the "Pinned versions" rule. This PR pins @3.7.1 and adds a rule that ties pins to sdk-source-sync.json, so the two can't both land. This PR also conflicts with main in .claude/rules/mdx-capability-guides.md, where main moved the Browser pin to rc.5. Even on its own terms, merging main leaves 14 guides that this PR doesn't touch on @signalwire/sdk@2.0.5: sidecar, SIP/byoc, eight TTS/* pages, both SMS pages, api-credentials and SWML deployment. That breaks "identical across every guide".
My suggestion: drop the install-line bumps and the rule change, rebase on #908 after it lands, and keep the sample fixes. The builder-gap fixes are right, and #908 doesn't have them. I ran addVerb on 3.7.1, and enter_queue without transfer_after_bridge, stream, stop_stream, and connect with codec/realtime/name all throw schema errors. #908 still chains .enter_queue({...}) in the Call queues TypeScript sample, which throws on 3.7.1.
2. The sync record says 3.7.1, but parts of the TypeScript reference still document 2.x. None of these files is in the PR, but moving synced_commit to the 3.7.1 tag says they're current. Either fix them here, or leave synced_commit where it was and list them as remaining work.
- REST pages still pass the 2.x options object. 3.7.1 takes positional arguments here, so these fail
tscand send malformed requests.fabric/tokens/create-subscriber-token.mdx:27callscreateSubscriberToken({ reference }), but the 3.7.1 signature iscreateSubscriberToken(reference: string, options?)(dist/rest/namespaces/fabric.resources.generated.d.ts:167).phone-numbers/set-relay-topic.mdx:50callssetRelayTopic(id, { topic, statusCallbackUrl }), but the signature issetRelayTopic(resourceId, topic: string, status_callback_url?, …)(relay-rest.resources.generated.d.ts:81). The guides in this PR fix exactly these two calls, so guide and reference now disagree on the same methods. The same pattern appears in:fabric/tokens/{index,create-embed-token,create-guest-token,create-invite-token,refresh-subscriber-token}phone-numbers/{set-cxml-webhook,set-call-flow}mfa/{index,sms,call,verify}video/room-tokens/{index,create},video/rooms/create-stream,video/conferences/create-stream,video/streams/updateverified-callers/submit-verification,number-groups/add-membership,fabric/resources/assign-domain-application
- Wrong argument counts (TS2554):
addresses/create,chat/{index,create-token},pubsub/{index,create-token},project/{index,create},imported-numbers/{index,create},short-codes/update,fabric/resources/assign-phone-routeandfabric/subscribers/create-sip-endpoint. - Missing required field:
fabric/swml-scripts/create.mdx:27omits the requiredcontents. SWMLService.run()no longer exists. 3.7.1 has onlyserve()andstop()(src/SWMLService.ts:1319).swml-service/run.mdxstill documents it, andswml-service/index.mdx:247,set-on-request-callback.mdx:51,as-router.mdx:19andstop.mdx:4still refer to it.data-map/global-error-keys.mdx:10-12says the keys "apply to all webhooks". The 3.7.1 JSDoc onDataMap.globalErrorKeys(src/DataMap.ts:467-476) says the platform readserror_keysonly on a webhook, "so these keys fail no request". The PR edits this page's example but not the claim, so the page still promises behavior the method doesn't have.
3. validateWebhookSignatureSha256 is wrong about cXML, and its example rejects genuine cXML webhooks. See the inline comments. The page copies the SDK JSDoc, which needs an upstream fix too.
4. The prefab factory imports don't resolve. prefabs/receptionist-agent.mdx:105 imports createReceptionistAgent and prefabs/survey-agent.mdx:150 imports createSurveyAgent, both from @signalwire/sdk. The package root exports only the classes (src/index.ts:272-276), the factories exist only in src/prefabs/index.ts, and package.json exports has no deep path to them. tsc fails with TS2724/TS2305. The PR edits both pages. The same import is on concierge-agent.mdx:88, faq-bot-agent.mdx:110 and info-gatherer-agent.mdx:116, and prefabs/index.mdx:34 lists the factories. Show new ReceptionistAgent({...}) etc. instead, or drop the sections.
5. The DataMap template fix stops partway. The correction itself is right. In mod_openai actions.c (around 1333-1346), a webhook's output, expressions and foreach expand against the response root plus input, global_data and prompt_vars, with no response key. That matches the SWML data_map reference. Four places still teach the old form:
data-map/foreach.mdx:51usesinput_key: 'response.items', which resolves to nothing. It should beinput_key: 'items'. Also, the ParamFields are orderedinput_key, output_key, max, append, but source order is…, append, max(DataMap.ts:407).data-map/index.mdx:125: theparamscard still says "Set query or form parameters for a webhook", which contradicts the rewrittenparams.mdx. Suggested: "Set the JSON request body for a webhook."guides/build-ai-agents/datamap.mdxuses${response.*}and${args.city}inside webhook output in every language tab, TypeScript included (lines 106-107, the table at 260-265, and 45${response.uses in all). After this merges, the guide contradicts the TypeScript reference.- The Python DataMap reference has 17
${response.uses.mdx-reference-pagessays to sync an edit across every language variant, so this belongs here or in a follow-up opened before merge. Separately, Python'sbody()writesbody(signalwire/core/data_map.py:273at the synced Python commit), and the platform ignores that key (actions.c:740reads onlyparams). That's an upstream SDK bug worth filing next to your TypeScript ones.
6. Version wording in pages. The semantic gates guide Note and semantic-gate/index.mdx:97 add "from version 3.7.1" and "Requires SDK 3.7.1 or later". Guides and reference shouldn't state minimum Server SDK versions, and guide prose shouldn't name per-language options. See the inline suggestions.
Should fix
Inline: relay/call/user-event.mdx (the platform rejects what the page now says is sent), the ChatGateway constructor's other throw conditions, serve.mdx's run() alias claim, the security overview's fallback wording, and a highlight range in Record calls.
Nits
configuration/index.mdx:78-83(not in the PR) still passesindex_filetonative_vector_search. The updatedskills/native-vector-search.mdxcorrectly says no index file is read (native_vector_search.ts:252-256).ai-chat-client/raw-post.mdx:23: "check the status first" works against the source. The_requestJSDoc says success is decided by the body because the keepalive commits a200early. Reading the body'serrormember is the check.agent-base/add-per-call-config.mdx:30:## Rejecting a callsits before## Parameters. Fold it into the intro or move it after Returns.agent-base/add-language.mdx:functionFillerscomes afterspeechModel.LanguageConfigorder (types.ts:108) puts it right afterspeechFillers.function-result/index.mdx:218: theholdcard still says only "with an optional timeout". It now also takes the announcement and the resume step.cli/sw-tsdocs.mdx:193-195hard-codes3.7.1as the--versionoutput. That goes stale, so use a placeholder.- Highlights already off in blocks this PR touches:
agent-base/register-swaig-function.mdx:32{15}should be{16}, andswml-service/register-swaig-function.mdx:30{12}should be{13}. record-calls.mdx:Object(event.params.result).params?.digitsreads oddly as a teaching sample. A typed cast with the comment you already have would be clearer.- 19 touched pages lack
max-toc-depth: 3(both prefab pages,skill-manager/*,skill-registry/*,skills/*). This predates the PR.
Public API still without a page
Besides WebService and createCgiHandler, which you noted:
AgentBase.runServerless()andgetTools()- The SemanticGate helpers:
gateDefinitions,applyGateFields,MAX_GATES,MAX_QUESTION_BYTES,MAX_CRITERIA_BYTES,MAX_ON_FAIL_BYTESandRESERVED_FUNCTION_NAMES - The top-level
registerSkill()andlistSkillsWithParams() paginateAll- Relay
CollectAction.pause()/resume() SkillManager.sizeandSkillRegistry.size
Not blocking, but worth a tracking issue.
What I verified as correct
- Guide samples: every complete TypeScript sample in the 10 guides type-checks against 3.7.1. The only failure is the Hono
checkJsmismatch you called out. - AgentBase:
addPerCallConfig,setDynamicConfigCallback,onCallStart/onCallEnd,mount,defineContextsoverloads,validateBasicAuth(now actually called, constant-time), credential precedence,swaigSecretand/mcpauth. - FunctionResult:
hold,changeVoice,rpcAiMessage/rpcAiGlobalData,joinConference(no 250 default),paycoercion, andtap(speak|listen|both). - ChatGateway and HandoffRouter: options and defaults; I ran
register/redeem/say/escalateand the outputs match. - Other areas: the capabilities and post-prompt helpers (run, and the output matches the comments), Bedrock voices (match the schema enum), the
swaig-testandsw-tsdocsflags, Relaystreamtrack, andSemanticGate.visualInput. - Environment variables: every public variable the source reads is documented, and nothing documented is missing from the source.
I couldn't verify the startup_hook 120-second wait and retry in mod_openai, swaig-test loading .ts agents on Node below 22, or "SignalWire address widget" as a customer-facing name (it isn't in the glossary). My mod_openai and mod_infrastructure checkouts are from April 2026, so the DataMap and user_event points should be rechecked against the deployed build if anything looks off.
|
A correction to item 5 of my review: Python's I re-checked the other backend-based points against current code, and they hold:
|
…run() serverless dispatch
…nt, and ChatGateway throws
…l on handle failure
…, skill module functions, and paginateAll
Devon-White
left a comment
Devon-White
left a comment
There was a problem hiding this comment.
Re-review of everything since 5508bc59, checked against the v3.7.1 tag (875e6e2) and the published @signalwire/sdk@3.7.1, which is still npm latest.
Earlier review: all resolved
- Must-change 1–6: the pin-sync rule is gone and
mdx-capability-guides.mdis no longer in the diff. The REST reference matches 3.7.1's positional signatures.SWMLService.run()and ConfigLoadergetAll()/getFilePath()are removed, with redirects and no stale links left.globalErrorKeysnow carries a Warning. The webhook signature pages and example are fixed. The prefab factories are dropped. The DataMap template fix now reachesforeach, theparamscard, every tab of the DataMap guide, and the Python reference (no${response.left). The version wording is gone. - Inline threads:
userEvent, theChatGatewaythrows,serve/run, the security overview, and the Record calls highlight are all fixed. I'll resolve those threads. - Nits: all addressed, including
max-toc-depthon every touched page. - Missing API pages:
WebService, the SemanticGate helpers and constants,runServerless,getTools,createCgiHandler, the skill module functions, andpaginateAllare now documented.CollectAction.pause()/resume()are left out on purpose, as #241 tracks.
What I verified in the delta
- I extracted all 272 TypeScript blocks that import the SDK from the files changed since
5508bc59and rantsc --strictagainst 3.7.1. The only failures are intentional fragments ({ /* ConciergeConfig */ }, the LiveWire before/after import, undeclareddb/app/MySkill) and thee164cases already noted in the PR body. - I read the new pages against source:
WebService(options, defaults, the dotfile/.well-knownrule,start()throwing without credentials,stop()),runServerless/run(env detection, CGI with an empty event),createCgiHandler,getTools(defineTools()first,SwaigFunctiononly), the skill module functions (includingaddSkillDirectory→addSearchPath, no validation),paginate/paginateAll, andHandoffRouter.redeem()returningnullon a mint failure after spending the nonce. All match. - I ran the SemanticGate constants and helpers. The values,
RESERVED_FUNCTION_NAMES, and the error messages match the pages, except for the two examples flagged inline. - CI is green.
Before merge
- Should fix: the
applyGateFieldsexample throws at runtime, and thegateDefinitionsplain-object example would too once its threshold is fixed. Both pass a stringon_fail, and a plain-object gate needs an object. See inline. - Nit: the
as nevernote and comments name "3.7.1". See inline. - Coordination, already in your notes: nine guides still install
@signalwire/sdk@3.7.1, so take #908's unpinned lines when you rebase. The branch is also 96 commits behindmain.
|
@Devon-White Thanks for the review. Inline threads are answered in place; here are the review-body items.
Nits: all applied. That includes Public API without a page: added Couldn't verify, now checked:
SDK issues: I filed #233, #235, #238, #241 in signalwire-typescript, consolidated from the gaps above. |
Description
@signalwire/sdkv3.7.1. It was synced to an unreleased commit between 2.0.5 and 3.5.0.AgentBase.addPerCallConfig,onCallStart,onCallEnd,mount;FunctionResult.changeVoice,rpcAiGlobalData;ChatGateway;HandoffRouter;AIChatClient.rawPost; the capabilities helpers; the post-prompt helpers;validateWebhookSignatureSha256; thesw-tsdocsCLI;WebService; the SemanticGate helpers and limits (gateDefinitions,applyGateFields,MAX_*,RESERVED_FUNCTION_NAMES);AgentBase.runServerless,getTools;ServerlessAdapter.createCgiHandler; the skill module functions (registerSkill,listSkills,listSkillsWithParams,addSkillDirectory); standalonepaginate/paginateAll.onSummary,validateBasicAuth,enableMcpServer,defineContexts,addLanguage,hold,rpcAiMessage,tap,joinConference,pay,SemanticGate(visualInput), Bedrock, LiveWire, prefabs, skills,swaig-test, environment variables, serverless,AgentServer, Relaystream/userEvent/events,SwmlBuilder.ai.SWMLService.run()(folded intoserve), ConfigLoadergetAll()/getFilePath(). Each old URL redirects to its replacement.AgentBase.run()is documented as dispatching to a serverless handler when it detects one, not as an alias ofserve().createXAgent()factories, which the package root doesn't export.body()sets the webhook'sparams, which is sent as a POST body. A webhook'soutput,expressions, andforeachread response fields from the root (${temp}) and arguments as${input.args.x}. Applied to the TypeScript and Python reference and to every language tab of the DataMap guide.globalErrorKeys()no longer claims to apply to all webhooks.validateWebhookSignatureSha256can't verify; the example falls back to SHA-1 on a mismatch.npm install @signalwire/sdk, exactly as Install the latest Server SDK in guides instead of pinned versions #908 writes them:calling.dial,transfer,stream/streamStop,phoneNumbers.setRelayTopic, andfabric.tokens.createSubscriberToken;swmlScripts.createtakescontentsas a string; listdatais optional.ringbackitems; typedcall.deviceand collect results;record()'s missingmax_length.enter_queue,stream,stop_stream, andconnect's stream settings fail the SDK's schema validation, so those samples skip validation for that verb only, as the rule's builder-gap convention says.sdk-source-sync.jsonto the v3.7.1 tag commit.visual_inputfrom the semantic gates guide and reference.Notes for reviewers
mdx-capability-guides.md). The latest@signalwire/sdkon npm is 3.7.1, the release these samples are checked against. Install the latest Server SDK in guides instead of pinned versions #908's Call queues TypeScript sample chains.enter_queue({...}), which throws on 3.7.1; this PR's version skips validation for that verb.SwmlBuildertypes disagree with its validation and withcalling.dialsignalwire-typescript#233 (SwmlBuildertyping:ai()prompt,build()vsdial'sswml), fix: broken links detected by daily link checker #235 (generated REST and Relay types:record()max_length,SipEndpointUpdateRequest,AvailablePhoneNumber.e164,userEvent,listAddresses()), add announcement bar, styling changes #238 (SHA-256 JSDoc and cXML), Fix schema components with correct endpoint #241 (CollectAction.pause()/resume()send commands the platform doesn't handle, so they're left undocumented). Already tracked: Add navbar links, branded logo text, dropdown, styling #183 (dialmaxDurationunit), Fix more links #184 (paramSchema().build()), SWML link fixes, fixed broken links for all paramfields #204, Calling API updates #206, Link fixes for call flow builder docs #207 (builder schema gaps).e164: phone-number search examples reade164, matching the platform and the corrected REST spec. 3.7.1's types still saynumber, so those 5 examples failtsc --strictuntil fix: broken links detected by daily link checker #235 is fixed.joannawas replaced withtiffanyin the examples, since the valid Bedrock voices aretiffany,matthew,amy,lupe, andcarlos.body()/params()still describe the older synced Python commit, which writesbody. Current Python releases writeparams; that's for the next Python sync.Preview
Guides:
Reference (main entry points):
Type of Change
Related Issues
Follow-up to #829, which pins
@signalwire/sdk@2.0.5and notes that this PR syncs the TypeScript reference. Aligns with #908.Testing
Behavior verified against the platform and the API spec.
tsc --strictagainst an installed@signalwire/sdk@3.7.1. One existing JavaScript sample (call streaming, Hono server) has acheckJs-only type mismatch under both 2.0.5 and 3.7.1; it runs as-is.e164cases above.yarn fern-md-check: all MDX files valid.Tests
Checklist