feat(ack-pay): add approval model types

[EfeDurmaz16]

Summary

• Add minimal exported ACK-Pay types for approval requests and approval decisions
• Document how HITL approval objects fit around payment execution without adding a workflow engine to ACK core
• Clarify that denied decisions should stop before signing or settlement, while approved decisions can be recorded as audit evidence

Fixes #93

Verification

• pnpm run build
• pnpm --filter ./packages/ack-pay check:types
• pnpm --filter ./packages/ack-pay exec vitest run
• pnpm exec oxfmt --check docs/ack-pay/hitl.mdx packages/ack-pay/src/index.ts packages/ack-pay/src/payment-approval.ts
• git diff --check

Summary by CodeRabbit

• New Features

  • Added payment approval request and decision types to ACK‑Pay to support approval workflows and decisions.

• Documentation

  • Added "Approval Request and Decision Shape" section with TypeScript examples illustrating request and decision structures.

• Chores

  • Included a changeset entry to publish the patch release containing these additions.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 47cae82c-555c-4424-9029-02dad37149cf

📥 Commits

Reviewing files that changed from the base of the PR and between 05cd68c and 5a358db.

📒 Files selected for processing (1)

• docs/ack-pay/hitl.mdx

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/ack-pay/hitl.mdx

---

Walkthrough

The PR introduces a minimal approval model for ACK-Pay consisting of PaymentApprovalRequest and PaymentApprovalDecision types. These shared contracts are exported from the package and documented in the HITL guide with examples, enabling human-in-the-loop payment flows without a full workflow engine.

Changes

Approval Request and Decision Model

Layer / File(s)	Summary
Approval request and decision type definitions packages/ack-pay/src/payment-approval.ts	New module exports PaymentApprovalRequest with required IDs and optional requester/reason/expiry/metadata fields, PaymentApprovalDecisionValue as a union type for "approved" or "denied", and PaymentApprovalDecision linking back to the request with decision value, optional approver identity/reason, required timestamp, and metadata.
Public API export packages/ack-pay/src/index.ts	Package entrypoint re-exports all payment-approval module symbols, making approval types available through the main package export.
Documentation and release docs/ack-pay/hitl.mdx, .changeset/add-approval-types.md	HITL documentation adds a subsection describing approval request and decision shapes with a TypeScript example showing requester/approver identity, reason, and metadata fields; changeset announces a patch release for the new approval model types.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(ack-pay): add approval model types' directly and accurately summarizes the main change: adding new approval-related TypeScript types to the ack-pay package.
Linked Issues check	✅ Passed	The PR implements all coding requirements from issue #93: PaymentApprovalRequest and PaymentApprovalDecision types are exported from ack-pay with matching field names/structure, documentation is added explaining HITL integration, and types are exported for example code.
Out of Scope Changes check	✅ Passed	All changes directly support the linked issue objectives: type definitions, exports, documentation of HITL approval integration, and a changeset entry. No unrelated modifications were introduced.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 05ddd97b3f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Add runtime schemas for approval models

Because this introduces new exported ACK-Pay model types, the repo’s schema contract requires matching Valibot and Zod v3/v4 schemas for new types. As written, applications receiving these approval objects over the wire can import only TypeScript interfaces, so runtime validation through @agentcommercekit/ack-pay/schemas/* is unavailable and inconsistent with existing payment request/receipt models; please add schemas for both PaymentApprovalRequest and PaymentApprovalDecision.

Useful? React with 👍 / 👎.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/ack-pay/hitl.mdx`:
- Line 48: The example's expiresAt field is stale (currently
"2026-01-01T12:00:00.000Z"); update the expiresAt value in the sample to a
future ISO8601 timestamp (e.g., a year or more ahead) or replace it with a
clearly labeled placeholder like expiresAt: "<FUTURE_ISO_TIMESTAMP>" so readers
copying the snippet get a valid approval window; locate and change the expiresAt
entry in the sample block where expiresAt is set.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 6240cde5-1695-4cca-8ab1-ff9ff2f15959

📥 Commits

Reviewing files that changed from the base of the PR and between 6f65936 and 05cd68c.

📒 Files selected for processing (4)

• .changeset/add-approval-types.md
• docs/ack-pay/hitl.mdx
• packages/ack-pay/src/index.ts
• packages/ack-pay/src/payment-approval.ts

[EfeDurmaz16]

Addressed the stale approval expiry example in 5a358db by replacing the fixed past timestamp with <FUTURE_ISO_TIMESTAMP>.