@hodi-app/plugin-sdk 0.1.0 → 0.2.0

package/README.md

@@ -2,7 +2,8 @@
 
 A plugin adds to Hodi without changing its code: a server part with its own routes and tables, a web part drawn with
 Hodi's own components, settings that Hodi draws for it, and its own texts. The admin installs it from
-Réglages › Plugins with a `.hodi-plugin` file. Start from [`examples/hello-world`](../examples/hello-world).
+Réglages › Plugins with a `.hodi-plugin` file. Start from
+[`hodi-plugin-template`](https://github.com/leclaudeur/hodi-plugin-template).
 
 ## A plugin's folder
 
@@ -18,7 +19,7 @@ my-plugin/
 ## Two ways to write one
 
 **In its own repository** (the usual way): start from
-[`hodi-plugin-template`](https://github.com/Anthodpnt/hodi-plugin-template), which depends on this package,
+[`hodi-plugin-template`](https://github.com/leclaudeur/hodi-plugin-template), which depends on this package,
 `@hodi-app/plugin-sdk`:
 
 ```bash
@@ -29,7 +30,7 @@ npx hodi-plugin build                       # the current folder into dist/<id>-
 Its `tsconfig.json` lists `"@hodi-app/plugin-sdk/hodi-sdk"` in `"types"`, so `import … from 'hodi:sdk'` is typed, and the
 server part takes its types from `@hodi-app/plugin-sdk/server`.
 
-**Inside a clone of Hodi**, as `examples/hello-world` is: `tsconfig.plugins.json` maps `hodi:sdk` to its source, and
+**Inside a clone of Hodi**, as the test plugin `plugin-sdk/test/hello-world` is: `tsconfig.plugins.json` maps `hodi:sdk` to its source, and
 
 ```bash
 npm run plugin:build -- path/to/my-plugin
@@ -75,8 +76,20 @@ A package is unsigned unless a key is given: `hodi-plugin build --key private.pe
 - `routes(router, ctx)`: an Express router served at `/api/plugins/<id>/`, to the signed-in profiles the plugin is
   for, while it is on.
 
+- `onArticle(article, ctx)`: told of each article Hodi reads from its site for the first time (in the reader or in
+  the background), while the plugin is on. It must return at once; slow work goes in the background.
+
 It never imports Hodi's modules. Its context gives it what it may use: `ctx.db` (its own tables only), `ctx.settings()`,
-`ctx.fetchText` (Hodi's guarded outgoing requests), `ctx.log` and `ctx.dataDir` (a folder of its own, kept in backups).
+`ctx.fetchText` (Hodi's guarded outgoing requests), `ctx.log`, `ctx.dataDir` (a folder of its own, kept in backups) and
+`ctx.articles`:
+
+- `ctx.articles.get(id)`: an article a source listed, with its reader text when it has one (`status` `ok`,
+  `unreadable` or `failed`); `null` for an id Hodi never listed.
+- `ctx.articles.page(id)`: its page as the site serves it now, fetched again from the source's own domains; `null`
+  when it cannot be had.
+
+A JSON body sent to the plugin's routes is read for it, up to 64 KB. Anything else, such as an image, reaches the
+route unread: read the request stream yourself and set your own size limit.
 
 ## The web part
 
@@ -94,10 +107,50 @@ const Page = () => {
 definePlugin({ settingsPage: Page })
 ```
 
-`hodi:sdk` (`web/src/plugins/sdk.ts`) has Hodi's components (`Button`, `Dialog`, `SettingRow`, `Toggle`, …), its
+`definePlugin()` takes:
+
+- `settingsPage`: drawn under the plugin's options in Réglages › Plugins.
+- `page`: a page of its own, an entry of Réglages placed by the manifest's `menu` (`group`: `reading`, `subjects`, `you`,
+  `household`, `device` or `about`; `after`: the entry it follows, such as `ai`). An unknown group or entry puts it at the end of the
+  household's group. It gets `layout` (`desktop` or `phone`): draw it with `SectionPage`, as Hodi's own pages.
+- `menuIcon`: that entry's icon, drawn at 18 px (a Lucide icon the plugin bundles); a puzzle piece without one.
+- `menuHint`: the line under the entry's name, as Hodi's entries say what they hold ("12 articles signalés"); the
+  plugin's description without one.
+- `readerAction`: drawn at the end of an article beside "Lire l'original". It gets `article` (`id`, `title`, `url`,
+  `sourceId`, `sourceName`) and usually draws a `ReaderButton`, which looks like that link, with `done` once the action
+  is done for this article.
+
+`hodi:sdk` (`web/src/plugins/sdk.ts`) has Hodi's components (`Button`, `Dialog`, `FilterChip`, `SettingsCard`,
+`SettingRow`, `SourceAvatar`, `Toggle`, …), `shortAgo` to date an article as cards do, its
 confirmations and toasts, and hooks scoped to the plugin. Use Hodi's CSS variables for colours, and prefix your class
 names with the plugin's id: its styles share the page with Hodi's.
 
+### Links and screens
+
+A plugin never writes one of Hodi's addresses (`#/article/…`, `#/settings/…`): Hodi's routes may change, and a plugin
+built against them would break. It asks Hodi for them instead, and they follow Hodi:
+
+```tsx
+import { Button, navigate, usePluginLinks, usePluginPath } from 'hodi:sdk'
+
+const Page = () => {
+  const links = usePluginLinks()
+  // Its own screens live under its page: #/settings/plugin/<id>/<path>, '' at the root.
+  const path = usePluginPath()
+  return path === 'history' ? (
+    <a href={links.page()}>Back</a>
+  ) : (
+    <>
+      <a href={links.article(articleId)}>Open the article</a>
+      <Button onClick={() => navigate(links.page('history'))}>History</Button>
+    </>
+  )
+}
+```
+
+`usePluginLinks()` gives `frontPage`, `article(id)`, `settings`, `plugins` (Réglages › Plugins) and `page(path?)`, the
+plugin's own page or one of its screens. `navigate(href)` goes there from a button or after an action.
+
 Hodi's rules hold for plugins too: no AI call without a click, every text in the locales, French says « tu ».
 
 ## The package itself

package/dist/bin.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { t as buildPlugin } from "./build-Bbd9DMak.mjs";
+import { t as buildPlugin } from "./build-KyLGWV-_.mjs";
 import { readFileSync } from "node:fs";
 import path from "node:path";
 // cli.ts

package/dist/{build-Bbd9DMak.mjs → build-KyLGWV-_.mjs}

@@ -135,6 +135,7 @@ const buildPlugin = async (source, { out = path.join(source, "dist"), key } = {}
 	if (server) await build({
 		configFile: false,
 		logLevel: "warn",
+		ssr: { noExternal: true },
 		build: {
 			ssr: server,
 			outDir: stage,

package/dist/build.mjs

@@ -1 +1 @@
-export { t as buildPlugin } from "./build-Bbd9DMak.mjs";
+export { t as buildPlugin } from "./build-KyLGWV-_.mjs";

package/dist/server.d.mts

@@ -9,6 +9,28 @@ type FetchText = (url: string, options?: {
   userAgent?: string;
   headers?: Record<string, string>;
 }) => Promise<FetchedText>;
+interface PluginArticle {
+  id: string;
+  title: string;
+  url: string;
+  sourceId: string;
+  sourceName: string;
+  publishedAt: string | null;
+  status: 'ok' | 'unreadable' | 'failed';
+  text: {
+    title: string | null;
+    byline: string | null;
+    contentHtml: string;
+    textLength: number;
+  } | null;
+}
+interface PluginArticles {
+  get: (id: string) => Promise<PluginArticle | null>;
+  page: (id: string) => Promise<{
+    url: string;
+    html: string;
+  } | null>;
+}
 declare const CAPABILITIES: readonly ["profile-kind:child", "shell:child", "speech"];
 type Capability = (typeof CAPABILITIES)[number];
 declare const AUDIENCES: readonly ["admin", "all"];
@@ -59,9 +81,11 @@ interface PluginContext {
   fetchText: FetchText;
   log: (message: string) => void;
   dataDir: string;
+  articles: PluginArticles;
 }
 interface ServerPlugin {
   migrations?: readonly string[];
   routes?: (router: Router, context: PluginContext) => void;
+  onArticle?: (article: PluginArticle, context: PluginContext) => void;
 }
-export type { Manifest, PluginContext, ServerPlugin, SettingSpec, SettingValues };
+export type { Manifest, PluginArticle, PluginArticles, PluginContext, ServerPlugin, SettingSpec, SettingValues };

package/dist/web.d.mts

@@ -1,6 +1,23 @@
 import { ButtonHTMLAttributes, ComponentType, ForwardRefExoticComponent, InputHTMLAttributes, ReactNode, RefAttributes, SVGProps } from "react";
+interface ReaderArticle {
+  id: string;
+  title: string;
+  url: string;
+  sourceId: string;
+  sourceName: string;
+}
 interface WebPlugin {
+  readerAction?: ComponentType<{
+    article: ReaderArticle;
+  }>;
   settingsPage?: ComponentType;
+  page?: ComponentType<{
+    layout: 'desktop' | 'phone';
+  }>;
+  menuIcon?: ComponentType<{
+    size?: number;
+  }>;
+  menuHint?: ComponentType;
 }
 export declare const usePluginCapability: (capability: string) => boolean;
 type ButtonLook = 'neutral' | 'primary' | 'danger' | 'ai' | 'glass';
@@ -61,6 +78,16 @@ interface LucideProps extends ElementAttributes {
   nonScalingStroke?: boolean;
 }
 type LucideIcon = ForwardRefExoticComponent<Omit<LucideProps, 'ref'> & RefAttributes<SVGSVGElement>>;
+interface FilterChipProps {
+  selected: boolean;
+  onClick?: () => void;
+  href?: string;
+  count?: number;
+  icon?: LucideIcon;
+  disabled?: boolean;
+  children: ReactNode;
+}
+declare const FilterChip: ({ selected, onClick, href, count, icon: Icon, disabled, children }: FilterChipProps) => import("react").JSX.Element;
 type RoundVariant = 'default' | 'on' | 'glass' | 'image' | 'ai' | 'danger' | 'primary';
 interface RoundButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
   icon: LucideIcon;
@@ -74,6 +101,12 @@ interface RoundButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
   children?: ReactNode;
 }
 declare const RoundButton: ({ icon: Icon, label, variant, size, filled, busy, href, external, className, ...props }: RoundButtonProps) => import("react").JSX.Element;
+interface SourceAvatarProps {
+  sourceId: string;
+  sourceName: string;
+  size?: 18 | 20 | 22 | 26 | 44;
+}
+declare const SourceAvatar: ({ sourceId, sourceName, size }: SourceAvatarProps) => import("react").JSX.Element;
 interface StatusLineProps {
   tone: 'info' | 'error';
   children: string;
@@ -101,6 +134,14 @@ interface SectionPageProps {
   children: ReactNode;
 }
 declare const SectionPage: ({ title, intro, aside, layout, children }: SectionPageProps) => import("react").JSX.Element;
+interface ReaderButtonProps {
+  children: ReactNode;
+  icon?: ReactNode;
+  onClick: () => void;
+  done?: boolean;
+  label?: string;
+}
+declare const ReaderButton: ({ children, icon, onClick, done, label }: ReaderButtonProps) => import("react").JSX.Element;
 interface SettingRowProps {
   label: ReactNode;
   meta?: ReactNode;
@@ -111,6 +152,10 @@ interface SettingRowProps {
   children?: ReactNode;
 }
 declare const SettingRow: ({ label, meta, hint, lead, as: Tag, className, children }: SettingRowProps) => import("react").JSX.Element;
+declare const SettingsCard: ({ label, children }: {
+  label?: string;
+  children: ReactNode;
+}) => import("react").JSX.Element;
 interface Confirmation {
   title: string;
   message: ReactNode;
@@ -125,10 +170,21 @@ interface ToastAction {
 export declare const showDone: (message: string, undo?: () => void) => undefined;
 export declare const showSaved: (message?: string) => undefined;
 export declare const showError: (message: string, action?: ToastAction, id?: string) => undefined;
+export declare const shortAgo: (iso: string | null, now?: number) => string | null;
+interface PluginLinks {
+  frontPage: string;
+  article: (id: string) => string;
+  settings: string;
+  plugins: string;
+  page: (path?: string) => string;
+}
+export declare const usePluginLinks: () => PluginLinks;
+export declare const navigate: (href: string) => void;
+export declare const usePluginPath: () => string;
 export declare const definePlugin: (definition: WebPlugin) => void;
 export declare const usePluginTranslation: () => {
   t: (key: string, options?: Record<string, unknown>) => string;
   language: string;
 };
 export declare const usePluginApi: () => (path: string, init?: RequestInit) => Promise<Response>;
-export { Button, Chip, Dialog, DialogActions, EmptyState, RoundButton, SectionPage, SettingRow, StatusLine, TextField, Toggle };
+export { Button, Chip, Dialog, DialogActions, EmptyState, FilterChip, type PluginLinks, type ReaderArticle, ReaderButton, RoundButton, SectionPage, SettingRow, SettingsCard, SourceAvatar, StatusLine, TextField, Toggle };

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@hodi-app/plugin-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Build and type plugins for Hodi, the self-hosted news reader for a household.",
   "license": "AGPL-3.0-only",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Anthodpnt/hodi.git",
+    "url": "git+https://github.com/leclaudeur/hodi.git",
     "directory": "plugin-sdk"
   },
-  "homepage": "https://github.com/Anthodpnt/hodi/tree/main/plugin-sdk#readme",
+  "homepage": "https://github.com/leclaudeur/hodi/tree/main/plugin-sdk#readme",
   "type": "module",
   "bin": {
     "hodi-plugin": "dist/bin.mjs"