bidkit 0.1.0__tar.gz

bidkit-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,39 @@
+name: Bug report
+description: Something behaves incorrectly
+labels: [bug]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened?
+      description: What did you do, what did you expect, what happened instead?
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: >-
+        Smallest snippet that shows the problem. Strip credentials; an httpx.MockTransport
+        repro is ideal.
+      render: python
+  - type: input
+    id: version
+    attributes:
+      label: bidkit version
+      placeholder: python -c "import bidkit; print(bidkit.__version__)"
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version & OS
+      placeholder: "3.12.4 on macOS 15"
+    validations:
+      required: true
+  - type: textarea
+    id: traceback
+    attributes:
+      label: Traceback / logs
+      description: Full traceback if there is one. Redact tokens and account data.
+      render: text

bidkit-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Question / usage help
+    url: https://github.com/heyalexej/bidkit/discussions
+    about: Ask questions and share usage tips in Discussions.
+  - name: Security issue
+    url: https://github.com/heyalexej/bidkit/security/advisories/new
+    about: Please report vulnerabilities privately, never as a public issue.
+  - name: eBay API behavior (not an SDK bug)
+    url: https://developer.ebay.com/support
+    about: Problems with the eBay APIs themselves belong to eBay developer support.

bidkit-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,20 @@
+name: Feature request
+description: Suggest an improvement or missing capability
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What are you trying to do that bidkit doesn't support well?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What would the API look like? Sketches welcome.
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered

bidkit-0.1.0/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      dev-dependencies:
+        dependency-type: development
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly

bidkit-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,11 @@
+## What & why
+
+<!-- What does this change, and what problem does it solve? -->
+
+## Checklist
+
+- [ ] PR title is a valid [Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/) header (it becomes the squash commit)
+- [ ] `uv run pytest`, `uv run ruff check .`, `uv run ruff format --check .`, and `uv run ty check src tests` pass
+- [ ] Tests added/updated for behavior changes
+- [ ] No hand edits to `src/bidkit/generated/` (change the generator/specs and regenerate instead)
+- [ ] No credentials, tokens, or real account data in code, tests, or fixtures

