@fluixi/api 0.0.0-stage → 0.1.0-alpha.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ibrahima Touré
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,38 @@
-# Temporary Holding Version
+# @fluixi/api
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+API route contracts for Fluixi: declare what a route accepts, returns and requires, and get
+validation, a consistent error model, an OpenAPI document and a typed client from the same
+declaration.
+
+```ts
+// src/api/v1/projects/index.ts
+import { route } from '@fluixi/api';
+import { z } from 'zod';
+
+export const POST = route({
+  body: z.object({ name: z.string().min(1) }),
+  response: Project,
+  status: 201,
+  handler: ({ body }) => createProject(body.name),
+});
+```
+
+- **Input**: `params`, `query` and `body`, with any Standard Schema validator (Zod, Valibot,
+  ArkType). Every problem is reported at once, as a 400 `validation_failed`.
+- **Output**: the `response` schema is applied on the way out, so fields it does not name never
+  reach the caller.
+- **Errors**: one shape, `{ error: { code, message, details? } }`. `ApiError` and `notFound`,
+  `conflict` and the others for refusals; anything unexpected is a 500 with a generic message.
+- **Guards**: `route({ guard })` runs before the input is read and types `auth` in the handler.
+  `signedIn()` and `member()` come from `@fluixi/auth/server`.
+- **Revalidation**: `route({ revalidates: ['orgs'] })` names the cached data a success changes;
+  the client refreshes the pages showing it.
+- **OpenAPI**: `openApiRoute(() => apiRoutes, info)` serves a 3.1 document generated from the
+  contracts; `describedBy` includes a library's own document.
+- **Typed client**: `createClient<ApiRoutes>()` from `@fluixi/api/client` knows each route's
+  params, query, body and response.
+- **Protection**: `apiSecurity({ origins, rateLimits })` for headers, CORS, the cross-site check
+  and rate limits.
+
+Documentation: [API contracts](https://docs.fluixi.com/v1/en/api-contracts) and
+[OpenAPI](https://docs.fluixi.com/v1/en/openapi).

package/dist/client.cjs

@@ -0,0 +1,103 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/client.ts
+var client_exports = {};
+__export(client_exports, {
+  ApiClientError: () => ApiClientError,
+  createClient: () => createClient
+});
+module.exports = __toCommonJS(client_exports);
+var ROUTER_REVALIDATE = /* @__PURE__ */ Symbol.for("fluixi.revalidate");
+function defaultRevalidate(names) {
+  if (typeof window === "undefined") return;
+  const revalidate = globalThis[ROUTER_REVALIDATE];
+  revalidate?.(names);
+}
+var ApiClientError = class extends Error {
+  constructor(status, code, message, details) {
+    super(message);
+    this.name = "ApiClientError";
+    this.status = status;
+    this.code = code;
+    this.details = details;
+  }
+};
+function createClient(options = {}) {
+  const { baseUrl = "", credentials = "same-origin" } = options;
+  async function call(method, path, input = {}) {
+    const fetcher = options.fetch ?? globalThis.fetch;
+    const headers = new Headers(typeof options.headers === "function" ? await options.headers() : options.headers);
+    for (const [name, value] of new Headers(input.headers)) headers.set(name, value);
+    headers.set("accept", "application/json");
+    let body;
+    if (input.body !== void 0) {
+      body = JSON.stringify(input.body);
+      headers.set("content-type", "application/json");
+    }
+    const response = await fetcher(baseUrl + fill(path, input.params) + search(input.query), {
+      method,
+      headers,
+      body,
+      credentials,
+      signal: input.signal
+    });
+    const json = (response.headers.get("content-type") ?? "").includes("json");
+    if (!response.ok) {
+      const error = json ? (await response.json().catch(() => null))?.error : void 0;
+      throw new ApiClientError(
+        response.status,
+        typeof error?.code === "string" ? error.code : "http_error",
+        typeof error?.message === "string" ? error.message : response.statusText || `HTTP ${response.status}`,
+        error?.details
+      );
+    }
+    const stale = response.headers.get("x-fx-revalidate");
+    if (stale && options.onRevalidate !== false) {
+      const names = stale.split(",").map((name) => name.trim()).filter(Boolean);
+      if (names.length) (options.onRevalidate ?? defaultRevalidate)(names);
+    }
+    if (response.status === 204 || response.status === 205) return void 0;
+    return json ? response.json() : response.text();
+  }
+  const bind = (method) => (path, input) => call(method, path, input);
+  return {
+    get: bind("GET"),
+    post: bind("POST"),
+    put: bind("PUT"),
+    patch: bind("PATCH"),
+    delete: bind("DELETE")
+  };
+}
+function fill(path, params = {}) {
+  return path.replace(/\{([^}]+)\}/g, (_, name) => {
+    const value = params[name];
+    if (value === void 0 || value === null) throw new TypeError(`Missing path parameter "${name}" for ${path}`);
+    return String(value).split("/").map(encodeURIComponent).join("/");
+  });
+}
+function search(query = {}) {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value === void 0 || value === null) continue;
+    for (const one of Array.isArray(value) ? value : [value]) params.append(key, String(one));
+  }
+  const text = params.toString();
+  return text ? `?${text}` : "";
+}

