@keystrokehq/integration-authoring

Authoring helpers for building Keystroke integration packages.

This package owns the integration-author ergonomics that aren't workflow primitives themselves: operation factories, REST client helpers, webhook verification, and trigger-binding helpers. It is intentionally separate from @keystrokehq/core so core can stay focused on CredentialSet, Step, Tool, Workflow, and the other end-user authoring primitives.

Install

npm install @keystrokehq/integration-authoring

This package is normally pulled in transitively when you install a Keystroke integration package (e.g. @keystrokehq/slack). Install it directly only if you are authoring your own integration package.

Public subpaths

| Import | Purpose | |---|---| | @keystrokehq/integration-authoring | createOperationFactory, error-normalizing proxy, polling and webhook trigger binding factories | | @keystrokehq/integration-authoring/http | createJsonRestClient and friends — typed JSON REST client with consistent error shapes | | @keystrokehq/integration-authoring/webhooks | HMAC webhook verification helpers | | @keystrokehq/integration-authoring/official | defineOfficialIntegration and the official-integration operation factory used by Keystroke's first-party integration packages | | @keystrokehq/integration-authoring/official/catalog | Provider-app seed and catalog descriptor types |

Operation factory

import { createOperationFactory } from '@keystrokehq/integration-authoring';
import { z } from 'zod';
import { mySlackCredentialSet } from './credential-set';

const myOp = createOperationFactory(mySlackCredentialSet);

export const sendMessage = myOp({
  id: 'send-message',
  name: 'Send Slack message',
  description: 'Posts a message to a Slack channel',
  input: z.object({ channel: z.string(), text: z.string() }),
  output: z.object({ ts: z.string() }),
  run: async ({ channel, text }, credentials) => {
    const res = await fetch('https://slack.com/api/chat.postMessage', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${credentials.SLACK_BOT_TOKEN}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ channel, text }),
    });
    const json = await res.json();
    return { ts: json.ts };
  },
});

The factory produces a @keystrokehq/core Operation with the credential set wired up, while letting authors keep a flat run(input, credentials) signature.

REST client

import { createJsonRestClient } from '@keystrokehq/integration-authoring/http';

const client = createJsonRestClient({
  baseUrl: 'https://api.example.com',
  headers: () => ({ Authorization: `Bearer ${getToken()}` }),
});

const result = await client.get<{ id: string }>('/items/123');

Webhook verification

import { verifyHmacSignature } from '@keystrokehq/integration-authoring/webhooks';

const ok = verifyHmacSignature({
  algorithm: 'sha256',
  secret: signingSecret,
  payload: rawBody,
  expected: req.headers['x-signature'],
});

Trigger binding factories

import {
  createPollingTriggerBindingFactory,
  createWebhookTriggerBindingFactory,
} from '@keystrokehq/integration-authoring';

These are used to declare polling and webhook triggers that compose with Keystroke's Trigger primitive.

Worked examples

Every integration in the integrations/ directory of this repository uses this package.

License

MIT