@doist/twist-sdk 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Doist
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,222 @@
+# Twist SDK TypeScript
+
+<p align="center">
+  <img src="./website/static/img/twist-logo.png" alt="Twist Logo" width="100" />
+</p>
+
+This is the official TypeScript SDK for the Twist REST API.
+
+## Installation
+
+```bash
+npm install @doist/twist-sdk
+```
+
+## Usage
+
+An example of initializing the API client and fetching a user's information:
+
+```typescript
+import { TwistApi } from '@doist/twist-sdk'
+
+const api = new TwistApi('YOUR_API_TOKEN')
+
+api.users.getSessionUser()
+    .then((user) => console.log(user))
+    .catch((error) => console.log(error))
+```
+
+### OAuth 2.0 Authentication
+
+For applications that need to access user data, use OAuth 2.0:
+
+```typescript
+import { getAuthorizationUrl, getAuthToken, TwistApi } from '@doist/twist-sdk'
+
+// Step 1: Generate authorization URL
+const authUrl = getAuthorizationUrl(
+    'your-client-id',
+    ['user:read', 'channels:read'],
+    'state-parameter',
+    'https://yourapp.com/callback'
+)
+
+// Step 2: Exchange authorization code for access token
+const tokenResponse = await getAuthToken({
+    clientId: 'your-client-id',
+    clientSecret: 'your-client-secret',
+    code: 'authorization-code',
+    redirectUri: 'https://yourapp.com/callback'
+})
+
+// Step 3: Use the access token
+const api = new TwistApi(tokenResponse.accessToken)
+const user = await api.users.getSessionUser()
+```
+
+### Batch Requests
+
+The SDK supports making multiple API calls in a single HTTP request using the `/batch` endpoint. This can significantly improve performance when you need to fetch or update multiple resources.
+
+**Note:** Batch requests are completely optional. If you only need to make a single API call, simply call the method normally without the `{ batch: true }` option.
+
+#### How It Works
+
+To use batch requests:
+
+1. Pass `{ batch: true }` as the last parameter to any API method
+2. This returns a `BatchRequestDescriptor` instead of executing the request immediately
+3. Pass multiple descriptors to `api.batch()` to execute them together
+
+```typescript
+// Single requests (normal usage)
+const user1 = await api.workspaceUsers.getUserById(123, 456)
+const user2 = await api.workspaceUsers.getUserById(123, 789)
+
+// Batch requests - executes in a single HTTP call
+const results = await api.batch(
+    api.workspaceUsers.getUserById(123, 456, { batch: true }),
+    api.workspaceUsers.getUserById(123, 789, { batch: true })
+)
+
+console.log(results[0].data.name) // First user
+console.log(results[1].data.name) // Second user
+```
+
+#### Response Structure
+
+Each item in the batch response includes:
+
+- `code` - HTTP status code for that specific request (e.g., 200, 404)
+- `headers` - Response headers as a key-value object
+- `data` - The parsed and validated response data
+
+```typescript
+const results = await api.batch(
+    api.channels.getChannel(123, { batch: true }),
+    api.channels.getChannel(456, { batch: true })
+)
+
+results.forEach((result) => {
+    if (result.code === 200) {
+        console.log('Success:', result.data.name)
+    } else {
+        console.error('Error:', result.code)
+    }
+})
+```
+
+#### Performance Optimization
+
+When all requests in a batch are GET requests, they are executed in parallel on the server for optimal performance. Mixed GET and POST requests are executed sequentially.
+
+```typescript
+// These GET requests execute in parallel
+const results = await api.batch(
+    api.workspaceUsers.getUserById(123, 456, { batch: true }),
+    api.channels.getChannel(789, { batch: true }),
+    api.threads.getThread(101112, { batch: true })
+)
+```
+
+#### Mixing Different API Calls
+
+You can batch requests across different resource types:
+
+```typescript
+const results = await api.batch(
+    api.workspaceUsers.getUserById(123, 456, { batch: true }),
+    api.channels.getChannels({ workspaceId: 123 }, { batch: true }),
+    api.conversations.getConversations({ workspaceId: 123 }, { batch: true })
+)
+
+const [user, channels, conversations] = results
+// TypeScript maintains proper types for each result
+console.log(user.data.name)
+console.log(channels.data.length)
+console.log(conversations.data.length)
+```
+
+#### Error Handling
+
+Individual requests in a batch can fail independently. Always check the status code of each result:
+
+```typescript
+const results = await api.batch(
+    api.channels.getChannel(123, { batch: true }),
+    api.channels.getChannel(999999, { batch: true }) // Non-existent channel
+)
+
+results.forEach((result, index) => {
+    if (result.code >= 200 && result.code < 300) {
+        console.log(`Request ${index} succeeded:`, result.data)
+    } else {
+        console.error(`Request ${index} failed with status ${result.code}`)
+    }
+})
+```
+
+## Documentation
+
+For detailed documentation, visit the [Twist SDK Documentation](https://doist.github.io/twist-sdk-typescript/).
+
+For information about the Twist REST API, see the [Twist API Documentation](https://developer.twist.com/v3/).
+
+## Development and Testing
+
+This project uses [ts-node](https://github.com/TypeStrong/ts-node) for local development and testing.
+
+- `npm install`
+- Add a file named `scratch.ts` in the `src` folder
+- Configure your IDE to run the scratch file with `ts-node` (instructions for [VSCode](https://medium.com/@dupski/debug-typescript-in-vs-code-without-compiling-using-ts-node-9d1f4f9a94a), [WebStorm](https://www.jetbrains.com/help/webstorm/running-and-debugging-typescript.html#ws_ts_run_debug_server_side_ts_node)), or run it directly: `npx ts-node ./src/scratch.ts`
+
+Example scratch.ts file:
+
+```typescript
+import { TwistApi } from './twist-api'
+
+const token = 'YOUR_API_TOKEN'
+const api = new TwistApi(token)
+
+api.workspaces.getWorkspaces()
+    .then((workspaces) => {
+        console.log(workspaces)
+    })
+    .catch((error) => console.error(error))
+```
+
+## Scripts
+
+- `npm test` - Run tests
+- `npm run test:watch` - Run tests in watch mode
+- `npm run test:coverage` - Run tests with coverage
+- `npm run build` - Build the package
+- `npm run type-check` - Type check without building
+- `npm run lint:check` - Check code style
+- `npm run format:check` - Check formatting
+
+## Releases
+
+This package follows semantic versioning. Currently in alpha release (0.1.0-alpha.x).
+
+A new version is published to the NPM Registry whenever a new release on GitHub is created. The workflow automatically detects prerelease versions (alpha, beta, rc) and publishes them with the appropriate tag.
+
+To prepare a new release:
+
+```bash
+# For alpha releases
+npm version prerelease --preid=alpha --no-git-tag-version
+
+# For stable releases
+npm version <major|minor|patch> --no-git-tag-version
+```
+
+Once the version in `package.json` is updated, push the changes and create a GitHub release. The workflow will automatically publish to npm with the correct tag.
+
+## Feedback
+
+Any feedback, such as bugs, questions, comments, etc. can be reported as _Issues_ in this repository, and will be handled by the Doist team.
+
+## Contributions
+
+We welcome contributions in the form of _Pull requests_ in this repository.

package/dist/authentication.d.ts

@@ -0,0 +1,79 @@
+/**
+ * OAuth scopes for the Twist API.
+ *
+ * @remarks
+ * Request only the scopes your application needs:
+ *
+ * **User Scopes:**
+ * - `user:read` - Access user's personal settings
+ * - `user:write` - Access and update user's personal settings
+ *
+ * **Workspace Scopes:**
+ * - `workspaces:read` - Access teams the user is part of
+ * - `workspaces:write` - Access and update teams the user is part of
+ *
+ * **Channel Scopes:**
+ * - `channels:read` - Access channels
+ * - `channels:write` - Access and update channels
+ * - `channels:remove` - Access, update, and delete channels
+ *
+ * **Thread Scopes:**
+ * - `threads:read` - Access threads
+ * - `threads:write` - Access and update threads
+ * - `threads:remove` - Access, update, and delete threads
+ *
+ * **Comment Scopes:**
+ * - `comments:read` - Access comments
+ * - `comments:write` - Access and update comments
+ * - `comments:remove` - Access, update, and delete comments
+ *
+ * **Group Scopes:**
+ * - `groups:read` - Access groups
+ * - `groups:write` - Access and update groups
+ * - `groups:remove` - Access, update, and delete groups
+ *
+ * **Message Scopes:**
+ * - `messages:read` - Access messages
+ * - `messages:write` - Access and update messages
+ * - `messages:remove` - Access, update, and delete messages
+ *
+ * **Reaction Scopes:**
+ * - `reactions:read` - Access reactions
+ * - `reactions:write` - Access and update reactions
+ * - `reactions:remove` - Access, update, and delete reactions
+ *
+ * **Search Scopes:**
+ * - `search:read` - Search
+ *
+ * **Attachment Scopes:**
+ * - `attachments:read` - Access attachments
+ * - `attachments:write` - Access and update attachments
+ *
+ * **Notification Scopes:**
+ * - `notifications:read` - Read user's notifications settings
+ * - `notifications:write` - Read and update user's notifications settings
+ */
+export type TwistScope = 'user:read' | 'user:write' | 'workspaces:read' | 'workspaces:write' | 'channels:read' | 'channels:write' | 'channels:remove' | 'threads:read' | 'threads:write' | 'threads:remove' | 'comments:read' | 'comments:write' | 'comments:remove' | 'groups:read' | 'groups:write' | 'groups:remove' | 'messages:read' | 'messages:write' | 'messages:remove' | 'reactions:read' | 'reactions:write' | 'reactions:remove' | 'search:read' | 'attachments:read' | 'attachments:write' | 'notifications:read' | 'notifications:write';
+export type AuthTokenRequestArgs = {
+    clientId: string;
+    clientSecret: string;
+    code: string;
+    redirectUri?: string;
+};
+export type AuthTokenResponse = {
+    accessToken: string;
+    tokenType: string;
+    refreshToken?: string;
+    expiresIn?: number;
+    scope?: string;
+};
+export type RevokeAuthTokenRequestArgs = {
+    clientId: string;
+    clientSecret: string;
+    accessToken: string;
+};
+export declare function getAuthStateParameter(): string;
+export declare function getAuthorizationUrl(clientId: string, scopes: TwistScope[], state: string, redirectUri?: string, baseUrl?: string): string;
+export declare function getAuthToken(args: AuthTokenRequestArgs, baseUrl?: string): Promise<AuthTokenResponse>;
+export declare function revokeAuthToken(args: RevokeAuthTokenRequestArgs, baseUrl?: string): Promise<boolean>;
+//# sourceMappingURL=authentication.d.ts.map

package/dist/authentication.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authentication.d.ts","sourceRoot":"","sources":["../src/authentication.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,MAAM,MAAM,UAAU,GAChB,WAAW,GACX,YAAY,GACZ,iBAAiB,GACjB,kBAAkB,GAClB,eAAe,GACf,gBAAgB,GAChB,iBAAiB,GACjB,cAAc,GACd,eAAe,GACf,gBAAgB,GAChB,eAAe,GACf,gBAAgB,GAChB,iBAAiB,GACjB,aAAa,GACb,cAAc,GACd,eAAe,GACf,eAAe,GACf,gBAAgB,GAChB,iBAAiB,GACjB,gBAAgB,GAChB,iBAAiB,GACjB,kBAAkB,GAClB,aAAa,GACb,kBAAkB,GAClB,mBAAmB,GACnB,oBAAoB,GACpB,qBAAqB,CAAA;AAE3B,MAAM,MAAM,oBAAoB,GAAG;IAC/B,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC5B,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,0BAA0B,GAAG;IACrC,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,WAAW,EAAE,MAAM,CAAA;CACtB,CAAA;AAED,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED,wBAAgB,mBAAmB,CAC/B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,UAAU,EAAE,EACpB,KAAK,EAAE,MAAM,EACb,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,MAAM,GACjB,MAAM,CAmBR;AAED,wBAAsB,YAAY,CAC9B,IAAI,EAAE,oBAAoB,EAC1B,OAAO,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,iBAAiB,CAAC,CAsB5B;AAED,wBAAsB,eAAe,CACjC,IAAI,EAAE,0BAA0B,EAChC,OAAO,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC,CAUlB"}

package/dist/authentication.js

@@ -0,0 +1,115 @@
+"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.getAuthStateParameter = getAuthStateParameter;
+exports.getAuthorizationUrl = getAuthorizationUrl;
+exports.getAuthToken = getAuthToken;
+exports.revokeAuthToken = revokeAuthToken;
+var uuid_1 = require("uuid");
+var rest_client_1 = require("./rest-client");
+var errors_1 = require("./types/errors");
+function getAuthStateParameter() {
+    return (0, uuid_1.v4)();
+}
+function getAuthorizationUrl(clientId, scopes, state, redirectUri, baseUrl) {
+    if (!(scopes === null || scopes === void 0 ? void 0 : scopes.length)) {
+        throw new Error('At least one scope value is required.');
+    }
+    var authBaseUrl = baseUrl ? "".concat(baseUrl, "/oauth") : 'https://twist.com/oauth';
+    var scope = scopes.join(' ');
+    var params = new URLSearchParams({
+        client_id: clientId,
+        response_type: 'code',
+        scope: scope,
+        state: state,
+    });
+    if (redirectUri) {
+        params.append('redirect_uri', redirectUri);
+    }
+    return "".concat(authBaseUrl, "/authorize?").concat(params.toString());
+}
+function getAuthToken(args, baseUrl) {
+    return __awaiter(this, void 0, void 0, function () {
+        var tokenUrl, payload, response;
+        var _a;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0:
+                    tokenUrl = baseUrl ? "".concat(baseUrl, "/oauth/token") : 'https://twist.com/oauth/token';
+                    payload = __assign({ clientId: args.clientId, clientSecret: args.clientSecret, code: args.code, grantType: 'authorization_code' }, (args.redirectUri && { redirectUri: args.redirectUri }));
+                    return [4 /*yield*/, (0, rest_client_1.request)('POST', tokenUrl, '', undefined, payload)];
+                case 1:
+                    response = _b.sent();
+                    if (!(0, rest_client_1.isSuccess)(response) || !((_a = response.data) === null || _a === void 0 ? void 0 : _a.accessToken)) {
+                        throw new errors_1.TwistRequestError('Authentication token exchange failed.', response.status, response.data);
+                    }
+                    return [2 /*return*/, response.data];
+            }
+        });
+    });
+}
+function revokeAuthToken(args, baseUrl) {
+    return __awaiter(this, void 0, void 0, function () {
+        var revokeUrl, response;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    revokeUrl = baseUrl ? "".concat(baseUrl, "/oauth/revoke") : 'https://twist.com/oauth/revoke';
+                    return [4 /*yield*/, (0, rest_client_1.request)('POST', revokeUrl, '', undefined, {
+                            clientId: args.clientId,
+                            clientSecret: args.clientSecret,
+                            token: args.accessToken,
+                        })];
+                case 1:
+                    response = _a.sent();
+                    return [2 /*return*/, (0, rest_client_1.isSuccess)(response)];
+            }
+        });
+    });
+}

package/dist/authentication.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authentication.test.d.ts","sourceRoot":"","sources":["../src/authentication.test.ts"],"names":[],"mappings":""}

package/dist/batch-builder.d.ts

@@ -0,0 +1,27 @@
+import type { BatchRequestDescriptor, BatchResponseArray } from './types/batch';
+/**
+ * Executes multiple API requests in a single HTTP call.
+ *
+ * @example
+ * ```typescript
+ * const results = await api.batch(
+ *   api.workspaceUsers.getUserById(123, 456, { batch: true }),
+ *   api.workspaceUsers.getUserById(123, 789, { batch: true })
+ * )
+ * ```
+ */
+export declare class BatchBuilder {
+    private apiToken;
+    private baseUrl?;
+    constructor(apiToken: string, baseUrl?: string | undefined);
+    private getBaseUri;
+    /**
+     * Executes an array of batch request descriptors in a single API call.
+     *
+     * @param requests - Array of batch request descriptors
+     * @returns Array of BatchResponse objects with processed data
+     * @throws {TwistRequestError} If the batch request fails
+     */
+    execute<T extends readonly BatchRequestDescriptor<unknown>[]>(requests: T): Promise<BatchResponseArray<T>>;
+}
+//# sourceMappingURL=batch-builder.d.ts.map

