@tsg-dsp/tsg-sdk 0.20.1 → 0.21.0

package/README.md

@@ -4,16 +4,28 @@ TypeScript SDK for interacting with TSG (TNO Security Gateway) Dataspace Protoco
 
 ## Installation
 
-The SDK is currently available to packages in this monorepo. Add it as a workspace
-dependency:
+Install the latest released SDK from npm:
+
+```bash
+npm install @tsg-dsp/tsg-sdk
+```
+
+Within this monorepo, use a workspace dependency to consume the current source:
 
 ```bash
 pnpm --filter <consumer-package> add '@tsg-dsp/tsg-sdk@workspace:*'
 ```
 
-Publication to npm is deferred until a later release.
+For an interactive example against the current shared services, use the
+[managed SDK playground](../../sample/sdk/README.md).
 
-## Quick Start
+## Quick start
+
+Use URLs, audiences, canonical tenant ID, service-local slugs and workload
+credentials from your provisioned deployment. Values below illustrate the
+configuration shape; they are not seeded accounts or deployment defaults.
+The [module examples](samples/README.md) read these settings from environment
+variables and support an offline construction check.
 
 ```typescript
 import { TsgSdk } from "@tsg-dsp/tsg-sdk";
@@ -22,11 +34,19 @@ const sdk = TsgSdk.create({
   controlPlaneBaseUrl: "http://localhost:3000",
   walletBaseUrl: "http://localhost:3001",
   ssoBridgeBaseUrl: "http://localhost:3002",
-  tenantSlug: "default", // sent as X-Tenant-Slug on every control-plane / wallet call
+  tenantSlug: "acme", // sent as X-Tenant-Slug on control-plane / wallet calls
+  canonicalTenantId: "11111111-1111-4111-8111-111111111111",
+  controlPlaneAudience: "control-plane-api",
+  walletAudience: "wallet-api",
   auth: {
     method: "client_secret_post",
-    clientId: "my-client",
-    clientSecret: "my-secret"
+    clientId: controlPlaneClientId,
+    clientSecret: controlPlaneClientSecret
+  },
+  walletAuth: {
+    method: "client_secret_post",
+    clientId: walletClientId,
+    clientSecret: walletClientSecret
   }
 });
 
@@ -43,18 +63,64 @@ const negotiation = await sdk.negotiations.requestNegotiation(
 );
 
 // Wait for agreement
-const finalized = await sdk.negotiations.waitForAgreement(negotiation["@id"]!);
+const finalized = await sdk.negotiations.waitForAgreement(negotiation.id);
 
 // Request a transfer
 const transfer = await sdk.transfers.requestTransfer(
   agreementId,
   participantId,
   remoteAddress,
-  "application/json",
-  "http-data-plane"
+  "https://w3id.org/dspace-sig/profile/http-pull"
+);
+```
+
+## Managed tenants
+
+`TenantManagementSdk` is a standalone client for the central manager. Use a
+human token issued for its audience. Workload provisioning credentials cannot
+administer organizations through these endpoints.
+
+```typescript
+import { AuthProvider, TenantManagementSdk } from "@tsg-dsp/tsg-sdk";
+
+const tenants = new TenantManagementSdk(
+  "https://hosted.example.com/tenant-management/api",
+  new AuthProvider(
+    { method: "access_token", accessToken: humanToken },
+    undefined
+  )
+);
+const accepted = await tenants.createForPlatform(
+  {
+    name: "Alice Corp",
+    slug: "alice-corp",
+    profile: "default",
+    owner: { kind: "new", username: "alice", email: "alice@example.com" }
+  },
+  "alice-corp-create-1"
 );
+const operation = await tenants.operation(accepted.operationId);
 ```
 
