@forgedesk/api 2.0.0

package/README.md

@@ -0,0 +1,28 @@
+# @forgedesk/api
+
+Typed JavaScript bindings for the Forge runtime.
+
+## Requirements
+
+- Forge runtime embedded in a Python 3.14+ free-threaded app
+
+## Install
+
+```bash
+npm install @forgedesk/api
+```
+
+## Usage
+
+```js
+import forge, { invoke, isForgeAvailable } from "@forgedesk/api";
+
+if (isForgeAvailable()) {
+  const version = await forge.app.version();
+  const state = await forge.window.state();
+  const result = await invoke("greet", { name: "Forge" });
+  console.log(version, state, result);
+}
+```
+
+This package expects the Forge runtime to inject `window.__forge__`.

package/index.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Forge Automatically Generated TypeScript API
+ * Do not edit this file manually.
+ */
+
+export interface InvokeDetailedOptions {
+  detailed?: boolean;
+  trace?: boolean;
+}
+
+export interface ForgeClipboardApi {
+  clear(): Promise<Record<string, unknown>>;
+  read(): Promise<Record<string, unknown>>;
+  write(text: string): Promise<Record<string, unknown>>;
+}
+
+export interface ForgeMenuApi {
+  check(item_id: string, checked?: boolean): Promise<Record<string, unknown>>;
+  clear(): Promise<boolean>;
+  disable(item_id: string): Promise<Record<string, unknown>>;
+  enable(item_id: string): Promise<Record<string, unknown>>;
+  get(): Promise<any[]>;
+  set(items: any[]): Promise<any[]>;
+  trigger(item_id: string, payload?: Record<string, unknown>): Promise<Record<string, unknown>>;
+  uncheck(item_id: string): Promise<Record<string, unknown>>;
+}
+
+export interface ForgeApi {
+  invoke(command: string, args?: Record<string, unknown>): Promise<unknown>;
+  invokeDetailed(command: string, args?: Record<string, unknown>, options?: InvokeDetailedOptions): Promise<unknown>;
+  on(eventName: string, handler: (payload: unknown) => void): unknown;
+  once(eventName: string, handler: (payload: unknown) => void): unknown;
+  off(eventName: string, handler: (payload: unknown) => void): unknown;
+  clipboard: ForgeClipboardApi;
+  menu: ForgeMenuApi;
+  apply_native_selection(item_id: string, checked?: boolean): Promise<Record<string, unknown>>;
+  clear_user_attention(): Promise<void>;
+  confirm(title: string, message: string, level?: string): Promise<Record<string, unknown>>;
+  deep_link_open(url: string): Promise<Record<string, unknown>>;
+  deep_link_protocols(): Promise<Record<string, unknown>>;
+  deep_link_state(): Promise<Record<string, unknown>>;
+  delete(path: string, recursive?: boolean): Promise<void>;
+  disable(): Promise<boolean>;
+  enable(): Promise<boolean>;
+  exists(path: string): Promise<boolean>;
+  exit(): Promise<void>;
+  exit_app(): Promise<void>;
+  get_base_path(): Promise<unknown>;
+  get_battery_info(): Promise<Record<string, unknown>>;
+  get_cursor_screen_point(): Promise<Record<string, unknown>>;
+  get_cwd(): Promise<string>;
+  get_env(key: string, default?: string): Promise<string>;
+  get_info(): Promise<Record<string, unknown>>;
+  get_monitors(): Promise<any[]>;
+  get_platform(): Promise<string>;
+  get_primary_monitor(): Promise<Record<string, unknown>>;
+  get_version(): Promise<string>;
+  info(): Promise<Record<string, unknown>>;
+  is_dir(path: string): Promise<boolean>;
+  is_enabled(): Promise<boolean>;
+  is_file(path: string): Promise<boolean>;
+  list(path: string, include_hidden?: boolean): Promise<any[]>;
+  list_dir(path: string, include_hidden?: boolean): Promise<any[]>;
+  message(title: string, body: string, level?: string): Promise<Record<string, unknown>>;
+  mkdir(path: string, parents?: boolean): Promise<void>;
+  notification_history(limit?: number): Promise<any[]>;
+  notification_notify(title: string, body: string, icon?: string, app_name?: string, timeout?: number): Promise<Record<string, unknown>>;
+  notification_state(): Promise<Record<string, unknown>>;
+  on_resume(callback: unknown): Promise<void>;
+  on_suspend(callback: unknown): Promise<void>;
+  open(title?: string, filters?: any[], multiple?: boolean): Promise<Record<string, unknown>>;
+  open_directory(title?: string): Promise<Record<string, unknown>>;
+  open_file(title?: string, filters?: any[], multiple?: boolean): Promise<Record<string, unknown>>;
+  open_url(url: string): Promise<void>;
+  platform(): Promise<string>;
+  read(path: string, max_size?: number): Promise<string>;
+  read_binary(path: string, max_size?: number): Promise<unknown>;
+  register(accelerator: string, callback: unknown): Promise<boolean>;
+  relaunch(): Promise<void>;
+  request_single_instance_lock(instance_name?: string): Promise<boolean>;
+  request_user_attention(is_critical?: boolean): Promise<void>;
+  save(title?: string, default_path?: string, filters?: any[]): Promise<Record<string, unknown>>;
+  save_file(title?: string, default_path?: string, filters?: any[]): Promise<Record<string, unknown>>;
+  set_progress_bar(progress: number): Promise<void>;
+  unregister(accelerator: string): Promise<boolean>;
+  unregister_all(): Promise<boolean>;
+  version(): Promise<string>;
+  write(path: string, content: string): Promise<void>;
+  write_binary(path: string, content: unknown): Promise<void>;
+}
+
+export declare function isForgeAvailable(): boolean;
+export declare function getForge(): ForgeApi;
+export declare function invoke(command: string, args?: Record<string, unknown>): Promise<unknown>;
+export declare function invokeDetailed(command: string, args?: Record<string, unknown>, options?: InvokeDetailedOptions): Promise<unknown>;
+export declare function on(eventName: string, handler: (payload: unknown) => void): unknown;
+export declare function once(eventName: string, handler: (payload: unknown) => void): unknown;
+export declare function off(eventName: string, handler: (payload: unknown) => void): unknown;
+export declare const forge: ForgeApi;
+export default forge;

