storybooker 0.19.4 → 0.22.0-canary.0

package/package.json

@@ -1,50 +1,171 @@
 {
   "name": "storybooker",
-  "version": "0.19.4",
+  "version": "0.22.0-canary.0",
   "type": "module",
-  "bin": "./dist/index.js",
-  "description": "Storybooker CLI for uploading builds and files.",
+  "description": "Manage Storybook instances on your own infrastructure with ease.",
   "author": {
     "name": "Siddhant Gupta",
     "url": "https://guptasiddhant.com"
   },
-  "files": [
-    "src",
-    "dist"
-  ],
   "homepage": "https://storybooker.js.org",
   "repository": {
     "type": "git",
-    "url": "https://github.com/guptasiddhant/storybooker",
-    "directory": "packages/cli"
+    "url": "https://github.com/GuptaSiddhant/storybooker",
+    "directory": "packages/core"
   },
+  "files": [
+    "adapters",
+    "src",
+    "dist",
+    "openapi.json"
+  ],
   "license": "MIT",
   "sideEffects": false,
   "scripts": {
     "build": "tsdown",
-    "check": "tsgo --noEmit",
-    "cli": "node ./dist/index.js --cwd ../../apps/test-ui",
-    "dev": "tsdown -w ./src",
-    "fmt": "prettier src --write --config ../../.prettierrc",
-    "lint": "oxlint --type-aware ./src",
+    "dev": "tsdown -w",
+    "fmt": "oxfmt -c ../../.oxfmtrc.json ./src",
+    "lint": "oxlint --type-aware --type-check --import-plugin ./src",
     "lint:fix": "yarn lint --fix",
-    "openapi": "openapi-typescript ../core/dist/openapi.json -o ./src/service-schema.d.ts",
-    "start": "node --watch ./dist/index.js --cwd ../../apps/test-ui"
+    "openapi": "node ./scripts/gen-openapi-json.ts",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest"
   },
   "dependencies": {
-    "openapi-fetch": "^0.14.0",
-    "yargs": "^18.0.0",
-    "zod": "4.1.0"
+    "@hono/swagger-ui": "^0.5.2",
+    "@hono/zod-openapi": "^1.1.5",
+    "@remix-run/headers": "^0.16.0",
+    "decompress": "^4.0.0",
+    "hono": "^4.11.0",
+    "js-yaml": "^4.1.1",
+    "zod": "^4.2.0"
   },
   "devDependencies": {
+    "@aws-sdk/client-dynamodb": "^3.0.0",
+    "@aws-sdk/client-s3": "^3.0.0",
+    "@azure/cosmos": "^4.5.1",
+    "@azure/data-tables": "^13.0.0",
+    "@azure/functions": "^4.0.0",
+    "@azure/storage-blob": "^12.0.0",
+    "@google-cloud/bigtable": "^6.0.0",
+    "@google-cloud/firestore": "^7.0.0",
+    "@google-cloud/storage": "^7.0.0",
+    "@types/decompress": "^4.0.0",
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
-    "@types/yargs": "^17.0.33",
-    "@typescript/native-preview": "^7.0.0-dev.20251024.1",
-    "openapi-typescript": "^7.9.1",
-    "oxlint": "^1.31.0",
-    "oxlint-tsgolint": "^0.8.0",
-    "prettier": "^3.6.2",
-    "tsdown": "^0.15.9",
-    "typescript": "^5.9.2"
+    "@typescript/native-preview": "7.0.0-dev.20251217.1",
+    "@vitest/coverage-v8": "^4.0.0",
+    "oxfmt": "^0.18.0",
+    "oxlint": "^1.33.0",
+    "oxlint-tsgolint": "^0.9.1",
+    "redis": "^5.10.0",
+    "tsdown": "^0.18.1",
+    "vitest": "^4.0.0"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-dynamodb": "^3.0.0",
+    "@aws-sdk/client-s3": "^3.0.0",
+    "@azure/cosmos": "^4.0.0",
+    "@azure/data-tables": "^13.0.0",
+    "@azure/functions": "^4.0.0",
+    "@azure/storage-blob": "^12.0.0",
+    "@google-cloud/bigtable": "^6.0.0",
+    "@google-cloud/firestore": "^7.0.0",
+    "@google-cloud/storage": "^7.0.0",
+    "redis": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-dynamodb": {
+      "optional": true
+    },
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "@azure/cosmos": {
+      "optional": true
+    },
+    "@azure/data-tables": {
+      "optional": true
+    },
+    "@azure/functions": {
+      "optional": true
+    },
+    "@azure/storage-blob": {
+      "optional": true
+    },
+    "@google-cloud/bigtable": {
+      "optional": true
+    },
+    "@google-cloud/firestore": {
+      "optional": true
+    },
+    "@google-cloud/storage": {
+      "optional": true
+    },
+    "redis": {
+      "optional": true
+    }
+  },
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./~internal/adapter": "./dist/~internal/adapter.mjs",
+    "./~internal/adapter/auth": "./dist/~internal/adapter/auth.mjs",
+    "./~internal/adapter/database": "./dist/~internal/adapter/database.mjs",
+    "./~internal/adapter/logger": "./dist/~internal/adapter/logger.mjs",
+    "./~internal/adapter/storage": "./dist/~internal/adapter/storage.mjs",
+    "./~internal/adapter/ui": "./dist/~internal/adapter/ui.mjs",
+    "./~internal/constants": "./dist/~internal/constants.mjs",
+    "./~internal/mimes": "./dist/~internal/mimes.mjs",
+    "./~internal/router": "./dist/~internal/router.mjs",
+    "./~internal/types": "./dist/~internal/types.mjs",
+    "./~internal/utils": "./dist/~internal/utils.mjs",
+    "./aws-dynamodb": "./dist/aws-dynamodb.mjs",
+    "./aws-s3": "./dist/aws-s3.mjs",
+    "./azure-blob-storage": "./dist/azure-blob-storage.mjs",
+    "./azure-cosmos-db": "./dist/azure-cosmos-db.mjs",
+    "./azure-data-tables": "./dist/azure-data-tables.mjs",
+    "./azure-easy-auth": "./dist/azure-easy-auth.mjs",
+    "./azure-functions": "./dist/azure-functions.mjs",
+    "./fs": "./dist/fs.mjs",
+    "./gcp-big-table": "./dist/gcp-big-table.mjs",
+    "./gcp-firestore": "./dist/gcp-firestore.mjs",
+    "./gcp-storage": "./dist/gcp-storage.mjs",
+    "./mysql": "./dist/mysql.mjs",
+    "./redis": "./dist/redis.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.mjs",
+      "./~internal/adapter": "./dist/~internal/adapter.mjs",
+      "./~internal/adapter/auth": "./dist/~internal/adapter/auth.mjs",
+      "./~internal/adapter/database": "./dist/~internal/adapter/database.mjs",
+      "./~internal/adapter/logger": "./dist/~internal/adapter/logger.mjs",
+      "./~internal/adapter/storage": "./dist/~internal/adapter/storage.mjs",
+      "./~internal/adapter/ui": "./dist/~internal/adapter/ui.mjs",
+      "./~internal/constants": "./dist/~internal/constants.mjs",
+      "./~internal/mimes": "./dist/~internal/mimes.mjs",
+      "./~internal/router": "./dist/~internal/router.mjs",
+      "./~internal/types": "./dist/~internal/types.mjs",
+      "./~internal/utils": "./dist/~internal/utils.mjs",
+      "./aws-dynamodb": "./dist/aws-dynamodb.mjs",
+      "./aws-s3": "./dist/aws-s3.mjs",
+      "./azure-blob-storage": "./dist/azure-blob-storage.mjs",
+      "./azure-cosmos-db": "./dist/azure-cosmos-db.mjs",
+      "./azure-data-tables": "./dist/azure-data-tables.mjs",
+      "./azure-easy-auth": "./dist/azure-easy-auth.mjs",
+      "./azure-functions": "./dist/azure-functions.mjs",
+      "./fs": "./dist/fs.mjs",
+      "./gcp-big-table": "./dist/gcp-big-table.mjs",
+      "./gcp-firestore": "./dist/gcp-firestore.mjs",
+      "./gcp-storage": "./dist/gcp-storage.mjs",
+      "./mysql": "./dist/mysql.mjs",
+      "./redis": "./dist/redis.mjs",
+      "./package.json": "./package.json"
+    }
   }
 }

