Your app backend→Booking & Calendar→Google Calendar / Stripe / Resend
Your app calls the mod on your server. The mod saves its records in your database and uses your own provider accounts for the features you enable.
Install the package, run its migrations, configure the mod and start its HTTP service as described in README.md. Set MOD_ORIGIN to the service’s origin. Keep its operator token, customer signing secret and provider keys in your server environment. Use the configured HTTPS service origin in production.
Connect a signed-in customer
Read this customer’s appointments and the configured calendar. Your backend verifies the person’s session and workspace membership, then chooses their actorId and tenantId from its own records. The helper signs a 60-second token limited to this mod and the customer role.
Customer request example
Save this helper beside the installed package’s package.json. Call customerRequest from your authenticated backend with that verified customer record. Set HM_AUTH_SECRET to the same private signing secret used by the mod. Do not construct verifiedCustomer from the browser’s request body.
import { signToken } from './dist/core/auth.js';
export async function customerRequest(verifiedCustomer) {
const token = signToken({
aud: 'helpfulmods', sub: verifiedCustomer.actorId,
tenant: verifiedCustomer.tenantId, role: 'customer', mods: ['booking'],
exp: Math.floor(Date.now() / 1000) + 60, external: false,
}, process.env.HM_AUTH_SECRET);
const response = await fetch(new URL('/api/booking/commands/customer_calendar', process.env.MOD_ORIGIN), {
method: 'POST', redirect: 'error', credentials: 'omit',
signal: AbortSignal.timeout(10000),
headers: { Authorization: 'Bearer ' + token, 'Content-Type': 'application/json' },
body: JSON.stringify({}),
});
if (!response.ok) throw new Error('Customer request failed: ' + response.status);
const result = await response.json();
return result;
}
Check the service from your private admin backend
Read the reservations saved in your booking workspace. This uses the installation’s operator credential for a private administration check. Your backend checks staff permissions before making this request.
Administration request example
Save this as integration-example.mjs and run node --env-file=.env integration-example.mjs. Set HM_API_TOKEN to the private operator token used by the service. These requests do not send email, take payment or call an AI model.
const origin = process.env.MOD_ORIGIN;
const token = process.env.HM_API_TOKEN;
if (!origin || !token) throw new Error('Set MOD_ORIGIN and HM_API_TOKEN');
const response = await fetch(new URL('/api/booking/commands/list', origin), {
method: 'POST', redirect: 'error', credentials: 'omit',
signal: AbortSignal.timeout(10000),
headers: { Authorization: 'Bearer ' + token, 'Content-Type': 'application/json' },
body: JSON.stringify({}),
});
if (!response.ok) throw new Error('Mod request failed: ' + response.status);
console.log(await response.json());