package/index.js

@@ -0,0 +1,47 @@
+function missingRuntimeError() {
+  return new Error(
+    "Forge runtime is not available. Load forge.js in a Forge window or run inside Forge dev/build output."
+  );
+}
+
+export function isForgeAvailable() {
+  return typeof globalThis !== "undefined" && !!globalThis.__forge__;
+}
+
+export function getForge() {
+  if (!isForgeAvailable()) {
+    throw missingRuntimeError();
+  }
+  return globalThis.__forge__;
+}
+
+export function invoke(command, args = {}) {
+  return getForge().invoke(command, args);
+}
+
+export function invokeDetailed(command, args = {}, options = {}) {
+  return getForge().invokeDetailed(command, args, options);
+}
+
+export function on(eventName, handler) {
+  return getForge().on(eventName, handler);
+}
+
+export function once(eventName, handler) {
+  return getForge().once(eventName, handler);
+}
+
+export function off(eventName, handler) {
+  return getForge().off(eventName, handler);
+}
+
+export const forge = new Proxy(
+  {},
+  {
+    get(_target, property) {
+      return getForge()[property];
+    },
+  }
+);
+
+export default forge;

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@forgedesk/api",
+  "version": "2.0.0",
+  "description": "Typed JavaScript API bindings for Forge applications",
+  "license": "MIT",
+  "homepage": "https://forge-framework.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/swadhinbiswas/Forge.git",
+    "directory": "packages/api"
+  },
+  "bugs": {
+    "url": "https://github.com/swadhinbiswas/Forge/issues"
+  },
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "forge",
+    "desktop",
+    "ipc",
+    "webview"
+  ]
+}