package/dist/client.d.ts

@@ -0,0 +1,95 @@
+/**
+ * A typed client for a Fluixi API, inferred from its route contracts.
+ *
+ * The API app's `src/api.gen.ts` (written by `@fluixi/start`) maps each path template to its
+ * route module; a client typed with it knows, per method, the params, query and body a route
+ * accepts and what it returns. Nothing from the server is bundled: the map is types only.
+ *
+ * @example
+ * ```ts
+ * import { createClient } from '@fluixi/api/client';
+ * import type { ApiRoutes } from '@acme/api/routes';
+ *
+ * const api = createClient<ApiRoutes>();
+ * const project = await api.get('/api/v1/projects/{id}', { params: { id } });
+ * ```
+ */
+import type { RouteHandler } from './route.js';
+import type { StandardSchemaV1 as Schema } from './standard-schema.js';
+type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * What `api.gen.ts` declares: path template to route module. `object` rather than an index
+ * signature, which the generated interface would not satisfy.
+ */
+export type ApiRouteMap = object;
+type ParamNames<P extends string> = P extends `${string}{${infer Name}}${infer Rest}` ? Name | ParamNames<Rest> : never;
+type Parts<H> = H extends RouteHandler<infer P, infer Q, infer B, infer R, any> ? {
+    contracted: true;
+    params: P;
+    query: Q;
+    body: B;
+    response: R;
+} : {
+    contracted: false;
+    params: undefined;
+    query: undefined;
+    body: undefined;
+    response: undefined;
+};
+type InputOf<S, Fallback> = S extends Schema ? Schema.InferInput<S> : Fallback;
+/** Optional when every field inside may be left out. */
+type Field<K extends string, T> = [T] extends [undefined] ? {
+    [_ in K]?: undefined;
+} : {} extends T ? {
+    [_ in K]?: T;
+} : {
+    [_ in K]: T;
+};
+type ParamsInput<Path extends string, S> = [ParamNames<Path>] extends [never] ? undefined : InputOf<S, Record<ParamNames<Path>, string | number>>;
+type Flatten<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/** The second argument of a call: what the route takes, plus per-call request options. */
+export type CallOptions<Path extends string, H> = Flatten<Field<'params', ParamsInput<Path, Parts<H>['params']>> & Field<'query', InputOf<Parts<H>['query'], Parts<H>['contracted'] extends true ? undefined : Record<string, unknown>>> & Field<'body', InputOf<Parts<H>['body'], Parts<H>['contracted'] extends true ? undefined : unknown>> & {
+    headers?: HeadersInit;
+    signal?: AbortSignal;
+}>;
+/** What a call resolves to: the response schema's output, `unknown` for a route without one. */
+export type CallResult<H> = Parts<H>['response'] extends Schema ? Schema.InferOutput<Parts<H>['response']> : unknown;
+type PathsWith<Routes extends ApiRouteMap, M extends Method> = {
+    [P in keyof Routes & string]: M extends keyof Routes[P] ? P : never;
+}[keyof Routes & string];
+type Handler<Routes extends ApiRouteMap, P extends keyof Routes, M extends Method> = Routes[P][M & keyof Routes[P]];
+type Call<Routes extends ApiRouteMap, M extends Method> = <P extends PathsWith<Routes, M>>(path: P, ...options: {} extends CallOptions<P, Handler<Routes, P, M>> ? [options?: CallOptions<P, Handler<Routes, P, M>>] : [options: CallOptions<P, Handler<Routes, P, M>>]) => Promise<CallResult<Handler<Routes, P, M>>>;
+export interface ApiClient<Routes extends ApiRouteMap> {
+    get: Call<Routes, 'GET'>;
+    post: Call<Routes, 'POST'>;
+    put: Call<Routes, 'PUT'>;
+    patch: Call<Routes, 'PATCH'>;
+    delete: Call<Routes, 'DELETE'>;
+}
+export interface ClientOptions {
+    /** Prepended to every path. Empty by default: the page's own origin, where the web app forwards `/api`. */
+    baseUrl?: string;
+    /** Sent with every call. A function runs per call: during SSR, to forward the visitor's cookie. */
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    /** `same-origin` by default; `include` for a widget calling the API from another site. */
+    credentials?: RequestCredentials;
+    /** `globalThis.fetch` by default. */
+    fetch?: typeof fetch;
+    /**
+     * Called with the cached data names a successful response says it changed (`x-fx-revalidate`).
+     * By default, in a browser, the router revalidates them. `false` ignores the header.
+     */
+    onRevalidate?: ((names: string[]) => void) | false;
+}
+/** A refusal or failure, as the API's error model reports it. */
+export declare class ApiClientError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details: unknown;
+    constructor(status: number, code: string, message: string, details?: unknown);
+}
+export declare function createClient<Routes extends ApiRouteMap>(options?: ClientOptions): ApiClient<Routes>;
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.js

