@allservices/sdk-server

Node-only server utilities for the AllServices API: webhook verification, server-side client factory, admin clients, framework middleware (Express, Fastify, Hono), Next.js RSC helpers, and Server Action wrapper.

Status: stable. 5.0.0. Verified against backend manual 2026-05-11. Node 22+.

The exports map declares "browser": null on every entry, so importing this package from a browser bundle fails at build time. This is the primary security boundary.

Install

pnpm add @allservices/sdk-server @allservices/sdk-core @allservices/contracts

Webhook verification

import {
  verifyWebhookSignature,
  constructEvent,
  createWebhookHandler,
} from '@allservices/sdk-server';

const result = verifyWebhookSignature({
  payload: rawBodyBuffer,
  signature: req.headers['x-allservices-signature'],
  timestamp: req.headers['x-allservices-timestamp'],
  secret: [process.env.WEBHOOK_SECRET_V1, process.env.WEBHOOK_SECRET_V2],
});

if (!result.valid) {
  return res.status(401).end(result.reason);
}

const event = constructEvent(rawBodyBuffer, signatureHeader, timestampHeader, secret);

const handle = createWebhookHandler({
  'license.activated': async (e) => {
    /* ... */
  },
  'license.revoked': async (e) => {
    /* ... */
  },
});

await handle(event);

The signature scheme is HMAC-SHA256 over ${timestamp}.${payload} with a 5-minute timestamp tolerance and constant-time comparison. Multi-secret support is for rotating webhook secrets without downtime.

Server client

import { createServerClient } from '@allservices/sdk-server';

const client = createServerClient();
const licenses = await client.licensing.list();

Refuses to construct in browser environments. Reads bearerToken from ALLSERVICES_PAT and region from ALLSERVICES_REGION (eu or na) by default.

Admin operations

import { createServerClient } from '@allservices/sdk-server';
import { LicensingAdminClient } from '@allservices/sdk-server';

const client = createServerClient();
const admin = new LicensingAdminClient(client);

await admin.setLicenseState(licenseId, { state: 'suspended', reason: 'fraud' });

Operator endpoints under /v1/licensing/operator/* are exposed only here, never in @allservices/sdk-react — they require operator permissions and are not appropriate for browser bundles.

RSC + Server Actions

// app/dashboard/page.tsx
import { dehydrate, HydrationBoundary, QueryClient } from '@tanstack/react-query';
import { prefetchQuery } from '@allservices/sdk-server';

export default async function Page() {
  const queryClient = new QueryClient();
  await prefetchQuery(queryClient, {
    queryKey: ['licenses'],
    queryFn: () => createServerClient().licensing.list(),
  });
  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <LicenseList />
    </HydrationBoundary>
  );
}

// app/actions/redeem.ts
'use server';
import { z } from 'zod';
import { action } from '@allservices/sdk-server';
import { createServerClient } from '@allservices/sdk-server';

export const redeemLicense = action(z.object({ code: z.string().min(1) }), async ({ code }) =>
  createServerClient().licensing.redeem({ code }),
);

Bundle size

Per size-limit:

• index (esm) ≤ 15 KB min+gz (ignoring sdk-core, contracts, @tanstack/react-query, zod).

The package has "browser": null on every entry; bundlers refuse it in a browser build. createServerClient adds a runtime guard for completeness.

Links

• docs/sdk/WEBHOOK_OPERATIONS.md — signing, rotation, retry policy, sample handlers (Express + Fastify + Hono + manual).
• docs/sdk/BEARER_TOKEN_MODE.md — ALLSERVICES_PAT and tokenStorage.
• RECIPES.md — 8. Server-side admin operations from a route handler, 9. Webhook receiver with multi-secret rotation.
• SECURITY.md — server boundary discussion.
• MIGRATION.md — upgrading from 4.x.

License

UNLICENSED — internal AllServices use only.