@xemahq/biome-activity-sdk

Helpers for outbound integration calls inside workflow activities

Overview

This package gives workflow activity authors a small set of helpers for talking to external providers. Its central helper, withIntegrationToken, mints a credential on behalf of a user, runs the caller's outbound request with that token, and re-mints once on a single auth failure before giving up.

It is provider-neutral and credential-kind-neutral by construction: the helper does not know which provider it is speaking to. The caller supplies the request function and signals an auth failure by throwing IntegrationAuthError, which is the only error the helper retries on — everything else propagates immediately.

When to use it

• Use it from biome workflow activities that make authenticated outbound calls to an external provider.
• Reach for withIntegrationToken when you want automatic re-mint-and-retry on a single expired-token failure.

Installation

pnpm add @xemahq/biome-activity-sdk

Usage

import { withIntegrationToken, IntegrationAuthError } from '@xemahq/biome-activity-sdk';
import { CredentialKind } from '@xemahq/connector-contracts';

const result = await withIntegrationToken(
  { adapterKind: 'scm', provider: 'GITHUB', credentialKind: CredentialKind.AppInstall, userId: ctx.actorId },
  async (token) => {
    const res = await fetch(url, { headers: { Authorization: `Bearer ${token.accessToken}` } });
    if (res.status === 401) throw new IntegrationAuthError(401);
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    return res.json();
  },
);

License

Proprietary — © Xema. All rights reserved. — xema.dev