@h-ai/reach 1.0.0-beta.13 → 1.0.0-beta.15

package/README.en.md

@@ -90,14 +90,31 @@ const config = { name: 'dev', type: 'console' }
 
 #### Alibaba Cloud SMS
 
-| Field             | Type     | Required | Default                 | Description          |
-| ----------------- | -------- | -------- | ----------------------- | -------------------- |
-| `name`            | `string` | ✅       | —                       | Provider name        |
-| `type`            | `string` | ✅       | —                       | Fixed `'aliyun-sms'` |
-| `accessKeyId`     | `string` | ✅       | —                       | AccessKey ID         |
-| `accessKeySecret` | `string` | ✅       | —                       | AccessKey Secret     |
-| `signName`        | `string` | ✅       | —                       | SMS signature        |
-| `endpoint`        | `string` | —        | `dysmsapi.aliyuncs.com` | API endpoint         |
+| Field             | Type     | Required | Default                 | Description                |
+| ----------------- | -------- | -------- | ----------------------- | -------------------------- |
+| `name`            | `string` | ✅       | —                       | Provider name              |
+| `type`            | `string` | ✅       | —                       | Fixed `'aliyun-sms'`       |
+| `accessKeyId`     | `string` | ✅       | —                       | AccessKey ID               |
+| `accessKeySecret` | `string` | ✅       | —                       | AccessKey Secret           |
+| `signName`        | `string` | ✅       | —                       | SMS signature              |
+| `endpoint`        | `string` | —        | `dysmsapi.aliyuncs.com` | Direct HTTPS GET endpoint  |
+| `gateway`         | `object` | —        | —                       | Optional isolation gateway |
+
+Add `gateway` to an `aliyun-sms` provider to send a POST request to the full `url`. Alibaba Cloud signature input uses `POST`, the RPC path `/`, and the query parameters. The gateway path, headers, and body apply to the gateway hop.
+
+```yaml
+gateway:
+  url: https://sms-gateway.example.com/dx
+  headers:
+    X-Gateway-Client: delivery
+  body: {}
+```
+
+`headers` accepts string values. `body` accepts a JSON object, an array, or raw text. Omit `body` for a request without content. Objects and arrays default to `application/json`, and text defaults to `text/plain; charset=utf-8`. Set `Content-Type` to override the default. HTTP on a trusted private network requires `allowInsecureHttp: true`. The signed query, phone numbers, and template variables travel in plaintext over HTTP. Redact query strings in gateway and proxy access logs.
+
+Bind a synchronous or asynchronous server-side function with `reach.init(config, { gatewayHooks: { sms: buildGatewayFields } })`, using the configured provider name as the key. The hook receives `{ method, url, body, signal }`, with the static body already serialized, and can return `{ headers, body }`. Its headers override static values by case-insensitive name, and its body replaces the entire static body. Omitted fields inherit the static values. The HTTP client manages transport headers such as `Host` and `Content-Length`. Treat the signed URL as sensitive. The gateway snapshot in `reach.config` includes the URL and HTTP opt-in flag.
+
+The hook and request share a 10-second deadline. Redirects are rejected. HTTP 2xx with Alibaba Cloud `Code: OK` confirms acceptance, and `BizId` can be used to check delivery. Uncertain outcomes follow the existing delivery policy, without falling back to direct delivery.
 
 #### API callbacks
 

package/README.ja.md

@@ -90,14 +90,31 @@ const config = { name: 'dev', type: 'console' }
 
 #### Alibaba Cloud SMS
 
