@elite-dangerous-plugin-framework/core 0.0.1-pre1

package/README.md

@@ -0,0 +1,3 @@
+# @elite-dangerous-plugin-framework/core
+
+Contains core, framework-independent helpers. You usually always want to have this imported for a plugin.

package/dist/_virtual/rolldown_runtime.js

@@ -0,0 +1,18 @@
+//#region rolldown:runtime
+var __defProp = Object.defineProperty;
+var __exportAll = (all, symbols) => {
+	let target = {};
+	for (var name in all) {
+		__defProp(target, name, {
+			get: all[name],
+			enumerable: true
+		});
+	}
+	if (symbols) {
+		__defProp(target, Symbol.toStringTag, { value: "Module" });
+	}
+	return target;
+};
+
+//#endregion
+export { __exportAll };

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { index_d_exports } from "./v1alpha/index.js";
+export { index_d_exports as V1Alpha };

package/dist/index.js

@@ -0,0 +1,3 @@
+import { v1alpha_exports } from "./v1alpha/index.js";
+
+export { v1alpha_exports as V1Alpha };

package/dist/v1alpha/context.d.ts

@@ -0,0 +1,125 @@
+import { JournalEventItemV1Alpha } from "./journalEvent.js";
+import { PluginManifestV1AlphaWithId } from "./manifest.js";
+
+//#region src/v1alpha/context.d.ts
+/**
+ * When subscribing to Listeners, you get back a function that you must invoke to stop listening.
+ * It is the caller's responsibility to do so.
+ */
+type Destructor = () => void;
+/**
+ * This is the main object your Plugin interacts with EDPF
+ *
+ * You can subscribe to events, requests specific Procedures (e.g requesting entire current journal file) (based on what your permissions allow)
+ */
+interface PluginContextV1Alpha {
+  /**
+   * ## Used to receive Journal Events
+   *
+   * Pass a callback into this method. The Callback will be invoked each time a Journal Event is received.
+   *
+   * Note that EDPF does Event batching, meaining you receive a List of Events if they happen in very quick succession.
+   *
+   * This can be called multiple times. On call, you get back a destructor that should be invoked to unregister.
+   */
+  registerEventListener(callback: (events: JournalEventItemV1Alpha[]) => void): Destructor;
+  /**
+   * ## Used to block shutdown for cleanup tasks
+   *
+   * If your Plugin requires some form of cleanup / finalizing, register a shutdown listener here.
+   * When stopping a Plugin, the Context will **wait up to a second** for you to finish cleanup.
+   *
+   * Cleanup is considered finished **when the Promise returns**. The callback is invoked once only
+   *
+   * This can be called multiple times. On call, you get back a destructor that should be invoked to unregister.
+   */
+  registerShutdownListener(callback: () => Promise<void>): Destructor;
+  /**
+   * ## Used to open a URL in the User's browser
+   *
+   * Note that using a `<a href="…"/>` is not possible as that would cause In-Webview navigation. Instead, you have to instruct the OS to open the resource outside the webview.
+   * This Command does just that. Do note that only the `http` and `https` protocols are supported.
+   *
+   * This action is considered a Safe action and is accessible to all plugins without additional permissions
+   */
+  openUrl(url: string): Promise<void>;
+  /**
+   * ## Request a reread of the current Journal
+   *
+   * This will replay all open Journals (one per CMDR), which should get the plugin up to speed on the current state.
+   *
+   * @returns a mapping containing CMDR Names as the Key and the entire file's events until this point in time within the Batch.
+   */
+  rereadCurrentJournals(): Promise<Record<string, JournalEventItemV1Alpha[]>>;
+  /**
+   * This is useful for writing plugins in a more abstract manner. (e.g. not hardcoding settings keys).
+   * The property exposes the Plugin Manifest
+   */
+  get pluginMeta(): PluginManifestV1AlphaWithId;
+  /**
+   * Your Plugin is exposed via an asset server that is running on localhost. The Port is not stable. Use this readonly property to get the base URL.
+   *
+   * You can then append the path to the file, relative to the `frontend` folder. Do note that relative escapes out of the `frontend` folder are not supported.
+   *
+   * `assetsBase` has always a `/` as a suffix.
+   */
+  get assetsBase(): string;
+  /**
+   * Accessing Settings, as well as any non-default Methods, is done via the capabilities object
+   */
+  get Capabilities(): PluginContextV1AlphaCapabilities;
+}
+/**
+ * Interacting with EDPF beyond the usual receiving of journal events is done with the help of **Capabilities**.
+ *
+ * There is a set of default capabilities that are deemed safe to use and sensible defaults. There are however also more complex cases that require more access to the user's system.
+ * A plugin has to advertise its need to for these capabilities. It can do so via it's manifest file.
+ *
+ * When using non-standard capabilities, a User is prompted / warned the first time they try to run the plugin.
+ */
+interface PluginContextV1AlphaCapabilities {
+  /**
+   * **Enabled by default**
+   *
+   * always present, used to read and write settings.
+   */
+  get Settings(): PluginContextV1AlphaCapabilitiesSettings;
+}
+interface PluginContextV1AlphaCapabilitiesSettings {
+  /**
+   * ## Write a setting for this plugin
+   *
+   * You can also push settings outside the Settings UI. Use this function to write a key / value pair.
+   *
+   * This is what you should look out for:
+   * - The key contains segments, separated by a dot (.)
+   * - You need at least 2 Segments
+   * - the first segment **MUST** be your plugin ID
+   * - the last segment determines if this is a "public" setting. If it starts uppercase, it is readable by every plugin
+   *    - `myPlugin.some.key` is private. Only your own plugin can read and edit it and get notified about it
+   *    - `myPlugin.some.Key` is public. You can read and edit it, other plugins can read it
+   */
+  writeSetting<T>(key: string, value: undefined | T): Promise<undefined | T>;
+  /**
+   * ## Fetches a setting by Key.
+   * See Docs for {@link writeSetting()} for key structure
+   *
+   * Return the setting if present, undefined if it doesnt exist.
+   * Throws an error if you are not allowed to access this setting
+   */
+  getSetting<T>(key: string): Promise<T | undefined>;
+  /**
+   * ## Used to listen for Settings
+   *
+   * Any plugin may listen for its own and other plugins changing their settings
+   *
+   * Do note that only keys where the last segment starts with an **Uppercase** char will be propagated here, except if the setting key is from your own plugin. This only gives you the key. If you wish the get the value, you should invoke {@link getSetting}
+   *
+   * This function can be called multiple times. **Each call gives you back an unlistener. Invoke it for clean up**. Callbacks are cleaned up automatically on Plugin shutdown.
+   *
+   */
+  registerSettingsChangedListener(callback: (key: string, value: unknown) => void): Destructor;
+}
+//#endregion
+export { Destructor, PluginContextV1Alpha, PluginContextV1AlphaCapabilitiesSettings };
+//# sourceMappingURL=context.d.ts.map

