PSA/ee/docs/plans/2026-03-26-extension-sdk-client-service-read-capabilities/PRD.md

PRD — Extension SDK Client And Service Read Capabilities

• Slug: extension-sdk-client-service-read-capabilities
• Date: 2026-03-26
• Status: Draft

Summary

Add read-only extension host capabilities for tenant-scoped client and service catalog lookup so extension handlers can read those records without making HTTP API calls.

Problem

Handlers that need client lists or service catalog data currently have to rely on API-like transport patterns. That creates unnecessary coupling to routes and credentials and makes scheduled or webhook-driven extension execution awkward.

Goals

• Add first-class host capabilities for reading clients and services from extension handlers.
• Support both user-backed and non-user execution contexts.
• Keep the extension contract typed, small, and versionable.
• Reuse existing internal query logic instead of duplicating API controllers.
• Enforce capability grants, RBAC behavior, and tenant isolation in one place.

Non-goals

• Mutating clients or services.
• Exposing arbitrary database queries.
• Returning the full internal IClient or IService shapes.
• Replacing existing HTTP APIs for the web app.

Users and Primary Flows

• Extension authors building tenant automations that need lookup data.
• Scheduler-driven handlers that need to read clients or services without a user session.
• Webhook-style handlers that need service catalog context during execution.

Primary flows:

• Extension lists clients with simple pagination and search.
• Extension fetches one client by id.
• Extension lists service catalog entries with simple filters.
• Extension fetches one service by id.

UX / UI Notes

This work is backend and SDK facing. The main user-facing ergonomics are:

• extension authors import typed host bindings
• handlers avoid HTTP fetches to Alga
• capability names remain explicit in manifests

Requirements

Functional Requirements

• Introduce cap:client.read and cap:service.read.
• Add clients.list, clients.get, services.list, and services.get host operations.
• Return summary-shaped records rather than full internal entities.
• Support pagination and a minimal filter set for list operations.
• Enforce normal client:read and service:read permissions when a user is present.
• Allow capability-only tenant-scoped access for non-user contexts.
• Return nullable results for not-found get operations.

Non-functional Requirements

• No handler-side HTTP dependency for these reads.
• Stable WIT and TypeScript surface for SDK consumers.
• Clear error semantics for not-allowed, invalid-input, and internal failures.
• Provider behavior must be unit testable without UI or HTTP routing.

Data / API / Integrations

• Extend extension runner WIT with clients and services interfaces.
• Extend sdk/extension-runtime host bindings and mocks.
• Add runner capability providers for both interfaces.
• Extract or factor shared read services from the current client and service action layers.

Likely internal reuse points:

• packages/clients/src/actions/clientActions.ts
• packages/billing/src/actions/serviceActions.ts

Security / Permissions

• Install capability grant is mandatory.
• User-backed executions must also pass the existing RBAC checks.
• Non-user executions may read tenant-scoped data when the install capability is granted.
• Extensions cannot override tenant id in capability input.

Observability

• Provider calls should emit structured runner logs for capability name, tenant, extension, result count, and error type.
• Failures should distinguish capability denial, RBAC denial, invalid input, and internal query failure.

Rollout / Migration

• Add the new capabilities behind normal manifest capability declarations.
• Ship a sample extension that exercises the new host APIs.
• Keep existing HTTP-based patterns working; this is additive.

Open Questions

• Include tags in client summaries in v1 or defer.
• Include currency-specific prices in service summaries in v1 or defer.
• Decide whether future write support should be separate capabilities.

Acceptance Criteria (Definition of Done)

• Extensions can read clients through a typed host capability without HTTP.
• Extensions can read services through a typed host capability without HTTP.
• User-backed execution respects existing client:read and service:read permissions.
• Non-user execution works when the install capability is granted.
• The SDK exposes typed bindings and mock bindings for both capabilities.
• Runner/provider tests cover user, non-user, denial, invalid input, not-found, and tenant isolation cases.
• A sample extension demonstrates end-to-end usage.