@deepseek-ai/dsh-web-deepseek-api 0.0.0-stage → 0.2.1-rc.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 DeepSeek
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,49 @@
1
+ # Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
2
+ # section, a hash of its English and Chinese blocks outside code blocks and generated regions.
3
+ # After editing either side, bring the other along and re-record with:
4
+ # pnpm run verify-translation-pairing --write packages/web/web-deepseek-api/README.md
5
+ /:
6
+ en: eb52169ad8cf3b38
7
+ zh: 3ad61fa2317079cf
8
+ /deepseek-ai-dsh-web-deepseek-api:
9
+ en: a56113c9530cb046
10
+ zh: bb07334e63fd9204
11
+ /deepseek-ai-dsh-web-deepseek-api/summary:
12
+ en: 49ea0208c97514dc
13
+ zh: 5ad4698f3588ebdb
14
+ /deepseek-ai-dsh-web-deepseek-api/table-of-contents:
15
+ en: 76368b6b1da79c80
16
+ zh: 1e8f931a56b7d34d
17
+ /deepseek-ai-dsh-web-deepseek-api/use-this-package:
18
+ en: 408a1ef777a98309
19
+ zh: 30c6b52c20de3b67
20
+ /deepseek-ai-dsh-web-deepseek-api/use-this-package/authentication:
21
+ en: 491f4c93c0d02152
22
+ zh: 4888cd52667bdc39
23
+ /deepseek-ai-dsh-web-deepseek-api/use-this-package/results-and-failures:
24
+ en: b8bfad1c79b2f05a
25
+ zh: b8d89fabbc028ac1
26
+ /deepseek-ai-dsh-web-deepseek-api/understand-the-implementation:
27
+ en: 0372c46bac133870
28
+ zh: 0c803f4fb04a7ee4
29
+ /deepseek-ai-dsh-web-deepseek-api/model-experience:
30
+ en: 215e7ba838619b7b
31
+ zh: a311da3843709f90
32
+ /deepseek-ai-dsh-web-deepseek-api/model-experience/conversation-tool-results:
33
+ en: dfd3b61aff4a8aa8
34
+ zh: 06e2b6cc71f461e2
35
+ /deepseek-ai-dsh-web-deepseek-api/model-experience/conversation-tool-results/what-the-model-sees:
36
+ en: a9fbb78ffe886f0b
37
+ zh: 813dc7ee283018d2
38
+ /deepseek-ai-dsh-web-deepseek-api/model-experience/conversation-tool-results/token-effect:
39
+ en: d82cd03f38fb4b38
40
+ zh: 7049a13d2373a7b9
41
+ /deepseek-ai-dsh-web-deepseek-api/model-experience/conversation-tool-results/kv-cache-effect:
42
+ en: 54ed534b58469807
43
+ zh: c3f8f178abb86ccb
44
+ /deepseek-ai-dsh-web-deepseek-api/known-limitations-and-deferred-work:
45
+ en: d4877c8f4e158a5d
46
+ zh: 45177b6d6c3ecc40
47
+ /deepseek-ai-dsh-web-deepseek-api/known-limitations-and-deferred-work/dev-note:
48
+ en: 0a1253c6f7b5e8b9
49
+ zh: 9f56528562c7c914
package/README.md CHANGED
@@ -1,3 +1,106 @@
1
- # Temporary Holding Version
1
+ ---
2
+ description: "DeepSeek Search and Fetch API providers, their shared authentication and transport, endpoint configuration, and normalized results."
3
+ kind: "package-reference"
4
+ ---
2
5
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
6
+ # @deepseek-ai/dsh-web-deepseek-api
7
+
8
+ English | [中文](README.zh.md)
9
+
10
+ ## Summary
11
+
12
+ Search and fetch the web through the DeepSeek Search and Fetch APIs: one direct request per operation, without an auxiliary model request. The plugin registers `deepseek-search-api` and `deepseek-fetch-api`, which share one credential and one API base, and authenticates with an API key or the configured account integration. Search returns titles, URLs, available snippets, and available publication dates; Fetch returns page Markdown. Messages search stays in [dsh-web-search-deepseek](../web-search-deepseek/README.md); the model-facing tools live in `dsh-tool-web`.
13
+
14
+ ## Table of Contents
15
+
16
+ - [Use this package](#use-this-package)
17
+ - [Understand the implementation](#understand-the-implementation)
18
+ - [Model Experience](#model-experience)
19
+ - [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
20
+ - [Dev Note](#dev-note)
21
+
22
+ -----
23
+
24
+ <a id="use-this-package"></a>
25
+ ## Use this package
26
+
27
+ Mount the plugin alongside `dsh-web` and select its providers. Shipped profiles mount it while selecting Messages search and local HTTP fetch. Turning on **Use the new Web Search API** in **Plugins > Built-in plugin settings > Web search** and saving selects both providers of this package; turning it off restores the shipped selection. A saved selection applies to the next operation.
28
+
29
+ ```yaml
30
+ - name: '@deepseek-ai/dsh-web'
31
+ config:
32
+ searchProvider: deepseek-search-api
33
+ fetchProvider: deepseek-fetch-api
34
+ - name: '@deepseek-ai/dsh-web-deepseek-api'
35
+ config:
36
+ apiKeyEnv: DEEPSEEK_API_KEY
37
+ ```
38
+
39
+ | Field | Default | Meaning |
40
+ |---|---|---|
41
+ | `apiKey` | omitted | Literal API key; prefer a credential reference |
42
+ | `apiKeyEnv` | `DEEPSEEK_API_KEY` | Credential reference resolved for each operation |
43
+ | `baseURL` | `https://api.deepseek.com/v1/tools` | Search and Fetch API base including its deployment path prefix; append `/search` or `/fetch` |
44
+ | `count` | `10` | Search API results per search, an integer from 1 to 50; a smaller `maxResults` on the request wins |
45
+ | `sendOriginalQuestion` | `true` | Send the triggering human prompt, cut to 128 characters, as the Search API's `ori_question` |
46
+
47
+ Fill `baseURL` with the complete API base, including its path prefix and excluding the operation name. The default reaches `https://api.deepseek.com/v1/tools/search` and `https://api.deepseek.com/v1/tools/fetch`; a deployment with another prefix, such as `/api/v1/tools`, needs its complete base.
48
+
49
+ Run the real API tests with `DEEPSEEK_API_KEY` and `DEEPSEEK_SEARCH_API_TEST_BASE_URL`; both are required, and the latter includes the API path prefix.
50
+
51
+ ### Authentication
52
+
53
+ A Session using the `deepseek-account` route asks the account service for a token authorized for the resolved endpoint and sends it as `x-dsh-auth-token`; the public Search and Fetch routes accepted it on 2026-10-16. Otherwise a non-empty literal `apiKey` wins over `apiKeyEnv`; the reference resolves through `ctx.credentials`, or the launch environment when that service is absent. API keys use `Authorization: Bearer`. Credential resolution and endpoint selection share one settings snapshot.
54
+
55
+ ### Results and failures
56
+
57
+ The Search API receives `query`, `count` (the configured count, or the request's smaller `maxResults`), `need_content: false`, and, unless `sendOriginalQuestion` is off, `ori_question`: the text of the initiating Session's latest human prompt with whitespace collapsed and cut to 128 characters. A search outside a Session or without such a prompt omits it. The provider maps `results[].snippet` directly and maps nullable `date` to optional `publishedAt`. An empty results array is successful. Fetch sends `url` and returns the original Markdown as a text body with HTTP status 200, because the API answers with an error status when the target yields no usable content. Its URL is the requested URL: the API reports no final redirected URL.
58
+
59
+ A blank or unparseable `baseURL` makes both providers unavailable, and a `count` outside 1 to 50 makes Search unavailable. Missing credentials fail with `WEB_PROVIDER_CREDENTIAL_MISSING`; cancellation uses `WEB_ABORTED`; transport, HTTP, and malformed response failures use `WEB_PROVIDER_ERROR`. Redirects are rejected before contacting their target. Non-success Fetch API statuses are retrieval failures, not target-page statuses. Account-authenticated HTTP 401 responses provide sign-in guidance; other dispatch failures identify the endpoint and the `baseURL` settings field. No automatic retry or provider fallback occurs.
60
+
61
+ -----
62
+
63
+ <a id="understand-the-implementation"></a>
64
+ ## Understand the implementation
65
+
66
+ <details>
67
+ <summary>Implementation internals — click to expand</summary>
68
+
69
+ The [plugin](src/index.ts) reads its settings once per operation and registers both providers. The [Search provider](src/search.ts) validates response JSON before returning service results; the [Fetch provider](src/fetch.ts) validates the Markdown body. The [transport](src/transport.ts) owns credential resolution, cancellation, redirect rejection, and failure guidance; a recording hook runs before dispatch and prevents it by throwing. Search and Fetch API calls emit no auxiliary request event. Tool calls and results retain their normal Session logging.
70
+
71
+ See the [web subsystem](../../../docs/subsystems/web.md) for service types and [tool-web](../tool-web/README.md) for bounded model output.
72
+
73
+ </details>
74
+
75
+ -----
76
+
77
+ <a id="model-experience"></a>
78
+ ## Model Experience
79
+
80
+ ### Conversation tool results
81
+
82
+ #### What the model sees
83
+
84
+ The `web_search` and `web_fetch` tools render sources or Markdown with an external-content notice. Fetch results carry the requested URL and HTTP 200. Errors retain actionable credential or endpoint guidance. Search sends the query, with the triggering question, directly to the Search API.
85
+
86
+ #### Token effect
87
+
88
+ No auxiliary model tokens are consumed. Conversation result tokens scale with returned snippets or Markdown and are bounded by the consumer. API retrieval billing is independent of model tokens.
89
+
90
+ #### KV Cache effect
91
+
92
+ Tool results append after the existing conversation prefix. Provider registration adds no model context.
93
+
94
+ ## Known Limitations and Deferred Work
95
+
96
+ <a id="known-limitations-and-deferred-work"></a>
97
+
98
+ - The shared search request does not expose `localization`; the provider requests snippets only and does not consume `summary`, `site_name`, `site_icon`, or full search content. Returned summaries measured 1,000–2,300 characters on 2026-10-16.
99
+ - In 2026-10-16 probes, different `ori_question` values left result order, scores, and summaries unchanged; the provider still sends it because the guide documents it as an intent signal.
100
+ - API query and URL constraints are enforced by the remote service. An unresolvable Fetch target returned HTTP 500 rather than the documented 404 on 2026-10-16, and its failure carries the same endpoint guidance as an endpoint failure. Fetch exposes neither the target status nor the final redirect URL, so results report HTTP 200 and the requested URL; the provider discards the API's page title.
101
+ - Availability checks cannot query asynchronous credential stores. A configured resolver can still fail with a missing-credential error when called.
102
+
103
+ <a id="dev-note"></a>
104
+ ### Dev Note
105
+
106
+ None.
package/README.zh.md ADDED
@@ -0,0 +1,106 @@
1
+ ---
2
+ description: "DeepSeek Search 与 Fetch API 提供者、共享的鉴权与传输层、端点配置及标准化结果。"
3
+ kind: "package-reference"
4
+ ---
5
+
6
+ # @deepseek-ai/dsh-web-deepseek-api
7
+
8
+ [English](README.md) | 中文
9
+
10
+ ## 概述
11
+
12
+ 通过 DeepSeek Search 与 Fetch API 搜索和抓取网页:每次操作只发起一次直接请求,无需辅助模型请求。插件注册 `deepseek-search-api` 和 `deepseek-fetch-api`,两者共用一份凭据和一个 API 基础地址,并使用 API key(API 密钥)或已配置的账号集成鉴权。Search 返回标题、URL、可用的摘要和可用的发布时间;Fetch 返回页面 Markdown。Messages 搜索仍由 [dsh-web-search-deepseek](../web-search-deepseek/README.zh.md) 提供;面向模型的工具由 `dsh-tool-web` 提供。
13
+
14
+ ## 目录
15
+
16
+ - [使用此包](#use-this-package)
17
+ - [理解实现](#understand-the-implementation)
18
+ - [模型体验](#model-experience)
19
+ - [已知限制与待办工作](#known-limitations-and-deferred-work)
20
+ - [开发备注](#dev-note)
21
+
22
+ -----
23
+
24
+ <a id="use-this-package"></a>
25
+ ## 使用此包
26
+
27
+ 将插件与 `dsh-web` 一起挂载,并选择它的提供者。内置配置挂载此插件,同时选择 Messages 搜索和本地 HTTP 抓取。在**插件 > 内置插件配置 > 网页搜索**中开启**启用新版 Web 搜索 API**并保存,会同时选择此包的两个提供者;关闭后恢复内置选择。保存的选择从下一次操作开始生效。
28
+
29
+ ```yaml
30
+ - name: '@deepseek-ai/dsh-web'
31
+ config:
32
+ searchProvider: deepseek-search-api
33
+ fetchProvider: deepseek-fetch-api
34
+ - name: '@deepseek-ai/dsh-web-deepseek-api'
35
+ config:
36
+ apiKeyEnv: DEEPSEEK_API_KEY
37
+ ```
38
+
39
+ | 字段 | 默认值 | 含义 |
40
+ |---|---|---|
41
+ | `apiKey` | 省略 | 字面 API 密钥;建议使用凭据引用 |
42
+ | `apiKeyEnv` | `DEEPSEEK_API_KEY` | 每次操作解析的凭据引用 |
43
+ | `baseURL` | `https://api.deepseek.com/v1/tools` | 包含部署路径前缀的 Search 与 Fetch API 基础地址;追加 `/search` 或 `/fetch` |
44
+ | `count` | `10` | Search API 每次搜索的结果数,为 1 至 50 的整数;请求中更小的 `maxResults` 优先 |
45
+ | `sendOriginalQuestion` | `true` | 将触发搜索的用户提示截取至 128 个字符,作为 Search API 的 `ori_question` 发送 |
46
+
47
+ `baseURL` 填写完整的 API 基础地址,包含路径前缀,但不包含操作名。默认值请求 `https://api.deepseek.com/v1/tools/search` 和 `https://api.deepseek.com/v1/tools/fetch`;使用其他前缀(例如 `/api/v1/tools`)的部署需要填写其完整基础地址。
48
+
49
+ 真实 API 测试要求同时设置 `DEEPSEEK_API_KEY` 和 `DEEPSEEK_SEARCH_API_TEST_BASE_URL`,后者包含 API 路径前缀。
50
+
51
+ ### 鉴权
52
+
53
+ 使用 `deepseek-account` 路由的会话向账号服务请求已授权用于解析后端点的令牌,并通过 `x-dsh-auth-token` 发送;2026-10-16 公网 Search 与 Fetch 路由已接受该令牌。其他情况下,非空的字面 `apiKey` 优先于 `apiKeyEnv`;凭据引用通过 `ctx.credentials` 解析,该服务缺省时使用启动环境。API 密钥使用 `Authorization: Bearer`。凭据解析和端点选择使用同一份设置快照。
54
+
55
+ ### 结果与失败
56
+
57
+ Search API 接收 `query`、`count`(配置的结果数,或请求中更小的 `maxResults`)、`need_content: false`,以及在 `sendOriginalQuestion` 未关闭时的 `ori_question`:发起会话中最近一条用户提示的文本,空白折叠后截取至 128 个字符。在会话之外或没有此类提示的搜索不发送该字段。提供者直接映射 `results[].snippet`,并将可为 null 的 `date` 映射为可选的 `publishedAt`。空结果数组表示成功。Fetch 发送 `url`,以文本正文返回原始 Markdown,并报告 HTTP 状态 200,因为目标没有可用内容时 API 会返回错误状态。返回 URL 为请求 URL:API 不报告重定向后的最终 URL。
58
+
59
+ `baseURL` 为空白或无法解析时,两个提供者都不可用;`count` 不在 1 至 50 之间时,Search 不可用。凭据缺失以 `WEB_PROVIDER_CREDENTIAL_MISSING` 失败;取消使用 `WEB_ABORTED`;传输、HTTP 和响应格式错误使用 `WEB_PROVIDER_ERROR`。重定向在联系目标前即被拒绝。Fetch API 的非成功状态表示抓取失败,不代表目标页面的状态。账号鉴权的 HTTP 401 响应提供重新登录指引;其他请求失败指出端点及 `baseURL` 设置字段。不会自动重试或回退至其他提供者。
60
+
61
+ -----
62
+
63
+ <a id="understand-the-implementation"></a>
64
+ ## 理解实现
65
+
66
+ <details>
67
+ <summary>实现细节 — 点击展开</summary>
68
+
69
+ [插件](src/index.ts)在每次操作时读取一次设置,并注册两个提供者。[Search 提供者](src/search.ts)在返回服务结果前校验响应 JSON;[Fetch 提供者](src/fetch.ts)校验 Markdown 正文。[传输层](src/transport.ts)负责凭据解析、取消、重定向拒绝和失败指引;记录钩子在发送前运行,抛出异常即阻止发送。Search 与 Fetch API 调用不产生辅助请求事件。工具调用和结果仍按常规记录到会话。
70
+
71
+ 服务类型见 [Web 子系统](../../../docs/subsystems/web.zh.md),受限的模型输出见 [tool-web](../tool-web/README.zh.md)。
72
+
73
+ </details>
74
+
75
+ -----
76
+
77
+ <a id="model-experience"></a>
78
+ ## 模型体验
79
+
80
+ ### 会话工具结果
81
+
82
+ #### 模型看到什么
83
+
84
+ `web_search` 和 `web_fetch` 工具在外部内容提示下呈现搜索来源或 Markdown。Fetch 结果包含请求 URL 和 HTTP 200。错误保留可操作的凭据或端点指引。Search 将查询连同触发问题直接发送给 Search API。
85
+
86
+ #### Token 影响
87
+
88
+ 不消耗辅助模型 token。会话结果 token 随返回的摘要或 Markdown 增长,并受消费方限制。API 抓取计费独立于模型 token。
89
+
90
+ #### KV Cache 影响
91
+
92
+ 工具结果追加在已有会话前缀之后。提供者注册不增加模型上下文。
93
+
94
+ ## 已知限制与待办工作
95
+
96
+ <a id="known-limitations-and-deferred-work"></a>
97
+
98
+ - 共享搜索请求不暴露 `localization`;提供者仅请求摘要,不消费 `summary`、`site_name`、`site_icon` 或搜索全文。2026-10-16 实测返回的 `summary` 长度为 1,000–2,300 个字符。
99
+ - 2026-10-16 的探测中,不同的 `ori_question` 未改变结果顺序、评分或摘要;由于指南将其列为意图信号,提供者仍会发送。
100
+ - 查询和 URL 约束由远端服务执行。2026-10-16 抓取无法解析的目标域名时返回 HTTP 500,而非文档所述的 404,其失败信息与端点失败附带相同的端点指引。Fetch 既不暴露目标状态,也不暴露最终重定向 URL,因此结果报告 HTTP 200 和请求 URL;提供者丢弃 API 返回的页面标题。
101
+ - 可用性检查无法查询异步凭据存储。已配置的解析器在调用时仍可能因凭据缺失失败。
102
+
103
+ <a id="dev-note"></a>
104
+ ### 开发备注
105
+
106
+ 无。
package/lib/index.js ADDED
@@ -0,0 +1,392 @@
1
+ import z from "@deepseek-ai/schemastery";
2
+ import { credentialRef } from "@deepseek-ai/dsh-credentials";
3
+ import { launchEnvironmentOf } from "@deepseek-ai/dsh-launch-environment";
4
+ import { WebError } from "@deepseek-ai/dsh-web";
5
+ //#region lib/types/transport.js
6
+ const ACCOUNT_PROVIDER = "deepseek-account";
7
+ const USER_AGENT = "deepseek-harness/0.0.1";
8
+ /**
9
+ * Resolve credential sources for one operation without retaining secret values.
10
+ * @param ctx - Provider context with request routing and credential services.
11
+ * @param config - Literal key and credential reference from the settings snapshot.
12
+ * @returns Authentication sources for one operation.
13
+ */
14
+ function deepSeekWebAuth(ctx, config) {
15
+ const apiKeyEnv = credentialRef(config.apiKeyEnv);
16
+ const literalApiKey = config.apiKey !== void 0 && config.apiKey.length > 0 ? config.apiKey : void 0;
17
+ return {
18
+ ...literalApiKey === void 0 ? {} : { apiKey: literalApiKey },
19
+ resolveAccountToken: async (endpoint) => {
20
+ if (ctx.get("agents")?.currentInitiator()?.session.requestContext()?.provider !== ACCOUNT_PROVIDER) return void 0;
21
+ return await ctx.get("deepseekAccount")?.resolveToken(endpoint);
22
+ },
23
+ resolveApiKey: async () => {
24
+ const credentials = ctx.get("credentials");
25
+ if (credentials !== void 0) return (await credentials.resolve(apiKeyEnv))?.value;
26
+ const ambient = launchEnvironmentOf(ctx).get(apiKeyEnv);
27
+ return ambient !== void 0 && ambient.value.length > 0 ? ambient.value : void 0;
28
+ },
29
+ apiKeyEnv
30
+ };
31
+ }
32
+ /**
33
+ * Check whether an authentication source exists; does not resolve credentials.
34
+ * @param auth - Sources for the operation.
35
+ * @returns Whether a literal key or resolver is present.
36
+ */
37
+ function hasDeepSeekWebCredential(auth) {
38
+ return (auth.apiKey?.length ?? 0) > 0 || auth.resolveApiKey !== void 0 || auth.resolveAccountToken !== void 0;
39
+ }
40
+ /** Narrow a remote JSON object.
41
+ * @param value - Untrusted JSON.
42
+ * @returns Whether readable object fields exist.
43
+ */
44
+ function isRecord(value) {
45
+ return typeof value === "object" && value !== null && !Array.isArray(value);
46
+ }
47
+ /** Report malformed upstream JSON without embedding response content.
48
+ * @returns The stable provider error.
49
+ */
50
+ function invalidResponse() {
51
+ return new WebError("DeepSeek returned an invalid response body", "WEB_PROVIDER_ERROR");
52
+ }
53
+ /** Dispatch one operation using a single settings and credential snapshot.
54
+ * @param options - Authentication sources for this operation.
55
+ * @param request - Resolved endpoint, JSON payload, and response decoder.
56
+ * @param signal - Caller cancellation signal.
57
+ * @returns The validated provider result.
58
+ */
59
+ async function dispatchDeepSeekWeb(options, request, signal) {
60
+ const { endpoint, body, decode, recordRequest, guidance } = request;
61
+ const auth = await authHeaders(options, request, signal);
62
+ throwIfSearchAborted(signal);
63
+ recordRequest?.(endpoint);
64
+ throwIfSearchAborted(signal);
65
+ let response;
66
+ try {
67
+ response = await fetch(endpoint, {
68
+ method: "POST",
69
+ redirect: "error",
70
+ headers: {
71
+ ...auth.headers,
72
+ ...request.headers,
73
+ "content-type": "application/json",
74
+ "accept": "application/json",
75
+ "user-agent": USER_AGENT
76
+ },
77
+ body: JSON.stringify(body),
78
+ ...signal !== void 0 ? { signal } : {}
79
+ });
80
+ } catch (error) {
81
+ if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
82
+ throw searchEndpointError(guidance, endpoint, `DeepSeek web request failed: ${String(error)}`, error);
83
+ }
84
+ if (!response.ok) {
85
+ const status = response.status;
86
+ let message = `DeepSeek API error (HTTP ${status})`;
87
+ try {
88
+ const parsed = await response.json();
89
+ if (isRecord(parsed)) {
90
+ const detail = typeof parsed.error === "string" ? parsed.error : isRecord(parsed.error) ? parsed.error.message : parsed.message;
91
+ if (typeof detail === "string" && detail.length > 0) message += `: ${detail}`;
92
+ }
93
+ } catch (error) {
94
+ if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
95
+ }
96
+ if (status === 401 && auth.kind === "account") throw accountRejectedError(message);
97
+ throw searchEndpointError(guidance, endpoint, message);
98
+ }
99
+ try {
100
+ const payload = await response.json();
101
+ throwIfSearchAborted(signal);
102
+ return decode(payload);
103
+ } catch (error) {
104
+ if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
105
+ throw searchEndpointError(guidance, endpoint, error instanceof WebError ? error.message : `DeepSeek returned an unprocessable response body: ${String(error)}`, error);
106
+ }
107
+ }
108
+ /** Replace endpoint guidance with sign-in guidance when DeepSeek rejects the account token. */
109
+ function accountRejectedError(message) {
110
+ return new WebError(`${message}\n\nDeepSeek rejected the account sign-in used for this web request. Guide the user to sign in to DeepSeek again; the endpoint does not need changing.`, "WEB_PROVIDER_ERROR");
111
+ }
112
+ /**
113
+ * Add endpoint recovery instructions to failures that occur after request dispatch begins.
114
+ * @param options - the plugin, settings field, and settings page the guidance names.
115
+ * @param endpoint - the dispatched endpoint.
116
+ * @param message - the failure description.
117
+ * @param cause - the underlying failure, when one exists.
118
+ * @returns the provider failure with recovery instructions.
119
+ */
120
+ function searchEndpointError(options, endpoint, message, cause) {
121
+ return new WebError(`${message}\n\nThe web request used endpoint ${JSON.stringify(endpoint)}. ${options.subject} endpoint configuration is separate from chat. If that endpoint is not intended, guide the user to Plugins > Built-in plugin settings > ${options.page}, where they can change and save ${options.label}. If that settings page is unavailable, the user can set ${options.plugin}.${options.field} to a trusted DeepSeek endpoint. Only the user should choose or change the endpoint.`, "WEB_PROVIDER_ERROR", cause === void 0 ? void 0 : { cause });
122
+ }
123
+ /**
124
+ * Resolve one operation's authentication headers without retaining a credential on the provider.
125
+ * @param options - the caller's snapshot, so the credential and the endpoint it is sent to come from one section.
126
+ * @param request - the resolved request; its endpoint scopes the account token.
127
+ * @param signal - abort signal for the surrounding operation.
128
+ * @returns the account-token header when one resolves, otherwise the API-key headers, tagged by credential kind.
129
+ */
130
+ async function authHeaders(options, request, signal) {
131
+ const { resolveAccountToken } = options;
132
+ const token = resolveAccountToken === void 0 ? void 0 : await resolveCredential(() => resolveAccountToken(request.endpoint), signal);
133
+ if (token !== void 0 && token.length > 0) return {
134
+ kind: "account",
135
+ headers: { "x-dsh-auth-token": token }
136
+ };
137
+ const apiKey = await resolveApiKey(options, request.guidance.plugin, signal);
138
+ return {
139
+ kind: "api-key",
140
+ headers: {
141
+ ...request.apiKeyHeaders?.(apiKey),
142
+ "authorization": `Bearer ${apiKey}`
143
+ }
144
+ };
145
+ }
146
+ /**
147
+ * Resolve one operation's API key without retaining it on the provider.
148
+ * @param options - the caller's snapshot, so the key and the endpoint it is sent to come from one section.
149
+ * @param plugin - configuration namespace named by the missing-key diagnostic.
150
+ * @param signal - abort signal for the surrounding operation.
151
+ * @returns the resolved key.
152
+ */
153
+ async function resolveApiKey(options, plugin, signal) {
154
+ throwIfSearchAborted(signal);
155
+ if (options.apiKey !== void 0 && options.apiKey.length > 0) return options.apiKey;
156
+ const { resolveApiKey } = options;
157
+ const resolved = resolveApiKey === void 0 ? void 0 : await resolveCredential(resolveApiKey, signal);
158
+ if (resolved !== void 0 && resolved.length > 0) return resolved;
159
+ throw new WebError(`DeepSeek web access has no API key for "${options.apiKeyEnv ?? "DEEPSEEK_API_KEY"}"; store it through the credentials service (the web Models page writes it), export it in the launching environment, or set a literal "apiKey" in the ${plugin} config; a conversation using a DeepSeek Account model searches with the account sign-in instead`, "WEB_PROVIDER_CREDENTIAL_MISSING");
160
+ }
161
+ /**
162
+ * Run one credential resolver under the search's cancellation signal. An
163
+ * already-cancelled search never starts the resolver.
164
+ * @param resolve - the resolver; a synchronous throw is mapped like a rejection.
165
+ * @param signal - abort signal for the surrounding search.
166
+ * @returns the resolved credential, or undefined when the resolver supplied none.
167
+ * @throws {@link WebError} `WEB_ABORTED` on cancellation, `WEB_PROVIDER_ERROR` when the resolver fails.
168
+ */
169
+ async function resolveCredential(resolve, signal) {
170
+ throwIfSearchAborted(signal);
171
+ try {
172
+ return await abortable(resolve(), signal);
173
+ } catch (error) {
174
+ if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
175
+ throw new WebError(`DeepSeek web credential resolution failed: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
176
+ }
177
+ }
178
+ /**
179
+ * Race a same-process asynchronous preflight against caller cancellation. The
180
+ * attached settlement handlers keep observing an uncooperative operation after
181
+ * abort so a later rejection cannot become unhandled.
182
+ */
183
+ function abortable(operation, signal) {
184
+ if (signal === void 0) return operation;
185
+ if (signal.aborted) return Promise.reject(searchAborted(signal));
186
+ return new Promise((resolve, reject) => {
187
+ const onAbort = () => {
188
+ reject(searchAborted(signal));
189
+ };
190
+ signal.addEventListener("abort", onAbort, { once: true });
191
+ operation.then((value) => {
192
+ signal.removeEventListener("abort", onAbort);
193
+ resolve(value);
194
+ }, (error) => {
195
+ signal.removeEventListener("abort", onAbort);
196
+ reject(new Error(String(error).replace(/^Error: /u, ""), { cause: error }));
197
+ });
198
+ });
199
+ }
200
+ /** Throw the provider's stable cancellation error when the caller already aborted. */
201
+ function throwIfSearchAborted(signal) {
202
+ if (signal?.aborted === true) throw searchAborted(signal);
203
+ }
204
+ /** Build the provider's stable cancellation error while retaining the caller's reason. */
205
+ function searchAborted(signal, fallback) {
206
+ return new WebError("DeepSeek web request aborted", "WEB_ABORTED", { cause: signal?.aborted === true ? signal.reason : fallback });
207
+ }
208
+ /** True for a fetch/`AbortSignal` abort, surfaced as `WEB_ABORTED`. */
209
+ function isAbortError(error) {
210
+ return error instanceof DOMException && error.name === "AbortError";
211
+ }
212
+ //#endregion
213
+ //#region lib/types/search.js
214
+ /** Stable id the Search API provider registers under in the search registry. */
215
+ const DEEPSEEK_SEARCH_API_PROVIDER_ID = "deepseek-search-api";
216
+ /** Default Search and Fetch API base, including its `/v1/tools` prefix; `/search` and `/fetch` are appended. */
217
+ const DEEPSEEK_WEB_API_BASE_URL = "https://api.deepseek.com/v1/tools";
218
+ /** Default Search API result count, the service's own default. */
219
+ const DEEPSEEK_DEFAULT_COUNT = 10;
220
+ /** Longest `ori_question` the Search API accepts, in characters. */
221
+ const ORIGINAL_QUESTION_MAX_CHARS = 128;
222
+ /** Settings named by endpoint failures of either API in this package. */
223
+ const DEEPSEEK_WEB_API_GUIDANCE = {
224
+ plugin: "web-deepseek-api",
225
+ field: "baseURL",
226
+ label: "Search / Fetch API base URL",
227
+ page: "Web search"
228
+ };
229
+ /**
230
+ * Validate a Search API response and project its sources into the web service.
231
+ * @param response - untrusted JSON from the Search endpoint.
232
+ * @returns sources with provider order and nullable publication dates preserved.
233
+ * @throws {@link WebError} when the response does not contain valid search results.
234
+ */
235
+ function mapSearchResponse(response) {
236
+ if (!isRecord(response) || !Array.isArray(response.results)) throw invalidResponse();
237
+ return {
238
+ sources: response.results.map((item) => {
239
+ if (!isRecord(item) || typeof item.url !== "string" || item.url.length === 0 || typeof item.title !== "string" || typeof item.snippet !== "string" || item.date !== null && typeof item.date !== "string") throw invalidResponse();
240
+ return {
241
+ url: item.url,
242
+ ...item.title.length > 0 ? { title: item.title } : {},
243
+ ...item.snippet.length > 0 ? { snippet: item.snippet } : {},
244
+ ...item.date !== null && item.date.length > 0 ? { publishedAt: item.date } : {}
245
+ };
246
+ }),
247
+ truncated: false
248
+ };
249
+ }
250
+ /**
251
+ * Search through the DeepSeek Search API. HTTP redirects fail as `WEB_PROVIDER_ERROR`;
252
+ * failures after dispatch name the endpoint and tell the model how the user can configure it.
253
+ */
254
+ var DeepSeekSearchApiProvider = class {
255
+ resolveOptions;
256
+ id = DEEPSEEK_SEARCH_API_PROVIDER_ID;
257
+ /**
258
+ * @param resolveOptions - the options for the NEXT search, read once at each
259
+ * search's entry so one search never mixes two settings sections.
260
+ */
261
+ constructor(resolveOptions) {
262
+ this.resolveOptions = resolveOptions;
263
+ }
264
+ available() {
265
+ const options = this.resolveOptions();
266
+ return hasDeepSeekWebCredential(options) && URL.canParse(options.baseURL) && isPositiveInteger(options.count);
267
+ }
268
+ search(request, signal) {
269
+ const options = this.resolveOptions();
270
+ const question = boundedQuestion(options.originalQuestion?.());
271
+ return dispatchDeepSeekWeb(options, {
272
+ endpoint: `${options.baseURL.replace(/\/+$/u, "")}/search`,
273
+ body: {
274
+ query: request.query,
275
+ count: Math.min(options.count, request.maxResults ?? options.count),
276
+ need_content: false,
277
+ ...question === void 0 ? {} : { ori_question: question }
278
+ },
279
+ decode: mapSearchResponse,
280
+ guidance: {
281
+ subject: "Search",
282
+ ...DEEPSEEK_WEB_API_GUIDANCE
283
+ }
284
+ }, signal);
285
+ }
286
+ };
287
+ /**
288
+ * Bound the triggering question to what `ori_question` accepts: whitespace
289
+ * collapses to single spaces and the first 128 characters remain.
290
+ * @param question - the user question, when one exists.
291
+ * @returns the bounded question, or undefined when nothing remains.
292
+ */
293
+ function boundedQuestion(question) {
294
+ const collapsed = question?.replace(/\s+/gu, " ").trim() ?? "";
295
+ if (collapsed.length === 0) return void 0;
296
+ return Array.from(collapsed).slice(0, ORIGINAL_QUESTION_MAX_CHARS).join("");
297
+ }
298
+ /** True for positive integral request limits. */
299
+ function isPositiveInteger(value) {
300
+ return Number.isInteger(value) && value > 0;
301
+ }
302
+ //#endregion
303
+ //#region lib/types/fetch.js
304
+ /** Stable id the Fetch API provider registers under in the fetch registry. */
305
+ const DEEPSEEK_FETCH_API_PROVIDER_ID = "deepseek-fetch-api";
306
+ /**
307
+ * Fetch page Markdown through the DeepSeek Fetch API. The API reports neither the
308
+ * target's status nor a final URL, and it fails when the target yields no usable
309
+ * content, so a success is the requested page retrieved with HTTP 200.
310
+ */
311
+ var DeepSeekFetchApiProvider = class {
312
+ resolveOptions;
313
+ id = DEEPSEEK_FETCH_API_PROVIDER_ID;
314
+ /** @param resolveOptions - the options for the NEXT fetch, read once at each fetch's entry. */
315
+ constructor(resolveOptions) {
316
+ this.resolveOptions = resolveOptions;
317
+ }
318
+ available() {
319
+ const options = this.resolveOptions();
320
+ return hasDeepSeekWebCredential(options) && URL.canParse(options.baseURL);
321
+ }
322
+ fetch(request, signal) {
323
+ const options = this.resolveOptions();
324
+ return dispatchDeepSeekWeb(options, {
325
+ endpoint: `${options.baseURL.replace(/\/+$/u, "")}/fetch`,
326
+ body: { url: request.url },
327
+ decode: (payload) => {
328
+ if (!isRecord(payload) || typeof payload.content !== "string") throw invalidResponse();
329
+ return {
330
+ url: request.url,
331
+ statusCode: 200,
332
+ body: {
333
+ kind: "text",
334
+ content: payload.content
335
+ },
336
+ truncated: false
337
+ };
338
+ },
339
+ guidance: {
340
+ subject: "Fetch",
341
+ ...DEEPSEEK_WEB_API_GUIDANCE
342
+ }
343
+ }, signal);
344
+ }
345
+ };
346
+ //#endregion
347
+ //#region lib/types/index.js
348
+ /** Cordis plugin name used by loader diagnostics. */
349
+ const name = "web-deepseek-api";
350
+ /** The web seam both providers register into. */
351
+ const inject = ["web"];
352
+ const Config = z.object({
353
+ apiKey: z.string().role("secret").volatile(),
354
+ apiKeyEnv: z.string().role("credential-ref").default("DEEPSEEK_API_KEY").volatile(),
355
+ baseURL: z.string().default(DEEPSEEK_WEB_API_BASE_URL).volatile(),
356
+ count: z.number().step(1).min(1).max(50).default(10).volatile(),
357
+ sendOriginalQuestion: z.boolean().default(true).volatile()
358
+ });
359
+ /**
360
+ * Read the text of the latest human prompt, the question that triggered the
361
+ * current turn. Injected user-role context carries another source kind.
362
+ * @param session - the initiating Session, when the search runs inside one.
363
+ * @returns the prompt's joined text blocks, or undefined without a prompt.
364
+ */
365
+ function latestUserQuestion(session) {
366
+ const prompt = session?.deriveMessages().findLast((message) => message.role === "user" && message.source.kind === "user");
367
+ if (prompt === void 0) return void 0;
368
+ return prompt.content.flatMap((block) => block.type === "text" ? [block.text] : []).join("\n");
369
+ }
370
+ /**
371
+ * Register the Search API and Fetch API providers over one live settings section.
372
+ * @param ctx - plugin context owning both registrations.
373
+ * @param config - live settings, read once per operation.
374
+ */
375
+ function apply(ctx, config) {
376
+ const auth = () => deepSeekWebAuth(ctx, {
377
+ apiKey: config.apiKey.get(),
378
+ apiKeyEnv: config.apiKeyEnv.get()
379
+ });
380
+ ctx.web.registerSearchProvider(new DeepSeekSearchApiProvider(() => ({
381
+ ...auth(),
382
+ baseURL: config.baseURL.get(),
383
+ count: config.count.get(),
384
+ ...config.sendOriginalQuestion.get() ? { originalQuestion: () => latestUserQuestion(ctx.get("agents")?.currentInitiator()?.session) } : {}
385
+ })));
386
+ ctx.web.registerFetchProvider(new DeepSeekFetchApiProvider(() => ({
387
+ ...auth(),
388
+ baseURL: config.baseURL.get()
389
+ })));
390
+ }
391
+ //#endregion
392
+ export { Config, DEEPSEEK_DEFAULT_COUNT, DEEPSEEK_FETCH_API_PROVIDER_ID, DEEPSEEK_SEARCH_API_PROVIDER_ID, DEEPSEEK_WEB_API_BASE_URL, DeepSeekFetchApiProvider, DeepSeekSearchApiProvider, apply, inject, mapSearchResponse, name };
@@ -0,0 +1,28 @@
1
+ /**
2
+ * DeepSeek Fetch API provider: page Markdown through one direct request, without
3
+ * a model request.
4
+ * @module @deepseek-ai/dsh-web-deepseek-api/fetch
5
+ */
6
+ import type { WebFetchProvider, WebFetchRequest, WebFetchResult } from '@deepseek-ai/dsh-web';
7
+ import { type DeepSeekWebAuth } from './transport.ts';
8
+ /** Stable id the Fetch API provider registers under in the fetch registry. */
9
+ export declare const DEEPSEEK_FETCH_API_PROVIDER_ID = "deepseek-fetch-api";
10
+ /** Authentication and endpoint settings snapshotted for one fetch. */
11
+ export interface DeepSeekFetchApiOptions extends DeepSeekWebAuth {
12
+ /** API base including its path prefix; `/fetch` is appended. */
13
+ baseURL: string;
14
+ }
15
+ /**
16
+ * Fetch page Markdown through the DeepSeek Fetch API. The API reports neither the
17
+ * target's status nor a final URL, and it fails when the target yields no usable
18
+ * content, so a success is the requested page retrieved with HTTP 200.
19
+ */
20
+ export declare class DeepSeekFetchApiProvider implements WebFetchProvider {
21
+ private readonly resolveOptions;
22
+ readonly id = "deepseek-fetch-api";
23
+ /** @param resolveOptions - the options for the NEXT fetch, read once at each fetch's entry. */
24
+ constructor(resolveOptions: () => DeepSeekFetchApiOptions);
25
+ available(): boolean;
26
+ fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>;
27
+ }
28
+ //# sourceMappingURL=fetch.d.ts.map
@@ -0,0 +1,52 @@
1
+ /**
2
+ * Register the DeepSeek Search and Fetch APIs in `ctx.web` as `deepseek-search-api`
3
+ * and `deepseek-fetch-api`. Each operation is one direct API request without an
4
+ * auxiliary model request; both providers read this section's credential and API
5
+ * base. `web.searchProvider` and `web.fetchProvider` select them. A Session on the
6
+ * DeepSeek account route authenticates with the account token when the account
7
+ * service allows the endpoint; every other request uses the configured key.
8
+ * @module @deepseek-ai/dsh-web-deepseek-api
9
+ */
10
+ import type { Context, Volatile } from '@deepseek-ai/cordis';
11
+ import z from '@deepseek-ai/schemastery';
12
+ export { DEEPSEEK_FETCH_API_PROVIDER_ID, DeepSeekFetchApiProvider } from './fetch.ts';
13
+ export type { DeepSeekFetchApiOptions } from './fetch.ts';
14
+ export { DEEPSEEK_DEFAULT_COUNT, DEEPSEEK_SEARCH_API_PROVIDER_ID, DEEPSEEK_WEB_API_BASE_URL, DeepSeekSearchApiProvider, mapSearchResponse, } from './search.ts';
15
+ export type { DeepSeekSearchApiOptions } from './search.ts';
16
+ /** Cordis plugin name used by loader diagnostics. */
17
+ export declare const name = "web-deepseek-api";
18
+ /** The web seam both providers register into. */
19
+ export declare const inject: string[];
20
+ /** Settings read by the next search or fetch without re-registering either provider. */
21
+ export interface Config {
22
+ /** Literal DeepSeek API key; prefer {@link apiKeyEnv} so no secret enters configuration files. */
23
+ apiKey: Volatile<string | undefined>;
24
+ /** Credential reference resolved for each operation; defaults to `DEEPSEEK_API_KEY`. */
25
+ apiKeyEnv: Volatile<string>;
26
+ /** API base including its path prefix; `/search` and `/fetch` are appended. */
27
+ baseURL: Volatile<string>;
28
+ /** Search API results per search, from 1 through 50; a smaller request bound wins. Defaults to 10. */
29
+ count: Volatile<number>;
30
+ /** Send the triggering user question, bounded to 128 characters, as `ori_question`. Defaults to true. */
31
+ sendOriginalQuestion: Volatile<boolean>;
32
+ }
33
+ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
34
+ apiKey: z<string, string, "volatile">;
35
+ apiKeyEnv: z<string, string, "volatile-defined">;
36
+ baseURL: z<string, string, "volatile-defined">;
37
+ count: z<number, number, "volatile-defined">;
38
+ sendOriginalQuestion: z<boolean, boolean, "volatile-defined">;
39
+ }>>, Schemastery.ObjectT<NoInfer<{
40
+ apiKey: z<string, string, "volatile">;
41
+ apiKeyEnv: z<string, string, "volatile-defined">;
42
+ baseURL: z<string, string, "volatile-defined">;
43
+ count: z<number, number, "volatile-defined">;
44
+ sendOriginalQuestion: z<boolean, boolean, "volatile-defined">;
45
+ }>>, "plain">;
46
+ /**
47
+ * Register the Search API and Fetch API providers over one live settings section.
48
+ * @param ctx - plugin context owning both registrations.
49
+ * @param config - live settings, read once per operation.
50
+ */
51
+ export declare function apply(ctx: Context, config: Config): void;
52
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1,47 @@
1
+ /**
2
+ * DeepSeek Search API provider: one direct request per search, without an
3
+ * auxiliary model request.
4
+ * @module @deepseek-ai/dsh-web-deepseek-api/search
5
+ */
6
+ import type { WebSearchProvider, WebSearchRequest, WebSearchResult } from '@deepseek-ai/dsh-web';
7
+ import { type DeepSeekWebAuth, type DeepSeekWebGuidance } from './transport.ts';
8
+ /** Stable id the Search API provider registers under in the search registry. */
9
+ export declare const DEEPSEEK_SEARCH_API_PROVIDER_ID = "deepseek-search-api";
10
+ /** Default Search and Fetch API base, including its `/v1/tools` prefix; `/search` and `/fetch` are appended. */
11
+ export declare const DEEPSEEK_WEB_API_BASE_URL = "https://api.deepseek.com/v1/tools";
12
+ /** Default Search API result count, the service's own default. */
13
+ export declare const DEEPSEEK_DEFAULT_COUNT = 10;
14
+ /** Settings named by endpoint failures of either API in this package. */
15
+ export declare const DEEPSEEK_WEB_API_GUIDANCE: Omit<DeepSeekWebGuidance, 'subject'>;
16
+ /** Authentication, endpoint, and result settings snapshotted for one search. */
17
+ export interface DeepSeekSearchApiOptions extends DeepSeekWebAuth {
18
+ /** API base including its path prefix; `/search` is appended. */
19
+ baseURL: string;
20
+ /** Results requested per search, from 1 through 50; a smaller request bound wins. */
21
+ count: number;
22
+ /** Read the user question that triggered the search; undefined or blank sends none. */
23
+ originalQuestion?: () => string | undefined;
24
+ }
25
+ /**
26
+ * Validate a Search API response and project its sources into the web service.
27
+ * @param response - untrusted JSON from the Search endpoint.
28
+ * @returns sources with provider order and nullable publication dates preserved.
29
+ * @throws {@link WebError} when the response does not contain valid search results.
30
+ */
31
+ export declare function mapSearchResponse(response: unknown): WebSearchResult;
32
+ /**
33
+ * Search through the DeepSeek Search API. HTTP redirects fail as `WEB_PROVIDER_ERROR`;
34
+ * failures after dispatch name the endpoint and tell the model how the user can configure it.
35
+ */
36
+ export declare class DeepSeekSearchApiProvider implements WebSearchProvider {
37
+ private readonly resolveOptions;
38
+ readonly id = "deepseek-search-api";
39
+ /**
40
+ * @param resolveOptions - the options for the NEXT search, read once at each
41
+ * search's entry so one search never mixes two settings sections.
42
+ */
43
+ constructor(resolveOptions: () => DeepSeekSearchApiOptions);
44
+ available(): boolean;
45
+ search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>;
46
+ }
47
+ //# sourceMappingURL=search.d.ts.map
@@ -0,0 +1,87 @@
1
+ /**
2
+ * Authentication and redirect-rejecting transport shared by the Search and
3
+ * Fetch API providers in this package. Credential resolution, the dispatch
4
+ * call, and the cancellation helpers deliberately repeat
5
+ * `dsh-web-search-deepseek`, so neither plugin depends on the other; the
6
+ * `jscpd:ignore` regions mark those repeats
7
+ * ([rationale](../../../../.agents/notes/implemented/feature/2026-10-15-deepseek-search-fetch-api.md)).
8
+ * @module @deepseek-ai/dsh-web-deepseek-api/transport
9
+ */
10
+ import type { Context } from '@deepseek-ai/cordis';
11
+ import { type CredentialRef } from '@deepseek-ai/dsh-credentials';
12
+ import { WebError } from '@deepseek-ai/dsh-web';
13
+ /** Authentication and endpoint values resolved once for an operation. */
14
+ export interface DeepSeekWebAuth {
15
+ /** Resolve an allowed account token; undefined selects API-key authentication. */
16
+ resolveAccountToken?: (endpoint: string) => Promise<string | undefined>;
17
+ /** Literal API key; takes precedence over the credential resolver. */
18
+ apiKey?: string;
19
+ /** Resolve the current API key without retaining it. */
20
+ resolveApiKey?: () => Promise<string | undefined>;
21
+ /** Credential reference named by missing-key diagnostics. */
22
+ apiKeyEnv?: CredentialRef;
23
+ }
24
+ /** User-owned endpoint settings named by dispatch failures. */
25
+ export interface DeepSeekWebGuidance {
26
+ /** Capability whose endpoint failed. */
27
+ subject: 'Search' | 'Fetch';
28
+ /** Plugin configuration namespace. */
29
+ plugin: string;
30
+ /** Endpoint configuration field. */
31
+ field: string;
32
+ /** Local settings label. */
33
+ label: string;
34
+ /** Built-in settings page title. */
35
+ page: string;
36
+ }
37
+ /** One fully resolved web API request. */
38
+ interface DeepSeekWebRequest<T> {
39
+ /** Absolute dispatch URL. */
40
+ endpoint: string;
41
+ /** JSON request body. */
42
+ body: object;
43
+ /** Protocol headers without credentials. */
44
+ headers?: Readonly<Record<string, string>>;
45
+ /** Additional API-key headers; not applied to account tokens. */
46
+ apiKeyHeaders?: (key: string) => Readonly<Record<string, string>>;
47
+ /** Validate and project the response. */
48
+ decode: (payload: unknown) => T;
49
+ /** Endpoint recovery settings. */
50
+ guidance: DeepSeekWebGuidance;
51
+ /** Record model input before dispatch; a throw prevents dispatch. */
52
+ recordRequest?: (endpoint: string) => void;
53
+ }
54
+ /**
55
+ * Resolve credential sources for one operation without retaining secret values.
56
+ * @param ctx - Provider context with request routing and credential services.
57
+ * @param config - Literal key and credential reference from the settings snapshot.
58
+ * @returns Authentication sources for one operation.
59
+ */
60
+ export declare function deepSeekWebAuth(ctx: Context, config: {
61
+ apiKey: string | undefined;
62
+ apiKeyEnv: string;
63
+ }): DeepSeekWebAuth;
64
+ /**
65
+ * Check whether an authentication source exists; does not resolve credentials.
66
+ * @param auth - Sources for the operation.
67
+ * @returns Whether a literal key or resolver is present.
68
+ */
69
+ export declare function hasDeepSeekWebCredential(auth: DeepSeekWebAuth): boolean;
70
+ /** Narrow a remote JSON object.
71
+ * @param value - Untrusted JSON.
72
+ * @returns Whether readable object fields exist.
73
+ */
74
+ export declare function isRecord(value: unknown): value is Record<string, unknown>;
75
+ /** Report malformed upstream JSON without embedding response content.
76
+ * @returns The stable provider error.
77
+ */
78
+ export declare function invalidResponse(): WebError;
79
+ /** Dispatch one operation using a single settings and credential snapshot.
80
+ * @param options - Authentication sources for this operation.
81
+ * @param request - Resolved endpoint, JSON payload, and response decoder.
82
+ * @param signal - Caller cancellation signal.
83
+ * @returns The validated provider result.
84
+ */
85
+ export declare function dispatchDeepSeekWeb<T>(options: DeepSeekWebAuth, request: DeepSeekWebRequest<T>, signal?: AbortSignal): Promise<T>;
86
+ export {};
87
+ //# sourceMappingURL=transport.d.ts.map
package/locale/en.json ADDED
@@ -0,0 +1,5 @@
1
+ {
2
+ "meta": {
3
+ "title": "web-deepseek-api"
4
+ }
5
+ }
package/locale/zh.json ADDED
@@ -0,0 +1,6 @@
1
+ {
2
+ "meta": {
3
+ "title": "DeepSeek 网页搜索与抓取 API",
4
+ "description": "通过 DeepSeek Search API 搜索网页、Fetch API 抓取网页正文。"
5
+ }
6
+ }
package/package.json CHANGED
@@ -1,6 +1,59 @@
1
1
  {
2
2
  "name": "@deepseek-ai/dsh-web-deepseek-api",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "description": "DeepSeek Search and Fetch API providers for the DeepSeek Harness web capability seam (ctx.web)",
4
+ "version": "0.2.1-rc.3",
5
+ "publishConfig": {
6
+ "access": "public"
7
+ },
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
11
+ "directory": "packages/web/web-deepseek-api"
12
+ },
13
+ "type": "module",
14
+ "main": "lib/index.js",
15
+ "types": "lib/types/index.d.ts",
16
+ "exports": {
17
+ ".": {
18
+ "types": "./lib/types/index.d.ts",
19
+ "default": "./lib/index.js"
20
+ },
21
+ "./src/*": "./src/*",
22
+ "./package.json": "./package.json",
23
+ "./locale/*.json": "./locale/*.json"
24
+ },
25
+ "files": [
26
+ "locale/*.json",
27
+ "lib/index.js",
28
+ "lib/types/**/*.d.ts"
29
+ ],
30
+ "license": "MIT",
31
+ "peerDependencies": {
32
+ "@deepseek-ai/dsh-agent": "0.2.1-rc.3",
33
+ "@deepseek-ai/dsh-credentials": "0.2.1-rc.3",
34
+ "@deepseek-ai/dsh-deepseek-account": "0.2.1-rc.3",
35
+ "@deepseek-ai/dsh-launch-environment": "0.2.1-rc.3",
36
+ "@deepseek-ai/dsh-session": "0.2.1-rc.3",
37
+ "@deepseek-ai/dsh-web": "0.2.1-rc.3",
38
+ "@deepseek-ai/cordis": "~4.0.5"
39
+ },
40
+ "dependencies": {
41
+ "@deepseek-ai/schemastery": "~3.18.5"
42
+ },
43
+ "devDependencies": {
44
+ "@deepseek-ai/dsh-agent": "0.2.1-rc.3",
45
+ "@deepseek-ai/dsh-credentials": "0.2.1-rc.3",
46
+ "@deepseek-ai/dsh-credentials-local": "0.2.1-rc.3",
47
+ "@deepseek-ai/dsh-deepseek-account": "0.2.1-rc.3",
48
+ "@deepseek-ai/dsh-launch-environment": "0.2.1-rc.3",
49
+ "@deepseek-ai/dsh-session": "0.2.1-rc.3",
50
+ "@deepseek-ai/dsh-web": "0.2.1-rc.3",
51
+ "@deepseek-ai/cordis": "~4.0.5",
52
+ "@deepseek-ai/dsh-http-proxy": "0.2.1-rc.3"
53
+ },
54
+ "peerDependenciesMeta": {
55
+ "@deepseek-ai/dsh-deepseek-account": {
56
+ "optional": true
57
+ }
58
+ }
6
59
  }