@synexusjs/sdk-client

Framework-agnostic client runtime for Synexus SDK Actions.

@synexusjs/sdk-client turns a browser or app host into a governed SDK target that can receive action executions from Synexus workflows, agents, and assistant flows, execute explicitly registered handlers, and return typed JSON results over the platform realtime channel.

Installation

npm install @synexusjs/sdk-client

Quick start

import {
  createSdkClient,
  getOrCreateBrowserSdkClientInstanceId,
} from '@synexusjs/sdk-client';

const client = createSdkClient({
  serverUrl: 'https://your-synexus-api.example.com',
  authToken: 'your-token',
  organizationId: 'org_123',
  workspaceId: 'ws_456',
  clientInstanceId: getOrCreateBrowserSdkClientInstanceId(),
  displayName: 'Operations Browser',
});

client.registerAction(
  {
    actionKey: 'ui.confirm',
    name: 'Confirm action',
    description: 'Shows a confirmation dialog in the current host.',
    metadataJson: {
      category: 'ui',
      label: 'Confirm',
      description: 'Ask the current connected user to confirm a sensitive step.',
      provider: 'synexus',
      origin: 'built_in_client_host',
      keywords: ['confirm', 'dialog', 'approval'],
      exampleInput: {
        title: 'Delete order',
        message: 'Do you want to delete this order?',
      },
      exampleOutput: {
        confirmed: true,
      },
      riskLevel: 'SENSITIVE_WRITE',
      requiresConfirmation: true,
    },
  },
  async ({ input }) => {
    const confirmed = window.confirm(String(input.message ?? 'Continue?'));
    return { confirmed };
  },
);

await client.connect();

Core concepts

Client host

A connected app instance that registers SDK actions with Synexus and can receive execution requests over the realtime transport.

Action

An explicitly registered handler identified by actionKey, such as ui.confirm or browser.context.capture. Actions are not arbitrary code execution. You choose which handlers exist and what each one can do.

Each action can also carry product metadata for discovery and governance:

• label
• description
• category
• riskLevel
• requiresConfirmation
• provider
• origin
• keywords
• exampleInput
• exampleOutput

Execution

When a workflow, agent, or assistant invokes an SDK capability, Synexus dispatches a structured request to an eligible host. The client handler returns a JSON object that becomes the execution result.

Governance

Risk metadata, confirmation requirements, host selection, approvals, and runtime tracing are enforced by the Synexus backend runtime. The client package focuses on connection lifecycle, action registration, and request/response handling.

Canonical built-in action shapes

These are the canonical client action identities already used inside Synexus:

• ui.confirm
• ui.form.collect
• browser.context.capture
• host.notification.show
• host.navigation.open

Example with richer action metadata:

client.registerAction(
  {
    actionKey: 'host.notification.show',
    name: 'Show host notification',
    description: 'Displays a local notification banner in the connected host.',
    metadataJson: {
      label: 'Show notification',
      category: 'notifications',
      riskLevel: 'LOW_RISK_WRITE',
      provider: 'synexus',
      origin: 'built_in_client_host',
      keywords: ['notification', 'toast', 'banner'],
      exampleInput: {
        title: 'Order synced',
        message: 'The ERP order was created successfully.',
        level: 'success',
      },
      exampleOutput: {
        shown: true,
        shownAt: '2026-03-29T12:00:00.000Z',
      },
    },
  },
  async ({ input }) => {
    console.log('Host notification request:', input);
    return {
      shown: true,
      shownAt: new Date().toISOString(),
    };
  },
);

Public API

createSdkClient(options)

Creates a client runtime instance.

const client = createSdkClient({
  serverUrl: 'https://your-synexus-api.example.com',
  authToken: 'your-token',
  organizationId: 'org_123',
  workspaceId: 'ws_456',
  clientInstanceId: 'browser-host-1',
  displayName: 'Operations Browser',
});

client.connect()

Opens the realtime connection and registers the host plus its currently registered actions with Synexus.

client.disconnect()

