kozz-module-maker 0.1.0

package/.env

@@ -0,0 +1,2 @@
+GATEWAY_URL=http://gramont.ddns.net:4521
+MY_CONTACT_ID=5511947952409@c.us

package/.prettierrc

@@ -0,0 +1,8 @@
+{
+	"trailingComma": "es5",
+	"arrowParens": "avoid",
+	"useTabs": true,
+	"printWidth": 80,
+	"singleQuote": true,
+	"bracketSpacing": true
+}

package/jest.config.ts

@@ -0,0 +1,196 @@
+/*
+ * For a detailed explanation regarding each configuration property and type check, visit:
+ * https://jestjs.io/docs/configuration
+ */
+
+export default {
+  // All imported modules in your tests should be mocked automatically
+  // automock: false,
+
+  // Stop running tests after `n` failures
+  // bail: 0,
+
+  // The directory where Jest should store its cached dependency information
+  // cacheDirectory: "C:\\Users\\guiga\\AppData\\Local\\Temp\\jest",
+
+  // Automatically clear mock calls, instances, contexts and results before every test
+  clearMocks: true,
+
+  // Indicates whether the coverage information should be collected while executing the test
+  collectCoverage: true,
+
+  // An array of glob patterns indicating a set of files for which coverage information should be collected
+  // collectCoverageFrom: undefined,
+
+  // The directory where Jest should output its coverage files
+  coverageDirectory: "coverage",
+
+  // An array of regexp pattern strings used to skip coverage collection
+  // coveragePathIgnorePatterns: [
+  //   "\\\\node_modules\\\\"
+  // ],
+
+  // Indicates which provider should be used to instrument code for coverage
+  coverageProvider: "v8",
+
+  // A list of reporter names that Jest uses when writing coverage reports
+  // coverageReporters: [
+  //   "json",
+  //   "text",
+  //   "lcov",
+  //   "clover"
+  // ],
+
+  // An object that configures minimum threshold enforcement for coverage results
+  // coverageThreshold: undefined,
+
+  // A path to a custom dependency extractor
+  // dependencyExtractor: undefined,
+
+  // Make calling deprecated APIs throw helpful error messages
+  // errorOnDeprecated: false,
+
+  // The default configuration for fake timers
+  // fakeTimers: {
+  //   "enableGlobally": false
+  // },
+
+  // Force coverage collection from ignored files using an array of glob patterns
+  // forceCoverageMatch: [],
+
+  // A path to a module which exports an async function that is triggered once before all test suites
+  // globalSetup: undefined,
+
+  // A path to a module which exports an async function that is triggered once after all test suites
+  // globalTeardown: undefined,
+
+  // A set of global variables that need to be available in all test environments
+  // globals: {},
+
+  // The maximum amount of workers used to run your tests. Can be specified as % or a number. E.g. maxWorkers: 10% will use 10% of your CPU amount + 1 as the maximum worker number. maxWorkers: 2 will use a maximum of 2 workers.
+  // maxWorkers: "50%",
+
+  // An array of directory names to be searched recursively up from the requiring module's location
+  // moduleDirectories: [
+  //   "node_modules"
+  // ],
+
+  // An array of file extensions your modules use
+  // moduleFileExtensions: [
+  //   "js",
+  //   "mjs",
+  //   "cjs",
+  //   "jsx",
+  //   "ts",
+  //   "tsx",
+  //   "json",
+  //   "node"
+  // ],
+
+  // A map from regular expressions to module names or to arrays of module names that allow to stub out resources with a single module
+  // moduleNameMapper: {},
+
+  // An array of regexp pattern strings, matched against all module paths before considered 'visible' to the module loader
+  // modulePathIgnorePatterns: [],
+
+  // Activates notifications for test results
+  // notify: false,
+
+  // An enum that specifies notification mode. Requires { notify: true }
+  // notifyMode: "failure-change",
+
+  // A preset that is used as a base for Jest's configuration
+  // preset: undefined,
+
+  // Run tests from one or more projects
+  // projects: undefined,
+
+  // Use this configuration option to add custom reporters to Jest
+  // reporters: undefined,
+
+  // Automatically reset mock state before every test
+  // resetMocks: false,
+
+  // Reset the module registry before running each individual test
+  // resetModules: false,
+
+  // A path to a custom resolver
+  // resolver: undefined,
+
+  // Automatically restore mock state and implementation before every test
+  // restoreMocks: false,
+
+  // The root directory that Jest should scan for tests and modules within
+  // rootDir: undefined,
+
+  // A list of paths to directories that Jest should use to search for files in
+  // roots: [
+  //   "<rootDir>"
+  // ],
+
+  // Allows you to use a custom runner instead of Jest's default test runner
+  // runner: "jest-runner",
+
+  // The paths to modules that run some code to configure or set up the testing environment before each test
+  // setupFiles: [],
+
+  // A list of paths to modules that run some code to configure or set up the testing framework before each test
+  // setupFilesAfterEnv: [],
+
+  // The number of seconds after which a test is considered as slow and reported as such in the results.
+  // slowTestThreshold: 5,
+
+  // A list of paths to snapshot serializer modules Jest should use for snapshot testing
+  // snapshotSerializers: [],
+
+  // The test environment that will be used for testing
+  // testEnvironment: "jest-environment-node",
+
+  // Options that will be passed to the testEnvironment
+  // testEnvironmentOptions: {},
+
+  // Adds a location field to test results
+  // testLocationInResults: false,
+
+  // The glob patterns Jest uses to detect test files
+  // testMatch: [
+  //   "**/__tests__/**/*.[jt]s?(x)",
+  //   "**/?(*.)+(spec|test).[tj]s?(x)"
+  // ],
+
+  // An array of regexp pattern strings that are matched against all test paths, matched tests are skipped
+  testPathIgnorePatterns: [
+    "\\\\node_modules\\\\",
+    "\\\\dist\\\\"
+  ],
+
+  // The regexp pattern or array of patterns that Jest uses to detect test files
+  // testRegex: [],
+
+  // This option allows the use of a custom results processor
+  // testResultsProcessor: undefined,
+
+  // This option allows use of a custom test runner
+  // testRunner: "jest-circus/runner",
+
+  // A map from regular expressions to paths to transformers
+  // transform: undefined,
+
+  // An array of regexp pattern strings that are matched against all source file paths, matched files will skip transformation
+  // transformIgnorePatterns: [
+  //   "\\\\node_modules\\\\",
+  //   "\\.pnp\\.[^\\\\]+$"
+  // ],
+
+  // An array of regexp pattern strings that are matched against all modules before the module loader will automatically return a mock for them
+  // unmockedModulePathPatterns: undefined,
+
+  // Indicates whether each individual test should be reported during the run
+  // verbose: undefined,
+
+  // An array of regexp patterns that are matched against all source file paths before re-running tests in watch mode
+  // watchPathIgnorePatterns: [],
+
+  // Whether to use watchman for file crawling
+  // watchman: true,
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+	"name": "kozz-module-maker",
+	"version": "0.1.0",
+	"description": "Library to create new module for the Kozz-Bot protocol",
+	"main": "./dist",
+	"license": "MIT",
+	"scripts": {
+		"dev": "tsc && link-module-alias && concurrently \"tsc --watch\" \"nodemon dist/debugIndex.js\"",
+		"start": "tsc && link-module-alias && node dist/index.js",
+		"test": "jest",
+		"docs": "typedoc ./src/index.ts",
+		"prepare": "husky install",
+		"refresh-lib": "./.husky./post-commit"
+	},
+	"devDependencies": {
+		"@types/jest": "^29.2.5",
+		"concurrently": "^7.5.0",
+		"kozz-types": "./../kozz-types/",
+		"nodemon": "^2.0.22",
+		"typedoc": "^0.23.21",
+		"typescript": "^5.0.4"
+	},
+	"dependencies": {
+		"arcsecond": "^5.0.0",
+		"dotenv": "^16.0.3",
+		"husky": "^8.0.3",
+		"link-module-alias": "^1.2.0",
+		"socket.io-client": "^4.6.1"
+	},
+	"_moduleAliases": {
+		"src": "dist"
+	}
+}

