Skip to content

feat(types): payment-failure triage demo scenarios + scenario manifest#103

Merged
dangazineu merged 1 commit into
mainfrom
feature/payment-failure-triage-scenarios
Jun 28, 2026
Merged

feat(types): payment-failure triage demo scenarios + scenario manifest#103
dangazineu merged 1 commit into
mainfrom
feature/payment-failure-triage-scenarios

Conversation

@dangazineu

@dangazineu dangazineu commented Jun 28, 2026

Copy link
Copy Markdown
Contributor

What

Adds the two shared DemoScenario objects for the payment-failure-triage demo to
@codespar/types/testing, plus a DEMO_SCENARIO_MANIFEST so an example that
drives these scenarios stays in sync with the published source. Bumps
@codespar/types to 0.10.12 — the version a consumer exact-pins.

This is the first of two parts: the scenarios must publish before the example can
pin them.

Scenarios

Both express one judgment at the commerce meta-tool abstraction — reading a
payment failure's category and routing the remediation (the platform owns
provider selection inside codespar_pay; the agent never picks a provider):

  • CUSTOMER_DATA_REJECTION_SCENARIOcodespar_pay returns a successful
    result whose payload is a decline (category: "customer_data",
    error_code: "INVALID_CPF_CNPJ"). The agent asks the customer for a correction
    via codespar_notify, retries codespar_pay (confirmed), then issues the NF-e
    via codespar_invoice. No human escalation.
  • MERCHANT_BLOCKED_SCENARIOcodespar_pay returns a decline
    (category: "non_recoverable", error_code: "MERCHANT_BLOCKED"). The agent
    notifies a human on an ops channel and stops — no retry, no invoice, no
    customer message.

A decline is a successful tool result carrying a status/category field, not
a transport error, so the meta-tool trace still reports status: "success".

Scenario manifest

DEMO_SCENARIO_MANIFEST ({ version, scenarios }) is the published contract for
these scenarios. A consumer that drives them asserts:

  • completeness — the scenarios it drives equal scenarios exactly (publish a
    new scenario and forget to cover it → fail);
  • version-alignment — its @codespar/types dependency is an exact pin equal
    to version (a caret/tilde or stale pin fails).

A lockstep test keeps version equal to the package version, so a publish that
forgets to bump the manifest fails CI.

Tests

npx tsc clean; npx vitest run green in packages/types (92 tests). The new
scenarios pass the existing internal-consistency checks (every fixture tool is a
meta-tool, mocked, agrees with expectMetaTools, and carries the contract's
required fields).

@dangazineu
dangazineu force-pushed the feature/payment-failure-triage-scenarios branch from c527b92 to 2c4e206 Compare June 28, 2026 13:46
…ifest

Add two shared DemoScenario objects for the payment-failure-triage demo,
authored once in @codespar/types/testing so any example that drives them stays in
sync with the published source:

- CUSTOMER_DATA_REJECTION_SCENARIO: codespar_pay returns a successful result
  whose payload is a decline with category "customer_data" / INVALID_CPF_CNPJ.
  The agent notifies the customer, retries codespar_pay (confirmed), then issues
  the NF-e via codespar_invoice. No human escalation.
- MERCHANT_BLOCKED_SCENARIO: codespar_pay returns a decline with category
  "non_recoverable" / MERCHANT_BLOCKED. The agent notifies a human (ops channel)
  and stops — no retry, no invoice, no customer message.

Both stay at the meta-tool abstraction (the agent routes the remediation, not the
provider) and pass the internal-consistency checks.

Add DEMO_SCENARIO_MANIFEST: the published contract for these scenarios (the
scenario names + the package version). A consumer asserts completeness (it drives
exactly the manifest's scenarios) and version-alignment (it exact-pins this
package to the manifest version), so an example and the published scenarios cannot
drift apart. A lockstep test keeps the manifest version equal to the package
version so a publish cannot ship a stale manifest.

Bump @codespar/types to 0.10.12 (the version a consumer pins).
@dangazineu
dangazineu force-pushed the feature/payment-failure-triage-scenarios branch from 2c4e206 to 8c2e7ac Compare June 28, 2026 18:45
@dangazineu dangazineu changed the title feat(types): payment-failure triage demo scenarios + dual-runtime manifest feat(types): payment-failure triage demo scenarios + scenario manifest Jun 28, 2026
@dangazineu
dangazineu merged commit bc629d3 into main Jun 28, 2026
9 checks passed
dangazineu added a commit that referenced this pull request Jun 28, 2026
Bumps `@codespar/types` to **0.10.13**. `0.10.12` was published in
parallel by unrelated work (no triage scenarios), so the scenarios from
#103 (which landed as 0.10.12) cannot publish at that number. This bumps
to a free version; the `DEMO_SCENARIO_MANIFEST` version moves in
lockstep (self-test enforces it), and the example (#104) + managed
parity test pin 0.10.13. Merge this, then a `v0.10.13` tag publishes the
package.
dangazineu added a commit that referenced this pull request Jun 28, 2026
Single release of @codespar/types at the next free version, 0.10.13. Consolidates
two additive changes already on main, plus the manifest bump they require:

- PayResult.checkout_session_id (merged in #105)
- the payment-failure-triage demo scenarios + DEMO_SCENARIO_MANIFEST (merged in
  #103)

0.10.12 was published in parallel by unrelated work and predates both, so this
ships at 0.10.13. Bumps packages/types/package.json AND
DEMO_SCENARIO_MANIFEST.version in lockstep (the manifest self-test enforces
equality with the package version — a package-only bump like #106 would fail it).
Supersedes #106. After merge, tagging v0.10.13 publishes the package; the example
(#104) and the managed parity test (#402) pin 0.10.13.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant