TypeScript

Coming A first slice is in

sombus-dev-kit, not on npm yet. Names and details may change before release.

The first slice covers the producer side: tokens, envelopes, and publishing with retries and typed verdicts. It needs Node 20 or later and has no runtime dependencies.

Try it

git clone https://github.com/rndsolutions/sombus-dev-kit.git
cd sombus-dev-kit && npm install && npm test

Then run the reference producer and consumer against your vendor workspace, with a producer app's and a consumer connection's credentials: see examples/.

Publish a message

const bus = new SomBusClient({
  baseUrl: 'https://api.sombus.rnd-solutions.net/v1/',
  publishPath: `tenants/${process.env.SOMBUS_WORKSPACE}/messages`,   // your workspace's route
  auth: new ClientCredentials({
    tokenUrl: 'https://api.sombus.rnd-solutions.net/v1/oauth/token',
    clientId: process.env.SOMBUS_CLIENT_ID!,        // your connection's client id
    clientSecret: process.env.SOMBUS_CLIENT_SECRET!,
  }),
});

const message = buildEnvelope({
  messageType: 'story.context',
  payload: snapshot,                                   // a whole snapshot, never a delta
  originatingSystem: { system_id: 'acme-ncs-test', system_type: 'ncs', vendor: 'acme' },
  correlationId: story.correlationId,                  // leave out for a new story
});

const v = await bus.publish(message);
switch (v.kind) {
  case 'accepted':  /* v.tolerated: warnings to log */ break;
  case 'duplicate': /* an earlier attempt got through: success */ break;
  case 'refused':   /* v.status, v.source, v.rule, v.path: don't resend this message */ break;
}

What publish does

• Retries timeouts, 408, 429 and 5xx with backoff, and a 401 once with a new token, always resending the same bytes. See SDKs.
• Resolves with the bus's final answer: accepted, duplicate or refused.
• Rejects with PublishError only when the bus never gave a final answer. Keep the message and resend it later, unchanged: it carries the message_id, the number of attempts and the last answer, if any.
• Rejects with TokenError when the token endpoint refused your credentials (retryable: false): configuration, not something to retry.

onAttempt reports each attempt (message id, attempt number, status, outcome, rule, delay) for your logs and metrics, never the payload or the token.

The envelope builder

Field	Default
som_version	1.0.0
message_id	A new UUIDv7
correlation_id	A new UUIDv7. Reuse the story's for every later message about it
causation_id	Unset. buildFollowUp(cause, …) sets it to the cause's message_id and copies its correlation_id
timestamp	Now, UTC
topic	som.<message_type>

Build once, keep it. Keep the built message until the bus gives a final answer. Rebuilding for a retry makes a new message.

Not in the first slice

Offline validation, the dry-run API, SigV4, your own identity provider's tokens, payload types generated from the SOM schemas, the snapshot helper, the consumer and the executor runtime.