@@ -0,0 +1,87 @@
+// The router registers itself here (`@fluixi/core`), so the client needs no import of it.
+const ROUTER_REVALIDATE = Symbol.for('fluixi.revalidate');
+function defaultRevalidate(names) {
+    // A server render has no routes on screen to reload.
+    if (typeof window === 'undefined')
+        return;
+    const revalidate = globalThis[ROUTER_REVALIDATE];
+    revalidate?.(names);
+}
+/** A refusal or failure, as the API's error model reports it. */
+export class ApiClientError extends Error {
+    status;
+    code;
+    details;
+    constructor(status, code, message, details) {
+        super(message);
+        this.name = 'ApiClientError';
+        this.status = status;
+        this.code = code;
+        this.details = details;
+    }
+}
+export function createClient(options = {}) {
+    const { baseUrl = '', credentials = 'same-origin' } = options;
+    async function call(method, path, input = {}) {
+        const fetcher = options.fetch ?? globalThis.fetch;
+        const headers = new Headers(typeof options.headers === 'function' ? await options.headers() : options.headers);
+        for (const [name, value] of new Headers(input.headers))
+            headers.set(name, value);
+        headers.set('accept', 'application/json');
+        let body;
+        if (input.body !== undefined) {
+            body = JSON.stringify(input.body);
+            headers.set('content-type', 'application/json');
+        }
+        const response = await fetcher(baseUrl + fill(path, input.params) + search(input.query), {
+            method,
+            headers,
+            body,
+            credentials,
+            signal: input.signal,
+        });
+        const json = (response.headers.get('content-type') ?? '').includes('json');
+        if (!response.ok) {
+            const error = json ? (await response.json().catch(() => null))?.error : undefined;
+            throw new ApiClientError(response.status, typeof error?.code === 'string' ? error.code : 'http_error', typeof error?.message === 'string' ? error.message : response.statusText || `HTTP ${response.status}`, error?.details);
+        }
+        const stale = response.headers.get('x-fx-revalidate');
+        if (stale && options.onRevalidate !== false) {
+            const names = stale.split(',').map((name) => name.trim()).filter(Boolean);
+            if (names.length)
+                (options.onRevalidate ?? defaultRevalidate)(names);
+        }
+        if (response.status === 204 || response.status === 205)
+            return undefined;
+        return json ? response.json() : response.text();
+    }
+    const bind = (method) => (path, input) => call(method, path, input);
+    return {
+        get: bind('GET'),
+        post: bind('POST'),
+        put: bind('PUT'),
+        patch: bind('PATCH'),
+        delete: bind('DELETE'),
+    };
+}
+/** `{id}` from params, encoded; a catch-all keeps its slashes. */
+function fill(path, params = {}) {
+    return path.replace(/\{([^}]+)\}/g, (_, name) => {
+        const value = params[name];
+        if (value === undefined || value === null)
+            throw new TypeError(`Missing path parameter "${name}" for ${path}`);
+        return String(value).split('/').map(encodeURIComponent).join('/');
+    });
+}
+/** Repeated keys for arrays, the way the server reads them; undefined left out. */
+function search(query = {}) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null)
+            continue;
+        for (const one of Array.isArray(value) ? value : [value])
+            params.append(key, String(one));
+    }
+    const text = params.toString();
+    return text ? `?${text}` : '';
+}

package/dist/client.mjs

@@ -0,0 +1,82 @@
+// src/client.ts
+var ROUTER_REVALIDATE = /* @__PURE__ */ Symbol.for("fluixi.revalidate");
+function defaultRevalidate(names) {
+  if (typeof window === "undefined") return;
+  const revalidate = globalThis[ROUTER_REVALIDATE];
+  revalidate?.(names);
+}
+var ApiClientError = class extends Error {
+  constructor(status, code, message, details) {
+    super(message);
+    this.name = "ApiClientError";
+    this.status = status;
+    this.code = code;
+    this.details = details;
+  }
+};
+function createClient(options = {}) {
+  const { baseUrl = "", credentials = "same-origin" } = options;
+  async function call(method, path, input = {}) {
+    const fetcher = options.fetch ?? globalThis.fetch;
+    const headers = new Headers(typeof options.headers === "function" ? await options.headers() : options.headers);
+    for (const [name, value] of new Headers(input.headers)) headers.set(name, value);
+    headers.set("accept", "application/json");
+    let body;
+    if (input.body !== void 0) {
+      body = JSON.stringify(input.body);
+      headers.set("content-type", "application/json");
+    }
+    const response = await fetcher(baseUrl + fill(path, input.params) + search(input.query), {
+      method,
+      headers,
+      body,
+      credentials,
+      signal: input.signal
+    });
+    const json = (response.headers.get("content-type") ?? "").includes("json");
+    if (!response.ok) {
+      const error = json ? (await response.json().catch(() => null))?.error : void 0;
+      throw new ApiClientError(
+        response.status,
+        typeof error?.code === "string" ? error.code : "http_error",
+        typeof error?.message === "string" ? error.message : response.statusText || `HTTP ${response.status}`,
+        error?.details
+      );
+    }
+    const stale = response.headers.get("x-fx-revalidate");
+    if (stale && options.onRevalidate !== false) {
+      const names = stale.split(",").map((name) => name.trim()).filter(Boolean);
+      if (names.length) (options.onRevalidate ?? defaultRevalidate)(names);
+    }
+    if (response.status === 204 || response.status === 205) return void 0;
+    return json ? response.json() : response.text();
+  }
+  const bind = (method) => (path, input) => call(method, path, input);
+  return {
+    get: bind("GET"),
+    post: bind("POST"),
+    put: bind("PUT"),
+    patch: bind("PATCH"),
+    delete: bind("DELETE")
+  };
+}
+function fill(path, params = {}) {
+  return path.replace(/\{([^}]+)\}/g, (_, name) => {
+    const value = params[name];
+    if (value === void 0 || value === null) throw new TypeError(`Missing path parameter "${name}" for ${path}`);
+    return String(value).split("/").map(encodeURIComponent).join("/");
+  });
+}
+function search(query = {}) {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value === void 0 || value === null) continue;
+    for (const one of Array.isArray(value) ? value : [value]) params.append(key, String(one));
+  }
+  const text = params.toString();
+  return text ? `?${text}` : "";
+}
+export {
+  ApiClientError,
+  createClient
+};

package/dist/errors.cjs

