@wizcommerce/sdk

Dependency-free client SDK that consuming apps (WizOrder, WizShop, Ultron, Studio, Integrations, Ella AI) call to trigger workflow events and wait for gate outcomes.

What's in here

src/
├── client.ts      WorkflowEngineClient — fetch + optional injected realtime
├── constants.ts   Channel prefixes, event names, status enums
├── types.ts       Local wire types (no @wizcommerce/contracts dependency)
└── index.ts       Public barrel exports

Usage

import { WorkflowEngineClient, RESULT_STRATEGY, WORKFLOW_BASE_ACTIONS } from '@wizcommerce/sdk';

const engine = new WorkflowEngineClient({
  baseUrl: 'https://workflow.wizcommerce.com',
  apiKey: process.env.WIZ_API_KEY!,
  tenantId: 'your-tenant-id',
  result_strategy: RESULT_STRATEGY.poll, // or RESULT_STRATEGY.pusher
  realtime: myPusherTransport, // required when result_strategy is 'pusher'
});

// Fire-and-forget dispatch
const dispatch = await engine.triggerEvent('order.submit', { orderId: '123' });

// Trigger and wait for gate outcome ('ok' | 'block' | custom action value)
const outcome = await engine.triggerAndWait('order.submit', { orderId: '123' });
if (outcome === WORKFLOW_BASE_ACTIONS.block) {
  // gate blocked the action
}

// Poll a specific async run
const status = await engine.pollRunResult(runId);

// Authorize a private Pusher channel (for host-native Pusher integrations)
const grant = await engine.authorizeRealtimeChannel(socketId, channelName);

Design

• Fail-open: HTTP errors return empty results / null — never throw on transport failure.
• Dependency-free: Wire types are defined locally so RN/Hermes consumers are not pulled into AJV.
• Host-injected realtime: Pusher (or any transport) is wired via RealtimeTransport; the SDK owns subscribe → trigger → wait → cleanup for the pusher strategy.
• Dual terminal event namespaces: Sync runs resolve on workflow.run.completed / workflow.run.failed. Async (Temporal) runs resolve on workflow.completed / workflow.failed / workflow.cancelled (AsyncWorkflowCompletionEvent). The pusher wait path handles both.
• Action registry: Register UI handlers by response type so workflow nodes can invoke host-specific logic.

Boundaries

• NOT a Builder UI helper (the Builder UI talks directly to apps/api's /api/v1/builder/* JWT-protected routes)
• NOT an admin / management SDK
• MUST stay framework-agnostic (no React-specific code in the core; React hooks land in a separate @wizcommerce/sdk-react sub-package if needed)

Consuming from outside the monorepo

This package is "private": true inside the workflow-engine pnpm workspace. Other repos (e.g. ultron-app) can depend on it via link:../workflow-engine/packages/sdk or a packed tarball after running pnpm --filter @wizcommerce/sdk build.