-| フィールド        | 型       | 必須 | 既定値                  | 説明                  |
-| ----------------- | -------- | ---- | ----------------------- | --------------------- |
-| `name`            | `string` | ✅   | —                       | Provider 名           |
-| `type`            | `string` | ✅   | —                       | 固定値 `'aliyun-sms'` |
-| `accessKeyId`     | `string` | ✅   | —                       | AccessKey ID          |
-| `accessKeySecret` | `string` | ✅   | —                       | AccessKey Secret      |
-| `signName`        | `string` | ✅   | —                       | SMS 署名              |
-| `endpoint`        | `string` | —    | `dysmsapi.aliyuncs.com` | API endpoint          |
+| フィールド        | 型       | 必須 | 既定値                  | 説明                         |
+| ----------------- | -------- | ---- | ----------------------- | ---------------------------- |
+| `name`            | `string` | ✅   | —                       | Provider 名                  |
+| `type`            | `string` | ✅   | —                       | 固定値 `'aliyun-sms'`        |
+| `accessKeyId`     | `string` | ✅   | —                       | AccessKey ID                 |
+| `accessKeySecret` | `string` | ✅   | —                       | AccessKey Secret             |
+| `signName`        | `string` | ✅   | —                       | SMS 署名                     |
+| `endpoint`        | `string` | —    | `dysmsapi.aliyuncs.com` | HTTPS GET の直接接続先       |
+| `gateway`         | `object` | —    | —                       | オプションの分離ゲートウェイ |
+
+`aliyun-sms` Provider に `gateway` を追加すると、完全な `url` へ POST します。Alibaba Cloud の署名には `POST`、RPC パス `/`、クエリパラメーターを使用します。ゲートウェイのパス、ヘッダー、ボディはゲートウェイへのリクエストに適用されます。
+
+```yaml
+gateway:
+  url: https://sms-gateway.example.com/dx
+  headers:
+    X-Gateway-Client: delivery
+  body: {}
+```
+
+`headers` の値は文字列です。`body` には JSON オブジェクト、配列、またはテキストを指定でき、省略時はボディなしで送信します。既定の `Content-Type` はオブジェクトと配列が `application/json`、テキストが `text/plain; charset=utf-8` です。信頼できる内部ネットワークで HTTP を使う場合は `allowInsecureHttp: true` が必要です。HTTP では署名済みクエリ、電話番号、テンプレート変数が平文で送られるため、ゲートウェイとプロキシのアクセスログでクエリをマスクしてください。
+
+同期または非同期の関数は、サーバー側で `reach.init(config, { gatewayHooks: { sms: buildGatewayFields } })` のように Provider 名へ紐付けます。関数は `{ method, url, body, signal }` を受け取り、`{ headers, body }` を返せます。入力の `body` はシリアライズ済みです。ヘッダー名は大文字・小文字を区別せず上書きし、ボディは全体を置き換えます。省略した項目には静的設定を使います。`Host` や `Content-Length` は HTTP クライアントが管理します。署名済み URL は機密情報として扱います。`reach.config` のゲートウェイ情報には URL と HTTP の許可フラグが含まれます。
+
+関数と HTTP リクエストの合計期限は 10 秒で、リダイレクトは拒否します。HTTP 2xx かつ Alibaba Cloud の `Code: OK` で受理を確認し、`BizId` で配信結果を照会できます。結果が不明な場合は既存の配信ポリシーに従い、直接送信への切り替えは行いません。
 
 #### API 通知
 

package/README.md

@@ -97,7 +97,24 @@ const config = { name: 'dev', type: 'console' }
 | `accessKeyId`     | `string` | ✅   | —                       | AccessKey ID        |
 | `accessKeySecret` | `string` | ✅   | —                       | AccessKey Secret    |
 | `signName`        | `string` | ✅   | —                       | 短信签名            |
-| `endpoint`        | `string` | —    | `dysmsapi.aliyuncs.com` | API 端点            |
+| `endpoint`        | `string` | —    | `dysmsapi.aliyuncs.com` | HTTPS GET 直连端点  |
+| `gateway`         | `object` | —    | —                       | 可选的隔离网关      |
+
+在 `aliyun-sms` Provider 下添加 `gateway` 后，Reach 向完整 `url` 发送 POST。阿里云签名使用 `POST`、RPC 路径 `/` 和查询参数。网关路径、请求头和请求体仅用于网关这一跳。
+
+```yaml
+gateway:
+  url: https://sms-gateway.example.com/dx
+  headers:
+    X-Gateway-Client: delivery
+  body: {}
+```
+
+`headers` 接受字符串键值，`body` 可为 JSON 对象、数组或原始文本。省略 `body` 时发送无正文请求。对象和数组默认为 `application/json`，文本默认为 `text/plain; charset=utf-8`，可以用 `Content-Type` 覆盖。受信内网使用 HTTP 时须显式设 `allowInsecureHttp: true`。HTTP 下签名查询串、手机号及模板变量是明文，网关和代理的访问日志应对查询串脱敏。
+
+在服务端通过 `reach.init(config, { gatewayHooks: { sms: buildGatewayFields } })` 绑定同步或异步函数，其中 `sms` 是启用网关的 Provider 名称。函数接收 `{ method, url, body, signal }`，可返回 `{ headers, body }`。`body` 入参是已序列化的静态正文。函数返回的头按名称忽略大小写覆盖静态头，返回的正文整段替换。省略字段时使用静态配置。`Host`、`Content-Length` 等传输头由客户端管理。函数接收的已签名 URL 仅供服务端构造请求，`reach.config` 的网关快照仅展示地址和 HTTP 开关。
+
+函数和 HTTP 请求共用 10 秒期限，禁止重定向。HTTP 2xx 且阿里云返回 `Code: OK` 表示受理，`BizId` 可用于查询送达结果。发送结果不明时按原投递策略处理，网关分支不会自动回退直连。
 
 #### API 回调
 

package/dist/index.d.ts

