feat(plugin): add openlibrary read commands

README.md

@@ -275,6 +275,7 @@ Use plugins for private company workflows, community adapters, or experiments th
 
 | Plugin | Description | Author |
 | --- | --- | --- |
+| [`openlibrary`](./plugins/openlibrary/) | Anonymous Open Library catalog commands for Webcmd | [WebCMD Agent](https://github.com/agentrhq) |
 | [`skyscanner`](./plugins/skyscanner/) | Skyscanner flight search commands for Webcmd | [Rishabh](https://github.com/rishabhraj36) |
 <!-- webcmd-community-plugins:end -->
 

plugins/openlibrary/README.md

@@ -0,0 +1,15 @@
+# Open Library Webcmd plugin
+
+Anonymous, read-only access to Open Library's public catalog APIs.
+
+## Commands
+
+```sh
+webcmd openlibrary search "the lord of the rings" --limit 5
+webcmd openlibrary subject science_fiction --limit 5
+webcmd openlibrary work OL45883W
+```
+
+- `search` searches by title, author, ISBN, or keywords.
+- `subject` browses works under an Open Library subject slug and supports `--offset` pagination.
+- `work` returns the catalog record for an Open Library work ID.

plugins/openlibrary/common.js

@@ -0,0 +1,65 @@
+import { ArgumentError, CommandExecutionError } from '@agentrhq/webcmd/errors';
+
+export const HOST = 'openlibrary.org';
+export const BASE_URL = `https://${HOST}`;
+export const MAX_LIMIT = 100;
+
+export function requiredText(raw, label) {
+  const value = String(raw ?? '').trim();
+  if (!value) throw new ArgumentError(`${label} is required`);
+  return value;
+}
+
+export function parseLimit(raw, fallback = 20) {
+  if (raw === undefined || raw === null || raw === '') return fallback;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 1 || value > MAX_LIMIT) {
+    throw new ArgumentError(`--limit must be an integer between 1 and ${MAX_LIMIT}`);
+  }
+  return value;
+}
+
+export function parseOffset(raw) {
+  if (raw === undefined || raw === null || raw === '') return 0;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 0 || value > 10000) {
+    throw new ArgumentError('--offset must be an integer between 0 and 10000');
+  }
+  return value;
+}
+
+export function workIdFromKey(key) {
+  return String(key ?? '').replace(/^\/works\//, '');
+}
+
+export function workUrl(key) {
+  const id = workIdFromKey(key);
+  return id ? `${BASE_URL}/works/${encodeURIComponent(id)}` : null;
+}
+
+export function coverUrl(coverId, size = 'M') {
+  return Number.isInteger(coverId) ? `https://covers.openlibrary.org/b/id/${coverId}-${size}.jpg` : null;
+}
+
+export async function getJson(url, command) {
+  let response;
+  try {
+    response = await fetch(url, {
+      headers: { Accept: 'application/json', 'User-Agent': 'Webcmd Open Library plugin' },
+    });
+  } catch (error) {
+    throw new CommandExecutionError(`${command} request failed: ${error.message}`);
+  }
+  if (!response.ok) {
+    throw new CommandExecutionError(`${command} request failed: HTTP ${response.status}`);
+  }
+  const contentType = response.headers.get('content-type') || '';
+  if (!contentType.includes('json')) {
+    throw new CommandExecutionError(`${command} returned an unexpected non-JSON response`);
+  }
+  try {
+    return await response.json();
+  } catch {
+    throw new CommandExecutionError(`${command} returned invalid JSON`);
+  }
+}

plugins/openlibrary/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "webcmd-plugin-openlibrary",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Anonymous Open Library catalog commands for Webcmd",
+  "peerDependencies": {
+    "@agentrhq/webcmd": ">=0.2.0"
+  }
+}

plugins/openlibrary/search.js

