[PY-02] Add authentication, pagination, retries, typed errors, and webhook helpers

[jaavid]

Background

CoreLink is one product across multiple implementation repositories. This work is owned by sdk-python under EPIC-05.

Problem

PY-02 previously depended on the vague phrase accepted contracts, which did not identify which public surfaces are required for implementation versus which must be accepted before SDK behavior may be advertised as supported.

Goal

Add authentication, pagination, retries, typed errors, and webhook helpers against version-identifiable CoreLink contracts, with retained conformance evidence for the Beta gate.

Parent

• Primary Product Epic: EPIC-05
• Backlog ID: PY-02

Scope

• Implement authentication and explicit tenant context.
• Add pagination, retry/backoff, typed error, and webhook helper behavior for supported surfaces.
• Preserve generated-contract provenance and avoid hand-written divergence from normative schemas.
• Retain positive, denied, malformed, retry, and recovery evidence against an accepted mock/sandbox path.

Out of Scope

• Advertising draft/scaffold contract slices as supported.
• Stable package publication; that remains under PY-03.
• Product-runtime acceptance outside the SDK boundary.

Acceptance Criteria

• Authentication and tenant context are explicit and least-privilege.
• Pagination/retry/error behavior maps to exact accepted contract semantics for each supported surface.
• Webhook helpers map to accepted/version-identifiable API-03/API-04 slices where applicable.
• Cross-tenant and insufficient-scope behavior fails closed.
• Positive, error, retry and recovery behavior is repeatable against MOCK-02/MOCK-03 or an equivalent accepted sandbox.
• Examples identify SDK and contract versions/maturity.
• Retained evidence is linked and EPIC-05 exit criteria are measurably advanced.

Dependencies and acceptance state

• Execution prerequisite: PY-01 reproducible generation/provenance baseline.
• Contract inputs: accepted/version-identifiable API-02 slices for device/telemetry helpers and API-03/API-04 slices for webhook/event helpers; draft implementation may proceed only when maturity is explicit.
• Conformance input: MOCK-02 / MOCK-03 or an equivalent accepted sandbox before Beta support claims.
• Blocks: PY-03 signed package/release work, DOCS-04 SDK guidance, WEB-03 supported-tool claims and EPIC-05 SDK acceptance.
• Current dependency state: See the CoreLink Product organization Project.

Planning Metadata

• Type: Feature
• Priority snapshot: P0
• Product milestone snapshot: Beta
• Domain snapshots: sdk, devex
• Area snapshot: package
• Complexity: L
• Created in status: Triage
• Current status and DRI: See the CoreLink Product organization Project.
• Intended repository labels: type:feature

Definition of Done

• Acceptance criteria demonstrated.
• Required conformance evidence passes on version-identifiable dependencies.
• Contract compatibility and generated provenance are reconciled.
• Security and tenant boundaries are reviewed.
• Retry/error/webhook behavior is documented.
• Package/release implications are reconciled with PY-03.
• Pull request(s), dependency versions and retained evidence are linked.