Epic: align SDK contracts, endpoint parity, and Knip

[altaywtf]

Goal

Make @putdotio/sdk a trustworthy, endpoint-complete public client whose contracts stay aligned with the put.io API.

Consumer call sites are prioritization evidence only; consumer adoption belongs to the consuming repository. Backend-wide route inventory and comparison remain private; this repository receives only public-safe SDK gaps and contract changes discovered by that process.

Current status

The public SDK implementation work is complete: confirmed contract fixes, audited endpoint slices, Promise token lifecycle, compile-time and runtime package-surface checks, blocking Knip gates, a 25-route public evidence matrix, full request-boundary validation, deterministic public-safe fixtures, one canonical typed operation tree, and a guard requiring every future canonical operation to declare its boundary.

The repository-side SOPS/age consumer is also complete and proven locally with real ciphertext plus a fresh-token account/tunnel live smoke. The remaining work is the environment-owned credential delivery for a scheduled or manually dispatched live lane and deeper fixtures for risky or branch-heavy behavior. No CI credential material or private inventory belongs in this public repository.

Completed

• Align known response/error contracts and canonical playback routes (#109, #110).
• Add audited app-password, folder-sort, podcast, file, transfer, and OAuth operations (#119-#123, #132-#134).
• Add Promise-client setAccessToken(string | undefined) with invocation-time token snapshots (#116, #117).
• Add packed compile-time contracts, exact runtime exports, and blocking source/packed Knip checks (#112-#114, #125, #126).
• Validate every public transport or config-backed input boundary before transport, including strict excess-property decoding and zero-request failure coverage (#127, #128, #135-#142, #153-#161, #163).
• Add and resolve the portable 25-route public evidence matrix (#129, #130, #147).
• Remove unsupported/deleted v11 contracts and publish migration guidance (#148).
• Add the focused fresh-token live runner (#151).
• Add deterministic sanitized transport/response fixtures (#164).
• Derive Effect and Promise clients from one canonical typed operation tree (#165, closes #152).
• Require every canonical operation to declare a validated, input-free, or pure boundary; reject malformed/unclassified leaves and check generic Promise adaptations at runtime (#166).
• Replace provider-specific secret export with a fail-closed SOPS ciphertext input, TypeScript renderer, fixed ignored mode-0600 output, and documented local live workflow (#167-#169).
• Harden release commit identity without a hardcoded bot user ID (#170).

Remaining live confidence work

• Add dedicated live fixtures for risky auth/account mutations and branch-heavy file/transfer behavior.
• Add a scheduled or manually dispatched credentialed workflow using runner-owned secretops-vault/age delivery for the existing PUTIO_SDK_TYPESCRIPT_SOPS_FILE contract.
• Keep ciphertext location and age identity environment-owned, keep runtime tokens ephemeral, and report only public-safe contract drift here.

Resume point

The immediately actionable repository work is deeper safe live fixtures. The credentialed workflow is blocked on runner-owned secretops-vault/age delivery; do not invent repository secrets, copy private ciphertext, or reintroduce Infisical.

Acceptance gates

All applicable changes must pass:

vp run verify
vp run lint:package
vp run test:compat

• Every supported operation resolves on both Effect and Promise clients, except explicit Promise-only lifecycle/pure-adapter methods.
• Every public request boundary validates runtime input before transport.
• Conditional and public package types are covered by packed positive and negative checks.
• Repository tooling does not log or persist credentials, access tokens, or one-time passwords.
• Breaking removals and tightened contracts have migration guidance and an explicit release decision.

Boundaries

• Do not publish a backend route extractor, complete backend route inventory, private route classifications, or private-checkout assumptions here.
• Do not add internal/admin/service endpoints to the public SDK.
• Do not emulate unsupported API filtering client-side.
• Do not make public PR CI depend on private repositories or credentials.
• Do not move consumer adoption work into this repository.
• Account settings intentionally remain JSON encoded; the API maps JSON objects into its request form while preserving nested settings.

[altaywtf]

Implementation has started with stack #111:

1. fix(sdk): align backend response contracts #109 aligns valid backend response/error contracts.
2. fix(files): use canonical playback progress routes #110 switches playback progress to the canonical POST routes.

Both PRs are ready for review. The top of the stack passes the canonical verify gate, package lint, and packed Node/browser/Bun compatibility checks.

[altaywtf]

A second independent implementation stack is ready: stack #115.

1. chore(knip): clean source analysis config #112 cleans the source Knip configuration and makes the Vite+ catalog authoritative.
2. chore(knip): analyze packed production output #113 analyzes the packed production artifact, including gitignored dist/**.
3. ci(knip): make unused-code checks blocking #114 makes both Knip graphs blocking and removes the duplicate unit-test execution.

The top passes vp run verify, package lint, and packed Node/Chromium/Firefox/WebKit/Bun compatibility checks. The production trace confirms effect is consumed from dist/index.js, so it remains unsuppressed.

[altaywtf]

Promise token lifecycle work is ready in stack #118.

1. feat(client): support mutable promise access tokens #116 adds setAccessToken(string | undefined) with invocation-time token snapshots and one reused managed Effect runtime.
2. docs(client): explain promise token snapshots #117 documents replacement, clearing, immutable URL config, and the in-flight operation contract.

Deterministic tests cover initial/replaced/cleared tokens before and after runtime creation plus a concurrent in-flight change. The packed external Node fixture compiles the public type and observes the replacement token in the generated request URL; the full Node/browser/Bun compatibility matrix passes.

[altaywtf]

The endpoint stack now includes app-specific passwords in stack #111:

3. feat(account): add app-specific passwords #119 adds account.appSpecificPasswords.{create,list,delete,deleteAll} to Effect and Promise clients.
4. docs(account): document app-specific passwords #120 documents the consumer lifecycle and one-time password boundary.

The implementation follows the audited response contract: list never exposes plaintext passwords, last_used_at is nullable, ip_address is null or masked, and create preserves typed backend failures including structured extra.limit. Invalid notes and IDs fail before transport. Canonical verification, package lint, and packed Node/browser/Bun compatibility pass.