flint-plugin-api 0.11.0 → 0.13.0

package/README.md

@@ -28,11 +28,12 @@ A plugin is a folder inside a vault's `.flint/plugins/` directory:
   "version": "1.0.0",
   "author": "You",
   "description": "What it does.",
-  "license": "AGPL-3.0-or-later"
+  "license": "AGPL-3.0-or-later",
+  "minAppVersion": "0.12.0"
 }
 ```
 
-The `license` is an [SPDX expression](https://spdx.org/licenses/). Flint is AGPL-3.0-or-later, so plugins must use a compatible free license; Flint warns before enabling a plugin that doesn't.
+The `license` is an [SPDX expression](https://spdx.org/licenses/). Flint is AGPL-3.0-or-later, so plugins must use a compatible free license; Flint warns before enabling a plugin that doesn't. `minAppVersion` is optional: older versions of Flint refuse to load the plugin and say which version it needs.
 
 `main.js` is an ES module whose default export receives the Flint API:
 
@@ -50,6 +51,8 @@ Everything registered through the API (commands, editor extensions, sidebar tabs
 
 Use `flint.codemirror` instead of bundling your own copy of CodeMirror; two copies in the same editor break it.
 
+To talk to a web service, use `flint.http.request()`: it runs in Flint's backend, so the server doesn't have to allow the app's origin (CORS), and it trusts certificates from the system's store. Keep tokens and passwords in `flint.secrets`, which stores them in the system's keychain instead of the vault. `flint.ui.renderDataView()` shows your own rows with the views of Bases (table, cards, list and map) along with their filters, sorting and summaries.
+
 For type hints, copy [`index.d.ts`](index.d.ts) next to your plugin and annotate `activate` with `/** @type {import('./index').ActivatePlugin} */`. See it for the full API and [`examples/word-count`](../examples/word-count) for a working plugin. To try it, copy the folder into your vault's `.flint/plugins/` and turn it on in Settings.
 
 Plugins run inside Flint with the same access as the app itself. Only turn on plugins you trust.

package/index.d.ts

@@ -65,6 +65,25 @@ export type CodeBlockProcessor = (
   context: MarkdownContext,
 ) => unknown
 
+export interface HttpRequest {
+  /** An `http://` or `https://` URL. */
+  url: string
+  /** Defaults to `GET`. */
+  method?: string
+  headers?: Record<string, string>
+  body?: string
+  /** Defaults to 30 seconds. */
+  timeoutMs?: number
+}
+
+export interface HttpResponse {
+  status: number
+  headers: Record<string, string>
+  body: string
+  /** The body parsed as JSON. */
+  json<T = unknown>(): T
+}
+
 /** A row a plugin shows in a data view. */
 export interface DataRow {
   /** Unique within the view. */
@@ -132,6 +151,8 @@ export interface FlintApi {
 
   ui: {
     notice(message: string): void
+    /** Opens a web or mail link in the system's default app. */
+    openUrl(url: string): void
     registerSidebarTab(tab: SidebarTab): Disposer
     /** Adds a section named after the plugin to Settings. */
     registerSettingsTab(tab: SettingsTab): Disposer
@@ -147,6 +168,19 @@ export interface FlintApi {
     registerCodeBlockProcessor(language: string, processor: CodeBlockProcessor): Disposer
   }
 
+  /** Requests made from Flint's backend, so servers don't need to allow the app's origin (CORS).
+   * Certificates are checked against the system's store, where companies install their own. */
+  http: {
+    request(request: HttpRequest): Promise<HttpResponse>
+  }
+
+  /** Secrets such as API tokens, kept in the system's keychain rather than in the vault. */
+  secrets: {
+    get(key: string): Promise<string | null>
+    set(key: string, value: string): Promise<void>
+    delete(key: string): Promise<void>
+  }
+
   storage: {
     load<T = unknown>(): Promise<T | null>
     save(data: unknown): Promise<void>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flint-plugin-api",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "TypeScript types for writing Flint plugins",
   "license": "AGPL-3.0-or-later",
   "repository": {