feat(amego): amegoErrorHint() — merchant-actionable guidance for account-level errors#1
Merged
Conversation
…nstalls tsdown 0.22 loads tsdown.config.ts via its optional peer "unrun", which a fresh pnpm install never provides — every package's build died with 'Failed to import module "unrun"' on a clean checkout (and typecheck cascaded into missing-dist errors). Declare it explicitly.
…unt-level errors
Amego's setup-level failures (IP allowlist 14, API access not enabled 22,
bad App Key 16, UBN mismatch 12, account inactive/suspended 13/19),
transient provider-side codes (10/15/18/21), and number-track exhaustion
(3040111/3040191) all require the merchant to act in the Amego backend —
but rawCode + the terse original message ('IP 錯誤') don't say what to do.
amegoErrorHint() maps them to display-ready zh-TW guidance; everything
else returns undefined so callers fall back to error.message. Accepts a
raw code or an InvoiceError (isInvoiceError-guarded, amego-only).
Code 14 behavior verified against a real merchant account: an Amego-side
IP allowlist rejects cloud egress IPs unconditionally (2026-07).
There was a problem hiding this comment.
Pull request overview
This PR adds an Amego-specific helper to translate a small, curated set of account/setup-level Amego raw error codes into merchant-actionable zh-TW hints, and fixes clean-checkout builds by adding unrun as a devDependency required by tsdown’s config loading.
Changes:
- Add
amegoErrorHint()with a focused raw-code → zh-TW guidance table for merchant-actionable Amego account/setup and transient provider-side errors. - Export the new helper from
@paid-tw/einvoice-amegoand add a dedicatedvitestsuite covering expected behaviors and exclusions. - Add
unrunto root devDependencies and update the lockfile to unblocktsdownbuilds on clean installs; update READMEs and add a changeset for a minor release.
Reviewed changes
Copilot reviewed 7 out of 8 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| pnpm-lock.yaml | Adds unrun@0.3.1 to the lockfile and wires it into the tsdown snapshot. |
| packages/einvoice-amego/src/index.ts | Exports amegoErrorHint from the package entrypoint. |
| packages/einvoice-amego/src/hints.ts | Implements the hint table and amegoErrorHint() lookup + InvoiceError extraction/guarding. |
| packages/einvoice-amego/src/hints.test.ts | Adds tests for code lookup, numeric codes, InvoiceError extraction, provider filtering, and exclusions. |
| packages/einvoice-amego/README.md | Documents opt-in error hints usage and covered codes in zh-TW. |
| packages/einvoice-amego/README.en.md | Documents opt-in error hints usage and covered codes in English. |
| package.json | Adds unrun to root devDependencies to satisfy tsdown’s optional peer usage. |
| .changeset/amego-error-hints.md | Adds a minor changeset describing the new API and its behavior. |
Files not reviewed (1)
- pnpm-lock.yaml: Generated file
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
amegoErrorHint(rawCode | InvoiceError): string | undefined(new,@paid-tw/einvoice-amego): translates Amego's account/setup-level raw error codes into display-ready zh-TW guidance — the codes where only the merchant can act in the Amego backend, and where the terse original message (「IP 錯誤」) doesn't say what to do.12131416192210151821(→ 稍後再試)30401113040191undefined(callers fall back toerror.message)unrundevDependency — tsdown 0.22 loadstsdown.config.tsvia its optional peerunrun; a freshpnpm installnever provides it, so every package's build failed on a clean checkout.Why
Integrating this SDK into Recur, a real merchant's key kept failing validation with the generic AUTH message. The actual cause was
rawCode 14— an IP allowlist configured in the Amego backend, which unconditionally rejects cloud egress IPs (verified live 2026-07). Neither14nor22(API access not enabled) is guessable by the merchant from the raw message; every integrator will end up hand-rolling this same table.Verification
pnpm build && pnpm typecheck && pnpm lint && pnpm format:check && pnpm testall green (750 passed; 7 new tests inhints.test.tscovering code lookup, numeric codes, InvoiceError extraction, foreign-provider rejection, and business-code exclusions). READMEs (zh + en) + changeset (minor) included.