bidkit-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,123 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+jobs:
+  static:
+    name: Lint, format, types
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Lint (ruff)
+        run: uv run ruff check .
+
+      - name: Format (ruff)
+        run: uv run ruff format --check .
+
+      - name: Type check (ty)
+        run: uv run ty check src tests
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Test (pytest + coverage)
+        run: uv run pytest -q --cov --cov-fail-under=88
+
+  generated-drift:
+    name: Generated code drift
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Regenerate from committed specs
+        run: uv run scripts/generate_openapi.py
+
+      - name: Fail if generated code drifted
+        run: git diff --exit-code src/bidkit/generated
+
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+
+      - name: Build wheel and sdist
+        run: uv build
+
+      - name: Guard against spec payloads in the wheel
+        run: |
+          python - <<'EOF'
+          import glob, sys, zipfile
+          whl = glob.glob("dist/*.whl")[0]
+          names = zipfile.ZipFile(whl).namelist()
+          leaked = [n for n in names if n.endswith(".json")]
+          if leaked:
+              sys.exit(f"spec JSON leaked into the wheel: {leaked}")
+          size = sum(i.file_size for i in zipfile.ZipFile(whl).infolist())
+          if size > 8_000_000:
+              sys.exit(f"wheel unexpectedly large: {size} bytes uncompressed")
+          print(f"wheel ok: {len(names)} files, {size} bytes uncompressed")
+          EOF
+
+      - name: Validate metadata (twine)
+        run: uvx twine check dist/*.whl dist/*.tar.gz
+
+  docs:
+    # Keep in sync with the build job in docs.yml (the Pages deploy).
+    name: Docs build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+
+      - name: Build site (strict)
+        run: |
+          uv sync --extra docs
+          uv run mkdocs build --strict

bidkit-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  # Keep in sync with the docs job in ci.yml (the PR gate).
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+
+      - name: Build site
+        run: |
+          uv sync --extra docs
+          uv run mkdocs build --strict
+
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

bidkit-0.1.0/.github/workflows/pr-title.yml

@@ -0,0 +1,17 @@
+name: PR title
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+
+permissions:
+  pull-requests: read
+
+jobs:
+  conventional-commit:
+    name: Validate conventional-commit title
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v6
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

bidkit-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  # release-please creates releases with GITHUB_TOKEN, which does NOT fire the
+  # release event for other workflows; dispatch this manually after merging the
+  # release PR (gh workflow run publish.yml).
+  workflow_dispatch:
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    # Trusted publishing (OIDC): configure this repo + workflow + environment as a
+    # pending publisher at https://pypi.org/manage/account/publishing/ - no token needed.
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

bidkit-0.1.0/.github/workflows/release-please.yml

@@ -0,0 +1,17 @@
+name: release-please
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v5
+        with:
+          release-type: python

bidkit-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+.ruff_cache/
+.pytest_cache/
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/
+specs/normalized/
+.coverage
+site/

bidkit-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,12 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/compilerla/conventional-pre-commit
+    rev: v4.0.0
+    hooks:
+      - id: conventional-pre-commit
+        stages: [commit-msg]

bidkit-0.1.0/CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog
+
+## 0.1.0 (2026-07-02)
+
+
+### ⚠ BREAKING CHANGES
+
+* **client:** the undocumented client.request()/client.stream() passthroughs are now private; call the typed generated methods, or client._transport for low-level needs.
+* **transport:** requests outside eBay's signed set no longer carry signature headers when EbaySigningConfig is set. Use EbaySigningConfig(sign_all=True) to restore blanket signing if eBay expands its signature requirements before the SDK updates.
+* import bidkit instead of ebay_sdk; install bidkit instead of ebay-sdk.
+
+### Features
+
+* **auth:** add OAuth authorization-code exchange ([a2e8db6](https://github.com/heyalexej/bidkit/commit/a2e8db6d68e830af21a6b798d99c6a242e3040be))
+* **auth:** add persistent FileTokenCache ([e77d6a5](https://github.com/heyalexej/bidkit/commit/e77d6a5b8609c8b9b874463b627f91c122eb5196))
+* **client:** scoped config overrides via with_options() ([e5be066](https://github.com/heyalexej/bidkit/commit/e5be06652d94cc84aa13eb1c53599d1df64a5530))
+* **config:** load ebay-cli style config files ([495d6ac](https://github.com/heyalexej/bidkit/commit/495d6ace368ddc71b88ae1c0831e338474cc4c98))
+* expose __version__ ([da90d90](https://github.com/heyalexej/bidkit/commit/da90d90ef9ac50392b6443e23ece5186ff7a7dd5))
+* **generator:** accept ints for limit/offset query params ([351819c](https://github.com/heyalexej/bidkit/commit/351819c911ce180344faca7df5e44c2f10dd636e))
+* **generator:** clean and trim generated documentation text ([08e76bb](https://github.com/heyalexej/bidkit/commit/08e76bbc9f306a530bd29a124efdcc8560880468))
+* **generator:** drop content-type/language params; derive them automatically ([9fbf679](https://github.com/heyalexej/bidkit/commit/9fbf679b615d1669b0def54272e48875b1cef683))
+* **generator:** emit full method docstrings wrapped as multi-line blocks ([bfea77d](https://github.com/heyalexej/bidkit/commit/bfea77dc919f421161f139b85e0d204b30fb3e99))
+* **models:** open enums so unknown eBay values don't fail validation ([139499d](https://github.com/heyalexej/bidkit/commit/139499de0f1d90976c478f3662f7a75ef20d7cde))
+* **notifications:** verify inbound eBay push signatures ([2312a5b](https://github.com/heyalexej/bidkit/commit/2312a5b135aa47523169ba6bf01c668006ba3c9b))
+* **pagination:** add auto-paging helpers for list endpoints ([e8976b8](https://github.com/heyalexej/bidkit/commit/e8976b8971d75ed86fb979569da0c8b738bd70e1))
+* **pagination:** support responses that nest paging in a pagination object ([58d14ae](https://github.com/heyalexej/bidkit/commit/58d14ae01580aada814cbfa44eff1bfb863ce6e8))
+* rename package to bidkit ([8004e0e](https://github.com/heyalexej/bidkit/commit/8004e0e40ed59137f342825e7ef7ed4632633857))
+* **scripts:** --write-config persists minted tokens and expiries ([8d015b1](https://github.com/heyalexej/bidkit/commit/8d015b1b51b3ca3b1e0dbed47ed7014cbb67966b))
+* **scripts:** add interactive CLI for the OAuth consent flow ([2a08bce](https://github.com/heyalexej/bidkit/commit/2a08bcef4b1d6c067f905d1ec46ce9e429b9107c))
+* **signing:** add eBay digital-signature support for the Finances API ([8daca6c](https://github.com/heyalexej/bidkit/commit/8daca6c94e007f431333aa2cf2db14ea544534ba))
+* **transport:** add structured logging for requests, retries, and refreshes ([1f97b4e](https://github.com/heyalexej/bidkit/commit/1f97b4e74527f5f4d0a3eda4b897ba0aa2cb6d74))
+* **transport:** retry transient responses with rate-limit awareness ([f6dc107](https://github.com/heyalexej/bidkit/commit/f6dc107d1b20aafd2f15bcaef9e916c58b6c8897))
+
+
+### Bug Fixes
+
+* **auth:** coalesce concurrent token refreshes behind a per-key lock ([f48f8b3](https://github.com/heyalexej/bidkit/commit/f48f8b32ddb12e963fdc33e76cdd70f34fd74878))
+* **auth:** harden FileTokenCache against foreign files and concurrency ([821ee3a](https://github.com/heyalexej/bidkit/commit/821ee3a649bf07c6af356fcbaf31c6c75fa2a491))
+* **config:** tolerant signing-key pickup, sandbox parsing, explicit optional timeout ([6674822](https://github.com/heyalexej/bidkit/commit/6674822c73101782e3349c21f93509aae0e07138))
+* **generator:** complete the signing allowlist and stop eating literal angle-bracket prose ([9a108bd](https://github.com/heyalexej/bidkit/commit/9a108bd92f1515076a4a844816f300b80259c5b4))
+* normalize generated enum schemas ([a656567](https://github.com/heyalexej/bidkit/commit/a6565671ac03e5551920cc0e59367293e8db7c5e))
+* **notifications:** fetch public keys with application credentials ([6d36f1b](https://github.com/heyalexej/bidkit/commit/6d36f1b855f14b362555fa03793157b8adb2cb2d))
+* **packaging:** correct description and complete PyPI metadata ([028f64c](https://github.com/heyalexej/bidkit/commit/028f64c8b9d361e0e4a893882fcf2b29c5b38574))
+* **scripts:** guard sandbox/prod keyset mismatch and add non-interactive code input ([ef81127](https://github.com/heyalexej/bidkit/commit/ef81127bdb51c0027ee0887f8f32d0ab66ff4cb1))
+* **scripts:** restore the missing-scopes guard and the maintainer smoke bootstrap ([e429ac0](https://github.com/heyalexej/bidkit/commit/e429ac05e88ac333dd9d7aaa4e4a1283556589aa))
+* tenant-safe token cache, http-client ownership, schemaless GET typing ([b514e10](https://github.com/heyalexej/bidkit/commit/b514e1041a18767ee05d6a1879e35fa2a07b3e59))
+* **transport:** re-fetch the auth header on each retry attempt ([d03703d](https://github.com/heyalexej/bidkit/commit/d03703db7a02832b633e52682d2fe62a777f2259))
+* **transport:** sign only operations that eBay requires signatures for ([be215e4](https://github.com/heyalexej/bidkit/commit/be215e428afae4c6246929de452cd941b94239a3))
+
+
+### Performance Improvements
+
+* lazy-load generated model modules and defer Pydantic builds ([230a985](https://github.com/heyalexej/bidkit/commit/230a98580f3a880d036b8c8f8878325029dd58fa))
+
+
+### Documentation
+
+* add contributing guide with conventional-commit policy ([d03e3a6](https://github.com/heyalexej/bidkit/commit/d03e3a63a32037c6b9f90e3ce3b8b58bd6aeeac0))
+* add mkdocs site ([6235b91](https://github.com/heyalexej/bidkit/commit/6235b9155e34be16b35a330f3462c615846f3492))
+* add NOTICE and eBay attribution/disclaimer ([7f3f845](https://github.com/heyalexej/bidkit/commit/7f3f845ca0d201db383d32aeb2ac2b11ec97b37b))
+* add security policy, code of conduct, and issue templates ([5a86dcd](https://github.com/heyalexej/bidkit/commit/5a86dcd544784dd83b597134a07815774777a598))
+* **examples:** add config and signing-key templates for the scripts ([fbb0120](https://github.com/heyalexej/bidkit/commit/fbb0120c8c51fd35cd3de23df27e004f70a149fe))
+* **examples:** add runnable usage examples ([38b96b1](https://github.com/heyalexej/bidkit/commit/38b96b15993582b39879c61921cd4840fd1a6218))
+* **readme:** add implementation status overview of all APIs and versions ([05469d4](https://github.com/heyalexej/bidkit/commit/05469d42884ea69dcc4f743d6eabd3aef13b7c6b))
+* **readme:** document the two rate-limit lookups and their token types ([b82ba84](https://github.com/heyalexej/bidkit/commit/b82ba84d78f8e28d906c98823891912ca21294c9))
+* **readme:** document with_options and rate-limit lookups ([fb7cf92](https://github.com/heyalexej/bidkit/commit/fb7cf92e88b505fa9e13ab8a97cb0d494c20ff0e))
+* **readme:** restructure around install + quickstart ([ea749f8](https://github.com/heyalexej/bidkit/commit/ea749f86caa1196cc90fae1dd5369f5284540bdd))
+* seed changelog ([932c933](https://github.com/heyalexej/bidkit/commit/932c933ef9862c341d482467f5ea9a1b179af0b3))
+
+
+### Code Refactoring
+
+* **client:** tighten the public surface ([79e5858](https://github.com/heyalexej/bidkit/commit/79e585860cf9899193d1e71008439cf6d9518b11))
+
+## Changelog
+
+All notable changes to bidkit are documented here. The format follows
+[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) and entries are
+generated by [release-please](https://github.com/googleapis/release-please); versioning is
+[SemVer](https://semver.org/) with 0.x semantics (see CONTRIBUTING.md).
+
+No releases yet — 0.1.0 will be the first published version, covering the initial SDK:
+41 eBay REST APIs / 455 typed operations, sync + async clients, OAuth with cached refresh,
+retries, pagination helpers, and Finances API digital signatures.

bidkit-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+heyalexej@gmail.com. All complaints will be reviewed and investigated promptly
+and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

bidkit-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,91 @@
+# Contributing to bidkit
+
+Thanks for helping out! This guide covers the dev setup, the commit conventions, and how the
+code generation works.
+
+## Development setup
+
+bidkit uses [uv](https://docs.astral.sh/uv/) exclusively:
+
+```bash
+uv sync --extra dev        # create .venv and install everything
+uv run pytest              # tests
+uv run ruff check .        # lint
+uv run ruff format .       # format
+uv run ty check src tests  # type check
+```
+
+All four must pass before a PR is ready; CI enforces them on Python 3.11–3.14.
+
+Optional but recommended:
+
+```bash
+uvx pre-commit install --install-hooks   # lint/format + commit-message checks on commit
+```
+
+## Commit messages: Conventional Commits 1.0.0
+
+Every commit message MUST follow [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/).
+Releases and the changelog are generated from them (release-please), so the format is
+load-bearing, not cosmetic. CI also validates PR titles, which become the squash-commit
+message.
+
+```
+<type>(<optional scope>): <description>
+
+[optional body]
+
+[optional BREAKING CHANGE: footer]
+```
+
+| Type | Use for | Release effect |
+|------|---------|----------------|
+| `feat` | new user-facing capability | minor bump |
+| `fix` | bug fixes | patch bump |
+| `perf` | performance improvements | patch bump |
+| `refactor` | code change with no behavior change | none |
+| `docs` | documentation only | none |
+| `test` | tests only | none |
+| `build` | packaging/build system | none |
+| `ci` | CI configuration | none |
+| `chore` | everything else | none |
+
+Common scopes: `auth`, `transport`, `retry`, `pagination`, `signing`, `config`, `errors`,
+`models`, `generator`, `packaging`, `scripts`, `readme`, `examples`.
+
+Breaking changes: add `!` after the type/scope (`feat(transport)!: ...`) **and** a
+`BREAKING CHANGE:` footer describing the migration.
+
+## Code generation
+
+The resource classes and Pydantic models under `src/bidkit/generated/` are **generated —
+never edit them by hand** (CI fails on drift). To change them, change the generator or the
+specs and regenerate:
+
+```bash
+uv run --extra dev scripts/generate_openapi.py
+```
+
+Pipeline: raw eBay OpenAPI contracts in `specs/ebay/` → compatibility patches
+(`preprocess_spec`) → normalized specs in `specs/normalized/` (git-ignored intermediate) →
+`datamodel-code-generator` for models + a local renderer for the resource classes.
+
+To update the specs themselves, download the current contracts from
+[developer.ebay.com](https://developer.ebay.com/) and place them via
+`scripts/sync_ebay_specs.py`, then regenerate. Note that the spec files are © eBay Inc.
+under the eBay API License Agreement (see [NOTICE](NOTICE)).
+
+## Pull requests
+
+- Keep PRs focused; one logical change per PR.
+- PR titles must be valid Conventional Commit headers (they become the squash commit).
+- Add or update tests for behavior changes; tests are wire-level (`httpx.MockTransport`),
+  fast, and offline — no eBay credentials needed.
+- Don't commit anything derived from real credentials, tokens, or account data.
+
+## Versioning & releases
+
+bidkit follows [SemVer](https://semver.org/) with 0.x semantics: while the major version
+is 0, `feat`/breaking changes bump the **minor** version and fixes bump the **patch**.
+Releases are cut by release-please from the commit history; maintainers merge the release
+PR and CI publishes to PyPI. 1.0.0 will be tagged once the public surface has settled.