feat: remediate HTTP API reliability and developer documentation

api/src/open-api/open-api.protocol.ts

@@ -0,0 +1,40 @@
+import { createHash, createHmac } from 'node:crypto';
+import { HttpException } from '@nestjs/common';
+
+/** v1 compatibility: an absent parsed body hashes as {}, never try alternate hashes. */
+export function openApiBodyHash(rawBody: Buffer | undefined, body: unknown) {
+  return createHash('sha256')
+    .update(rawBody ?? Buffer.from(JSON.stringify(body ?? {})))
+    .digest('hex');
+}
+
+export function openApiSignature(
+  secret: string,
+  method: string,
+  path: string,
+  timestamp: string,
+  nonce: string,
+  bodyHash: string,
+) {
+  return createHmac('sha256', secret)
+    .update([method.toUpperCase(), path.split('?')[0], timestamp, nonce, bodyHash].join('\n'))
+    .digest('hex');
+}
+
+export function publicOpenApiFailure(error: unknown) {
+  if (!(error instanceof HttpException) || error.getStatus() >= 500) {
+    return { status: 500, code: 'INTERNAL_ERROR', message: 'Internal server error' };
+  }
+  const value = error.getResponse();
+  const object = typeof value === 'object' && value ? (value as Record<string, unknown>) : {};
+  const message = object.message ?? value;
+  return {
+    status: error.getStatus(),
+    code: String(object.code ?? 'REQUEST_FAILED'),
+    message: Array.isArray(message) ? message.join('；') : String(message),
+  };
+}
+
+export function webhookJobId(deliveryId: string, attemptNo: number) {
+  return `webhook-${createHash('sha256').update(deliveryId).digest('hex')}-${attemptNo}`;
+}