@czj-git/dsh-plugin-hub 0.1.0

package/README.md

@@ -0,0 +1,357 @@
+# DSH Plugin Hub 插件
+
+[English](README.en.md) | 中文
+
+把 [DSH Plugin Hub](https://dshpluginhub.dev) 的公开、只读搜索 API 接入 DeepSeek Harness。Agent 可以在对话中搜索已发布且通过验证的插件，查看排行榜，并取得安装命令、兼容性、社区指标和来源链接。
+
+## 能做什么
+
+- `dsh_plugin_search`：按任务、功能、插件名、仓库或作者搜索插件。
+- `dsh_plugin_rankings`：查询日增长、Star 总榜、最新上架和最近活跃榜单。
+- 支持中文和英文描述，以及分类、运行形态、安装来源、排序和分页筛选。
+- Native 模式向模型返回紧凑、便于后续操作的文本；Code Mode 返回完整结构化结果。
+- 校验公网 API 的每个返回字段，并暴露分页、数据更新时间和匿名限流信息。
+- 支持 Harness 取消信号、可配置超时、429 重试信息和稳定的错误分类。
+
+插件只调用公开的 `GET /api/v1/plugins/search`，不需要 API Key，不读取用户身份、收藏或私有数据，也不执行安装或其他写操作。安装命令只是结果数据，是否执行仍由 Harness 的 Shell、权限和审批策略控制。
+
+## 安装与启动
+
+从 npm 安装到 Web profile：
+
+```sh
+dsh plugin --profile web add @czj-git/dsh-plugin-hub
+```
+
+检查最终组合并启动：
+
+```sh
+dsh --profile web --dump-config
+dsh --profile web
+```
+
+## 配置
+
+Bundle 默认配置：
+
+```yaml
+- id: dsh-plugin-hub
+  name: '@czj-git/dsh-plugin-hub'
+  config:
+    baseUrl: https://dshpluginhub.dev
+    locale: en
+    timeoutMs: 15000
+    maxResults: 10
+```
+
+| 字段 | 类型 | 默认值 | 约束与行为 |
+|---|---|---:|---|
+| `baseUrl` | `string` | `https://dshpluginhub.dev` | API 服务地址；只接受 HTTP(S)，不能包含用户名、密码、查询参数或 URL 片段，末尾 `/` 会被移除。 |
+| `locale` | `zh \| en` | `en` | 工具调用没有传入 `locale` 时使用的描述语言。 |
+| `timeoutMs` | `integer` | `15000` | 每次 HTTP 请求的超时，范围为 1–120000 毫秒。 |
+| `maxResults` | `integer` | `10` | 工具允许的最大 `limit`，范围为 1–50；同时也是每次调用的默认 `limit`。 |
+
+后续 profile patch 覆盖配置时需要完整重述该行的全部 `config` 字段，因为 Cordis patch 替换整个配置对象而不是深度合并。
+
+## 工具输入
+
+### `dsh_plugin_search`
+
+搜索已发布且通过验证的插件。`query` 会去除首尾空白并把连续空白合并成一个空格；规范化后为空会在发出网络请求前失败。
+
+| 参数 | 必填 | 类型/可选值 | 默认值 | 说明 |
+|---|---|---|---|---|
+| `query` | 是 | `string` | — | 用户需求、功能、插件名、作者或仓库；规范化后必须非空，最长 100 个字符。 |
+| `locale` | 否 | `zh`, `en` | 配置中的 `locale` | 返回本地化描述。 |
+| `category` | 否 | 见“枚举值” | 全部分类 | 限定市场分类。 |
+| `type` | 否 | `host`, `client`, `hybrid` | 全部形态 | 限定插件运行形态。 |
+| `source` | 否 | `npm`, `github` | 全部来源 | 限定安装包来源。 |
+| `sort` | 否 | `relevance`, `growth`, `stars`, `newest`, `active` | `relevance` | 控制稳定排序；非空关键词默认按相关性排序。 |
+| `page` | 否 | `integer` | `1` | 页码，范围为 1–1000。 |
+| `limit` | 否 | `integer` | 配置中的 `maxResults` | 本页条数，范围为 1–`maxResults`，且服务端上限为 50。 |
+
+示例输入：
+
+```json
+{
+  "query": "让纯文本 Agent 看懂截图",
+  "locale": "zh",
+  "category": "multimodal-creative",
+  "type": "hybrid",
+  "source": "npm",
+  "sort": "relevance",
+  "page": 1,
+  "limit": 5
+}
+```
+
+自然语言示例：
+
+```text
+帮我找一个能让纯文本 Agent 分析截图的 DeepSeek Harness 插件，优先返回 npm 包，并给出安装命令。
+```
+
+### `dsh_plugin_rankings`
+
+使用同一个公开搜索端点的排序能力列出榜单。该工具没有关键词、`type` 或 `source` 参数。
+
+| 参数 | 必填 | 类型/可选值 | 默认值 | 说明 |
+|---|---|---|---|---|
+| `ranking` | 是 | `growth`, `stars`, `newest`, `active` | — | 选择榜单口径。 |
+| `locale` | 否 | `zh`, `en` | 配置中的 `locale` | 返回本地化描述。 |
+| `category` | 否 | 见“枚举值” | 全部分类 | 只排列指定分类。 |
+| `page` | 否 | `integer` | `1` | 页码，范围为 1–1000。 |
+| `limit` | 否 | `integer` | 配置中的 `maxResults` | 本页条数，范围为 1–`maxResults`。 |
+
+`ranking` 的含义：
+
+| 值 | 榜单 | 排序依据 |
+|---|---|---|
+| `growth` | 日增长 | 两个最近成功快照之间的 GitHub Star 变化。无上一份快照时 `starsDelta1d` 为 `null`。 |
+| `stars` | Star 总榜 | GitHub Stars 总数。 |
+| `newest` | 最新上架 | DSH Plugin Hub 首次收录时间。 |
+| `active` | 最近活跃 | GitHub 最近推送时间。 |
+
+示例输入：
+
+```json
+{
+  "ranking": "stars",
+  "locale": "zh",
+  "category": "coding-tools",
+  "page": 1,
+  "limit": 10
+}
+```
+
+## 枚举值
+
+分类 `category`：
+
+| 值 | 含义 |
+|---|---|
+| `agent-workflow` | Agent 与工作流 |
+| `coding-tools` | 编程与工具 |
+| `models-data` | 模型与数据 |
+| `ui-experience` | 界面与体验 |
+| `integrations` | 连接与集成 |
+| `security-governance` | 安全与治理 |
+| `multimodal-creative` | 多模态与创作 |
+| `observability-cost` | 监控与用量 |
+| `other` | 其他 |
+
+排序 `sort`：
+
+- `relevance`：名称、仓库和作者匹配优先，其次是简介匹配；同级结果使用 Stars 和插件 ID 保持稳定顺序。
+- `growth`、`stars`、`newest`、`active`：与排行榜工具中的同名口径一致。
+
+## 工具输出
+
+两个工具返回同一份结构化数据。Code Mode 可以读取全部字段；Native 模式使用下面的文本投影，避免把大量 JSON 填入模型上下文。
+
+### 完整字段
+
+| 路径 | 类型 | 说明 |
+|---|---|---|
+| `items` | `Plugin[]` | 当前页的插件。空结果为 `[]`，不是错误。 |
+| `items[].id` | `string` | 插件的稳定公开 ID。 |
+| `items[].slug` | `string` | `owner/repository` 形式的公开标识。 |
+| `items[].name` | `string` | 插件显示名称。 |
+| `items[].owner` | `string` | GitHub 仓库所有者。 |
+| `items[].repo` | `string` | GitHub 仓库名。 |
+| `items[].description` | `string` | 按 `locale` 返回的插件简介。 |
+| `items[].type` | `host \| client \| hybrid` | 插件运行形态。 |
+| `items[].category` | `string` | 市场分类枚举值。 |
+| `items[].topics` | `string[]` | 仓库主题标签。 |
+| `items[].language` | `string` | 仓库主要语言。 |
+| `items[].license` | `string` | 许可证标识。 |
+| `items[].package.name` | `string` | 包或安装目标名称。 |
+| `items[].package.version` | `string` | 已验证版本。 |
+| `items[].package.source` | `npm \| github` | 安装来源。 |
+| `items[].package.sourceSpec` | `string` | 固定到已验证来源/版本的安装说明符。 |
+| `items[].package.installCommand` | `string` | 可复制的 DSH 安装命令；返回命令不会自动执行。 |
+| `items[].package.profile` | `string` | 建议安装的 Harness profile。 |
+| `items[].compatibility.harnessVersion` | `string` | 验证时使用或要求的 Harness 版本。 |
+| `items[].compatibility.verificationLevel` | `static-checked \| runtime-verified` | 静态检查或运行时验证级别。 |
+| `items[].compatibility.smokeStatus` | `static-passed \| passed \| manual-step-required \| failed \| not-run` | Smoke 检查结果。 |
+| `items[].compatibility.validatedAt` | `string` | 兼容性验证时间。 |
+| `items[].metrics.stars` | `integer` | GitHub Stars。 |
+| `items[].metrics.starsDelta1d` | `integer \| null` | 最近两个成功快照之间的 Star 变化；缺少基线时为 `null`。 |
+| `items[].metrics.forks` | `integer` | GitHub Forks。 |
+| `items[].metrics.openIssues` | `integer` | GitHub Open Issues。 |
+| `items[].metrics.views` | `integer` | DSH Plugin Hub 公开浏览量。 |
+| `items[].timestamps.listedAt` | `string` | 市场首次收录时间。 |
+| `items[].timestamps.lastPushedAt` | `string` | GitHub 最近推送时间。 |
+| `items[].timestamps.sourceUpdatedAt` | `string` | 来源数据最近更新时间。 |
+| `items[].links.detail` | `string` | DSH Plugin Hub 详情页 URL。 |
+| `items[].links.repository` | `string` | GitHub 仓库 URL。 |
+| `pagination.page` | `integer` | 当前页码。 |
+| `pagination.perPage` | `integer` | 服务端返回的每页条数。 |
+| `pagination.total` | `integer` | 符合条件的插件总数。 |
+| `pagination.totalPages` | `integer` | 总页数。 |
+| `meta.apiVersion` | `v1` | 公网 API 版本。 |
+| `meta.locale` | `zh \| en` | 实际使用的描述语言。 |
+| `meta.query` | `string` | 服务端接收的规范化关键词；排行榜通常为空字符串。 |
+| `meta.sort` | `string` | 实际使用的排序。 |
+| `meta.dataUpdatedAt` | `string` | 此响应所基于的数据更新时间。 |
+| `rateLimit.limit` | `integer \| null` | 响应头中的匿名额度上限；响应头缺失或无效时为 `null`。 |
+| `rateLimit.remaining` | `integer \| null` | 响应头中的剩余额度；缺失或无效时为 `null`。 |
+| `rateLimit.reset` | `string \| null` | `RateLimit-Reset` 响应头的原始值。 |
+| `rateLimit.retryAfterSeconds` | `integer \| null` | `Retry-After` 的非负整数秒数；通常只在 429 时出现。 |
+
+### 完整结构化输出示例
+
+```json
+{
+  "items": [
+    {
+      "id": "123",
+      "slug": "owner/plugin",
+      "name": "plugin",
+      "owner": "owner",
+      "repo": "plugin",
+      "description": "一个已通过验证的 DeepSeek Harness 插件。",
+      "type": "host",
+      "category": "coding-tools",
+      "topics": ["dsh-plugin", "developer-tools"],
+      "language": "TypeScript",
+      "license": "MIT",
+      "package": {
+        "name": "dsh-plugin-example",
+        "version": "1.0.0",
+        "source": "npm",
+        "sourceSpec": "dsh-plugin-example@1.0.0",
+        "installCommand": "dsh plugin --profile web add dsh-plugin-example",
+        "profile": "web"
+      },
+      "compatibility": {
+        "harnessVersion": "0.1.0-rc.7",
+        "verificationLevel": "runtime-verified",
+        "smokeStatus": "passed",
+        "validatedAt": "2026-08-27T00:00:00.000Z"
+      },
+      "metrics": {
+        "stars": 42,
+        "starsDelta1d": 3,
+        "forks": 4,
+        "openIssues": 1,
+        "views": 20
+      },
+      "timestamps": {
+        "listedAt": "2026-08-20T00:00:00.000Z",
+        "lastPushedAt": "2026-08-26T00:00:00.000Z",
+        "sourceUpdatedAt": "2026-08-27T00:00:00.000Z"
+      },
+      "links": {
+        "detail": "https://dshpluginhub.dev/zh/plugins/owner/plugin",
+        "repository": "https://github.com/owner/plugin"
+      }
+    }
+  ],
+  "pagination": {
+    "page": 1,
+    "perPage": 5,
+    "total": 1,
+    "totalPages": 1
+  },
+  "meta": {
+    "apiVersion": "v1",
+    "locale": "zh",
+    "query": "截图分析",
+    "sort": "relevance",
+    "dataUpdatedAt": "2026-08-27T00:00:00.000Z"
+  },
+  "rateLimit": {
+    "limit": 60,
+    "remaining": 58,
+    "reset": "42",
+    "retryAfterSeconds": null
+  }
+}
+```
+
+### Native 模式文本示例
+
+```text
+Plugin search: 1 matches; showing 1 on page 1.
+1. plugin (owner/plugin)
+   一个已通过验证的 DeepSeek Harness 插件。
+   coding-tools · host · 42 stars · 1d growth +3
+   Install: dsh plugin --profile web add dsh-plugin-example
+   Details: https://dshpluginhub.dev/zh/plugins/owner/plugin
+   Repository: https://github.com/owner/plugin
+Anonymous API quota remaining: 58/60.
+```
+
+空结果会返回有效的 `items: []`。Native 模式显示：
+
+```text
+Plugin search: no published, verified plugins matched. Try a broader query or remove a filter.
+```
+
+## 错误与取消
+
+工具输入校验、网络访问、服务端错误和返回校验失败都会结束本次工具调用，不会把不完整数据伪装成成功结果。底层客户端抛出 `PluginHubApiError`，包含以下可编程字段：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `message` | `string` | 面向调用者的稳定错误说明。 |
+| `code` | `string` | 本地错误码或服务端公开错误码。 |
+| `status` | `integer \| null` | HTTP 状态码；请求未取得响应时为 `null`。 |
+| `fields` | `Record<string, string>` | 服务端返回的字段级错误；没有时为空对象。 |
+| `retryAfterSeconds` | `integer \| null` | 可重试等待秒数；只接受有效的非负整数响应头。 |
+
+本地错误码：
+
+| `code` | 触发条件 |
+|---|---|
+| `CANCELLED` | Harness 取消了正在进行的工具调用。 |
+| `TIMEOUT` | 请求超过配置中的 `timeoutMs`。 |
+| `NETWORK_ERROR` | DNS、TLS、连接或其他网络访问失败。 |
+| `INVALID_RESPONSE` | 服务返回非 JSON，或成功响应不符合完整字段定义。 |
+| `HTTP_<status>` | 非成功响应没有可识别的公开错误对象。 |
+
+服务端错误码会原样保留，例如参数不合法的 `INVALID_QUERY` 或匿名额度耗尽的 `RATE_LIMITED`。429 响应同时读取 `Retry-After`。
+
+程序化处理示例：
+
+```ts
+import { PluginHubApiError, PluginHubClient } from '@czj-git/dsh-plugin-hub/api'
+
+const client = new PluginHubClient({
+  baseUrl: 'https://dshpluginhub.dev',
+  timeoutMs: 15_000,
+})
+
+try {
+  const result = await client.search(
+    { query: 'memory', locale: 'zh', page: 1, perPage: 5 },
+    new AbortController().signal,
+  )
+  console.log(result.items)
+} catch (error) {
+  if (error instanceof PluginHubApiError) {
+    console.error(error.code, error.status, error.retryAfterSeconds)
+  }
+}
+```
+
+## 开发与验证
+
+```sh
+npm install
+npm run check
+```
+
+`npm run check` 依次运行严格类型检查、无网络单元测试和生产构建。GitHub 源安装会执行 `prepare` 生成 `dist/`；pnpm 10+ 会要求用户明确允许该构建脚本。若不希望授予安装期构建权限，请发布包含预构建 `dist/` 的 npm 包或 tarball。
+
+## 限制
+
+- 当前公开 API 只有搜索端点；排行榜工具通过同一端点的稳定排序参数实现。
+- 插件详情正文、评论、收藏和用户数据不在公开 API 中，因此本插件不读取这些内容。
+- 返回的安装命令不会自动执行，也不表示插件适用于所有 profile；调用者应检查 `package.profile` 和兼容性字段。
+- 匿名额度由服务端控制；默认策略可能调整，工具只报告当前响应中的实际限流头。
+
+## 许可证
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+- insert:
+    - id: dsh-plugin-hub
+      name: '@czj-git/dsh-plugin-hub'
+      config:
+        baseUrl: https://dshpluginhub.dev
+        locale: en
+        timeoutMs: 15000
+        maxResults: 10

package/dist/api.d.ts

@@ -0,0 +1,246 @@
+import { z } from 'zod';
+/** Locales supported by the public DSH Plugin Hub API. */
+export declare const pluginHubLocales: readonly ["zh", "en"];
+/** Public plugin categories exposed by DSH Plugin Hub. */
+export declare const pluginHubCategories: readonly ["agent-workflow", "coding-tools", "models-data", "ui-experience", "integrations", "security-governance", "multimodal-creative", "observability-cost", "other"];
+/** Plugin runtime shapes supported by the public API. */
+export declare const pluginHubTypes: readonly ["host", "client", "hybrid"];
+/** Install sources supported by the public API. */
+export declare const pluginHubSources: readonly ["npm", "github"];
+/** Ordering modes supported by the public API. */
+export declare const pluginHubSorts: readonly ["relevance", "growth", "stars", "newest", "active"];
+export type PluginHubLocale = (typeof pluginHubLocales)[number];
+export type PluginHubCategory = (typeof pluginHubCategories)[number];
+export type PluginHubType = (typeof pluginHubTypes)[number];
+export type PluginHubSource = (typeof pluginHubSources)[number];
+export type PluginHubSort = (typeof pluginHubSorts)[number];
+declare const pluginSchema: z.ZodObject<{
+    id: z.ZodString;
+    slug: z.ZodString;
+    name: z.ZodString;
+    owner: z.ZodString;
+    repo: z.ZodString;
+    description: z.ZodString;
+    type: z.ZodEnum<{
+        host: "host";
+        client: "client";
+        hybrid: "hybrid";
+    }>;
+    category: z.ZodEnum<{
+        "agent-workflow": "agent-workflow";
+        "coding-tools": "coding-tools";
+        "models-data": "models-data";
+        "ui-experience": "ui-experience";
+        integrations: "integrations";
+        "security-governance": "security-governance";
+        "multimodal-creative": "multimodal-creative";
+        "observability-cost": "observability-cost";
+        other: "other";
+    }>;
+    topics: z.ZodArray<z.ZodString>;
+    language: z.ZodString;
+    license: z.ZodString;
+    package: z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+        source: z.ZodEnum<{
+            npm: "npm";
+            github: "github";
+        }>;
+        sourceSpec: z.ZodString;
+        installCommand: z.ZodString;
+        profile: z.ZodString;
+    }, z.core.$strip>;
+    compatibility: z.ZodObject<{
+        harnessVersion: z.ZodString;
+        verificationLevel: z.ZodEnum<{
+            "static-checked": "static-checked";
+            "runtime-verified": "runtime-verified";
+        }>;
+        smokeStatus: z.ZodEnum<{
+            "static-passed": "static-passed";
+            passed: "passed";
+            "manual-step-required": "manual-step-required";
+            failed: "failed";
+            "not-run": "not-run";
+        }>;
+        validatedAt: z.ZodString;
+    }, z.core.$strip>;
+    metrics: z.ZodObject<{
+        stars: z.ZodNumber;
+        starsDelta1d: z.ZodNullable<z.ZodNumber>;
+        forks: z.ZodNumber;
+        openIssues: z.ZodNumber;
+        views: z.ZodNumber;
+    }, z.core.$strip>;
+    timestamps: z.ZodObject<{
+        listedAt: z.ZodString;
+        lastPushedAt: z.ZodString;
+        sourceUpdatedAt: z.ZodString;
+    }, z.core.$strip>;
+    links: z.ZodObject<{
+        detail: z.ZodURL;
+        repository: z.ZodURL;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+declare const responseSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        slug: z.ZodString;
+        name: z.ZodString;
+        owner: z.ZodString;
+        repo: z.ZodString;
+        description: z.ZodString;
+        type: z.ZodEnum<{
+            host: "host";
+            client: "client";
+            hybrid: "hybrid";
+        }>;
+        category: z.ZodEnum<{
+            "agent-workflow": "agent-workflow";
+            "coding-tools": "coding-tools";
+            "models-data": "models-data";
+            "ui-experience": "ui-experience";
+            integrations: "integrations";
+            "security-governance": "security-governance";
+            "multimodal-creative": "multimodal-creative";
+            "observability-cost": "observability-cost";
+            other: "other";
+        }>;
+        topics: z.ZodArray<z.ZodString>;
+        language: z.ZodString;
+        license: z.ZodString;
+        package: z.ZodObject<{
+            name: z.ZodString;
+            version: z.ZodString;
+            source: z.ZodEnum<{
+                npm: "npm";
+                github: "github";
+            }>;
+            sourceSpec: z.ZodString;
+            installCommand: z.ZodString;
+            profile: z.ZodString;
+        }, z.core.$strip>;
+        compatibility: z.ZodObject<{
+            harnessVersion: z.ZodString;
+            verificationLevel: z.ZodEnum<{
+                "static-checked": "static-checked";
+                "runtime-verified": "runtime-verified";
+            }>;
+            smokeStatus: z.ZodEnum<{
+                "static-passed": "static-passed";
+                passed: "passed";
+                "manual-step-required": "manual-step-required";
+                failed: "failed";
+                "not-run": "not-run";
+            }>;
+            validatedAt: z.ZodString;
+        }, z.core.$strip>;
+        metrics: z.ZodObject<{
+            stars: z.ZodNumber;
+            starsDelta1d: z.ZodNullable<z.ZodNumber>;
+            forks: z.ZodNumber;
+            openIssues: z.ZodNumber;
+            views: z.ZodNumber;
+        }, z.core.$strip>;
+        timestamps: z.ZodObject<{
+            listedAt: z.ZodString;
+            lastPushedAt: z.ZodString;
+            sourceUpdatedAt: z.ZodString;
+        }, z.core.$strip>;
+        links: z.ZodObject<{
+            detail: z.ZodURL;
+            repository: z.ZodURL;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    pagination: z.ZodObject<{
+        page: z.ZodNumber;
+        perPage: z.ZodNumber;
+        total: z.ZodNumber;
+        totalPages: z.ZodNumber;
+    }, z.core.$strip>;
+    meta: z.ZodObject<{
+        apiVersion: z.ZodLiteral<"v1">;
+        locale: z.ZodEnum<{
+            zh: "zh";
+            en: "en";
+        }>;
+        query: z.ZodString;
+        sort: z.ZodEnum<{
+            relevance: "relevance";
+            growth: "growth";
+            stars: "stars";
+            newest: "newest";
+            active: "active";
+        }>;
+        dataUpdatedAt: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type PluginHubPlugin = z.infer<typeof pluginSchema>;
+export interface PluginHubRateLimit {
+    limit: number | null;
+    remaining: number | null;
+    reset: string | null;
+    retryAfterSeconds: number | null;
+}
+export interface PluginHubSearchResult extends z.infer<typeof responseSchema> {
+    rateLimit: PluginHubRateLimit;
+}
+export interface PluginHubSearchInput {
+    query?: string;
+    locale?: PluginHubLocale;
+    category?: PluginHubCategory;
+    type?: PluginHubType;
+    source?: PluginHubSource;
+    sort?: PluginHubSort;
+    page?: number;
+    perPage?: number;
+}
+export interface PluginHubClientOptions {
+    baseUrl: string;
+    timeoutMs: number;
+    fetch?: typeof globalThis.fetch;
+}
+/** An HTTP or response-validation failure returned by DSH Plugin Hub. */
+export declare class PluginHubApiError extends Error {
+    readonly code: string;
+    readonly status: number | null;
+    readonly fields: Readonly<Record<string, string>>;
+    readonly retryAfterSeconds: number | null;
+    /**
+     * Create one stable public-API failure.
+     * @param message - Human-readable failure.
+     * @param options - Structured HTTP and API diagnostics.
+     */
+    constructor(message: string, options: {
+        code: string;
+        status?: number;
+        fields?: Record<string, string>;
+        retryAfterSeconds?: number | null;
+        cause?: unknown;
+    });
+}
+/**
+ * Validate and canonicalize the configured service origin.
+ * @param raw - User-configured base URL.
+ * @returns An HTTP(S) origin without a trailing slash.
+ */
+export declare function normalizePluginHubBaseUrl(raw: string): string;
+/** Read-only client for the versioned DSH Plugin Hub search endpoint. */
+export declare class PluginHubClient {
+    #private;
+    /**
+     * Create a client with one deployment's network policy.
+     * @param options - Service origin, request timeout, and optional test transport.
+     */
+    constructor(options: PluginHubClientOptions);
+    /**
+     * Search published, verified plugins.
+     * @param input - Public search filters and page controls.
+     * @param signal - Caller-owned cancellation signal.
+     * @returns Validated API data plus anonymous quota headers.
+     */
+    search(input: PluginHubSearchInput, signal: AbortSignal): Promise<PluginHubSearchResult>;
+}
+export {};
+//# sourceMappingURL=api.d.ts.map