@forge/llm 0.0.1-experimental-994fcd3

package/LICENSE.txt

@@ -0,0 +1,7 @@
+Copyright (c) 2025 Atlassian
+Permission is hereby granted to use this software in accordance with the terms 
+and conditions outlined in the Atlassian Developer Terms, which can be found 
+at the following URL:
+https://developer.atlassian.com/platform/marketplace/atlassian-developer-terms/
+By using this software, you agree to comply with these terms and conditions. 
+If you do not agree with these terms, you are not permitted to use this software.

package/README.md

@@ -0,0 +1,98 @@
+# @forge/llm
+
+Library for Forge LLM
+
+
+## Usage Example
+
+
+### Sending a Prompt
+
+```typescript
+import { chat } from '@forge/llm';
+
+const prompt = {
+  model: 'claude-sonnet-4-20250514',
+  messages: [
+    {
+      role: 'user',
+      content: [
+        { type: 'text', text: 'What is the weather like in Melbourne?'}
+      ]
+    },
+    {
+      role: 'system',
+      content: [
+        { type: 'text', text: 'You are a helpful assistant.' }
+      ]
+    }
+  ],
+  temperature: 0.7,
+  max_completion_tokens: 1000,
+  top_p: 0.9,
+  tools: [
+    {
+      type: 'function',
+      function: {
+        name: 'get_current_weather',
+        description: 'Get the current weather in a given location',
+        parameters: {
+          type: 'object',
+          properties: {
+            location: {
+              type: 'string',
+              description: 'The city and state, e.g. San Francisco, CA'
+            },
+            unit: {
+              type: 'string',
+              enum: ['celsius', 'fahrenheit']
+            }
+          },
+          required: ['location']
+        }
+      }
+    }
+  ],
+  tool_choice: 'auto'
+};
+
+const response = await chat(prompt);
+```
+
+### Response Structure
+The response is a `ChatResponse` object:
+
+```json
+{
+  "choices": [
+    {
+      "finish_reason": "tool_use",
+      "message": {
+        "role": "assistant",
+        "content": [
+          {
+            "type": "text",
+            "text": "I'll help you check the weather in Melbourne using the WeatherTool." 
+          }
+        ],
+        "tool_calls": [
+          {
+            "id": "toolu_bdrk_019EF362R6946pMuFhpLHLif",
+            "type": "function",
+            "function": {
+              "name": "get_current_weather",
+              "arguments": {
+                "location": "San Francisco, CA",
+                "unit": "celsius"
+              }
+            }
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+### Errors
+The SDK throws validation and Forge Errors.

package/out/__test__/error-handling.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=error-handling.test.d.ts.map

package/out/__test__/error-handling.test.d.ts.map

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

package/out/__test__/error-handling.test.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const errors_1 = require("../errors");
+const error_handling_1 = require("../utils/error-handling");
+describe('Error Handling', () => {
+    it('should handle a 400 response and return a ForgeLlmAPIError', async () => {
+        const code = 'UNSUPPORTED_AI_MODEL';
+        const message = 'Requested claude-3-5-sonnet-v2@20241022 not available for vendor: Claude';
+        const traceId = 'trace-123';
+        const apiResponse = new Response(JSON.stringify({
+            code: code,
+            message: message
+        }), {
+            status: 400,
+            statusText: 'Bad Request',
+            headers: {
+                'x-trace-id': traceId,
+                'Forge-Proxy-Error': 'UNSUPPORTED_AI_MODEL'
+            }
+        });
+        await expect(async () => (0, error_handling_1.checkResponseError)(apiResponse)).rejects.toMatchError(new errors_1.ForgeLlmAPIError({
+            status: 400,
+            statusText: 'Bad Request',
+            traceId
+        }, { code, message }));
+    });
+    it('should handle an Unknown error, that is a Forge error, with empty body and return a ForgeLlmAPIError', async () => {
+        const code = 'UNKNOWN_ERROR';
+        const traceId = 'trace-123';
+        const apiResponse = new Response(undefined, {
+            status: 500,
+            statusText: 'Internal Server Error',
+            headers: {
+                'x-trace-id': traceId
+            }
+        });
+        await expect(async () => (0, error_handling_1.checkResponseError)(apiResponse)).rejects.toMatchError(new errors_1.ForgeLlmAPIError({
+            status: 500,
+            statusText: 'Internal Server Error',
+            traceId
+        }, { code, message: 'Unexpected error in Forge LLM API', context: { responseText: '' } }));
+    });
+    it('should handle an Unknown error response, that is not a Forge error, with a json body and return a ForgeLlmAPIError', async () => {
+        const code = 'UNKNOWN_ERROR';
+        const body = JSON.stringify({
+            unknownError: 'Unexpected error with a non-json body'
+        });
+        const traceId = 'trace-123';
+        const apiResponse = new Response(body, {
+            status: 500,
+            statusText: 'Internal Server Error',
+            headers: {
+                'x-trace-id': traceId
+            }
+        });
+        await expect(async () => (0, error_handling_1.checkResponseError)(apiResponse)).rejects.toMatchError(new errors_1.ForgeLlmAPIError({
+            status: 500,
+            statusText: 'Internal Server Error',
+            traceId
+        }, {
+            message: 'Unexpected error in Forge LLM API',
+            code: code,
+            context: {
+                responseText: body
+            }
+        }));
+    });
+    it('should include context fields in the error when provided by the API', async () => {
+        const code = 'QUOTA_EXCEEDED';
+        const message = 'You have exceeded your quota';
+        const context = { quota: '1000', usage: '1500' };
+        const traceId = 'trace-123';
+        const apiResponse = new Response(JSON.stringify({ code, message, context }), {
+            status: 500,
+            statusText: 'Internal Server Error',
+            headers: {
+                'x-trace-id': traceId
+            }
+        });
+        await expect(async () => (0, error_handling_1.checkResponseError)(apiResponse)).rejects.toMatchError(new errors_1.ForgeLlmAPIError({
+            status: 500,
+            statusText: 'Internal Server Error',
+            traceId
+        }, { code, message, context }));
+    });
+    it('should include any extra fields in the error context when provided by the API', async () => {
+        const code = 'QUOTA_EXCEEDED';
+        const message = 'You have exceeded your quota';
+        const context = { quota: '1000', usage: '1500' };
+        const extraFields = { retryAfter: 30, plan: 'pro' };
+        const traceId = 'trace-123';
+        const apiResponse = new Response(JSON.stringify({ code, message, context, ...extraFields }), {
+            status: 500,
+            statusText: 'Internal Server Error',
+            headers: {
+                'x-trace-id': traceId
+            }
+        });
+        await expect(async () => (0, error_handling_1.checkResponseError)(apiResponse)).rejects.toMatchError(new errors_1.ForgeLlmAPIError({
+            status: 500,
+            statusText: 'Internal Server Error',
+            traceId
+        }, { code, message, context, ...extraFields }));
+    });
+});

package/out/__test__/fetch-wrapper-test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=fetch-wrapper-test.d.ts.map

package/out/__test__/fetch-wrapper-test.d.ts.map

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

package/out/__test__/fetch-wrapper-test.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const fetch_wrapper_1 = require("../fetch-wrapper");
+describe('FetchWrapper', () => {
+    it('should construct the args correctly', async () => {
+        const mockFetch = jest.fn().mockResolvedValue({ status: 200 });
+        global.__forge_fetch__ = mockFetch;
+        const fetchWrapper = (0, fetch_wrapper_1.getFetchWrapper)();
+        await fetchWrapper('https://llm/model-id', { method: 'POST' });
+        expect(mockFetch).toHaveBeenCalledTimes(1);
+        const [firstArg] = mockFetch.mock.calls[0];
+        expect(firstArg).toEqual({ type: 'llm', model: 'model-id' });
+    });
+});

package/out/__test__/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

package/out/__test__/index.test.d.ts.map

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

package/out/__test__/index.test.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../index");
+const test_helpers_1 = require("./test-helpers");
+const llm_api_1 = require("../llm-api");
+const errors_1 = require("../errors");
+jest.mock('../../src/fetch-wrapper', () => ({
+    getFetchWrapper: jest.fn(() => 'FAKE_FETCH_WRAPPER')
+}));
+jest.mock('../../src/llm-api', () => {
+    return {
+        LlmApiImpl: jest.fn().mockImplementation(() => ({
+            chat: jest.fn(async (...promptArgs) => ({ inputArgs: promptArgs }))
+        }))
+    };
+});
+describe('Chat', () => {
+    it('should call LlmApiImpl.chat with provided prompt payload', async () => {
+        const promptPayload = (0, test_helpers_1.constructPrompt)();
+        const result = await (0, index_1.chat)(promptPayload);
+        const llmApi = llm_api_1.LlmApiImpl.mock.results[0].value;
+        expect(llmApi.chat).toHaveBeenCalledWith(promptPayload);
+        expect(result).toEqual({ inputArgs: [promptPayload] });
+    });
+    it('should propagate Forge errors returned', async () => {
+        const prompt = (0, test_helpers_1.constructPrompt)();
+        const llmApi = llm_api_1.LlmApiImpl.mock.results[0].value;
+        llmApi.chat.mockRejectedValueOnce(new errors_1.ForgeLlmAPIError({ status: 400, statusText: 'bad request' }, { code: 'INVALID_BODY', message: 'Bad request' }));
+        await expect((0, index_1.chat)(prompt)).rejects.toThrow(errors_1.ForgeLlmAPIError);
+    });
+    it('should propagate validation errors', async () => {
+        const prompt = 'invalid_prompt';
+        const llmApi = llm_api_1.LlmApiImpl.mock.results[0].value;
+        llmApi.chat.mockRejectedValueOnce(new errors_1.PromptValidationError('The payload is invalid: Prompt is required and must be a valid object.'));
+        await expect((0, index_1.chat)(prompt)).rejects.toThrow(errors_1.PromptValidationError);
+    });
+});

package/out/__test__/llm-api.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=llm-api.test.d.ts.map

package/out/__test__/llm-api.test.d.ts.map

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

package/out/__test__/llm-api.test.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const fetch_wrapper_1 = require("../fetch-wrapper");
+const llm_api_1 = require("../llm-api");
+const errors_1 = require("../errors");
+const test_helpers_1 = require("./test-helpers");
+function setupEnvironment(response) {
+    const mockedFetch = jest.fn().mockResolvedValue(response || new Response(null, { status: 200 }));
+    global.__forge_fetch__ = jest.fn((_ctx, path, options) => mockedFetch(path, options));
+}
+describe('llm api', () => {
+    it('should make ForgeLlm request', async () => {
+        const llmResponse = (0, test_helpers_1.constructLlmResponse)();
+        const apiResponse = new Response(JSON.stringify(llmResponse), {
+            status: 200
+        });
+        const mockedFetch = jest.fn().mockResolvedValue(apiResponse);
+        global.__forge_fetch__ = jest.fn((_ctx, path, options) => mockedFetch(path, options));
+        const llmAPI = new llm_api_1.LlmApiImpl((0, fetch_wrapper_1.getFetchWrapper)());
+        const promptBody = {
+            model: 'claude-sonnet-4-20250514',
+            messages: [
+                { role: 'user', content: [{ type: 'text', text: 'Hello, how are you?' }] },
+                { role: 'system', content: [{ type: 'text', text: 'You are a creative agent' }] }
+            ],
+            temperature: 0.7,
+            max_completion_tokens: 1000,
+            top_p: 0.9
+        };
+        const prompt = (0, test_helpers_1.constructPrompt)(promptBody);
+        await llmAPI.chat(prompt);
+        const [[path, options]] = mockedFetch.mock.calls;
+        expect(path).toBe('https://llm/claude-sonnet-4-20250514');
+        expect(options.method).toBe('POST');
+        expect(options.headers).toEqual({ 'Content-Type': 'application/json' });
+        expect(JSON.parse(options.body)).toEqual({
+            messages: [
+                {
+                    role: 'user',
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'Hello, how are you?'
+                        }
+                    ]
+                },
+                {
+                    role: 'system',
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'You are a creative agent'
+                        }
+                    ]
+                }
+            ],
+            temperature: 0.7,
+            max_completion_tokens: 1000,
+            top_p: 0.9
+        });
+    });
+    it('should throw a validation error when prompt is invalid', async () => {
+        const promptWithEmptyMessages = (0, test_helpers_1.constructPrompt)({ messages: [] });
+        const llmAPI = new llm_api_1.LlmApiImpl((0, fetch_wrapper_1.getFetchWrapper)());
+        await expect(llmAPI.chat(promptWithEmptyMessages)).rejects.toThrow(errors_1.PromptValidationError);
+    });
+    it('should return a ChatResponse for a 200 success response', async () => {
+        const llmResponse = (0, test_helpers_1.constructLlmResponse)({
+            finish_reason: 'tool_calls',
+            index: 19,
+            message: {
+                role: 'assistant',
+                content: [
+                    {
+                        type: 'text',
+                        text: "It's 20 degrees celsius"
+                    }
+                ]
+            }
+        });
+        const apiResponse = new Response(JSON.stringify(llmResponse), {
+            status: 200
+        });
+        setupEnvironment(apiResponse);
+        const llmAPI = new llm_api_1.LlmApiImpl((0, fetch_wrapper_1.getFetchWrapper)());
+        const prompt = (0, test_helpers_1.constructPrompt)();
+        const response = await llmAPI.chat(prompt);
+        expect(response.choices[0]).toEqual({
+            finish_reason: 'tool_calls',
+            message: {
+                content: [
+                    {
+                        type: 'text',
+                        text: "It's 20 degrees celsius"
+                    }
+                ],
+                role: 'assistant',
+                tool_calls: undefined
+            },
+            index: 19
+        });
+    });
+    it('should throw an error for a non-200 response', async () => {
+        const apiResponse = new Response(JSON.stringify({}), {
+            status: 400
+        });
+        setupEnvironment(apiResponse);
+        const llmAPI = new llm_api_1.LlmApiImpl((0, fetch_wrapper_1.getFetchWrapper)());
+        const prompt = (0, test_helpers_1.constructPrompt)();
+        await expect(llmAPI.chat(prompt)).rejects.toThrow(errors_1.ForgeLlmAPIError);
+    });
+});

package/out/__test__/response-mapper.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=response-mapper.test.d.ts.map

package/out/__test__/response-mapper.test.d.ts.map

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

package/out/__test__/response-mapper.test.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const response_mapper_1 = require("../response-mapper");
+const test_helpers_1 = require("./test-helpers");
+describe('response mapper', () => {
+    it('should map the Forge LLM response to a user response (choices empty)', async () => {
+        const llmResponseBody = { choices: [] };
+        const apiResponse = (0, test_helpers_1.makeApiResponse)({ json: () => Promise.resolve(llmResponseBody) });
+        const mappedResponse = await (0, response_mapper_1.mapForgeLLMResponse)(apiResponse);
+        expect(mappedResponse).toEqual({ choices: [] });
+    });
+    it('should map the Forge LLM response', async () => {
+        const llmResponseBody = {
+            choices: [
+                {
+                    finish_reason: 'tool_calls',
+                    index: 19,
+                    message: {
+                        role: 'assistant',
+                        content: [
+                            { type: 'text', text: 'It is warm outside' },
+                            { type: 'text', text: "It's 20 degrees celsius" }
+                        ],
+                        tool_calls: [
+                            {
+                                id: 'tool-call-123',
+                                type: 'function',
+                                function: {
+                                    name: 'WeatherTool',
+                                    arguments: {
+                                        location: 'San Francisco, CA',
+                                        unit: 'celsius'
+                                    }
+                                }
+                            }
+                        ]
+                    }
+                }
+            ]
+        };
+        const apiResponse = (0, test_helpers_1.makeApiResponse)({ json: () => Promise.resolve(llmResponseBody) });
+        const mappedResponse = await (0, response_mapper_1.mapForgeLLMResponse)(apiResponse);
+        expect(mappedResponse).toEqual({ choices: llmResponseBody.choices });
+    });
+});

package/out/__test__/test-helpers.d.ts

@@ -0,0 +1,19 @@
+import { Prompt } from '../interfaces/types';
+import { APIResponse } from '@forge/api';
+import { Choice } from '../interfaces/llm-api';
+export declare const constructPrompt: (overrides?: {}) => Prompt;
+export declare const makeApiResponse: (overrides: Partial<APIResponse>) => APIResponse;
+export declare const constructLlmResponse: (overrides?: Partial<Choice>) => {
+    choices: {
+        finish_reason: string;
+        index: number;
+        message: import("../interfaces/llm-api").AssistantMessage | {
+            role: string;
+            content: {
+                type: string;
+                text: string;
+            }[];
+        };
+    }[];
+};
+//# sourceMappingURL=test-helpers.d.ts.map

package/out/__test__/test-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-helpers.d.ts","sourceRoot":"","sources":["../../src/__test__/test-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE/C,eAAO,MAAM,eAAe,sBAAqB,MAU/C,CAAC;AAEH,eAAO,MAAM,eAAe,cAAe,QAAQ,WAAW,CAAC,KAAG,WAWjE,CAAC;AAEF,eAAO,MAAM,oBAAoB,eAAe,QAAQ,MAAM,CAAC;;;;;;;;;;;;CAiB7D,CAAC"}

package/out/__test__/test-helpers.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.constructLlmResponse = exports.makeApiResponse = exports.constructPrompt = void 0;
+const constructPrompt = (overrides = {}) => ({
+    model: 'claude-sonnet-4-20250514',
+    messages: [
+        { role: 'user', content: [{ type: 'text', text: 'Hello, how are you?' }] },
+        { role: 'system', content: [{ type: 'text', text: 'You are a creative agent' }] }
+    ],
+    temperature: 0.7,
+    max_completion_tokens: 1000,
+    top_p: 0.9,
+    ...overrides
+});
+exports.constructPrompt = constructPrompt;
+const makeApiResponse = (overrides) => {
+    return {
+        status: 200,
+        statusText: 'OK',
+        headers: new Headers({
+            'Content-Type': 'application/json'
+        }),
+        json: async () => Promise.resolve({}),
+        text: async () => JSON.stringify({}),
+        ...overrides
+    };
+};
+exports.makeApiResponse = makeApiResponse;
+const constructLlmResponse = (overrides = {}) => ({
+    choices: [
+        {
+            finish_reason: 'tool_calls',
+            message: {
+                role: 'assistant',
+                content: [
+                    {
+                        type: 'text',
+                        text: "It's 20 degrees celsius"
+                    }
+                ]
+            },
+            index: 19,
+            ...overrides
+        }
+    ]
+});
+exports.constructLlmResponse = constructLlmResponse;

package/out/__test__/validators.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=validators.test.d.ts.map

package/out/__test__/validators.test.d.ts.map

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

package/out/__test__/validators.test.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const validators_1 = require("../validators");
+const errors_1 = require("../errors");
+const test_helpers_1 = require("./test-helpers");
+describe('Validators', () => {
+    describe('required fields', () => {
+        it('should validate a correct prompt', () => {
+            const validPrompt = (0, test_helpers_1.constructPrompt)();
+            expect(() => (0, validators_1.validatePrompt)(validPrompt)).not.toThrow();
+        });
+        it('should fail if no prompt is provided', () => {
+            const emptyPrompt = undefined;
+            expect(() => (0, validators_1.validatePrompt)(emptyPrompt)).toMatchError(new errors_1.PromptValidationError('The payload is invalid: Prompt is required and must be a valid object.'));
+        });
+        describe('model validation', () => {
+            it('should throw an error for a missing model', () => {
+                const prompt = (0, test_helpers_1.constructPrompt)({ model: undefined });
+                expect(() => (0, validators_1.validatePrompt)(prompt)).toMatchError(new errors_1.PromptValidationError('The payload is invalid: Model is required.'));
+            });
+        });
+        describe('messages validation', () => {
+            it('should throw an error when no messages are provided', () => {
+                const prompt = (0, test_helpers_1.constructPrompt)({ messages: undefined });
+                expect(() => (0, validators_1.validatePrompt)(prompt)).toMatchError(new errors_1.PromptValidationError('The payload is invalid: No messages were provided. Please provide at least one message.'));
+            });
+            it('should throw an error when a message body is missing the role field', () => {
+                const prompt = (0, test_helpers_1.constructPrompt)({ messages: [{ content: 'Hello' }] });
+                expect(() => (0, validators_1.validatePrompt)(prompt)).toMatchError(new errors_1.PromptValidationError('The payload is invalid: Invalid role at index 0: . Role must be present and one of [system, user, assistant, tool].'));
+            });
+            it('should throw an error when a message body has an invalid role type', () => {
+                const prompt = (0, test_helpers_1.constructPrompt)({ messages: [{ content: 'Hello', role: 'unknown-role' }] });
+                expect(() => (0, validators_1.validatePrompt)(prompt)).toMatchError(new errors_1.PromptValidationError('The payload is invalid: Invalid role at index 0: unknown-role. Role must be present and one of [system, user, assistant, tool].'));
+            });
+            it('should throw an error when a message body is missing the content field', () => {
+                const prompt = (0, test_helpers_1.constructPrompt)({ messages: [{ role: 'user' }] });
+                expect(() => (0, validators_1.validatePrompt)(prompt)).toMatchError(new errors_1.PromptValidationError('The payload is invalid: Message content at index 0 must be a non-empty string.'));
+            });
+        });
+    });
+    describe('optional fields', () => {
+        describe('temperature validation', () => {
+            it('should throw an error for a temperature under 0', () => {
+                const prompt = (0, test_helpers_1.constructPrompt)({ temperature: -1 });
+                expect(() => (0, validators_1.validatePrompt)(prompt)).toMatchError(new errors_1.PromptValidationError('The payload is invalid: Invalid temperature -1: Temperature must be between 0 and 1.'));
+            });
+            it('should throw an error for a temperature above 1', () => {
+                const prompt = (0, test_helpers_1.constructPrompt)({ temperature: 2 });
+                expect(() => (0, validators_1.validatePrompt)(prompt)).toMatchError(new errors_1.PromptValidationError('The payload is invalid: Invalid temperature 2: Temperature must be between 0 and 1.'));
+            });
+            it('should not throw an error for a non-numeric temperature', () => {
+                const prompt = (0, test_helpers_1.constructPrompt)({ temperature: undefined });
+                expect(() => (0, validators_1.validatePrompt)(prompt)).not.toThrow();
+            });
+            it('should throw an error for a non-finite temperature', () => {
+                const prompt = (0, test_helpers_1.constructPrompt)({ temperature: 'NaN' });
+                expect(() => (0, validators_1.validatePrompt)(prompt)).toMatchError(new errors_1.PromptValidationError('The payload is invalid: Invalid temperature NaN: Temperature must be between 0 and 1.'));
+            });
+        });
+        describe('max_completion_tokens validation', () => {
+            const invalidValues = [NaN, 0, -5, 10.5];
+            invalidValues.forEach((value) => {
+                it(`should throw an error for invalid max_completion_tokens value ${value}`, () => {
+                    const prompt = (0, test_helpers_1.constructPrompt)({ max_completion_tokens: value });
+                    expect(() => (0, validators_1.validatePrompt)(prompt)).toMatchError(new errors_1.PromptValidationError(`The payload is invalid: Invalid max_completion_tokens ${value}: max_completion_tokens must be a positive integer.`));
+                });
+            });
+            it('should not throw when max_completion_tokens is undefined', () => {
+                const prompt = (0, test_helpers_1.constructPrompt)({ max_completion_tokens: undefined });
+                expect(() => (0, validators_1.validatePrompt)(prompt)).not.toThrow();
+            });
+            it('should not throw when max_completion_tokens is a valid positive integer', () => {
+                const prompt = (0, test_helpers_1.constructPrompt)({ max_completion_tokens: 256 });
+                expect(() => (0, validators_1.validatePrompt)(prompt)).not.toThrow();
+            });
+        });
+        describe('top_p validation', () => {
+            it('should not throw an error when top_p is not provided', () => {
+                const prompt = (0, test_helpers_1.constructPrompt)({ top_p: undefined });
+                expect(() => (0, validators_1.validatePrompt)(prompt)).not.toThrow();
+            });
+            it('should not throw an error for a valid top_p', () => {
+                const prompt = (0, test_helpers_1.constructPrompt)({ top_p: 0.9 });
+                expect(() => (0, validators_1.validatePrompt)(prompt)).not.toThrow();
+            });
+            const invalidTopPValues = [-0.1, 1.5, NaN, 'string'];
+            invalidTopPValues.forEach((value) => {
+                it(`should throw an error for invalid top_p value ${value}`, () => {
+                    const prompt = (0, test_helpers_1.constructPrompt)({ top_p: value });
+                    expect(() => (0, validators_1.validatePrompt)(prompt)).toMatchError(new errors_1.PromptValidationError(`The payload is invalid: Invalid top_p ${value}: top_p must be between 0 and 1.`));
+                });
+            });
+        });
+    });
+});

package/out/errors.d.ts

@@ -0,0 +1,28 @@
+export declare const errorCodes: {
+    readonly FORGE_LLM_API_ERROR: "FORGE_API_ERROR";
+    readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
+};
+export interface ForgeError {
+    code: string;
+    message: string;
+    context?: Record<string, unknown>;
+}
+export declare class ForgeLlmError extends Error {
+    constructor(message: string);
+}
+export declare class PromptValidationError extends ForgeLlmError {
+    constructor(message: string);
+}
+export interface APIErrorResponseDetails {
+    status: number;
+    statusText: string;
+    traceId?: string | null;
+}
+export declare class ForgeLlmAPIError extends ForgeLlmError {
+    responseDetails: APIErrorResponseDetails;
+    code: string;
+    message: string;
+    context: Record<string, unknown>;
+    constructor(responseDetails: APIErrorResponseDetails, forgeError: ForgeError);
+}
+//# sourceMappingURL=errors.d.ts.map

package/out/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,UAAU;;;CAGb,CAAC;AAEX,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,qBAAa,aAAc,SAAQ,KAAK;gBAC1B,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,qBAAsB,SAAQ,aAAa;gBAC1C,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,qBAAa,gBAAiB,SAAQ,aAAa;IACjD,eAAe,EAAE,uBAAuB,CAAC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAErB,eAAe,EAAE,uBAAuB,EAAE,UAAU,EAAE,UAAU;CAU7E"}

package/out/errors.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ForgeLlmAPIError = exports.PromptValidationError = exports.ForgeLlmError = exports.errorCodes = void 0;
+exports.errorCodes = {
+    FORGE_LLM_API_ERROR: 'FORGE_API_ERROR',
+    UNKNOWN_ERROR: 'UNKNOWN_ERROR'
+};
+class ForgeLlmError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ForgeLlmError';
+    }
+}
+exports.ForgeLlmError = ForgeLlmError;
+class PromptValidationError extends ForgeLlmError {
+    constructor(message) {
+        super(message);
+        this.name = 'PromptValidationError';
+    }
+}
+exports.PromptValidationError = PromptValidationError;
+class ForgeLlmAPIError extends ForgeLlmError {
+    responseDetails;
+    code;
+    message;
+    context;
+    constructor(responseDetails, forgeError) {
+        super(forgeError.message);
+        const { status, statusText, traceId } = responseDetails;
+        this.responseDetails = { status, statusText, traceId };
+        const { code, message, context, ...bodyData } = forgeError;
+        this.code = code || exports.errorCodes.FORGE_LLM_API_ERROR;
+        this.message = message;
+        this.context = { ...context, ...bodyData };
+    }
+}
+exports.ForgeLlmAPIError = ForgeLlmAPIError;

package/out/fetch-wrapper.d.ts

@@ -0,0 +1,3 @@
+import { FetchMethod } from '@forge/api';
+export declare function getFetchWrapper(): FetchMethod;
+//# sourceMappingURL=fetch-wrapper.d.ts.map

package/out/fetch-wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-wrapper.d.ts","sourceRoot":"","sources":["../src/fetch-wrapper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,WAAW,EAAe,MAAM,YAAY,CAAC;AAEnE,wBAAgB,eAAe,IAAI,WAAW,CAW7C"}

package/out/fetch-wrapper.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getFetchWrapper = void 0;
+function getFetchWrapper() {
+    return async function (path, options) {
+        const model = path?.split('/').pop();
+        return await global.__forge_fetch__({ type: 'llm', model: model }, path, {
+            ...options,
+            headers: {
+                ...options?.headers,
+                'Content-Type': 'application/json'
+            }
+        });
+    };
+}
+exports.getFetchWrapper = getFetchWrapper;

package/out/index.d.ts

@@ -0,0 +1,4 @@
+export * from './interfaces/types';
+export declare const chat: (prompt: import("./interfaces/types").Prompt) => Promise<import("./interfaces/llm-api").LlmResponse>;
+export default chat;
+//# sourceMappingURL=index.d.ts.map

package/out/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,oBAAoB,CAAC;AAInC,eAAO,MAAM,IAAI,sGAAoE,CAAC;AAEtF,eAAe,IAAI,CAAC"}

package/out/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.chat = void 0;
+const tslib_1 = require("tslib");
+const llm_api_1 = require("./llm-api");
+const fetch_wrapper_1 = require("./fetch-wrapper");
+tslib_1.__exportStar(require("./interfaces/types"), exports);
+const llmApi = new llm_api_1.LlmApiImpl((0, fetch_wrapper_1.getFetchWrapper)());
+const chat = (...args) => llmApi.chat(...args);
+exports.chat = chat;
+exports.default = exports.chat;

package/out/interfaces/llm-api.d.ts

@@ -0,0 +1,78 @@
+import { ChatResponse, Prompt } from './types';
+export interface LlmApi {
+    chat(prompt: Prompt): Promise<ChatResponse>;
+}
+export interface LlmRequest {
+    messages: Message[];
+    temperature?: number;
+    max_completion_tokens?: number;
+    top_p?: number;
+    tools?: Tool[] | undefined;
+    tool_choice?: ToolChoice;
+}
+export declare type Message = SystemMessage | UserMessage | AssistantMessage | ToolMessage;
+export interface Tool {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+export declare type ToolChoice = 'auto' | 'none' | 'required' | {
+    type: 'function';
+    function: {
+        name: string;
+    };
+};
+export interface LlmResponseTool {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: Record<string, unknown>;
+    };
+}
+export interface SystemMessage {
+    content: Content;
+    role: 'system';
+}
+export interface UserMessage {
+    content: Content;
+    role: 'user';
+}
+export interface ToolMessage {
+    content: Content;
+    role: 'tool';
+    tool_call_id?: string;
+    name?: string;
+}
+export interface AssistantMessage {
+    content: Content;
+    role: 'assistant';
+    tool_calls?: ToolCall[];
+}
+export interface ToolCall {
+    id: string;
+    type: 'function';
+    index: number;
+    function: {
+        name: string;
+        arguments: object;
+    };
+}
+export interface LlmResponse {
+    choices: Choice[];
+}
+export interface Choice {
+    finish_reason: string;
+    index?: number;
+    message: AssistantMessage;
+}
+export declare type Content = string | ContentPart[];
+export declare type ContentPart = TextPart;
+export interface TextPart {
+    type: 'text';
+    text: string;
+}
+//# sourceMappingURL=llm-api.d.ts.map

package/out/interfaces/llm-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-api.d.ts","sourceRoot":"","sources":["../../src/interfaces/llm-api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAE/C,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,IAAI,EAAE,GAAG,SAAS,CAAC;IAC3B,WAAW,CAAC,EAAE,UAAU,CAAC;CAC1B;AAED,oBAAY,OAAO,GAAG,aAAa,GAAG,WAAW,GAAG,gBAAgB,GAAG,WAAW,CAAC;AAEnF,MAAM,WAAW,IAAI;IACnB,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACrC,CAAC;CACH;AAED,oBAAY,UAAU,GAClB,MAAM,GACN,MAAM,GACN,UAAU,GACV;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;CACH,CAAC;AAEN,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,CAAC;CACH;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AACD,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,WAAW,CAAC;IAClB,UAAU,CAAC,EAAE,QAAQ,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,MAAM;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAED,oBAAY,OAAO,GAAG,MAAM,GAAG,WAAW,EAAE,CAAC;AAE7C,oBAAY,WAAW,GAAG,QAAQ,CAAC;AAEnC,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd"}

package/out/interfaces/llm-api.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/out/interfaces/types.d.ts

@@ -0,0 +1,10 @@
+import { ForgeLlmError, PromptValidationError } from '../errors';
+import { LlmRequest, LlmResponse, Message, Tool, ToolCall } from './llm-api';
+export declare type Prompt = LlmRequest & {
+    model: string;
+};
+export declare type ChatResponse = LlmResponse;
+export declare type ToolSchema = Tool;
+export type { Message, ToolCall };
+export { ForgeLlmError, PromptValidationError };
+//# sourceMappingURL=types.d.ts.map

package/out/interfaces/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/interfaces/types.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE7E,oBAAY,MAAM,GAAG,UAAU,GAAG;IAChC,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,oBAAY,YAAY,GAAG,WAAW,CAAC;AAEvC,oBAAY,UAAU,GAAG,IAAI,CAAC;AAE9B,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AAElC,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAE,CAAC"}

package/out/interfaces/types.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PromptValidationError = exports.ForgeLlmError = void 0;
+const errors_1 = require("../errors");
+Object.defineProperty(exports, "ForgeLlmError", { enumerable: true, get: function () { return errors_1.ForgeLlmError; } });
+Object.defineProperty(exports, "PromptValidationError", { enumerable: true, get: function () { return errors_1.PromptValidationError; } });

package/out/llm-api.d.ts

@@ -0,0 +1,10 @@
+import { FetchMethod } from '@forge/api';
+import { ChatResponse, Prompt } from './interfaces/types';
+import { LlmApi } from './interfaces/llm-api';
+export declare class LlmApiImpl implements LlmApi {
+    private readonly apiClient;
+    constructor(apiClient: FetchMethod);
+    chat: (prompt: Prompt) => Promise<ChatResponse>;
+    private buildForgeLlmUrl;
+}
+//# sourceMappingURL=llm-api.d.ts.map

package/out/llm-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-api.d.ts","sourceRoot":"","sources":["../src/llm-api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,WAAW,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE1D,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAI9C,qBAAa,UAAW,YAAW,MAAM;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAAT,SAAS,EAAE,WAAW;IAEnD,IAAI,WAAkB,MAAM,KAAG,QAAQ,YAAY,CAAC,CAelD;IAEF,OAAO,CAAC,gBAAgB;CAIzB"}

package/out/llm-api.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LlmApiImpl = void 0;
+const validators_1 = require("./validators");
+const response_mapper_1 = require("./response-mapper");
+const error_handling_1 = require("./utils/error-handling");
+class LlmApiImpl {
+    apiClient;
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+    }
+    chat = async (prompt) => {
+        (0, validators_1.validatePrompt)(prompt);
+        const { model, ...request } = prompt;
+        const forgeLlmUrl = this.buildForgeLlmUrl(model);
+        const response = await this.apiClient(forgeLlmUrl, {
+            method: 'POST',
+            body: JSON.stringify(request)
+        });
+        await (0, error_handling_1.checkResponseError)(response);
+        return await (0, response_mapper_1.mapForgeLLMResponse)(response);
+    };
+    buildForgeLlmUrl(model) {
+        const baseUrl = 'https://llm';
+        return `${baseUrl}/${encodeURIComponent(model)}`;
+    }
+}
+exports.LlmApiImpl = LlmApiImpl;

package/out/response-mapper.d.ts

@@ -0,0 +1,4 @@
+import { APIResponse } from '@forge/api';
+import { ChatResponse } from './interfaces/types';
+export declare const mapForgeLLMResponse: (response: APIResponse) => Promise<ChatResponse>;
+//# sourceMappingURL=response-mapper.d.ts.map

package/out/response-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-mapper.d.ts","sourceRoot":"","sources":["../src/response-mapper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGlD,eAAO,MAAM,mBAAmB,aAAoB,WAAW,KAAG,QAAQ,YAAY,CAIrF,CAAC"}

package/out/response-mapper.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapForgeLLMResponse = void 0;
+const mapForgeLLMResponse = async (response) => {
+    const jsonBody = await response.json();
+    const choices = jsonBody.choices ?? [];
+    return { choices };
+};
+exports.mapForgeLLMResponse = mapForgeLLMResponse;

package/out/text.d.ts

@@ -0,0 +1,15 @@
+export declare const Text: {
+    error: {
+        missingModel: string;
+        invalidTemperature: (temp: number) => string;
+        invalidTopP: (topP: number) => string;
+        invalidMaxCompletionTokens: (maxCompletionTokens: number) => string;
+        invalidRole: (index: number, role: string | undefined, expectedRoles: string) => string;
+        emptyMessageContent: (index: number) => string;
+        promptRequired: string;
+        noMessagesProvided: string;
+        invalidPayload: string;
+        unKnownError: string;
+    };
+};
+//# sourceMappingURL=text.d.ts.map

package/out/text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../src/text.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,IAAI;;;mCAGc,MAAM,KAAG,MAAM;4BACtB,MAAM,KAAG,MAAM;0DACe,MAAM,KAAG,MAAM;6BAE5C,MAAM,QAAQ,MAAM,GAAG,SAAS,iBAAiB,MAAM,KAAG,MAAM;qCAExD,MAAM,KAAG,MAAM;;;;;;CAM/C,CAAC"}

package/out/text.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Text = void 0;
+exports.Text = {
+    error: {
+        missingModel: `Model is required.`,
+        invalidTemperature: (temp) => `Invalid temperature ${temp}: Temperature must be between 0 and 1.`,
+        invalidTopP: (topP) => `Invalid top_p ${topP}: top_p must be between 0 and 1.`,
+        invalidMaxCompletionTokens: (maxCompletionTokens) => `Invalid max_completion_tokens ${maxCompletionTokens}: max_completion_tokens must be a positive integer.`,
+        invalidRole: (index, role, expectedRoles) => `Invalid role at index ${index}: ${role || ''}. Role must be present and one of [${expectedRoles}].`,
+        emptyMessageContent: (index) => `Message content at index ${index} must be a non-empty string.`,
+        promptRequired: 'Prompt is required and must be a valid object.',
+        noMessagesProvided: 'No messages were provided. Please provide at least one message.',
+        invalidPayload: 'The payload is invalid:',
+        unKnownError: 'Unexpected error in Forge LLM API'
+    }
+};

package/out/utils/error-handling.d.ts

@@ -0,0 +1,6 @@
+import { ForgeError } from '../errors';
+import { APIResponse } from '@forge/api';
+export declare function isForgeError(body: unknown): body is ForgeError;
+export declare function checkResponseError(response: APIResponse): Promise<void>;
+export declare function safeGetParsedBody(text: string): unknown | undefined;
+//# sourceMappingURL=error-handling.d.ts.map

package/out/utils/error-handling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handling.d.ts","sourceRoot":"","sources":["../../src/utils/error-handling.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuC,UAAU,EAAoB,MAAM,WAAW,CAAC;AAE9F,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAMzC,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,UAAU,CAE9D;AAED,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAwB7E;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAMnE"}

package/out/utils/error-handling.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeGetParsedBody = exports.checkResponseError = exports.isForgeError = void 0;
+const errors_1 = require("../errors");
+const text_1 = require("../text");
+function extractTraceId(response) {
+    return response.headers.get('x-b3-traceid') || response.headers.get('x-trace-id');
+}
+function isForgeError(body) {
+    return typeof body === 'object' && body !== null && 'code' in body && 'message' in body;
+}
+exports.isForgeError = isForgeError;
+async function checkResponseError(response) {
+    if (response.ok) {
+        return;
+    }
+    const responseText = await response.text();
+    const parsedBody = safeGetParsedBody(responseText);
+    const statusText = response.statusText;
+    const traceId = extractTraceId(response);
+    const responseDetails = {
+        status: response.status,
+        statusText,
+        traceId
+    };
+    if (parsedBody && isForgeError(parsedBody)) {
+        throw new errors_1.ForgeLlmAPIError(responseDetails, parsedBody);
+    }
+    throw new errors_1.ForgeLlmAPIError(responseDetails, {
+        code: errors_1.errorCodes.UNKNOWN_ERROR,
+        message: text_1.Text.error.unKnownError,
+        context: { responseText }
+    });
+}
+exports.checkResponseError = checkResponseError;
+function safeGetParsedBody(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+exports.safeGetParsedBody = safeGetParsedBody;

package/out/validators.d.ts

@@ -0,0 +1,4 @@
+import { Prompt } from './interfaces/types';
+export declare const ChatRoles: readonly ["system", "user", "assistant", "tool"];
+export declare const validatePrompt: (prompt: Prompt) => void;
+//# sourceMappingURL=validators.d.ts.map

package/out/validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../src/validators.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAK5C,eAAO,MAAM,SAAS,kDAAmD,CAAC;AA4F1E,eAAO,MAAM,cAAc,WAAY,MAAM,KAAG,IAQ/C,CAAC"}

package/out/validators.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validatePrompt = exports.ChatRoles = void 0;
+const errors_1 = require("./errors");
+const text_1 = require("./text");
+exports.ChatRoles = ['system', 'user', 'assistant', 'tool'];
+function promptIsPresent(value) {
+    return value !== null && typeof value === 'object';
+}
+function validateModel(model) {
+    const errors = [];
+    if (!model) {
+        errors.push(text_1.Text.error.missingModel);
+    }
+    return errors;
+}
+function validateTemperature(temperature) {
+    const errors = [];
+    if (temperature !== undefined && (!Number.isFinite(temperature) || temperature < 0 || temperature > 1)) {
+        errors.push(text_1.Text.error.invalidTemperature(temperature));
+    }
+    return errors;
+}
+function validateMaxCompletionTokens(maxCompletionTokens) {
+    const errors = [];
+    if (maxCompletionTokens !== undefined && (!Number.isInteger(maxCompletionTokens) || maxCompletionTokens <= 0)) {
+        errors.push(text_1.Text.error.invalidMaxCompletionTokens(maxCompletionTokens));
+    }
+    return errors;
+}
+function validateMessages(messages) {
+    const errors = [];
+    if (messages === undefined || !Array.isArray(messages) || messages.length === 0) {
+        errors.push(text_1.Text.error.noMessagesProvided);
+    }
+    else {
+        messages.forEach((m, messagesIndex) => {
+            if (!isRequestMessage(m)) {
+                errors.push(text_1.Text.error.noMessagesProvided);
+                return;
+            }
+            if (!isValidChatRole(m)) {
+                errors.push(text_1.Text.error.invalidRole(messagesIndex, m.role, getChatRoles()));
+            }
+            if (!isValidChatContent(m)) {
+                errors.push(text_1.Text.error.emptyMessageContent(messagesIndex));
+            }
+        });
+    }
+    return errors;
+}
+function isRequestMessage(value) {
+    return value !== null && typeof value === 'object';
+}
+function isValidChatRole(msg) {
+    return 'role' in msg && typeof msg.role === 'string' && msg.role.trim().length > 0 && exports.ChatRoles.includes(msg.role);
+}
+function isValidChatContent(msg) {
+    return 'content' in msg && typeof msg.content !== undefined;
+}
+function getChatRoles() {
+    return exports.ChatRoles.join(', ');
+}
+function validateTopP(topP) {
+    const errors = [];
+    if (topP !== undefined && (!Number.isFinite(topP) || topP < 0 || topP > 1)) {
+        errors.push(text_1.Text.error.invalidTopP(topP));
+    }
+    return errors;
+}
+const validatorFns = [
+    (p) => validateModel(p.model),
+    (p) => validateTemperature(p.temperature),
+    (p) => validateMaxCompletionTokens(p.max_completion_tokens),
+    (p) => validateMessages(p.messages),
+    (p) => validateTopP(p.top_p)
+];
+function getValidationErrors(prompt) {
+    return validatorFns.flatMap((fn) => fn(prompt));
+}
+const validatePrompt = (prompt) => {
+    if (!promptIsPresent(prompt)) {
+        throw new errors_1.PromptValidationError(`${text_1.Text.error.invalidPayload} ${text_1.Text.error.promptRequired}`);
+    }
+    const errors = getValidationErrors(prompt);
+    if (errors.length > 0) {
+        throw new errors_1.PromptValidationError(`${text_1.Text.error.invalidPayload} ${errors.join('; ')}`);
+    }
+};
+exports.validatePrompt = validatePrompt;

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@forge/llm",
+  "version": "0.0.1-experimental-994fcd3",
+  "description": "Forge LLM SDK",
+  "main": "out/index.js",
+  "types": "out/index.d.ts",
+  "files": [
+    "out"
+  ],
+  "author": "Atlassian",
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "dependencies": {
+    "@forge/api": "^6.2.0-next.1-experimental-994fcd3"
+  },
+  "devDependencies": {
+    "@types/node": "20.19.1",
+    "expect-type": "^0.17.3",
+    "jest-when": "^3.6.0"
+  },
+  "scripts": {
+    "build": "yarn run clean && yarn run compile",
+    "clean": "rm -rf ./out && rm -f tsconfig.tsbuildinfo",
+    "compile": "tsc -b -v"
+  },
+  "publishConfig": {
+    "registry": "https://packages.atlassian.com/api/npm/npm-public/"
+  }
+}