@topolo/sdk 0.3.0 → 0.4.1

package/README.md

@@ -4,6 +4,11 @@ Typed client SDK for the Topolo platform. Consumed by `@topolo/cli` and
 `@topolo/mcp`, and available to any first- or third-party code that needs to
 call Topolo APIs on a user's behalf.
 
+Use `@topolo/login` for Login with Topolo OAuth/OIDC provider integration,
+token exchange, userinfo, ID-token verification, and local account linking.
+Use `@topolo/sdk` after login, when the app already has a Topolo API credential
+and needs to call Topolo APIs.
+
 This package is the single place where cross-org isolation is enforced on the
 client side.
 
@@ -80,9 +85,16 @@ Additional modules land per-app as each backend contract stabilizes.
 ## Application catalog
 
 `APPLICATIONS` describes every Topolo platform application discovered from the
-PlatformApplications metadata, including pages-only apps that do not expose a
-callable service. `DEFAULT_SERVICE_URLS` remains the callable API service map
-used by `TopoloClient`.
+PlatformApplications metadata, including Worker apps that do not expose a
+callable service. `DEFAULT_SERVICE_URLS` is the bundled callable API service
+snapshot generated from `topolo.cloudcontrol.json`.
+
+For agent-scale fleets, the bundle is a floor, not a cap. `TopoloClient.request`
+accepts bundled service IDs and live Auth-catalog service IDs/slugs. When a
+service is not in the bundled snapshot, the client resolves the selected
+environment's live catalog and only routes entries marked as API/technical
+service surfaces. Browser/runtime surfaces are not treated as generic API
+targets.
 
 `APPLICATION_REQUIREMENTS` is the versioned app-build contract agents should
 read before creating or expanding a Topolo app. `requirementsForApplication()`
@@ -103,7 +115,7 @@ their own `GET /api/widget` endpoint. The SDK owns the shared payload contract:
 import { createTopoloWidgetResponse } from '@topolo/sdk';
 
 return Response.json(createTopoloWidgetResponse({
-  serviceId: 'srv_topolo_example',
+  serviceId: '<runtime-service-id>',
   serviceName: 'Example',
   widgets: [
     {
@@ -139,7 +151,7 @@ Still routes through auth + audit headers. Mutating methods still require
 | `TopoloHttpError`        | Other non-2xx responses                  |
 | `TopoloSdkError`         | Base class                               |
 
-## Service URL overrides
+## Service URL Overrides
 
 Defaults target production. Override per-service for staging/dev: