RAP-sdk

Imported from revaly-co/RAP-sdk (AGENTS.md). Install upstream with npx skills add revaly-co/RAP-sdk. Copyright stays with the author.

AGENTS.md — the Revaly RAP SDK in one page

Machine-readable orientation for AI coding agents integrating or modifying this SDK. Humans are welcome here too; the prose is just denser than README.md.

Read this whole file before writing integration code. The classification rules in §3 are normative and safety-critical: getting them wrong is how a cardholder gets charged twice.

1. What this repository is

Six server-side SDKs for the RAP V2 API (RAP-core, https://api.revaly.co) — .NET, Java, PHP, TypeScript, Python, Go — generated from one gated OpenAPI artifact and wrapped in a hand-written runtime that implements a merchant-facing failover & reconciliation contract.

2. Install and import, per language

One package per language: the generated core is re-exported through the runtime's namespace, so integration code imports the runtime only.

3. The classification algorithm (normative)

Every failed payment call resolves to exactly one of three outcome classes. Apply this algorithm and nothing else — never classify from the human-readable error message, from latency, or from how long you waited:

if transport error and request provably never sent          → TransientFailure
if HTTP status in {400, 401, 403, 404, 422}                 → PermanentRejection
if HTTP status == 503 and body.code == "not_processed"      → TransientFailure
if HTTP status >= 500                                        → OutcomeUnknown
if deadline exceeded after send / reset / ambiguous          → OutcomeUnknown

Supporting rules:

• ErrorResponse.code and transactionType are open strings, never closed enums. A code the SDK does not recognize is handled as absent, which resolves to OutcomeUnknown.
• details is opaque. Do not parse it for control flow.
• When a language's HTTP stack cannot prove the request was never sent, the outcome is OutcomeUnknown. The safe-to-fail-over class is reserved for provable non-dispatch.
• Only RAP-core's own 503 {code: "not_processed"} licenses immediate failover. Edge (Front Door / WAF) error bodies are HTML rather than ErrorResponse, and the edge cannot mint that code; a 504 can fire in about 4 seconds and never implies your deadline elapsed.

What each class means for calling code

Class names per language

Every typed error carries: class, HTTP status (when there was one), verbatim code (when present), human message, opaque details, correlation ID, and a reference to the raw response.

4. Reconcile — the OutcomeUnknown procedure

merchantTransactionId is required on every payment request (max length 100) and is the key reconcile looks the payment up by. Generate it as unique and durable in your own system before you send the charge; persist it before the call, not after.

reconcile(merchantTransactionId, policy) → Found(outcome) | NotFoundYet

Verdict handling:

A default / else branch on the verdict switch is mandatory in every language. Generated integration code that omits it is incorrect even though it compiles today.

NotFoundYet carries attempts, elapsed time, last correlation ID, and last HTTP status. A null last HTTP status with attempts > 0 means no attempt ever received an HTTP response — the API-unreachable signal. Degraded reads (5xx or timeout on the GET) keep polling within the caller's budget; the merchant action on NotFoundYet is the same either way.

policy bounds the loop: backoff schedule, per-attempt deadline, overall budget, cancellation in the language's idiom (CancellationToken / context.Context / AbortSignal / …). V1 ships no default policy — pass one explicitly. The helper is GET-only and side-effect-free.

Reconcile symbols: rap.ReconcileAsync(...) + ReconcilePolicy (.NET) · client.reconcile(...)

• ReconcilePolicy.builder() + RapReconcileVerdict.Found / .NotFoundYet (Java) · $client->reconcile(...) + Revaly\Sdk\Reconcile\{Found, NotFoundYet, ReconcilePolicy} (PHP) · client.reconcile(id, { maxAttempts, overallBudgetMs, initialDelayMs }) returning verdict.kind (TypeScript) · client.reconcile(...) (Python) · client.Reconcile(ctx, id, revaly.ReconcilePolicy{...}) (Go).

5. Configuration surface

6. Testing integration code offline

Every language ships a first-class mock transport that reproduces every row of the taxonomy plus both reconcile verdicts, with synthetic data only. Scenario methods mirror the contract vocabulary, so a test reads as the row it covers:

const mock = new RapMockTransport();
mock.charge().returnsNotProcessed503();                    // → TransientFailure
mock.reconcile('order-1042').notFoundYet(2).thenFoundApproved();
const client = new RapClient({ apiKey: 'sk-synthetic', transport: mock });

Namespaces: Revaly.Sdk.Testing (.NET) · co.revaly.sdk.testing (Java) · Revaly\Sdk\Testing (PHP) · @revaly/sdk (TypeScript) · revaly_sdk.testing (Python) · .../languages/go/raptest (Go). Method casing follows each language (ReturnsNotProcessed503, returns_not_processed_503, …).

A complete failover handler test suite covers, at minimum: each of the three classes, Found after NotFoundYet, sustained NotFoundYet, and the default verdict branch.

7. Rules for agents modifying this repository

These are enforced by CI and by CONTRIBUTING.md; a PR that breaks one fails rather than merges.

1. languages/*/core/ is generated. Never hand-edit it. It changes only by regeneration against a newly pinned spec artifact. CI runs a regeneration-diff check and fails on a one-byte difference. The hand-written product code is languages/*/runtime/ (Go: revaly.go, internal/runtime/, raptest/).
2. Spec input is a pinned, gated artifact only — a spec/v* release tag verified against its .sha256 and provenance.json, pinned in spec/. Never generate from a branch, a URL, or a locally edited spec.
3. Publishing runs through the pipeline. The one human act is a per-language release tag on main. Never publish, re-publish, or yank out of band. A failed release is fixed and re-tagged, never resumed by re-running build stages.
4. The safety-contract invariants in §3 and §4 are fixed by ADR. Changing one requires an ADR revision, never a code choice. Reproducing them incorrectly in generated integration code is a correctness bug.
5. Logging stays values-free. No payload values at default verbosity; debug scrubs PAN, CVV and PII; API keys appear in neither logs nor exception messages. Scrubbing goes through the one central allowlist function per runtime, and every language ships log-capture tests asserting it.
6. Do not decide open items. Items in docs/open-items.md have owners. Where code needs an undecided answer, leave a marker referencing the OQ.

8. Where to look next