Thanks for considering a contribution. Lonca is a community-maintained project and every kind of contribution helps — bug reports, documentation, new marketplace SDKs, performance improvements.
Before opening a PR:
- Does your change come from real usage pain, or from speculation? Lonca follows an authentic pain-validation principle — instead of designing for a scenario you haven't experienced, open an issue or Discussion and let's talk it through.
- For large changes (new package, breaking change, architecture) open an issue or Discussion before the PR.
- Node.js >= 22 (active LTS;
.nvmrcpins 24) - pnpm >= 10 (Corepack recommended)
- Git >= 2.40
git clone https://github.com/zanaat-dev/lonca.git
cd lonca
pnpm installpnpm typecheck # TypeScript
pnpm lint # ESLint
pnpm format # Prettier
pnpm test # Vitest
pnpm test:coverage # Vitest + per-package coverage thresholds (what CI runs)
pnpm build # Build via TurborepoWork on a single package:
pnpm --filter @lonca/trendyol test
pnpm --filter @lonca/core buildpnpm test:coverage runs the suite with V8 coverage (pnpm --filter @lonca/trendyol test:coverage for one package). Each published package pins its own coverage.thresholds in vitest.config.ts, calibrated as a regression floor (measured coverage rounded down to the nearest 5). CI runs test:coverage, so a change that drops a package below its floor fails the build. Raising a floor after adding tests is welcome — lowering one needs a reason in the PR. The HTML report lands in each package's gitignored coverage/ directory.
The public .d.ts surface of every published package is snapshotted under etc/ and checked in
CI (pnpm api:check, after pnpm build). For the SDKs, which have two entry points, tsup puts the
shared declarations in a hashed client-*.d.ts chunk; that chunk is snapshotted too
(etc/<sdk>-client.d.ts.snapshot), with hashes and minified re-export aliases normalised away, so
a changed field or signature shows up as a one-line diff. If the check fails, your change altered
the public API surface:
- Run
pnpm build && pnpm api:updateto regenerate the snapshots. - Commit the updated
etc/*.snapshotfiles with your change and mention the surface diff in the PR description. - If the change is a removal or an incompatible signature change, it is breaking — pick a major bump in your changeset.
An unintentional diff usually means something leaked into the public surface — prefer narrowing
the export over updating the snapshot. CI also runs pnpm health:packages
(publint + arethetypeswrong) against
each published package, which guards the exports map and type resolution.
- Fork the repo and create a feature branch (
git checkout -b fix/trendyol-rate-limit). - Make the change, add or update tests.
- Add a changeset (required for bug fixes, features, and breaking changes):
Pick how each affected package should be bumped (patch / minor / major) and write a short summary. Docs, refactors, and chores do not need a changeset. The summary also appears on the release notes page; a Turkish version is welcome but optional (see .changeset/README.md).
pnpm changeset
- Make sure
pnpm typecheck && pnpm lint && pnpm test && pnpm format:checkpass locally. - Open the PR and fill in the template.
We loosely follow Conventional Commits — not enforced, but consistent titles help readability:
feat(trendyol): add inventory bulk update endpoint
fix(core): retry should not consume body on 429
docs: clarify pnpm catalog usage
To add an SDK for a new marketplace (n11, Çiçeksepeti, Pazarama, ePttAVM, …):
- Open an issue using the
🏬 New marketplace SDK requesttemplate. Fill in the pain-validation section honestly. - Once a maintainer approves, start work under
sdks/<marketplace>. - Reuse
@lonca/coreprimitives (Money, Pagination, error hierarchy, retry, logger) — do not duplicate. - At minimum cover the following endpoint groups: Orders + Products + Inventory.
- Prettier + ESLint run in CI — please don't override the configs, keep the repo standard.
- TypeScript
strictmode. Useanyonly as a last resort and document why. - Public API surfaces should have TSDoc comments.
By contributing you agree your contribution is licensed under the MIT License.