storybooker 0.19.4 → 0.22.0-canary.0

package/dist/utils/store.mjs

@@ -0,0 +1,54 @@
+import { createConsoleLoggerAdapter } from "../~internal/adapter/logger.mjs";
+import { DEFAULT_LOCALE } from "../~internal/constants.mjs";
+import { SuperHeaders } from "@remix-run/headers";
+import { endTime, startTime } from "hono/timing";
+import { AsyncLocalStorage } from "node:async_hooks";
+
+//#region src/utils/store.ts
+const localStore = new AsyncLocalStorage();
+function getStore() {
+	const value = localStore.getStore();
+	if (!value) throw new Error("Store not found.");
+	return value;
+}
+function getStoreOrNull() {
+	const value = localStore.getStore();
+	if (!value) return null;
+	return value;
+}
+function setupStore(options, initPromises) {
+	return async (ctx, next) => {
+		const logger = options.logger ?? createConsoleLoggerAdapter();
+		startTime(ctx, "init-adapters", "Initialize adapters");
+		await initPromises;
+		endTime(ctx, "init-adapters");
+		const request = ctx.req.raw;
+		const headers = new SuperHeaders(request.headers);
+		const locale = headers.acceptLanguage.languages[0] ?? DEFAULT_LOCALE;
+		startTime(ctx, "get-user", "Get user details");
+		const user = await options.auth?.getUserDetails({
+			logger,
+			request: request.clone()
+		});
+		endTime(ctx, "get-user");
+		startTime(ctx, "request-handler", "Handle request");
+		localStore.enterWith({
+			...options,
+			abortSignal: request.signal,
+			auth: options.auth,
+			headers,
+			locale,
+			logger,
+			prefix: options.config?.prefix ?? "",
+			request,
+			url: request.url,
+			user
+		});
+		await next();
+		endTime(ctx, "request-handler");
+	};
+}
+
+//#endregion
+export { getStore, getStoreOrNull, localStore, setupStore };
+//# sourceMappingURL=store.mjs.map

package/dist/utils/store.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.mjs","names":[],"sources":["../../src/utils/store.ts"],"sourcesContent":["import { SuperHeaders } from \"@remix-run/headers\";\nimport type { MiddlewareHandler } from \"hono\";\nimport { endTime, startTime } from \"hono/timing\";\nimport { AsyncLocalStorage } from \"node:async_hooks\";\nimport {\n  createConsoleLoggerAdapter,\n  type AuthAdapter,\n  type LoggerAdapter,\n} from \"../adapters/_internal/index.ts\";\nimport type { RouterOptions, StoryBookerUser } from \"../types.ts\";\nimport type { ErrorParser } from \"../utils/error.ts\";\nimport { DEFAULT_LOCALE } from \"./constants.ts\";\n\nexport interface Store extends RouterOptions<StoryBookerUser> {\n  abortSignal: AbortSignal | undefined;\n  errorParser?: ErrorParser;\n  headers: SuperHeaders;\n  locale: string;\n  logger: LoggerAdapter;\n  prefix: string;\n  request: Request;\n  url: string;\n  user: StoryBookerUser | null | undefined;\n}\n\nexport const localStore = new AsyncLocalStorage<Store>();\n\nexport function getStore(): Store {\n  const value = localStore.getStore();\n  if (!value) {\n    throw new Error(\"Store not found.\");\n  }\n\n  return value;\n}\n\nexport function getStoreOrNull(): Store | null {\n  const value = localStore.getStore();\n  if (!value) {\n    return null;\n  }\n\n  return value;\n}\n\nexport function setupStore<User extends StoryBookerUser>(\n  options: RouterOptions<User>,\n  initPromises: Promise<unknown>,\n): MiddlewareHandler {\n  return async (ctx, next) => {\n    const logger = options.logger ?? createConsoleLoggerAdapter();\n\n    startTime(ctx, \"init-adapters\", \"Initialize adapters\");\n    await initPromises;\n    endTime(ctx, \"init-adapters\");\n\n    const request = ctx.req.raw;\n    const headers = new SuperHeaders(request.headers);\n    const locale = headers.acceptLanguage.languages[0] ?? DEFAULT_LOCALE;\n\n    startTime(ctx, \"get-user\", \"Get user details\");\n    const user = await options.auth?.getUserDetails({\n      logger,\n      request: request.clone(),\n    });\n    endTime(ctx, \"get-user\");\n\n    startTime(ctx, \"request-handler\", \"Handle request\");\n    localStore.enterWith({\n      ...options,\n      abortSignal: request.signal,\n      auth: options.auth as AuthAdapter | undefined,\n      headers,\n      locale,\n      logger,\n      prefix: options.config?.prefix ?? \"\",\n      request,\n      url: request.url,\n      user,\n    });\n\n    await next();\n    endTime(ctx, \"request-handler\");\n  };\n}\n"],"mappings":";;;;;;;AAyBA,MAAa,aAAa,IAAI,mBAA0B;AAExD,SAAgB,WAAkB;CAChC,MAAM,QAAQ,WAAW,UAAU;AACnC,KAAI,CAAC,MACH,OAAM,IAAI,MAAM,mBAAmB;AAGrC,QAAO;;AAGT,SAAgB,iBAA+B;CAC7C,MAAM,QAAQ,WAAW,UAAU;AACnC,KAAI,CAAC,MACH,QAAO;AAGT,QAAO;;AAGT,SAAgB,WACd,SACA,cACmB;AACnB,QAAO,OAAO,KAAK,SAAS;EAC1B,MAAM,SAAS,QAAQ,UAAU,4BAA4B;AAE7D,YAAU,KAAK,iBAAiB,sBAAsB;AACtD,QAAM;AACN,UAAQ,KAAK,gBAAgB;EAE7B,MAAM,UAAU,IAAI,IAAI;EACxB,MAAM,UAAU,IAAI,aAAa,QAAQ,QAAQ;EACjD,MAAM,SAAS,QAAQ,eAAe,UAAU,MAAM;AAEtD,YAAU,KAAK,YAAY,mBAAmB;EAC9C,MAAM,OAAO,MAAM,QAAQ,MAAM,eAAe;GAC9C;GACA,SAAS,QAAQ,OAAO;GACzB,CAAC;AACF,UAAQ,KAAK,WAAW;AAExB,YAAU,KAAK,mBAAmB,iBAAiB;AACnD,aAAW,UAAU;GACnB,GAAG;GACH,aAAa,QAAQ;GACrB,MAAM,QAAQ;GACd;GACA;GACA;GACA,QAAQ,QAAQ,QAAQ,UAAU;GAClC;GACA,KAAK,QAAQ;GACb;GACD,CAAC;AAEF,QAAM,MAAM;AACZ,UAAQ,KAAK,kBAAkB"}

