@doist/twist-sdk 2.8.1 → 2.9.0

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

@@ -0,0 +1,124 @@
+"use strict";
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AttachmentsClient = void 0;
+var uuid_1 = require("uuid");
+var endpoints_1 = require("../consts/endpoints");
+var entities_1 = require("../types/entities");
+var multipart_upload_1 = require("../utils/multipart-upload");
+var base_client_1 = require("./base-client");
+/**
+ * Client for uploading file attachments to Twist.
+ *
+ * Attachments are uploaded independently, then referenced by passing the returned
+ * {@link Attachment} into the `attachments` array of `comments.createComment`,
+ * `conversationMessages.createMessage`, and similar calls.
+ */
+var AttachmentsClient = /** @class */ (function (_super) {
+    __extends(AttachmentsClient, _super);
+    function AttachmentsClient() {
+        return _super !== null && _super.apply(this, arguments) || this;
+    }
+    /**
+     * Uploads a file and returns the created {@link Attachment}.
+     *
+     * Mirrors the canonical multipart upload used by twist-web: `POST /attachments/upload`
+     * with the `file` binary plus `file_name`, `file_size`, `attachment_id`, and
+     * `underlying_type` form fields.
+     *
+     * @param args - The file to upload and optional metadata.
+     * @returns The created attachment, ready to attach to a comment or message.
+     *
+     * @example
+     * ```typescript
+     * import { readFile } from 'node:fs/promises'
+     *
+     * const attachment = await api.attachments.upload({
+     *   file: await readFile('./diagram.png'),
+     *   fileName: 'diagram.png',
+     * })
+     *
+     * await api.comments.createComment({
+     *   threadId: 789,
+     *   content: 'See attached',
+     *   attachments: [attachment],
+     * })
+     * ```
+     */
+    AttachmentsClient.prototype.upload = function (args) {
+        return __awaiter(this, void 0, void 0, function () {
+            var data;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, (0, multipart_upload_1.uploadMultipartFile)({
+                            baseUrl: this.getBaseUri(),
+                            authToken: this.apiToken,
+                            endpoint: "".concat(endpoints_1.ENDPOINT_ATTACHMENTS, "/upload"),
+                            file: args.file,
+                            fileName: args.fileName,
+                            contentType: args.contentType,
+                            additionalFields: {
+                                attachment_id: args.attachmentId || (0, uuid_1.v4)(),
+                            },
+                            customFetch: this.customFetch,
+                        })];
+                    case 1:
+                        data = _a.sent();
+                        return [2 /*return*/, entities_1.AttachmentSchema.parse(data)];
+                }
+            });
+        });
+    };
+    return AttachmentsClient;
+}(base_client_1.BaseClient));
+exports.AttachmentsClient = AttachmentsClient;

package/dist/cjs/consts/endpoints.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ENDPOINT_CONVERSATION_MESSAGES = exports.ENDPOINT_SEARCH = exports.ENDPOINT_REACTIONS = exports.ENDPOINT_INBOX = exports.ENDPOINT_NOTIFICATIONS = exports.ENDPOINT_COMMENTS = exports.ENDPOINT_CONVERSATIONS = exports.ENDPOINT_GROUPS = exports.ENDPOINT_THREADS = exports.ENDPOINT_CHANNELS = exports.ENDPOINT_WORKSPACES = exports.ENDPOINT_USERS = exports.API_BASE_URI = exports.API_VERSION = void 0;
+exports.ENDPOINT_ATTACHMENTS = exports.ENDPOINT_CONVERSATION_MESSAGES = exports.ENDPOINT_SEARCH = exports.ENDPOINT_REACTIONS = exports.ENDPOINT_INBOX = exports.ENDPOINT_NOTIFICATIONS = exports.ENDPOINT_COMMENTS = exports.ENDPOINT_CONVERSATIONS = exports.ENDPOINT_GROUPS = exports.ENDPOINT_THREADS = exports.ENDPOINT_CHANNELS = exports.ENDPOINT_WORKSPACES = exports.ENDPOINT_USERS = exports.API_BASE_URI = exports.API_VERSION = void 0;
 exports.getTwistBaseUri = getTwistBaseUri;
 var api_version_1 = require("../types/api-version");
 var BASE_URI = 'https://api.twist.com';
