Title: fix(sdk): make the 0.2.0 SDK release safe to publish by waleedlatif1 · Pull Request #6616 · simstudioai/sim · GitHub
Open Graph Title: fix(sdk): make the 0.2.0 SDK release safe to publish by waleedlatif1 · Pull Request #6616 · simstudioai/sim
X Title: fix(sdk): make the 0.2.0 SDK release safe to publish by waleedlatif1 · Pull Request #6616 · simstudioai/sim
Description: Summary Three release-correctness defects in the two SDK packages, all of which would have shipped badly on the next publish. 1. The TypeScript SDK carried five breaking changes but was versioned 0.1.3. The v2 migration already landed on this branch's base. It changed, in the published API: executeWorkflow moved to POST /api/v2/workflows/{id}/execute, with the workflow input nested under input and async / executionTimeoutSeconds moved from the X-Execution-Mode / X-Execution-Timeout-Seconds headers into the body AsyncExecutionResult.jobId renamed to runId executionId removed from AsyncExecutionResult getJobStatus superseded by getWorkflowRun(workflowId, runId) a failed synchronous run now throws instead of resolving with { success: false } At 0.1.3 every existing consumer would have taken all five automatically: npm expands ^0.1.2 to >=0.1.2 <0.2.0-0, so 0.1.3 is in range and 0.2.0 is not. Verified with the resolver rather than by eye: semver.satisfies('0.1.3', '^0.1.2') === true semver.satisfies('0.2.0', '^0.1.2') === false Now 0.2.0. Minor rather than major because the package is pre-1.0 and 0.x minors are where breaking changes belong under semver — 1.0.0 would additionally assert a stability commitment the package has not made. 0.1.3 was never published (npm has 0.1.0, 0.1.1, 0.1.2), so nothing is being reused or overwritten. 2. The Python SDK was rewritten onto /api/v2 with no version bump, so it was silently unpublishable. pyproject.toml still said 0.1.2 and PyPI already has 0.1.2. The publish job's existence check therefore matched, the job skipped, and it skipped green — so the repo and PyPI diverged with no failing signal. Every v2 change made since has been sitting unpublished. Now 0.2.0. 3. A cancelled run reported success=True in Python and False in TypeScript. Python derived success = status != 'failed', which counts cancelled as a success. TypeScript derives status === 'completed' || status === 'paused'. Python was the wrong side and now matches. The predicate is a whitelist on purpose: a status added to the API later defaults to "not successful" rather than silently reporting True. A new WorkflowExecutionResult.status field carries the server's terminal status verbatim, so a caller can tell a cancelled run from a failed one — both report success=False. The two SDKs now agree on the predicate for all four terminal states and differ only in delivery, which is documented on both sides: status TypeScript Python completed success: true success=True paused success: true success=True cancelled success: false success=False failed throws SimStudioError returns success=False, status='failed', error set Also fixed, found while verifying the above: Python parsed X-RateLimit-Reset with a bare int(). The v2 API sends that header as an ISO 8601 timestamp (resetAt.toISOString()), so every execute_workflow call against v2 would have raised ValueError out of the rate-limit bookkeeping — the Python 0.2.0 would have been dead on arrival. It now mirrors the TypeScript parser exactly (all-digit kept as-is, otherwise parsed to epoch ms, otherwise 0) and degrades rather than raising, because a quota hint must never take down the call it rode in on. Both READMEs get a migration guide. A breaking major without one is the actual defect. Publish implications — read before merging This is a breaking release of two packages to two registries that cannot be un-published cleanly. Versions can never be reused. Nothing publishes on merge to staging. Both publish-ts-sdk.yml and publish-python-sdk.yml trigger on push to main only, path-filtered to their package. The publish fires when staging is promoted to main, not on this merge. Each job reads exactly one version file. The npm job reads packages/ts-sdk/package.json; the PyPI job reads [project].version from packages/python-sdk/pyproject.toml. Both are 0.2.0 here, and neither version exists on its registry, so both existence checks miss and both will publish. Each also cuts a GitHub release tag. packages/python-sdk/setup.py still says 0.1.1 and is dead. The publish job does not read it, and because [project].version is static, setuptools ignores the version= kwarg passed to setup(). It does not affect this release. Left alone deliberately — see follow-ups. Consumers are not auto-upgraded. That is the entire point of 0.2.0: ^0.1.2 and simstudio-sdk<0.2 both stay on the old line, and upgrading becomes a deliberate act. Server compatibility claim The branch originally asserted a minimum server version of "Sim v0.7.69 or later" in both READMEs. I removed that number rather than shipping it, because a published README cannot be corrected without cutting another release and the claim did not hold up: No stable v0.7.69 tag exists — only -beta / -staging prereleases. The latest stable tag is v0.7.68. The commit that added the v2 execute route (#5273) is on staging and not on main, so v0.7.68 does not contain it and a stable v0.7.69 cut before that promotion would not either. More fundamentally, a version number cannot express the requirement at all. The whole /api/v2 surface sits behind the v2-api gate, which answers 404 when off. A self-hosted deployment serves it only when the operator enables V2_API, regardless of which version it runs. The READMEs now describe the requirement in terms the reader can actually check — the endpoint, the V2_API setting, and the 404 they will see — with no version number to go stale. Type of Change Bug fix Testing packages/python-sdk: 40 passed. Run with PYTHONPATH=. python -m pytest tests/test_client.py -q. Note that PR CI does not cover this suite — the Python SDK is not a JS workspace, so turbo run test skips it and the tests run only inside the publish job on main. Run locally when reviewing. packages/ts-sdk: 38 passed (bunx vitest run src/index.test.ts). This one is covered by PR CI via turbo run test. Re-proved the cancelled-run test fails without the fix: reverting success to status != 'failed' turns test_sync_execution_cancelled_is_not_success red, and restoring it turns it green with a clean tree. Same for the ISO reset parser — reverting to int(reset) fails three tests with ValueError. bun run type-check and biome clean on the changed TypeScript. bun.lock changed by exactly one line: the packages/ts-sdk workspace version propagating. No dependency, resolution, or integrity change. Explicitly out of scope A 404-fallback / dual-endpoint compatibility shim was considered and rejected. The legacy 202 body's statusUrl points at /api/jobs/{jobId}, so mapping jobId onto runId would hand the caller a runId that this SDK's own getWorkflowRun cannot resolve — a silently broken poll is worse than an honest 404. Follow-ups, not this PR RateLimitInfo.reset carries epoch seconds for the legacy integer header and epoch milliseconds for the ISO one, in both SDKs. That inconsistency is faithfully mirrored from TypeScript rather than fixed here; normalizing both to milliseconds is a separate breaking change to a separate field. The non-English SDK doc pages still document the 0.1.x API (job_id / jobId / get_job_status / getJobStatus) and become wrong the moment 0.2.0 publishes. This is broader than it first looks: 20 pages across 5 locales — {de,es,fr,ja,zh} × {api-reference,sdks} × {python,typescript}. The English api-reference pages are already current. Separately, there is no en/sdks/ directory at all, so the ten */sdks/*.mdx pages are orphaned translations of a source page that no longer exists and no English-side edit will ever propagate to them. packages/python-sdk/setup.py should probably be deleted outright rather than bumped. It is a wholly redundant second metadata declaration — name, description, classifiers, install_requires, python_requires all duplicated from pyproject.toml and none of it consulted. Bumping it to 0.2.0 would make it look live and guarantee the same drift recurs at 0.3.0. Deleting it removes the trap: if version were ever moved to dynamic, setup.py's stale value would silently become authoritative. The TypeScript WorkflowExecutionResult has no status field, so "a resolved success: false means it was cancelled" is an inference the caller cannot verify from the type. It holds today only because failed throws. Python fixed exactly this; adding status to TypeScript would be another breaking-ish change and belongs on its own. Checklist Code follows project style guidelines Self-reviewed my changes Tests added/updated and passing No new warnings introduced I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)
Open Graph Description: Summary Three release-correctness defects in the two SDK packages, all of which would have shipped badly on the next publish. 1. The TypeScript SDK carried five breaking changes but was versioned 0...
X Description: Summary Three release-correctness defects in the two SDK packages, all of which would have shipped badly on the next publish. 1. The TypeScript SDK carried five breaking changes but was versioned 0...
Opengraph URL: https://github.com/simstudioai/sim/pull/6616
X: @github
Domain: github.com
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react-reconciler,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@d5750093facf |
| route-pattern | /:user_id/:repository/pull/:id/files(.:format) |
| route-controller | pull_requests |
| route-action | files |
| fetch-nonce | v2:fb7a7da3-2ead-0246-5ecd-6c4deead0ca9 |
| current-catalog-service-hash | ae870bc5e265a340912cde392f23dad3671a0a881730ffdadd82f2f57d81641b |
| request-id | EE3E:71C2F:718B5E:9C8AF8:6AFB43E0 |
| html-safe-nonce | 93bdccb07cdd6bcb48cfff78a95a909d3cf8b5523381beceec1da8c4d45744c8 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJFRTNFOjcxQzJGOjcxOEI1RTo5QzhBRjg6NkFGQjQzRTAiLCJ2aXNpdG9yX2lkIjoiNjQ2ODU5MTc4NzUwMDU4NTk1MiIsInJlZ2lvbl9lZGdlIjoiaWFkIiwicmVnaW9uX3JlbmRlciI6ImlhZCJ9 |
| visitor-hmac | cbfc65d2c4d4fac85ccbc87486eee4ee139936a14bdd66ddbeb77e59e219fb2a |
| hovercard-subject-tag | pull_request:4260631574 |
| github-keyboard-shortcuts | repository,pull-request-list,pull-request-conversation,pull-request-files-changed,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/simstudioai/sim/pull/6616/files |
| twitter:image | https://avatars.githubusercontent.com/u/40672544?s=400&v=4 |
| twitter:card | summary_large_image |
| og:image | https://avatars.githubusercontent.com/u/40672544?s=400&v=4 |
| og:image:alt | Summary Three release-correctness defects in the two SDK packages, all of which would have shipped badly on the next publish. 1. The TypeScript SDK carried five breaking changes but was versioned 0... |
| og:site_name | GitHub |
| og:type | object |
| hostname | github.com |
| expected-hostname | github.com |
| None | d849b928f455c800985398e7f1b659425adb312a5fa14fba5d9a14e62e9fe5dd |
| turbo-cache-control | no-preview |
| diff-view | unified |
| go-import | github.com/simstudioai/sim git https://github.com/simstudioai/sim.git |
| octolytics-dimension-user_id | 199344406 |
| octolytics-dimension-user_login | simstudioai |
| octolytics-dimension-repository_id | 912559512 |
| octolytics-dimension-repository_nwo | simstudioai/sim |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 912559512 |
| octolytics-dimension-repository_network_root_nwo | simstudioai/sim |
| turbo-body-classes | logged-out env-production page-responsive full-width |
| disable-turbo | true |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | a6c2f87cbcb6414452377b4967858ed6a66f1109 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
Links:
Viewport: width=device-width