{"id":"1582f0e0-9d34-44cb-bb97-29fb6229dc7f","slug":"sumup-developer","kind":"skill","name":"sumup-developer","summary":"Source code of the SumUp Developer Portal.","owner":"sumup","repoUrl":"https://github.com/sumup/sumup-developer","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":8,"match":null,"fewStars":false,"format":"skill","createdAt":"2025-01-21T22:12:31.000Z","addedAt":"2026-11-08T07:39:39.472Z","logoUrl":"https://avatars.githubusercontent.com/u/1194464?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","writing"],"tags":["developer-portal","docs","documentation","sumup"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-11-08T07:40:18.920Z","sample":false,"url":"https://conduits.dev/tools/sumup-developer","language":"MDX","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"\n\n# SumUp Developer Portal 👩💻\n\n[![Documentation][docs-badge]](https://developer.sumup.com)\n[](https://github.com/sumup/sumup-developer/actions/workflows/ci.yaml)\n[](./LICENSE)\n[](https://github.com/sumup/sumup-developer/tree/main/CODE_OF_CONDUCT.md)\n\nThe SumUp Developer Portal documents the integrations, SDKs, and public APIs that external developers use to build payment-acceptance solutions. The site is built with [Astro](https://astro.build/) and [Nimbus](https://nimbus-docs.com/). Documentation pages are written in Markdown and MDX, while the visible theme uses plain CSS and SumUp's Circuit UI design tokens.\n\n
\n\n## Local Development\n\n### Prerequisites\n\n- Node.js 24.x, as specified in `.nvmrc` and `package.json`\n- npm 12.x\n\nUsing a Node version manager such as [nvm](https://github.com/nvm-sh/nvm) makes it easier to use the version required by the repository.\n\n### Set up the Project\n\nClone the repository:\n\n```bash\ngit clone git@github.com:sumup/sumup-developer.git\ncd sumup-developer\n```\n\nIf you use nvm, install and select the configured Node.js version:\n\n```bash\nnvm install\nnvm use\n```\n\nInstall the locked dependencies:\n\n```bash\nnpm ci\n```\n\nNo environment variables are required to install, build, or browse the documentation locally. Deployment-only integrations, such as analytics, require secrets that are not stored in the repository.\n\n### Start the Development Server\n\n```bash\nnpm run dev\n```\n\nOpen `http://localhost:3000` in a browser. Most content and component changes appear without restarting the server.\n\n## Validate Changes\n\nRun the checks that match your change before opening a pull request:\n\n| Command | Purpose |\n| ----------------------- | ------------------------------------------------------- |\n| `npm run check` | Validate Astro, TypeScript, and content schemas |\n| `npm run check:nimbus` | Validate Nimbus configuration, adapters, and migrations |\n| `npm run format:check` | Check source and Markdown/MDX formatting |\n| `npm run lint` | Lint application source |\n| `npm run lint:nimbus` | Check MDX structure and links after building |\n| `npm run test` | Run the Vitest test suite |\n| `npm run build` | Build and validate generated pages and agent outputs |\n| `npm run linkcheck` | Build the site and validate internal links |\n| `npm run check:site` | Validate an existing build with a shared HTML cache |\n| `npm run test:worker` | Smoke-test the built Cloudflare Worker locally |\n| `npm run lint:spelling` | Check authored content with the typos CLI |\n| `npm run validate` | Run checks, tests, a build, and Worker smoke tests |\n\nAll authored website content under `src/content/` uses MDX, including changelog\nentries. Repository documents such as this README and imported skills\nremain Markdown.\n\nPrettier handles source formatting, including Markdown tables and list spacing.\nIt preserves prose wrapping and leaves embedded code examples unchanged. Nimbus\nchecks heading structure, duplicate headings, code-block languages, shell prompt\nprefixes, frontmatter, images, and internal links. `npm run linkcheck` also checks\nrendered link targets and fragments, rejects empty links, and requires image alt\nattributes; explicitly decorative images can use `alt=\"\"`.\n\nEvery build runs the redirect, rendered-link, and agent-output checks through\n`check:site`, sharing one parsed HTML cache. The individual check commands remain\navailable for focused diagnosis. Website source files must use `.mdx`; the build\nrejects stray `.md` files under `src/content/`.\n\n`test:worker` uses Wrangler's local workerd test harness against\n`dist/server/wrangler.json`. It checks API HTML/Markdown, the public OpenAPI\nredirect, missing API routes, and documentation MCP without deploying or calling\nthe payment API. Run `npm run build` first, or use `npm run validate` to build and\ntest together.\n\nCI also runs the pinned `typos` spelling check. To run it locally, install the\n[typos CLI](https://github.com/crate-ci/typos#install) and use\n`npm run lint:spelling`. Keep exceptions in `_typos.toml` scoped to genuine\nidentifiers or localized terms; fix spelling errors in the content.\n\nThese checks replace the separate Markdown linter. Its Markdown-only editorial\nrestrictions, such as forbidding inline HTML in MDX or treating a bold paragraph\nas a heading error, are not carried over. Keep new checks focused on formatting,\naccessibility, and working documentation.\n\n## API Specs\n\nThe OpenAPI definition used by the [API Reference](https://developer.sumup.com/api/) is managed in another repository and synchronized into `openapi.yaml`. Do not edit this file directly. If you find a mistake or have an improvement to suggest, [open an issue](https://github.com/sumup/sumup-developer/issues/new).\n\nNimbus serves the API reference at `/api/`, including operation and schema\npages, alternate Markdown, search, `/api/llms.txt`, documentation MCP access,\nand citation coordinates at `/nimbus-api/coordinates.json`.\n\n`src/lib/api/reference.ts` derives Nimbus's input from `openapi.json` and the\nvendored SDK samples without changing either source. Established operation\nURLs are recorded in `src/lib/api/operationPaths.json`. The projection adds\naccess requirements to agent Markdown and converts MDX callouts to CommonMark\nblockquotes. Nimbus shares one operation/schema coordinate namespace, so it\naliases the colliding `ProcessCheckout` schema to `ProcessCheckoutSchema`\nand updates its references in memory. `/openapi.json` publishes the original\ncontract, and `/api/openapi.json` permanently redirects to it. The postbuild\ndiscovery script adds that original contract to Nimbus's API catalog while\npreserving its HTML and Markdown documentation links.\n\nThe reference uses repository-owned Circuit components under\n`src/components/ApiDocs/`, adapted from the portal's original renderer. Nimbus\nowns the prepared API model, routes, highlighted examples, Markdown, MCP, and\ncitation coordinates; our components own the HTML, styles, and presentation.\nAPI pages use the same `DocsLayout`, navigation, search, mobile menu, theme,\nand page actions as the guides. No separate API theme or Tailwind setup is needed.\n\nThe renderer uses Nimbus's headless disclosure and tab controllers for nested\nproperties, expand/collapse all, field deep links, and keyboard navigation.\nUnions show their variants and discriminator mappings. Request samples support\nall vendored SDKs and generated cURL, remember the chosen language, and accept\n`?lang=` links. Inactive samples start hidden; a small inline script\nrestores the selected language before paint. With JavaScript disabled, native\nproperty disclosures still work and the default request/response examples remain\nvisible. The page's Markdown version includes every SDK and response example.\n\nTreat these components as application source, not registry-installed copies.\nNimbus dependency upgrades update the data/runtime layer. Review new upstream UI\nfeatures selectively and adapt those useful to integrators; do not reinstall\n`api-layout` over the portal renderer. Run `npm run validate` and check the\nrendered API when changing the model integration or interactions.\n\nOld resource URLs redirect to Nimbus's `/api/tags/` pages. The small\n`LegacyLinks.astro` adapter resolves operation and object fragments from the\nold combined pages to their new pages, since fragments never reach the server.\nSDK and authorization links redirect to their existing guides; error guidance\nlives at `/tools/errors/`. Validate with `npm run validate` and a local Worker.\n\n[docs-badge]: https://img.shields.io/badge/SumUp-documentation-white.svg?logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgY29sb3I9IndoaXRlIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPgogICAgPHBhdGggZD0iTTIyLjI5IDBIMS43Qy43NyAwIDAgLjc3IDAgMS43MVYyMi4zYzAgLjkzLjc3IDEuNyAxLjcxIDEuN0gyMi4zYy45NCAwIDEuNzEtLjc3IDEuNzEtMS43MVYxLjdDMjQgLjc3IDIzLjIzIDAgMjIuMjkgMFptLTcuMjIgMTguMDdhNS42MiA1LjYyIDAgMCAxLTcuNjguMjQuMzYuMzYgMCAwIDEtLjAxLS40OWw3LjQ0LTcuNDRhLjM1LjM1IDAgMCAxIC40OSAwIDUuNiA1LjYgMCAwIDEtLjI0IDcuNjlabTEuNTUtMTEuOS03LjQ0IDcuNDVhLjM1LjM1IDAgMCAxLS41IDAgNS42MSA1LjYxIDAgMCAxIDcuOS03Ljk2bC4wMy4wM2MuMTMuMTMuMTQuMzUuMDEuNDlaIiBmaWxsPSJjdXJyZW50Q29sb3IiLz4KPC9zdmc+\n\n## Documentation for agents\n\nNimbus publishes `/llms.txt`, section indexes, `/llms-full.txt`, and an\n`index.md` alternate for each guide and API reference page. The index also links to `/openapi.json`,\nwhich publishes the synchronized API contract without modifying it.\n\nKeep reference tables in Markdown. `SearchableTable.astro` adds browser filtering\nwithout hiding the source data from agents or requiring JavaScript to read it.\nProject components that generate content use `src/lib/markdownComponents.ts`;\nshared data drives both their HTML and Markdown representations.\nEvery component used in docs must have a renderer or an explicit preservation\npolicy in that module. Agent validation checks component coverage and compares\nrendered code blocks, including generated examples, with both Markdown outputs.\nBump a renderer's revision when its output logic changes; generated renderers\nshould include their source data in the revision to invalidate cached output.\n\n`npm run check:agent-docs` checks the built output against every authored code\nexample and verifies the full bundle, canonical URLs, and API contract. It runs\nas part of `npm run validate`. Nimbus owns Markdown conversion, sitemap dates,\nand skill archive generation. The postbuild\ndiscovery step adds our OpenAPI and MCP routes to Nimbus's generated catalogs.\nNimbus owns discovery-file CORS and content types. Keep owner header rules\ndisjoint from those generated rules: Cloudflare combines overlapping values.\nAgent validation rejects duplicated CORS/content types in the built output.\n\n`npm run check:redirects` validates every explicit redirect destination and\nfragment, including rules unused by current pages, and rejects duplicate sources,\nloops, and static rules after dynamic rules. It runs in `npm run linkcheck`.\nRemove redirects for retired endpoints without a documented replacement instead\nof pointing them at an unrelated API operation.\n\nThe documentation MCP server at `https://developer.sumup.com/mcp` exposes\n`list_pages` and `get_page` without authentication. Nimbus serves it and its\n`/mcp/server-card` route through the Worker while guide pages remain prerendered.\nThe SumUp account-tools server at `https://mcp.sumup.com/mcp` remains separate\nand uses OAuth. Validate documentation MCP changes against the built Worker:\ncheck `tools/list`, then call both tools and verify the returned Markdown.\n\nThe Cloud API checkout walkthrough uses Nimbus's headless React `Diagram` and\n`usePhase` helpers with SumUp styles. Its shared step data also produces the\nMarkdown version; keep the two representations aligned when adding diagrams.\nUse `client:visible` and keep the explanation readable before hydration.\n\nSkills are imported verbatim from the commit in `agent-skills.source.json`.\nRun `npm run sync:agent-skills` to reproduce them, or add\n`-- --source /path/to/sumup-skills` to use an existing Git checkout offline.\nThe command reads the pinned Git tree and ignores uncommitted source edits.\nTo publish an upstream change, review and update the pinned revision, sync, and\ncommit the lock and imported `skills/` files together. Builds need no source\ncheckout or network access: Nimbus packages the checked-in sources into\ndeterministic archives and publishes their discovery index and SHA-256 digests.\n\nSecurity overrides: Mermaid's KaTeX is pinned to 0.19.0 until Mermaid's supported\ndependency range includes a patched release. Validate Mermaid diagrams when\nupdating that override.\n\n## Updating Nimbus\n\nRun `npm run check:nimbus` before accepting dependency upgrades. In particular,\nstay within Nimbus's supported Astro adapter range even when a newer adapter\nbuilds successfully. Run `nimbus-docs migrate` and complete its reviews, then\nuse `nimbus-docs outdated --json` to inspect upstream changes.\n\nKeep the ownership boundary explicit during upgrades:\n\n| Layer | Responsibility |\n| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| Nimbus | Documentation/API models, metadata, Markdown and agent publishing, and headless client helpers |\n| Portal | Astro layouts and routes, Circuit presentation, and browser interactions |\n| Integration | SumUp API adaptations in `src/lib/api/reference.ts`, component-to-Markdown mappings in `src/lib/markdownComponents.ts`, and compatibility/discovery adapters |\n\nAdopt upstream features for a concrete portal requirement. Registry and starter\nvisual changes are optional; keep the shared Circuit rendering. Validate API\nURLs, SDK samples, citation anchors, Markdown/full-bundle content, and discovery\noutputs with `npm run validate`. This also compares tag descriptions in the API\noverview with their dedicated pages, including Markdown structure and links.\nFor affected UI, check desktop/mobile and both themes. The Worker smoke tests exercise documentation MCP on every validation run.\nFor changes to MCP behavior, also check the affected tools and responses.\n\nThis portal adopted Nimbus through a custom migration. Its original scaffold\nversion is unknown, so `nimbus.json` keeps `version: null`. The recorded\n`templates-v0.8.0` tag is an explicit comparison baseline reviewed against Nimbus\n0.19, rather than a claim that the portal was scaffolded from that release.\nThe guide layouts, fonts, styles, homepage, and navigation keep the SumUp\ndesign. The API reference uses the same shell and Circuit tokens. Optional\nstarter features are adopted individually.\n\nRegistry entries in `nimbus.json` record reviewed upstream hashes and the paths\nof our customized copies. Most live under `src/components/nimbus/`, rather than\nthe registry's `src/components/ui//` directories. Compare the corresponding\nregistry item before updating these files; do not install a second copy at its\ndefault path or overwrite our styles. Steps stays at the registry's normal path\nand follows its ordered-list semantics. Custom diagrams use the framework's\nheadless hooks directly and are owned by this repository.\n\nAfter merging upstream behavior, update the relevant reviewed baseline and run\n`npm run validate`. A baseline update means the upstream changes were reviewed;\nit does not mean our customized files should match the starter byte for byte.\n"}