Feat/telemetry

[Arshia-r-m]

No description provided.

[moakilodash]

looks good to me.

[moakilodash]

though i suggest using v0.2.0 as this has breaking changes.

[bitwalt]

Telemetry review — SDK #26

Blocker

1. Version — breaking change shipped as patch. create()/from_config going async is a hard breaking change, but the version stays 0.1.6 and the X-Kaleido-SDK header too. Every existing caller breaks on a patch bump. → 0.2.0 + sync the header.

Majors

2. http-client — no TLS guard on attribution headers. Authorization: Bearer kld_live_... + install/session headers are attached regardless of scheme. A http:// base URL leaks the live API key in cleartext. Refuse to attach Authorization over non-https (allow an explicit allow_insecure opt-out for localhost).

3. identity.ts — browser install-id is a persistent supercookie. localStorage["kld_install_id"] is a stable cross-session device identifier sent on every request with no consent — privacy/GDPR concern for a partner-embedded SDK. Make persistence opt-in or default to in-memory in browsers.

4. _identity.py — TOCTOU on install-id file. write_text then chmod 0600 leaves the file briefly world-readable. Use os.open(..., O_CREAT|O_EXCL, 0o600). Also: the TS random fallback to Math.random() when crypto is absent should warn/throw.

Identity design itself is reasonable; the async create() conversion is clean. Main fixes: semver bump and the cleartext-key TLS guard before this leaves Draft.

[Copilot]

Pull request overview

Adds telemetry/attribution support to both the Python and TypeScript SDKs. The Maker API now receives persistent install IDs, per-client session IDs, and an SDK version header, with HTTPS enforcement (and a localhost/explicit allowInsecure escape hatch) for any request that carries an API key or attribution. To support filesystem/browser-storage lookups during identity resolution, KaleidoClient.create() / from_config() becomes async in both SDKs — a documented breaking change.

Changes:

• New identity module in each SDK that generates and persists install IDs (Node file at ~/.kaleido/install_id with 0600; browser memory-only by default, with opt-in localStorage persistence) and per-session UUIDs.
• HttpClient now emits Authorization, X-Kaleido-Install-Id, X-Kaleido-Session-Id, and X-Kaleido-SDK headers for Maker requests, refusing apiKey over non-HTTPS unless local or allowInsecure.
• KaleidoClient.create() becomes async; examples, READMEs, and tests are updated accordingly; CHANGELOG documents the breaking change.

Reviewed changes

Copilot reviewed 42 out of 42 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
typescript-sdk/src/identity.ts	New install/session ID generation and pluggable storage (memory/localStorage/Node FS)
typescript-sdk/src/http-client.ts	Adds Maker attribution headers + HTTPS guard with localhost/allowInsecure exemptions
typescript-sdk/src/client.ts	create() is now async; resolves install + session IDs and passes them to HttpClient; hard-codes SDK_VERSION = '0.1.6'
typescript-sdk/src/types/config.ts	New allowInsecure, installId, installIdStore, persistInstallId config fields
typescript-sdk/src/index.ts, src/logging.ts	Exports identity helpers; doc snippets updated to await
typescript-sdk/tests/**	New identity unit tests; HttpClient header/HTTPS tests; integration/type-safety tests adapted to async create()
typescript-sdk/examples/*.ts	Updated to await KaleidoClient.create(...) and read optional KALEIDO_API_KEY; prettier reformatting
typescript-sdk/README.md	Documents attribution behavior, local-dev override, and browser persistence opt-in
python-sdk/kaleido_sdk/_identity.py	New install/session ID helpers with atomic 0o600 file creation and asyncio.to_thread wrapper
python-sdk/kaleido_sdk/_http_client.py	Splits default vs maker headers; adds HTTPS/localhost/allow-insecure validation; emits attribution headers per request
python-sdk/kaleido_sdk/client.py	create() and from_config() are now async; resolve install/session IDs
python-sdk/kaleido_sdk/types.py	Adds allow_insecure, install_id, session_id fields to KaleidoConfig
python-sdk/tests/**	New identity/header tests; fixtures updated to bypass async create() by constructing the client directly
python-sdk/examples/*.py	Updated to await KaleidoClient.create(...) and read optional KALEIDO_API_KEY
python-sdk/README.md, kaleido_sdk/init.py	Documents async usage and attribution behavior
CHANGELOG.md	Records the new attribution features and the async breaking change

Comments suppressed due to low confidence (1)

python-sdk/kaleido_sdk/client.py:141

• The replace(config, install_id=..., session_id=...) here unconditionally overwrites the caller's config.install_id with whatever load_or_create_install_id returns. That branch already handles the override case (returning it unchanged), so behavior is correct today, but it does mean any explicit install_id passed via the dataclass goes through file-IO resolution on a worker thread. More importantly, this path silently ignores the new allow_insecure setting at validation time — the only validation happens lazily on the first Maker request inside _build_maker_headers. Consider validating (base_url, api_key, allow_insecure) once during client construction so misconfigurations fail fast rather than on the first attributed call.

        resolved_config = replace(
            config,
            install_id=await load_or_create_install_id(config.install_id),
            session_id=config.session_id or generate_session_id(),
        )
        return cls(resolved_config)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[moakilodash]

this looks great, idk if the same could be done for the python sdk as well or not @Arshia-r-m?

[Copilot]

Pull request overview

Copilot reviewed 42 out of 42 changed files in this pull request and generated 5 comments.