@@ -59,6 +59,12 @@ declare const AliyunSmsProviderConfigSchema: z.ZodObject<{
     accessKeySecret: z.ZodString;
     signName: z.ZodString;
     endpoint: z.ZodDefault<z.ZodString>;
+    gateway: z.ZodOptional<z.ZodObject<{
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        body: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodJSONSchema>, z.ZodRecord<z.ZodString, z.ZodJSONSchema>]>>;
+        url: z.ZodURL;
+        allowInsecureHttp: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
 }, z.core.$strip>;
 /**
  * HTTP回调配置；idempotent默认false，只有接收端按稳定Idempotency-Key原子持久去重并覆盖旧请求迟到窗口才允许true。
@@ -115,6 +121,12 @@ declare const ProviderConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     accessKeySecret: z.ZodString;
     signName: z.ZodString;
     endpoint: z.ZodDefault<z.ZodString>;
+    gateway: z.ZodOptional<z.ZodObject<{
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        body: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodJSONSchema>, z.ZodRecord<z.ZodString, z.ZodJSONSchema>]>>;
+        url: z.ZodURL;
+        allowInsecureHttp: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
 }, z.core.$strip>, z.ZodObject<{
     name: z.ZodString;
     type: z.ZodLiteral<"api">;
@@ -344,6 +356,12 @@ declare const ReachConfigSchema: z.ZodObject<{
         accessKeySecret: z.ZodString;
         signName: z.ZodString;
         endpoint: z.ZodDefault<z.ZodString>;
+        gateway: z.ZodOptional<z.ZodObject<{
+            headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            body: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodJSONSchema>, z.ZodRecord<z.ZodString, z.ZodJSONSchema>]>>;
+            url: z.ZodURL;
+            allowInsecureHttp: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strict>>;
     }, z.core.$strip>, z.ZodObject<{
         name: z.ZodString;
         type: z.ZodLiteral<"api">;
@@ -440,6 +458,38 @@ declare const HaiReachError: {
  * ```
  */
 type ReachChannel = 'email' | 'sms' | 'api';
+/**
+ * 发送前为网关提供请求头或替换请求体。URL 已包含签名和可能敏感的查询数据，函数必须在可信服务端运行。
+ * 返回 undefined 保留静态配置；字符串 body 按原样发送。signal 覆盖函数执行与 HTTP 请求的共同期限。
+ *
+ * @example
+ * ```ts
+ * import type { ReachGatewayHook } from '@h-ai/reach'
+ * const hook: ReachGatewayHook = ({ body, signal }) => {
+ *   signal.throwIfAborted()
+ *   return { headers: { 'X-Client': 'delivery' }, body: body ?? '{}' }
+ * }
+ * ```
+ */
+type ReachGatewayHook = (request: Readonly<{
+    method: 'POST';
+    url: string;
+    body: string | undefined;
+    signal: AbortSignal;
+}>) => Pick<NonNullable<AliyunSmsProviderConfig['gateway']>, 'headers' | 'body'> | void | Promise<Pick<NonNullable<AliyunSmsProviderConfig['gateway']>, 'headers' | 'body'> | void>;
+/**
+ * 服务端运行时注入选项，与可序列化的配置分离。
+ *
+ * @example
+ * ```ts
+ * import type { ReachInitOptions } from '@h-ai/reach'
+ * const options: ReachInitOptions = { gatewayHooks: { sms: () => ({ headers: { 'X-Client': 'delivery' } }) } }
+ * ```
+ */
+interface ReachInitOptions {
+    /** 以已配置网关的 Provider 名称绑定自定义函数。 */
+    gatewayHooks?: Readonly<Record<string, ReachGatewayHook>>;
+}
 /**
  * 直接发送必须指定Provider名和内容；模板发送可由持久模板推导路由，vars做文本替换。
  * 队列幂等键固定为持久queueId；直接调用的业务重试由应用提供稳定idempotencyKey并核验接收端契约。
@@ -1215,6 +1265,7 @@ interface ReachFunctions extends SendOperations {
     /**
      * 初始化触达模块（注册多个 Provider）
      * @param config - 实际操作输入，按本方法约束校验。
+     * @param options - 可选服务端运行时网关函数，按 Provider 名称绑定。
      * @returns HaiResult；先检查success，条件提交失败不能伪装成功。
      *
      * @example
@@ -1244,7 +1295,7 @@ interface ReachFunctions extends SendOperations {
      * }
      * ```
      */
-    init: (config: ReachConfigInput) => Promise<HaiResult<void>>;
+    init: (config: ReachConfigInput, options?: ReachInitOptions) => Promise<HaiResult<void>>;
     /** 当前脱敏后的配置快照（未初始化时为 null） */
     readonly config: ReachConfig | null;
     /** 是否已初始化 */
@@ -1338,4 +1389,4 @@ declare function migrateReach(options?: {
     dryRun?: boolean;
 }, db?: ReldbFunctions): Promise<_h_ai_core.HaiResult<_h_ai_reldb.SchemaMigrationPlan>>;
 
