keysat-root/PUBLISH_SDKS_CHECKLIST.md

# Make the SDKs actually installable by external developers + LLMs

The KEYSAT_INTEGRATION.md doc tells consumers to `npm install
@keysat/licensing-client`, `pip install keysat-licensing-client`, and
`cargo add keysat-licensing-client` (or git fallbacks). Today none of
those paths work cleanly — all three SDK repos are private on GitHub,
and none of the packages are published to their respective registries.

This doc is the punch list to fix that. Everything below is a one-time
setup. Once done, integration on the consumer side becomes a single
install command.

## TL;DR

For each SDK repo, do **one of two** things:

- **Option A (best): publish to the package registry.** Repo can stay
  private; the published artifact is what consumers install.
- **Option B (good): make the GitHub repo public.** Consumers install
  via `npm install github:...` / `pip install git+...` / cargo `git =
  "..."`. Free, no account setup required.

Option A is the right long-term answer (faster installs, fewer cross-
service auth issues). Option B unblocks the LLM-wiring test cleanly
without commiting to a registry yet.

## TS SDK — `@keysat/licensing-client`

### Option A: publish to npm

```sh
cd ~/path/to/Licensing/licensing-client-ts

# 1) Login (one-time per machine).
npm login

# 2) Verify the build works locally before publishing.
npm install
npm run build
npm test

# 3) Publish. The first publish under a new scope needs --access public.
npm publish --access public

# 4) Sanity check.
npm view @keysat/licensing-client
```

The `prepublishOnly` script in `package.json` already builds + tests
before publish; the line above just runs it explicitly first to catch
any failures locally rather than on the registry side.

### Option B: make the GitHub repo public

On github.com → `keysat-xyz/keysat-client-ts` → Settings → General →
Danger Zone → Change repository visibility → Public.

A `prepare` script was added to `package.json` (this version) so git-
installs build `dist/` automatically. Without that script, consumers
got `Cannot find module './dist/index.cjs'` at import time. Confirm
your local `package.json` has both:

```json
"scripts": {
  "build": "tsup src/index.ts --format esm,cjs --dts --clean",
  "test": "vitest run",
  "prepare": "npm run build",
  "prepublishOnly": "npm run build && npm test"
}
```

After making the repo public, verify in a clean dir:

```sh
mkdir /tmp/keysat-test && cd /tmp/keysat-test
npm init -y
npm install github:keysat-xyz/keysat-client-ts
node -e "console.log(require('@keysat/licensing-client'))"
```

Should print the module exports without errors.

## Python SDK — `keysat-licensing-client`

### Option A: publish to PyPI

```sh
cd ~/path/to/Licensing/licensing-client-python

# 1) Build.
python3 -m pip install --upgrade build twine
python3 -m build

# 2) Login (one-time): create an API token at https://pypi.org/manage/account/token/
# Save it to ~/.pypirc or pass via env.

# 3) Upload.
python3 -m twine upload dist/*
```

### Option B: make the GitHub repo public

On github.com → `keysat-xyz/keysat-client-python` → Settings → Public.
No additional changes needed — pip installs pure-Python packages from
git directly.

Verify:

```sh
python3 -m venv /tmp/keysat-py-test && . /tmp/keysat-py-test/bin/activate
pip install git+https://github.com/keysat-xyz/keysat-client-python.git
python3 -c "from keysat_licensing_client import Verifier; print(Verifier)"
```

## Rust SDK — `keysat-licensing-client`

The crate was renamed from `licensing-client` to `keysat-licensing-client`
in `Cargo.toml` for consistency with the TS / Python names. The
integration doc references `keysat-licensing-client`.

### Option A: publish to crates.io

```sh
cd ~/path/to/Licensing/licensing-client-rust

# 1) Login (one-time): get token from https://crates.io/me.
cargo login

# 2) Sanity check.
cargo build --no-default-features --features offline
cargo build --no-default-features --features online
cargo test
cargo publish --dry-run

# 3) Publish.
cargo publish
```

### Option B: make the GitHub repo public

On github.com → `keysat-xyz/keysat-client-rust` → Settings → Public.

Verify:

```sh
cd /tmp && cargo new keysat-rust-test && cd keysat-rust-test
cat >> Cargo.toml <<'EOF'
keysat-licensing-client = { git = "https://github.com/keysat-xyz/keysat-client-rust.git" }
EOF
cargo build
```

## Recommended order

If you're just doing the LLM-wiring test on youtube-summarizer:

1. **Make the three SDK repos public** (Option B for all three). Five
   clicks on github.com. Free.
2. Re-run the LLM test against youtube-summarizer. The integration doc
   now tells the LLM both prerequisites (public repo + prepare script);
   the install commands should now succeed in a clean Docker.
3. Defer the registry publish (Option A) to the public-launch checklist.

If you're getting close to public launch:

1. Publish all three to their registries (Option A for all three).
2. Keep the GitHub repos visible-or-not as you prefer; consumers don't
   need them once the registry artifact exists.

## What broke and why

The downstream integrator ran into two real bugs in their own clean
build environment:

1. **TS SDK installed from GitHub produced an empty package.** The
   `dist/` directory is gitignored (correct), but there was no
   `prepare` script to rebuild on git-install (incorrect). `main`
   pointed at `./dist/index.cjs`, which didn't exist. Fixed: added
   `"prepare": "npm run build"` to `package.json`.
2. **All three SDK repos were private.** The integration doc said to
   install from GitHub as the fallback. Private repos require auth
   credentials, which Docker / CI / fresh dev machines don't have.
   Fix: flip the repos public.

Both bugs only manifest when the consumer runs in a clean environment —
they're invisible during local dev because (a) `dist/` is built in your
own working tree, (b) you have GitHub auth set up. The downstream LLM
caught both correctly.