@probemesh/sdk 0.1.0

package/dist/chunk-5Q3PDYIA.js

@@ -0,0 +1,657 @@
+import {
+  redactX402Secrets
+} from "./chunk-NYTV263W.js";
+import {
+  ProbeMeshError,
+  isProbeMeshError
+} from "./chunk-2ASMVLG4.js";
+
+// src/callAuditArtifact.ts
+import { createHash } from "crypto";
+var PROBEMESH_CALL_AUDIT_ARTIFACT_SCHEMA_VERSION = "probemesh.call-audit.v1";
+function createProbeMeshCallAuditArtifact(options) {
+  assertAuditArtifactOptions(options);
+  const requestHash = hashStableJson(options.request);
+  const status = options.response ? "completed" : "failed";
+  const callId = options.response?.callId ?? options.error?.callId;
+  const capability = options.response?.capability ?? options.error?.capability ?? options.request.capability;
+  const receiptRefs = cloneSerializable(
+    options.response?.receiptRefs ?? options.error?.receiptRefs ?? []
+  );
+  const safety = cloneSerializable(
+    options.response?.safety ?? options.error?.safety
+  );
+  const retrySafety = cloneSerializable(
+    options.retrySafety ?? options.response?.retrySafety ?? options.error?.retrySafety
+  );
+  const attempt = cloneSerializable(
+    options.attempt ?? options.response?.attempt ?? options.error?.attempt
+  );
+  const route = cloneSerializable(
+    options.route ?? options.response?.route ?? options.error?.route
+  );
+  const timeline = cloneSerializable(
+    options.timeline ?? options.response?.timeline ?? options.error?.timeline
+  );
+  const timelineSummary = summarizeTimeline(timeline);
+  const baseContent = sanitizeAuditOutput(
+    {
+      schemaVersion: PROBEMESH_CALL_AUDIT_ARTIFACT_SCHEMA_VERSION,
+      artifactId: options.artifactId ?? `call_audit_${callId ?? requestHash.slice(0, 16)}`,
+      generatedAt: options.generatedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+      status,
+      hashAlgorithm: "sha256",
+      call: {
+        callId,
+        capability,
+        status,
+        providerId: options.response?.provider.id ?? options.error?.provider,
+        errorCode: options.error?.code,
+        cost: cloneSerializable(options.response?.cost),
+        latencyMs: options.response?.latencyMs,
+        attempt
+      },
+      request: {
+        requestHash,
+        idempotencyKey: options.request.idempotencyKey
+      },
+      evidence: {
+        receiptSummary: summarizeAuditReceipts(receiptRefs),
+        receiptRefs,
+        safety,
+        retrySafety,
+        route,
+        timeline: timelineSummary
+      }
+    },
+    options.forbiddenOutputValues ?? []
+  );
+  const hashesWithoutArtifact = {
+    request: requestHash,
+    route: hashStableJson(baseContent.evidence.route ?? null),
+    timeline: hashStableJson(baseContent.evidence.timeline),
+    receipts: hashStableJson(baseContent.evidence.receiptRefs),
+    safety: hashStableJson(baseContent.evidence.safety ?? null),
+    retrySafety: hashStableJson(baseContent.evidence.retrySafety ?? null),
+    artifact: ""
+  };
+  const artifact = {
+    ...baseContent,
+    hashes: {
+      ...hashesWithoutArtifact,
+      artifact: hashArtifactContent({
+        ...baseContent,
+        hashes: hashesWithoutArtifact
+      })
+    }
+  };
+  assertProbeMeshCallAuditArtifact(artifact);
+  return artifact;
+}
+function validateProbeMeshCallAuditArtifact(artifact) {
+  const errors = [];
+  if (!isRecord(artifact)) {
+    return {
+      valid: false,
+      errors: [
+        {
+          path: "$",
+          message: "ProbeMesh call audit artifact must be an object."
+        }
+      ]
+    };
+  }
+  if (artifact.schemaVersion !== PROBEMESH_CALL_AUDIT_ARTIFACT_SCHEMA_VERSION) {
+    errors.push({
+      path: "schemaVersion",
+      message: `schemaVersion must be "${PROBEMESH_CALL_AUDIT_ARTIFACT_SCHEMA_VERSION}".`
+    });
+  }
+  validateNonEmptyString(artifact.artifactId, "artifactId", errors);
+  validateIsoTimestamp(artifact.generatedAt, "generatedAt", errors);
+  if (artifact.status !== "completed" && artifact.status !== "failed") {
+    errors.push({
+      path: "status",
+      message: 'status must be "completed" or "failed".'
+    });
+  }
+  if (artifact.hashAlgorithm !== "sha256") {
+    errors.push({
+      path: "hashAlgorithm",
+      message: 'hashAlgorithm must be "sha256".'
+    });
+  }
+  validateHashes(artifact.hashes, errors);
+  validateCallSummary(artifact.call, artifact.status, errors);
+  validateRequestProof(artifact.request, artifact.hashes, errors);
+  validateEvidence(artifact.evidence, errors);
+  if (errors.length === 0) {
+    const typedArtifact = artifact;
+    pushHashMismatch(
+      errors,
+      "hashes.route",
+      typedArtifact.hashes.route,
+      hashStableJson(typedArtifact.evidence.route ?? null)
+    );
+    pushHashMismatch(
+      errors,
+      "hashes.timeline",
+      typedArtifact.hashes.timeline,
+      hashStableJson(typedArtifact.evidence.timeline)
+    );
+    pushHashMismatch(
+      errors,
+      "hashes.receipts",
+      typedArtifact.hashes.receipts,
+      hashStableJson(typedArtifact.evidence.receiptRefs)
+    );
+    pushHashMismatch(
+      errors,
+      "hashes.safety",
+      typedArtifact.hashes.safety,
+      hashStableJson(typedArtifact.evidence.safety ?? null)
+    );
+    pushHashMismatch(
+      errors,
+      "hashes.retrySafety",
+      typedArtifact.hashes.retrySafety,
+      hashStableJson(typedArtifact.evidence.retrySafety ?? null)
+    );
+    pushHashMismatch(
+      errors,
+      "hashes.artifact",
+      typedArtifact.hashes.artifact,
+      hashArtifactContent(typedArtifact)
+    );
+  }
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+function assertProbeMeshCallAuditArtifact(artifact) {
+  const result = validateProbeMeshCallAuditArtifact(artifact);
+  if (result.valid) {
+    return;
+  }
+  throw new ProbeMeshError({
+    code: "invalid_request",
+    message: `Invalid ProbeMesh call audit artifact: ${formatValidationErrors(
+      result.errors
+    )}`
+  });
+}
+function formatProbeMeshCallAuditArtifact(artifact, options = {}) {
+  assertProbeMeshCallAuditArtifact(artifact);
+  if ((options.format ?? "json") === "markdown") {
+    return formatAuditArtifactMarkdown(artifact);
+  }
+  return JSON.stringify(artifact, null, 2);
+}
+function assertAuditArtifactOptions(options) {
+  if (!isRecord(options)) {
+    throw new ProbeMeshError({
+      code: "invalid_request",
+      message: "ProbeMesh call audit artifact options must be an object."
+    });
+  }
+  if (!isRecord(options.request)) {
+    throw new ProbeMeshError({
+      code: "invalid_request",
+      message: "ProbeMesh call audit artifact request must be an object."
+    });
+  }
+  if (typeof options.request.capability !== "string" || options.request.capability.length === 0) {
+    throw new ProbeMeshError({
+      code: "invalid_request",
+      message: "ProbeMesh call audit artifact request capability is required."
+    });
+  }
+  if (!("input" in options.request)) {
+    throw new ProbeMeshError({
+      code: "invalid_request",
+      message: "ProbeMesh call audit artifact request input is required for hashing."
+    });
+  }
+  if (options.response === void 0 && options.error === void 0 || options.response !== void 0 && options.error !== void 0) {
+    throw new ProbeMeshError({
+      code: "invalid_request",
+      message: "ProbeMesh call audit artifact requires exactly one response or error."
+    });
+  }
+  if (options.error !== void 0 && !isProbeMeshError(options.error)) {
+    throw new ProbeMeshError({
+      code: "invalid_request",
+      message: "ProbeMesh call audit artifact error must be a ProbeMeshError."
+    });
+  }
+  if (options.generatedAt !== void 0 && (typeof options.generatedAt !== "string" || Number.isNaN(Date.parse(options.generatedAt)))) {
+    throw new ProbeMeshError({
+      code: "invalid_request",
+      message: "ProbeMesh call audit artifact generatedAt must be an ISO timestamp."
+    });
+  }
+  if (options.artifactId !== void 0 && (typeof options.artifactId !== "string" || options.artifactId.length === 0)) {
+    throw new ProbeMeshError({
+      code: "invalid_request",
+      message: "ProbeMesh call audit artifact artifactId must be a non-empty string."
+    });
+  }
+  if (options.forbiddenOutputValues !== void 0 && (!Array.isArray(options.forbiddenOutputValues) || options.forbiddenOutputValues.some((value) => typeof value !== "string"))) {
+    throw new ProbeMeshError({
+      code: "invalid_request",
+      message: "ProbeMesh call audit artifact forbiddenOutputValues must be an array of strings."
+    });
+  }
+}
+function summarizeAuditReceipts(receiptRefs) {
+  const types = [];
+  const providers = [];
+  const byType = {};
+  for (const receiptRef of receiptRefs) {
+    if (!types.includes(receiptRef.type)) {
+      types.push(receiptRef.type);
+    }
+    if (!providers.includes(receiptRef.provider)) {
+      providers.push(receiptRef.provider);
+    }
+    byType[receiptRef.type] = (byType[receiptRef.type] ?? 0) + 1;
+  }
+  return {
+    total: receiptRefs.length,
+    types,
+    providers,
+    byType,
+    hasPaymentProof: receiptRefs.some(
+      (receiptRef) => receiptRef.type === "payment_proof"
+    ),
+    hasSettlementConfirmation: receiptRefs.some(
+      (receiptRef) => receiptRef.type === "settlement_confirmation"
+    ),
+    hasProviderDelivery: receiptRefs.some(
+      (receiptRef) => receiptRef.type === "provider_delivery"
+    )
+  };
+}
+function summarizeTimeline(timeline) {
+  if (!timeline) {
+    return {
+      eventTypes: [],
+      events: []
+    };
+  }
+  return {
+    routeId: timeline.routeId,
+    eventTypes: timeline.events.map((event) => event.type),
+    events: timeline.events.map((event) => ({
+      type: event.type,
+      timestamp: event.timestamp,
+      provider: event.provider,
+      status: event.status,
+      errorCode: event.errorCode,
+      receiptType: event.receiptRef?.type,
+      attestationBundleId: event.attestation?.bundleId
+    }))
+  };
+}
+function validateHashes(hashes, errors) {
+  if (!isRecord(hashes)) {
+    errors.push({
+      path: "hashes",
+      message: "hashes must be an object."
+    });
+    return;
+  }
+  for (const key of [
+    "request",
+    "route",
+    "timeline",
+    "receipts",
+    "safety",
+    "retrySafety",
+    "artifact"
+  ]) {
+    validateSha256String(hashes[key], `hashes.${key}`, errors);
+  }
+}
+function validateCallSummary(call, status, errors) {
+  if (!isRecord(call)) {
+    errors.push({
+      path: "call",
+      message: "call must be an object."
+    });
+    return;
+  }
+  validateNonEmptyString(call.capability, "call.capability", errors);
+  if (call.status !== status) {
+    errors.push({
+      path: "call.status",
+      message: "call.status must match artifact status."
+    });
+  }
+  if (call.callId !== void 0) {
+    validateNonEmptyString(call.callId, "call.callId", errors);
+  }
+  if (call.providerId !== void 0) {
+    validateNonEmptyString(call.providerId, "call.providerId", errors);
+  }
+  if (call.errorCode !== void 0 && (typeof call.errorCode !== "string" || call.errorCode.length === 0)) {
+    errors.push({
+      path: "call.errorCode",
+      message: "call.errorCode must be a non-empty string when provided."
+    });
+  }
+  if (call.latencyMs !== void 0 && (typeof call.latencyMs !== "number" || !Number.isFinite(call.latencyMs) || call.latencyMs < 0)) {
+    errors.push({
+      path: "call.latencyMs",
+      message: "call.latencyMs must be a non-negative finite number."
+    });
+  }
+}
+function validateRequestProof(request, hashes, errors) {
+  if (!isRecord(request)) {
+    errors.push({
+      path: "request",
+      message: "request must be an object."
+    });
+    return;
+  }
+  validateSha256String(request.requestHash, "request.requestHash", errors);
+  if (isRecord(hashes) && hashes.request !== request.requestHash) {
+    errors.push({
+      path: "hashes.request",
+      message: "hashes.request must equal request.requestHash."
+    });
+  }
+  if (request.idempotencyKey !== void 0) {
+    validateNonEmptyString(
+      request.idempotencyKey,
+      "request.idempotencyKey",
+      errors
+    );
+  }
+}
+function validateEvidence(evidence, errors) {
+  if (!isRecord(evidence)) {
+    errors.push({
+      path: "evidence",
+      message: "evidence must be an object."
+    });
+    return;
+  }
+  validateReceiptSummary(evidence.receiptSummary, errors);
+  validateReceiptRefs(evidence.receiptRefs, errors);
+  validateTimelineSummary(evidence.timeline, errors);
+}
+function validateReceiptSummary(summary, errors) {
+  if (!isRecord(summary)) {
+    errors.push({
+      path: "evidence.receiptSummary",
+      message: "evidence.receiptSummary must be an object."
+    });
+    return;
+  }
+  if (typeof summary.total !== "number" || !Number.isFinite(summary.total)) {
+    errors.push({
+      path: "evidence.receiptSummary.total",
+      message: "evidence.receiptSummary.total must be a number."
+    });
+  }
+  validateStringArray(summary.types, "evidence.receiptSummary.types", errors);
+  validateStringArray(
+    summary.providers,
+    "evidence.receiptSummary.providers",
+    errors
+  );
+  if (!isRecord(summary.byType)) {
+    errors.push({
+      path: "evidence.receiptSummary.byType",
+      message: "evidence.receiptSummary.byType must be an object."
+    });
+  }
+  for (const key of [
+    "hasPaymentProof",
+    "hasSettlementConfirmation",
+    "hasProviderDelivery"
+  ]) {
+    if (typeof summary[key] !== "boolean") {
+      errors.push({
+        path: `evidence.receiptSummary.${key}`,
+        message: `evidence.receiptSummary.${key} must be a boolean.`
+      });
+    }
+  }
+}
+function validateReceiptRefs(receiptRefs, errors) {
+  if (!Array.isArray(receiptRefs)) {
+    errors.push({
+      path: "evidence.receiptRefs",
+      message: "evidence.receiptRefs must be an array."
+    });
+    return;
+  }
+  receiptRefs.forEach((receiptRef, index) => {
+    if (!isRecord(receiptRef)) {
+      errors.push({
+        path: `evidence.receiptRefs.${index}`,
+        message: "receipt ref must be an object."
+      });
+      return;
+    }
+    for (const key of ["type", "provider", "status", "ref", "timestamp"]) {
+      validateNonEmptyString(
+        receiptRef[key],
+        `evidence.receiptRefs.${index}.${key}`,
+        errors
+      );
+    }
+  });
+}
+function validateTimelineSummary(timeline, errors) {
+  if (!isRecord(timeline)) {
+    errors.push({
+      path: "evidence.timeline",
+      message: "evidence.timeline must be an object."
+    });
+    return;
+  }
+  if (timeline.routeId !== void 0) {
+    validateNonEmptyString(timeline.routeId, "evidence.timeline.routeId", errors);
+  }
+  validateStringArray(
+    timeline.eventTypes,
+    "evidence.timeline.eventTypes",
+    errors
+  );
+  if (!Array.isArray(timeline.events)) {
+    errors.push({
+      path: "evidence.timeline.events",
+      message: "evidence.timeline.events must be an array."
+    });
+    return;
+  }
+  timeline.events.forEach((event, index) => {
+    if (!isRecord(event)) {
+      errors.push({
+        path: `evidence.timeline.events.${index}`,
+        message: "timeline event must be an object."
+      });
+      return;
+    }
+    validateNonEmptyString(
+      event.type,
+      `evidence.timeline.events.${index}.type`,
+      errors
+    );
+    validateIsoTimestamp(
+      event.timestamp,
+      `evidence.timeline.events.${index}.timestamp`,
+      errors
+    );
+  });
+}
+function hashArtifactContent(artifact) {
+  return hashStableJson({
+    ...artifact,
+    hashes: {
+      ...artifact.hashes,
+      artifact: ""
+    }
+  });
+}
+function pushHashMismatch(errors, path, expected, actual) {
+  if (expected === actual) {
+    return;
+  }
+  errors.push({
+    path,
+    message: `${path} does not match artifact content.`
+  });
+}
+function hashStableJson(value) {
+  return createHash("sha256").update(stableStringify(value)).digest("hex");
+}
+function stableStringify(value) {
+  return JSON.stringify(sortSerializable(value));
+}
+function sortSerializable(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortSerializable);
+  }
+  if (!isRecord(value)) {
+    return value;
+  }
+  return Object.fromEntries(
+    Object.keys(value).sort().filter((key) => value[key] !== void 0).map((key) => [key, sortSerializable(value[key])])
+  );
+}
+function sanitizeAuditOutput(value, forbiddenOutputValues) {
+  const forbiddenValues = forbiddenOutputValues.filter((entry) => entry.length > 0);
+  return redactX402Secrets(
+    replaceForbiddenValues(cloneSerializable(value), forbiddenValues)
+  );
+}
+function replaceForbiddenValues(value, forbiddenValues) {
+  if (typeof value === "string") {
+    return forbiddenValues.reduce(
+      (current, forbidden) => current.split(forbidden).join("[REDACTED]"),
+      value
+    );
+  }
+  if (value === null || typeof value !== "object" || value instanceof Date) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => replaceForbiddenValues(entry, forbiddenValues));
+  }
+  return Object.fromEntries(
+    Object.entries(value).map(([key, entry]) => [
+      key,
+      replaceForbiddenValues(entry, forbiddenValues)
+    ])
+  );
+}
+function cloneSerializable(value) {
+  if (value === void 0) {
+    return value;
+  }
+  return JSON.parse(JSON.stringify(value));
+}
+function formatAuditArtifactMarkdown(artifact) {
+  const attestation = artifact.evidence.route?.attestation;
+  return [
+    `# ProbeMesh Call Audit Artifact`,
+    ``,
+    `Status: ${artifact.status}`,
+    `Schema: ${artifact.schemaVersion}`,
+    `Artifact ID: ${artifact.artifactId}`,
+    `Generated: ${artifact.generatedAt}`,
+    ``,
+    `## Call`,
+    `- Call ID: ${artifact.call.callId ?? "none"}`,
+    `- Capability: ${artifact.call.capability}`,
+    `- Provider: ${artifact.call.providerId ?? "none"}`,
+    `- Error code: ${artifact.call.errorCode ?? "none"}`,
+    `- Cost USD: ${artifact.call.cost?.amountUsd ?? "none"}`,
+    `- Request hash: ${artifact.request.requestHash}`,
+    ``,
+    `## Evidence`,
+    `- Receipts: ${artifact.evidence.receiptSummary.total}`,
+    `- Receipt types: ${formatInlineList(artifact.evidence.receiptSummary.types)}`,
+    `- Payment proof: ${String(artifact.evidence.receiptSummary.hasPaymentProof)}`,
+    `- Settlement confirmation: ${String(
+      artifact.evidence.receiptSummary.hasSettlementConfirmation
+    )}`,
+    `- Provider delivery: ${String(
+      artifact.evidence.receiptSummary.hasProviderDelivery
+    )}`,
+    `- Money may have moved: ${String(
+      artifact.evidence.safety?.moneyMayHaveMoved ?? false
+    )}`,
+    `- Retry safe: ${String(
+      artifact.evidence.retrySafety?.safeToAutoRetry ?? false
+    )}`,
+    `- Route stop: ${artifact.evidence.route?.explanation?.stopReason ?? "none"}`,
+    `- Bundle: ${attestation?.bundleId ?? "none"}`,
+    `- Bundle verified: ${String(attestation?.runtimeVerified ?? false)}`,
+    `- Timeline events: ${formatInlineList(
+      artifact.evidence.timeline.eventTypes
+    )}`,
+    ``,
+    `## Hashes`,
+    `- Artifact: ${artifact.hashes.artifact}`,
+    `- Route: ${artifact.hashes.route}`,
+    `- Timeline: ${artifact.hashes.timeline}`,
+    `- Receipts: ${artifact.hashes.receipts}`
+  ].join("\n");
+}
+function formatInlineList(values) {
+  return values.length === 0 ? "none" : values.join(", ");
+}
+function validateSha256String(value, path, errors) {
+  if (typeof value !== "string" || !/^[a-f0-9]{64}$/.test(value)) {
+    errors.push({
+      path,
+      message: `${path} must be a sha256 hex string.`
+    });
+  }
+}
+function validateNonEmptyString(value, path, errors) {
+  if (typeof value !== "string" || value.length === 0) {
+    errors.push({
+      path,
+      message: `${path} must be a non-empty string.`
+    });
+  }
+}
+function validateIsoTimestamp(value, path, errors) {
+  if (typeof value !== "string" || Number.isNaN(Date.parse(value))) {
+    errors.push({
+      path,
+      message: `${path} must be an ISO timestamp.`
+    });
+  }
+}
+function validateStringArray(value, path, errors) {
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string" || entry.length === 0)) {
+    errors.push({
+      path,
+      message: `${path} must be an array of non-empty strings.`
+    });
+  }
+}
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function formatValidationErrors(errors) {
+  return errors.map((error) => `${error.path}: ${error.message}`).join("; ");
+}
+
+export {
+  PROBEMESH_CALL_AUDIT_ARTIFACT_SCHEMA_VERSION,
+  createProbeMeshCallAuditArtifact,
+  validateProbeMeshCallAuditArtifact,
+  assertProbeMeshCallAuditArtifact,
+  formatProbeMeshCallAuditArtifact
+};
+//# sourceMappingURL=chunk-5Q3PDYIA.js.map