@@ -0,0 +1,63 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/errors.ts
+var errors_exports = {};
+__export(errors_exports, {
+  ApiError: () => ApiError,
+  badRequest: () => badRequest,
+  conflict: () => conflict,
+  errorResponse: () => errorResponse,
+  forbidden: () => forbidden,
+  notFound: () => notFound,
+  toApiError: () => toApiError,
+  unauthorized: () => unauthorized
+});
+module.exports = __toCommonJS(errors_exports);
+var ApiError = class extends Error {
+  constructor(status, code, message, details) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.code = code;
+    this.details = details;
+  }
+};
+var badRequest = (message, details) => new ApiError(400, "bad_request", message, details);
+var unauthorized = (message = "Sign in to continue.") => new ApiError(401, "unauthorized", message);
+var forbidden = (message = "Not allowed.") => new ApiError(403, "forbidden", message);
+var notFound = (message = "Not found.") => new ApiError(404, "not_found", message);
+var conflict = (message, details) => new ApiError(409, "conflict", message, details);
+function toApiError(error) {
+  if (error instanceof ApiError) return { error, internal: false };
+  const { status, code, message } = error ?? {};
+  if (status === 401 || status === 403) {
+    if (typeof code === "string" && typeof message === "string") return { error: new ApiError(status, code, message), internal: false };
+    return { error: status === 401 ? unauthorized() : forbidden(), internal: false };
+  }
+  return { error: new ApiError(500, "internal", "Something went wrong on our side."), internal: true };
+}
+function errorResponse(error) {
+  const body = { error: { code: error.code, message: error.message } };
+  if (error.details !== void 0) body.error.details = error.details;
+  return new Response(JSON.stringify(body), {
+    status: error.status,
+    headers: { "content-type": "application/json; charset=utf-8" }
+  });
+}

package/dist/errors.d.ts

@@ -0,0 +1,47 @@
+/**
+ * One error model for every contracted route.
+ *
+ * A failure is always `{ error: { code, message, details? } }` with a matching HTTP status. The
+ * code is for programs, the message for people. Nothing from the server's internals reaches the
+ * response: an error that is not an `ApiError` becomes a 500 with a generic message, and the
+ * original is handed to `onError` for logging.
+ */
+/** A failure a handler means to report, with the status and code the caller gets. */
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details: unknown;
+    constructor(status: number, code: string, message: string, details?: unknown);
+}
+/** The body of every error response. */
+export interface ApiErrorBody {
+    error: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+}
+/** One problem with the input, as reported in `details` of a `validation_failed` error. */
+export interface ValidationIssue {
+    /** Where: `body.items.0.name`, `query.page`, `params.id`. */
+    path: string;
+    message: string;
+}
+export declare const badRequest: (message: string, details?: unknown) => ApiError;
+export declare const unauthorized: (message?: string) => ApiError;
+export declare const forbidden: (message?: string) => ApiError;
+export declare const notFound: (message?: string) => ApiError;
+export declare const conflict: (message: string, details?: unknown) => ApiError;
+/**
+ * Anything thrown by a handler, as the `ApiError` the caller sees.
+ *
+ * Auth refusals from `@fluixi/auth` (`requireUser`, the guards) carry a 401 or 403, and a
+ * `code` when they have a more precise one, and are matched by shape, the way `@fluixi/start` matches them, so neither package depends on the other.
+ */
+export declare function toApiError(error: unknown): {
+    error: ApiError;
+    internal: boolean;
+};
+/** An `ApiError` as a JSON response. */
+export declare function errorResponse(error: ApiError): Response;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,qFAAqF;AACrF,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;gBAEd,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAO7E;AAED,wCAAwC;AACxC,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAC7D;AAED,2FAA2F;AAC3F,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,UAAU,GAAI,SAAS,MAAM,EAAE,UAAU,OAAO,aAAuD,CAAC;AACrH,eAAO,MAAM,YAAY,GAAI,gBAAgC,aAA+C,CAAC;AAC7G,eAAO,MAAM,SAAS,GAAI,gBAAwB,aAA4C,CAAC;AAC/F,eAAO,MAAM,QAAQ,GAAI,gBAAsB,aAA4C,CAAC;AAC5F,eAAO,MAAM,QAAQ,GAAI,SAAS,MAAM,EAAE,UAAU,OAAO,aAAoD,CAAC;AAEhH;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAUjF;AAED,wCAAwC;AACxC,wBAAgB,aAAa,CAAC,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAOvD"}

package/dist/errors.js

@@ -0,0 +1,55 @@
+/**
+ * One error model for every contracted route.
+ *
+ * A failure is always `{ error: { code, message, details? } }` with a matching HTTP status. The
+ * code is for programs, the message for people. Nothing from the server's internals reaches the
+ * response: an error that is not an `ApiError` becomes a 500 with a generic message, and the
+ * original is handed to `onError` for logging.
+ */
+/** A failure a handler means to report, with the status and code the caller gets. */
+export class ApiError extends Error {
+    status;
+    code;
+    details;
+    constructor(status, code, message, details) {
+        super(message);
+        this.name = 'ApiError';
+        this.status = status;
+        this.code = code;
+        this.details = details;
+    }
+}
+export const badRequest = (message, details) => new ApiError(400, 'bad_request', message, details);
+export const unauthorized = (message = 'Sign in to continue.') => new ApiError(401, 'unauthorized', message);
+export const forbidden = (message = 'Not allowed.') => new ApiError(403, 'forbidden', message);
+export const notFound = (message = 'Not found.') => new ApiError(404, 'not_found', message);
+export const conflict = (message, details) => new ApiError(409, 'conflict', message, details);
+/**
+ * Anything thrown by a handler, as the `ApiError` the caller sees.
+ *
+ * Auth refusals from `@fluixi/auth` (`requireUser`, the guards) carry a 401 or 403, and a
+ * `code` when they have a more precise one, and are matched by shape, the way `@fluixi/start` matches them, so neither package depends on the other.
+ */
+export function toApiError(error) {
+    if (error instanceof ApiError)
+        return { error, internal: false };
+    const { status, code, message } = (error ?? {});
+    if (status === 401 || status === 403) {
+        // A refusal that names itself (`no_active_organization`) keeps its code and message, so a
+        // client can tell "pick an organisation" from "not allowed".
+        if (typeof code === 'string' && typeof message === 'string')
+            return { error: new ApiError(status, code, message), internal: false };
+        return { error: status === 401 ? unauthorized() : forbidden(), internal: false };
+    }
+    return { error: new ApiError(500, 'internal', 'Something went wrong on our side.'), internal: true };
+}
+/** An `ApiError` as a JSON response. */
+export function errorResponse(error) {
+    const body = { error: { code: error.code, message: error.message } };
+    if (error.details !== undefined)
+        body.error.details = error.details;
+    return new Response(JSON.stringify(body), {
+        status: error.status,
+        headers: { 'content-type': 'application/json; charset=utf-8' },
+    });
+}

package/dist/errors.mjs

@@ -0,0 +1,42 @@
+// src/errors.ts
+var ApiError = class extends Error {
+  constructor(status, code, message, details) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.code = code;
+    this.details = details;
+  }
+};
+var badRequest = (message, details) => new ApiError(400, "bad_request", message, details);
+var unauthorized = (message = "Sign in to continue.") => new ApiError(401, "unauthorized", message);
+var forbidden = (message = "Not allowed.") => new ApiError(403, "forbidden", message);
+var notFound = (message = "Not found.") => new ApiError(404, "not_found", message);
+var conflict = (message, details) => new ApiError(409, "conflict", message, details);
+function toApiError(error) {
+  if (error instanceof ApiError) return { error, internal: false };
+  const { status, code, message } = error ?? {};
+  if (status === 401 || status === 403) {
+    if (typeof code === "string" && typeof message === "string") return { error: new ApiError(status, code, message), internal: false };
+    return { error: status === 401 ? unauthorized() : forbidden(), internal: false };
+  }
+  return { error: new ApiError(500, "internal", "Something went wrong on our side."), internal: true };
+}
+function errorResponse(error) {
+  const body = { error: { code: error.code, message: error.message } };
+  if (error.details !== void 0) body.error.details = error.details;
+  return new Response(JSON.stringify(body), {
+    status: error.status,
+    headers: { "content-type": "application/json; charset=utf-8" }
+  });
+}
+export {
+  ApiError,
+  badRequest,
+  conflict,
+  errorResponse,
+  forbidden,
+  notFound,
+  toApiError,
+  unauthorized
+};