@stepyo/server

Stepyo Server SDK — manage flows, webhooks, and analytics from your Node.js backend.

Zero external dependencies. Requires Node.js 18+ (uses native fetch and crypto).

Installation

npm install @stepyo/server

Quick Start

import { StepyoServer } from '@stepyo/server';

const stepyo = new StepyoServer({ apiKey: 'sk_your_key_here' });

// List available flows
const flows = await stepyo.listFlows();
console.log(flows);

// Get a specific flow with steps
const flow = await stepyo.getFlow('onboarding');
console.log(flow.steps);

// Ask AI a question
const answer = await stepyo.ask('How do I create a new project?', {
  pageUrl: '/dashboard',
  lang: 'en',
});
console.log(answer);

// Track an event
await stepyo.trackEvent('flow_completed', {
  flow_key: 'onboarding',
  user_id: 'usr_123',
});

Webhooks

// Create a webhook
const webhook = await stepyo.createWebhook({
  url: 'https://your-app.com/webhooks/stepyo',
  events: ['flow_completed', 'flow_started'],
  description: 'Production webhook',
});
// Save webhook.secret securely — you need it to verify signatures

// List webhooks
const webhooks = await stepyo.listWebhooks();

// Test a webhook
const result = await stepyo.testWebhook(webhook.id);

// Delete a webhook
await stepyo.deleteWebhook(webhook.id);

Webhook Signature Verification

Verify incoming webhook payloads to ensure they come from Stepyo:

import express from 'express';
import { StepyoServer } from '@stepyo/server';

const app = express();
app.use(express.json());

app.post('/webhooks/stepyo', (req, res) => {
  const signature = req.headers['x-stepyo-signature'] as string;
  const isValid = StepyoServer.verifySignature(
    JSON.stringify(req.body),
    signature,
    process.env.STEPYO_WEBHOOK_SECRET!
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Handle the event
  const { event, data } = req.body;
  console.log(`Received ${event}:`, data);

  res.status(200).send('OK');
});

Error Handling

All API errors throw a StepyoError with status and code properties:

import { StepyoServer, StepyoError } from '@stepyo/server';

try {
  const flow = await stepyo.getFlow('nonexistent');
} catch (err) {
  if (err instanceof StepyoError) {
    console.error(`Error ${err.status}: ${err.message} (${err.code})`);
  }
}

Configuration

const stepyo = new StepyoServer({
  apiKey: 'sk_your_key_here',       // Required
  baseUrl: 'https://custom.url',     // Optional, defaults to https://app.stepyo.com.br
});

License

MIT