Develop Opensecret SDK

Develop the Maple SDK

Work from MaplePrivacyLabs/Maple/sdk. Read the repository-root AGENTS.md, sdk/README.md, the affected implementation and tests, and the root .github/workflows/sdk-*.yml files relevant to the change.

The SDK source is part of the Maple repository, but its TypeScript and Rust package boundaries remain independently versioned and publishable:

• src/ builds @mapleai/sdk for browser and React consumers.
• rust/ builds the maple-sdk crate (imported as maple_sdk) for native consumers.
• apps/maple-research/frontend/package.json is authoritative for whether Maple's browser client consumes a published TypeScript version or the in-tree file:../../../sdk package.
• Research native clients, Maple Agent, and proxy/ select their Rust SDK through their own manifests and lockfiles. Research iOS and Android use the Rust SDK for native OAuth; the embedded proxy and Goose remain desktop-only.

Follow the consumer version policy. To ship an SDK change to clients, follow the rollout order: SDK PR with version bump, publish, consumer pins, isolated app bump, release. Prefer published pins without upgrading unrelated consumers. Local links are allowed during active development, including on master; a registry-pinned client build does not exercise an SDK source edit. Test an affected consumer with the local SDK when that integration is part of the change.

Do not commit, push, open a PR, publish, or alter Maple's application dependency wiring unless the user authorizes that action.

Keep protocol ownership clear

OpenSecret owns authentication and authorization truth, public HTTP semantics, provider policy, persistence, and usage accounting. The SDKs own client-side attestation, encrypted sessions, typed contracts, authentication state, and safe transport adaptation. Maple owns application presentation and local device behavior.

For a public contract change, inspect services/opensecret/ at the same monorepo revision and both SDK implementations when they expose the affected behavior. Preserve old-client/new-server and new-client/old-server compatibility where clients can update independently. Do not weaken HTTPS, PCR validation, attestation, key exchange, randomness, retry safety, or sanitized errors to accommodate a caller.

Develop and validate

Use the SDK's pinned Nix shell. For TypeScript/React work:

nix develop --no-update-lock-file -c bun install --frozen-lockfile --ignore-scripts
nix develop --no-update-lock-file -c bun run format:check
nix develop --no-update-lock-file -c bun run build

For tests without service fixtures, use the credential-free selection in .github/workflows/sdk-typescript.yml. An unfiltered bun test also collects integration tests that require a configured backend and test identities; use sdk-integration.yml for that complete local-stack setup.

For Rust work:

nix develop --no-update-lock-file -c bash -lc '
  set -euo pipefail
  cd rust
  cargo fmt --all -- --check
  cargo clippy --locked --all-targets --all-features -- -D warnings
  cargo test --locked --all-features --lib
  cargo doc --locked --no-deps --all-features
'

Run focused tests while iterating, then match the root path-scoped workflows: sdk-typescript.yml, sdk-rust.yml, and sdk-supply-chain.yml as applicable. The repository pre-commit hook runs sdk/.githooks/pre-commit in this shell when SDK files are staged: the Rust format, Clippy, --lib tests, and docs, and the TypeScript format, build, and top-level unit tests. It never runs the integration suites or cargo-deny. When the change reaches backend behavior, authentication, or the encrypted wire contract, also match sdk-integration.yml. It starts disposable PostgreSQL and the in-tree services/opensecret/ backend from the same checkout, then tests both SDK implementations without a hosted development server. Inspect backend changes and run its component validation when the compatibility contract reaches them; there is no separate integration revision to advance.

Provider-spending tests remain opt-in through RUN_LIVE_AI=1 and require explicit credential, egress, and cost authorization. Both SDKs use signed-PCR histories under MaplePrivacyLabs/Maple/master/services/opensecret/, with the existing verification key and separate development/production policies. Keep the legacy OpenSecretCloud/opensecret histories available for older clients through the backend's manual compatibility procedure. Source changes do not publish SDKs or update installed clients.

Before handoff, inspect package boundaries as applicable:

bun run pack
cargo package --locked --manifest-path rust/Cargo.toml

These commands validate package contents; they do not publish them. For Rust SDK changes, also run the root scripts/ci/verify-local-rust-deps.sh check and the applicable desktop/proxy validation. Check its selected SDK source before claiming Maple consumes the result.