package/dist/v1alpha/element.d.ts

@@ -0,0 +1,21 @@
+import { PluginContextV1Alpha } from "./context.js";
+import { PluginSettingsContextV1Alpha } from "./settingsContext.js";
+
+//#region src/v1alpha/element.d.ts
+/**
+ * Inherit from this class for your Plugin definition if your manifest defines `v1alpha` as the type!
+ */
+declare abstract class EDPFPluginElementV1Alpha extends HTMLElement {
+  abstract initPlugin(ctx: PluginContextV1Alpha): void;
+}
+/**
+ * Inherit from this class for your Plugin **Settings** definition if your manifest defines `v1alpha` as the type!
+ *
+ * Note that the settings element is stripped down and only contains the relevant methods to get and update secrets.
+ */
+declare abstract class EDPFPluginSettingsElementV1Alpha extends HTMLElement {
+  abstract initSettings(ctx: PluginSettingsContextV1Alpha): void;
+}
+//#endregion
+export { EDPFPluginElementV1Alpha, EDPFPluginSettingsElementV1Alpha };
+//# sourceMappingURL=element.d.ts.map

package/dist/v1alpha/element.js

@@ -0,0 +1,15 @@
+//#region src/v1alpha/element.ts
+/**
+* Inherit from this class for your Plugin definition if your manifest defines `v1alpha` as the type!
+*/
+var EDPFPluginElementV1Alpha = class extends HTMLElement {};
+/**
+* Inherit from this class for your Plugin **Settings** definition if your manifest defines `v1alpha` as the type!
+*
+* Note that the settings element is stripped down and only contains the relevant methods to get and update secrets.
+*/
+var EDPFPluginSettingsElementV1Alpha = class extends HTMLElement {};
+
+//#endregion
+export { EDPFPluginElementV1Alpha, EDPFPluginSettingsElementV1Alpha };
+//# sourceMappingURL=element.js.map

