@doist/comms-sdk 0.6.0 → 0.7.0

package/dist/cjs/index.js

@@ -16,6 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.closeDefaultDispatcher = exports.CommsApi = exports.WorkspacesClient = exports.WorkspaceUsersClient = exports.UsersClient = exports.ThreadsClient = exports.SearchClient = exports.ReactionsClient = exports.InboxClient = exports.HooksClient = exports.GroupsClient = exports.ConversationsClient = exports.ConversationMessagesClient = exports.CommentsClient = exports.ChannelsClient = exports.AttachmentsClient = void 0;
 __exportStar(require("./authentication"), exports);
+__exportStar(require("./migration"), exports);
 var attachments_client_1 = require("./clients/attachments-client");
 Object.defineProperty(exports, "AttachmentsClient", { enumerable: true, get: function () { return attachments_client_1.AttachmentsClient; } });
 var channels_client_1 = require("./clients/channels-client");

package/dist/cjs/migration.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchNewCommsUrl = fetchNewCommsUrl;
+exports.fetchNewCommsUrls = fetchNewCommsUrls;
+const http_client_1 = require("./transport/http-client");
+const errors_1 = require("./types/errors");
+/**
+ * Default origin of the Twist migration backend.
+ *
+ * The `fetch_new_url` endpoint lives on Twist (`twist.com`) and authenticates
+ * with a **Twist** token, not a Comms one. This is why the migration helpers are
+ * standalone functions rather than methods on {@link CommsApi} (which is
+ * constructed with a Comms token).
+ */
+const DEFAULT_TWIST_BASE_URL = 'https://twist.com';
+function getTwistMigrationUrl(baseUrl) {
+    const base = baseUrl ?? DEFAULT_TWIST_BASE_URL;
+    const trimmed = base.endsWith('/') ? base.slice(0, -1) : base;
+    return `${trimmed}/api/comms_migration/fetch_new_url`;
+}
+/**
+ * Translates a Twist URL to its equivalent Comms URL using Twist's
+ * `comms_migration/fetch_new_url` endpoint.
+ *
+ * Authenticates with a **Twist** token (external to the Comms SDK), so this is a
+ * standalone helper rather than a method on {@link CommsApi}.
+ *
+ * @example
+ * ```typescript
+ * const newUrl = await fetchNewCommsUrl({
+ *   oldUrl: 'https://twist.com/a/123/ch/456/t/789',
+ *   twistToken: process.env.TWIST_AUTH_TOKEN,
+ * })
+ * ```
+ *
+ * @returns The equivalent Comms URL.
+ * @throws {@link CommsRequestError} If the request fails. URLs that cannot be
+ * migrated surface as a thrown error too: `400` with `responseData.error.code`
+ * of `'invalid_url'`, or `404` with `'not_imported'`.
+ */
+async function fetchNewCommsUrl(args, options) {
+    const response = await (0, http_client_1.request)({
+        httpMethod: 'POST',
+        baseUri: getTwistMigrationUrl(options?.baseUrl),
+        relativePath: '',
+        apiToken: args.twistToken,
+        payload: { oldUrl: args.oldUrl },
+        customFetch: options?.customFetch,
+    });
+    const newUrl = response.data?.newUrl;
+    if (!newUrl) {
+        throw new errors_1.CommsRequestError('Migration response did not contain a new URL.', response.status, response.data);
+    }
+    return newUrl;
+}
+/**
+ * Translates multiple Twist URLs to their equivalent Comms URLs.
+ *
+ * URLs are processed **sequentially** to stay friendly to the rate-sensitive
+ * migration endpoint. A failure on one URL does not abort the run: each result
+ * carries either a `newUrl` (success) or a `CommsRequestError` (failure), in the
+ * same order as the input.
+ *
+ * @example
+ * ```typescript
+ * const results = await fetchNewCommsUrls({
+ *   oldUrls: ['https://twist.com/a/1/ch/2/t/3', 'https://twist.com/bad'],
+ *   twistToken: process.env.TWIST_AUTH_TOKEN,
+ * })
+ * for (const result of results) {
+ *   if (result.newUrl) console.log(`${result.oldUrl} -> ${result.newUrl}`)
+ *   else console.warn(`${result.oldUrl} failed`, result.error)
+ * }
+ * ```
+ *
+ * @returns One {@link MigrationResult} per input URL, in input order.
+ * @throws Re-throws any error that is not a {@link CommsRequestError}.
+ */
+async function fetchNewCommsUrls(args, options) {
+    const results = [];
+    for (const oldUrl of args.oldUrls) {
+        try {
+            const newUrl = await fetchNewCommsUrl({ oldUrl, twistToken: args.twistToken }, options);
+            results.push({ oldUrl, newUrl });
+        }
+        catch (error) {
+            if (error instanceof errors_1.CommsRequestError) {
+                results.push({ oldUrl, error });
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    return results;
+}

package/dist/esm/index.js

@@ -1,4 +1,5 @@
 export * from './authentication.js';
+export * from './migration.js';
 export { AttachmentsClient } from './clients/attachments-client.js';
 export { ChannelsClient } from './clients/channels-client.js';
 export { CommentsClient } from './clients/comments-client.js';

package/dist/esm/migration.js

@@ -0,0 +1,92 @@
+import { request } from './transport/http-client.js';
+import { CommsRequestError } from './types/errors.js';
+/**
+ * Default origin of the Twist migration backend.
+ *
+ * The `fetch_new_url` endpoint lives on Twist (`twist.com`) and authenticates
+ * with a **Twist** token, not a Comms one. This is why the migration helpers are
+ * standalone functions rather than methods on {@link CommsApi} (which is
+ * constructed with a Comms token).
+ */
+const DEFAULT_TWIST_BASE_URL = 'https://twist.com';
+function getTwistMigrationUrl(baseUrl) {
+    const base = baseUrl ?? DEFAULT_TWIST_BASE_URL;
+    const trimmed = base.endsWith('/') ? base.slice(0, -1) : base;
+    return `${trimmed}/api/comms_migration/fetch_new_url`;
+}
+/**
+ * Translates a Twist URL to its equivalent Comms URL using Twist's
+ * `comms_migration/fetch_new_url` endpoint.
+ *
+ * Authenticates with a **Twist** token (external to the Comms SDK), so this is a
+ * standalone helper rather than a method on {@link CommsApi}.
+ *
+ * @example
+ * ```typescript
+ * const newUrl = await fetchNewCommsUrl({
+ *   oldUrl: 'https://twist.com/a/123/ch/456/t/789',
+ *   twistToken: process.env.TWIST_AUTH_TOKEN,
+ * })
+ * ```
+ *
+ * @returns The equivalent Comms URL.
+ * @throws {@link CommsRequestError} If the request fails. URLs that cannot be
+ * migrated surface as a thrown error too: `400` with `responseData.error.code`
+ * of `'invalid_url'`, or `404` with `'not_imported'`.
+ */
+export async function fetchNewCommsUrl(args, options) {
+    const response = await request({
+        httpMethod: 'POST',
+        baseUri: getTwistMigrationUrl(options?.baseUrl),
+        relativePath: '',
+        apiToken: args.twistToken,
+        payload: { oldUrl: args.oldUrl },
+        customFetch: options?.customFetch,
+    });
+    const newUrl = response.data?.newUrl;
+    if (!newUrl) {
+        throw new CommsRequestError('Migration response did not contain a new URL.', response.status, response.data);
+    }
+    return newUrl;
+}
+/**
+ * Translates multiple Twist URLs to their equivalent Comms URLs.
+ *
+ * URLs are processed **sequentially** to stay friendly to the rate-sensitive
+ * migration endpoint. A failure on one URL does not abort the run: each result
+ * carries either a `newUrl` (success) or a `CommsRequestError` (failure), in the
+ * same order as the input.
+ *
+ * @example
+ * ```typescript
+ * const results = await fetchNewCommsUrls({
+ *   oldUrls: ['https://twist.com/a/1/ch/2/t/3', 'https://twist.com/bad'],
+ *   twistToken: process.env.TWIST_AUTH_TOKEN,
+ * })
+ * for (const result of results) {
+ *   if (result.newUrl) console.log(`${result.oldUrl} -> ${result.newUrl}`)
+ *   else console.warn(`${result.oldUrl} failed`, result.error)
+ * }
+ * ```
+ *
+ * @returns One {@link MigrationResult} per input URL, in input order.
+ * @throws Re-throws any error that is not a {@link CommsRequestError}.
+ */
+export async function fetchNewCommsUrls(args, options) {
+    const results = [];
+    for (const oldUrl of args.oldUrls) {
+        try {
+            const newUrl = await fetchNewCommsUrl({ oldUrl, twistToken: args.twistToken }, options);
+            results.push({ oldUrl, newUrl });
+        }
+        catch (error) {
+            if (error instanceof CommsRequestError) {
+                results.push({ oldUrl, error });
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    return results;
+}

package/dist/types/index.d.ts

@@ -1,4 +1,5 @@
 export * from './authentication.js';
+export * from './migration.js';
 export { AttachmentsClient } from './clients/attachments-client.js';
 export { ChannelsClient } from './clients/channels-client.js';
 export { CommentsClient } from './clients/comments-client.js';

package/dist/types/migration.d.ts

@@ -0,0 +1,78 @@
+import { CommsRequestError } from './types/errors.js';
+import type { CustomFetch } from './types/http.js';
+export type MigrationOptions = {
+    /** Optional custom base URL for the Twist migration endpoint (testing/self-host). */
+    baseUrl?: string;
+    /** Optional custom fetch implementation for cross-platform compatibility. */
+    customFetch?: CustomFetch;
+};
+export type FetchNewCommsUrlArgs = {
+    /** A `twist.com` URL to translate to its Comms equivalent. */
+    oldUrl: string;
+    /** A Twist (not Comms) auth token. */
+    twistToken: string;
+};
+export type FetchNewCommsUrlsArgs = {
+    /** The `twist.com` URLs to translate to their Comms equivalents. */
+    oldUrls: string[];
+    /** A Twist (not Comms) auth token. */
+    twistToken: string;
+};
+/**
+ * Result of translating a single URL in a batch migration. Discriminated by the
+ * presence of `newUrl` (success) or `error` (failure).
+ */
+export type MigrationResult = {
+    oldUrl: string;
+    newUrl: string;
+    error?: undefined;
+} | {
+    oldUrl: string;
+    newUrl?: undefined;
+    error: CommsRequestError;
+};
+/**
+ * Translates a Twist URL to its equivalent Comms URL using Twist's
+ * `comms_migration/fetch_new_url` endpoint.
+ *
+ * Authenticates with a **Twist** token (external to the Comms SDK), so this is a
+ * standalone helper rather than a method on {@link CommsApi}.
+ *
+ * @example
+ * ```typescript
+ * const newUrl = await fetchNewCommsUrl({
+ *   oldUrl: 'https://twist.com/a/123/ch/456/t/789',
+ *   twistToken: process.env.TWIST_AUTH_TOKEN,
+ * })
+ * ```
+ *
+ * @returns The equivalent Comms URL.
+ * @throws {@link CommsRequestError} If the request fails. URLs that cannot be
+ * migrated surface as a thrown error too: `400` with `responseData.error.code`
+ * of `'invalid_url'`, or `404` with `'not_imported'`.
+ */
+export declare function fetchNewCommsUrl(args: FetchNewCommsUrlArgs, options?: MigrationOptions): Promise<string>;
+/**
+ * Translates multiple Twist URLs to their equivalent Comms URLs.
+ *
+ * URLs are processed **sequentially** to stay friendly to the rate-sensitive
+ * migration endpoint. A failure on one URL does not abort the run: each result
+ * carries either a `newUrl` (success) or a `CommsRequestError` (failure), in the
+ * same order as the input.
+ *
+ * @example
+ * ```typescript
+ * const results = await fetchNewCommsUrls({
+ *   oldUrls: ['https://twist.com/a/1/ch/2/t/3', 'https://twist.com/bad'],
+ *   twistToken: process.env.TWIST_AUTH_TOKEN,
+ * })
+ * for (const result of results) {
+ *   if (result.newUrl) console.log(`${result.oldUrl} -> ${result.newUrl}`)
+ *   else console.warn(`${result.oldUrl} failed`, result.error)
+ * }
+ * ```
+ *
+ * @returns One {@link MigrationResult} per input URL, in input order.
+ * @throws Re-throws any error that is not a {@link CommsRequestError}.
+ */
+export declare function fetchNewCommsUrls(args: FetchNewCommsUrlsArgs, options?: MigrationOptions): Promise<MigrationResult[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@doist/comms-sdk",
-    "version": "0.6.0",
+    "version": "0.7.0",
     "description": "A TypeScript wrapper for the Comms REST API.",
     "author": "Doist developers",
     "homepage": "https://doist.github.io/comms-sdk-typescript/",
@@ -11,6 +11,9 @@
     },
     "license": "MIT",
     "type": "module",
+    "engines": {
+        "node": ">=20.18.1"
+    },
     "main": "dist/cjs/index.js",
     "module": "dist/esm/index.js",
     "types": "dist/types/index.d.ts",
@@ -43,36 +46,29 @@
         "prepare": "npm run build"
     },
     "dependencies": {
-        "camelcase": "8.0.0",
-        "ts-custom-error": "^3.2.0",
-        "undici": "7.24.8",
-        "uuid": "^11.1.0",
-        "zod": "4.1.12"
+        "camelcase": "9.0.0",
+        "ts-custom-error": "3.3.1",
+        "undici": "7.28.0",
+        "uuid": "11.1.1",
+        "zod": "4.4.3"
     },
     "devDependencies": {
-        "@arethetypeswrong/cli": "0.18.2",
+        "@arethetypeswrong/cli": "0.18.4",
         "@semantic-release/changelog": "6.0.3",
         "@semantic-release/git": "10.0.1",
-        "conventional-changelog-conventionalcommits": "9.3.0",
+        "conventional-changelog-conventionalcommits": "9.3.1",
         "husky": "9.1.7",
-        "lint-staged": "16.2.6",
-        "msw": "^2.11.3",
-        "npm-run-all2": "8.0.4",
-        "obsidian": "^1.10.2-1",
-        "oxfmt": "0.43.0",
-        "oxlint": "1.58.0",
-        "rimraf": "6.1.0",
-        "semantic-release": "25.0.3",
+        "lint-staged": "17.0.8",
+        "msw": "2.14.6",
+        "npm-run-all2": "9.0.2",
+        "obsidian": "1.13.1",
+        "oxfmt": "0.56.0",
+        "oxlint": "1.71.0",
+        "rimraf": "6.1.3",
+        "semantic-release": "25.0.5",
         "ts-node": "10.9.2",
-        "type-fest": "^5.0.0",
         "typescript": "5.9.3",
-        "vitest": "4.0.14"
-    },
-    "peerDependencies": {
-        "type-fest": "^4.12.0 || ^5.1.0"
-    },
-    "overrides": {
-        "fflate": "0.8.2"
+        "vitest": "4.1.9"
     },
     "husky": {
         "hooks": {