@promptbook/remote-server 0.89.0-4 → 0.89.0-6

package/esm/typings/src/_packages/types.index.d.ts

@@ -112,6 +112,7 @@ import type { components } from '../playground/brjapp-api-schema';
 import type { $defs } from '../playground/brjapp-api-schema';
 import type { operations } from '../playground/brjapp-api-schema';
 import type { PrepareAndScrapeOptions } from '../prepare/PrepareAndScrapeOptions';
+import type { RemoteServer } from '../remote-server/RemoteServer';
 import type { PromptbookServer_Identification } from '../remote-server/socket-types/_subtypes/PromptbookServer_Identification';
 import type { PromptbookServer_ApplicationIdentification } from '../remote-server/socket-types/_subtypes/PromptbookServer_Identification';
 import type { PromptbookServer_AnonymousIdentification } from '../remote-server/socket-types/_subtypes/PromptbookServer_Identification';
@@ -401,6 +402,7 @@ export type { components };
 export type { $defs };
 export type { operations };
 export type { PrepareAndScrapeOptions };
+export type { RemoteServer };
 export type { PromptbookServer_Identification };
 export type { PromptbookServer_ApplicationIdentification };
 export type { PromptbookServer_AnonymousIdentification };

package/esm/typings/src/remote-server/RemoteServer.d.ts

@@ -0,0 +1,23 @@
+/// <reference types="node" />
+import type { IDestroyable } from 'destroyable';
+import express from 'express';
+import http from 'http';
+import { DefaultEventsMap, Server } from 'socket.io';
+import type { TODO_any } from '../utils/organization/TODO_any';
+import type { TODO_narrow } from '../utils/organization/TODO_narrow';
+export type RemoteServer = IDestroyable & {
+    /**
+     * HTTP server instance
+     */
+    readonly httpServer: http.Server<TODO_any>;
+    /**
+     * Express application instance
+     *
+     * Note: This is useful for adding custom routes
+     */
+    readonly expressApp: express.Express;
+    /**
+     * Socket.io server instance
+     */
+    readonly socketIoServer: Server<TODO_narrow<DefaultEventsMap>, TODO_narrow<DefaultEventsMap>, TODO_narrow<DefaultEventsMap>, TODO_any>;
+};

package/esm/typings/src/remote-server/startRemoteServer.d.ts

@@ -1,4 +1,4 @@
-import type { IDestroyable } from 'destroyable';
+import type { RemoteServer } from './RemoteServer';
 import type { RemoteServerOptions } from './types/RemoteServerOptions';
 /**
  * Remote server is a proxy server that uses its execution tools internally and exposes the executor interface externally.
@@ -9,7 +9,7 @@ import type { RemoteServerOptions } from './types/RemoteServerOptions';
  * @see https://github.com/webgptorg/promptbook#remote-server
  * @public exported from `@promptbook/remote-server`
  */
-export declare function startRemoteServer<TCustomOptions = undefined>(options: RemoteServerOptions<TCustomOptions>): IDestroyable;
+export declare function startRemoteServer<TCustomOptions = undefined>(options: RemoteServerOptions<TCustomOptions>): RemoteServer;
 /**
  * TODO: !! Add CORS and security - probbably via `helmet`
  * TODO: [👩🏾‍🤝‍🧑🏾] Allow to pass custom fetch function here - PromptbookFetch

package/esm/typings/src/utils/organization/TODO_narrow.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Organizational helper to better mark the place where the more specific type is missing
+ *
+ * @private within the repository
+ */
+export type TODO_narrow<T> = T;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/remote-server",
-    "version": "0.89.0-4",
+    "version": "0.89.0-6",
     "description": "It's time for a paradigm shift. The future of software in plain English, French or Latin",
     "private": false,
     "sideEffects": false,
@@ -47,7 +47,7 @@
     "module": "./esm/index.es.js",
     "typings": "./esm/typings/src/_packages/remote-server.index.d.ts",
     "peerDependencies": {
-        "@promptbook/core": "0.89.0-4"
+        "@promptbook/core": "0.89.0-6"
     },
     "dependencies": {
         "colors": "1.4.0",
@@ -59,6 +59,8 @@
         "rxjs": "^7.8.1",
         "socket.io": "4.8.1",
         "spacetrim": "0.11.59",
+        "swagger-jsdoc": "^6.2.8",
+        "swagger-ui-express": "^5.0.1",
         "userhome": "1.0.1",
         "waitasecond": "1.11.83"
     }