@@ -0,0 +1,40 @@
+import { EmptyResultError, CommandExecutionError } from '@agentrhq/webcmd/errors';
+import { cli, Strategy } from '@agentrhq/webcmd/registry';
+import { BASE_URL, HOST, coverUrl, getJson, parseLimit, requiredText, workUrl } from './common.js';
+
+cli({
+  site: 'openlibrary',
+  name: 'search',
+  access: 'read',
+  description: 'Search Open Library books by title, author, ISBN, or keywords',
+  domain: HOST,
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [
+    { name: 'query', positional: true, required: true, help: 'Book title, author, ISBN, or keywords' },
+    { name: 'limit', type: 'int', default: 20, help: 'Maximum results to return (1-100)' },
+  ],
+  columns: ['title', 'workId', 'url', 'authors', 'firstPublishYear', 'editionCount', 'coverUrl'],
+  func: async (args) => {
+    const query = requiredText(args.query, 'query');
+    const limit = parseLimit(args.limit);
+    const url = new URL('/search.json', BASE_URL);
+    url.searchParams.set('q', query);
+    url.searchParams.set('limit', String(limit));
+    url.searchParams.set('fields', 'key,title,author_name,first_publish_year,edition_count,cover_i');
+    const data = await getJson(url, 'Open Library search');
+    if (!Array.isArray(data?.docs)) {
+      throw new CommandExecutionError('Open Library search returned an unexpected response shape');
+    }
+    if (!data.docs.length) throw new EmptyResultError('openlibrary search', `No books matched ${JSON.stringify(query)}`);
+    return data.docs.map((book) => ({
+      title: String(book.title ?? ''),
+      workId: String(book.key ?? '').replace(/^\/works\//, ''),
+      url: workUrl(book.key),
+      authors: Array.isArray(book.author_name) ? book.author_name.join(', ') : null,
+      firstPublishYear: Number.isInteger(book.first_publish_year) ? book.first_publish_year : null,
+      editionCount: Number.isInteger(book.edition_count) ? book.edition_count : null,
+      coverUrl: coverUrl(book.cover_i),
+    }));
+  },
+});

plugins/openlibrary/subject.js

@@ -0,0 +1,41 @@
+import { EmptyResultError, CommandExecutionError } from '@agentrhq/webcmd/errors';
+import { cli, Strategy } from '@agentrhq/webcmd/registry';
+import { BASE_URL, HOST, coverUrl, getJson, parseLimit, parseOffset, requiredText, workUrl } from './common.js';
+
+cli({
+  site: 'openlibrary',
+  name: 'subject',
+  access: 'read',
+  description: 'Browse Open Library works in a subject',
+  domain: HOST,
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [
+    { name: 'subject', positional: true, required: true, help: 'Subject slug, for example science_fiction' },
+    { name: 'limit', type: 'int', default: 20, help: 'Maximum works to return (1-100)' },
+    { name: 'offset', type: 'int', default: 0, help: 'Number of works to skip (0-10000)' },
+  ],
+  columns: ['title', 'workId', 'url', 'authors', 'firstPublishYear', 'editionCount', 'coverUrl'],
+  func: async (args) => {
+    const subject = requiredText(args.subject, 'subject').toLowerCase().replace(/\s+/g, '_');
+    const limit = parseLimit(args.limit);
+    const offset = parseOffset(args.offset);
+    const url = new URL(`/subjects/${encodeURIComponent(subject)}.json`, BASE_URL);
+    url.searchParams.set('limit', String(limit));
+    url.searchParams.set('offset', String(offset));
+    const data = await getJson(url, 'Open Library subject browse');
+    if (!Array.isArray(data?.works)) {
+      throw new CommandExecutionError('Open Library subject browse returned an unexpected response shape');
+    }
+    if (!data.works.length) throw new EmptyResultError('openlibrary subject', `No works found for subject ${JSON.stringify(subject)}`);
+    return data.works.map((work) => ({
+      title: String(work.title ?? ''),
+      workId: String(work.key ?? '').replace(/^\/works\//, ''),
+      url: workUrl(work.key),
+      authors: Array.isArray(work.authors) ? work.authors.map((author) => author?.name).filter(Boolean).join(', ') || null : null,
+      firstPublishYear: Number.isInteger(work.first_publish_year) ? work.first_publish_year : null,
+      editionCount: Number.isInteger(work.edition_count) ? work.edition_count : null,
+      coverUrl: coverUrl(work.cover_id),
+    }));
+  },
+});

plugins/openlibrary/webcmd-plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "openlibrary",
+  "version": "0.1.0",
+  "description": "Anonymous Open Library catalog commands for Webcmd",
+  "webcmd": ">=0.2.0",
+  "author": {
+    "name": "WebCMD Agent",
+    "handle": "agentrhq"
+  }
+}

plugins/openlibrary/work.js

@@ -0,0 +1,47 @@
+import { ArgumentError, CommandExecutionError } from '@agentrhq/webcmd/errors';
+import { cli, Strategy } from '@agentrhq/webcmd/registry';
+import { BASE_URL, HOST, coverUrl, getJson, requiredText, workUrl } from './common.js';
+
+function normalizeWorkId(raw) {
+  const value = requiredText(raw, 'work-id').replace(/^https?:\/\/openlibrary\.org\/works\//i, '').replace(/^\/works\//, '').replace(/\/$/, '');
+  if (!/^OL\d+W$/i.test(value)) throw new ArgumentError('work-id must look like OL45883W');
+  return value.toUpperCase();
+}
+
+function descriptionText(value) {
+  if (typeof value === 'string') return value.trim() || null;
+  if (value && typeof value.value === 'string') return value.value.trim() || null;
+  return null;
+}
+
+cli({
+  site: 'openlibrary',
+  name: 'work',
+  access: 'read',
+  description: 'Get details for one Open Library work',
+  domain: HOST,
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [{ name: 'work-id', positional: true, required: true, help: 'Open Library work ID, for example OL45883W' }],
+  columns: ['title', 'workId', 'url', 'description', 'firstPublishDate', 'subjects', 'authorKeys', 'coverUrl'],
+  func: async (args) => {
+    const workId = normalizeWorkId(args['work-id']);
+    const data = await getJson(new URL(`/works/${encodeURIComponent(workId)}.json`, BASE_URL), 'Open Library work lookup');
+    if (!data || typeof data !== 'object' || Array.isArray(data) || !data.title) {
+      throw new CommandExecutionError('Open Library work lookup returned an unexpected response shape');
+    }
+    const authorKeys = Array.isArray(data.authors)
+      ? data.authors.map((entry) => entry?.author?.key).filter(Boolean).map((key) => key.replace(/^\/authors\//, ''))
+      : [];
+    return [{
+      title: String(data.title),
+      workId,
+      url: workUrl(workId),
+      description: descriptionText(data.description),
+      firstPublishDate: typeof data.first_publish_date === 'string' ? data.first_publish_date : null,
+      subjects: Array.isArray(data.subjects) ? data.subjects.join(', ') : null,
+      authorKeys: authorKeys.length ? authorKeys.join(', ') : null,
+      coverUrl: coverUrl(Array.isArray(data.covers) ? data.covers.find(Number.isInteger) : null, 'L'),
+    }];
+  },
+});

webcmd-plugin.json

@@ -4,6 +4,16 @@
   "description": "Webcmd plugin collection",
   "webcmd": ">=0.2.0",
   "plugins": {
+    "openlibrary": {
+      "path": "plugins/openlibrary",
+      "version": "0.1.0",
+      "description": "Anonymous Open Library catalog commands for Webcmd",
+      "webcmd": ">=0.2.0",
+      "author": {
+        "name": "WebCMD Agent",
+        "handle": "agentrhq"
+      }
+    },
     "skyscanner": {
       "path": "plugins/skyscanner",
       "version": "0.1.0",