package/dist/utils/ui-utils.mjs

@@ -0,0 +1,38 @@
+import { getStore } from "./store.mjs";
+import { urlBuilderWithoutStore } from "../urls.mjs";
+
+//#region src/utils/ui-utils.ts
+function createUIAdapterOptions() {
+	const { auth, database, storage, ui, locale, logger, url, user } = getStore();
+	return {
+		isAuthEnabled: Boolean(auth),
+		locale,
+		logger,
+		url,
+		urlBuilder: urlBuilderWithoutStore,
+		user,
+		adaptersMetadata: {
+			auth: auth?.metadata,
+			database: database?.metadata,
+			logger: logger?.metadata,
+			storage: storage?.metadata,
+			ui: ui?.metadata
+		}
+	};
+}
+function createUIResultResponse(ctx, render, props, init) {
+	return uiResultResponse(ctx, render(props, createUIAdapterOptions()), init);
+}
+async function uiResultResponse(ctx, result, init) {
+	if (result instanceof Promise) {
+		const awaitedResult = await result;
+		if (awaitedResult instanceof Response) return awaitedResult;
+		return ctx.html(awaitedResult);
+	}
+	if (result instanceof Response) return result;
+	return ctx.html(result, init);
+}
+
+//#endregion
+export { createUIAdapterOptions, createUIResultResponse, uiResultResponse };
+//# sourceMappingURL=ui-utils.mjs.map

package/dist/utils/ui-utils.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-utils.mjs","names":[],"sources":["../../src/utils/ui-utils.ts"],"sourcesContent":["import type { Context } from \"hono\";\nimport type { UIAdapterOptions, UIResult } from \"../adapters/_internal/ui.ts\";\nimport { urlBuilderWithoutStore } from \"../urls.ts\";\nimport { getStore } from \"./store.ts\";\n\nexport function createUIAdapterOptions(): UIAdapterOptions {\n  const { auth, database, storage, ui, locale, logger, url, user } = getStore();\n\n  return {\n    isAuthEnabled: Boolean(auth),\n    locale,\n    logger,\n    url,\n    urlBuilder: urlBuilderWithoutStore,\n    user,\n    adaptersMetadata: {\n      auth: auth?.metadata,\n      database: database?.metadata,\n      logger: logger?.metadata,\n      storage: storage?.metadata,\n      ui: ui?.metadata,\n    },\n  };\n}\n\n// oxlint-disable-next-line max-params\nexport function createUIResultResponse<Props>(\n  ctx: Context,\n  render: (props: Props, options: UIAdapterOptions) => UIResult,\n  props: NoInfer<Props>,\n  init?: ResInit,\n): Promise<Response> {\n  return uiResultResponse(ctx, render(props, createUIAdapterOptions()), init);\n}\n\nexport async function uiResultResponse(\n  ctx: Context,\n  result: UIResult,\n  init?: ResInit,\n): Promise<Response> {\n  if (result instanceof Promise) {\n    const awaitedResult = await result;\n    if (awaitedResult instanceof Response) {\n      return awaitedResult;\n    }\n\n    return ctx.html(awaitedResult);\n  }\n\n  if (result instanceof Response) {\n    return result;\n  }\n\n  return ctx.html(result, init);\n}\n\ntype ResInit = Parameters<Context[\"html\"]>[1];\n"],"mappings":";;;;AAKA,SAAgB,yBAA2C;CACzD,MAAM,EAAE,MAAM,UAAU,SAAS,IAAI,QAAQ,QAAQ,KAAK,SAAS,UAAU;AAE7E,QAAO;EACL,eAAe,QAAQ,KAAK;EAC5B;EACA;EACA;EACA,YAAY;EACZ;EACA,kBAAkB;GAChB,MAAM,MAAM;GACZ,UAAU,UAAU;GACpB,QAAQ,QAAQ;GAChB,SAAS,SAAS;GAClB,IAAI,IAAI;GACT;EACF;;AAIH,SAAgB,uBACd,KACA,QACA,OACA,MACmB;AACnB,QAAO,iBAAiB,KAAK,OAAO,OAAO,wBAAwB,CAAC,EAAE,KAAK;;AAG7E,eAAsB,iBACpB,KACA,QACA,MACmB;AACnB,KAAI,kBAAkB,SAAS;EAC7B,MAAM,gBAAgB,MAAM;AAC5B,MAAI,yBAAyB,SAC3B,QAAO;AAGT,SAAO,IAAI,KAAK,cAAc;;AAGhC,KAAI,kBAAkB,SACpB,QAAO;AAGT,QAAO,IAAI,KAAK,QAAQ,KAAK"}