package/umd/index.umd.js

@@ -1,8 +1,8 @@
 (function (global, factory) {
-    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('colors'), require('express'), require('http'), require('socket.io'), require('spacetrim'), require('waitasecond'), require('crypto'), require('child_process'), require('fs/promises'), require('path'), require('rxjs'), require('prettier'), require('prettier/parser-html'), require('crypto-js/enc-hex'), require('crypto-js/sha256'), require('crypto-js'), require('mime-types'), require('papaparse')) :
-    typeof define === 'function' && define.amd ? define(['exports', 'colors', 'express', 'http', 'socket.io', 'spacetrim', 'waitasecond', 'crypto', 'child_process', 'fs/promises', 'path', 'rxjs', 'prettier', 'prettier/parser-html', 'crypto-js/enc-hex', 'crypto-js/sha256', 'crypto-js', 'mime-types', 'papaparse'], factory) :
-    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global["promptbook-remote-server"] = {}, global.colors, global.express, global.http, global.socket_io, global.spaceTrim, global.waitasecond, global.crypto, global.child_process, global.promises, global.path, global.rxjs, global.prettier, global.parserHtml, global.hexEncoder, global.sha256, global.cryptoJs, global.mimeTypes, global.papaparse));
-})(this, (function (exports, colors, express, http, socket_io, spaceTrim, waitasecond, crypto, child_process, promises, path, rxjs, prettier, parserHtml, hexEncoder, sha256, cryptoJs, mimeTypes, papaparse) { 'use strict';
+    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('colors'), require('express'), require('http'), require('socket.io'), require('spacetrim'), require('swagger-jsdoc'), require('swagger-ui-express'), require('waitasecond'), require('crypto'), require('child_process'), require('fs/promises'), require('path'), require('rxjs'), require('prettier'), require('prettier/parser-html'), require('crypto-js/enc-hex'), require('crypto-js/sha256'), require('crypto-js'), require('mime-types'), require('papaparse')) :
+    typeof define === 'function' && define.amd ? define(['exports', 'colors', 'express', 'http', 'socket.io', 'spacetrim', 'swagger-jsdoc', 'swagger-ui-express', 'waitasecond', 'crypto', 'child_process', 'fs/promises', 'path', 'rxjs', 'prettier', 'prettier/parser-html', 'crypto-js/enc-hex', 'crypto-js/sha256', 'crypto-js', 'mime-types', 'papaparse'], factory) :
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global["promptbook-remote-server"] = {}, global.colors, global.express, global.http, global.socket_io, global.spaceTrim, global.swaggerJsdoc, global.swaggerUi, global.waitasecond, global.crypto, global.child_process, global.promises, global.path, global.rxjs, global.prettier, global.parserHtml, global.hexEncoder, global.sha256, global.cryptoJs, global.mimeTypes, global.papaparse));
+})(this, (function (exports, colors, express, http, socket_io, spaceTrim, swaggerJsdoc, swaggerUi, waitasecond, crypto, child_process, promises, path, rxjs, prettier, parserHtml, hexEncoder, sha256, cryptoJs, mimeTypes, papaparse) { 'use strict';
 
     function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
 
@@ -10,6 +10,8 @@
     var express__default = /*#__PURE__*/_interopDefaultLegacy(express);
     var http__default = /*#__PURE__*/_interopDefaultLegacy(http);
     var spaceTrim__default = /*#__PURE__*/_interopDefaultLegacy(spaceTrim);
+    var swaggerJsdoc__default = /*#__PURE__*/_interopDefaultLegacy(swaggerJsdoc);
+    var swaggerUi__default = /*#__PURE__*/_interopDefaultLegacy(swaggerUi);
     var parserHtml__default = /*#__PURE__*/_interopDefaultLegacy(parserHtml);
     var hexEncoder__default = /*#__PURE__*/_interopDefaultLegacy(hexEncoder);
     var sha256__default = /*#__PURE__*/_interopDefaultLegacy(sha256);
@@ -28,7 +30,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.89.0-4';
+    const PROMPTBOOK_ENGINE_VERSION = '0.89.0-6';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -6779,9 +6781,37 @@
             response.setHeader('X-Powered-By', 'Promptbook engine');
             next();
         });
+        const swaggerOptions = {
+            definition: {
+                openapi: '3.0.0',
+                info: {
+                    title: 'Promptbook Remote Server API',
+                    version: '1.0.0',
+                    description: 'API documentation for the Promptbook Remote Server',
+                },
+                servers: [
+                    {
+                        url: `http://localhost:${port}${rootPath}`,
+                    },
+                ],
+            },
+            apis: ['./src/remote-server/**/*.ts'], // Adjust path as needed
+        };
+        const swaggerSpec = swaggerJsdoc__default["default"](swaggerOptions);
+        app.use(`${rootPath}/api-docs`, swaggerUi__default["default"].serve, swaggerUi__default["default"].setup(swaggerSpec));
         const runningExecutionTasks = [];
         // <- TODO: [🤬] Identify the users
         // TODO: [🧠] Do here some garbage collection of finished tasks
+        /**
+         * @swagger
+         * /:
+         *   get:
+         *     summary: Get server details
+         *     description: Returns details about the Promptbook server.
+         *     responses:
+         *       200:
+         *         description: Server details in markdown format.
+         */
         app.get(['/', rootPath], async (request, response) => {
             var _a;
             if ((_a = request.url) === null || _a === void 0 ? void 0 : _a.includes('socket.io')) {
@@ -6839,6 +6869,22 @@
                 `));
         });
         // TODO: !!!!!! Add login route
+        /**
+         * @swagger
+         * /books:
+         *   get:
+         *     summary: List all books
+         *     description: Returns a list of all available books in the collection.
+         *     responses:
+         *       200:
+         *         description: A list of books.
+         *         content:
+         *           application/json:
+         *             schema:
+         *               type: array
+         *               items:
+         *                 type: string
+         */
         app.get(`${rootPath}/books`, async (request, response) => {
             if (collection === null) {
                 response.status(500).send('No collection available');
@@ -6849,6 +6895,29 @@
             response.send(pipelines);
         });
         // TODO: [🧠] Is it secure / good idea to expose source codes of hosted books
+        /**
+         * @swagger
+         * /books/{bookId}:
+         *   get:
+         *     summary: Get book content
+         *     description: Returns the content of a specific book.
+         *     parameters:
+         *       - in: path
+         *         name: bookId
+         *         required: true
+         *         schema:
+         *           type: string
+         *         description: The ID of the book to retrieve.
+         *     responses:
+         *       200:
+         *         description: The content of the book.
+         *         content:
+         *           text/markdown:
+         *             schema:
+         *               type: string
+         *       404:
+         *         description: Book not found.
+         */
         app.get(`${rootPath}/books/*`, async (request, response) => {
             try {
                 if (collection === null) {
@@ -6903,6 +6972,22 @@
                 };
             }
         }
+        /**
+         * @swagger
+         * /executions:
+         *   get:
+         *     summary: List all executions
+         *     description: Returns a list of all running execution tasks.
+         *     responses:
+         *       200:
+         *         description: A list of execution tasks.
+         *         content:
+         *           application/json:
+         *             schema:
+         *               type: array
+         *               items:
+         *                 type: object
+         */
         app.get(`${rootPath}/executions`, async (request, response) => {
             response.send(runningExecutionTasks.map((runningExecutionTask) => exportExecutionTask(runningExecutionTask, false)));
         });
@@ -6927,6 +7012,35 @@
             }
             response.send(exportExecutionTask(executionTask, true));
         });
+        /**
+         * @swagger
+         * /executions/new:
+         *   post:
+         *     summary: Start a new execution
+         *     description: Starts a new execution task for a given pipeline.
+         *     requestBody:
+         *       required: true
+         *       content:
+         *         application/json:
+         *           schema:
+         *             type: object
+         *             properties:
+         *               pipelineUrl:
+         *                 type: string
+         *               inputParameters:
+         *                 type: object
+         *               identification:
+         *                 type: object
+         *     responses:
+         *       200:
+         *         description: The newly created execution task.
+         *         content:
+         *           application/json:
+         *             schema:
+         *               type: object
+         *       400:
+         *         description: Invalid input.
+         */
         app.post(`${rootPath}/executions/new`, async (request, response) => {
             try {
                 const { inputParameters, identification /* <- [🤬] */ } = request.body;
@@ -7104,6 +7218,15 @@
         }
         let isDestroyed = false;
         return {
+            get httpServer() {
+                return httpServer;
+            },
+            get expressApp() {
+                return app;
+            },
+            get socketIoServer() {
+                return server;
+            },
             get isDestroyed() {
                 return isDestroyed;
             },