@doist/comms-sdk 3.0.1 → 3.1.0

package/dist/esm/clients/attachments-client.js

@@ -1,7 +1,9 @@
-import { ENDPOINT_ATTACHMENTS } from '../consts/endpoints.js';
+import { z } from 'zod';
+import { ENDPOINT_ATTACHMENTS, ENDPOINT_FILES } from '../consts/endpoints.js';
+import { request } from '../transport/http-client.js';
 import { AttachmentSchema } from '../types/entities.js';
 import { uploadMultipartFile } from '../utils/multipart-upload.js';
-import { isValidUuidV7Base58, resolveCreateId, UuidV7Error } from '../utils/uuidv7.js';
+import { isValidUuidV7Base58, resolveCreateId, resolveReferenceId, UuidV7Error, } from '../utils/uuidv7.js';
 import { BaseClient } from './base-client.js';
 /**
  * Resolve the `attachment_id`: validate a caller-supplied value (throwing an
@@ -15,14 +17,37 @@ function resolveAttachmentId(attachmentId) {
     }
     return resolveCreateId(attachmentId);
 }
+export const IMAGE_READ_MIME_TYPES = ['image/jpeg', 'image/png', 'image/webp'];
+export const ImageReadResultSchema = z.object({
+    mimeType: z.enum(IMAGE_READ_MIME_TYPES),
+    dataBase64: z.string().min(1).max(5592408).base64(),
+    byteLength: z
+        .number()
+        .int()
+        .positive()
+        .max(4 * 1024 * 1024),
+});
 /**
- * Client for uploading file attachments to Comms.
+ * Client for uploading attachments and reading thread images.
  *
  * Attachments are uploaded independently, then referenced by passing the returned
  * {@link Attachment} into the `attachments` array of `comments.createComment`,
  * `conversationMessages.createMessage`, and similar calls.
  */
 export class AttachmentsClient extends BaseClient {
+    /** Read one thread image under the caller's content scope. */
+    async readImage(uploadId, threadId) {
+        const id = resolveReferenceId(uploadId, 'uploadId');
+        const checkedThreadId = resolveReferenceId(threadId, 'threadId');
+        const response = await request({
+            httpMethod: 'GET',
+            baseUri: this.getBaseUri(),
+            relativePath: `${ENDPOINT_FILES}/image/${checkedThreadId}/${id}`,
+            apiToken: this.apiToken,
+            customFetch: this.customFetch,
+        });
+        return ImageReadResultSchema.parse(response.data);
+    }
     /**
      * Uploads a file and returns the created {@link Attachment}.
      *

package/dist/esm/consts/endpoints.js

@@ -27,4 +27,5 @@ export const ENDPOINT_REACTIONS = 'reactions';
 export const ENDPOINT_SEARCH = 'search';
 export const ENDPOINT_CONVERSATION_MESSAGES = 'conversation_messages';
 export const ENDPOINT_ATTACHMENTS = 'attachments';
+export const ENDPOINT_FILES = 'files';
 export const ENDPOINT_HOOKS = 'hooks';

package/dist/esm/index.js

@@ -1,6 +1,6 @@
 export * from './authentication.js';
 export * from './migration.js';
-export { AttachmentsClient } from './clients/attachments-client.js';
+export { AttachmentsClient, IMAGE_READ_MIME_TYPES, ImageReadResultSchema, } from './clients/attachments-client.js';
 export { ChannelsClient } from './clients/channels-client.js';
 export { CommentsClient } from './clients/comments-client.js';
 export { ConversationMessagesClient } from './clients/conversation-messages-client.js';

package/dist/esm/transport/fetch-with-retry.js

@@ -79,22 +79,30 @@ function describeTransportFailure(error, attempts) {
 }
 function describeCauseChain(error) {
     const descriptions = [];
-    const seen = new Set();
-    let current = error?.cause;
-    while (current instanceof Error &&
-        !seen.has(current) &&
-        descriptions.length < CAUSE_CHAIN_LIMIT) {
-        seen.add(current);
-        const description = describeCause(current);
+    for (const cause of causeChain(error)) {
+        const description = describeCause(cause);
         if (description) {
             descriptions.push(description);
         }
-        // A failed connect can carry one error per address it tried; the first
-        // one is representative and the rest are the same failure repeated.
+    }
+    return descriptions.length > 0 ? descriptions.join(' <- ') : undefined;
+}
+/**
+ * Walks an error's `cause` chain, stopping at {@link CAUSE_CHAIN_LIMIT} and on
+ * a cycle. A failed connect can carry one error per address it tried; the first
+ * is representative and the rest repeat the same failure.
+ */
+function* causeChain(error) {
+    const seen = new Set();
+    let current = error?.cause;
+    let depth = 0;
+    while (current instanceof Error && !seen.has(current) && depth < CAUSE_CHAIN_LIMIT) {
+        seen.add(current);
+        depth++;
+        yield current;
         const aggregated = current instanceof AggregateError ? current.errors[0] : undefined;
         current = aggregated ?? current.cause;
     }
-    return descriptions.length > 0 ? descriptions.join(' <- ') : undefined;
 }
 function describeCause(error) {
     const code = error.code;
@@ -134,13 +142,60 @@ function createTimeoutError(timeoutMs) {
     error.name = timeoutErrorName;
     return error;
 }
+/**
+ * Transport-level failure codes worth another attempt: the request never got an
+ * answer, so nothing about the response argues against retrying. `UND_ERR_SOCKET`
+ * covers the HTTP/2 `GOAWAY` an edge proxy sends when it retires a pooled
+ * connection, which is otherwise indistinguishable from any other `fetch failed`.
+ */
+const NETWORK_ERROR_CODES = new Set([
+    'ECONNREFUSED',
+    'ECONNRESET',
+    'EAI_AGAIN',
+    'ENOTFOUND',
+    'EPIPE',
+    'ETIMEDOUT',
+    'UND_ERR_SOCKET',
+]);
 function isNetworkError(error) {
     return (error.name === 'TypeError' ||
         error.name === timeoutErrorName ||
-        error.message.toLowerCase().includes('network'));
+        error.message.toLowerCase().includes('network') ||
+        hasNetworkErrorCode(error));
+}
+function hasNetworkErrorCode(error) {
+    // The code can be on the error itself — a `customFetch` is free to reject
+    // with one directly — or on anything `fetch` wrapped to produce it.
+    if (hasRetryableCode(error)) {
+        return true;
+    }
+    for (const cause of causeChain(error)) {
+        if (hasRetryableCode(cause)) {
+            return true;
+        }
+    }
+    return false;
 }
+function hasRetryableCode(error) {
+    const code = error.code;
+    return typeof code === 'string' && NETWORK_ERROR_CODES.has(code);
+}
+/** First retry delay, doubling by {@link RETRY_DELAY_FACTOR} per attempt. */
+const RETRY_BASE_DELAY_MS = 100;
+const RETRY_DELAY_FACTOR = 4;
+const RETRY_MAX_DELAY_MS = 2000;
+/**
+ * How long to wait before retry `retryCount` (1-based).
+ *
+ * A retired connection takes a moment to be torn down and replaced, so retrying
+ * immediately just re-dispatches onto the socket that is going away and burns
+ * the whole retry budget inside a second. The delay grows so the later attempts
+ * land on a fresh connection, and carries jitter because one retirement hits
+ * every pooled connection at once: without it, every caller reconnects in step.
+ */
 function getRetryDelay(retryCount) {
-    return retryCount === 1 ? 0 : 500;
+    const delay = Math.min(RETRY_BASE_DELAY_MS * RETRY_DELAY_FACTOR ** (retryCount - 1), RETRY_MAX_DELAY_MS);
+    return delay / 2 + Math.random() * (delay / 2);
 }
 function createTimeoutSignal(timeoutMs, existingSignal) {
     const controller = new AbortController();

package/dist/types/clients/attachments-client.d.ts

@@ -1,14 +1,29 @@
+import { z } from 'zod';
 import { type Attachment } from '../types/entities.js';
 import type { UploadAttachmentArgs } from '../types/requests.js';
 import { BaseClient } from './base-client.js';
+export declare const IMAGE_READ_MIME_TYPES: readonly ["image/jpeg", "image/png", "image/webp"];
+export type ImageReadMimeType = (typeof IMAGE_READ_MIME_TYPES)[number];
+export declare const ImageReadResultSchema: z.ZodObject<{
+    mimeType: z.ZodEnum<{
+        "image/png": "image/png";
+        "image/jpeg": "image/jpeg";
+        "image/webp": "image/webp";
+    }>;
+    dataBase64: z.ZodString;
+    byteLength: z.ZodNumber;
+}, z.core.$strip>;
+export type ImageReadResult = z.infer<typeof ImageReadResultSchema>;
 /**
- * Client for uploading file attachments to Comms.
+ * Client for uploading attachments and reading thread images.
  *
  * Attachments are uploaded independently, then referenced by passing the returned
  * {@link Attachment} into the `attachments` array of `comments.createComment`,
  * `conversationMessages.createMessage`, and similar calls.
  */
 export declare class AttachmentsClient extends BaseClient {
+    /** Read one thread image under the caller's content scope. */
+    readImage(uploadId: string, threadId: string): Promise<ImageReadResult>;
     /**
      * Uploads a file and returns the created {@link Attachment}.
      *

package/dist/types/consts/endpoints.d.ts

@@ -23,4 +23,5 @@ export declare const ENDPOINT_REACTIONS = "reactions";
 export declare const ENDPOINT_SEARCH = "search";
 export declare const ENDPOINT_CONVERSATION_MESSAGES = "conversation_messages";
 export declare const ENDPOINT_ATTACHMENTS = "attachments";
+export declare const ENDPOINT_FILES = "files";
 export declare const ENDPOINT_HOOKS = "hooks";

package/dist/types/index.d.ts

@@ -1,6 +1,6 @@
 export * from './authentication.js';
 export * from './migration.js';
-export { AttachmentsClient } from './clients/attachments-client.js';
+export { AttachmentsClient, IMAGE_READ_MIME_TYPES, ImageReadResultSchema, type ImageReadMimeType, type ImageReadResult, } from './clients/attachments-client.js';
 export { ChannelsClient } from './clients/channels-client.js';
 export { CommentsClient } from './clients/comments-client.js';
 export { ConversationMessagesClient } from './clients/conversation-messages-client.js';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@doist/comms-sdk",
-    "version": "3.0.1",
+    "version": "3.1.0",
     "description": "A TypeScript wrapper for the Comms REST API.",
     "author": "Doist developers",
     "homepage": "https://doist.github.io/comms-sdk-typescript/",