Closes the realtime connection and stops heartbeats.

client.registerAction(definition, handler)

Registers a handler for an actionKey. Returns an unsubscribe function that unregisters the action.

const unregister = client.registerAction(
  {
    actionKey: 'host.notification.show',
    name: 'Show notification',
  },
  async ({ input, context, request }) => {
    console.log('Request context:', context, request.executionId);
    return {
      shown: true,
      title: input.title ?? null,
    };
  },
);

client.unregisterAction(actionKey)

Explicitly removes a previously registered action.

client.onEvent(eventName, listener)

Subscribes to lifecycle events:

• connect
• disconnect
• registration
• executionRequest
• executionResult
• error

client.getState()

Returns connection and registration state:

{
  connected: true,
  connecting: false,
  sessionId: 'session_123',
  targetIds: ['sdk_target_1'],
  targetKeys: ['web.client']
}

client.getRegisteredActions()

Returns the current action definitions registered in the local runtime.

Main exported types

• SdkClientOptions
• SdkClient
• SdkClientActionDefinition
• SdkClientActionHandler
• SdkClientActionMetadata
• SdkClientContext
• SdkExecutionRequest
• SdkExecutionResponse

Advanced transport types are also exported for custom transport injection:

• SdkClientTransport
• SdkClientTransportFactory
• SdkClientSocket
• SdkClientSocketFactory

Handler contract

Handlers receive a normalized request shape:

type SdkClientActionHandler = (args: {
  input: Record<string, unknown>;
  context: SdkClientContext;
  request: SdkExecutionRequest;
}) => Promise<Record<string, unknown>> | Record<string, unknown>;

Handlers must return a JSON object. Returning anything else causes the SDK to send a failed execution response.

Transport

The default transport uses Socket.IO and is already compatible with the Synexus runtime. For advanced setups you can provide a custom transportFactory or socketFactory.

const client = createSdkClient({
  ...options,
  transportFactory: ({ serverUrl, authToken, socketPath }) => {
    return customTransport(serverUrl, authToken, socketPath);
  },
});

Relationship with workflows, agents, and assistant

This package does not contain workflow or agent logic itself. Instead:

• Synexus workflows can dispatch SDK capabilities to connected hosts
• agents and assistant can reuse the same SDK capabilities through the central capability runtime
• approvals, risk enforcement, and target selection remain server-side concerns

The client package is the host-side runtime that makes those flows executable.

Platform flow

At runtime, the end-to-end flow is:

1. A workflow, agent, or assistant invokes an SDK capability.
2. Synexus resolves the eligible SDK target and host session.
3. The backend dispatches a typed execution request over the realtime channel.
4. The registered client action handler runs locally in the host.
5. The handler returns a typed JSON output.
6. Synexus persists the execution result and continues the caller flow.

Basic example

A runnable local example lives in examples/basic.

cd packages/sdk-client
npm run build
SYNEXUS_AUTH_TOKEN=... \
SYNEXUS_ORGANIZATION_ID=... \
SYNEXUS_WORKSPACE_ID=... \
npm run example:basic

Release checklist

Before running npm publish, verify:

1. npm run clean
2. npm run typecheck
3. npm run build
4. npm run pack:dry-run
5. Inspect the tarball contents and confirm only dist/, README.md, and package metadata are included.
6. Confirm version is correct for the intended release.
7. Confirm the license is correct for your intended public distribution.
8. Run a smoke install in a separate test project:

npm pack
mkdir -p /tmp/synexus-sdk-smoke
cd /tmp/synexus-sdk-smoke
npm init -y
npm install /absolute/path/to/synexusjs-sdk-client-0.1.0.tgz

9. Authenticate with npm:

npm login

10. Publish manually from the package root when ready:

npm publish --access public

Notes

• The package is currently marked UNLICENSED in this repo state. If this should grant public usage rights, replace that before publishing.
• React adapters, UI helpers, and product-specific host implementations are intentionally out of scope for this package.
• The public API is intentionally small. Internal runtime wiring stays inside the package.