putio-sdk-dev

put.io SDK development

Apply put.io SDK conventions after the target repository's own guidance.

Shared defaults

• Treat each SDK as a public package, not an internal compatibility layer.
• Treat TypeScript as the canonical full put.io API client, not just the richest reference.
• Keep every public surface domain-first, strongly typed, and native to its host language.
• Update request, response, and typed error contracts together.
• Prove behavior with deterministic tests plus safe live tests when real API behavior matters.
• Keep Swift and Kotlin scope narrower than TypeScript only when product usage justifies it.

Source order

When sources disagree, prefer local backend behavior and tests, current first-party app usage, maintained SDKs, archived clients, then published API documentation.

Start with sources present in the target repository. Add backend or first-party consumer evidence only when it is authorized and available.

Widen SDK surfaces only when real app use and verified backend behavior justify it.

Start

Read only what you need:

• nested guidance from git ls-files '*AGENTS.md' '*SKILL.md'
• the canonical verify and live-test commands from README.md, AGENTS.md, or docs/*
• SDK vision for scope rules, shared engineering principles, and the verification policy; product direction lives in the Frontend hub in the put.io Notion workspace (page: Products)
• patterns for typed boundaries, error mapping, pagination, and live-test layering
• language notes for TypeScript, Swift, or Kotlin-specific guidance
• release security when publishing, signing, releasing, or building distributable binaries

Target-repo guidance, matching repo-local skills, the repo's canonical verify command, and its delivery or supply-chain policy override this shared skill.

Workflow

1. Inspect the target namespace and the shared transport or client runtime.
2. Check backend behavior, backend tests, and current app usage before widening or changing a contract.
3. Update typed request input, response parsing, and operation-specific error mapping together.
4. Add or update deterministic coverage for request shaping, parsing, errors, and public client contracts.
5. Add or refresh safe live verification when production behavior matters and the surface is reversible.
6. Keep multiple public clients aligned when the repo exposes more than one interface style.
7. Run the owner's documented checks for the affected contracts and their dependents, including installed-package and downstream-consumer proof when relevant. Run the full canonical gate when mandated, shared inputs changed, or focused coverage is uncertain.
8. Update package-facing docs and release notes when the public surface changes.

Endpoint changes

For a new or changed endpoint, discover the tracked source, test, fixture, and consumer paths first. Search only paths that exist:

git ls-files -z -- \
  ':(glob)**/src/**' \
  ':(glob)**/test/**' \
  ':(glob)**/tests/**' \
  ':(glob)**/Tests/**' \
  ':(glob)**/Sources/**' \
  ':(glob)**/docs/**' \
  ':(glob)**/fixtures/**' \
  ':(glob)**/Package.swift' \
  ':(glob)**/build.gradle' \
  ':(glob)**/package.json' |
  xargs -0 rg -n "route_name|endpoint_path|field_name" -- || true

Repeat this search from a backend, fixture, or first-party consumer checkout only when that source is available and authorized.

Then update the SDK in this order:

1. request input type or query model
2. response parser or native decode model
3. operation-specific error mapping
4. public client method or namespace export
5. unit tests for request, response, and error behavior
6. safe live test when the endpoint behavior cannot be proven locally
7. README, API docs, or release notes when the public surface changed

Verification

Use the owning repository's documented commands. Do not infer a Vite+, Gradle, or Make entrypoint from this shared skill.

An SDK repo should expose both:

• a default deterministic unit-test path that is safe for CI and local iteration
• a separate documented live-test path for real API verification

If one of those layers is missing, treat it as a repo gap to document or fix rather than silently accepting a weaker verification story.

For runtime verification, prefer the repo's documented live-test entrypoints and follow the shared-account safety rules in that repo's testing docs.

Boundaries

• Verify backend contracts with current docs, source, fixtures, or live probes rather than old SDKs alone.
• Claim full verification only when the unit, fixture, and live layers that matter for the change were exercised.
• Keep live coverage against shared accounts non-destructive.
• Merging to main is delivery, including the release CI starts from it. Ask before publishing or writing a release by hand, coverage-threshold changes, and live writes that are not reversible.
• Preserve naming, parity, and type-safety unless a documented reason justifies a change.
• Keep repo-specific implementation guidance in that repo's AGENTS.md or docs/*
• Generic SDK work, end-user application code, and CLI consumer operations are outside this skill.