@evomap/evolver-adapter-public 2.0.30 → 2.0.32

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/dist/connect.d.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  import type { hub } from '@evomap/evolver-core';
2
2
  import { PublicHubCapability } from './hubCapability.js';
3
3
  import type { AntiAbuseTelemetryOptions } from './antiAbuseTelemetry.js';
4
+ import type { MalformedPublishReceiptEvent } from './hubCapability.js';
4
5
  import { type FetchLike } from './hubFetch.js';
5
6
  import { type OAuthTransport } from './auth/oauthDeviceToken.js';
6
7
  export type AuthMode = 'oauth' | 'keypair' | 'legacy';
@@ -32,6 +33,8 @@ export interface ConnectPublicOptions {
32
33
  }>;
33
34
  /** Optional anti-abuse metadata context for heartbeat payloads. */
34
35
  antiAbuse?: AntiAbuseTelemetryOptions;
36
+ /** Optional non-sensitive notification when publish returns malformed 2xx JSON. */
37
+ onMalformedPublishReceipt?: (event: MalformedPublishReceiptEvent) => void;
35
38
  }
36
39
  /** 选址装配公版 hub(M6-7): 按 authMode 组 AuthProvider(M6-5) + PublicHubCapability(M6-6). */
37
40
  export declare function connectPublicHub(opts: ConnectPublicOptions): {
package/dist/connect.js CHANGED
@@ -35,7 +35,17 @@ export function connectPublicHub(opts) {
35
35
  throw new Error(`未知 authMode: ${String(_x)}`);
36
36
  }
37
37
  }
38
- return { hub: new PublicHubCapability({ baseUrl: opts.hubUrl, auth, fetchFn, senderId: opts.senderId, antiAbuse: withWorkspaceIdResolver(opts.antiAbuse) }), auth };
38
+ return {
39
+ hub: new PublicHubCapability({
40
+ baseUrl: opts.hubUrl,
41
+ auth,
42
+ fetchFn,
43
+ senderId: opts.senderId,
44
+ antiAbuse: withWorkspaceIdResolver(opts.antiAbuse),
45
+ ...(opts.onMalformedPublishReceipt ? { onMalformedPublishReceipt: opts.onMalformedPublishReceipt } : {}),
46
+ }),
47
+ auth,
48
+ };
39
49
  }
40
50
  function withWorkspaceIdResolver(antiAbuse) {
41
51
  if (antiAbuse?.workspaceId || antiAbuse?.workspaceIdResolver)
@@ -65,6 +65,10 @@ export declare class MalformedAccountAssetPageError extends Error {
65
65
  export declare function gepEnvelope(messageType: string, payload: unknown, options?: {
66
66
  messageId?: string;
67
67
  }): Record<string, unknown>;
68
+ export interface MalformedPublishReceiptEvent {
69
+ httpStatus: number;
70
+ occurredAt: number;
71
+ }
68
72
  export interface PublicHubOptions {
69
73
  baseUrl: string;
70
74
  auth: hub.AuthProvider;
@@ -74,6 +78,8 @@ export interface PublicHubOptions {
74
78
  subscribePollMs?: number;
75
79
  /** Public Hub anti-abuse heartbeat metadata. Defaults to env-controlled heartbeat mode. */
76
80
  antiAbuse?: AntiAbuseTelemetryOptions;
81
+ /** Best-effort notification for malformed 2xx publish responses; receives no Hub body or credential data. */
82
+ onMalformedPublishReceipt?: (event: MalformedPublishReceiptEvent) => void;
77
83
  }
78
84
  export interface PublicHelloResult {
79
85
  ok: boolean;
@@ -142,6 +148,9 @@ export declare function outboundMaxBodyBytes(env?: Record<string, string | undef
142
148
  export declare class PublicHubCapability implements hub.HubCapability {
143
149
  private readonly opts;
144
150
  private readonly http;
151
+ private malformedPublish2xxCount;
152
+ private lastMalformedPublish2xxAt;
153
+ private lastMalformedPublish2xxStatus;
145
154
  readonly auth: hub.AuthProvider;
146
155
  readonly recipes: hub.RecipeCapability;
147
156
  constructor(opts: PublicHubOptions);
@@ -151,6 +160,8 @@ export declare class PublicHubCapability implements hub.HubCapability {
151
160
  heartbeat(opts?: PublicHeartbeatOptions): Promise<PublicHeartbeatResult>;
152
161
  private heartbeatMeta;
153
162
  publish(bundle: hub.AssetRecord[], options?: hub.PublishOptions): Promise<hub.PublishReceipt>;
163
+ publishDiagnostics(): hub.PublishReceiptDiagnostics;
164
+ private recordMalformedPublishReceipt;
154
165
  fetch(query: hub.HubQuery): Promise<hub.AssetRecord[]>;
155
166
  /**
156
167
  * Fetch one asset AND say why, when the answer is not an asset. `fetchAssetById` collapses every outcome to
@@ -97,6 +97,9 @@ function traceOutboundMaxBodyBytes(env = process.env) {
97
97
  export class PublicHubCapability {
98
98
  opts;
99
99
  http;
100
+ malformedPublish2xxCount = 0;
101
+ lastMalformedPublish2xxAt;
102
+ lastMalformedPublish2xxStatus;
100
103
  auth;
101
104
  recipes = {
102
105
  create: async (request) => this.createRecipe(request),
@@ -272,15 +275,38 @@ export class PublicHubCapability {
272
275
  ? stablePublishMessageId(idempotencyKey)
273
276
  : undefined;
274
277
  const body = await this.http.call('POST', '/a2a/publish', gepEnvelope('publish', { assets: bundle }, messageId ? { messageId } : {}));
275
- return publishRespToReceipt(200, body);
278
+ const receipt = publishRespToReceipt(200, body);
279
+ if (receipt.rejection?.code === 'invalid_payload')
280
+ this.recordMalformedPublishReceipt(200);
281
+ return receipt;
276
282
  }
277
283
  catch (e) {
278
284
  if (e instanceof HubClientError) {
279
- return publishRespToReceipt(e.status, e.body ?? {}, e.retryAfterMs);
285
+ const receipt = publishRespToReceipt(e.status, e.body ?? {}, e.retryAfterMs);
286
+ return receipt;
280
287
  }
281
288
  throw e; // 5xx/网络 → 重试
282
289
  }
283
290
  }
291
+ publishDiagnostics() {
292
+ return {
293
+ malformed2xxCount: this.malformedPublish2xxCount,
294
+ ...(this.lastMalformedPublish2xxAt !== undefined ? { lastMalformed2xxAt: this.lastMalformedPublish2xxAt } : {}),
295
+ ...(this.lastMalformedPublish2xxStatus !== undefined ? { lastMalformed2xxStatus: this.lastMalformedPublish2xxStatus } : {}),
296
+ };
297
+ }
298
+ recordMalformedPublishReceipt(httpStatus) {
299
+ const occurredAt = Date.now();
300
+ this.malformedPublish2xxCount += 1;
301
+ this.lastMalformedPublish2xxAt = occurredAt;
302
+ this.lastMalformedPublish2xxStatus = httpStatus;
303
+ try {
304
+ this.opts.onMalformedPublishReceipt?.({ httpStatus, occurredAt });
305
+ }
306
+ catch {
307
+ // Observability must never change publish outcome or retry behavior.
308
+ }
309
+ }
284
310
  async fetch(query) {
285
311
  // #69: map camelCase SearchQuery → hub snake_case wire (signalsAny → signals) before sending.
286
312
  // /a2a/fetch responses are FULL GEP envelopes (buildResponse('fetch', …)); the rows live at payload.results,
package/dist/wireMap.d.ts CHANGED
@@ -26,5 +26,5 @@ export type AtpRetryClass = 'permanent' | 'cooldown' | 'recoverable';
26
26
  * cooldown → backoff, recoverable → retry next tick. Same map, different retry policy per caller.
27
27
  */
28
28
  export declare function atpRetryClass(status: number): AtpRetryClass;
29
- /** /a2a/publish 响应 → PublishReceipt. 200=accepted; 402/4xx=rejected 终态. */
29
+ /** /a2a/publish 响应 → PublishReceipt. 2xx 必须包含显式成功/拒绝决议;缺失或畸形回执 fail closed. */
30
30
  export declare function publishRespToReceipt(status: number, body: Record<string, unknown>, retryAfterMs?: number): hub.PublishReceipt;
package/dist/wireMap.js CHANGED
@@ -64,29 +64,62 @@ export function atpRetryClass(status) {
64
64
  return 'cooldown';
65
65
  return 'recoverable';
66
66
  }
67
- /** /a2a/publish 响应 → PublishReceipt. 200=accepted; 402/4xx=rejected 终态. */
67
+ /** /a2a/publish 响应 → PublishReceipt. 2xx 必须包含显式成功/拒绝决议;缺失或畸形回执 fail closed. */
68
68
  export function publishRespToReceipt(status, body, retryAfterMs) {
69
- const payload = body['payload'] ?? body;
70
- const assetIds = payload['asset_ids'];
71
- const targetAssetId = payload['target_asset_id']
72
- ?? body['target_asset_id'];
69
+ const bodyRecord = isRecord(body) ? body : {};
70
+ const rawPayload = bodyRecord['payload'];
71
+ const malformedPayload = rawPayload !== undefined && !isRecord(rawPayload);
72
+ const payload = isRecord(rawPayload) ? rawPayload : bodyRecord;
73
+ const rawAssetIds = payload['asset_ids'];
74
+ const malformedAssetIds = rawAssetIds !== undefined
75
+ && (!Array.isArray(rawAssetIds) || rawAssetIds.some((value) => typeof value !== 'string'));
76
+ const assetIds = !malformedAssetIds && Array.isArray(rawAssetIds) ? rawAssetIds : undefined;
77
+ const targetAssetId = stringField(payload, 'target_asset_id') ?? stringField(bodyRecord, 'target_asset_id');
73
78
  const assetId = (status === 409 ? targetAssetId : undefined)
74
- ?? payload['asset_id']
75
- ?? body['asset_id']
79
+ ?? stringField(payload, 'asset_id')
80
+ ?? stringField(bodyRecord, 'asset_id')
76
81
  ?? assetIds?.[0]
77
82
  ?? targetAssetId;
78
- const bundleId = payload['bundle_id'];
83
+ const bundleId = stringField(payload, 'bundle_id');
84
+ const receiptId = nonBlankString(payload['receipt_id']);
85
+ const hasDecisionField = Object.prototype.hasOwnProperty.call(payload, 'decision');
86
+ const hasStatusField = Object.prototype.hasOwnProperty.call(payload, 'status');
87
+ const explicitDecision = explicitPublishDecision(payload['decision']);
88
+ const explicitStatus = explicitPublishDecision(payload['status']);
89
+ const decision = explicitDecision ?? explicitStatus;
90
+ const invalidDecisionField = (hasDecisionField && explicitDecision === undefined)
91
+ || (hasStatusField && explicitStatus === undefined);
92
+ const accepted = decision === 'accepted';
93
+ const contradictory = hasDecisionField
94
+ && hasStatusField
95
+ && (explicitDecision === undefined || explicitStatus === undefined || explicitDecision !== explicitStatus);
96
+ const explicitError = hasFieldWithValue(payload, 'error') || hasFieldWithValue(bodyRecord, 'error');
97
+ const explicitOkFalse = payload['ok'] === false || bodyRecord['ok'] === false;
79
98
  if (status >= 200 && status < 300) {
80
- const decision = String(payload['decision'] ?? payload['status'] ?? 'accepted');
81
- const accepted = decision === 'accept' || decision === 'accepted' || decision === 'approved' || decision === 'ok';
99
+ if (decision === undefined
100
+ || malformedPayload
101
+ || invalidDecisionField
102
+ || contradictory
103
+ || explicitError
104
+ || explicitOkFalse
105
+ || malformedAssetIds
106
+ || (accepted && receiptId === undefined)) {
107
+ return {
108
+ receiptId: receiptId ?? 'malformed_receipt',
109
+ status: 'rejected',
110
+ terminal: true,
111
+ reason: 'malformed publish receipt',
112
+ rejection: { code: 'invalid_payload' },
113
+ };
114
+ }
82
115
  return {
83
- receiptId: String(payload['receipt_id'] ?? bundleId ?? payload['id'] ?? assetId ?? 'unknown'),
84
- status: accepted ? 'accepted' : (decision === 'quarantine' ? 'quarantine' : 'rejected'),
116
+ receiptId: receiptId ?? 'rejected',
117
+ status: decision,
85
118
  ...(assetId ? { assetId } : {}),
86
119
  ...(bundleId ? { bundleId } : {}),
87
120
  ...(assetIds ? { assetIds } : {}),
88
- ...(payload['reason'] ? { reason: String(payload['reason']) } : {}),
89
- terminal: !accepted, // quarantine/rejected 终态不重试
121
+ ...(typeof payload['reason'] === 'string' && payload['reason'] ? { reason: payload['reason'] } : {}),
122
+ terminal: decision !== 'accepted', // quarantine/rejected 终态不重试
90
123
  };
91
124
  }
92
125
  // M8-1: 按语义而非纯状态码区分(都终态不重试 = money-safety: 不反复打经济端点).
@@ -102,9 +135,9 @@ export function publishRespToReceipt(status, body, retryAfterMs) {
102
135
  429: 'cooldown',
103
136
  };
104
137
  const receipt = {
105
- receiptId: String(payload['receipt_id'] ?? 'rejected'),
138
+ receiptId: receiptId ?? 'rejected',
106
139
  status: 'rejected',
107
- reason: String(payload['reason'] ?? reasonByStatus[status] ?? `hub ${status}`),
140
+ reason: nonBlankString(payload['reason']) ?? reasonByStatus[status] ?? `hub ${status}`,
108
141
  ...(assetId ? { assetId } : {}),
109
142
  ...(assetIds ? { assetIds } : {}),
110
143
  terminal: true,
@@ -122,4 +155,31 @@ export function publishRespToReceipt(status, body, retryAfterMs) {
122
155
  };
123
156
  }
124
157
  return receipt;
158
+ }
159
+ function isRecord(value) {
160
+ return value !== null && typeof value === 'object' && !Array.isArray(value);
161
+ }
162
+ function stringField(record, key) {
163
+ return typeof record[key] === 'string' ? record[key] : undefined;
164
+ }
165
+ function nonBlankString(value) {
166
+ if (typeof value !== 'string')
167
+ return undefined;
168
+ const valueTrimmed = value.trim();
169
+ return valueTrimmed.length > 0 ? valueTrimmed : undefined;
170
+ }
171
+ function hasFieldWithValue(record, key) {
172
+ return Object.prototype.hasOwnProperty.call(record, key) && record[key] !== undefined;
173
+ }
174
+ function explicitPublishDecision(value) {
175
+ if (typeof value !== 'string')
176
+ return undefined;
177
+ const normalized = value.trim();
178
+ if (normalized === 'accept' || normalized === 'accepted' || normalized === 'approved' || normalized === 'ok')
179
+ return 'accepted';
180
+ if (normalized === 'quarantine')
181
+ return 'quarantine';
182
+ if (normalized === 'reject' || normalized === 'rejected')
183
+ return 'rejected';
184
+ return undefined;
125
185
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@evomap/evolver-adapter-public",
3
- "version": "2.0.30",
3
+ "version": "2.0.32",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "engines": {
@@ -17,7 +17,7 @@
17
17
  },
18
18
  "dependencies": {
19
19
  "@evomap/atp-sdk": "^0.1.0",
20
- "@evomap/evolver-core": "2.0.30",
20
+ "@evomap/evolver-core": "2.0.32",
21
21
  "undici": "^6.27.0"
22
22
  },
23
23
  "optionalDependencies": {