package/dist/v1alpha/element.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"element.js","names":[],"sources":["../../src/v1alpha/element.ts"],"sourcesContent":["import { PluginContextV1Alpha } from \"./context.js\";\nimport { PluginSettingsContextV1Alpha } from \"./settingsContext.js\";\n\n/**\n * Inherit from this class for your Plugin definition if your manifest defines `v1alpha` as the type!\n */\nexport abstract class EDPFPluginElementV1Alpha extends HTMLElement {\n  public abstract initPlugin(ctx: PluginContextV1Alpha): void;\n}\n\n/**\n * Inherit from this class for your Plugin **Settings** definition if your manifest defines `v1alpha` as the type!\n *\n * Note that the settings element is stripped down and only contains the relevant methods to get and update secrets.\n */\nexport abstract class EDPFPluginSettingsElementV1Alpha extends HTMLElement {\n  public abstract initSettings(ctx: PluginSettingsContextV1Alpha): void;\n}\n"],"mappings":";;;;AAMA,IAAsB,2BAAtB,cAAuD,YAAY;;;;;;AASnE,IAAsB,mCAAtB,cAA+D,YAAY"}

package/dist/v1alpha/index.d.ts

@@ -0,0 +1,12 @@
+import { JournalEventItemV1Alpha } from "./journalEvent.js";
+import { PluginContextV1Alpha } from "./context.js";
+import { PluginSettingsContextV1Alpha } from "./settingsContext.js";
+import { EDPFPluginElementV1Alpha, EDPFPluginSettingsElementV1Alpha } from "./element.js";
+
+//#region src/v1alpha/index.d.ts
+declare namespace index_d_exports {
+  export { EDPFPluginElementV1Alpha, EDPFPluginSettingsElementV1Alpha, JournalEventItemV1Alpha, PluginContextV1Alpha, PluginSettingsContextV1Alpha };
+}
+//#endregion
+export { EDPFPluginElementV1Alpha, EDPFPluginSettingsElementV1Alpha, type JournalEventItemV1Alpha, type PluginContextV1Alpha, type PluginSettingsContextV1Alpha, index_d_exports };
+//# sourceMappingURL=index.d.ts.map

package/dist/v1alpha/index.js

@@ -0,0 +1,12 @@
+import { __exportAll } from "../_virtual/rolldown_runtime.js";
+import { EDPFPluginElementV1Alpha, EDPFPluginSettingsElementV1Alpha } from "./element.js";
+
+//#region src/v1alpha/index.ts
+var v1alpha_exports = /* @__PURE__ */ __exportAll({
+	EDPFPluginElementV1Alpha: () => EDPFPluginElementV1Alpha,
+	EDPFPluginSettingsElementV1Alpha: () => EDPFPluginSettingsElementV1Alpha
+});
+
+//#endregion
+export { EDPFPluginElementV1Alpha, EDPFPluginSettingsElementV1Alpha, v1alpha_exports };
+//# sourceMappingURL=index.js.map

package/dist/v1alpha/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/v1alpha/index.ts"],"sourcesContent":["export type { PluginContextV1Alpha } from \"./context.js\";\nexport type { PluginSettingsContextV1Alpha } from \"./settingsContext.js\";\nexport type { JournalEventItemV1Alpha } from \"./journalEvent.js\";\nexport {\n  EDPFPluginElementV1Alpha,\n  EDPFPluginSettingsElementV1Alpha,\n} from \"./element.js\";\n"],"mappings":""}

package/dist/v1alpha/journalEvent.d.ts