package/dist/utils/url-utils.d.mts

@@ -0,0 +1,10 @@
+import "../~internal/router.mjs";
+import { hc } from "hono/client";
+
+//#region src/utils/url-utils.d.ts
+
+declare function generatePrefixFromBaseRoute(baseRoute: string): `/${string}` | undefined;
+declare function urlJoin(...parts: string[]): string;
+//#endregion
+export { generatePrefixFromBaseRoute, urlJoin };
+//# sourceMappingURL=url-utils.d.mts.map

package/dist/utils/url-utils.mjs

@@ -0,0 +1,54 @@
+import { hc } from "hono/client";
+
+//#region src/utils/url-utils.ts
+function linkRoute(link, options) {
+	const { baseUrl, searchParams } = options;
+	if (typeof link === "string") {
+		if (baseUrl !== void 0) return appendSearchParamsToURL(new URL(link, baseUrl), searchParams).toString();
+		return link;
+	}
+	if (link instanceof URL) return appendSearchParamsToURL(link, searchParams).toString();
+	if (baseUrl) return appendSearchParamsToURL(link(hc(baseUrl)), searchParams).toString();
+	const dummyBaseUrl = "http://host.local";
+	return appendSearchParamsToURL(link(hc(dummyBaseUrl)), searchParams).toString().replace(dummyBaseUrl, "");
+}
+function appendSearchParamsToURL(url, searchParams) {
+	searchParams?.forEach((value, key) => {
+		url.searchParams.append(key, value);
+	});
+	return url;
+}
+function generatePrefixFromBaseRoute(baseRoute) {
+	if (!baseRoute) return;
+	if (baseRoute.startsWith("/")) return baseRoute;
+	return `/${baseRoute}`;
+}
+function urlJoin(...parts) {
+	if (parts.length === 0) return "";
+	let protocol = "";
+	let host = "";
+	const match = parts[0]?.match(/^([a-zA-Z][a-zA-Z0-9+\-.]*:)?(\/\/[^/?#]*)?/);
+	if (match && (match[1] || match[2])) {
+		protocol = match[1] ?? "";
+		host = match[2] ?? "";
+		const remainder = parts[0]?.slice((match[0] || "").length);
+		parts = remainder ? [remainder, ...parts.slice(1)] : parts.slice(1);
+	}
+	const segments = [];
+	for (const part of parts) for (const seg of part.split("/")) {
+		if (!seg || seg === ".") continue;
+		if (seg === "..") {
+			if (segments.length > 0) segments.pop();
+		} else segments.push(seg);
+	}
+	let result = "";
+	if (protocol || host) {
+		result = protocol + host;
+		if (segments.length > 0) result += segments[0]?.startsWith("?") || segments[0]?.startsWith("#") ? "" : `/${segments.join("/")}`;
+	} else result = `/${segments.join("/")}`;
+	return result;
+}
+
+//#endregion
+export { generatePrefixFromBaseRoute, linkRoute, urlJoin };
+//# sourceMappingURL=url-utils.mjs.map

package/dist/utils/url-utils.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-utils.mjs","names":["segments: string[]"],"sources":["../../src/utils/url-utils.ts"],"sourcesContent":["import { hc } from \"hono/client\";\nimport type { AppRouter } from \"../routers/_app-router\";\n\ntype HonoClient = ReturnType<typeof hc<AppRouter>>;\n\nexport function linkRoute(\n  link: ((client: HonoClient) => URL) | URL | string,\n  options: { baseUrl?: string; searchParams?: URLSearchParams },\n): string {\n  const { baseUrl, searchParams } = options;\n\n  if (typeof link === \"string\") {\n    if (baseUrl !== undefined) {\n      return appendSearchParamsToURL(new URL(link, baseUrl), searchParams).toString();\n    }\n    return link;\n  }\n\n  if (link instanceof URL) {\n    return appendSearchParamsToURL(link, searchParams).toString();\n  }\n\n  if (baseUrl) {\n    const client = hc<AppRouter>(baseUrl);\n\n    return appendSearchParamsToURL(link(client), searchParams).toString();\n  }\n\n  const dummyBaseUrl = \"http://host.local\";\n  const client = hc<AppRouter>(dummyBaseUrl);\n  const url = appendSearchParamsToURL(link(client), searchParams).toString();\n  return url.replace(dummyBaseUrl, \"\");\n}\n\nfunction appendSearchParamsToURL(url: URL, searchParams: URLSearchParams | undefined): URL {\n  // oxlint-disable-next-line no-array-for-each\n  searchParams?.forEach((value, key) => {\n    url.searchParams.append(key, value);\n  });\n\n  return url;\n}\n\nexport function urlSearchParamsToObject(\n  query: URLSearchParams | FormData,\n): Record<string, unknown> {\n  const result: Record<string, unknown> = {};\n\n  for (const key of query.keys()) {\n    const values = query.getAll(key);\n    // If multiple values for the same key, return array, else single value string\n    result[key] = values.length > 1 ? values : values[0];\n  }\n\n  return result;\n}\n\nexport function generatePrefixFromBaseRoute(baseRoute: string): `/${string}` | undefined {\n  if (!baseRoute) {\n    return undefined;\n  }\n  if (baseRoute.startsWith(\"/\")) {\n    return baseRoute as `/${string}`;\n  }\n  return `/${baseRoute}` as const;\n}\n\nexport function urlJoin(...parts: string[]): string {\n  if (parts.length === 0) {\n    return \"\";\n  }\n  let protocol = \"\";\n  let host = \"\";\n  // Detect protocol + host in the first argument if present\n  const match = parts[0]?.match(/^([a-zA-Z][a-zA-Z0-9+\\-.]*:)?(\\/\\/[^/?#]*)?/);\n  if (match && (match[1] || match[2])) {\n    protocol = match[1] ?? \"\"; // e.g. \"https:\"\n    host = match[2] ?? \"\"; // e.g. \"//example.com\"\n    const remainder = parts[0]?.slice((match[0] || \"\").length);\n    parts = remainder ? [remainder, ...parts.slice(1)] : parts.slice(1);\n  }\n  const segments: string[] = [];\n  for (const part of parts) {\n    for (const seg of part.split(\"/\")) {\n      if (!seg || seg === \".\") {\n        continue;\n      }\n      if (seg === \"..\") {\n        // Don't pop past the beginning\n        if (segments.length > 0) {\n          segments.pop();\n        }\n      } else {\n        segments.push(seg);\n      }\n    }\n  }\n  // Build the final URL\n  let result = \"\";\n  if (protocol || host) {\n    result = protocol + host;\n    if (segments.length > 0) {\n      // Ensure separator slash between host and path\n      result +=\n        segments[0]?.startsWith(\"?\") || segments[0]?.startsWith(\"#\")\n          ? \"\"\n          : `/${segments.join(\"/\")}`;\n    }\n  } else {\n    result = `/${segments.join(\"/\")}`;\n  }\n  return result;\n}\n"],"mappings":";;;AAKA,SAAgB,UACd,MACA,SACQ;CACR,MAAM,EAAE,SAAS,iBAAiB;AAElC,KAAI,OAAO,SAAS,UAAU;AAC5B,MAAI,YAAY,OACd,QAAO,wBAAwB,IAAI,IAAI,MAAM,QAAQ,EAAE,aAAa,CAAC,UAAU;AAEjF,SAAO;;AAGT,KAAI,gBAAgB,IAClB,QAAO,wBAAwB,MAAM,aAAa,CAAC,UAAU;AAG/D,KAAI,QAGF,QAAO,wBAAwB,KAFhB,GAAc,QAAQ,CAEM,EAAE,aAAa,CAAC,UAAU;CAGvE,MAAM,eAAe;AAGrB,QADY,wBAAwB,KADrB,GAAc,aAAa,CACM,EAAE,aAAa,CAAC,UAAU,CAC/D,QAAQ,cAAc,GAAG;;AAGtC,SAAS,wBAAwB,KAAU,cAAgD;AAEzF,eAAc,SAAS,OAAO,QAAQ;AACpC,MAAI,aAAa,OAAO,KAAK,MAAM;GACnC;AAEF,QAAO;;AAiBT,SAAgB,4BAA4B,WAA6C;AACvF,KAAI,CAAC,UACH;AAEF,KAAI,UAAU,WAAW,IAAI,CAC3B,QAAO;AAET,QAAO,IAAI;;AAGb,SAAgB,QAAQ,GAAG,OAAyB;AAClD,KAAI,MAAM,WAAW,EACnB,QAAO;CAET,IAAI,WAAW;CACf,IAAI,OAAO;CAEX,MAAM,QAAQ,MAAM,IAAI,MAAM,8CAA8C;AAC5E,KAAI,UAAU,MAAM,MAAM,MAAM,KAAK;AACnC,aAAW,MAAM,MAAM;AACvB,SAAO,MAAM,MAAM;EACnB,MAAM,YAAY,MAAM,IAAI,OAAO,MAAM,MAAM,IAAI,OAAO;AAC1D,UAAQ,YAAY,CAAC,WAAW,GAAG,MAAM,MAAM,EAAE,CAAC,GAAG,MAAM,MAAM,EAAE;;CAErE,MAAMA,WAAqB,EAAE;AAC7B,MAAK,MAAM,QAAQ,MACjB,MAAK,MAAM,OAAO,KAAK,MAAM,IAAI,EAAE;AACjC,MAAI,CAAC,OAAO,QAAQ,IAClB;AAEF,MAAI,QAAQ,MAEV;OAAI,SAAS,SAAS,EACpB,UAAS,KAAK;QAGhB,UAAS,KAAK,IAAI;;CAKxB,IAAI,SAAS;AACb,KAAI,YAAY,MAAM;AACpB,WAAS,WAAW;AACpB,MAAI,SAAS,SAAS,EAEpB,WACE,SAAS,IAAI,WAAW,IAAI,IAAI,SAAS,IAAI,WAAW,IAAI,GACxD,KACA,IAAI,SAAS,KAAK,IAAI;OAG9B,UAAS,IAAI,SAAS,KAAK,IAAI;AAEjC,QAAO"}

package/dist/~internal/adapter/auth.d.mts

@@ -0,0 +1,123 @@
+import { StoryBookerAdapterMetadata } from "../../utils/adapter-utils.mjs";
+import { LoggerAdapter } from "./logger.mjs";
+
+//#region src/adapters/_internal/auth.d.ts
+
+/**
+ * Service adapter to manage authentication.
+ *
+ * The service is responsible to authorise users from
+ * accessing the app.
+ */
+interface AuthAdapter<AuthUser extends StoryBookerUser = StoryBookerUser> {
+  /**
+   * Metadata about the adapter.
+   */
+  metadata: StoryBookerAdapterMetadata;
+  /**
+   * An optional method that is called on app boot-up
+   * to run async setup functions.
+   * @param options Common options like abortSignal.
+   * @throws if an error occur during initialisation.
+   */
+  init?: (options: Omit<AuthAdapterOptions, "request">) => Promise<void>;
+  /**
+   * Get details about the user and permissions based on incoming request.
+   *
+   * @param options Common options like abortSignal.
+   *
+   * @throws an error or response (redirect-to-login) if it is a unauthenticated/unauthorised request.
+   */
+  getUserDetails: (options: AuthAdapterOptions) => Promise<AuthUser | null>;
+  /**
+   * Get user to login from UI. The returning response should create auth session.
+   * User will be redirected automatically after function is resolved.
+   *
+   * @param options Common options like abortSignal.
+   */
+  login: (options: AuthAdapterOptions) => Promise<Response> | Response;
+  /**
+   * Get user to logout from UI. The returning response should clear auth session.
+   * User will be redirected automatically after function is resolved.
+   *
+   * @param options Common options like abortSignal.
+   */
+  logout: (user: AuthUser, options: AuthAdapterOptions) => Promise<Response> | Response;
+  /**
+   * Render custom HTML in account page. Must return valid HTML string;
+   *
+   * @param options Common options like abortSignal.
+   */
+  renderAccountDetails?: (user: AuthUser, options: AuthAdapterOptions) => Promise<string> | string;
+}
+/**
+ * Type for the callback function to check permissions.
+ *
+ * @param options Common options like abortSignal.
+ *
+ * @returns true to allow access, or following to deny:
+ * - false - returns 403 response
+ * - Response - returns the specified HTTP response
+ */
+type AuthAdapterAuthorise<AuthUser extends StoryBookerUser = StoryBookerUser> = (params: {
+  permission: StoryBookerPermissionWithKey;
+  user: AuthUser;
+}, options: AuthAdapterOptions) => Promise<boolean | Response> | boolean | Response;
+/**  Type of permission to check */
+interface StoryBookerPermission {
+  action: StoryBookerPermissionAction;
+  projectId?: string;
+  resource: StoryBookerPermissionResource;
+}
+/** Permission object with key */
+type StoryBookerPermissionWithKey = StoryBookerPermission & {
+  key: StoryBookerPermissionKey;
+};
+/** Permission in a string format */
+type StoryBookerPermissionKey = `${StoryBookerPermissionResource}:${StoryBookerPermissionAction}`;
+/** Type of possible resources to check permissions for */
+type StoryBookerPermissionResource = "project" | "build" | "tag";
+/** Type of possible actions to check permissions for */
+type StoryBookerPermissionAction = "create" | "read" | "update" | "delete";
+/**
+ * Base representation of a generic User
+ */
+interface StoryBookerUser {
+  /** Name of the user displayed in UI. */
+  displayName: string;
+  /** Unique ID of the user. Could be email-address. */
+  id: string;
+  /** Static URL for User's avatar shown in UI. */
+  imageUrl?: string;
+  /** Title or Team-name of the User shown in UI. */
+  title?: string;
+  /** Permissions assigned to the user. Missing permissions are considered false. */
+  permissions: Partial<Record<StoryBookerPermissionKey, boolean>>;
+}
+/** Common Auth adapter options.  */
+interface AuthAdapterOptions {
+  /** A signal that can be used to cancel the request handling. */
+  abortSignal?: AbortSignal;
+  /** Incoming request (cloned) */
+  request: Request;
+  /** Logger */
+  logger: LoggerAdapter;
+}
+declare const StoryBookerPermissionsAllEnabled: {
+  "build:create": true;
+  "build:delete": true;
+  "project:update": true;
+  "build:read": true;
+  "tag:delete": true;
+  "build:update": true;
+  "tag:create": true;
+  "project:read": true;
+  "project:create": true;
+  "tag:read": true;
+  "project:delete": true;
+  "tag:update": true;
+};
+declare const StoryBookerPermissionsList: ("build:create" | "build:delete" | "build:read" | "build:update" | "project:create" | "project:delete" | "project:read" | "project:update" | "tag:create" | "tag:delete" | "tag:read" | "tag:update")[];
+//#endregion
+export { AuthAdapter, AuthAdapterAuthorise, AuthAdapterOptions, StoryBookerPermission, StoryBookerPermissionAction, StoryBookerPermissionKey, StoryBookerPermissionResource, StoryBookerPermissionWithKey, StoryBookerPermissionsAllEnabled, StoryBookerPermissionsList, StoryBookerUser };
+//# sourceMappingURL=auth.d.mts.map

package/dist/~internal/adapter/auth.mjs

@@ -0,0 +1,20 @@
+//#region src/adapters/_internal/auth.ts
+const StoryBookerPermissionsAllEnabled = {
+	"build:create": true,
+	"build:delete": true,
+	"project:update": true,
+	"build:read": true,
+	"tag:delete": true,
+	"build:update": true,
+	"tag:create": true,
+	"project:read": true,
+	"project:create": true,
+	"tag:read": true,
+	"project:delete": true,
+	"tag:update": true
+};
+const StoryBookerPermissionsList = Object.keys(StoryBookerPermissionsAllEnabled);
+
+//#endregion
+export { StoryBookerPermissionsAllEnabled, StoryBookerPermissionsList };
+//# sourceMappingURL=auth.mjs.map

package/dist/~internal/adapter/auth.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.mjs","names":[],"sources":["../../../src/adapters/_internal/auth.ts"],"sourcesContent":["import type { StoryBookerAdapterMetadata } from \"../../utils/adapter-utils.ts\";\nimport type { LoggerAdapter } from \"./logger.ts\";\n\n/**\n * Service adapter to manage authentication.\n *\n * The service is responsible to authorise users from\n * accessing the app.\n */\nexport interface AuthAdapter<AuthUser extends StoryBookerUser = StoryBookerUser> {\n  /**\n   * Metadata about the adapter.\n   */\n  metadata: StoryBookerAdapterMetadata;\n\n  /**\n   * An optional method that is called on app boot-up\n   * to run async setup functions.\n   * @param options Common options like abortSignal.\n   * @throws if an error occur during initialisation.\n   */\n  init?: (options: Omit<AuthAdapterOptions, \"request\">) => Promise<void>;\n\n  /**\n   * Get details about the user and permissions based on incoming request.\n   *\n   * @param options Common options like abortSignal.\n   *\n   * @throws an error or response (redirect-to-login) if it is a unauthenticated/unauthorised request.\n   */\n  getUserDetails: (options: AuthAdapterOptions) => Promise<AuthUser | null>;\n\n  /**\n   * Get user to login from UI. The returning response should create auth session.\n   * User will be redirected automatically after function is resolved.\n   *\n   * @param options Common options like abortSignal.\n   */\n  login: (options: AuthAdapterOptions) => Promise<Response> | Response;\n\n  /**\n   * Get user to logout from UI. The returning response should clear auth session.\n   * User will be redirected automatically after function is resolved.\n   *\n   * @param options Common options like abortSignal.\n   */\n  logout: (user: AuthUser, options: AuthAdapterOptions) => Promise<Response> | Response;\n\n  /**\n   * Render custom HTML in account page. Must return valid HTML string;\n   *\n   * @param options Common options like abortSignal.\n   */\n  renderAccountDetails?: (user: AuthUser, options: AuthAdapterOptions) => Promise<string> | string;\n}\n\n/**\n * Type for the callback function to check permissions.\n *\n * @param options Common options like abortSignal.\n *\n * @returns true to allow access, or following to deny:\n * - false - returns 403 response\n * - Response - returns the specified HTTP response\n */\nexport type AuthAdapterAuthorise<AuthUser extends StoryBookerUser = StoryBookerUser> = (\n  params: {\n    permission: StoryBookerPermissionWithKey;\n    user: AuthUser;\n  },\n  options: AuthAdapterOptions,\n) => Promise<boolean | Response> | boolean | Response;\n\n/**  Type of permission to check */\nexport interface StoryBookerPermission {\n  action: StoryBookerPermissionAction;\n  projectId?: string;\n  resource: StoryBookerPermissionResource;\n}\n/** Permission object with key */\nexport type StoryBookerPermissionWithKey = StoryBookerPermission & {\n  key: StoryBookerPermissionKey;\n};\n/** Permission in a string format */\nexport type StoryBookerPermissionKey =\n  `${StoryBookerPermissionResource}:${StoryBookerPermissionAction}`;\n/** Type of possible resources to check permissions for */\nexport type StoryBookerPermissionResource = \"project\" | \"build\" | \"tag\";\n/** Type of possible actions to check permissions for */\nexport type StoryBookerPermissionAction = \"create\" | \"read\" | \"update\" | \"delete\";\n\n/**\n * Base representation of a generic User\n */\nexport interface StoryBookerUser {\n  /** Name of the user displayed in UI. */\n  displayName: string;\n  /** Unique ID of the user. Could be email-address. */\n  id: string;\n  /** Static URL for User's avatar shown in UI. */\n  imageUrl?: string;\n  /** Title or Team-name of the User shown in UI. */\n  title?: string;\n  /** Permissions assigned to the user. Missing permissions are considered false. */\n  permissions: Partial<Record<StoryBookerPermissionKey, boolean>>;\n}\n\n/** Common Auth adapter options.  */\nexport interface AuthAdapterOptions {\n  /** A signal that can be used to cancel the request handling. */\n  abortSignal?: AbortSignal;\n  /** Incoming request (cloned) */\n  request: Request;\n  /** Logger */\n  logger: LoggerAdapter;\n}\n\nexport const StoryBookerPermissionsAllEnabled = {\n  \"build:create\": true,\n  \"build:delete\": true,\n  \"project:update\": true,\n  \"build:read\": true,\n  \"tag:delete\": true,\n  \"build:update\": true,\n  \"tag:create\": true,\n  \"project:read\": true,\n  \"project:create\": true,\n  \"tag:read\": true,\n  \"project:delete\": true,\n  \"tag:update\": true,\n} satisfies Record<StoryBookerPermissionKey, true>;\n\nexport const StoryBookerPermissionsList = Object.keys(\n  StoryBookerPermissionsAllEnabled,\n) as StoryBookerPermissionKey[];\n"],"mappings":";AAqHA,MAAa,mCAAmC;CAC9C,gBAAgB;CAChB,gBAAgB;CAChB,kBAAkB;CAClB,cAAc;CACd,cAAc;CACd,gBAAgB;CAChB,cAAc;CACd,gBAAgB;CAChB,kBAAkB;CAClB,YAAY;CACZ,kBAAkB;CAClB,cAAc;CACf;AAED,MAAa,6BAA6B,OAAO,KAC/C,iCACD"}