-export { type AliyunSmsProviderConfig, AliyunSmsProviderConfigSchema, type ApiProviderConfig, ApiProviderConfigSchema, type ConsoleProviderConfig, ConsoleProviderConfigSchema, type DndConfig, DndConfigSchema, HaiReachError, type ProviderConfig, ProviderConfigSchema, type ReachChannel, type ReachConfig, type ReachConfigInput, ReachConfigSchema, type ReachDeadRequeue, ReachDeadRequeueSchema, type ReachFunctions, type ReachMessage, type ReachQueueConfig, ReachQueueConfigSchema, type ReachQueueEntry, type ReachQueueFailure, ReachQueueIdSchema, type ReachQueueListOptions, ReachQueueListSchema, type ReachQueueOperations, type ReachQueueStatus, type ReachTemplate, type ReachTemplateRegistry, type ReachUnknownResolution, ReachUnknownResolutionSchema, type RenderedTemplate, type SendOperations, type SendResult, type SmtpProviderConfig, SmtpProviderConfigSchema, type TemplateConfig, TemplateConfigSchema, migrateReach, reach };
+export { type AliyunSmsProviderConfig, AliyunSmsProviderConfigSchema, type ApiProviderConfig, ApiProviderConfigSchema, type ConsoleProviderConfig, ConsoleProviderConfigSchema, type DndConfig, DndConfigSchema, HaiReachError, type ProviderConfig, ProviderConfigSchema, type ReachChannel, type ReachConfig, type ReachConfigInput, ReachConfigSchema, type ReachDeadRequeue, ReachDeadRequeueSchema, type ReachFunctions, type ReachGatewayHook, type ReachInitOptions, type ReachMessage, type ReachQueueConfig, ReachQueueConfigSchema, type ReachQueueEntry, type ReachQueueFailure, ReachQueueIdSchema, type ReachQueueListOptions, ReachQueueListSchema, type ReachQueueOperations, type ReachQueueStatus, type ReachTemplate, type ReachTemplateRegistry, type ReachUnknownResolution, ReachUnknownResolutionSchema, type RenderedTemplate, type SendOperations, type SendResult, type SmtpProviderConfig, SmtpProviderConfigSchema, type TemplateConfig, TemplateConfigSchema, migrateReach, reach };

package/dist/index.js

@@ -3,6 +3,7 @@ import { core, err, ok } from '@h-ai/core';
 import process from 'process';
 import { reldb, migrateSchema, schemaColumns, BaseReldbCrudRepository } from '@h-ai/reldb';
 import { randomUUID, createHash, createHmac } from 'crypto';
+import { addAbortListener } from 'events';
 import { createRequire } from 'module';
 import { cache } from '@h-ai/cache';
 
