GeezerVison

Poll cached full scan results until ready (#115)

* Poll cached full scan results

Wait for cached full scan artifacts and bound retries so SDK callers receive completed results or a clear timeout.

Assisted-by: Codex: GPT-6

* Fix cached scan CI coverage

Exercise the cached stream through the real SDK transport and bump the package version to an unpublished release.

Assisted-by: Codex: GPT-6

* Tighten full scan polling and document it

Stop polling once the next attempt could not start before the deadline instead of sleeping out the budget, give each request the configured timeout rather than a fixed 30s cap, and document the polling parameters in the README.

---------

Co-authored-by: lelia <[email protected]>

Release `v3.6.1`: patched `certifi`, `uv` and `virtualenv`; require `…

…certifi>=2026.10.19` (#120)

* chore(release): 3.6.1 with patched certifi, uv and virtualenv

Cut a release that ships the Dependabot security bumps merged since 3.6.0
(#112, #116, #117, #118, #119).

The release build toolchain in setup-hatch still pinned virtualenv 21.7.13
and hatchling 1.32.0, because Dependabot updates uv.lock but not the pip
pins inside the composite action. Sync them to the locked virtualenv
21.14.7 and the [build-system] hatchling 1.32.4 so published artifacts are
built with the patched versions.

* Require certifi>=2026.10.19

requests takes its CA bundle from certifi, and socketdev didn't constrain
it, so pip could leave consumers on a bundle that trusts the compromised
eMudhra intermediate CAs. A floor rather than an exact pin, so later
trust-store fixes still reach them.

Make every API-sourced enum forward-compatible, and detect drift proa…

…ctively (#107)

* feat(enums): make every API-sourced enum forward-compatible

Five of the six enums populated from API responses coerced strictly, so a
value the backend added would raise ValueError inside from_dict and empty an
entire response rather than degrade one field. That is the mechanism behind
issue #78 and the unknown `generic` purl type; each was fixed on the single
enum that fired, leaving the rest holding the same landmine.

All five now fall back to a documented member and log the unrecognized value.
The fallbacks are chosen rather than convenient: SocketIssueSeverity and
DiffType gain an explicit UNKNOWN, since guessing an existing level would
either hide a real finding or invent one, and SecurityAction defers.

A generalized test discovers every enum in the package, including ones added
later, and fails if any raises. A drift check compares the enums against the
public OpenAPI spec; it found 10 purl types the SDK was missing, which are
added here.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

* docs: drop Linear IDs from test docstrings and comments

Ticket identifiers belong in the pull request description, not in code that
outlives the ticket. The GitHub issue reference in the purl test docstring
stays, since that resolves for anyone reading the repository.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

* chore: add .gitattributes and normalize line endings to LF

Eleven Python files were committed with CRLF, socketdev/__init__.py among them.
Any tooling that reads and rewrites one of those files converts it to LF on the
way out, so a two-line edit arrives as a whole-file diff with the real change
buried in it. That happened while writing the enum change in this same branch.

This normalizes all of them once and pins the setting so it cannot recur.
Reviewable with `git diff -w`, which shows only .gitattributes: no file content
changed, and the unit suite is unaffected.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

* fix(enums): keep ScanType strict, it only ever builds requests

ScanType never parses an API response. FullScanParams.to_dict() is urlencoded
onto the create-scan query string, so giving it a _missing_ fallback meant a
caller typo silently shipped scan_type=unknown to the API instead of failing at
construction. The same from_dict already passes integration_type through
uncoerced for that reason.

It is now recorded in REQUEST_ONLY_ENUMS, the opt-out the invariant test always
had and this branch had left empty, and a new test asserts request-only enums
keep raising so the exemption cannot quietly become a skip.

Also bumps actions/setup-python in the new workflow to v7.0.0, matching the pin
already used by .github/actions/setup-sfw.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

---------

Co-authored-by: Claude Opus 5 (1M context) <[email protected]>

Bound runtime dependency ranges and pin build backend (#103)

* Bound runtime dependency ranges and pin build backend

Add version bounds to the runtime dependencies: requests was fully
unbounded and typing-extensions had no upper bound, so a fresh install
could resolve either to any just-published release. As a library,
socketdev declares bounded ranges rather than exact pins - exact pins
in package metadata would conflict with consumers that pin their own
dependencies, including socket-python-cli, which pins its entire
runtime closure (socketsecurity 2.5.10+) and relies on this package's
ranges staying compatible.

Floors match the versions already resolved and tested in uv.lock;
ceilings exclude the next major. Also pins the hatchling build backend
used for sdist builds. Dependabot (uv ecosystem, 7-day cooldown)
already keeps the lockfile fresh within these bounds.

Companion to the socket-python-cli dependency pinning work (CE-359).

Co-Authored-By: Claude Fable 5 <[email protected]>
Signed-off-by: lelia <[email protected]>

* Add CHANGELOG.md

Seed a changelog in the socket-python-cli format, starting at 3.4.3,
with a pointer to GitHub releases for earlier history.

Co-Authored-By: Claude Fable 5 <[email protected]>
Signed-off-by: lelia <[email protected]>

* Backfill changelog from GitHub release notes

Import all 53 published releases (v1.0.15 through v3.4.2) from the
auto-generated GitHub release notes: one dated entry per version,
pre-releases labeled, body headings demoted one level so version
headings stay the top-level structure.

Co-Authored-By: Claude Fable 5 <[email protected]>
Signed-off-by: lelia <[email protected]>

* Bump version to 3.5.0

The new requests floor is a newly binding constraint for consumers on
older versions, so this warrants a minor bump rather than a patch.

Co-Authored-By: Claude Fable 5 <[email protected]>
Signed-off-by: lelia <[email protected]>

* Fix static project version and use a Python 3.9-compatible hatchling

The [project] version in pyproject.toml is static ([tool.hatch.version]
is only consulted when version is declared dynamic), so bumping
version.py alone left the packaging metadata and uv.lock at 3.4.2.
Set the static version to 3.5.0 to match.

Pin hatchling to 1.27.0 instead of 1.31.0: 1.28+ requires Python 3.10,
while this package's requires-python still includes 3.9, so the newer
pin would break sdist builds on 3.9.

Addresses PR#103 review findings.

Co-Authored-By: Claude Fable 5 <[email protected]>
Signed-off-by: lelia <[email protected]>

* Declare the version dynamic so version.py is the single source of truth

Per review on PR#103: with dynamic = ["version"], hatchling reads
socketdev/version.py (the file version-check.yml already validates),
so packaging metadata can never drift from the checked version again.

Co-Authored-By: Claude Fable 5 <[email protected]>
Signed-off-by: lelia <[email protected]>

---------

Signed-off-by: lelia <[email protected]>
Co-authored-by: Claude Fable 5 <[email protected]>

fix(purl): expose fail-open batch params and harden dedupe (#98)

* fix(purl): expose fail-open batch params and harden dedupe (CE-360)

purl.post() defaulted to the batch API's fail-open behavior with no way to
opt out: unresolved input purls are silently omitted from the response, so
callers could not tell "clean" from "dropped". Add typed poll/timeout_sec/
alerts/purl_errors params (None => omit, preserving the fail-open default for
existing callers) plus a strict=True guard that raises APIPartialResponse when
requested purls are missing from the response.

Also harden Dedupe.consolidate_and_merge_alerts to use .get() for
key/type/severity/action so synthetic pendingScan/notFound status rows (built
server-side from a minimal {type, key} base) no longer raise KeyError.

Bump 3.3.0 -> 3.4.0.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
Signed-off-by: lelia <[email protected]>

* fix(purl): preserve error stream records

* fix(purl): define strict response semantics

* fix(purl): preserve legacy boolean strings

---------

Signed-off-by: lelia <[email protected]>
Co-authored-by: Claude Opus 4.8 <[email protected]>

Add transient-error classification to APIFailure (#93)

* Add transient-error classification to APIFailure

API.do_request now records the HTTP status code on every exception it
raises (status_code attribute), and APIFailure gains
is_transient_error(): True for gateway/connection-level failures
(HTTP 408/502/503/504, dropped or reset connections, client-side
timeouts) where retrying the same request may succeed, False for
deterministic errors (400/401/403/404/429, wrapped unexpected errors).

Classification is based on the recorded status code rather than
exception class identity or message text, so it stays correct if a
status code gains a dedicated subclass later.

Motivated by SocketDev/socket-python-cli#232: the CLI retries transient
full-scan upload failures and previously had to parse the status code
out of catch-all APIFailure message text.

* Hardcode 502 in APIBadGateway instead of accepting a status_code

The class definitionally represents a 502, so there is no reason for
construction sites to pass (or be able to override) the status.

Add `sfw` aggregator gate to enforce required CI checks (#89)

* ci: add Socket Firewall aggregator gate; bump 3.2.0 -> 3.2.1

Add a single sfw-gate job (if: always(), needs the conditional inspect +
free/enterprise smoke + workflow-notice jobs) that fails only when an
upstream job failed or was cancelled -- success and skipped both pass.

This is the check intended to become the required status check on main:
the smoke jobs are conditional (deps-changed gates them, and exactly one
of free/enterprise runs per PR), so none can be required directly -- a
required check whose job is if-skipped is never created and blocks merge
forever. The gate is green when no deps change and is satisfied by
whichever smoke path actually ran.

NOT yet wired into branch protection -- added during a soak period so the
check is visible before it becomes blocking, and so requiring it doesn't
strand other open PRs.

Pattern adapted from SocketDev/socket-python-cli #224.

Signed-off-by: lelia <[email protected]>

* ci: spell out 'iff' as 'if and only if' in gate comment

Review feedback: 'iff' read as a typo. It is the logic shorthand for
'if and only if', but the comment exists to communicate, so spell it out.

Signed-off-by: lelia <[email protected]>

---------

Signed-off-by: lelia <[email protected]>

ci(deps): bump actions/github-script from 7.0.1 to 9.0.0 (#87)

* ci(deps): bump actions/github-script from 7.0.1 to 9.0.0

Bumps [actions/github-script](https://github.com/actions/github-script) from 7.0.1 to 9.0.0.
- [Release notes](https://github.com/actions/github-script/releases)
- [Commits](actions/github-script@60a0d83...3a2844b)

---
updated-dependencies:
- dependency-name: actions/github-script
  dependency-version: 9.0.0
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <[email protected]>

* Add version number as comment

* Add version number as comment

---------

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: lelia <[email protected]>

Dependabot hardening + dependency update bundle (#84)

* Harden Dependabot reviews and bundle dependency updates

Mirrors the Dependabot hardening done in socket-python-cli (#207/#217/#218),
adapted to this SDK (no Dockerfile, no e2e fixtures, hatch/pip build path).

Bundle dependency updates (supersedes 4 open Dependabot PRs):
- idna 3.11 -> 3.17 (security: CVE-2026-45409 quadratic-time DoS fix)
- cryptography 46.0.5 -> 46.0.7
- pygments 2.19.2 -> 2.20.0
- uv 0.9.21 -> 0.11.17

Verified via uv sync --locked, import smoke, and pytest tests/unit (102 passed).

Adds grouped/cooldowned dependabot.yml (uv + github-actions), a
dependabot-review workflow running anonymous Socket Firewall smoke jobs,
Version Check / PR Preview skips for Dependabot PRs, and setup-sfw /
setup-hatch composite actions.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

* chore(release): bump to 3.1.2

Version Check requires a package-version increment on maintainer PRs, and
this PR bundles dependency bumps + Dependabot hardening. Bump version.py,
pyproject.toml, and the uv.lock project version in sync.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

* Extend dependency review to maintainers (free + enterprise SFW)

Broaden dependabot-review into dependency-review so the Socket Firewall
guardrail covers maintainer PRs too, not just Dependabot:

- inspect now runs on every PR and computes the SFW edition per-PR:
  enterprise for a trusted SocketDev member (author_association OWNER/
  MEMBER/COLLABORATOR) on an in-repo (non-fork) PR when SOCKET_API_TOKEN
  is present; free (anonymous) for Dependabot, forks, external
  contributors, or when the token is absent.
- The mode degrades to free whenever the token is missing, so this is
  safe to ship before the secret exists and auto-upgrades to enterprise
  once SOCKET_API_TOKEN is added (repo or org level). The SDK has no
  Socket token today (cf. socket-python-cli's SOCKET_CLI_API_TOKEN).
- setup-sfw composite action gains `mode` + `socket-token` inputs,
  forwarded to socketdev/action (same action, firewall-free vs
  firewall-enterprise).
- Rename workflow dependabot-review.yml -> dependency-review.yml to match
  the broadened scope (not a required status check).

Co-Authored-By: Claude Opus 4.8 <[email protected]>

* fix(dependency-review): use runner Python, forbid uv interpreter download

.python-version pins 3.12.7; setup-python provides 3.12.13, so `uv sync`
tried to download the exact managed CPython from GitHub, which Socket
Firewall's TLS interception blocked (UnknownIssuer). Set UV_PYTHON=3.12 +
UV_PYTHON_DOWNLOADS=never so uv uses the runner interpreter and only PyPI
package fetches route through sfw.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

* fix(dependency-review): require strict org membership for enterprise SFW

Tighten the enterprise-mode gate to author_association OWNER/MEMBER only.
Outside collaborators (COLLABORATOR) now fall through to the free edition,
same as Dependabot / forks / external contributors.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

* chore(dependency-review): rename enterprise secret to SOCKET_SFW_API_TOKEN

Co-Authored-By: Claude Opus 4.8 <[email protected]>

* fix(dependency-review): scope SFW token to a dedicated environment

Resolve zizmor secrets-outside-env (medium) without suppressing it. Split
the single mode-switching smoke job into two:

- python-sfw-smoke-free: untrusted PRs (Dependabot, forks, outside
  collaborators, externals). Anonymous free edition, never references the
  token.
- python-sfw-smoke-enterprise: SocketDev org members (OWNER/MEMBER) on an
  in-repo PR. Authenticated enterprise edition; SOCKET_SFW_API_TOKEN is
  scoped to the `socket-firewall` GitHub environment, so only this job can
  read it.

inspect now classifies PR trust (author_association OWNER/MEMBER, non-fork,
non-Dependabot) and references no secret. No required-reviewer protection
on the environment, so trusted dep PRs still run automatically.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

* fix(dependency-review): gate enterprise on write-access (non-fork), not author_association

author_association only reflects PUBLIC org membership, so private members
(the common case here) show as CONTRIBUTOR and were misclassified -> the
enterprise job always skipped. Switch the trust gate to "non-fork PR and not
Dependabot": only accounts with write access can push an in-repo branch, the
same boundary GitHub uses for secret exposure. No read:org token needed.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

* ci(dependency-review): upload SFW smoke artifacts

* ci(dependency-review): include SFW JSON report artifact

* ci(dependency-review): read SFW report path from env var, drop stdout scrape

Match socket-python-cli: discover the firewall report via the
$SFW_JSON_REPORT_PATH env var that socketdev/action exports, instead of
parsing the 'sfw report written to:' line out of stdout.

The two sync steps return to plain 'set -o pipefail' + tee. A new
'Collect SFW JSON report' step (if: always(), before each upload) copies
$SFW_JSON_REPORT_PATH into sfw-artifacts/sfw-report.json -- copy, not
move, since socketdev/action's post step reads that temp path for its job
summary -- and drops a sfw-report-missing.txt breadcrumb when absent.

More robust than scraping an undocumented log string, and keeps the
report-capture pattern uniform across both repos.

Signed-off-by: lelia <[email protected]>

---------

Signed-off-by: lelia <[email protected]>
Co-authored-by: Claude Opus 4.8 <[email protected]>

Fix stale `didYouMean` props (#81)

* test: failing regression for stale didYouMean props

* fix(issues): drop stale didYouMean props, add detectedAt

Resolves CUS2-5. The didYouMean class declared four props
(alternatePackage, downloads, downloadsRatio, editDistance) but the
current OpenAPI schema (socket-sdk-js/openapi.json:9298) only emits
{ alternatePackage, detectedAt }. The three stale keys were dead at
runtime and detectedAt was missing a human-readable label entirely.
Updated to match the schema.

* chore(release): bump to 3.1.1 and sync pyproject.toml

Run via .hooks/sync_version.py after merging origin/main (now at 3.1.0
from lelia's purl PR). Keeps pyproject.toml and socketdev/version.py
in lockstep, as flagged in code review.

* chore: sync uv.lock to 3.1.1