feat(ack-pay): add minimal approval request and decision model

[EfeDurmaz16]

Context

ACK-Pay documentation already describes human oversight and approval as an important part of payment flows. Today that is mostly conceptual. It may be useful to add a small, typed approval request/decision shape that examples can use without creating a full workflow engine.

Proposal

Add a minimal, optional ACK-Pay approval model for demos/examples:

type PaymentApprovalRequest = {
  id: string
  paymentRequestId: string
  paymentOptionId?: string
  requesterDid?: string
  reason?: string
  expiresAt?: string
  metadata?: Record<string, unknown>
}

type PaymentApprovalDecision = {
  requestId: string
  decision: "approved" | "denied"
  approverDid?: string
  reason?: string
  decidedAt: string
  metadata?: Record<string, unknown>
}

Exact naming can change. The important goal is to give demos a shared object model for approval-required paths.

Why this helps

• Makes HITL flows easier to implement consistently in ACK examples.
• Creates a clean bridge to policy-before-signing demos.
• Keeps policy engines out of ACK core while documenting the boundary where policy/approval systems integrate.
• Aligns with agent-payment systems where high-risk payments require human or owner authorization.

Small first slice

• Add docs in docs/ack-pay/hitl.mdx.
• Optionally export types from packages/ack-pay if maintainers want a code surface.
• Add one example flow showing: payment request -> approval request -> approval decision -> receipt issuance.