@doist/comms-sdk 3.2.0 → 3.3.1

package/dist/esm/types/errors.js

@@ -6,3 +6,77 @@ export class CommsRequestError extends CustomError {
         this.responseData = responseData;
     }
 }
+function hasStatus(error, status) {
+    return error instanceof CommsRequestError && error.httpStatusCode === status;
+}
+function getResponseField(error, field) {
+    if (!(error instanceof CommsRequestError))
+        return undefined;
+    const data = error.responseData;
+    if (typeof data !== 'object' || data === null || !(field in data))
+        return undefined;
+    return data[field];
+}
+/**
+ * The numeric `error_code` the API sends in an error body, when there was one.
+ *
+ * @param error - The thrown value to inspect.
+ * @returns The code, or `null` when the error is not a
+ * {@link CommsRequestError} or carried no numeric `error_code`.
+ */
+export function getCommsErrorCode(error) {
+    const code = getResponseField(error, 'error_code');
+    return typeof code === 'number' ? code : null;
+}
+/**
+ * The `error_string` the API sends alongside `error_code`, when there was one.
+ * It is a server-authored message rather than a stable contract, so branch on
+ * {@link getCommsErrorCode} and use this for display.
+ *
+ * @param error - The thrown value to inspect.
+ * @returns The message, or `null` when the error is not a
+ * {@link CommsRequestError} or carried no string `error_string`.
+ */
+export function getCommsErrorString(error) {
+    const message = getResponseField(error, 'error_string');
+    return typeof message === 'string' ? message : null;
+}
+/**
+ * True when the request failed with a 404.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *     await api.threads.getThread(id)
+ * } catch (error) {
+ *     if (isNotFound(error)) return null
+ *     throw error
+ * }
+ * ```
+ */
+export function isNotFound(error) {
+    return hasStatus(error, 404);
+}
+/**
+ * True when the request failed with a 409. The API uses this both for genuine
+ * conflicts and for a malformed id, so narrow with {@link isMalformedId}
+ * before reporting one as the other.
+ */
+export function isConflict(error) {
+    return hasStatus(error, 409);
+}
+/**
+ * True when the API rejected an id as malformed: a 409 carrying `error_code`
+ * 217, which it sends both for a value that does not base58-decode to 16 bytes
+ * and for one whose version nibble is not 7. That is a bad reference rather
+ * than a conflict, so it usually deserves a different message from
+ * {@link isConflict}.
+ *
+ * @example
+ * ```typescript
+ * if (isMalformedId(error)) throw new Error(`Not a valid Comms id: ${ref}`)
+ * ```
+ */
+export function isMalformedId(error) {
+    return isConflict(error) && getCommsErrorCode(error) === 217;
+}

package/dist/types/types/errors.d.ts

@@ -4,3 +4,54 @@ export declare class CommsRequestError extends CustomError {
     responseData?: unknown;
     constructor(message: string, httpStatusCode?: number, responseData?: unknown, options?: ErrorOptions);
 }
+/**
+ * The numeric `error_code` the API sends in an error body, when there was one.
+ *
+ * @param error - The thrown value to inspect.
+ * @returns The code, or `null` when the error is not a
+ * {@link CommsRequestError} or carried no numeric `error_code`.
+ */
+export declare function getCommsErrorCode(error: unknown): number | null;
+/**
+ * The `error_string` the API sends alongside `error_code`, when there was one.
+ * It is a server-authored message rather than a stable contract, so branch on
+ * {@link getCommsErrorCode} and use this for display.
+ *
+ * @param error - The thrown value to inspect.
+ * @returns The message, or `null` when the error is not a
+ * {@link CommsRequestError} or carried no string `error_string`.
+ */
+export declare function getCommsErrorString(error: unknown): string | null;
+/**
+ * True when the request failed with a 404.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *     await api.threads.getThread(id)
+ * } catch (error) {
+ *     if (isNotFound(error)) return null
+ *     throw error
+ * }
+ * ```
+ */
+export declare function isNotFound(error: unknown): boolean;
+/**
+ * True when the request failed with a 409. The API uses this both for genuine
+ * conflicts and for a malformed id, so narrow with {@link isMalformedId}
+ * before reporting one as the other.
+ */
+export declare function isConflict(error: unknown): boolean;
+/**
+ * True when the API rejected an id as malformed: a 409 carrying `error_code`
+ * 217, which it sends both for a value that does not base58-decode to 16 bytes
+ * and for one whose version nibble is not 7. That is a bad reference rather
+ * than a conflict, so it usually deserves a different message from
+ * {@link isConflict}.
+ *
+ * @example
+ * ```typescript
+ * if (isMalformedId(error)) throw new Error(`Not a valid Comms id: ${ref}`)
+ * ```
+ */
+export declare function isMalformedId(error: unknown): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@doist/comms-sdk",
-    "version": "3.2.0",
+    "version": "3.3.1",
     "description": "A TypeScript wrapper for the Comms REST API.",
     "author": "Doist developers",
     "homepage": "https://doist.github.io/comms-sdk-typescript/",
@@ -45,7 +45,7 @@
         "@doist/sdk-kmp": "0.2.3",
         "camelcase": "9.0.0",
         "ts-custom-error": "3.3.1",
-        "undici": "7.29.0",
+        "undici": "8.11.2",
         "uuid": "11.1.1",
         "zod": "4.4.3"
     },