@@ -30,6 +31,11 @@ var en_US_default = {
   reach_queueInputInvalid: "Invalid queue receipt or manual resolution parameters",
   reach_deliveryUnknown: "The external delivery outcome is unknown; manual review is required and automatic redelivery has stopped",
   reach_smsSendFailed: "SMS send failed: {error}",
+  reach_smsGatewayFailed: "The SMS gateway request failed or timed out. Delivery is unconfirmed",
+  reach_gatewayUrlInvalid: "Use a full HTTPS gateway URL without credentials, a query, or a fragment. For HTTP on a trusted private network, explicitly enable allowInsecureHttp",
+  reach_gatewayHeadersInvalid: "Gateway headers are invalid or include a header managed by the HTTP client",
+  reach_gatewayBodyInvalid: "The gateway request body must be a JSON object, an array, or text",
+  reach_gatewayHookInvalid: "Gateway hooks must be bound to an SMS provider with a gateway configured",
   reach_emailSendFailed: "Email send failed: {error}",
   reach_apiSendFailed: "API callback send failed: {error}",
   reach_configError: "Reach config validation failed: {error}",
@@ -83,6 +89,11 @@ var ja_JP_default = {
   reach_queueInputInvalid: "\u30AD\u30E5\u30FC\u306E\u53D7\u9818\u8A18\u9332\u307E\u305F\u306F\u624B\u52D5\u89E3\u6C7A\u306E\u30D1\u30E9\u30E1\u30FC\u30BF\u30FC\u304C\u7121\u52B9\u3067\u3059",
   reach_deliveryUnknown: "\u5916\u90E8\u3078\u306E\u914D\u4FE1\u7D50\u679C\u306F\u4E0D\u660E\u3067\u3059\u3002\u624B\u52D5\u78BA\u8A8D\u304C\u5FC5\u8981\u306A\u305F\u3081\u3001\u81EA\u52D5\u518D\u914D\u4FE1\u3092\u505C\u6B62\u3057\u307E\u3057\u305F",
   reach_smsSendFailed: "SMS\u306E\u9001\u4FE1\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
+  reach_smsGatewayFailed: "SMS \u30B2\u30FC\u30C8\u30A6\u30A7\u30A4\u3078\u306E\u30EA\u30AF\u30A8\u30B9\u30C8\u304C\u5931\u6557\u307E\u305F\u306F\u30BF\u30A4\u30E0\u30A2\u30A6\u30C8\u3057\u3001\u914D\u4FE1\u3092\u78BA\u8A8D\u3067\u304D\u307E\u305B\u3093\u3067\u3057\u305F",
+  reach_gatewayUrlInvalid: "\u30B2\u30FC\u30C8\u30A6\u30A7\u30A4\u306B\u306F\u8A8D\u8A3C\u60C5\u5831\u3001\u30AF\u30A8\u30EA\u3001\u30D5\u30E9\u30B0\u30E1\u30F3\u30C8\u3092\u542B\u307E\u306A\u3044\u5B8C\u5168\u306A HTTPS URL \u3092\u6307\u5B9A\u3057\u3066\u304F\u3060\u3055\u3044\u3002\u4FE1\u983C\u3067\u304D\u308B\u5185\u90E8\u30CD\u30C3\u30C8\u30EF\u30FC\u30AF\u3067 HTTP \u3092\u4F7F\u7528\u3059\u308B\u5834\u5408\u306F allowInsecureHttp \u3092\u660E\u793A\u7684\u306B\u6709\u52B9\u306B\u3057\u3066\u304F\u3060\u3055\u3044",
+  reach_gatewayHeadersInvalid: "\u30B2\u30FC\u30C8\u30A6\u30A7\u30A4\u306E\u30EA\u30AF\u30A8\u30B9\u30C8\u30D8\u30C3\u30C0\u30FC\u304C\u7121\u52B9\u304B\u3001HTTP \u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u304C\u7BA1\u7406\u3059\u308B\u30D8\u30C3\u30C0\u30FC\u304C\u542B\u307E\u308C\u3066\u3044\u307E\u3059",
+  reach_gatewayBodyInvalid: "\u30B2\u30FC\u30C8\u30A6\u30A7\u30A4\u306E\u30EA\u30AF\u30A8\u30B9\u30C8\u30DC\u30C7\u30A3\u306B\u306F JSON \u30AA\u30D6\u30B8\u30A7\u30AF\u30C8\u3001\u914D\u5217\u3001\u307E\u305F\u306F\u30C6\u30AD\u30B9\u30C8\u3092\u6307\u5B9A\u3057\u3066\u304F\u3060\u3055\u3044",
+  reach_gatewayHookInvalid: "\u30B2\u30FC\u30C8\u30A6\u30A7\u30A4\u306E\u30D5\u30C3\u30AF\u306F\u3001\u30B2\u30FC\u30C8\u30A6\u30A7\u30A4\u3092\u8A2D\u5B9A\u3057\u305F SMS Provider \u306B\u5272\u308A\u5F53\u3066\u3066\u304F\u3060\u3055\u3044",
   reach_emailSendFailed: "\u30E1\u30FC\u30EB\u306E\u9001\u4FE1\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
   reach_apiSendFailed: "API\u30B3\u30FC\u30EB\u30D0\u30C3\u30AF\u306E\u9001\u4FE1\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
   reach_configError: "\u901A\u77E5\u8A2D\u5B9A\u306E\u691C\u8A3C\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
@@ -136,6 +147,11 @@ var zh_CN_default = {
   reach_queueInputInvalid: "\u961F\u5217\u56DE\u6267\u6216\u4EBA\u5DE5\u88C1\u5B9A\u53C2\u6570\u65E0\u6548",
   reach_deliveryUnknown: "\u5916\u90E8\u6295\u9012\u7ED3\u679C\u672A\u77E5\uFF0C\u9700\u8981\u4EBA\u5DE5\u6838\u5BF9\uFF0C\u5DF2\u505C\u6B62\u81EA\u52A8\u91CD\u53D1",
   reach_smsSendFailed: "\u77ED\u4FE1\u53D1\u9001\u5931\u8D25: {error}",
+  reach_smsGatewayFailed: "\u77ED\u4FE1\u7F51\u5173\u8BF7\u6C42\u5931\u8D25\u6216\u8D85\u65F6\uFF0C\u6295\u9012\u7ED3\u679C\u672A\u786E\u8BA4",
+  reach_gatewayUrlInvalid: "\u7F51\u5173\u987B\u4F7F\u7528\u5B8C\u6574\u7684 HTTPS URL\uFF0C\u4E14\u4E0D\u80FD\u5305\u542B\u51ED\u636E\u3001\u67E5\u8BE2\u53C2\u6570\u6216\u7247\u6BB5\u3002\u53D7\u4FE1\u5185\u7F51\u4F7F\u7528 HTTP \u65F6\u987B\u663E\u5F0F\u542F\u7528 allowInsecureHttp",
+  reach_gatewayHeadersInvalid: "\u7F51\u5173\u8BF7\u6C42\u5934\u683C\u5F0F\u65E0\u6548\uFF0C\u6216\u5305\u542B\u7531 HTTP \u5BA2\u6237\u7AEF\u7BA1\u7406\u7684\u8BF7\u6C42\u5934",
+  reach_gatewayBodyInvalid: "\u7F51\u5173\u8BF7\u6C42\u4F53\u5FC5\u987B\u662F JSON \u5BF9\u8C61\u3001\u6570\u7EC4\u6216\u6587\u672C",
+  reach_gatewayHookInvalid: "\u7F51\u5173\u51FD\u6570\u5FC5\u987B\u7ED1\u5B9A\u5230\u542F\u7528\u4E86\u7F51\u5173\u7684\u77ED\u4FE1 Provider",
   reach_emailSendFailed: "\u90AE\u4EF6\u53D1\u9001\u5931\u8D25: {error}",
   reach_apiSendFailed: "API \u56DE\u8C03\u53D1\u9001\u5931\u8D25: {error}",
   reach_configError: "\u89E6\u8FBE\u914D\u7F6E\u6821\u9A8C\u5931\u8D25\uFF1A{error}",
@@ -174,6 +190,33 @@ var reachM = core.i18n.createMessageGetter({
   "ja-JP": ja_JP_default
 });
 
+// src/reach-gateway-config.ts
+var transportHeader = /^(?:connection|content-length|host|keep-alive|proxy-connection|te|trailer|transfer-encoding|upgrade)$/i;
+var jsonValue = z.json();
+var gatewayFields = {
+  /** 网关自定义请求头；连接与消息长度相关的头由 HTTP 客户端管理。 */
+  headers: z.record(z.string(), z.string()).refine((headers) => {
+    try {
+      return [...new Headers(headers).keys()].every((name) => !transportHeader.test(name));
+    } catch {
+      return false;
+    }
+  }, reachM("reach_gatewayHeadersInvalid")).optional(),
+  /** 网关请求体；对象和数组序列化为 JSON，字符串原样发送。省略时不发请求体。 */
+  body: z.union([z.string(), z.array(jsonValue), z.record(z.string(), jsonValue)], reachM("reach_gatewayBodyInvalid")).optional()
+};
+var ReachGatewayFieldsSchema = z.strictObject(gatewayFields);
+var ReachGatewayConfigSchema = z.strictObject({
+  /** 网关的完整 HTTP(S) URL；包含路径，不允许凭据、查询参数或片段。 */
+  url: z.url(reachM("reach_gatewayUrlInvalid")),
+  /** 仅在受信内网显式允许明文 HTTP。 */
+  allowInsecureHttp: z.boolean().default(false),
+  ...gatewayFields
+}).refine(({ url, allowInsecureHttp }) => {
+  const target = URL.parse(url);
+  return target !== null && /^https?:\/\//i.test(url) && !/[?#]/.test(url) && !target.username && !target.password && (target.protocol === "https:" || target.protocol === "http:" && allowInsecureHttp);
+}, { path: ["url"], message: reachM("reach_gatewayUrlInvalid") });
+
 // src/reach-config.ts
 var ConsoleProviderConfigSchema = z.object({
   /** Provider 唯一名称 */
@@ -207,8 +250,10 @@ var AliyunSmsProviderConfigSchema = z.object({
   accessKeySecret: z.string().min(1, reachM("reach_config_accessKeySecretRequired")),
   /** 短信签名 */
   signName: z.string().min(1, reachM("reach_config_signNameRequired")),
-  /** API 端点（默认 dysmsapi.aliyuncs.com） */
-  endpoint: z.string().default("dysmsapi.aliyuncs.com")
+  /** 直连 API 端点（默认 dysmsapi.aliyuncs.com）；配置网关时使用网关 URL。 */
+  endpoint: z.string().default("dysmsapi.aliyuncs.com"),
+  /** 可选的短信隔离网关，以 POST 请求转发已签名的查询参数。 */
+  gateway: ReachGatewayConfigSchema.optional()
 });
 var ApiProviderConfigSchema = z.object({
   /** Provider 唯一名称 */
@@ -308,6 +353,9 @@ var HaiReachError = core.error.buildHaiErrorsDef("reach", ReachErrorInfo);
 // src/providers/reach-provider-aliyun-sms.ts
 var logger = core.logger.child({ module: "reach", scope: "provider-aliyun-sms" });
 var ISO_MILLISECONDS_SUFFIX_REGEX = /\.\d{3}Z$/;
+var RFC3986_RESERVED_CHARACTERS_REGEX = /[!'()*]/g;
+var GATEWAY_TIMEOUT_MS = 1e4;
+var GATEWAY_RESPONSE_LIMIT_BYTES = 64 * 1024;
 function toReachError(error) {
   return {
     code: HaiReachError.SEND_FAILED.code,
@@ -318,7 +366,7 @@ function toReachError(error) {
   };
 }
 function percentEncode(str) {
-  return encodeURIComponent(str).replace(/\+/g, "%20").replace(/\*/g, "%2A").replace(/~/g, "%7E");
+  return encodeURIComponent(str).replace(RFC3986_RESERVED_CHARACTERS_REGEX, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
 }
 function signRequest(params, accessKeySecret, method) {
   const sortedKeys = Object.keys(params).sort();
@@ -328,7 +376,58 @@ function signRequest(params, accessKeySecret, method) {
   hmac.update(stringToSign);
   return hmac.digest("base64");
 }
-function createAliyunSmsProvider() {
+async function prepareGatewayRequest(gateway, url, signal, hook) {
+  let body = gateway.body;
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(gateway.headers ?? {}))
+    headers.set(name, value);
+  if (hook) {
+    signal.throwIfAborted();
+    let listener;
+    const aborted = new Promise((_resolve, reject) => {
+      listener = addAbortListener(signal, () => reject(signal.reason));
+    });
+    try {
+      const output = await Promise.race([
+        Promise.resolve().then(() => hook({ method: "POST", url, body: typeof body === "string" ? body : JSON.stringify(body), signal })),
+        aborted
+      ]);
+      const patch = ReachGatewayFieldsSchema.parse(output === void 0 ? {} : output);
+      body = patch.body ?? body;
+      for (const [name, value] of Object.entries(patch.headers ?? {}))
+        headers.set(name, value);
+    } finally {
+      listener?.[Symbol.dispose]();
+    }
+  }
+  if (body !== void 0 && !headers.has("Content-Type"))
+    headers.set("Content-Type", typeof body === "string" ? "text/plain; charset=utf-8" : "application/json");
+  return { method: "POST", headers, body: typeof body === "string" ? body : JSON.stringify(body), redirect: "error", signal };
+}
+async function readGatewayResponse(response) {
+  if (response.ok && response.body) {
+    let bytes = 0;
+    const stream = response.body.pipeThrough(new TransformStream({
+      transform(chunk, controller) {
+        bytes += chunk.byteLength;
+        if (bytes > GATEWAY_RESPONSE_LIMIT_BYTES)
+          throw new Error("SMS gateway response exceeded the size limit");
+        controller.enqueue(chunk);
+      }
+    }));
+    const body = await new Response(stream).json();
+    if (body && typeof body === "object" && "Code" in body && body.Code === "OK") {
+      const messageId = "BizId" in body ? body.BizId : void 0;
+      if (messageId === void 0 || typeof messageId === "string" && messageId.length <= 255)
+        return ok({ success: true, messageId });
+    }
+  } else {
+    await response.body?.cancel();
+  }
+  logger.warn("SMS gateway returned an unsuccessful receipt", { status: response.status });
+  return err(HaiReachError.SEND_FAILED, reachM("reach_smsGatewayFailed"));
+}
+function createAliyunSmsProvider(gatewayHook) {
   let smsConfig = null;
   return {
     name: "aliyun-sms",
@@ -341,7 +440,7 @@ function createAliyunSmsProvider() {
         );
       }
       smsConfig = config;
-      logger.info("Aliyun SMS provider connected", { endpoint: config.endpoint });
+      logger.info("Aliyun SMS provider connected", config.gateway ? { gateway: true } : { endpoint: config.endpoint });
       return ok(void 0);
     },
     async close() {
@@ -352,21 +451,23 @@ function createAliyunSmsProvider() {
       return smsConfig !== null;
     },
     async send(message) {
-      if (!smsConfig) {
+      const config = smsConfig;
+      if (!config) {
         return err(
           HaiReachError.NOT_INITIALIZED,
           reachM("reach_notInitialized")
         );
       }
       const templateCode = message.extra?.templateCode;
-      logger.debug("Sending SMS", { to: message.to, templateCode });
+      if (!config.gateway)
+        logger.debug("Sending SMS", { to: message.to, templateCode });
       try {
         const params = {
-          AccessKeyId: smsConfig.accessKeyId,
+          AccessKeyId: config.accessKeyId,
           Action: "SendSms",
           Format: "JSON",
           PhoneNumbers: message.to,
-          SignName: smsConfig.signName,
+          SignName: config.signName,
           SignatureMethod: "HMAC-SHA1",
           SignatureNonce: randomUUID(),
           SignatureVersion: "1.0",
@@ -377,13 +478,25 @@ function createAliyunSmsProvider() {
         if (message.vars) {
           params.TemplateParam = JSON.stringify(message.vars);
         }
-        params.Signature = signRequest(params, smsConfig.accessKeySecret, "GET");
+        params.Signature = signRequest(params, config.accessKeySecret, config.gateway ? "POST" : "GET");
         const queryString = Object.entries(params).map(([k, v]) => `${percentEncode(k)}=${percentEncode(v)}`).join("&");
-        const url = `https://${smsConfig.endpoint}/?${queryString}`;
+        if (config.gateway) {
+          const deadline = performance.now() + GATEWAY_TIMEOUT_MS;
+          const signal = AbortSignal.timeout(GATEWAY_TIMEOUT_MS);
+          const url2 = `${new URL(config.gateway.url).href}?${queryString}`;
+          const request = await prepareGatewayRequest(config.gateway, url2, signal, gatewayHook);
+          signal.throwIfAborted();
+          if (smsConfig !== config || performance.now() >= deadline)
+            return err(HaiReachError.SEND_FAILED, reachM("reach_smsGatewayFailed"));
+          if (message.sensitive && message.expiresAt !== void 0 && Date.now() >= message.expiresAt)
+            return err(HaiReachError.MESSAGE_EXPIRED, reachM("reach_messageExpired"));
+          return await readGatewayResponse(await fetch(url2, request));
+        }
+        const url = `https://${config.endpoint}/?${queryString}`;
         const response = await fetch(url);
         const body = await response.json();
         if (body.Code !== "OK") {
-          logger.warn("SMS send returned non-OK status", { code: body.Code, message: body.Message });
+          logger.warn("SMS send returned non-OK status", { code: body.Code });
           return err(
             HaiReachError.SEND_FAILED,
             reachM("reach_smsSendFailed", { params: { error: body.Message } })
@@ -392,6 +505,10 @@ function createAliyunSmsProvider() {
         logger.info("SMS sent", { to: message.to, bizId: body.BizId });
         return ok({ success: true, messageId: body.BizId });
       } catch (error) {
+        if (config.gateway) {
+          logger.warn("SMS gateway request failed");
+          return err(HaiReachError.SEND_FAILED, reachM("reach_smsGatewayFailed"));
+        }
         logger.error("SMS send failed", { to: message.to, error });
         return err(toReachError(error));
       }
@@ -1970,14 +2087,14 @@ var templateRepo = null;
 var initInProgress = false;
 var initCompletion = null;
 var closeInProgress = null;
-function createProvider(config) {
+function createProvider(config, gatewayHook) {
   switch (config.type) {
     case "console":
       return createConsoleProvider();
     case "smtp":
       return createSmtpProvider();
     case "aliyun-sms":
-      return createAliyunSmsProvider();
+      return createAliyunSmsProvider(gatewayHook);
     case "api":
       return createApiProvider();
   }
@@ -2047,7 +2164,7 @@ async function doClose() {
   resetSendState();
   logger7.info("Reach module closed");
 }
-async function doInit(config) {
+async function doInit(config, options) {
   if (providers.size > 0) {
     logger7.warn("Reach module is already initialized, reinitializing");
     await doClose();
@@ -2063,6 +2180,11 @@ async function doInit(config) {
     );
   }
   const parsed = parseResult.data;
+  const gatewayHooks = new Map(Object.entries(options?.gatewayHooks ?? {}));
+  for (const [name, hook] of gatewayHooks) {
+    if (typeof hook !== "function" || !parsed.providers.some((provider) => provider.name === name && provider.type === "aliyun-sms" && provider.gateway))
+      return err(HaiReachError.CONFIG_ERROR, reachM("reach_gatewayHookInvalid"));
+  }
   if (core.module.requiresSharedState(process.env) && parsed.providers.some((provider) => provider.type === "console"))
     return err(HaiReachError.CONFIG_ERROR, reachM("reach_productionProviderRequired"));
   try {
@@ -2077,7 +2199,7 @@ async function doInit(config) {
     }
     const newProviders = /* @__PURE__ */ new Map();
     for (const providerConfig of parsed.providers) {
-      const provider = createProvider(providerConfig);
+      const provider = createProvider(providerConfig, gatewayHooks.get(providerConfig.name));
       const connectResult = await provider.connect(providerConfig);
       if (!connectResult.success) {
         logger7.error("Provider initialization failed", {
@@ -2193,7 +2315,7 @@ var reach = {
       return sendLogRepo.resolveUnknown(queueId, parsed.data);
     }
   },
-  async init(config) {
+  async init(config, options) {
     if (initInProgress || closeInProgress) {
       logger7.warn("Reach module init already in progress, skipping");
       return err(
@@ -2203,7 +2325,7 @@ var reach = {
     }
     initInProgress = true;
     try {
-      initCompletion = doInit(config);
+      initCompletion = doInit(config, options);
       return await initCompletion;
     } finally {
       initInProgress = false;
@@ -2221,7 +2343,15 @@ var reach = {
     return templateRegistry;
   },
   get config() {
-    return currentConfig ? core.sanitize.sanitizeSensitiveFields(currentConfig) : null;
+    if (!currentConfig)
+      return null;
+    const safeProviders = currentConfig.providers.map((provider) => {
+      if (provider.type !== "aliyun-sms" || !provider.gateway)
+        return provider;
+      const { url, allowInsecureHttp } = provider.gateway;
+      return { ...provider, gateway: { url, allowInsecureHttp } };
+    });
+    return core.sanitize.sanitizeSensitiveFields({ ...currentConfig, providers: safeProviders });
   },
   get isInitialized() {
     return providers.size > 0;