package/dist/~internal/adapter/database.d.mts

@@ -0,0 +1,240 @@
+import { StoryBookerAdapterMetadata } from "../../utils/adapter-utils.mjs";
+import { LoggerAdapter } from "./logger.mjs";
+import { ContentfulStatusCode } from "hono/utils/http-status";
+
+//#region src/adapters/_internal/database.d.ts
+
+/**
+ * Service adapter to interact with database.
+ *
+ * @description
+ * The adapter should provide callbacks to CRUD operations
+ * to an existing database.
+ *
+ * - `collection`: A collection/container/table to hold items.
+ * - `document`: A single entry in collection which contains key-value pairs (no nested data).
+ *    Each document has a key 'id` which is unique in the collection.
+ *
+ * @throws {DatabaseNotInitializedError} if the DB service is not connected.
+ * @throws {CollectionAlreadyExistsError} if the collection already exists.
+ * @throws {CollectionDoesNotExistError} if the collection does not exist.
+ * @throws {DocumentAlreadyExistsError} if the document already exists in the collection.
+ * @throws {DocumentDoesNotExistError} if the document does not exist in the collection.
+ * @throws {CustomError} if some other error occurs.
+ */
+interface DatabaseAdapter<DbDocument extends StoryBookerDatabaseDocument = StoryBookerDatabaseDocument> {
+  /**
+   * Metadata about the adapter.
+   */
+  metadata: StoryBookerAdapterMetadata;
+  /**
+   * An optional method that is called on app boot-up
+   * to run async setup functions.
+   * @param options Common options like abortSignal.
+   * @throws if an error occur during initialisation.
+   */
+  init?: (options: DatabaseAdapterOptions) => Promise<void>;
+  /**
+   * List all collections available in the DB.
+   * @param options Common options like abortSignal.
+   * @returns A list of names/IDs of the collections.
+   * @throws {DatabaseNotInitializedError} if the DB service is not connected.
+   */
+  listCollections: (options: DatabaseAdapterOptions) => Promise<string[]>;
+  /**
+   * Create a collection used for different projects.
+   * @param collectionId ID of the collection
+   * @param options Common options like abortSignal.
+   * @throws {DatabaseNotInitializedError} if the DB service is not connected.
+   * @throws {CollectionAlreadyExistsError} if collection with ID already exists.
+   */
+  createCollection: (collectionId: string, options: DatabaseAdapterOptions) => Promise<void>;
+  /**
+   * Delete an existing collection.
+   * @param collectionId ID of the collection
+   * @param options Common options like abortSignal.
+   * @throws {DatabaseNotInitializedError} if the DB service is not connected.
+   * @throws {CollectionDoesNotExistError} if collection with ID does not exist.
+   */
+  deleteCollection: (collectionId: string, options: DatabaseAdapterOptions) => Promise<void>;
+  /**
+   * Check if collection exists.
+   * @param collectionId ID of the collection
+   * @param options Common options like abortSignal.
+   * @returns if collection is available of not
+   * @throws never.
+   */
+  hasCollection: (collectionId: string, options: DatabaseAdapterOptions) => Promise<boolean>;
+  /**
+   * List all documents available in the requested collection.
+   * @param collectionId ID of the collection
+   * @param listOptions Options to format/sort the result
+   * @param options Common options like abortSignal.
+   * @returns List of documents
+   * @throws if the collection does not exist.
+   */
+  listDocuments: (collectionId: string, listOptions: DatabaseDocumentListOptions<DbDocument>, options: DatabaseAdapterOptions) => Promise<DbDocument[]>;
+  /**
+   * Create a new document in the collection.
+   * @param collectionId ID of the collection
+   * @param documentData Data to be stored
+   * @param options Common options like abortSignal.
+   * @throws if the collection does not exist.
+   */
+  createDocument: (collectionId: string, documentData: DbDocument, options: DatabaseAdapterOptions) => Promise<void>;
+  /**
+   * Get matching document data available in the requested collection.
+   * @param collectionId ID of the collection
+   * @param documentId ID of the document
+   * @param options Common options like abortSignal.
+   * @returns Data of the document
+   * @throws if the collection or document does not exist.
+   */
+  getDocument: (collectionId: string, documentId: string, options: DatabaseAdapterOptions) => Promise<DbDocument>;
+  /**
+   * Check matching document data available in the requested collection.
+   * @param collectionId ID of the collection
+   * @param documentId ID of the document
+   * @param options Common options like abortSignal.
+   * @returns if document is available of not
+   * @throws if the collection does not exists.
+   */
+  hasDocument: (collectionId: string, documentId: string, options: DatabaseAdapterOptions) => Promise<boolean>;
+  /**
+   * Update matching document data available in the requested collection.
+   * @param collectionId ID of the collection
+   * @param documentId ID of the document
+   * @param documentData Partial data to be updated.
+   * @param options Common options like abortSignal.
+   * @throws if the collection or document does not exist.
+   */
+  updateDocument: (collectionId: string, documentId: string, documentData: Partial<Omit<DbDocument, "id">>, options: DatabaseAdapterOptions) => Promise<void>;
+  /**
+   * Delete matching document available in the requested collection.
+   * @param collectionId ID of the collection
+   * @param documentId ID of the document
+   * @param options Common options like abortSignal.
+   * @throws if the collection or document does not exist.
+   */
+  deleteDocument: (collectionId: string, documentId: string, options: DatabaseAdapterOptions) => Promise<void>;
+}
+/**
+ * Base Document shape used in StoryBooker Database.
+ * Should always contain a filed 'id' with string value.
+ */
+interface StoryBookerDatabaseDocument {
+  id: string;
+  updatedAt: string;
+  createdAt: string;
+  [key: string]: unknown;
+}
+/** Common Database adapter options.  */
+interface DatabaseAdapterOptions {
+  /** A signal that can be used to cancel the request handling. */
+  abortSignal?: AbortSignal;
+  /** Logger */
+  logger: LoggerAdapter;
+}
+interface DatabaseDocumentListOptions<Item extends {
+  id: string;
+}> {
+  limit?: number;
+  filter?: string | ((item: Item) => boolean);
+  select?: string[];
+  sort?: "latest" | ((item1: Item, item2: Item) => number);
+}
+/**
+ * Pre-defined Database adapter errors
+ * that can be used across different adapters.
+ *
+ * Throws {HTTPException} with relevant status codes.
+ */
+declare const DatabaseAdapterErrors: {
+  DatabaseNotInitializedError: {
+    new (cause?: unknown): {
+      name: string;
+      message: string;
+      stack?: string | undefined;
+      cause?: unknown;
+      readonly res?: Response | undefined;
+      readonly status: ContentfulStatusCode;
+      getResponse(): Response;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function | undefined): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+  };
+  CollectionAlreadyExistsError: {
+    new (collectionId: string, cause?: unknown): {
+      name: string;
+      message: string;
+      stack?: string | undefined;
+      cause?: unknown;
+      readonly res?: Response | undefined;
+      readonly status: ContentfulStatusCode;
+      getResponse(): Response;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function | undefined): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+  };
+  CollectionDoesNotExistError: {
+    new (collectionId: string, cause?: unknown): {
+      name: string;
+      message: string;
+      stack?: string | undefined;
+      cause?: unknown;
+      readonly res?: Response | undefined;
+      readonly status: ContentfulStatusCode;
+      getResponse(): Response;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function | undefined): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+  };
+  DocumentAlreadyExistsError: {
+    new (collectionId: string, documentId: string, cause?: unknown): {
+      name: string;
+      message: string;
+      stack?: string | undefined;
+      cause?: unknown;
+      readonly res?: Response | undefined;
+      readonly status: ContentfulStatusCode;
+      getResponse(): Response;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function | undefined): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+  };
+  DocumentDoesNotExistError: {
+    new (collectionId: string, documentId: string, cause?: unknown): {
+      name: string;
+      message: string;
+      stack?: string | undefined;
+      cause?: unknown;
+      readonly res?: Response | undefined;
+      readonly status: ContentfulStatusCode;
+      getResponse(): Response;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function | undefined): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+  };
+  CustomError: {
+    new (status: number | undefined, message: string, cause?: unknown): {
+      name: string;
+      message: string;
+      stack?: string | undefined;
+      cause?: unknown;
+      readonly res?: Response | undefined;
+      readonly status: ContentfulStatusCode;
+      getResponse(): Response;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function | undefined): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+  };
+};
+//#endregion
+export { DatabaseAdapter, DatabaseAdapterErrors, DatabaseAdapterOptions, DatabaseDocumentListOptions, StoryBookerDatabaseDocument };
+//# sourceMappingURL=database.d.mts.map

