@hotstack/catalogue-client 0.1.0

package/README.md

@@ -0,0 +1,79 @@
+# @hotstack/catalogue-client
+
+A thin, typed, dependency-free client for the [HotStack Catalogue](https://github.com/hotstacklabs/hotstack-mcp-catalog)
+read API — search MCP servers and plugins, fetch full entries, and read the
+curated registry projection. Global `fetch` only; no runtime dependencies.
+
+This is the **read/discovery** SDK. It never asserts that a listed server is
+safe (the catalogue records provenance, not endorsements), and it has no auth
+or tool-execution surface — that is a separate product.
+
+## Install
+
+```sh
+npm install @hotstack/catalogue-client
+```
+
+Node ≥ 20, or any runtime with a global `fetch` (pass `fetch` explicitly for
+older ones).
+
+## Quickstart
+
+```ts
+import { CatalogueClient } from '@hotstack/catalogue-client';
+
+const client = new CatalogueClient({ baseUrl: 'https://api.hotstack.dev' });
+
+// Search (filters + sort mirror GET /v1/search).
+const page = await client.search({ q: 'gmail', category: 'communication', sort: 'newest', limit: 10 });
+console.log(page.total, page.results[0]?.id);
+
+// Walk every match without hand-rolling pagination.
+for await (const hit of client.searchAll({ category: 'data' })) {
+  console.log(hit.id, hit.tier);
+}
+
+// Fetch one entry (its inline `mcp` config is on `entry`, ready to paste).
+const detail = await client.entry('stripe/stripe-mcp');
+console.log(detail.entry);
+```
+
+## Honesty semantics
+
+The catalogue never fabricates data to look healthy, and neither does this
+client:
+
+- **Degraded vs empty.** When no source has ever ingested successfully the API
+  returns `503`; the client throws `CatalogueUnavailableError` (never an empty
+  result). A legitimate zero-hit search is a normal `SearchPage` with
+  `total: 0`.
+- **Stale data.** `client.registry()` surfaces the `stale` flag
+  (`x-hotstack-stale`) so you can tell current data from last-good data.
+- **ETag round-trip.** Pass the `etag` from a prior `registry()` call to
+  revalidate; an unchanged index returns `{ status: 'not_modified' }`.
+
+```ts
+import { CatalogueUnavailableError, EntryNotFoundError } from '@hotstack/catalogue-client';
+
+try {
+  await client.entry('nope/missing');
+} catch (error) {
+  if (error instanceof EntryNotFoundError) { /* 404 */ }
+  if (error instanceof CatalogueUnavailableError) { /* index down, not empty */ }
+}
+```
+
+## API
+
+- `new CatalogueClient({ baseUrl, fetch?, userAgent? })`
+- `search(params): Promise<SearchPage>` — `GET /v1/search`
+- `searchAll(params): AsyncIterableIterator<SearchHit>` — pages until done
+- `entry(id): Promise<EntryDetail>` — `GET /v1/entries/:id` (404 → `EntryNotFoundError`)
+- `registry({ etag? }): Promise<RegistryResult>` — `GET /v1/registry`
+- `sources(): Promise<SourceStatus[]>` — `GET /v1/sources`
+
+The full parameter and response reference is [`docs/api.md`](https://github.com/hotstacklabs/hotstack-mcp-catalog/blob/main/docs/api.md).
+
+## License
+
+MIT.

package/dist/client.d.ts

@@ -0,0 +1,32 @@
+import type { EntryDetail, RegistryResult, SearchHit, SearchPage, SearchParams, SourceStatus } from './types.js';
+export interface CatalogueClientOptions {
+    /** Catalogue service origin, e.g. "https://api.hotstack.dev". Trailing slashes are trimmed. */
+    baseUrl: string;
+    /** Fetch implementation; defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+    /** Optional User-Agent sent with every request (ignored by browsers). */
+    userAgent?: string;
+}
+export declare class CatalogueClient {
+    #private;
+    constructor(options: CatalogueClientOptions);
+    /** GET /v1/search. Throws CatalogueUnavailableError on the degraded 503. */
+    search(params?: SearchParams): Promise<SearchPage>;
+    /**
+     * Walk every page of a search, yielding each hit once. Pages at the server's
+     * max limit and stops on `hasMore: false`. Honors an explicit `offset` start.
+     */
+    searchAll(params?: SearchParams): AsyncIterableIterator<SearchHit>;
+    /** GET /v1/entries/:id. Throws EntryNotFoundError on 404, CatalogueUnavailableError on 503. */
+    entry(id: string): Promise<EntryDetail>;
+    /**
+     * GET /v1/registry. Pass `etag` from a prior call for a conditional request:
+     * an unchanged index returns `{status: 'not_modified'}`. Surfaces the strong
+     * ETag and the honest `stale` flag; throws CatalogueUnavailableError on 503.
+     */
+    registry(opts?: {
+        etag?: string;
+    }): Promise<RegistryResult>;
+    /** GET /v1/sources — per-source ingest status. Always 200 when the service is up. */
+    sources(): Promise<SourceStatus[]>;
+}

package/dist/client.js

@@ -0,0 +1,145 @@
+// The catalogue read client: a thin, typed wrapper over the three stable read
+// endpoints plus /v1/sources. Zero runtime dependencies — global `fetch` only
+// (inject one for older runtimes or tests). Read/discovery only: this SDK never
+// grows auth or tool-execution features (that is a separate product).
+import { CatalogueApiError, CatalogueUnavailableError, EntryNotFoundError } from './errors.js';
+/**
+ * The server's `limit` clamp (parseSearchParams, MAX_LIMIT in
+ * src/api/search.ts). searchAll pages at this size so it never over-requests.
+ */
+const MAX_LIMIT = 100;
+function buildSearchQuery(params) {
+    const query = new URLSearchParams();
+    if (params.q !== undefined)
+        query.set('q', params.q);
+    if (params.category !== undefined)
+        query.set('category', params.category);
+    if (params.kind !== undefined)
+        query.set('kind', params.kind);
+    if (params.tier !== undefined)
+        query.set('tier', params.tier);
+    if (params.publisher !== undefined)
+        query.set('publisher', params.publisher);
+    if (params.sort !== undefined)
+        query.set('sort', params.sort);
+    if (params.limit !== undefined)
+        query.set('limit', String(params.limit));
+    if (params.offset !== undefined)
+        query.set('offset', String(params.offset));
+    const encoded = query.toString();
+    return encoded.length > 0 ? `?${encoded}` : '';
+}
+async function readBody(response) {
+    const text = await response.text();
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+export class CatalogueClient {
+    #baseUrl;
+    #fetch;
+    #userAgent;
+    constructor(options) {
+        if (typeof options.baseUrl !== 'string' || options.baseUrl.length === 0) {
+            throw new TypeError('CatalogueClient requires a non-empty baseUrl');
+        }
+        this.#baseUrl = options.baseUrl.replace(/\/+$/, '');
+        const fetchImpl = options.fetch ?? globalThis.fetch;
+        if (typeof fetchImpl !== 'function') {
+            throw new TypeError('global fetch is unavailable in this runtime; pass options.fetch');
+        }
+        this.#fetch = fetchImpl;
+        this.#userAgent = options.userAgent;
+    }
+    async #request(path, init) {
+        const headers = new Headers(init?.headers);
+        headers.set('accept', 'application/json');
+        if (this.#userAgent !== undefined)
+            headers.set('user-agent', this.#userAgent);
+        // Call through a local so `fetch` keeps its own `this` (native fetch is not
+        // bound to the client instance).
+        const doFetch = this.#fetch;
+        return doFetch(`${this.#baseUrl}${path}`, { ...init, headers });
+    }
+    /** GET /v1/search. Throws CatalogueUnavailableError on the degraded 503. */
+    async search(params = {}) {
+        const path = `/v1/search${buildSearchQuery(params)}`;
+        const response = await this.#request(path);
+        if (response.status === 503)
+            throw new CatalogueUnavailableError({ status: 503, url: this.#baseUrl + path, body: await readBody(response) });
+        if (!response.ok) {
+            throw new CatalogueApiError(`search failed with ${response.status}`, { status: response.status, url: this.#baseUrl + path, body: await readBody(response) });
+        }
+        return (await response.json());
+    }
+    /**
+     * Walk every page of a search, yielding each hit once. Pages at the server's
+     * max limit and stops on `hasMore: false`. Honors an explicit `offset` start.
+     */
+    async *searchAll(params = {}) {
+        const pageSize = Math.min(params.limit ?? MAX_LIMIT, MAX_LIMIT);
+        let offset = params.offset ?? 0;
+        for (;;) {
+            const page = await this.search({ ...params, limit: pageSize, offset });
+            for (const hit of page.results)
+                yield hit;
+            if (!page.hasMore || page.results.length === 0)
+                break;
+            offset += page.results.length;
+        }
+    }
+    /** GET /v1/entries/:id. Throws EntryNotFoundError on 404, CatalogueUnavailableError on 503. */
+    async entry(id) {
+        // Ids are publisher-namespaced ("publisher/name"); the literal "/" stays in
+        // the path, each segment percent-encoded.
+        const path = `/v1/entries/${id.split('/').map(encodeURIComponent).join('/')}`;
+        const response = await this.#request(path);
+        if (response.status === 404)
+            throw new EntryNotFoundError(id, { status: 404, url: this.#baseUrl + path, body: await readBody(response) });
+        if (response.status === 503)
+            throw new CatalogueUnavailableError({ status: 503, url: this.#baseUrl + path, body: await readBody(response) });
+        if (!response.ok) {
+            throw new CatalogueApiError(`entry lookup failed with ${response.status}`, { status: response.status, url: this.#baseUrl + path, body: await readBody(response) });
+        }
+        return (await response.json());
+    }
+    /**
+     * GET /v1/registry. Pass `etag` from a prior call for a conditional request:
+     * an unchanged index returns `{status: 'not_modified'}`. Surfaces the strong
+     * ETag and the honest `stale` flag; throws CatalogueUnavailableError on 503.
+     */
+    async registry(opts = {}) {
+        const path = '/v1/registry';
+        const headers = new Headers();
+        if (opts.etag !== undefined)
+            headers.set('if-none-match', opts.etag);
+        const response = await this.#request(path, { headers });
+        if (response.status === 304)
+            return { status: 'not_modified' };
+        if (response.status === 503)
+            throw new CatalogueUnavailableError({ status: 503, url: this.#baseUrl + path, body: await readBody(response) });
+        if (!response.ok) {
+            throw new CatalogueApiError(`registry fetch failed with ${response.status}`, { status: response.status, url: this.#baseUrl + path, body: await readBody(response) });
+        }
+        const index = (await response.json());
+        return {
+            status: 'ok',
+            index,
+            etag: response.headers.get('etag') ?? '',
+            stale: response.headers.get('x-hotstack-stale') === 'true',
+        };
+    }
+    /** GET /v1/sources — per-source ingest status. Always 200 when the service is up. */
+    async sources() {
+        const path = '/v1/sources';
+        const response = await this.#request(path);
+        if (!response.ok) {
+            throw new CatalogueApiError(`sources fetch failed with ${response.status}`, { status: response.status, url: this.#baseUrl + path, body: await readBody(response) });
+        }
+        const body = (await response.json());
+        return body.sources;
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,23 @@
+export interface CatalogueApiErrorInit {
+    status: number;
+    url: string;
+    /** Parsed JSON body when available, else the raw text. */
+    body: unknown;
+}
+export declare class CatalogueApiError extends Error {
+    readonly status: number;
+    readonly url: string;
+    readonly body: unknown;
+    constructor(message: string, init: CatalogueApiErrorInit);
+}
+/** GET /v1/entries/:id → 404: the id is not in the index. */
+export declare class EntryNotFoundError extends CatalogueApiError {
+    constructor(id: string, init: CatalogueApiErrorInit);
+}
+/**
+ * The API's explicit 503 degraded response — no configured source has ever
+ * ingested successfully. Distinct from a 200 empty/zero-hit result.
+ */
+export declare class CatalogueUnavailableError extends CatalogueApiError {
+    constructor(init: CatalogueApiErrorInit);
+}

package/dist/errors.js

@@ -0,0 +1,32 @@
+// One error hierarchy over the catalogue API. The degraded (503) signal is
+// never swallowed: it becomes CatalogueUnavailableError, distinct from a
+// legitimate empty result, so a consumer can tell "down" from "empty".
+export class CatalogueApiError extends Error {
+    status;
+    url;
+    body;
+    constructor(message, init) {
+        super(message);
+        this.name = 'CatalogueApiError';
+        this.status = init.status;
+        this.url = init.url;
+        this.body = init.body;
+    }
+}
+/** GET /v1/entries/:id → 404: the id is not in the index. */
+export class EntryNotFoundError extends CatalogueApiError {
+    constructor(id, init) {
+        super(`no catalogue entry with id "${id}"`, init);
+        this.name = 'EntryNotFoundError';
+    }
+}
+/**
+ * The API's explicit 503 degraded response — no configured source has ever
+ * ingested successfully. Distinct from a 200 empty/zero-hit result.
+ */
+export class CatalogueUnavailableError extends CatalogueApiError {
+    constructor(init) {
+        super('catalogue unavailable: no source has been ingested successfully yet', init);
+        this.name = 'CatalogueUnavailableError';
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { CatalogueClient, type CatalogueClientOptions } from './client.js';
+export { CatalogueApiError, CatalogueUnavailableError, EntryNotFoundError, type CatalogueApiErrorInit } from './errors.js';
+export type { ComponentKind, EntryDetail, HotstackCategory, MarketplaceIndex, RegistryResult, SearchHit, SearchPage, SearchParams, SortOrder, SourceStatus, SourceTier, } from './types.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+// @hotstack/catalogue-client — typed, dependency-free read client for the
+// HotStack Catalogue API. See README.md for a quickstart.
+export { CatalogueClient } from './client.js';
+export { CatalogueApiError, CatalogueUnavailableError, EntryNotFoundError } from './errors.js';

package/dist/types.d.ts

@@ -0,0 +1,102 @@
+export type SourceTier = 'curated' | 'community' | 'indexed';
+export type ComponentKind = 'mcp' | 'skills' | 'module' | 'cli';
+export type HotstackCategory = 'code' | 'communication' | 'data' | 'design' | 'development' | 'productivity' | 'sales-marketing';
+export type SortOrder = 'relevance' | 'newest' | 'name';
+/** GET /v1/search query parameters. All optional. */
+export interface SearchParams {
+    q?: string;
+    category?: HotstackCategory;
+    kind?: ComponentKind;
+    tier?: SourceTier;
+    publisher?: string;
+    sort?: SortOrder;
+    /** Page size, 1–100 (server default 20). */
+    limit?: number;
+    /** Page start, ≥ 0 (server default 0). */
+    offset?: number;
+}
+export interface SearchHit {
+    id: string;
+    /** Entry kind: `inline-mcp` | `bundle` | `plugin`. Kept as string; new kinds must not break clients. */
+    kind: string;
+    tier: SourceTier;
+    /** Blended ordering value in [0, 1). */
+    rank: number;
+    /** Ingest-time ranking score. */
+    score: number;
+    provenance: {
+        sourceId: string;
+        ingestedAt: string;
+    };
+    /** The full native entry (including any inline `mcp` config). Shape varies by kind. */
+    entry: unknown;
+}
+export interface SearchPage {
+    total: number;
+    limit: number;
+    offset: number;
+    hasMore: boolean;
+    results: SearchHit[];
+}
+export interface EntryDetail {
+    id: string;
+    kind: string;
+    tier: SourceTier;
+    provenance: {
+        sourceId: string;
+        ingestedAt: string;
+        /** Present only when the id collided across sources. */
+        collision?: Record<string, unknown>;
+    };
+    ranking: {
+        score: number;
+        signals: Record<string, unknown>;
+    };
+    entry: unknown;
+}
+/** The GET /v1/registry compat projection (byte-compatible MarketplaceIndex). */
+export interface MarketplaceIndex {
+    schemaVersion: number;
+    plugins: unknown[];
+}
+export interface SourceStatus {
+    id: string;
+    tier: SourceTier;
+    adapter: string;
+    state: 'ok' | 'degraded' | 'never_ingested';
+    denylisted: boolean;
+    lastAttemptAt: string | null;
+    lastSuccessAt: string | null;
+    lastError: string | null;
+    lastErrorAt: string | null;
+    entryCount: number;
+    issues: Array<{
+        path: string;
+        message: string;
+    }>;
+    collisions: Array<{
+        entryId: string;
+        role: string;
+        winnerSourceId?: string;
+        sourceIds: string[];
+    }>;
+    removals: Array<{
+        entryId: string;
+        reason: string;
+        detail: string;
+        removedAt: string;
+    }>;
+}
+/**
+ * GET /v1/registry outcome. `not_modified` surfaces a real 304 from an ETag
+ * round-trip; `ok` carries the strong `etag` and the honest `stale` flag
+ * (`x-hotstack-stale`) so a consumer can tell current from last-good data.
+ */
+export type RegistryResult = {
+    status: 'ok';
+    index: MarketplaceIndex;
+    etag: string;
+    stale: boolean;
+} | {
+    status: 'not_modified';
+};

package/dist/types.js

@@ -0,0 +1,5 @@
+// Types hand-authored from docs/api.md (the API reference is the contract),
+// named to match the service's exported shapes but deliberately NOT imported
+// from service code — the package stands alone. The live contract test keeps
+// them honest against the real /v1 responses.
+export {};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@hotstack/catalogue-client",
+  "version": "0.1.0",
+  "description": "Typed, dependency-free fetch client for the HotStack Catalogue read API (search, entries, registry).",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "keywords": [
+    "hotstack",
+    "mcp",
+    "catalogue",
+    "model-context-protocol",
+    "sdk"
+  ]
+}