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.

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+	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.9.0 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.9.0 SDK guide and each runtime directory for full examples.