@praxium/sdk 0.2.4

package/dist/revalidation.d.ts

@@ -0,0 +1,28 @@
+/**
+ * ISR Revalidation Handler for Tenant Websites
+ *
+ * When admin updates data in the platform, a webhook triggers
+ * revalidation on the tenant's public website. This handler
+ * validates the secret and calls Next.js revalidatePath().
+ *
+ * Usage in tenant website's `app/api/revalidate/route.ts`:
+ *
+ * ```ts
+ * import { createRevalidationHandler } from '@praxium/sdk/revalidation'
+ *
+ * export const POST = createRevalidationHandler({
+ *   secret: process.env.PRAXIUM_REVALIDATION_SECRET!,
+ * })
+ * ```
+ */
+interface RevalidationConfig {
+    /** Shared secret for webhook authentication */
+    secret: string;
+}
+/**
+ * Creates a Next.js route handler that revalidates ISR pages
+ * when triggered by the Praxium platform webhook.
+ */
+declare function createRevalidationHandler(config: RevalidationConfig): (request: Request) => Promise<Response>;
+
+export { createRevalidationHandler };

package/dist/revalidation.js

@@ -0,0 +1,46 @@
+// src/revalidation.ts
+function isSecretValid(provided, expected) {
+  const encoder = new TextEncoder();
+  const a = encoder.encode(provided);
+  const b = encoder.encode(expected);
+  if (a.length !== b.length) {
+    return false;
+  }
+  let mismatch = 0;
+  for (let i = 0; i < a.length; i++) {
+    mismatch |= a[i] ^ b[i];
+  }
+  return mismatch === 0;
+}
+function createRevalidationHandler(config) {
+  return async (request) => {
+    let body;
+    try {
+      body = await request.json();
+    } catch {
+      return Response.json({ error: "Invalid JSON body" }, { status: 400 });
+    }
+    if (!isSecretValid(body.secret, config.secret)) {
+      return Response.json(
+        { error: "Invalid revalidation secret" },
+        { status: 401 }
+      );
+    }
+    const paths = body.paths ?? ["/"];
+    try {
+      const { revalidatePath } = await import("next/cache");
+      for (const path of paths) {
+        revalidatePath(path);
+      }
+    } catch {
+      return Response.json(
+        { error: "Revalidation failed \u2014 next/cache not available" },
+        { status: 500 }
+      );
+    }
+    return Response.json({ revalidated: true, paths });
+  };
+}
+export {
+  createRevalidationHandler
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@praxium/sdk",
+  "version": "0.2.4",
+  "description": "TypeScript SDK for Praxium public tenant API — auto-generated from OpenAPI spec",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./revalidation": {
+      "import": "./dist/revalidation.js",
+      "types": "./dist/revalidation.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "generate": "openapi-ts",
+    "build": "tsup src/index.ts src/revalidation.ts --format esm --dts --clean --external next",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@hey-api/openapi-ts": "^0.92.4",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.18"
+  },
+  "peerDependencies": {
+    "next": ">=14.0.0"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "praxium",
+    "sdk",
+    "openapi",
+    "physiotherapy",
+    "tenant-api"
+  ],
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/praxium_platform/core/sdk.git"
+  }
+}

package/src/errors.ts

@@ -0,0 +1,126 @@
+/**
+ * Typed error hierarchy for the Praxium SDK.
+ *
+ * Every method on `TenantClient` throws one of these errors when the
+ * API returns a non-2xx response. Consumers can catch a specific
+ * subclass (e.g. `PraxiumNotFoundError`) or the base `PraxiumError`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   const hours = await client.getOpeningHours()
+ * } catch (err) {
+ *   if (err instanceof PraxiumNotFoundError) {
+ *     // tenant slug is invalid
+ *   }
+ * }
+ * ```
+ */
+
+import type { ApiError } from './generated/types.gen'
+
+/** Validation error detail from the API */
+export type ValidationDetail = NonNullable<ApiError['details']>[number]
+
+// ─── Base Error ──────────────────────────────────────────────────────
+
+/**
+ * Base error for all Praxium API failures.
+ *
+ * Properties mirror the `ApiError` response body from the platform:
+ * - `status`    — HTTP status code
+ * - `errorCode` — Machine-readable code (e.g. `'TENANT_NOT_FOUND'`)
+ * - `message`   — Human-readable explanation
+ * - `details`   — Optional validation error details (400 responses only)
+ */
+export class PraxiumError extends Error {
+  override name: string
+
+  constructor(
+    public readonly status: number,
+    public readonly errorCode: string,
+    message: string,
+    public readonly details?: ApiError['details']
+  ) {
+    super(message)
+    this.name = 'PraxiumError'
+    // Restore prototype chain broken by extending built-ins
+    Object.setPrototypeOf(this, new.target.prototype)
+  }
+}
+
+// ─── 400 Validation ──────────────────────────────────────────────────
+
+/** Thrown when the server rejects the request body (HTTP 400). */
+export class PraxiumValidationError extends PraxiumError {
+  constructor(
+    errorCode: string,
+    message: string,
+    details?: ApiError['details']
+  ) {
+    super(400, errorCode, message, details)
+    this.name = 'PraxiumValidationError'
+  }
+}
+
+// ─── 401 Authentication ──────────────────────────────────────────────
+
+/** Thrown when the API key is missing or invalid (HTTP 401). */
+export class PraxiumAuthError extends PraxiumError {
+  constructor(errorCode: string, message: string) {
+    super(401, errorCode, message)
+    this.name = 'PraxiumAuthError'
+  }
+}
+
+// ─── 403 Forbidden ───────────────────────────────────────────────────
+
+/** Thrown when the API key does not match the requested tenant (HTTP 403). */
+export class PraxiumForbiddenError extends PraxiumError {
+  constructor(errorCode: string, message: string) {
+    super(403, errorCode, message)
+    this.name = 'PraxiumForbiddenError'
+  }
+}
+
+// ─── 404 Not Found ───────────────────────────────────────────────────
+
+/** Thrown when the tenant is not found or inactive (HTTP 404). */
+export class PraxiumNotFoundError extends PraxiumError {
+  constructor(errorCode: string, message: string) {
+    super(404, errorCode, message)
+    this.name = 'PraxiumNotFoundError'
+  }
+}
+
+// ─── 429 Rate Limit ──────────────────────────────────────────────────
+
+/** Thrown when the rate limit is exceeded (HTTP 429). */
+export class PraxiumRateLimitError extends PraxiumError {
+  constructor(errorCode: string, message: string) {
+    super(429, errorCode, message)
+    this.name = 'PraxiumRateLimitError'
+  }
+}
+
+// ─── Status → Error Mapping ──────────────────────────────────────────
+
+/**
+ * Map of HTTP status codes to their corresponding PraxiumError subclass.
+ * Used internally by `unwrapOrThrow` to construct the correct error.
+ * @internal Not part of the public SDK API — do not re-export from index.ts
+ */
+export const STATUS_ERROR_MAP: Record<
+  number,
+  new (
+    errorCode: string,
+    message: string,
+    details?: ApiError['details']
+  ) => PraxiumError
+> = {
+  400: PraxiumValidationError,
+  401: PraxiumAuthError,
+  403: PraxiumForbiddenError,
+  404: PraxiumNotFoundError,
+  429: PraxiumRateLimitError,
+}

package/src/generated/client/client.gen.ts