package/src/adapters/_internal/auth.ts

@@ -0,0 +1,135 @@
+import type { StoryBookerAdapterMetadata } from "../../utils/adapter-utils.ts";
+import type { LoggerAdapter } from "./logger.ts";
+
+/**
+ * Service adapter to manage authentication.
+ *
+ * The service is responsible to authorise users from
+ * accessing the app.
+ */
+export 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
+ */
+export type AuthAdapterAuthorise<AuthUser extends StoryBookerUser = StoryBookerUser> = (
+  params: {
+    permission: StoryBookerPermissionWithKey;
+    user: AuthUser;
+  },
+  options: AuthAdapterOptions,
+) => Promise<boolean | Response> | boolean | Response;
+
+/**  Type of permission to check */
+export interface StoryBookerPermission {
+  action: StoryBookerPermissionAction;
+  projectId?: string;
+  resource: StoryBookerPermissionResource;
+}
+/** Permission object with key */
+export type StoryBookerPermissionWithKey = StoryBookerPermission & {
+  key: StoryBookerPermissionKey;
+};
+/** Permission in a string format */
+export type StoryBookerPermissionKey =
+  `${StoryBookerPermissionResource}:${StoryBookerPermissionAction}`;
+/** Type of possible resources to check permissions for */
+export type StoryBookerPermissionResource = "project" | "build" | "tag";
+/** Type of possible actions to check permissions for */
+export type StoryBookerPermissionAction = "create" | "read" | "update" | "delete";
+
+/**
+ * Base representation of a generic User
+ */
+export 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.  */
+export interface AuthAdapterOptions {
+  /** A signal that can be used to cancel the request handling. */
+  abortSignal?: AbortSignal;
+  /** Incoming request (cloned) */
+  request: Request;
+  /** Logger */
+  logger: LoggerAdapter;
+}
+
+export 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,
+} satisfies Record<StoryBookerPermissionKey, true>;
+
+export const StoryBookerPermissionsList = Object.keys(
+  StoryBookerPermissionsAllEnabled,
+) as StoryBookerPermissionKey[];

