Business-side SDKs

Business-side SDKs are integration helpers, not a new authorization system. The stable boundary remains OpenAPI + x-agent-capability + HMAC + final business authorization.

Declaration generation fix in 0.10.1

Validate the business SDKs from Core tag v0.10.1 together with Core 0.10.1. Generators now preserve explicit risk: low/medium/high, readonly: false/true and idempotent: false/true; unset fields remain omitted. ACC specification 1.0.6 and declaration version: 1 are unchanged. The independent MCP / Agent Client SDK 0.8.0 and DSH 0.8.0 do not require a version change for this patch.

Regenerate and review declaration differences first. A non-readonly POST whose explicit low was lost may now resolve to low rather than medium and needs business-owner review. GET with explicit readonly=false and no risk should resolve to medium. Approval, subject and final business authorization remain independent. Do not mark every write operation low or replay business actions for acceptance.

Updating only the generator or consumer can leave the other defect unresolved. Custom code reading intermediate tool objects must also handle unset risk values. PHP7 remains compatible with PHP 7.3; the PHP8 Attribute SDK requires PHP 8.1+. Verify artifact and per-file digests, then refresh tool sources through the existing process while preserving original invocations and approvals. See the 0.10.1 upgrade guide.

Optional plan provisioning

Node UsageIssuerClient and PHP7 UsageClient provide listBillingPlans, grantBillingPlan, controlBillingPlan and getBillingSummary through /usage/v1/external/billing/ with a separate server-side issuer credential. Node types are exported at @bailinghub/connect/usage. Preserve the original request key, parameters and revision; mutations never retry automatically. See Model services and plan billing for responsibilities, customer presentation and plan-scoped identity.

Runtime coverage

Runtime	Surface
PHP 8.1+	Attribute declarations, SpecServer, verification, tickets, and HubClient
PHP 7.3+	Builder declarations over the same wire contract
Node.js / Python	Spec builders, ticket signing, tool/callback verification, authz probe, and HubClient
Java 11+ / Go 1.21+ / .NET 8+	Standard-library reference SDKs for enterprise backends
Other languages	Implement the same OpenAPI/ACC, HMAC, and authz-probe contract directly

What the SDK helps with

1. Generate a tool spec;
2. verify signed tool calls;
3. verify completion callbacks;
4. sign short-lived web-chat identity tickets;
5. implement a fail-closed authorization probe;
6. call /run and /jobs/{id} through HubClient.

Node example

import { buildOpenApiSpec, param, tool } from '@bailinghub/connect';

const spec = buildOpenApiSpec({
  title: 'CRM Tools',
  version: '1.0.0',
  authzProbe: { method: 'POST', path: '/.well-known/bailing/authz-probe' },
  tools: [
    tool({
      name: 'member_query',
      method: 'GET',
      path: '/api/members/{id}',
      description: 'Read a member profile',
      scope: 'member.read',
      requiresSubject: true,
      params: [param('id', { in: 'path', required: true })],
    }),
  ],
});

After verification, call your own permission service. Never implement the authorization callback as unconditional success.

Subject names and authorization lifecycle

A trusted authorization confirmation may include subject_display.name. Read it from the business record for the authenticated subject, not from an arbitrary client label. It is display metadata for an organization, account, project, or store, never an authorization identifier.

Core 0.10.1 PHP and PHP 7 helpers support own-client authorization/session lookup, revocation, and subject-name updates. Existing sessions can receive a name without replacing their Agent Session. Other languages may use the same HTTP contract; check each SDK rather than assuming every helper exposes identical methods.

See the Agent Auth API and upgrade guide.

Do not confuse the two SDK layers

• Business-side SDKs live under Core sdk/* and run inside business backends.
• Agent Client SDK / MCP Server is the independent bailinghub-mcp-server package and runs on the local-agent side.

See the fixed v0.10.1 SDK guide and each runtime directory for full examples.