package/dist/batch-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-builder.d.ts","sourceRoot":"","sources":["../src/batch-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAoB,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAKjG;;;;;;;;;;GAUG;AACH,qBAAa,YAAY;IAEjB,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,OAAO,CAAC;gBADR,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,YAAA;IAG5B,OAAO,CAAC,UAAU;IAIlB;;;;;;OAMG;IACG,OAAO,CAAC,CAAC,SAAS,SAAS,sBAAsB,CAAC,OAAO,CAAC,EAAE,EAC9D,QAAQ,EAAE,CAAC,GACZ,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;CAyHpC"}

package/dist/batch-builder.js

@@ -0,0 +1,191 @@
+"use strict";
+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.BatchBuilder = void 0;
+var errors_1 = require("./types/errors");
+var case_conversion_1 = require("./utils/case-conversion");
+var timestamp_conversion_1 = require("./utils/timestamp-conversion");
+/**
+ * Executes multiple API requests in a single HTTP call.
+ *
+ * @example
+ * ```typescript
+ * const results = await api.batch(
+ *   api.workspaceUsers.getUserById(123, 456, { batch: true }),
+ *   api.workspaceUsers.getUserById(123, 789, { batch: true })
+ * )
+ * ```
+ */
+var BatchBuilder = /** @class */ (function () {
+    function BatchBuilder(apiToken, baseUrl) {
+        this.apiToken = apiToken;
+        this.baseUrl = baseUrl;
+    }
+    BatchBuilder.prototype.getBaseUri = function () {
+        return this.baseUrl ? "".concat(this.baseUrl, "/api/v3") : 'https://api.twist.com/api/v3/';
+    };
+    /**
+     * Executes an array of batch request descriptors in a single API call.
+     *
+     * @param requests - Array of batch request descriptors
+     * @returns Array of BatchResponse objects with processed data
+     * @throws {TwistRequestError} If the batch request fails
+     */
+    BatchBuilder.prototype.execute = function (requests) {
+        return __awaiter(this, void 0, void 0, function () {
+            var batchRequests, allGets, formData, response, errorText, batchApiResponses;
+            var _this = this;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        if (requests.length === 0) {
+                            return [2 /*return*/, []];
+                        }
+                        batchRequests = requests.map(function (descriptor) {
+                            // Convert params to snake_case
+                            var snakeCaseParams = descriptor.params
+                                ? (0, case_conversion_1.snakeCaseKeys)(descriptor.params)
+                                : undefined;
+                            // Build the full URL with query params for GET requests
+                            var url = "".concat(_this.getBaseUri()).concat(descriptor.url);
+                            if (descriptor.method === 'GET' && snakeCaseParams) {
+                                var searchParams_1 = new URLSearchParams();
+                                Object.entries(snakeCaseParams).forEach(function (_a) {
+                                    var key = _a[0], value = _a[1];
+                                    if (value != null) {
+                                        if (Array.isArray(value)) {
+                                            searchParams_1.append(key, value.join(','));
+                                        }
+                                        else {
+                                            searchParams_1.append(key, String(value));
+                                        }
+                                    }
+                                });
+                                var queryString = searchParams_1.toString();
+                                if (queryString) {
+                                    url += "?".concat(queryString);
+                                }
+                            }
+                            return {
+                                method: descriptor.method,
+                                url: url,
+                            };
+                        });
+                        allGets = batchRequests.every(function (req) { return req.method === 'GET'; });
+                        formData = new URLSearchParams();
+                        formData.append('requests', JSON.stringify(batchRequests));
+                        if (allGets) {
+                            formData.append('parallel', 'true');
+                        }
+                        return [4 /*yield*/, fetch("".concat(this.getBaseUri(), "batch"), {
+                                method: 'POST',
+                                headers: {
+                                    'Content-Type': 'application/x-www-form-urlencoded',
+                                    Authorization: "Bearer ".concat(this.apiToken),
+                                },
+                                body: formData.toString(),
+                            })];
+                    case 1:
+                        response = _a.sent();
+                        if (!!response.ok) return [3 /*break*/, 3];
+                        return [4 /*yield*/, response.text()];
+                    case 2:
+                        errorText = _a.sent();
+                        throw new errors_1.TwistRequestError("Batch request failed with status ".concat(response.status), response.status, errorText);
+                    case 3: return [4 /*yield*/, response.json()
+                        // Process each response
+                    ];
+                    case 4:
+                        batchApiResponses = _a.sent();
+                        // Process each response
+                        return [2 /*return*/, batchApiResponses.map(function (apiResponse, index) {
+                                var descriptor = requests[index];
+                                // Parse the body JSON
+                                var parsedBody;
+                                try {
+                                    parsedBody = apiResponse.body ? JSON.parse(apiResponse.body) : undefined;
+                                }
+                                catch (_error) {
+                                    parsedBody = apiResponse.body;
+                                }
+                                // Apply transformations: camelCase -> timestamps
+                                var camelCased = (0, case_conversion_1.camelCaseKeys)(parsedBody);
+                                var transformed = (0, timestamp_conversion_1.transformTimestamps)(camelCased);
+                                // Validate with schema if provided
+                                var finalData = transformed;
+                                if (descriptor.schema && apiResponse.code >= 200 && apiResponse.code < 300) {
+                                    try {
+                                        finalData = descriptor.schema.parse(transformed);
+                                    }
+                                    catch (error) {
+                                        // If validation fails, include the error in the response
+                                        console.error('Batch response validation failed:', error);
+                                    }
+                                }
+                                // Parse headers string into object
+                                var headers = {};
+                                if (apiResponse.headers && typeof apiResponse.headers === 'string') {
+                                    try {
+                                        var headerLines = apiResponse.headers.split('\n');
+                                        headerLines.forEach(function (line) {
+                                            var separatorIndex = line.indexOf(':');
+                                            if (separatorIndex > 0) {
+                                                var key = line.substring(0, separatorIndex).trim();
+                                                var value = line.substring(separatorIndex + 1).trim();
+                                                headers[key] = value;
+                                            }
+                                        });
+                                    }
+                                    catch (error) {
+                                        // If header parsing fails, just leave headers empty
+                                        console.error('Failed to parse batch response headers:', error);
+                                    }
+                                }
+                                return {
+                                    code: apiResponse.code,
+                                    headers: headers,
+                                    data: finalData,
+                                };
+                            })];
+                }
+            });
+        });
+    };
+    return BatchBuilder;
+}());
+exports.BatchBuilder = BatchBuilder;

package/dist/batch-builder.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-builder.test.d.ts","sourceRoot":"","sources":["../src/batch-builder.test.ts"],"names":[],"mappings":""}