+The client covers capabilities, account lookup/onboarding, setup links, operation
+history/retry, invitations, memberships, grants, ownership, lifecycle, audit and
+workload credential rotation. Self-service `create` requires explicit deployment
+policy. A setup link contains a URL only when email delivery is disabled.
+The browser export also provides `TenantManagementSdk`; omit its auth argument
+for same-origin cookie sessions.
+
+For managed Wallet/Control Plane calls, set `canonicalTenantId`,
+`controlPlaneAudience` and `walletAudience`. Keep the target-local tenant selector
+in `tenantSlug`, or use `controlPlaneTenantSlug` and `walletTenantSlug` when
+imported services have different URL names. `walletAuth` supplies a separate
+Wallet token or credential whenever explicit Control Plane authentication is configured. Tokens are never inherited across services. Setting `ssoBridgeBaseUrl` allows
+workload token discovery; it does not give `sdk.sso` management authority.
+Use `ssoAuth` and `ssoAudience` for a separate credential authorized to administer
+SSO. Tenant Management administration and consumer authorization use separate
+audiences. A tenant slug selects a service-local tenant; it does not replace the
+canonical tenant UUID in workload token requests. There is no implicit `default`
+tenant, seeded workload client, or token audience fallback.
+
 ## Modules
 
 The SDK is organized into focused modules, each accessible as a property on the `TsgSdk` instance:
@@ -164,10 +230,13 @@ The SDK supports three authentication methods:
 const sdk = TsgSdk.create({
   controlPlaneBaseUrl: "http://localhost:3000",
   ssoBridgeBaseUrl: "http://localhost:3002",
+  canonicalTenantId,
+  controlPlaneTenantSlug,
+  controlPlaneAudience,
   auth: {
     method: "client_secret_post",
-    clientId: "my-client",
-    clientSecret: "my-secret"
+    clientId: controlPlaneClientId,
+    clientSecret: controlPlaneClientSecret
   }
 });
 ```
@@ -178,33 +247,40 @@ const sdk = TsgSdk.create({
 const sdk = TsgSdk.create({
   controlPlaneBaseUrl: "http://localhost:3000",
   ssoBridgeBaseUrl: "http://localhost:3002",
+  canonicalTenantId,
+  controlPlaneTenantSlug,
+  controlPlaneAudience,
   auth: {
     method: "private_key_jwt",
-    clientId: "my-client",
-    privateKeyJwk: myPrivateKey
+    clientId: controlPlaneClientId,
+    privateKeyJwk: controlPlanePrivateKey
   }
 });
 ```
 
-### Pre-obtained Access Token
+### Pre-obtained access token
+
+Use a token issued for the receiving service and intended tenant. The SDK does
+not change its claims or refresh it. Configure `walletAuth` and `ssoAuth` with
+separate tokens when calling those services.
 
 ```typescript
 const sdk = TsgSdk.create({
   controlPlaneBaseUrl: "http://localhost:3000",
+  controlPlaneTenantSlug,
   auth: {
     method: "access_token",
-    accessToken: "eyJhbGciOi..."
+    accessToken: controlPlaneToken
   }
 });
 ```
 
-### No Authentication
+### Cookie sessions
 
-```typescript
-const sdk = TsgSdk.create({
-  controlPlaneBaseUrl: "http://localhost:3000"
-});
-```
+Omitting auth sends no bearer token. It does not bypass service authorization or
+select a tenant. In a same-origin browser session, configure the service-local
+tenant slug explicitly and let the browser send its existing session cookie.
+The Node.js module examples use explicit workload credentials instead.
 
 ## Optional Modules
 
@@ -267,8 +343,21 @@ The SDK build includes compiled private DTOs and their declarations under
 metadata by copying the TypeScript compiler output. Only `common-dsp` remains a
 separately published TSG dependency. The browser entry does not load the DTOs.
 
-The SDK is currently consumed within the monorepo. Automated npm publication is
-deferred until a later release. After building the workspace, check an external
-installation locally: pack with `pnpm --filter @tsg-dsp/tsg-sdk pack`, install the tarball outside the
-workspace, and compile a TypeScript consumer using both the main and browser
-entries.
+To check an external installation locally, build with
+`pnpm --filter @tsg-dsp/tsg-sdk... -r build`, pack with
+`pnpm --filter @tsg-dsp/tsg-sdk pack`, install the tarball outside the workspace,
+and compile a TypeScript consumer using both the main and browser entries.
+
+### Renewable HTTP data access
+
+Use `transfers.dataAccess(transferId)` before sending an HTTP data request. The
+control plane coordinates refresh-token rotation across clients and persists the
+new credentials. The returned object contains `endpoint` and `headers`.
+
+```ts
+const access = await sdk.transfers.dataAccess(transferId);
+const response = await fetch(access.endpoint, { headers: access.headers });
+```
+
+After a 401, request `{ forceRefresh: true }` and decide whether to repeat the
+request. The SDK never retries data requests automatically.