@promptbook/markdown-utils 0.89.0-2 → 0.89.0-20

package/esm/typings/src/llm-providers/_common/register/$provideLlmToolsForWizzardOrCli.d.ts

@@ -1,11 +1,55 @@
+import { Promisable } from 'type-fest';
+import type { Identification } from '../../../remote-server/socket-types/_subtypes/Identification';
+import type { string_app_id } from '../../../types/typeAliases';
+import type { string_url } from '../../../types/typeAliases';
+import type { really_any } from '../../../utils/organization/really_any';
 import type { CacheLlmToolsOptions } from '../utils/cache/CacheLlmToolsOptions';
 import type { LlmExecutionToolsWithTotalUsage } from '../utils/count-total-usage/LlmExecutionToolsWithTotalUsage';
+type ProvideLlmToolsForWizzardOrCliOptions = {
+    /**
+     * If true, user will be always prompted for login
+     *
+     * Note: This is used in `ptbk login` command
+     */
+    isLoginloaded?: true;
+} & Pick<CacheLlmToolsOptions, 'isCacheReloaded'> & ({
+    /**
+     * Use local keys and execute LLMs directly
+     */
+    readonly strategy: 'BRING_YOUR_OWN_KEYS';
+} | {
+    /**
+     * Do not use local keys but login to Promptbook server and execute LLMs there
+     */
+    readonly strategy: 'REMOTE_SERVER';
+    /**
+     * URL of the remote server
+     *
+     * @default `DEFAULT_REMOTE_SERVER_URL`
+     */
+    readonly remoteServerUrl?: string_url;
+    /**
+     * Identifier of the application which will be passed to the remote server identification
+     *
+     * Note: This can be some id or some semantic name like "email-agent"
+     */
+    readonly appId: string_app_id;
+    /**
+     *
+     *
+     * Note: When login prompt fails, `process.exit(1)` is called
+     */
+    loginPrompt(): Promisable<Identification<really_any>>;
+});
 /**
  * Returns LLM tools for CLI
  *
+ * Note: `$` is used to indicate that this function is not a pure function - it uses filesystem to access `.env` file and also writes this .env file
+ *
  * @private within the repository - for CLI utils
  */
-export declare function $provideLlmToolsForWizzardOrCli(options?: Pick<CacheLlmToolsOptions, 'isCacheReloaded'>): Promise<LlmExecutionToolsWithTotalUsage>;
+export declare function $provideLlmToolsForWizzardOrCli(options?: ProvideLlmToolsForWizzardOrCliOptions): Promise<LlmExecutionToolsWithTotalUsage>;
+export {};
 /**
  * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
  * TODO: [👷‍♂️] @@@ Manual about construction of llmTools

package/esm/typings/src/llm-providers/_common/register/$provideLlmToolsFromEnv.d.ts

@@ -6,6 +6,7 @@ import type { CreateLlmToolsFromConfigurationOptions } from './createLlmToolsFro
  * Note: This function is not cached, every call creates new instance of `MultipleLlmExecutionTools`
  *
  * @@@ .env
+ * Note: `$` is used to indicate that this function is not a pure function - it uses filesystem to access `.env` file
  *
  * It looks for environment variables:
  * - `process.env.OPENAI_API_KEY`

package/esm/typings/src/llm-providers/anthropic-claude/AnthropicClaudeExecutionToolsOptions.d.ts

@@ -25,7 +25,7 @@ export type AnthropicClaudeExecutionToolsDirectOptions = CommonToolsOptions & Cl
  */
 export type AnthropicClaudeExecutionToolsProxiedOptions = CommonToolsOptions & ClientOptions & {
     isProxied: true;
-} & Pick<RemoteClientOptions<undefined>, 'remoteUrl' | 'path'>;
+} & Pick<RemoteClientOptions<undefined>, 'remoteServerUrl'>;
 /**
  * TODO: [🧠][🤺] Pass `userId`
  */

package/esm/typings/src/llm-providers/anthropic-claude/register-configuration.d.ts

@@ -11,4 +11,4 @@ import type { Registration } from '../../utils/$Register';
 export declare const _AnthropicClaudeMetadataRegistration: Registration;
 /**
  * Note: [💞] Ignore a discrepancy between file name and entity name
- */ 
+ */

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/socket-types/_subtypes/{PromptbookServer_Identification.d.ts → Identification.d.ts}

@@ -7,14 +7,14 @@ import type { ApplicationRemoteServerClientOptions } from '../../types/RemoteSer
  * @public exported from `@promptbook/remote-server`
  * @public exported from `@promptbook/remote-client`
  */
-export type PromptbookServer_Identification<TCustomOptions> = PromptbookServer_ApplicationIdentification<TCustomOptions> | PromptbookServer_AnonymousIdentification;
+export type Identification<TCustomOptions> = ApplicationModeIdentification<TCustomOptions> | AnonymousModeIdentification;
 /**
  * Application mode is situation when you run known and well-defined books with your own api keys
  *
  * @public exported from `@promptbook/remote-server`
  * @public exported from `@promptbook/remote-client`
  */
-export type PromptbookServer_ApplicationIdentification<TCustomOptions> = ApplicationRemoteServerClientOptions<TCustomOptions> & {
+export type ApplicationModeIdentification<TCustomOptions> = ApplicationRemoteServerClientOptions<TCustomOptions> & {
     /**
      * Application mode
      */
@@ -29,7 +29,7 @@ export type PromptbookServer_ApplicationIdentification<TCustomOptions> = Applica
  * @public exported from `@promptbook/remote-server`
  * @public exported from `@promptbook/remote-client`
  */
-export type PromptbookServer_AnonymousIdentification = {
+export type AnonymousModeIdentification = {
     /**
      * Anonymous mode
      */

package/esm/typings/src/remote-server/socket-types/_subtypes/identificationToPromptbookToken.d.ts

@@ -0,0 +1,11 @@
+import type { string_promptbook_token } from '../../../types/typeAliases';
+import type { really_unknown } from '../../../utils/organization/really_unknown';
+import type { ApplicationModeIdentification } from './Identification';
+/**
+ * Convert identification to Promptbook token
+ *
+ * @param identification
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare function identificationToPromptbookToken(identification: ApplicationModeIdentification<really_unknown>): string_promptbook_token;

package/esm/typings/src/remote-server/socket-types/_subtypes/promptbookTokenToIdentification.d.ts

@@ -0,0 +1,10 @@
+import type { string_promptbook_token } from '../../../types/typeAliases';
+import type { ApplicationModeIdentification } from './Identification';
+/**
+ * Convert Promptbook token to identification
+ *
+ * @param promptbookToken
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare function promptbookTokenToIdentification(promptbookToken: string_promptbook_token): ApplicationModeIdentification<undefined>;

package/esm/typings/src/remote-server/socket-types/listModels/PromptbookServer_ListModels_Request.d.ts

@@ -1,4 +1,4 @@
-import type { PromptbookServer_Identification } from '../_subtypes/PromptbookServer_Identification';
+import type { Identification } from '../_subtypes/Identification';
 /**
  * List models available in the server
  *
@@ -10,7 +10,7 @@ export type PromptbookServer_ListModels_Request<TCustomOptions> = {
     /**
      * Identifier of the end user or application
      */
-    readonly identification: PromptbookServer_Identification<TCustomOptions>;
+    readonly identification: Identification<TCustomOptions>;
 };
 /**
  * TODO: [🧠] Listing models inanonymous mode does not make sence - keeping only to preserve consistency

package/esm/typings/src/remote-server/socket-types/prepare/PromptbookServer_PreparePipeline_Request.d.ts

@@ -1,5 +1,5 @@
 import type { PipelineJson } from '../../../pipeline/PipelineJson/PipelineJson';
-import type { PromptbookServer_Identification } from '../_subtypes/PromptbookServer_Identification';
+import type { Identification } from '../_subtypes/Identification';
 /**
  * This is a request from client to server to prepare a pipeline
  *
@@ -9,7 +9,7 @@ export type PromptbookServer_PreparePipeline_Request<TCustomOptions> = {
     /**
      * Identifier of the end user or application
      */
-    readonly identification: PromptbookServer_Identification<TCustomOptions>;
+    readonly identification: Identification<TCustomOptions>;
     /**
      * The Pipeline to prepare
      */

package/esm/typings/src/remote-server/socket-types/prompt/PromptbookServer_Prompt_Request.d.ts

@@ -1,5 +1,5 @@
 import type { Prompt } from '../../../types/Prompt';
-import type { PromptbookServer_Identification } from '../_subtypes/PromptbookServer_Identification';
+import type { Identification } from '../_subtypes/Identification';
 /**
  * This is a request from client to server to execute a prompt
  *
@@ -9,7 +9,7 @@ export type PromptbookServer_Prompt_Request<TCustomOptions> = {
     /**
      * Identifier of the end user or application
      */
-    readonly identification: PromptbookServer_Identification<TCustomOptions>;
+    readonly identification: Identification<TCustomOptions>;
     /**
      * The Prompt to execute
      */

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,10 +9,9 @@ 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
  * TODO: Split this file into multiple functions - handler for each request
  * TODO: Maybe use `$exportJson`
  * TODO: [🧠][🛍] Maybe not `isAnonymous: boolean` BUT `mode: 'ANONYMOUS'|'COLLECTION'`

package/esm/typings/src/remote-server/types/RemoteClientOptions.d.ts

@@ -1,7 +1,6 @@
 import type { CommonToolsOptions } from '../../execution/CommonToolsOptions';
 import type { string_base_url } from '../../types/typeAliases';
-import type { string_uri } from '../../types/typeAliases';
-import type { PromptbookServer_Identification } from '../socket-types/_subtypes/PromptbookServer_Identification';
+import type { Identification } from '../socket-types/_subtypes/Identification';
 /**
  * Options for `RemoteLlmExecutionTools`
  *
@@ -12,21 +11,14 @@ export type RemoteClientOptions<TCustomOptions> = CommonToolsOptions & {
      * URL of the remote server
      * On this server will be connected to the socket.io server
      */
-    readonly remoteUrl: string_base_url;
-    /**
-     * Path for the Socket.io server to listen
-     *
-     * @default '/socket.io'
-     * @example '/promptbook/socket.io'
-     */
-    readonly path: string_uri;
+    readonly remoteServerUrl: string_base_url;
     /**
      * Identification of client for Socket.io remote server
      */
-    readonly identification: PromptbookServer_Identification<TCustomOptions>;
+    readonly identification: Identification<TCustomOptions>;
 };
 /**
  * TODO: Pass more options from Socket.io to `RemoteClientOptions` (like `transports`)
  * TODO: [🧠][🛍] Maybe not `isAnonymous: boolean` BUT `mode: 'ANONYMOUS'|'COLLECTION'`
- * TODO: [🧠][🧜‍♂️] Maybe join remoteUrl and path into single value
+ * TODO: [🧠][🧜‍♂️] Maybe join remoteServerUrl and path into single value
  */

package/esm/typings/src/remote-server/types/RemoteServerOptions.d.ts

@@ -1,10 +1,17 @@
+import type { Request, Response } from 'express';
 import type { Promisable } from 'type-fest';
 import type { PipelineCollection } from '../../collection/PipelineCollection';
+import { AuthenticationError } from '../../errors/AuthenticationError';
 import type { CommonToolsOptions } from '../../execution/CommonToolsOptions';
+import type { ExecutionTools } from '../../execution/ExecutionTools';
 import type { LlmExecutionTools } from '../../execution/LlmExecutionTools';
 import type { string_app_id } from '../../types/typeAliases';
+import type { string_email } from '../../types/typeAliases';
+import type { string_password } from '../../types/typeAliases';
 import type { string_uri } from '../../types/typeAliases';
 import type { string_user_id } from '../../types/typeAliases';
+import type { ApplicationModeIdentification } from '../socket-types/_subtypes/Identification';
+import type { Identification } from '../socket-types/_subtypes/Identification';
 /**
  * @@@
  *
@@ -16,7 +23,6 @@ import type { string_user_id } from '../../types/typeAliases';
  *
  * You can enable both modes at the same time.
  *
- * @public exported from `@promptbook/remote-client`
  * @public exported from `@promptbook/remote-server`
  */
 export type RemoteServerOptions<TCustomOptions> = CommonToolsOptions & {
@@ -32,8 +38,25 @@ export type RemoteServerOptions<TCustomOptions> = CommonToolsOptions & {
      * @default '/'
      * @example '/api/promptbook/'
      */
-    readonly rootPath: string_uri;
-} & (AnonymousRemoteServerOptions | ApplicationRemoteServerOptions<TCustomOptions> | (AnonymousRemoteServerOptions & ApplicationRemoteServerOptions<TCustomOptions>));
+    readonly rootPath?: string_uri;
+    /**
+     * Creates execution tools the client
+     *
+     * This is relevant also in anonymous mode in oposition to `createLlmExecutionTools`
+     *
+     * Note: You can provide only some tools and leave the rest to the default ones also llm tools are created by `createLlmExecutionTools`
+     * Note: This is useful when you want to provide some custom restrictions for example:
+     * - Limit access to certain websites for some users
+     * - Bind user-interface tools to email agent
+     * - Allow / block script execution
+     * - And many more
+     */
+    createExecutionTools?(options: Identification<TCustomOptions>): Promisable<Partial<Omit<ExecutionTools, 'llm'>>>;
+} & ((AnonymousRemoteServerOptions & {
+    readonly isApplicationModeAllowed?: false;
+}) | ({
+    readonly isAnonymousModeAllowed?: false;
+} & ApplicationRemoteServerOptions<TCustomOptions>) | (AnonymousRemoteServerOptions & ApplicationRemoteServerOptions<TCustomOptions>));
 export type AnonymousRemoteServerOptions = {
     /**
      * Enable anonymous mode
@@ -51,10 +74,22 @@ export type ApplicationRemoteServerOptions<TCustomOptions> = {
      * This is used to check validity of the prompt to prevent misuse
      */
     readonly collection: PipelineCollection;
+    /**
+     * User tries to login to the server, this function will be called verify the user and return the identification or throw an error
+     * This can be also doubled as a function to register the user
+     *
+     * Note: In most cases, you will return `PromptbookServer_ApplicationIdentification`
+     *       `PromptbookServer_AnonymousIdentification` is useful only in scenarios when user stores its own api keys on the application server and
+     *       server acts only as a api key provider
+     *
+     * Note: In most cases DO NOT THROW `AuthenticationError` but return `isSuccess: false` with message
+     * @throws `AuthenticationError`  if the user is not allowed to login for example because of invalid credentials
+     */
+    login(loginRequest: LoginRequest): Promise<LoginResponse<TCustomOptions>>;
     /**
      * Creates llm execution tools for each client
      */
-    createLlmExecutionTools(options: ApplicationRemoteServerClientOptions<TCustomOptions>): Promisable<LlmExecutionTools>;
+    createLlmExecutionTools(options: ApplicationModeIdentification<TCustomOptions>): Promisable<LlmExecutionTools>;
 };
 export type ApplicationRemoteServerClientOptions<TCustomOptions> = {
     /**
@@ -82,6 +117,56 @@ export type ApplicationRemoteServerClientOptions<TCustomOptions> = {
      */
     readonly customOptions?: TCustomOptions;
 };
+/**
+ * Login request for the application mode
+ */
+export type LoginRequest = {
+    /**
+     * Identifier of the application you are using
+     *
+     * Note: This is usefull when you use Promptbook remote server for multiple apps/frontends, if its used just for single app, use here just "app" or "your-app-name"
+     */
+    readonly appId: string_app_id | null;
+    /**
+     * Username (for example email) of the user
+     */
+    readonly username: string_email | string;
+    /**
+     * Password of the user
+     */
+    readonly password: string_password;
+    /**
+     * Request object from express if you want to access some request data for example headers, IP address, etc.
+     */
+    readonly rawRequest: Request;
+    /**
+     * Response object from express if you want to add some custom headers.
+     *
+     * Note: It is not recommended to use this object to send body of the response because it can confuse the client
+     */
+    readonly rawResponse: Response;
+};
+/**
+ * Login response for the application mode
+ */
+export type LoginResponse<TCustomOptions> = {
+    /**
+     * Was the login successful
+     */
+    readonly isSuccess: boolean;
+    /**
+     * Message to display to the user, this message is always displayed
+     */
+    readonly message?: string;
+    /**
+     * Optional error if the login was not successful
+     */
+    readonly error?: AuthenticationError;
+    /**
+     * Identification of the user to be used in the future requests
+     */
+    readonly identification?: Identification<TCustomOptions>;
+};
 /**
  * TODO: Constrain anonymous mode for specific models / providers
  */

package/esm/typings/src/scrapers/_common/utils/{scraperFetch.d.ts → promptbookFetch.d.ts}

@@ -2,9 +2,9 @@ import type { PromptbookFetch } from '../../../execution/PromptbookFetch';
 /**
  * The built-in `fetch' function with a lightweight error handling wrapper as default fetch function used in Promptbook scrapers
  *
- * @private as default `fetch` function used in Promptbook scrapers
+ * @public exported from `@promptbook/core`
  */
-export declare const scraperFetch: PromptbookFetch;
+export declare const promptbookFetch: PromptbookFetch;
 /**
  * TODO: [🧠] Maybe rename because it is not used only for scrapers but also in `$getCompiledBook`
  */

package/esm/typings/src/storage/env-storage/$EnvStorage.d.ts

@@ -0,0 +1,40 @@
+import type { PromptbookStorage } from '../_common/PromptbookStorage';
+/**
+ * Stores data in .env variables
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it uses filesystem to access `.env` file and also writes to `process.env`
+ *
+ * @private within the repository - for CLI utils
+ */
+export declare class $EnvStorage<TItem> implements PromptbookStorage<TItem> {
+    private envFilename;
+    private $provideOrCreateEnvFile;
+    private transformKey;
+    /**
+     * Returns the number of key/value pairs currently present in the list associated with the object.
+     */
+    get length(): number;
+    /**
+     * Empties the list associated with the object of all key/value pairs, if there are any.
+     */
+    clear(): void;
+    /**
+     * Returns the current value associated with the given key, or null if the given key does not exist in the list associated with the object.
+     */
+    getItem(key: string): Promise<TItem | null>;
+    /**
+     * Returns the name of the nth key in the list, or null if n is greater than or equal to the number of key/value pairs in the object.
+     */
+    key(index: number): string | null;
+    /**
+     * Sets the value of the pair identified by key to value, creating a new key/value pair if none existed for key previously.
+     */
+    setItem(key: string, value: TItem): Promise<void>;
+    /**
+     * Removes the key/value pair with the given key from the list associated with the object, if a key/value pair with the given key exists.
+     */
+    removeItem(key: string): void;
+}
+/**
+ * TODO: Write file more securely - ensure that there can be no accidental overwriting of existing variables and other content
+ */

package/esm/typings/src/types/typeAliases.d.ts

@@ -325,6 +325,12 @@ export type string_css_selector = string;
  * For example `"https://collboard.com/9SeSQTupmQHwuSrLi"`
  */
 export type string_url = string;
+/**
+ * Semantic helper
+ *
+ * For example `"https://s1.ptbk.io/promptbook"`
+ */
+export type string_promptbook_server_url = string;
 /**
  * Semantic helper
  *
@@ -521,6 +527,13 @@ export type string_person_profile = string;
  * For example `"MIT"`
  */
 export type string_license = string;
+/**
+ * Semantic helper
+ *
+ * For example `"Pavol Hejný <pavol@ptbk.io> (https://www.pavolhejny.com/)"`
+ * For example `"AI Web, LLC <legal@ptbk.io> (https://www.ptbk.io/)"`
+ */
+export type string_legal_entity = string | string_person_profile | string_title;
 /**
  * Semantic helper for attributes
  *
@@ -570,6 +583,12 @@ export type string_postprocessing_function_name = string;
 export type id = string | number;
 export type task_id = string;
 export type string_token = string;
+/**
+ * Semantic helper
+ *
+ * Made by `identificationToPromptbookToken` exported from `@promptbook/core`
+ */
+export type string_promptbook_token = string_token;
 export type string_license_token = string_token;
 export type string_password = string;
 export type string_ssh_key = string;

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/markdown-utils",
-    "version": "0.89.0-2",
+    "version": "0.89.0-20",
     "description": "It's time for a paradigm shift. The future of software in plain English, French or Latin",
     "private": false,
     "sideEffects": false,
@@ -43,15 +43,19 @@
         "url": "https://github.com/webgptorg/promptbook/issues"
     },
     "homepage": "https://ptbk.io/",
+    "engines": {
+        "node": ">=16.0.0",
+        "npm": ">=8.0.0"
+    },
     "main": "./umd/index.umd.js",
     "module": "./esm/index.es.js",
     "typings": "./esm/typings/src/_packages/markdown-utils.index.d.ts",
     "dependencies": {
-        "crypto": "^1.0.1",
+        "crypto": "1.0.1",
         "crypto-js": "4.2.0",
         "papaparse": "5.4.1",
         "prettier": "2.8.1",
-        "rxjs": "^7.8.1",
+        "rxjs": "7.8.1",
         "spacetrim": "0.11.59",
         "waitasecond": "1.11.83"
     }