card-endpoint-shape

Defines declarative RTK Query endpoint conventions for the card-management API module.

615|491|Updated Jan 4, 2022
One-click install
npx skills add https://github.com/LedgerHQ/ledger-live --skill card-endpoint-shape
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: card-endpoint-shape
Source: https://github.com/LedgerHQ/ledger-live/tree/main/domain/api/card-management/.agents/skills/card-endpoint-shape
Command: npx skills add https://github.com/LedgerHQ/ledger-live --skill card-endpoint-shape

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Adding or editing endpoints in the card-management API layer often leads to inconsistent patterns: misuse of queryFn, manual type casts, inline transforms, and leaked PII in the cache. This Skill enforces a single declarative endpoint shape so every endpoint reads the same way.

Core Features & Use Cases

  • Four-key endpoint contract: Every endpoint declares query, rawResponseSchema, transformResponse, and responseSchema in a fixed order, with unused keys dropped.
  • queryFn prohibition: Explains why RTK Query skips transformResponse for queryFn endpoints and why configuration must arrive as request arguments instead of being read from the store.
  • Schema-only validation: Zod schemas in schema.ts are the sole validation mechanism, keeping wire shapes narrow so undeclared fields (and PII) never reach the cache.
  • Use Case: When adding a new OAuth or session endpoint to domain/api/card-management/src/api.ts, follow this Skill to declare it as a build.mutation with a wire schema, a named transform in transforms.ts, and a canonical response schema.

Quick Start

Read this Skill before adding or editing any endpoint in domain/api/card-management/src/api.ts and follow its checklist.

Frequently Asked Questions about card-endpoint-shape

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a new endpoint to the card-management API?

Declare it in api.ts with up to four keys in fixed order: query, rawResponseSchema, transformResponse, and responseSchema. Put the wire schema in schema.ts, the mapping as a named function in transforms.ts, and drop any keys the endpoint does not need.

Why should I avoid queryFn in RTK Query endpoints?

RTK Query skips transformResponse for queryFn endpoints, so the mapping must be done manually inside the function. The base query result is also typed as unknown, forcing casts or manual safeParse calls plus repetitive error handling.

When should an endpoint use build.mutation instead of build.query?

Use build.mutation for anything that is not idempotent, even a GET request. For example, each authorize initiation carries a fresh state and challenge, so it is declared as a mutation.

How does Zod schema validation keep PII out of the RTK Query cache?

Zod drops undeclared keys during parsing, so a narrow wire schema like PayCardUserResponseSchema only keeps the fields it declares. Widening the schema would let extra backend fields, potentially including PII, into the cache.

Where does endpoint configuration like OAuth client id come from?

Base URL, client key, Authorization, and 401 refresh come from cardApiExtra in the shared api-services package. Everything else, such as the OAuth client id and redirect URI, must arrive as request arguments rather than being read from the store via queryFn.