@@ -33,3 +33,4 @@ exports.ENDPOINT_INBOX = 'inbox';
 exports.ENDPOINT_REACTIONS = 'reactions';
 exports.ENDPOINT_SEARCH = 'search';
 exports.ENDPOINT_CONVERSATION_MESSAGES = 'conversation_messages';
+exports.ENDPOINT_ATTACHMENTS = 'attachments';

package/dist/cjs/index.js

@@ -14,10 +14,12 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TwistApi = exports.SearchClient = exports.ReactionsClient = exports.InboxClient = exports.ConversationMessagesClient = exports.BatchBuilder = void 0;
+exports.TwistApi = exports.SearchClient = exports.ReactionsClient = exports.InboxClient = exports.ConversationMessagesClient = exports.AttachmentsClient = exports.BatchBuilder = void 0;
 __exportStar(require("./authentication"), exports);
 var batch_builder_1 = require("./batch-builder");
 Object.defineProperty(exports, "BatchBuilder", { enumerable: true, get: function () { return batch_builder_1.BatchBuilder; } });
+var attachments_client_1 = require("./clients/attachments-client");
+Object.defineProperty(exports, "AttachmentsClient", { enumerable: true, get: function () { return attachments_client_1.AttachmentsClient; } });
 var conversation_messages_client_1 = require("./clients/conversation-messages-client");
 Object.defineProperty(exports, "ConversationMessagesClient", { enumerable: true, get: function () { return conversation_messages_client_1.ConversationMessagesClient; } });
 var inbox_client_1 = require("./clients/inbox-client");

package/dist/cjs/twist-api.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TwistApi = void 0;
 var batch_builder_1 = require("./batch-builder");
+var attachments_client_1 = require("./clients/attachments-client");
 var channels_client_1 = require("./clients/channels-client");
 var comments_client_1 = require("./clients/comments-client");
 var conversation_messages_client_1 = require("./clients/conversation-messages-client");
@@ -73,6 +74,7 @@ var TwistApi = /** @class */ (function () {
         this.inbox = new inbox_client_1.InboxClient(clientConfig);
         this.reactions = new reactions_client_1.ReactionsClient(clientConfig);
         this.search = new search_client_1.SearchClient(clientConfig);
+        this.attachments = new attachments_client_1.AttachmentsClient(clientConfig);
     }
     /**
      * Executes multiple API requests in a single HTTP call using the batch endpoint.

package/dist/cjs/utils/multipart-upload.js

@@ -0,0 +1,154 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getContentTypeFromFileName = getContentTypeFromFileName;
+exports.uploadMultipartFile = uploadMultipartFile;
+var fetch_with_retry_1 = require("../transport/fetch-with-retry");
+/**
+ * Determine a content-type from a filename extension. Falls back to
+ * `application/octet-stream` for unknown extensions.
+ */
+function getContentTypeFromFileName(fileName) {
+    var extension = fileName.toLowerCase().split('.').pop();
+    switch (extension) {
+        case 'png':
+            return 'image/png';
+        case 'jpg':
+        case 'jpeg':
+            return 'image/jpeg';
+        case 'gif':
+            return 'image/gif';
+        case 'webp':
+            return 'image/webp';
+        case 'svg':
+            return 'image/svg+xml';
+        case 'pdf':
+            return 'application/pdf';
+        default:
+            return 'application/octet-stream';
+    }
+}
+/**
+ * Normalise a supported {@link UploadFile} into a `Blob` plus a resolved file name and
+ * content type, so uploads use the cross-platform global `FormData`/`Blob` body that
+ * `undici` and browsers both accept natively.
+ */
+function toBlob(file, fileName, contentType) {
+    if (file instanceof Blob) {
+        // `File` is not a global in Node 18, so guard the check before using it.
+        var name_1 = fileName ||
+            (typeof File !== 'undefined' && file instanceof File ? file.name : undefined) ||
+            'upload';
+        var type = contentType || file.type || getContentTypeFromFileName(name_1);
+        // Re-wrap only when stamping a type the Blob doesn't already carry.
+        var blob = file.type === type ? file : new Blob([file], { type: type });
+        return { blob: blob, fileName: name_1, contentType: type };
+    }
+    if (file instanceof Uint8Array) {
+        if (!fileName) {
+            throw new Error('fileName is required when uploading raw bytes');
+        }
+        var type = contentType || getContentTypeFromFileName(fileName);
+        // `Blob` accepts any `ArrayBufferView`; the cast satisfies the stricter lib
+        // `BlobPart` type (which pins the backing buffer to `ArrayBuffer`).
+        return { blob: new Blob([file], { type: type }), fileName: fileName, contentType: type };
+    }
+    throw new Error('Unsupported file type for upload: expected a Blob or Uint8Array');
+}
+/**
+ * Upload a file using `multipart/form-data`.
+ *
+ * Builds the request body with the global `FormData`/`Blob` so it works unchanged in the
+ * browser and in Node.js (via `undici`). The `file` part is sent alongside `file_name`,
+ * `file_size`, and `underlying_type` fields (the canonical Twist upload shape); any
+ * `additionalFields` are merged in and override the derived values. Authentication uses
+ * `Authorization: Bearer`, matching every other Twist SDK client, and `Content-Type` is
+ * intentionally left unset so the runtime adds the correct multipart boundary.
+ *
+ * The response is JSON-parsed and camel-cased by {@link fetchWithRetry}; callers validate
+ * the returned shape with the appropriate schema.
+ */
+function uploadMultipartFile(args) {
+    return __awaiter(this, void 0, void 0, function () {
+        var baseUrl, authToken, endpoint, file, fileName, contentType, additionalFields, requestId, customFetch, _a, blob, resolvedFileName, resolvedType, fields, form, _i, _b, _c, key, value, headers, url, response;
+        return __generator(this, function (_d) {
+            switch (_d.label) {
+                case 0:
+                    baseUrl = args.baseUrl, authToken = args.authToken, endpoint = args.endpoint, file = args.file, fileName = args.fileName, contentType = args.contentType, additionalFields = args.additionalFields, requestId = args.requestId, customFetch = args.customFetch;
+                    _a = toBlob(file, fileName, contentType), blob = _a.blob, resolvedFileName = _a.fileName, resolvedType = _a.contentType;
+                    fields = __assign({ file_name: resolvedFileName, file_size: blob.size, underlying_type: resolvedType }, additionalFields);
+                    form = new FormData();
+                    form.append('file', blob, resolvedFileName);
+                    for (_i = 0, _b = Object.entries(fields); _i < _b.length; _i++) {
+                        _c = _b[_i], key = _c[0], value = _c[1];
+                        if (value !== undefined && value !== null) {
+                            form.append(key, String(value));
+                        }
+                    }
+                    headers = {
+                        Authorization: "Bearer ".concat(authToken),
+                    };
+                    if (requestId) {
+                        headers['X-Request-Id'] = requestId;
+                    }
+                    url = new URL(endpoint, baseUrl).toString();
+                    return [4 /*yield*/, (0, fetch_with_retry_1.fetchWithRetry)(url, {
+                            method: 'POST',
+                            headers: headers,
+                            body: form,
+                            // Don't set Content-Type — the runtime adds the multipart boundary.
+                            timeout: 30000,
+                        }, 3, customFetch)];
+                case 1:
+                    response = _d.sent();
+                    return [2 /*return*/, response.data];
+            }
+        });
+    });
+}

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

@@ -0,0 +1,121 @@
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+import { v4 as uuid } from 'uuid';
+import { ENDPOINT_ATTACHMENTS } from '../consts/endpoints.js';
+import { AttachmentSchema } from '../types/entities.js';
+import { uploadMultipartFile } from '../utils/multipart-upload.js';
+import { BaseClient } from './base-client.js';
+/**
+ * Client for uploading file attachments to Twist.
+ *
+ * Attachments are uploaded independently, then referenced by passing the returned
+ * {@link Attachment} into the `attachments` array of `comments.createComment`,
+ * `conversationMessages.createMessage`, and similar calls.
+ */
+var AttachmentsClient = /** @class */ (function (_super) {
+    __extends(AttachmentsClient, _super);
+    function AttachmentsClient() {
+        return _super !== null && _super.apply(this, arguments) || this;
+    }
+    /**
+     * Uploads a file and returns the created {@link Attachment}.
+     *
+     * Mirrors the canonical multipart upload used by twist-web: `POST /attachments/upload`
+     * with the `file` binary plus `file_name`, `file_size`, `attachment_id`, and
+     * `underlying_type` form fields.
+     *
+     * @param args - The file to upload and optional metadata.
+     * @returns The created attachment, ready to attach to a comment or message.
+     *
+     * @example
+     * ```typescript
+     * import { readFile } from 'node:fs/promises'
+     *
+     * const attachment = await api.attachments.upload({
+     *   file: await readFile('./diagram.png'),
+     *   fileName: 'diagram.png',
+     * })
+     *
+     * await api.comments.createComment({
+     *   threadId: 789,
+     *   content: 'See attached',
+     *   attachments: [attachment],
+     * })
+     * ```
+     */
+    AttachmentsClient.prototype.upload = function (args) {
+        return __awaiter(this, void 0, void 0, function () {
+            var data;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, uploadMultipartFile({
+                            baseUrl: this.getBaseUri(),
+                            authToken: this.apiToken,
+                            endpoint: "".concat(ENDPOINT_ATTACHMENTS, "/upload"),
+                            file: args.file,
+                            fileName: args.fileName,
+                            contentType: args.contentType,
+                            additionalFields: {
+                                attachment_id: args.attachmentId || uuid(),
+                            },
+                            customFetch: this.customFetch,
+                        })];
+                    case 1:
+                        data = _a.sent();
+                        return [2 /*return*/, AttachmentSchema.parse(data)];
+                }
+            });
+        });
+    };
+    return AttachmentsClient;
+}(BaseClient));
+export { AttachmentsClient };

