feat: add Twist→Comms URL migration helper#42
Merged
Conversation
Adds standalone helpers that translate twist.com URLs to their Comms equivalents via Twist's comms_migration/fetch_new_url endpoint. These authenticate with a Twist (not Comms) token, so they live alongside authentication.ts rather than on CommsApi. - fetchNewCommsUrl: single URL, throws CommsRequestError on non-2xx - fetchNewCommsUrls: batch, sequential, collects per-URL success/failure Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
doistbot
reviewed
Jun 26, 2026
doistbot
left a comment
doistbot
left a comment
Member
There was a problem hiding this comment.
This PR adds a new src/migration.ts module with standalone helper functions (fetchNewCommsUrl and fetchNewCommsUrls) that map old Twist URLs to their Comms equivalents, mirroring the auth pattern in authentication.ts.
Few things worth tightening:
MigrationOptionscurrently duplicatesAuthOptionsexactly — consider aliasing it or extracting a shared request-options type so future transport options don't drift between the two standalone helper modules.
I also included a few optional follow-up notes in the details below.
Optional follow-up note (1)
src/migration.ts:21:
MigrationOptionsis an exact copy ofAuthOptions, so these two top-level helper modules now have to stay in sync by hand. Consider aliasingAuthOptionshere (or extracting a shared request-options type) so future transport options don't drift between auth and migration helpers.
doist-release-bot Bot
added a commit
that referenced
this pull request
Jun 26, 2026
## [0.7.0](v0.6.1...v0.7.0) (2026-06-26) ### Features * add Twist→Comms URL migration helper ([#42](#42)) ([0fda8af](0fda8af))
Contributor
|
🎉 This PR is included in version 0.7.0 🎉 The release is available on: Your semantic-release bot 📦🚀 |
amix
reviewed
Jun 26, 2026
amix
left a comment
amix
left a comment
Member
There was a problem hiding this comment.
LGTM. Small nit regarding the test suite 👍
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Context
As part of the Twist→Comms migration, Twist's backend exposes
POST https://twist.com/api/comms_migration/fetch_new_url, which maps an oldtwist.comURL to its equivalent Comms URL. This is useful for migration tooling (e.g. rewriting bookmarks/history — see reference gist).The endpoint authenticates with a Twist token, not a Comms one, so it doesn't belong on
CommsApi(constructed with a Comms token). It mirrorsauthentication.ts: standalone top-level functions that take their own token plus optionalbaseUrl/customFetch.Changes
New
src/migration.ts:fetchNewCommsUrl({ oldUrl, twistToken }, options?)→Promise<string>— POSTs to the endpoint via the existingrequest()helper (auto snake_case payload, camelCase response, Bearer auth, retries). Always throwsCommsRequestErroron non-2xx; not-migratable URLs surface as400 invalid_url/404 not_importedinerror.responseData.error.code.fetchNewCommsUrls({ oldUrls, twistToken }, options?)→Promise<MigrationResult[]>— batch variant. Processes sequentially (the endpoint is rate-sensitive); a failure on one URL doesn't abort the run. Each result is{ oldUrl, newUrl }or{ oldUrl, error }, in input order.MigrationOptions(baseUrl,customFetch) mirrorsAuthOptions.Exported from
src/index.ts.Verification
npx vitest run src/migration.test.ts→ 8 passed (success + header/body assertion, missingnew_url, 400/404/500, custom baseUrl, batch mixed success/failure, empty input)npx tsc --noEmit→ cleanoxlint→ 0 warnings/errors;oxfmt→ formatted🤖 Generated with Claude Code