JavaScript / TypeScript SDK

The @lohisoftsro/yappointment-sdk package provides a type-safe, documented SDK for the yAppointment API. Built on top of the OpenAPI spec, it handles authentication, error handling, and webhook verification out of the box.

Installation

npm install @lohisoftsro/yappointment-sdk

Available on npm under the @lohisoftsro/yappointment-sdk scope.

Requirements:

• Node.js 18+
• TypeScript 5.0+ (optional, for type hints)

Quick Start

Initialize the client with an API key:

import { YApp } from "@lohisoftsro/yappointment-sdk";

const yapp = new YApp({
  apiKey: process.env.YAPP_SECRET_KEY,
});

// Create a booking
const booking = await yapp.bookings.create({
  serviceId: "507f1f77bcf86cd799439011",
  startAt: "2026-04-20T14:00:00+02:00",
  customer: {
    name: "Kovács János",
    email: "janos@example.com",
    phone: "+36701234567",
  },
  idempotencyKey: crypto.randomUUID(),
});

console.log(booking.id);

Authentication Options

API Key (Recommended for Server-to-Server)

const yapp = new YApp({
  apiKey: process.env.YAPP_SECRET_KEY,
});

OAuth Access Token

const yapp = new YApp({
  accessToken: process.env.OAUTH_ACCESS_TOKEN,
});

Custom Base URL

const yapp = new YApp({
  apiKey: process.env.YAPP_SECRET_KEY,
  baseUrl: "http://localhost:11186", // local development
});

Service Modules

The SDK provides the following service modules:

Bookings

Create, fetch, update, and cancel bookings:

// Create a booking
const booking = await yapp.bookings.create({
  serviceId: "507f1f77bcf86cd799439011",
  startAt: "2026-04-20T14:00:00+02:00",
  customer: { name: "John", email: "john@example.com" },
  idempotencyKey: crypto.randomUUID(),
});

// Fetch a single booking
const booking = await yapp.bookings.get("BOOKING_ID");

// List bookings with pagination
const list = await yapp.bookings.list({ limit: 50, cursor: null });

// Update a booking (reschedule, change service/employee/location)
const updated = await yapp.bookings.update("BOOKING_ID", {
  startAt: "2026-04-21T10:00:00+02:00",
});

// Cancel a booking
await yapp.bookings.cancel("BOOKING_ID");

Customers

Manage customer records:

// Create a customer
const customer = await yapp.customers.create({
  name: "Kovács János",
  email: "janos@example.com",
  phone: "+36701234567",
});

// Fetch a customer
const customer = await yapp.customers.get("CUSTOMER_ID");

// List customers
const list = await yapp.customers.list({ limit: 50 });

// Update a customer
const updated = await yapp.customers.update("CUSTOMER_ID", {
  email: "newemail@example.com",
});

Webhooks

Manage webhook endpoints and test deliveries:

// List webhook endpoints
const endpoints = await yapp.webhooks.list();

// Create a webhook endpoint
const webhook = await yapp.webhooks.create({
  url: "https://yourapp.com/webhooks/yapp",
  events: ["booking.created", "booking.cancelled"],
  description: "Booking event notifications",
});

// Get webhook details
const webhook = await yapp.webhooks.get("WEBHOOK_ID");

// Update a webhook
const updated = await yapp.webhooks.update("WEBHOOK_ID", {
  events: ["booking.created", "booking.updated", "booking.cancelled"],
});

// Delete a webhook
await yapp.webhooks.delete("WEBHOOK_ID");

// Send a test event
await yapp.webhooks.test("WEBHOOK_ID");

Me

Get the authenticated company and scopes:

const me = await yapp.me.get();

console.log(me.company.id);
console.log(me.scopes); // ['bookings:read', 'bookings:write', ...]

Analytics

Fetch booking statistics:

const stats = await yapp.analytics.summary({
  from: "2026-01-01",
  to: "2026-12-31",
});

console.log(stats.total_bookings);
console.log(stats.total_revenue); // Money object: { amount, currency }

Public

Fetch public data (no authentication required for some operations):

// List service categories
const categories = await yapp.public.categories();

// Get featured providers
const providers = await yapp.public.featuredProviders();

// Platform statistics
const stats = await yapp.public.statistics();

Error Handling

All SDK methods throw YAppError subclasses. Always wrap API calls in try-catch:

import {
  YAppError,
  AuthenticationError,
  SlotUnavailableError,
  ValidationError,
  RateLimitError,
} from "@lohisoftsro/yappointment-sdk";

try {
  const booking = await yapp.bookings.create({
    serviceId: "SERVICE_ID",
    startAt: "2026-04-20T14:00:00+02:00",
    customer: { name: "John", email: "john@example.com" },
    idempotencyKey: crypto.randomUUID(),
  });
} catch (e) {
  if (e instanceof SlotUnavailableError) {
    // Slot already booked or unavailable
    console.log("Slot unavailable, try another time");
  } else if (e instanceof ValidationError) {
    // Invalid input
    console.log(`Validation failed: ${e.message}`);
  } else if (e instanceof RateLimitError) {
    // Rate limited, retry after e.retryAfter seconds
    console.log(`Rate limited, retry after ${e.retryAfter}s`);
  } else if (e instanceof AuthenticationError) {
    // Missing or invalid API key
    console.log("Invalid API key");
  } else if (e instanceof YAppError) {
    // Generic error
    console.log(`[${e.code}] ${e.message}`);
    console.log(`Request ID: ${e.requestId}`);
  } else {
    // Network or unexpected error
    throw e;
  }
}

Error Properties

All YAppError instances include:

• code — machine-readable error code (e.g., SLOT_UNAVAILABLE)
• message — human-readable error message
• statusCode — HTTP status code
• requestId — request ID for debugging
• details — additional error context

Webhook Verification

Verify webhook signatures using the verifyWebhookSignature() function:

import { verifyWebhookSignature } from "@lohisoftsro/yappointment-sdk";

app.post("/webhooks/yapp", (req, res) => {
  const valid = verifyWebhookSignature({
    payload: req.rawBody, // raw request body (not parsed JSON)
    signature: req.headers["yapp-signature"],
    secret: process.env.YAPP_WEBHOOK_SECRET, // from webhook creation response
  });

  if (!valid) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  // Signature is valid and within tolerance window (default 5 minutes)
  const event = JSON.parse(req.rawBody);
  console.log(`Received ${event.type} event`);

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

Signature Format

The yapp-signature header contains two comma-separated key=value pairs:

yapp-signature: t=1234567890,v1=abcd1234...

• t — Unix timestamp of the webhook generation
• v1 — HMAC-SHA256(timestamp.rawBody, secret) as hex

Runtime Support

The SDK works in the following environments:

• Node.js 18+ — Full support, all features available
• Deno — Compatible with Deno runtime
• Bun — Compatible with Bun runtime
• Browser — Public API keys only (read:profile scope limited, no secret key)

Versioning

The SDK follows semantic versioning and remains compatible with yAppointment API v1. Breaking changes are announced with a major version bump.

Current version: 0.1.0

Source Code

The SDK is built from the OpenAPI spec. Source code is available when the repository is published. For now, use the generated TypeScript types in your IDE for full documentation.

Support

For issues, questions, or feature requests, contact Developer Support at developers@yappointment.com or visit https://developers.yappointment.com.