@harborclient/team-hub-api 0.1.1

package/dist/TeamHubClient.js

@@ -0,0 +1,665 @@
+import { TeamHubClientError } from './TeamHubClientError.js';
+import { collectionRecordSchema, environmentRecordSchema, errorResponseSchema, folderRecordSchema, healthResponseSchema, listCollectionsResponseSchema, listEnvironmentsResponseSchema, listFoldersResponseSchema, listHubLlmModelsResponseSchema, pluginSourcesResponseSchema, listRequestsResponseSchema, hubChatStepResponseSchema, savedRequestRecordSchema, sessionResponseSchema, listAdminUsersResponseSchema, listAdminCollectionsResponseSchema, listAdminEnvironmentsResponseSchema, adminEntityConfigSchema, createAdminUserResponseSchema, createdApiTokenResponseSchema, listAdminTokensResponseSchema, hubUserRecordSchema, reloadConfigResponseSchema } from './schemas.js';
+/**
+ * Default request timeout when {@link TeamHubClientConfig.requestTimeoutMs} is omitted.
+ */
+export const DEFAULT_TEAM_HUB_REQUEST_TIMEOUT_MS = 30_000;
+/**
+ * Executes typed HTTP requests against HarborClient Server.
+ */
+export class TeamHubClient {
+    baseUrl;
+    token;
+    requestTimeoutMs;
+    /**
+     * Creates a client bound to a HarborClient Server instance and bearer token.
+     *
+     * @param config - Base URL, token, and optional request timeout.
+     */
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/+$/, '');
+        this.token = config.token;
+        this.requestTimeoutMs = config.requestTimeoutMs ?? DEFAULT_TEAM_HUB_REQUEST_TIMEOUT_MS;
+    }
+    /**
+     * Joins the configured base URL with a relative API path.
+     *
+     * @param path - Path beginning with `/`.
+     */
+    buildUrl(path) {
+        const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+        return `${this.baseUrl}${normalizedPath}`;
+    }
+    /**
+     * Parses a failed response body into a human-readable error message.
+     *
+     * @param response - Non-success fetch response.
+     * @param method - HTTP method used for the request.
+     * @param path - Request path relative to the base URL.
+     */
+    async parseErrorMessage(response) {
+        const contentType = response.headers.get('content-type') ?? '';
+        if (contentType.includes('application/json')) {
+            try {
+                const json = await response.json();
+                const parsed = errorResponseSchema.safeParse(json);
+                if (parsed.success) {
+                    return parsed.data.error;
+                }
+            }
+            catch {
+                // Fall through to status-based message.
+            }
+        }
+        return `Request failed with status ${response.status}`;
+    }
+    /**
+     * Sends an HTTP request to HarborClient Server and validates the response.
+     *
+     * @param method - HTTP method.
+     * @param path - Path relative to the configured base URL.
+     * @param options - Optional body, response schema, and auth flag.
+     * @returns Parsed response body, or `undefined` for `204 No Content`.
+     * @throws {TeamHubClientError} When the request fails or the response is invalid.
+     */
+    async request(method, path, options = {}) {
+        const { body, schema, auth = true } = options;
+        const headers = {
+            Accept: 'application/json'
+        };
+        if (auth) {
+            headers.Authorization = `Bearer ${this.token}`;
+        }
+        let requestBody;
+        if (body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+            requestBody = JSON.stringify(body);
+        }
+        let response;
+        try {
+            response = await fetch(this.buildUrl(path), {
+                method,
+                headers,
+                body: requestBody,
+                signal: AbortSignal.timeout(this.requestTimeoutMs)
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error && err.name === 'TimeoutError'
+                ? `Request timed out after ${this.requestTimeoutMs} ms`
+                : err instanceof Error
+                    ? err.message
+                    : 'Unknown network error';
+            throw new TeamHubClientError(message, { status: 0, method, path });
+        }
+        if (response.status === 204) {
+            return undefined;
+        }
+        if (!response.ok) {
+            const message = await this.parseErrorMessage(response);
+            throw new TeamHubClientError(message, {
+                status: response.status,
+                method,
+                path
+            });
+        }
+        if (!schema) {
+            return undefined;
+        }
+        let json;
+        try {
+            json = await response.json();
+        }
+        catch {
+            throw new TeamHubClientError('Response body is not valid JSON', {
+                status: response.status,
+                method,
+                path
+            });
+        }
+        const parsed = schema.safeParse(json);
+        if (!parsed.success) {
+            throw new TeamHubClientError('Response body failed validation', {
+                status: response.status,
+                method,
+                path
+            });
+        }
+        return parsed.data;
+    }
+    /**
+     * Probes server availability via the public health endpoint.
+     */
+    async checkHealth() {
+        const result = await this.request('GET', '/health', {
+            auth: false,
+            schema: healthResponseSchema
+        });
+        return result;
+    }
+    /**
+     * Returns the authenticated user, token metadata, and derived API capabilities.
+     */
+    async getSession() {
+        const result = await this.request('GET', '/auth/session', {
+            schema: sessionResponseSchema
+        });
+        return result;
+    }
+    /**
+     * Lists all Team Hub user accounts visible to an admin-role token.
+     */
+    async listAdminUsers() {
+        const result = await this.request('GET', '/admin/users', {
+            schema: listAdminUsersResponseSchema
+        });
+        return result.users;
+    }
+    /**
+     * Creates a Team Hub user account and an initial API bearer token.
+     *
+     * @param input - User fields for the new account.
+     */
+    async createAdminUser(input) {
+        const result = await this.request('POST', '/admin/users', {
+            body: input,
+            schema: createAdminUserResponseSchema
+        });
+        return result;
+    }
+    /**
+     * Updates a Team Hub user account via the management API.
+     *
+     * @param id - User account identifier.
+     * @param input - Partial user fields to apply.
+     */
+    async updateAdminUser(id, input) {
+        const result = await this.request('PUT', `/admin/users/${id}`, {
+            body: input,
+            schema: hubUserRecordSchema
+        });
+        return result;
+    }
+    /**
+     * Deletes a Team Hub user account and their API tokens via the management API.
+     *
+     * @param id - User account identifier.
+     */
+    async deleteAdminUser(id) {
+        await this.request('DELETE', `/admin/users/${id}`);
+    }
+    /**
+     * Lists all API bearer tokens visible to an admin-role token.
+     */
+    async listAdminTokens() {
+        const result = await this.request('GET', '/admin/tokens', {
+            schema: listAdminTokensResponseSchema
+        });
+        return result.tokens;
+    }
+    /**
+     * Creates an additional API bearer token for a user account.
+     *
+     * @param userId - Owning user account identifier.
+     * @param input - Human-readable label for the new token.
+     */
+    async createAdminUserToken(userId, input) {
+        const result = await this.request('POST', `/admin/users/${userId}/tokens`, {
+            body: input,
+            schema: createdApiTokenResponseSchema
+        });
+        return result;
+    }
+    /**
+     * Permanently deletes an API bearer token via the management API.
+     *
+     * @param id - Token record identifier.
+     */
+    async deleteAdminToken(id) {
+        await this.request('DELETE', `/admin/tokens/${id}`);
+    }
+    /**
+     * Lists all collections as id/name metadata for admin user management.
+     */
+    async listAdminCollections() {
+        const result = await this.request('GET', '/admin/collections', {
+            schema: listAdminCollectionsResponseSchema
+        });
+        return result.collections;
+    }
+    /**
+     * Lists all environments as id/name metadata for admin user management.
+     */
+    async listAdminEnvironments() {
+        const result = await this.request('GET', '/admin/environments', {
+            schema: listAdminEnvironmentsResponseSchema
+        });
+        return result.environments;
+    }
+    /**
+     * Lists folders in a collection for operator inspection.
+     *
+     * @param collectionId - Parent collection UUID.
+     */
+    async listAdminCollectionFolders(collectionId) {
+        const result = await this.request('GET', `/admin/collections/${collectionId}/folders`, {
+            schema: listFoldersResponseSchema
+        });
+        return result.folders;
+    }
+    /**
+     * Lists saved requests in a collection for operator inspection.
+     *
+     * @param collectionId - Parent collection UUID.
+     */
+    async listAdminCollectionRequests(collectionId) {
+        const result = await this.request('GET', `/admin/collections/${collectionId}/requests`, {
+            schema: listRequestsResponseSchema
+        });
+        return result.requests;
+    }
+    /**
+     * Deletes a collection via the admin management API.
+     *
+     * @param id - Collection UUID.
+     */
+    async deleteAdminCollection(id) {
+        await this.request('DELETE', `/admin/collections/${id}`);
+    }
+    /**
+     * Deletes an environment via the admin management API.
+     *
+     * @param id - Environment UUID.
+     */
+    async deleteAdminEnvironment(id) {
+        await this.request('DELETE', `/admin/environments/${id}`);
+    }
+    /**
+     * Deletes a saved request via the admin management API.
+     *
+     * @param id - Saved request UUID.
+     */
+    async deleteAdminRequest(id) {
+        await this.request('DELETE', `/admin/requests/${id}`);
+    }
+    /**
+     * Updates whether non-admin users may delete a collection.
+     *
+     * @param id - Collection UUID.
+     * @param deletionLocked - When true, user-role tokens cannot delete the collection.
+     */
+    async updateAdminCollectionDeletionLocked(id, deletionLocked) {
+        const result = await this.request('PUT', `/admin/collections/${id}`, {
+            body: { deletionLocked },
+            schema: adminEntityConfigSchema
+        });
+        return result;
+    }
+    /**
+     * Updates whether non-admin users may delete an environment.
+     *
+     * @param id - Environment UUID.
+     * @param deletionLocked - When true, user-role tokens cannot delete the environment.
+     */
+    async updateAdminEnvironmentDeletionLocked(id, deletionLocked) {
+        const result = await this.request('PUT', `/admin/environments/${id}`, {
+            body: { deletionLocked },
+            schema: adminEntityConfigSchema
+        });
+        return result;
+    }
+    /**
+     * Lists all hub-offered LLM models for admin user management.
+     *
+     * Returns an empty list when LLM support is not configured on the hub.
+     */
+    async listAdminLlmModels() {
+        try {
+            const result = await this.request('GET', '/admin/llm/models', {
+                schema: listHubLlmModelsResponseSchema
+            });
+            return result.models;
+        }
+        catch (error) {
+            if (error instanceof TeamHubClientError && error.status === 503) {
+                return [];
+            }
+            throw error;
+        }
+    }
+    /**
+     * Returns whether the Team Hub server has LLM support configured.
+     *
+     * Uses the admin models route for management tokens and the user route otherwise.
+     * A 503 response means LLM is not configured; any other successful response means
+     * configured.
+     *
+     * @param managementApi - When true, probes `GET /admin/llm/models`.
+     */
+    async probeLlmServiceEnabled(managementApi) {
+        const path = managementApi ? '/admin/llm/models' : '/llm/models';
+        try {
+            await this.request('GET', path, {
+                schema: listHubLlmModelsResponseSchema
+            });
+            return true;
+        }
+        catch (error) {
+            if (error instanceof TeamHubClientError && error.status === 503) {
+                return false;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Loads collection, environment, and LLM model options for admin user forms.
+     */
+    async listAdminResourceOptions() {
+        const [collections, environments, models] = await Promise.all([
+            this.listAdminCollections(),
+            this.listAdminEnvironments(),
+            this.listAdminLlmModels()
+        ]);
+        return { collections, environments, models };
+    }
+    /**
+     * Re-reads server.yaml on the Team Hub and applies reloadable config sections.
+     *
+     * Returns parsed bodies for both `200` and `400` responses. Only auth and
+     * transport failures throw {@link TeamHubClientError}.
+     */
+    async reloadConfig() {
+        const method = 'POST';
+        const path = '/admin/config/reload';
+        let response;
+        try {
+            response = await fetch(this.buildUrl(path), {
+                method,
+                headers: {
+                    Accept: 'application/json',
+                    Authorization: `Bearer ${this.token}`
+                },
+                signal: AbortSignal.timeout(this.requestTimeoutMs)
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error && err.name === 'TimeoutError'
+                ? `Request timed out after ${this.requestTimeoutMs} ms`
+                : err instanceof Error
+                    ? err.message
+                    : 'Unknown network error';
+            throw new TeamHubClientError(message, { status: 0, method, path });
+        }
+        if (response.status !== 200 && response.status !== 400) {
+            const message = await this.parseErrorMessage(response);
+            throw new TeamHubClientError(message, {
+                status: response.status,
+                method,
+                path
+            });
+        }
+        let json;
+        try {
+            json = await response.json();
+        }
+        catch {
+            throw new TeamHubClientError('Response body is not valid JSON', {
+                status: response.status,
+                method,
+                path
+            });
+        }
+        const parsed = reloadConfigResponseSchema.safeParse(json);
+        if (!parsed.success) {
+            throw new TeamHubClientError('Response body failed validation', {
+                status: response.status,
+                method,
+                path
+            });
+        }
+        return parsed.data;
+    }
+    /**
+     * Lists all collections visible to the authenticated token.
+     *
+     * Admin tokens receive the full catalog from `GET /collections`; create, update,
+     * and delete remain forbidden on the server.
+     */
+    async listCollections() {
+        const result = await this.request('GET', '/collections', {
+            schema: listCollectionsResponseSchema
+        });
+        return result.collections;
+    }
+    /**
+     * Creates a new top-level collection.
+     *
+     * @param input - Display name for the collection.
+     */
+    async createCollection(input) {
+        const result = await this.request('POST', '/collections', {
+            body: input,
+            schema: collectionRecordSchema
+        });
+        return result;
+    }
+    /**
+     * Updates an existing collection's settings.
+     *
+     * @param id - Collection UUID.
+     * @param input - Updated collection fields.
+     */
+    async updateCollection(id, input) {
+        const result = await this.request('PUT', `/collections/${id}`, {
+            body: input,
+            schema: collectionRecordSchema
+        });
+        return result;
+    }
+    /**
+     * Deletes a collection and all nested folders and requests.
+     *
+     * @param id - Collection UUID.
+     */
+    async deleteCollection(id) {
+        await this.request('DELETE', `/collections/${id}`);
+    }
+    /**
+     * Lists all environments visible to the authenticated token.
+     *
+     * Admin tokens receive the full catalog from `GET /environments`; create, update,
+     * and delete remain forbidden on the server.
+     */
+    async listEnvironments() {
+        const result = await this.request('GET', '/environments', {
+            schema: listEnvironmentsResponseSchema
+        });
+        return result.environments;
+    }
+    /**
+     * Creates a new top-level environment.
+     *
+     * @param input - Display name for the environment.
+     */
+    async createEnvironment(input) {
+        const result = await this.request('POST', '/environments', {
+            body: input,
+            schema: environmentRecordSchema
+        });
+        return result;
+    }
+    /**
+     * Updates an existing environment's name and variables.
+     *
+     * @param id - Environment UUID.
+     * @param input - Updated environment fields.
+     */
+    async updateEnvironment(id, input) {
+        const result = await this.request('PUT', `/environments/${id}`, {
+            body: input,
+            schema: environmentRecordSchema
+        });
+        return result;
+    }
+    /**
+     * Deletes an environment by id.
+     *
+     * @param id - Environment UUID.
+     */
+    async deleteEnvironment(id) {
+        await this.request('DELETE', `/environments/${id}`);
+    }
+    /**
+     * Lists folders in a collection ordered by sort order, then name.
+     *
+     * @param collectionId - Parent collection UUID.
+     */
+    async listFolders(collectionId) {
+        const result = await this.request('GET', `/collections/${collectionId}/folders`, {
+            schema: listFoldersResponseSchema
+        });
+        return result.folders;
+    }
+    /**
+     * Creates a folder in the given collection.
+     *
+     * @param collectionId - Parent collection UUID.
+     * @param input - Display name for the folder.
+     */
+    async createFolder(collectionId, input) {
+        const result = await this.request('POST', `/collections/${collectionId}/folders`, {
+            body: input,
+            schema: folderRecordSchema
+        });
+        return result;
+    }
+    /**
+     * Renames a folder by id.
+     *
+     * @param id - Folder UUID.
+     * @param input - Updated folder name.
+     */
+    async renameFolder(id, input) {
+        const result = await this.request('PATCH', `/folders/${id}`, {
+            body: input,
+            schema: folderRecordSchema
+        });
+        return result;
+    }
+    /**
+     * Deletes a folder and all saved requests inside it.
+     *
+     * @param id - Folder UUID.
+     */
+    async deleteFolder(id) {
+        await this.request('DELETE', `/folders/${id}`);
+    }
+    /**
+     * Reorders folders within a collection.
+     *
+     * @param collectionId - Parent collection UUID.
+     * @param input - Folder ids in the desired order.
+     */
+    async reorderFolders(collectionId, input) {
+        await this.request('PUT', `/collections/${collectionId}/folders/reorder`, {
+            body: input
+        });
+    }
+    /**
+     * Lists saved requests in a collection.
+     *
+     * @param collectionId - Parent collection UUID.
+     */
+    async listRequests(collectionId) {
+        const result = await this.request('GET', `/collections/${collectionId}/requests`, {
+            schema: listRequestsResponseSchema
+        });
+        return result.requests;
+    }
+    /**
+     * Creates a new saved request in a collection.
+     *
+     * @param collectionId - Parent collection UUID.
+     * @param input - Saved request fields.
+     */
+    async createRequest(collectionId, input) {
+        const result = await this.request('POST', `/collections/${collectionId}/requests`, {
+            body: input,
+            schema: savedRequestRecordSchema
+        });
+        return result;
+    }
+    /**
+     * Updates an existing saved request by id.
+     *
+     * @param id - Saved request UUID.
+     * @param input - Updated request fields including collection id.
+     */
+    async updateRequest(id, input) {
+        const result = await this.request('PUT', `/requests/${id}`, {
+            body: input,
+            schema: savedRequestRecordSchema
+        });
+        return result;
+    }
+    /**
+     * Deletes a saved request by id.
+     *
+     * @param id - Saved request UUID.
+     */
+    async deleteRequest(id) {
+        await this.request('DELETE', `/requests/${id}`);
+    }
+    /**
+     * Reorders saved requests within a folder or the collection root.
+     *
+     * @param collectionId - Parent collection UUID.
+     * @param input - Destination folder and ordered request ids.
+     */
+    async reorderRequests(collectionId, input) {
+        await this.request('PUT', `/collections/${collectionId}/requests/reorder`, {
+            body: input
+        });
+    }
+    /**
+     * Moves a saved request to another folder or root index.
+     *
+     * @param id - Saved request UUID.
+     * @param input - Destination folder and target index.
+     */
+    async moveRequest(id, input) {
+        await this.request('PUT', `/requests/${id}/move`, {
+            body: input
+        });
+    }
+    /**
+     * Lists hub-offered LLM models visible to the authenticated token.
+     */
+    async listLlmModels() {
+        const result = await this.request('GET', '/llm/models', {
+            schema: listHubLlmModelsResponseSchema
+        });
+        return result.models;
+    }
+    /**
+     * Returns plugin catalog and trusted-publisher URLs configured on this Team Hub.
+     */
+    async getPluginSources() {
+        const result = await this.request('GET', '/plugins/sources', {
+            schema: pluginSourcesResponseSchema
+        });
+        return result;
+    }
+    /**
+     * Runs one hub-proxied LLM completion step.
+     *
+     * @param input - Model, messages, tools, and system prompt for the step.
+     */
+    async completeChatStep(input) {
+        const result = await this.request('POST', '/llm/chat/step', {
+            body: input,
+            schema: hubChatStepResponseSchema
+        });
+        return result;
+    }
+}

package/dist/TeamHubClientError.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Thrown when a HarborClient Server request fails or the response body is invalid.
+ */
+export declare class TeamHubClientError extends Error {
+    /**
+     * HTTP status code from the server, or `0` for network and parse failures.
+     */
+    readonly status: number;
+    /**
+     * HTTP method used for the failed request.
+     */
+    readonly method: string;
+    /**
+     * Request path relative to the configured base URL.
+     */
+    readonly path: string;
+    /**
+     * Creates a team hub client error with request context for logging and UI display.
+     *
+     * @param message - Human-readable error description.
+     * @param options - HTTP status and request metadata.
+     */
+    constructor(message: string, options: {
+        status: number;
+        method: string;
+        path: string;
+    });
+}
+//# sourceMappingURL=TeamHubClientError.d.ts.map

package/dist/TeamHubClientError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TeamHubClientError.d.ts","sourceRoot":"","sources":["../src/TeamHubClientError.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;gBAED,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QACP,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;KACd;CAQJ"}