separated JavaScript and TypeScript export,

added AGENTS.md for AI bot

AGENTS.md

@@ -0,0 +1,37 @@
+# AGENTS.md
+
+## Project overview
+APIlite is a lightweight PHP library. A class extends `TPsoft\APIlite\APIlite`, public methods become API actions, requests are processed automatically, and responses are returned as JSON.
+
+The project also generates frontend clients:
+- JavaScript client: `format=javascript` (`.js`)
+- TypeScript client: `format=typescript` (`.ts`, real typed output)
+
+## Core files
+- `src/APIlite.php`: runtime, routing, docs JSON/HTML/client generation
+- `src/help.tpl.php`: HTML documentation template
+- `src/javascript.tpl.php`: JavaScript client template
+- `src/typescript.tpl.php`: TypeScript client template
+- `bin/apilite-files`: helper script for bootstrapping files in consumer projects
+
+## Working rules
+- Keep API behavior backward compatible unless explicitly requested.
+- Maintain both generated clients:
+  - JavaScript stays plain JS.
+  - TypeScript stays typed (interfaces + typed method signatures).
+- If you change output field names in JSON help, update README and templates consistently.
+- Prefer small, focused changes over broad rewrites.
+
+## Verification checklist
+- Run syntax checks on edited PHP files:
+  - `php -l src/APIlite.php`
+  - `php -l src/help.tpl.php`
+  - `php -l src/javascript.tpl.php`
+  - `php -l src/typescript.tpl.php`
+  - `php -l bin/apilite-files`
+- If client generation changes, test with:
+  - `php test/APIcalculator.php --javascript`
+  - `php test/APIcalculator.php --typescript`
+
+## Documentation rule
+When output format names/flags/URLs change, update `README.md` in the same change set.

README.md

@@ -132,6 +132,7 @@ When you run this subfile through the webserver, you will see the JSON documenta
 {
   "name": "APIcalculator",
   "html_version": "http://localhost/APIlite/test/APIcalculator.php?format=html",
+  "javascript_version": "http://localhost/APIlite/test/APIcalculator.php?format=javascript",
   "typescript_version": "http://localhost/APIlite/test/APIcalculator.php?format=typescript",
   "actions": [
     {
@@ -230,84 +231,33 @@ and there is also an HTML version available
 
 <img src="test/Example.APIcalculator.png" />
 
-To connect to the API from TypeScript (e.g. Vue application) it is possible to download the backend script
+You can also download generated frontend clients:
 
-```ts
+* JavaScript: `?format=javascript`
-/**
+* TypeScript (typed for Vue/TS projects): `?format=typescript`
- * Generated by APIlite
- * https://gitea.tpsoft.org/TPsoft.org/APIlite
- *
- * 2025-06-12 06:24:33 */
 
-class APIcalculator {
+JavaScript usage example:
-	endpont = "http://";
 
-	/* ----------------------------------------------------
+```js
-		* General API call
+import backend from './backend.js';
-		*/
-	call(method, data, callback) {
-			var xhttp = new XMLHttpRequest();
-			xhttp.withCredentials = true;
-			xhttp.onreadystatechange = function() {
-					if (this.readyState == 4) {
-							if (this.status == 200) {
-									if (callback != null) callback(JSON.parse(this.responseText));
-							} else {
-									if (callback != null) callback({'status': 'ERROR', 'message': 'HTTP STATUS ' + this.status});
-							}
-					}
-			}
-			var form_data  = new FormData();
-			Object.keys(data).forEach(key => {
-					let val = data[key];
-					if (typeof val == 'object') val = JSON.stringify(val);
-					form_data.append(key, val);
-			});
-			xhttp.open('POST', this.endpont + '?action=' + method);
-			xhttp.send(form_data);
-	}
 
-	callPromise(method, data) {
+backend.add(1, 2).then((response) => {
-			return new Promise((resolve, reject) => {
+	console.log(response.data);
-					this.call(method, data, function(response) {
+});
-							if (response.status == 'OK') {
-									resolve(response.data);
-							} else {
-									reject(response.msg);
-							}
-					});
-			})
-	}
-
-	/* ----------------------------------------------------
-		* API actions
-		*/
-	help() {
-			return this.callPromise('__HELP__', {});
-	}
-
-	add(a, b) {
-			return this.callPromise('add', {a: a, b: b});
-	}
-
-	subtract(a, b) {
-			return this.callPromise('subtract', {a: a, b: b});
-	}
-
-	multiply(a, b) {
-			return this.callPromise('multiply', {a: a, b: b});
-	}
-
-	divide(a, b) {
-			return this.callPromise('divide', {a: a, b: b});
-	}
-
-};
-
-export default new BackendAPI();
 ```
 
-These outputs can also be generated in the command line as follows
+TypeScript usage example (Vue + TS):
 
-* for HTML`$> php APIcalculator.php --html`
+```ts
-* for TypeScript`$> php APIcalculator.php --typescript`
+import backend from './backend';
+
+backend.add(1, 2).then((response) => {
+	console.log(response.data); // typed value based on PHP return type
+});
+```
+
+These outputs can also be generated in command line:
+
+* HTML: `$> php APIcalculator.php --html`
+* JavaScript: `$> php APIcalculator.php --javascript > backend.js` (`--js` alias is available)
+* TypeScript: `$> php APIcalculator.php --typescript > backend.ts`

bin/apilite-files

@@ -55,7 +55,7 @@ $backend_api = new TPsoft\BugreportBackend\API(\'typescript\', \'import.meta.env
 $output = ob_get_contents();
 ob_end_clean();
 
-$ts_path = realpath(__DIR__ . \'/../../frontend/src\').\'/backend.js\';
+$ts_path = realpath(__DIR__ . \'/../../frontend/src\').\'/backend.ts\';
 $suc = file_put_contents($ts_path, $output);
 if ($suc === false) {
 	echo "✗ TypeScript store into file failed\n";

composer.json

@@ -9,6 +9,7 @@
 		"rest",
 		"json",
 		"php",
+		"javascript",
 		"typescript"
 	],
 	"authors": [

src/APIlite.php

@@ -39,6 +39,9 @@ class APIlite
 				if (in_array('--html', $switches)) {
 					$format = 'html';
 				}
+				if (in_array('--javascript', $switches) || in_array('--js', $switches)) {
+					$format = 'javascript';
+				}
 				if (in_array('--typescript', $switches)) {
 					$format = 'typescript';
 				}
@@ -47,6 +50,10 @@ class APIlite
 				case 'html':
 					$this->printHelpHTML();
 					break;
+				case 'javascript':
+				case 'js':
+					$this->printHelpJavascript();
+					break;
 				case 'typescript':
 					$this->printHelpTypescript();
 					break;
@@ -189,6 +196,7 @@ class APIlite
 		$this->response(array(
 			'name' => $this->apiName,
 			'html_version' => $this->getCurrentUrl().'?format=html',
+			'javascript_version' => $this->getCurrentUrl().'?format=javascript',
 			'typescript_version' => $this->getCurrentUrl().'?format=typescript',
 			'actions' => $this->methods
 		));
@@ -199,20 +207,36 @@ class APIlite
 		include __DIR__ . '/help.tpl.php';
 	}
 
-	private function printHelpTypescript(): void
+	private function printHelpJavascript(): void
 	{
 		ob_clean();
 		header('Content-Type: application/javascript');
 		header('Content-Disposition: attachment; filename="' . $this->apiName . '.js"');
+		include __DIR__ . '/javascript.tpl.php';
+	}
+
+	private function printHelpTypescript(): void
+	{
+		ob_clean();
+		header('Content-Type: application/typescript');
+		header('Content-Disposition: attachment; filename="' . $this->apiName . '.ts"');
 		include __DIR__ . '/typescript.tpl.php';
 	}
 
 	private function getCurrentUrl(): string {
-		$protocol = (!empty($_SERVER['HTTPS']) && $_SERVER['HTTPS'] !== 'off' ||
+		$https = !empty($_SERVER['HTTPS']) && $_SERVER['HTTPS'] !== 'off';
-					 $_SERVER['SERVER_PORT'] == 443) ? "https://" : "http://";
+		$serverPort = isset($_SERVER['SERVER_PORT']) ? (int) $_SERVER['SERVER_PORT'] : null;
-		$host = $_SERVER['HTTP_HOST'];
+		$protocol = ($https || $serverPort === 443) ? 'https://' : 'http://';
-		$uri = $_SERVER['REQUEST_URI'];
+		$host = $_SERVER['HTTP_HOST'] ?? 'localhost';
+		$uri = $_SERVER['REQUEST_URI'] ?? ($_SERVER['SCRIPT_NAME'] ?? '/');
 		$path = parse_url($uri, PHP_URL_PATH);
+		if (!is_string($path) || $path === '') {
+			$path = '/';
+		}
+		$path = str_replace('\\', '/', $path);
+		if (substr($path, 0, 1) !== '/') {
+			$path = '/' . ltrim($path, '/');
+		}
 		return $protocol . $host . $path;
 	}
 

src/help.tpl.php

@@ -396,6 +396,7 @@
 		<nav class="nav-menu">
 			<div class="nav-links">
 				<a href="<?php echo $this->getCurrentUrl(); ?>?format=json">🔗 JSON Documentation</a>
+				<a href="<?php echo $this->getCurrentUrl(); ?>?format=javascript">📄 JavaScript backend script</a>
 				<a href="<?php echo $this->getCurrentUrl(); ?>?format=typescript">📄 TypeScript backend script</a>
 			</div>
 		</nav>

src/javascript.tpl.php

@@ -0,0 +1,69 @@
+/**
+ * Generated by APIlite
+ * https://gitea.tpsoft.org/TPsoft.org/APIlite
+ *
+ * <?php echo date('Y-m-d H:i:s'); ?>
+ */
+
+class <?php echo $this->apiName; ?> {
+	endpoint = <?php echo sprintf(substr($this->endpoint, 0, 4) == 'http' ? '"%s"' : '%s', $this->endpoint); ?>;
+
+	/* ----------------------------------------------------
+	 * General API call
+	 */
+	call(method, data, callback) {
+		var xhttp = new XMLHttpRequest();
+		xhttp.withCredentials = true;
+		xhttp.onreadystatechange = function() {
+			if (this.readyState === 4) {
+				if (this.status === 200) {
+					if (callback != null) callback(JSON.parse(this.responseText));
+				} else {
+					if (callback != null) callback({'status': 'ERROR', 'msg': 'HTTP STATUS ' + this.status});
+				}
+			}
+		}
+		var form_data  = new FormData();
+		Object.keys(data).forEach(key => {
+			let val = data[key];
+			if (typeof val === 'undefined') return;
+			if (typeof val == 'object') val = JSON.stringify(val);
+			form_data.append(key, val);
+		});
+		xhttp.open('POST', this.endpoint + '?action=' + method);
+		xhttp.send(form_data);
+	}
+
+	callPromise(method, data) {
+		return new Promise((resolve, reject) => {
+			this.call(method, data, function(response) {
+				if (method === '__HELP__') {
+					resolve(response);
+					return;
+				}
+				if (response.status === 'OK') {
+					resolve(response.data);
+				} else {
+					reject(response.msg);
+				}
+			});
+		})
+	}
+
+	/* ----------------------------------------------------
+	 * API actions
+	 */
+	help() {
+		return this.callPromise('__HELP__', {});
+	}
+
+<?php if (is_array($this->methods)) foreach ($this->methods as $method) {
+	echo "\t".$method['name'].'('.implode(', ', array_map(function($param) { return $param['name']; }, $method['params'])).') {';
+	echo "\n\t\treturn this.callPromise('".$method['name']."', {".implode(', ', array_map(function($param) { return $param['name'].': '.$param['name']; }, $method['params']))."});";
+	echo "\n\t}\n\n";
+	}
+?>
+
+};
+
+export default new <?php echo $this->apiName; ?>();

src/typescript.tpl.php

@@ -1,3 +1,39 @@
+<?php
+$mapType = function (?string $type): string {
+	if (!is_string($type) || $type === '') {
+		return 'unknown';
+	}
+
+	$type = strtolower(ltrim($type, '\\'));
+
+	return match ($type) {
+		'int', 'integer', 'float', 'double' => 'number',
+		'string' => 'string',
+		'bool', 'boolean' => 'boolean',
+		'array', 'iterable' => 'unknown[]',
+		'object', 'stdclass' => 'Record<string, unknown>',
+		'mixed', 'resource' => 'unknown',
+		'null', 'void' => 'null',
+		'scalar' => 'string | number | boolean',
+		'callable', 'closure' => '(...args: unknown[]) => unknown',
+		'never' => 'never',
+		default => 'unknown',
+	};
+};
+
+$mapUnionType = function (mixed $type) use ($mapType): string {
+	if (is_array($type)) {
+		$parts = array();
+		foreach ($type as $singleType) {
+			$parts[] = $mapType(is_string($singleType) ? $singleType : null);
+		}
+		$parts = array_values(array_unique($parts));
+		return empty($parts) ? 'unknown' : implode(' | ', $parts);
+	}
+
+	return $mapType(is_string($type) ? $type : null);
+};
+?>
 /**
  * Generated by APIlite
  * https://gitea.tpsoft.org/TPsoft.org/APIlite
@@ -5,64 +41,117 @@
  * <?php echo date('Y-m-d H:i:s'); ?>
  */
 
-class <?php echo $this->apiName; ?> {
+export interface APIliteActionResponse<T> {
-	endpoint = <?php echo sprintf(substr($this->endpoint, 0, 4) == 'http' ? '"%s"' : '%s', $this->endpoint); ?>;
+	status: 'OK';
+	data: T;
+}
 
-	/* ----------------------------------------------------
+export interface APIliteErrorResponse {
-	 * General API call
+	status: 'ERROR';
-	 */
+	msg: string;
-	call(method, data, callback) {
+}
-		var xhttp = new XMLHttpRequest();
+
+export interface APIliteMethodParam {
+	name: string;
+	type: string | null;
+	optional: boolean;
+	default: unknown;
+	doc: string | null;
+}
+
+export interface APIliteMethodDoc {
+	name: string;
+	doc: string | null;
+	description: string | null;
+	params: APIliteMethodParam[];
+	return: string | string[] | null;
+}
+
+export interface APIliteHelpResponse {
+	name: string;
+	html_version: string;
+	javascript_version: string;
+	typescript_version: string;
+	actions: APIliteMethodDoc[];
+}
+
+class <?php echo $this->apiName; ?> {
+	endpoint: string = <?php echo sprintf(substr($this->endpoint, 0, 4) == 'http' ? '"%s"' : '%s', $this->endpoint); ?>;
+
+	private call(
+		method: string,
+		data: Record<string, unknown>,
+		callback: (response: APIliteHelpResponse | APIliteActionResponse<unknown> | APIliteErrorResponse) => void
+	): void {
+		const xhttp = new XMLHttpRequest();
 		xhttp.withCredentials = true;
 		xhttp.onreadystatechange = function() {
-			if (this.readyState == 4) {
+			if (this.readyState === 4) {
-				if (this.status == 200) {
+				if (this.status === 200) {
-					if (callback != null) callback(JSON.parse(this.responseText));
+					const response = JSON.parse(this.responseText) as APIliteHelpResponse | APIliteActionResponse<unknown> | APIliteErrorResponse;
+					callback(response);
 				} else {
-					if (callback != null) callback({'status': 'ERROR', 'message': 'HTTP STATUS ' + this.status});
+					callback({ status: 'ERROR', msg: 'HTTP STATUS ' + this.status });
 				}
 			}
-		}
+		};
-		var form_data  = new FormData();
+
-		Object.keys(data).forEach(key => {
+		const formData = new FormData();
-			let val = data[key];
+		Object.keys(data).forEach((key) => {
-			if (typeof val == 'object') val = JSON.stringify(val);
+			const rawValue = data[key];
-			form_data.append(key, val);
+			if (typeof rawValue === 'undefined') {
+				return;
+			}
+			let value: string | Blob;
+			if (rawValue instanceof Blob) {
+				value = rawValue;
+			} else if (typeof rawValue === 'object' && rawValue !== null) {
+				value = JSON.stringify(rawValue);
+			} else {
+				value = String(rawValue);
+			}
+			formData.append(key, value);
 		});
+
 		xhttp.open('POST', this.endpoint + '?action=' + method);
-		xhttp.send(form_data);
+		xhttp.send(formData);
 	}
 
-	callPromise(method, data) {
+	private callPromise<T>(method: string, data: Record<string, unknown>): Promise<T> {
-		return new Promise((resolve, reject) => {
+		return new Promise<T>((resolve, reject) => {
-			this.call(method, data, function(response) {
+			this.call(method, data, (response) => {
-				if (method == '__HELP__') {
+				if (method === '__HELP__') {
-					resolve(response);
+					resolve(response as T);
 					return;
 				}
-				if (response.status == 'OK') {
+				if (response.status === 'OK') {
-					resolve(response.data);
+					resolve(response.data as T);
-				} else {
+					return;
-					reject(response.msg);
 				}
+				reject(response.msg);
 			});
-		})
+		});
 	}
 
-	/* ----------------------------------------------------
+	help(): Promise<APIliteHelpResponse> {
-	 * API actions
+		return this.callPromise<APIliteHelpResponse>('__HELP__', {});
-	 */
-	help() {
-		return this.callPromise('__HELP__', {});
 	}
 
 <?php if (is_array($this->methods)) foreach ($this->methods as $method) {
-	echo "\t".$method['name'].'('.implode(', ', array_map(function($param) { return $param['name']; }, $method['params'])).') {';
+	$paramsSignature = array();
-	echo "\n\t\treturn this.callPromise('".$method['name']."', {".implode(', ', array_map(function($param) { return $param['name'].': '.$param['name']; }, $method['params']))."});";
+	$paramsPayload = array();
-	echo "\n\t}\n\n";
+	foreach ($method['params'] as $param) {
+		$paramType = $mapType($param['type']);
+		$paramsSignature[] = $param['name'] . ($param['optional'] ? '?' : '') . ': ' . $paramType;
+		$paramsPayload[] = $param['name'];
 	}
+	$returnType = $mapUnionType($method['return']);
 ?>
+	<?php echo $method['name']; ?>(<?php echo implode(', ', $paramsSignature); ?>): Promise<APIliteActionResponse<<?php echo $returnType; ?>>> {
+		return this.callPromise<APIliteActionResponse<<?php echo $returnType; ?>>>('<?php echo $method['name']; ?>', { <?php echo implode(', ', $paramsPayload); ?> });
+	}
 
-};
+<?php } ?>
+}
 
 export default new <?php echo $this->apiName; ?>();