package/dist/esm/consts/endpoints.js

@@ -29,3 +29,4 @@ export var ENDPOINT_INBOX = 'inbox';
 export var ENDPOINT_REACTIONS = 'reactions';
 export var ENDPOINT_SEARCH = 'search';
 export var ENDPOINT_CONVERSATION_MESSAGES = 'conversation_messages';
+export var ENDPOINT_ATTACHMENTS = 'attachments';

package/dist/esm/index.js

@@ -1,5 +1,6 @@
 export * from './authentication.js';
 export { BatchBuilder } from './batch-builder.js';
+export { AttachmentsClient } from './clients/attachments-client.js';
 export { ConversationMessagesClient } from './clients/conversation-messages-client.js';
 export { InboxClient } from './clients/inbox-client.js';
 export { ReactionsClient } from './clients/reactions-client.js';

package/dist/esm/twist-api.js

@@ -1,4 +1,5 @@
 import { BatchBuilder } from './batch-builder.js';
+import { AttachmentsClient } from './clients/attachments-client.js';
 import { ChannelsClient } from './clients/channels-client.js';
 import { CommentsClient } from './clients/comments-client.js';
 import { ConversationMessagesClient } from './clients/conversation-messages-client.js';
@@ -70,6 +71,7 @@ var TwistApi = /** @class */ (function () {
         this.inbox = new InboxClient(clientConfig);
         this.reactions = new ReactionsClient(clientConfig);
         this.search = new SearchClient(clientConfig);
+        this.attachments = new AttachmentsClient(clientConfig);
     }
     /**
      * Executes multiple API requests in a single HTTP call using the batch endpoint.

package/dist/esm/utils/multipart-upload.js

@@ -0,0 +1,150 @@
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+import { fetchWithRetry } from '../transport/fetch-with-retry.js';
+/**
+ * Determine a content-type from a filename extension. Falls back to
+ * `application/octet-stream` for unknown extensions.
+ */
+export function getContentTypeFromFileName(fileName) {
+    var extension = fileName.toLowerCase().split('.').pop();
+    switch (extension) {
+        case 'png':
+            return 'image/png';
+        case 'jpg':
+        case 'jpeg':
+            return 'image/jpeg';
+        case 'gif':
+            return 'image/gif';
+        case 'webp':
+            return 'image/webp';
+        case 'svg':
+            return 'image/svg+xml';
+        case 'pdf':
+            return 'application/pdf';
+        default:
+            return 'application/octet-stream';
+    }
+}
+/**
+ * Normalise a supported {@link UploadFile} into a `Blob` plus a resolved file name and
+ * content type, so uploads use the cross-platform global `FormData`/`Blob` body that
+ * `undici` and browsers both accept natively.
+ */
+function toBlob(file, fileName, contentType) {
+    if (file instanceof Blob) {
+        // `File` is not a global in Node 18, so guard the check before using it.
+        var name_1 = fileName ||
+            (typeof File !== 'undefined' && file instanceof File ? file.name : undefined) ||
+            'upload';
+        var type = contentType || file.type || getContentTypeFromFileName(name_1);
+        // Re-wrap only when stamping a type the Blob doesn't already carry.
+        var blob = file.type === type ? file : new Blob([file], { type: type });
+        return { blob: blob, fileName: name_1, contentType: type };
+    }
+    if (file instanceof Uint8Array) {
+        if (!fileName) {
+            throw new Error('fileName is required when uploading raw bytes');
+        }
+        var type = contentType || getContentTypeFromFileName(fileName);
+        // `Blob` accepts any `ArrayBufferView`; the cast satisfies the stricter lib
+        // `BlobPart` type (which pins the backing buffer to `ArrayBuffer`).
+        return { blob: new Blob([file], { type: type }), fileName: fileName, contentType: type };
+    }
+    throw new Error('Unsupported file type for upload: expected a Blob or Uint8Array');
+}
+/**
+ * Upload a file using `multipart/form-data`.
+ *
+ * Builds the request body with the global `FormData`/`Blob` so it works unchanged in the
+ * browser and in Node.js (via `undici`). The `file` part is sent alongside `file_name`,
+ * `file_size`, and `underlying_type` fields (the canonical Twist upload shape); any
+ * `additionalFields` are merged in and override the derived values. Authentication uses
+ * `Authorization: Bearer`, matching every other Twist SDK client, and `Content-Type` is
+ * intentionally left unset so the runtime adds the correct multipart boundary.
+ *
+ * The response is JSON-parsed and camel-cased by {@link fetchWithRetry}; callers validate
+ * the returned shape with the appropriate schema.
+ */
+export function uploadMultipartFile(args) {
+    return __awaiter(this, void 0, void 0, function () {
+        var baseUrl, authToken, endpoint, file, fileName, contentType, additionalFields, requestId, customFetch, _a, blob, resolvedFileName, resolvedType, fields, form, _i, _b, _c, key, value, headers, url, response;
+        return __generator(this, function (_d) {
+            switch (_d.label) {
+                case 0:
+                    baseUrl = args.baseUrl, authToken = args.authToken, endpoint = args.endpoint, file = args.file, fileName = args.fileName, contentType = args.contentType, additionalFields = args.additionalFields, requestId = args.requestId, customFetch = args.customFetch;
+                    _a = toBlob(file, fileName, contentType), blob = _a.blob, resolvedFileName = _a.fileName, resolvedType = _a.contentType;
+                    fields = __assign({ file_name: resolvedFileName, file_size: blob.size, underlying_type: resolvedType }, additionalFields);
+                    form = new FormData();
+                    form.append('file', blob, resolvedFileName);
+                    for (_i = 0, _b = Object.entries(fields); _i < _b.length; _i++) {
+                        _c = _b[_i], key = _c[0], value = _c[1];
+                        if (value !== undefined && value !== null) {
+                            form.append(key, String(value));
+                        }
+                    }
+                    headers = {
+                        Authorization: "Bearer ".concat(authToken),
+                    };
+                    if (requestId) {
+                        headers['X-Request-Id'] = requestId;
+                    }
+                    url = new URL(endpoint, baseUrl).toString();
+                    return [4 /*yield*/, fetchWithRetry(url, {
+                            method: 'POST',
+                            headers: headers,
+                            body: form,
+                            // Don't set Content-Type — the runtime adds the multipart boundary.
+                            timeout: 30000,
+                        }, 3, customFetch)];
+                case 1:
+                    response = _d.sent();
+                    return [2 /*return*/, response.data];
+            }
+        });
+    });
+}

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

@@ -0,0 +1,39 @@
+import { type Attachment } from '../types/entities.js';
+import type { UploadAttachmentArgs } from '../types/requests.js';
+import { BaseClient } from './base-client.js';
+/**
+ * Client for uploading file attachments to Twist.
+ *
+ * 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 {
+    /**
+     * Uploads a file and returns the created {@link Attachment}.
+     *
+     * Mirrors the canonical multipart upload used by twist-web: `POST /attachments/upload`
+     * with the `file` binary plus `file_name`, `file_size`, `attachment_id`, and
+     * `underlying_type` form fields.
+     *
+     * @param args - The file to upload and optional metadata.
+     * @returns The created attachment, ready to attach to a comment or message.
+     *
+     * @example
+     * ```typescript
+     * import { readFile } from 'node:fs/promises'
+     *
+     * const attachment = await api.attachments.upload({
+     *   file: await readFile('./diagram.png'),
+     *   fileName: 'diagram.png',
+     * })
+     *
+     * await api.comments.createComment({
+     *   threadId: 789,
+     *   content: 'See attached',
+     *   attachments: [attachment],
+     * })
+     * ```
+     */
+    upload(args: UploadAttachmentArgs): Promise<Attachment>;
+}

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