package/src/adapters/_internal/database.ts

@@ -0,0 +1,241 @@
+// oxlint-disable max-classes-per-file
+
+import { HTTPException } from "hono/http-exception";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+import type { StoryBookerAdapterMetadata } from "../../utils/adapter-utils.ts";
+import type { LoggerAdapter } from "./logger.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.
+ */
+export 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>;
+
+  // Collections (group of items. aka Tables)
+
+  /**
+   * 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>;
+
+  // Documents (items, entries, rows, etc)
+
+  /**
+   * 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.
+ */
+export interface StoryBookerDatabaseDocument {
+  id: string;
+  updatedAt: string;
+  createdAt: string;
+  [key: string]: unknown;
+}
+
+/** Common Database adapter options.  */
+export interface DatabaseAdapterOptions {
+  /** A signal that can be used to cancel the request handling. */
+  abortSignal?: AbortSignal;
+  /** Logger */
+  logger: LoggerAdapter;
+}
+
+export 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.
+ */
+export const DatabaseAdapterErrors = {
+  DatabaseNotInitializedError: class extends HTTPException {
+    constructor(cause?: unknown) {
+      super(500, { cause, message: "Database adapter is not initialized." });
+    }
+  },
+  CollectionAlreadyExistsError: class extends HTTPException {
+    constructor(collectionId: string, cause?: unknown) {
+      super(409, {
+        cause,
+        message: `Database collection '${collectionId}' already exists.`,
+      });
+    }
+  },
+  CollectionDoesNotExistError: class extends HTTPException {
+    constructor(collectionId: string, cause?: unknown) {
+      super(404, {
+        cause,
+        message: `Database collection '${collectionId}' does not exist.`,
+      });
+    }
+  },
+  DocumentAlreadyExistsError: class extends HTTPException {
+    constructor(collectionId: string, documentId: string, cause?: unknown) {
+      super(409, {
+        cause,
+        message: `Database document '${documentId}' already exists in collection '${collectionId}'.`,
+      });
+    }
+  },
+  DocumentDoesNotExistError: class extends HTTPException {
+    constructor(collectionId: string, documentId: string, cause?: unknown) {
+      super(404, {
+        cause,
+        message: `Database document '${documentId}' does not exist in collection '${collectionId}'.`,
+      });
+    }
+  },
+  CustomError: class extends HTTPException {
+    constructor(status: number | undefined, message: string, cause?: unknown) {
+      super(status as ContentfulStatusCode, { cause, message });
+    }
+  },
+  // oxlint-disable-next-line no-explicit-any
+} satisfies Record<string, new (...args: any[]) => HTTPException>;

package/src/adapters/_internal/index.ts

@@ -0,0 +1,8 @@
+// oxlint-disable no-barrel-file
+export * from "./auth.ts";
+export * from "./database.ts";
+export * from "./logger.ts";
+export * from "./queue.ts";
+export * from "./storage.ts";
+export * from "./ui.ts";
+export type { StoryBookerAdapterMetadata } from "../../utils/adapter-utils.ts";

package/src/adapters/_internal/logger.ts

@@ -0,0 +1,41 @@
+import type { StoryBookerAdapterMetadata } from "../../utils/adapter-utils.ts";
+
+// oxlint-disable no-console
+/**
+ * Service adapter to log to desired destination.
+ *
+ * The service should contain method to `log` and report `error`.
+ * It can optionally have `debug` callback for debug messages.
+ *
+ * @default NodeJS.console
+ */
+export interface LoggerAdapter {
+  /**
+   * Metadata about the adapter.
+   */
+  metadata: StoryBookerAdapterMetadata;
+  /**
+   * Optional debug logs
+   */
+  debug?: (...args: unknown[]) => void;
+  /**
+   * Error logs
+   */
+  error: (...args: unknown[]) => void;
+  /**
+   * Normal logs
+   */
+  log: (...args: unknown[]) => void;
+}
+
+export function createConsoleLoggerAdapter(): LoggerAdapter {
+  return {
+    metadata: {
+      name: "console",
+    },
+
+    debug: console.debug.bind(console),
+    error: console.error.bind(console),
+    log: console.log.bind(console),
+  };
+}