wiki-starlight-api 1.0.0

package/README.md

@@ -0,0 +1,177 @@
+# Wikipedia API
+
+**Package:** `wikipedia-api`  
+**Author:** Dominex Macedon  
+**License:** MIT  
+
+A **lightweight, zero-dependency Wikipedia API client** for Node.js and Starlight.  
+Designed for **searching, reading, and exploring Wikipedia content** using clean async APIs.
+
+
+---
+
+##  Features
+
+-  Search Wikipedia articles
+-  Fetch article summaries
+-  Retrieve full plain-text pages
+-  Get a random article
+-  List available language translations
+-  Extract image titles
+-  Get article categories
+-  Search + summary combined helper
+-  No dependencies
+
+---
+
+##  Installation
+
+```bash
+npm install wikipedia-api
+````
+
+---
+
+##  Usage
+
+### Importing
+
+```js
+import {
+  search,
+  summary,
+  page,
+  random,
+  languages,
+  images,
+  categories,
+  searchAndSummary
+} from "wikipedia-api";
+```
+
+---
+
+## 🔍 Search Articles
+
+```js
+const results = await search("Starlight programming language", 5);
+
+console.log(results);
+```
+
+**Output**
+
+```js
+[
+  {
+    title: "Starlight",
+    snippet: "Starlight is ...",
+    pageid: 123456
+  }
+]
+```
+
+---
+
+##  Article Summary
+
+```js
+const info = await summary("JavaScript");
+console.log(info.extract);
+```
+
+---
+
+##  Full Page Content
+
+```js
+const article = await page("Node.js");
+console.log(article.content);
+```
+
+---
+
+##  Random Article
+
+```js
+const randomArticle = await random();
+console.log(randomArticle.title);
+```
+
+---
+
+##  Available Languages
+
+```js
+const langs = await languages("JavaScript");
+console.log(langs);
+```
+
+**Output**
+
+```js
+[
+  { lang: "es", title: "JavaScript" },
+  { lang: "fr", title: "JavaScript" }
+]
+```
+
+---
+
+##  Images Used in Article
+
+```js
+const imgs = await images("Node.js");
+console.log(imgs);
+```
+
+**Note:** Returns image titles only (file names).
+
+---
+
+##  Categories
+
+```js
+const cats = await categories("Node.js");
+console.log(cats);
+```
+
+---
+
+##  Search + Summary (Combined Helper)
+
+```js
+const summaries = await searchAndSummary("Programming language", 3);
+console.log(summaries);
+```
+
+---
+
+##  Design Philosophy
+
+*  Minimal and readable
+*  Uses official Wikipedia APIs
+*  Async / await friendly
+*  Works with Starlight and Node.js
+*  No external libraries
+
+---
+
+##  Notes
+
+* This package retrieves **public Wikipedia data only**
+* Intended for **CLI tools, scripts, bots, and learning projects**
+* Subject to Wikipedia API usage limits
+
+---
+
+##  Resources
+
+* Wikipedia API Docs: [https://www.mediawiki.org/wiki/API:Main_page](https://www.mediawiki.org/wiki/API:Main_page)
+* REST API Docs: [https://en.wikipedia.org/api/rest_v1/](https://en.wikipedia.org/api/rest_v1/)
+
+---
+
+##  License
+
+MIT © Dominex Macedon

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "wiki-starlight-api",
+  "version": "1.0.0",
+  "description": "Lightweight zero-dependency Wikipedia API client for Node.js",
+  "type": "module",
+  "main": "wiki-starlight-api.mjs",
+  "exports": {
+    ".": "./wiki-starlight-api.mjs"
+  },
+  "author": "Dominex Macedon",
+  "license": "MIT",
+  "keywords": [
+    "wikipedia",
+    "api",
+    "search",
+    "wiki",
+    "node",
+    "starlight"
+  ]
+}

package/wiki-starlight-api.mjs

@@ -0,0 +1,178 @@
+/**
+ * Internal helper for API requests
+ */
+async function request(params) {
+  const url = new URL(BASE_URL);
+  params.format = "json";
+  params.origin = "*";
+
+  for (const key in params) {
+    url.searchParams.set(key, params[key]);
+  }
+
+  const res = await fetch(url.toString());
+  if (!res.ok) {
+    throw new Error(`Wikipedia API error: ${res.status}`);
+  }
+
+  return res.json();
+}
+
+/**
+ * Search Wikipedia articles
+ * @param {string} query
+ * @param {number} limit
+ */
+export async function search(query, limit = 5) {
+  const data = await request({
+    action: "query",
+    list: "search",
+    srsearch: query,
+    srlimit: limit
+  });
+
+  return data.query.search.map(item => ({
+    title: item.title,
+    snippet: item.snippet.replace(/<\/?[^>]+>/g, ""),
+    pageid: item.pageid
+  }));
+}
+
+/**
+ * Get article summary (intro)
+ * @param {string} title
+ */
+export async function summary(title) {
+  const url = `https://en.wikipedia.org/api/rest_v1/page/summary/${encodeURIComponent(title)}`;
+  const res = await fetch(url);
+
+  if (!res.ok) {
+    throw new Error(`Failed to fetch summary for "${title}"`);
+  }
+
+  const data = await res.json();
+
+  return {
+    title: data.title,
+    description: data.description,
+    extract: data.extract,
+    url: data.content_urls?.desktop?.page
+  };
+}
+
+/**
+ * Get full page content (plain text)
+ * @param {string} title
+ */
+export async function page(title) {
+  const data = await request({
+    action: "query",
+    prop: "extracts",
+    explaintext: true,
+    redirects: true,
+    titles: title
+  });
+
+  const pages = data.query.pages;
+  const p = pages[Object.keys(pages)[0]];
+
+  return {
+    title: p.title,
+    content: p.extract
+  };
+}
+
+/**
+ * Get a random Wikipedia article
+ */
+export async function random() {
+  const data = await request({
+    action: "query",
+    list: "random",
+    rnnamespace: 0,
+    rnlimit: 1
+  });
+
+  const title = data.query.random[0].title;
+  return summary(title);
+}
+
+/**
+ * Get available language translations for an article
+ * @param {string} title
+ */
+export async function languages(title) {
+  const data = await request({
+    action: "query",
+    prop: "langlinks",
+    titles: title,
+    lllimit: "max"
+  });
+
+  const pages = data.query.pages;
+  const p = pages[Object.keys(pages)[0]];
+
+  return (p.langlinks || []).map(lang => ({
+    lang: lang.lang,
+    title: lang["*"]
+  }));
+}
+
+/**
+ * Get image URLs used in an article
+ * @param {string} title
+ */
+export async function images(title) {
+  const data = await request({
+    action: "query",
+    prop: "images",
+    titles: title,
+    imlimit: "max"
+  });
+
+  const pages = data.query.pages;
+  const p = pages[Object.keys(pages)[0]];
+
+  return (p.images || [])
+    .map(img => img.title)
+    .filter(name => /\.(png|jpg|jpeg|svg|gif)$/i.test(name));
+}
+
+/**
+ * Get categories of an article
+ * @param {string} title
+ */
+export async function categories(title) {
+  const data = await request({
+    action: "query",
+    prop: "categories",
+    titles: title,
+    cllimit: "max"
+  });
+
+  const pages = data.query.pages;
+  const p = pages[Object.keys(pages)[0]];
+
+  return (p.categories || []).map(cat =>
+    cat.title.replace("Category:", "")
+  );
+}
+
+/**
+ * Search and return summaries for results
+ * @param {string} query
+ * @param {number} limit
+ */
+export async function searchAndSummary(query, limit = 3) {
+  const results = await search(query, limit);
+
+  const summaries = [];
+  for (const r of results) {
+    try {
+      summaries.push(await summary(r.title));
+    } catch {
+    }
+  }
+
+  return summaries;
+}