package/readme.md

@@ -0,0 +1,187 @@
+# Kozz Handler Maker
+
+This is a library that allows you to create your Handlers for any given chatbot created with Kozz-Bot.
+
+## Authentication
+
+All the entities connected to the Gateway must introduce themselves. Is at this point that the authenticaton happens using a pair of RSA keys. You can generate a pair running the script inside `./scripts/generate_key_pair.sh`. There will be a private key and a public key. The public key must be sent to the person who is running the `Kozz-Gateway` instance to be copied to the `./keys` folder. The name of the files must not be changed. After that, the authentication should be taken care. At the moment you have to authenticate all the entities with the same key pair but it's going to change in the future.
+
+If for some reason you need to generate the introduction payloads outside the library, you can run the scripts `./scripts/boundary_signature.js` or `./scripts/handler_signature.js`. The payload will be outputed to the console and you have to store the signature in a secure place. Currently it's the solution for you to authenticate when in a Web Browser because the readding of the key is done using `fs` which is not supported on browsers.
+
+```bash
+node ./scripts/handler_signature.js my-handler
+#                                       ^
+#                                    Name of the handler
+{
+  methods: [],
+  name: 'my-handler',
+  role: 'handler',
+  signature: 'EkeHbGsdky3r1AbXBkxnybipTtAdLhJ9sIV0w6BfN7tXpWWHztII7xvyROk0jAVdj3DjzQgWxRugxb2f5qAowcKLmr8akBCVU2PO5hnA/XaXjqX6XR2D+AOwVOYwJZk4ToiiJJ/s/qyouJ643cabm+sAt0VvYHsn2JUcg7YqZY4aexFfjHdWJMGFy8CV+JGtA9YTQvTa0+KZTgxE2qY+aLAmTQ3cXC7TML0EtNUgFJV9jlvWUg0Vm7x47unIyIZWROUm6LP8DPnVkraOFNICwWXqhJJ7FhdxiE88L/Q1s8i9T6deRF5tKiZYduOIXz7wQbB3xyrfAxei7s5vvVsIIA=='
+}
+```
+
+```bash
+node ./scripts/boundary_signature.js my-boundary
+#                                       ^
+#                                    Name of the boundary
+{
+  OS: 'windows',
+  platforrm: 'WA',
+  id: 'my-boundary',
+  role: 'boundary',
+  signature: 'ONidVqD49w6d7jitqBHtMJ5sJoTqoq1iDNZBruA+xCYLWv5IunY7MF0UwORPJK2pDb4bMlwW+yTd8UdFLlDBzXSEATY+CRUc3HJTS3Hwvf1mICmLqKykERb70I5v1Tba/htakTgKYpTBk1PSBfwabUcLQfNecMZoBoN7J5iCFATshBMeQXgh1mFV9PpS8eNVHnSFDu+d471va9C/BEFutQE+ezLXol/1wtxQm4wKO2a4z07ipUgCPwHaau5dyPPJYr5LDLFGrzzdYenOI5qLthF4Z3t6fswgfwYS5b/yg3tsXr1qgk6YY4Vn5ESjB1Jcits9qsvKz3ryL403nZ4wJg=='
+}
+```
+
+## Basic Controller
+
+The basic controller is a type of Handler that doens't receive messages. It's purpose is to send events to the boundaries or exchange resources with other entities.
+
+```typescript
+const basicController = createBasicController({
+	address: 'gateway_address',
+	name: 'myController', //must be unique
+});
+
+basicController.sendMessage('contact_id', 'boundary_id', 'Hello!!');
+
+basicController.ask
+	.handler('otherhandler', {
+		resource: 'some_resource',
+		data: {},
+	})
+	.then(resource => {
+		basicController.sendMessage.withMedia(
+			'contact_id',
+			'boundary_id',
+			'Here is your picture',
+			resource.response
+		);
+	});
+```
+
+## Message Proxy
+
+Message proxy is a type of Handler that will request all the messages from a given boundary to be forwareded to it. The proxy can also request only a single chat from the boundary to be proxied to it. The destination of the messages can be overritten, so there can be a proxy request for another entity other than the proxy itself.
+
+```typescript
+const proxy = createProxyInstance({
+	address: 'gateway_address',
+	source: 'source_boundary_id/chat_id',
+	name: 'my_proxy'
+	onMessage: message => {
+        if (message.body === "Hello"){
+            message.reply("World!");
+        }
+
+        // Stops listening to messages;
+        proxy.revoke();
+    },
+});
+
+const forwarder = createProxyInstance({
+	address: 'gateway_address',
+	source: 'source_boundary_id/*',
+    //Forwards all the messages to another boundary
+	name: 'my_other_boundary'
+    // Not dealing with messages here, just forwarding them
+	onMessage: message => {},
+});
+```
+
+## Command Handler
+
+The command handler is a cool CLI-ish command interpreter that can deal with strong-typed commands.
+
+The structure of a command is described below:
+
+### `/hanlder method immediateArg --argName1 arg_value1 --argName2 arg_value2...`
+
+`/` is the initial character. All the commands must start with one of the initial characters.
+
+`handler` is the name of the handler that must reply to the provided command.
+
+`method` is tha name of the method that the command is trying to execute. If no method is provided, it falls back to the method named "default";
+
+`immediateArg` is the argument that follows the method.
+
+`namedArgs` are arguments to the command that can be referencied with a name.
+
+```typescript
+createHandlerInstance({
+    // only commands comming from those bounaries will attempt to run the methods
+	boundariesToHandle: ['my_boundary', 'my-other-boundary'],
+	name: 'ping',
+	address: 'gateway_address',
+	methods: {
+        // `/ping` => `pong! 0,3 seconds`
+		...createMethod({
+            name: 'default',
+            args: {},
+            func: requester => {
+                const now = new Date().getTime();
+                const requestTime = requester.rawCommand.message.timestamp;
+                const difference = (now - requestTime) / 1000;
+
+                requester.reply(`Pong! ${difference} seconds`);
+            },
+        });
+
+        // `/ping echo test --foo true --bar 12345` => `you provided the correct args!`
+        // `/ping echo test --bar 12345` => `you provided the correct args!`
+        // `/ping echo --foo true --bar 12345` => _no_response_
+        ...createMethod({
+            name: 'echo',
+            args: {
+                immediate: "string"
+                foo: "boolean?",
+                bar: "number",
+            },
+            // the args will be type checked and strong typed in the callback;
+            func: (requester, {immediate, foo, bar, baz}) => {
+                requester.reply("you provided the correct args!");
+            },
+        });
+	},
+});
+```
+
+## From template
+
+You cand send or reply to messages using templates. Instead of relying on strings hard-coded in the methods or callbacks, you can create a simpler version of .MD files and read message templates direct from them. It is still in its early stages so you can bet the .md parser will fail. Use at your own risk.
+
+```markdown
+> @pong
+
+# PONG!
+
+Time: {{difference}} seconds
+
+> ---
+```
+
+```typescript
+createHandlerInstance({
+    boundariesToHandle: ['my_boundary', 'my-other-boundary'],
+	name: 'ping',
+	address: 'gateway_address',
+	methods: {
+        // `/ping` =>
+        // `PONG! (in bold)
+        // Time: 0.3 seconds` (interpolation with values is working)
+		...createMethod({
+            name: 'default',
+            args: {},
+            func: requester => {
+                const now = new Date().getTime();
+                const requestTime = requester.rawCommand.message.timestamp;
+                const difference = (now - requestTime) / 1000;
+
+                requester.reply.withTemplate('pong', {
+			        difference,
+		        });
+            },
+        });
+    templatePath: './src/Handlers/Ping/reply.kozz.md',
+});
+```

package/src/Instance/Common/ResourceMap/index.ts

@@ -0,0 +1,26 @@
+import { AskResourcePayload } from 'kozz-types/dist';
+
+type ResourceName = string;
+type ResourceGetter = (args: AskResourcePayload['request']['data']) => any;
+
+export type ResourceMap = {
+	[key: ResourceName]: ResourceGetter;
+};
+
+export const createResourceMap = () => {
+	const resourceMap: ResourceMap = {};
+
+	const upsertResource = (name: ResourceName, getter: ResourceGetter) => {
+		resourceMap[name] = getter;
+	};
+
+	const removeResource = (name: ResourceName) => {
+		delete resourceMap[name];
+	};
+
+	return {
+		resourceMap,
+		upsertResource,
+		removeResource,
+	};
+};

package/src/Instance/Common/UseFns/index.ts

@@ -0,0 +1,22 @@
+import { Command } from 'kozz-types';
+
+// [TODO] Better type for this
+type HandlerOrProxy = any;
+type HandleOrProxyGetter = () => HandlerOrProxy;
+
+export type UseFn = (args: Command) => Command;
+export type OriginalFn = (args: Command) => any;
+
+export const createUseFns = (instanceGetter: HandleOrProxyGetter) => {
+	const moduleUseFns: UseFn[] = [];
+
+	const use = (useFn: UseFn) => {
+		moduleUseFns.push(useFn);
+		return instanceGetter();
+	};
+
+	return {
+		moduleUseFns,
+		use,
+	};
+};

package/src/Instance/Common/index.ts

@@ -0,0 +1,3 @@
+export { createResourceMap } from './ResourceMap';
+export { UseFn, createUseFns } from './UseFns';
+export { onEvent } from './onEvent';

package/src/Instance/Common/onEvent/index.ts

@@ -0,0 +1,105 @@
+import { Socket } from 'socket.io-client';
+import { ForwardedEventPayload } from 'kozz-types';
+import crypto from 'crypto';
+
+type OnEvent = {
+	name: string;
+	source: string;
+	listeners: {
+		id: string;
+		cb: (ev: any) => any;
+	}[];
+};
+
+export const onEvent = (socket: Socket, handlerId: string) => {
+	const eventListeners: OnEvent[] = [];
+
+	const getListenersFromEvent = (evName: string) => {
+		return eventListeners.find(ev => ev.name === evName);
+	};
+
+	const on = (
+		evName: string,
+		eventSource: string,
+		callback: (ev: any) => any
+	) => {
+		if (!eventListeners.find(listener => listener.name === evName)) {
+			eventListeners.push({
+				name: evName,
+				source: eventSource,
+				listeners: [],
+			});
+		}
+
+		const id = crypto.randomUUID();
+
+		eventListeners
+			.find(listener => listener.name === evName)
+			?.listeners.push({
+				id,
+				cb: callback,
+			});
+
+		socket.emit('event_forward_request', {
+			sourceId: eventSource,
+			destination: {
+				id: handlerId,
+				type: 'Handler',
+			},
+			eventName: evName,
+		});
+
+		return {
+			eventId: id,
+			revoke: removeListener(evName, id),
+		};
+	};
+
+	const resendEvents = () => {
+		eventListeners.forEach(({ name, listeners, source }) => {
+			listeners.forEach(({ id, cb }) => {
+				socket.emit('event_forward_request', {
+					sourceId: source,
+					destination: {
+						id: handlerId,
+						type: 'Handler',
+					},
+					eventName: name,
+				});
+			});
+		});
+	};
+
+	const removeListener = (evName: string, evId: string) => () => {
+		const event = getListenersFromEvent(evName);
+		if (!event?.listeners) return;
+		event.listeners = event?.listeners.filter(listener => listener.id !== evId);
+		if (event.listeners.length === 0) {
+			socket.emit('event_forward_revoke', {
+				eventName: evName,
+				destination: {
+					id: handlerId,
+					type: 'Handler',
+				},
+			});
+		}
+	};
+
+	const tryRunEventListeners = (evName: string, eventPayload: any) => {
+		const event = getListenersFromEvent(evName);
+		if (!event?.listeners) return;
+		event.listeners.forEach(listener => listener.cb(eventPayload));
+	};
+
+	socket.on('forwarded_event', (event: ForwardedEventPayload) => {
+		console.log('Received Event aaa');
+		tryRunEventListeners(event.eventName, event.payload);
+	});
+
+	socket.on('connect', resendEvents);
+
+	return {
+		on,
+		tryRunEventListeners,
+	};
+};

package/src/Instance/GeneralModule/index.ts

@@ -0,0 +1,98 @@
+import { Method, TypeString } from '../../Schema';
+import { createResourceMap, createUseFns, onEvent } from '../Common';
+import { connect } from '../../Socket';
+import { revokeProxy } from '../../Socket/Events/Emit/RevokeProxy';
+import { requestProxy } from '../../Socket/Events/Emit/RequestProxy';
+import { ProxiedMessageObject } from '../../Message/ProxiedMessage';
+import { Source } from 'kozz-types';
+import { onAskResource } from '../../Socket/Events/Handle/AskResource';
+import { sendMessageToContact } from '../../Message/RoutineCreation/SendMessage';
+import { createAskResource } from '../../Message/RoutineCreation/AskResource';
+
+export type ControllerInitParams<Methods extends Record<string, TypeString>> = {
+	name: string;
+	address: string;
+	templatePath?: string;
+	signature?: string;
+
+	commands?: {
+		boundariesToHandle: string[];
+		methods?: Record<string, Method<Methods>>;
+	};
+
+	proxy?: {
+		source: Source;
+		destinationOverride?: string;
+		onMessage: (message: ProxiedMessageObject) => any;
+		keepAliveProxy?: boolean;
+	};
+};
+
+export const createModule = <Methods extends Record<string, TypeString>>({
+	name,
+	address,
+	commands,
+	proxy,
+	signature,
+	templatePath,
+}: ControllerInitParams<Methods>) => {
+	const { moduleUseFns, use } = createUseFns(() => instance);
+
+	const { socket, registerMethods } = connect(
+		address,
+		moduleUseFns,
+		templatePath || '',
+		name,
+		commands?.methods || {},
+		commands?.boundariesToHandle || [],
+		signature
+	);
+
+	if (commands?.methods) {
+		registerMethods(commands?.methods);
+	}
+
+	if (proxy) {
+		requestProxy(socket, {
+			address,
+			name,
+			...proxy,
+		});
+	}
+
+	const { removeResource, resourceMap, upsertResource } = createResourceMap();
+	onAskResource(socket, resourceMap);
+
+	const sendMessage = sendMessageToContact(socket, name);
+
+	let revoke = () => {
+		if (proxy) {
+			revokeProxy(socket, proxy.source);
+		}
+	};
+
+	const { on } = onEvent(socket, name);
+
+	const ask = createAskResource(socket, {
+		requester: {
+			id: name,
+			type: 'Handler',
+		},
+	});
+
+	const instance = {
+		use,
+		on,
+		sendMessage,
+		resources: {
+			removeResource,
+			upsertResource,
+		},
+		proxy: {
+			revoke,
+		},
+		ask,
+	};
+
+	return instance;
+};