@@ -0,0 +1,288 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+import { createSseClient } from '../core/serverSentEvents.gen';
+import type { HttpMethod } from '../core/types.gen';
+import { getValidRequestBody } from '../core/utils.gen';
+import type { Client, Config, RequestOptions, ResolvedRequestOptions } from './types.gen';
+import {
+  buildUrl,
+  createConfig,
+  createInterceptors,
+  getParseAs,
+  mergeConfigs,
+  mergeHeaders,
+  setAuthParams,
+} from './utils.gen';
+
+type ReqInit = Omit<RequestInit, 'body' | 'headers'> & {
+  body?: any;
+  headers: ReturnType<typeof mergeHeaders>;
+};
+
+export const createClient = (config: Config = {}): Client => {
+  let _config = mergeConfigs(createConfig(), config);
+
+  const getConfig = (): Config => ({ ..._config });
+
+  const setConfig = (config: Config): Config => {
+    _config = mergeConfigs(_config, config);
+    return getConfig();
+  };
+
+  const interceptors = createInterceptors<Request, Response, unknown, ResolvedRequestOptions>();
+
+  const beforeRequest = async (options: RequestOptions) => {
+    const opts = {
+      ..._config,
+      ...options,
+      fetch: options.fetch ?? _config.fetch ?? globalThis.fetch,
+      headers: mergeHeaders(_config.headers, options.headers),
+      serializedBody: undefined,
+    };
+
+    if (opts.security) {
+      await setAuthParams({
+        ...opts,
+        security: opts.security,
+      });
+    }
+
+    if (opts.requestValidator) {
+      await opts.requestValidator(opts);
+    }
+
+    if (opts.body !== undefined && opts.bodySerializer) {
+      opts.serializedBody = opts.bodySerializer(opts.body);
+    }
+
+    // remove Content-Type header if body is empty to avoid sending invalid requests
+    if (opts.body === undefined || opts.serializedBody === '') {
+      opts.headers.delete('Content-Type');
+    }
+
+    const url = buildUrl(opts);
+
+    return { opts, url };
+  };
+
+  const request: Client['request'] = async (options) => {
+    // @ts-expect-error
+    const { opts, url } = await beforeRequest(options);
+    const requestInit: ReqInit = {
+      redirect: 'follow',
+      ...opts,
+      body: getValidRequestBody(opts),
+    };
+
+    let request = new Request(url, requestInit);
+
+    for (const fn of interceptors.request.fns) {
+      if (fn) {
+        request = await fn(request, opts);
+      }
+    }
+
+    // fetch must be assigned here, otherwise it would throw the error:
+    // TypeError: Failed to execute 'fetch' on 'Window': Illegal invocation
+    const _fetch = opts.fetch!;
+    let response: Response;
+
+    try {
+      response = await _fetch(request);
+    } catch (error) {
+      // Handle fetch exceptions (AbortError, network errors, etc.)
+      let finalError = error;
+
+      for (const fn of interceptors.error.fns) {
+        if (fn) {
+          finalError = (await fn(error, undefined as any, request, opts)) as unknown;
+        }
+      }
+
+      finalError = finalError || ({} as unknown);
+
+      if (opts.throwOnError) {
+        throw finalError;
+      }
+
+      // Return error response
+      return opts.responseStyle === 'data'
+        ? undefined
+        : {
+            error: finalError,
+            request,
+            response: undefined as any,
+          };
+    }
+
+    for (const fn of interceptors.response.fns) {
+      if (fn) {
+        response = await fn(response, request, opts);
+      }
+    }
+
+    const result = {
+      request,
+      response,
+    };
+
+    if (response.ok) {
+      const parseAs =
+        (opts.parseAs === 'auto'
+          ? getParseAs(response.headers.get('Content-Type'))
+          : opts.parseAs) ?? 'json';
+
+      if (response.status === 204 || response.headers.get('Content-Length') === '0') {
+        let emptyData: any;
+        switch (parseAs) {
+          case 'arrayBuffer':
+          case 'blob':
+          case 'text':
+            emptyData = await response[parseAs]();
+            break;
+          case 'formData':
+            emptyData = new FormData();
+            break;
+          case 'stream':
+            emptyData = response.body;
+            break;
+          case 'json':
+          default:
+            emptyData = {};
+            break;
+        }
+        return opts.responseStyle === 'data'
+          ? emptyData
+          : {
+              data: emptyData,
+              ...result,
+            };
+      }
+
+      let data: any;
+      switch (parseAs) {
+        case 'arrayBuffer':
+        case 'blob':
+        case 'formData':
+        case 'text':
+          data = await response[parseAs]();
+          break;
+        case 'json': {
+          // Some servers return 200 with no Content-Length and empty body.
+          // response.json() would throw; read as text and parse if non-empty.
+          const text = await response.text();
+          data = text ? JSON.parse(text) : {};
+          break;
+        }
+        case 'stream':
+          return opts.responseStyle === 'data'
+            ? response.body
+            : {
+                data: response.body,
+                ...result,
+              };
+      }
+
+      if (parseAs === 'json') {
+        if (opts.responseValidator) {
+          await opts.responseValidator(data);
+        }
+
+        if (opts.responseTransformer) {
+          data = await opts.responseTransformer(data);
+        }
+      }
+
+      return opts.responseStyle === 'data'
+        ? data
+        : {
+            data,
+            ...result,
+          };
+    }
+
+    const textError = await response.text();
+    let jsonError: unknown;
+
+    try {
+      jsonError = JSON.parse(textError);
+    } catch {
+      // noop
+    }
+
+    const error = jsonError ?? textError;
+    let finalError = error;
+
+    for (const fn of interceptors.error.fns) {
+      if (fn) {
+        finalError = (await fn(error, response, request, opts)) as string;
+      }
+    }
+
+    finalError = finalError || ({} as string);
+
+    if (opts.throwOnError) {
+      throw finalError;
+    }
+
+    // TODO: we probably want to return error and improve types
+    return opts.responseStyle === 'data'
+      ? undefined
+      : {
+          error: finalError,
+          ...result,
+        };
+  };
+
+  const makeMethodFn = (method: Uppercase<HttpMethod>) => (options: RequestOptions) =>
+    request({ ...options, method });
+
+  const makeSseFn = (method: Uppercase<HttpMethod>) => async (options: RequestOptions) => {
+    const { opts, url } = await beforeRequest(options);
+    return createSseClient({
+      ...opts,
+      body: opts.body as BodyInit | null | undefined,
+      headers: opts.headers as unknown as Record<string, string>,
+      method,
+      onRequest: async (url, init) => {
+        let request = new Request(url, init);
+        for (const fn of interceptors.request.fns) {
+          if (fn) {
+            request = await fn(request, opts);
+          }
+        }
+        return request;
+      },
+      serializedBody: getValidRequestBody(opts) as BodyInit | null | undefined,
+      url,
+    });
+  };
+
+  return {
+    buildUrl,
+    connect: makeMethodFn('CONNECT'),
+    delete: makeMethodFn('DELETE'),
+    get: makeMethodFn('GET'),
+    getConfig,
+    head: makeMethodFn('HEAD'),
+    interceptors,
+    options: makeMethodFn('OPTIONS'),
+    patch: makeMethodFn('PATCH'),
+    post: makeMethodFn('POST'),
+    put: makeMethodFn('PUT'),
+    request,
+    setConfig,
+    sse: {
+      connect: makeSseFn('CONNECT'),
+      delete: makeSseFn('DELETE'),
+      get: makeSseFn('GET'),
+      head: makeSseFn('HEAD'),
+      options: makeSseFn('OPTIONS'),
+      patch: makeSseFn('PATCH'),
+      post: makeSseFn('POST'),
+      put: makeSseFn('PUT'),
+      trace: makeSseFn('TRACE'),
+    },
+    trace: makeMethodFn('TRACE'),
+  } as Client;
+};

package/src/generated/client/index.ts

@@ -0,0 +1,25 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+export type { Auth } from '../core/auth.gen';
+export type { QuerySerializerOptions } from '../core/bodySerializer.gen';
+export {
+  formDataBodySerializer,
+  jsonBodySerializer,
+  urlSearchParamsBodySerializer,
+} from '../core/bodySerializer.gen';
+export { buildClientParams } from '../core/params.gen';
+export { serializeQueryKeyValue } from '../core/queryKeySerializer.gen';
+export { createClient } from './client.gen';
+export type {
+  Client,
+  ClientOptions,
+  Config,
+  CreateClientConfig,
+  Options,
+  RequestOptions,
+  RequestResult,
+  ResolvedRequestOptions,
+  ResponseStyle,
+  TDataShape,
+} from './types.gen';
+export { createConfig, mergeHeaders } from './utils.gen';