@@ -24,3 +24,4 @@ export declare const ENDPOINT_INBOX = "inbox";
 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";

package/dist/types/index.d.ts

@@ -1,5 +1,6 @@
 export * from './authentication.js';
 export { BatchBuilder } from './batch-builder.js';
+export { AttachmentsClient } from './clients/attachments-client.js';
 export { ConversationMessagesClient } from './clients/conversation-messages-client.js';
 export { InboxClient } from './clients/inbox-client.js';
 export { ReactionsClient } from './clients/reactions-client.js';

package/dist/types/twist-api.d.ts

@@ -1,3 +1,4 @@
+import { AttachmentsClient } from './clients/attachments-client.js';
 import { ChannelsClient } from './clients/channels-client.js';
 import { CommentsClient } from './clients/comments-client.js';
 import { ConversationMessagesClient } from './clients/conversation-messages-client.js';
@@ -42,6 +43,7 @@ export declare class TwistApi {
     inbox: InboxClient;
     reactions: ReactionsClient;
     search: SearchClient;
+    attachments: AttachmentsClient;
     private authToken;
     private baseUrl?;
     private customFetch?;

package/dist/types/types/requests.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import type { UploadFile } from '../utils/multipart-upload.js';
 import { type Attachment } from './entities.js';
 export declare const CreateChannelArgsSchema: z.ZodObject<{
     workspaceId: z.ZodNumber;
@@ -375,4 +376,20 @@ export type GetUserLocalTimeArgs = {
     workspaceId: number;
     userId: number;
 };
+export type UploadAttachmentArgs = {
+    /**
+     * The file to upload. Accepts a `Blob`/`File` (browser) or a `Uint8Array` of raw
+     * bytes. A Node `Buffer` is a `Uint8Array`, so `await readFile(path)` works directly.
+     */
+    file: UploadFile;
+    /**
+     * File name. Required when `file` is a `Uint8Array`; inferred from the `File.name`
+     * otherwise.
+     */
+    fileName?: string;
+    /** MIME type. Defaults to the `Blob`'s type or one inferred from the file extension. */
+    contentType?: string;
+    /** Attachment ID to use. A random UUID is generated when omitted. */
+    attachmentId?: string;
+};
 export {};

package/dist/types/utils/multipart-upload.d.ts

@@ -0,0 +1,53 @@
+import type { CustomFetch } from '../types/http.js';
+/**
+ * File content accepted by the upload helpers.
+ *
+ * - `Blob`/`File` — browser, or any runtime with a global `Blob` (Node 18+).
+ * - `Uint8Array` — raw bytes (requires `fileName`). A Node `Buffer` is a `Uint8Array`,
+ *   so reading a file with `fs` and passing the result works without conversion.
+ *
+ * Both are universal types, so the published `.d.ts` stays free of Node-only globals
+ * (`Buffer`, `NodeJS.*`) and the helper pulls in no Node built-ins — keeping the browser
+ * bundle clean.
+ */
+export type UploadFile = Blob | Uint8Array;
+type UploadMultipartFileArgs = {
+    /** Base API URI with trailing slash, e.g. `https://api.twist.com/api/v3/`. */
+    baseUrl: string;
+    /** API token used for `Authorization: Bearer`. */
+    authToken: string;
+    /** Relative endpoint path, e.g. `attachments/upload`. */
+    endpoint: string;
+    /** File content to upload. */
+    file: UploadFile;
+    /** File name. Required for raw `Uint8Array` bytes; inferred from a `File`. */
+    fileName?: string;
+    /** MIME type. Defaults to the `Blob`'s type or one inferred from the file extension. */
+    contentType?: string;
+    /** Extra multipart fields to send alongside the file metadata fields. */
+    additionalFields?: Record<string, string | number | boolean | undefined | null>;
+    /** Optional request ID for tracing. */
+    requestId?: string;
+    /** Optional custom fetch implementation. */
+    customFetch?: CustomFetch;
+};
+/**
+ * Determine a content-type from a filename extension. Falls back to
+ * `application/octet-stream` for unknown extensions.
+ */
+export declare function getContentTypeFromFileName(fileName: string): string;
+/**
+ * Upload a file using `multipart/form-data`.
+ *
+ * Builds the request body with the global `FormData`/`Blob` so it works unchanged in the
+ * browser and in Node.js (via `undici`). The `file` part is sent alongside `file_name`,
+ * `file_size`, and `underlying_type` fields (the canonical Twist upload shape); any
+ * `additionalFields` are merged in and override the derived values. Authentication uses
+ * `Authorization: Bearer`, matching every other Twist SDK client, and `Content-Type` is
+ * intentionally left unset so the runtime adds the correct multipart boundary.
+ *
+ * The response is JSON-parsed and camel-cased by {@link fetchWithRetry}; callers validate
+ * the returned shape with the appropriate schema.
+ */
+export declare function uploadMultipartFile<T>(args: UploadMultipartFileArgs): Promise<T>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@doist/twist-sdk",
-    "version": "2.8.1",
+    "version": "2.9.0",
     "description": "A TypeScript wrapper for the Twist REST API.",
     "author": "Doist developers",
     "homepage": "https://doist.github.io/twist-sdk-typescript/",