@@ -0,0 +1,19 @@
+//#region src/v1alpha/journalEvent.d.ts
+/**
+ * EDPF sends Journal Items as stringified JSON.
+ * EDPF does a bit of buffering to reduce the amount of internal events being sent.
+ *
+ * As of 2025-11, this buffering is based on two timers:
+ * - a soft-resettable 0.1s (if a new event drops in, the timer resets)
+ * - a hard cap at 0.5s
+ *
+ * Events are guaranteed to be sorted as they are found in the journal.
+ */
+interface JournalEventItemV1Alpha {
+  cmdr: string;
+  file: string;
+  event: string;
+}
+//#endregion
+export { JournalEventItemV1Alpha };
+//# sourceMappingURL=journalEvent.d.ts.map

package/dist/v1alpha/manifest.d.ts

@@ -0,0 +1,15 @@
+//#region src/v1alpha/manifest.d.ts
+interface PluginManifestV1Alpha {
+  type: "v1alpha";
+  name: string;
+  description?: string | null | undefined;
+  repository_url?: string | null | undefined;
+  support_url?: string | null | undefined;
+  version?: string | null | undefined;
+}
+type PluginManifestV1AlphaWithId = PluginManifestV1Alpha & {
+  id: string;
+};
+//#endregion
+export { PluginManifestV1AlphaWithId };
+//# sourceMappingURL=manifest.d.ts.map

package/dist/v1alpha/settingsContext.d.ts

@@ -0,0 +1,51 @@
+import { PluginManifestV1AlphaWithId } from "./manifest.js";
+import { Destructor, PluginContextV1AlphaCapabilitiesSettings } from "./context.js";
+
+//#region src/v1alpha/settingsContext.d.ts
+/**
+ * The settings context. This is trimmed down and does not get any Journal updates. You only get access to read and write Settings here, plus get the assetsBase so you can load images / stylesheets.
+ */
+interface PluginSettingsContextV1Alpha {
+  /**
+   * **Enabled by default**
+   *
+   * always present, used to read and write settings.
+   */
+  get Settings(): PluginContextV1AlphaCapabilitiesSettings;
+  /**
+   * Your Plugin is exposed via an asset server that is running on localhost. The Port is not stable. Use this readonly property to get the base URL.
+   *
+   * You can then append the path to the file, relative to the `frontend` folder. Do note that relative escapes out of the `frontend` folder are not supported.
+   *
+   * `assetsBase` has always a `/` as a suffix.
+   */
+  get assetsBase(): string;
+  /**
+   * This is useful for writing plugins in a more abstract manner. (e.g. not hardcoding settings keys).
+   * The property exposes the Plugin Manifest
+   */
+  get pluginMeta(): PluginManifestV1AlphaWithId;
+  /**
+   * ## Used to block shutdown for cleanup tasks
+   *
+   * If your Plugin requires some form of cleanup / finalizing, register a shutdown listener here.
+   * When stopping a Plugin, the Context will **wait up to a second** for you to finish cleanup.
+   *
+   * Cleanup is considered finished **when the Promise returns**. The callback is invoked once only
+   *
+   * This can be called multiple times. On call, you get back a destructor that should be invoked to unregister.
+   */
+  registerShutdownListener(callback: () => Promise<void>): Destructor;
+  /**
+   * ## Used to open a URL in the User's browser
+   *
+   * Note that using a `<a href="…"/>` is not possible as that would cause In-Webview navigation. Instead, you have to instruct the OS to open the resource outside the webview.
+   * This Command does just that. Do note that only the `http` and `https` protocols are supported.
+   *
+   * This action is considered a Safe action and is accessible to all plugins without additional permissions
+   */
+  openUrl(url: string): Promise<void>;
+}
+//#endregion
+export { PluginSettingsContextV1Alpha };
+//# sourceMappingURL=settingsContext.d.ts.map

package/package.json

@@ -0,0 +1,29 @@
+{
+  "private": false,
+  "name": "@elite-dangerous-plugin-framework/core",
+  "description": "Core Plugin Library for Elite: Dangerous Plugin Framework. This provides mostly types and helpers to interact with EDPF, as well as an abstraction layer around the HTMLElement used by plugins.",
+  "workspaces": [
+    "packages/*"
+  ],
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "pretty": "prettier src -w"
+  },
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./v1alpha": "./dist/v1alpha/index.js",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "provenance": false,
+    "access": "public"
+  },
+  "version": "0.0.1-pre1",
+  "gitHead": "c7919bb37e1b55eadd413bd0e8ceda64adabdf23"
+}