package/dist/~internal/adapter/database.mjs

@@ -0,0 +1,63 @@
+import { HTTPException } from "hono/http-exception";
+
+//#region src/adapters/_internal/database.ts
+/**
+* Pre-defined Database adapter errors
+* that can be used across different adapters.
+*
+* Throws {HTTPException} with relevant status codes.
+*/
+const DatabaseAdapterErrors = {
+	DatabaseNotInitializedError: class extends HTTPException {
+		constructor(cause) {
+			super(500, {
+				cause,
+				message: "Database adapter is not initialized."
+			});
+		}
+	},
+	CollectionAlreadyExistsError: class extends HTTPException {
+		constructor(collectionId, cause) {
+			super(409, {
+				cause,
+				message: `Database collection '${collectionId}' already exists.`
+			});
+		}
+	},
+	CollectionDoesNotExistError: class extends HTTPException {
+		constructor(collectionId, cause) {
+			super(404, {
+				cause,
+				message: `Database collection '${collectionId}' does not exist.`
+			});
+		}
+	},
+	DocumentAlreadyExistsError: class extends HTTPException {
+		constructor(collectionId, documentId, cause) {
+			super(409, {
+				cause,
+				message: `Database document '${documentId}' already exists in collection '${collectionId}'.`
+			});
+		}
+	},
+	DocumentDoesNotExistError: class extends HTTPException {
+		constructor(collectionId, documentId, cause) {
+			super(404, {
+				cause,
+				message: `Database document '${documentId}' does not exist in collection '${collectionId}'.`
+			});
+		}
+	},
+	CustomError: class extends HTTPException {
+		constructor(status, message, cause) {
+			super(status, {
+				cause,
+				message
+			});
+		}
+	}
+};
+
+//#endregion
+export { DatabaseAdapterErrors };
+//# sourceMappingURL=database.mjs.map