@btst/stack 2.2.0 → 2.4.0

package/dist/shared/stack.CgWzG5jH.d.ts

@@ -0,0 +1,500 @@
+import * as _btst_stack_plugins_api from '@btst/stack/plugins/api';
+import * as better_call from 'better-call';
+import { Adapter } from '@btst/db';
+import { B as BoardWithColumns, P as Priority, T as Task, d as Board, e as Column, C as ColumnWithTasks } from './stack.DJaKVY7v.js';
+import { z } from 'zod';
+import { QueryClient } from '@tanstack/react-query';
+
+declare const createBoardSchema: z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    slug: z.ZodOptional<z.ZodString>;
+    ownerId: z.ZodOptional<z.ZodString>;
+    organizationId: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    updatedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    name: z.ZodString;
+}, z.core.$strip>;
+declare const updateBoardSchema: z.ZodObject<{
+    createdAt: z.ZodOptional<z.ZodOptional<z.ZodCoercedDate<unknown>>>;
+    updatedAt: z.ZodOptional<z.ZodOptional<z.ZodCoercedDate<unknown>>>;
+    name: z.ZodOptional<z.ZodString>;
+    slug: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    ownerId: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    organizationId: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    id: z.ZodNonOptional<z.ZodOptional<z.ZodString>>;
+}, z.core.$strip>;
+declare const createColumnSchema: z.ZodObject<{
+    title: z.ZodString;
+    createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    updatedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    order: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    boardId: z.ZodString;
+}, z.core.$strip>;
+declare const updateColumnSchema: z.ZodObject<{
+    createdAt: z.ZodOptional<z.ZodOptional<z.ZodCoercedDate<unknown>>>;
+    updatedAt: z.ZodOptional<z.ZodOptional<z.ZodCoercedDate<unknown>>>;
+    title: z.ZodOptional<z.ZodString>;
+    order: z.ZodOptional<z.ZodDefault<z.ZodOptional<z.ZodNumber>>>;
+    boardId: z.ZodOptional<z.ZodString>;
+    id: z.ZodNonOptional<z.ZodOptional<z.ZodString>>;
+}, z.core.$strip>;
+declare const createTaskSchema: z.ZodObject<{
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    updatedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    order: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    completedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    priority: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        LOW: "LOW";
+        MEDIUM: "MEDIUM";
+        HIGH: "HIGH";
+        URGENT: "URGENT";
+    }>>>;
+    columnId: z.ZodString;
+    assigneeId: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    isArchived: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strip>;
+declare const updateTaskSchema: z.ZodObject<{
+    completedAt: z.ZodOptional<z.ZodOptional<z.ZodCoercedDate<unknown>>>;
+    createdAt: z.ZodOptional<z.ZodOptional<z.ZodCoercedDate<unknown>>>;
+    updatedAt: z.ZodOptional<z.ZodOptional<z.ZodCoercedDate<unknown>>>;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    priority: z.ZodOptional<z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        LOW: "LOW";
+        MEDIUM: "MEDIUM";
+        HIGH: "HIGH";
+        URGENT: "URGENT";
+    }>>>>;
+    order: z.ZodOptional<z.ZodDefault<z.ZodOptional<z.ZodNumber>>>;
+    columnId: z.ZodOptional<z.ZodString>;
+    assigneeId: z.ZodOptional<z.ZodNullable<z.ZodOptional<z.ZodString>>>;
+    isArchived: z.ZodOptional<z.ZodDefault<z.ZodOptional<z.ZodBoolean>>>;
+    id: z.ZodNonOptional<z.ZodOptional<z.ZodString>>;
+}, z.core.$strip>;
+declare const BoardListQuerySchema: z.ZodObject<{
+    slug: z.ZodOptional<z.ZodString>;
+    ownerId: z.ZodOptional<z.ZodString>;
+    organizationId: z.ZodOptional<z.ZodString>;
+    offset: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+
+/**
+ * Paginated result returned by {@link getAllBoards}.
+ */
+interface BoardListResult {
+    items: BoardWithColumns[];
+    total: number;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Retrieve all boards matching optional filter criteria, with columns and tasks.
+ * Pure DB function - no hooks, no HTTP context. Safe for SSG and server-side use.
+ *
+ * @param adapter - The database adapter
+ * @param params - Optional filter/pagination parameters (same shape as the list API query)
+ */
+declare function getAllBoards(adapter: Adapter, params?: z.infer<typeof BoardListQuerySchema>): Promise<BoardListResult>;
+/**
+ * Retrieve a single board by its ID, with all columns and tasks.
+ * Returns null if the board is not found.
+ * Pure DB function - no hooks, no HTTP context. Safe for SSG and server-side use.
+ *
+ * @param adapter - The database adapter
+ * @param id - The board ID
+ */
+declare function getBoardById(adapter: Adapter, id: string): Promise<BoardWithColumns | null>;
+
+/**
+ * Input for creating a new Kanban task.
+ */
+interface CreateKanbanTaskInput {
+    title: string;
+    columnId: string;
+    description?: string;
+    priority?: Priority;
+    assigneeId?: string;
+}
+/**
+ * Create a new task in a Kanban column.
+ * Computes the next order value from existing tasks in the column.
+ *
+ * @remarks **Security:** No authorization hooks (onBeforeCreateTask) are called.
+ * The caller is responsible for any access-control checks before invoking this
+ * function.
+ *
+ * @param adapter - The database adapter
+ * @param input - Task creation input
+ */
+declare function createKanbanTask(adapter: Adapter, input: CreateKanbanTaskInput): Promise<Task>;
+/**
+ * Find a board by slug, or create it with the given name and custom column titles.
+ *
+ * Concurrency-safe at two levels:
+ * - **Same process**: concurrent calls with the same slug share a single in-flight
+ *   Promise (via `_pendingBoardCreations`), so only one DB write is attempted.
+ * - **Cross-instance**: the DB `unique` constraint on `slug` causes the losing
+ *   write to throw; the catch block re-fetches and returns the winner's board.
+ *
+ * @remarks **Security:** No authorization hooks are called. The caller is
+ * responsible for any access-control checks before invoking this function.
+ *
+ * @param adapter - The database adapter
+ * @param slug - Unique URL-safe slug for the board
+ * @param name - Display name for the board (used only on creation)
+ * @param columnTitles - Ordered list of column names to create (used only on creation)
+ */
+declare function findOrCreateKanbanBoard(adapter: Adapter, slug: string, name: string, columnTitles: string[]): Promise<Board>;
+/**
+ * Retrieve all columns for a given board, sorted by order.
+ * Co-located with mutations because it is primarily used alongside
+ * {@link createKanbanTask} to resolve column IDs before task creation.
+ *
+ * @remarks **Security:** No authorization hooks are called.
+ *
+ * @param adapter - The database adapter
+ * @param boardId - The board ID
+ */
+declare function getKanbanColumnsByBoardId(adapter: Adapter, boardId: string): Promise<Column[]>;
+
+/**
+ * Route keys for the Kanban plugin — matches the keys returned by
+ * `stackClient.router.getRoute(path).routeKey`.
+ */
+type KanbanRouteKey = "boards" | "newBoard" | "board";
+interface KanbanPrefetchForRoute {
+    (key: "boards" | "newBoard", qc: QueryClient): Promise<void>;
+    (key: "board", qc: QueryClient, params: {
+        boardId: string;
+    }): Promise<void>;
+}
+/**
+ * Context passed to kanban API hooks
+ */
+interface KanbanApiContext<TBody = unknown, TParams = unknown, TQuery = unknown> {
+    body?: TBody;
+    params?: TParams;
+    query?: TQuery;
+    request?: Request;
+    headers?: Headers;
+    [key: string]: unknown;
+}
+/**
+ * Configuration hooks for kanban backend plugin
+ * All hooks are optional and allow consumers to customize behavior
+ */
+interface KanbanBackendHooks {
+    /**
+     * Called before listing boards. Return false to deny access.
+     */
+    onBeforeListBoards?: (filter: z.infer<typeof BoardListQuerySchema>, context: KanbanApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called before creating a board. Return false to deny access.
+     */
+    onBeforeCreateBoard?: (data: z.infer<typeof createBoardSchema>, context: KanbanApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called before reading a single board. Return false to deny access.
+     */
+    onBeforeReadBoard?: (boardId: string, context: KanbanApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called before updating a board. Return false to deny access.
+     */
+    onBeforeUpdateBoard?: (boardId: string, data: z.infer<typeof updateBoardSchema>, context: KanbanApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called before deleting a board. Return false to deny access.
+     */
+    onBeforeDeleteBoard?: (boardId: string, context: KanbanApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called after boards are listed successfully.
+     * Receives the items array (same shape as `board[]`) for consistency
+     * with analogous hooks in other plugins (e.g. `onPostsRead`).
+     */
+    onBoardsRead?: (boards: BoardWithColumns[], filter: z.infer<typeof BoardListQuerySchema>, context: KanbanApiContext) => Promise<void> | void;
+    /**
+     * Called after a single board is read successfully
+     */
+    onBoardRead?: (board: Board, context: KanbanApiContext) => Promise<void> | void;
+    /**
+     * Called after a board is created successfully
+     */
+    onBoardCreated?: (board: Board, context: KanbanApiContext) => Promise<void> | void;
+    /**
+     * Called after a board is updated successfully
+     */
+    onBoardUpdated?: (board: Board, context: KanbanApiContext) => Promise<void> | void;
+    /**
+     * Called after a board is deleted successfully
+     */
+    onBoardDeleted?: (boardId: string, context: KanbanApiContext) => Promise<void> | void;
+    /**
+     * Called when listing boards fails
+     */
+    onListBoardsError?: (error: Error, context: KanbanApiContext) => Promise<void> | void;
+    /**
+     * Called when reading a single board fails
+     */
+    onReadBoardError?: (error: Error, context: KanbanApiContext) => Promise<void> | void;
+    /**
+     * Called when creating a board fails
+     */
+    onCreateBoardError?: (error: Error, context: KanbanApiContext) => Promise<void> | void;
+    /**
+     * Called when updating a board fails
+     */
+    onUpdateBoardError?: (error: Error, context: KanbanApiContext) => Promise<void> | void;
+    /**
+     * Called when deleting a board fails
+     */
+    onDeleteBoardError?: (error: Error, context: KanbanApiContext) => Promise<void> | void;
+    /**
+     * Called before creating a column. Return false to deny access.
+     */
+    onBeforeCreateColumn?: (data: z.infer<typeof createColumnSchema>, context: KanbanApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called before updating a column. Return false to deny access.
+     */
+    onBeforeUpdateColumn?: (columnId: string, data: z.infer<typeof updateColumnSchema>, context: KanbanApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called before deleting a column. Return false to deny access.
+     */
+    onBeforeDeleteColumn?: (columnId: string, context: KanbanApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called after a column is created successfully
+     */
+    onColumnCreated?: (column: Column, context: KanbanApiContext) => Promise<void> | void;
+    /**
+     * Called after a column is updated successfully
+     */
+    onColumnUpdated?: (column: Column, context: KanbanApiContext) => Promise<void> | void;
+    /**
+     * Called after a column is deleted successfully
+     */
+    onColumnDeleted?: (columnId: string, context: KanbanApiContext) => Promise<void> | void;
+    /**
+     * Called before creating a task. Return false to deny access.
+     */
+    onBeforeCreateTask?: (data: z.infer<typeof createTaskSchema>, context: KanbanApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called before updating a task. Return false to deny access.
+     */
+    onBeforeUpdateTask?: (taskId: string, data: z.infer<typeof updateTaskSchema>, context: KanbanApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called before deleting a task. Return false to deny access.
+     */
+    onBeforeDeleteTask?: (taskId: string, context: KanbanApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called after a task is created successfully
+     */
+    onTaskCreated?: (task: Task, context: KanbanApiContext) => Promise<void> | void;
+    /**
+     * Called after a task is updated successfully
+     */
+    onTaskUpdated?: (task: Task, context: KanbanApiContext) => Promise<void> | void;
+    /**
+     * Called after a task is deleted successfully
+     */
+    onTaskDeleted?: (taskId: string, context: KanbanApiContext) => Promise<void> | void;
+}
+/**
+ * Kanban backend plugin
+ * Provides API endpoints for managing kanban boards, columns, and tasks
+ *
+ * @param hooks - Optional configuration hooks for customizing plugin behavior
+ */
+declare const kanbanBackendPlugin: (hooks?: KanbanBackendHooks) => _btst_stack_plugins_api.BackendPlugin<{
+    readonly listBoards: better_call.StrictEndpoint<"/boards", {
+        method: "GET";
+        query: z.ZodObject<{
+            slug: z.ZodOptional<z.ZodString>;
+            ownerId: z.ZodOptional<z.ZodString>;
+            organizationId: z.ZodOptional<z.ZodString>;
+            offset: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+            limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+        }, z.core.$strip>;
+    }, BoardListResult>;
+    readonly getBoard: better_call.StrictEndpoint<"/boards/:id", {
+        method: "GET";
+    }, BoardWithColumns>;
+    readonly createBoard: better_call.StrictEndpoint<"/boards", {
+        method: "POST";
+        body: z.ZodObject<{
+            description: z.ZodOptional<z.ZodString>;
+            slug: z.ZodOptional<z.ZodString>;
+            ownerId: z.ZodOptional<z.ZodString>;
+            organizationId: z.ZodOptional<z.ZodString>;
+            createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+            updatedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+            name: z.ZodString;
+        }, z.core.$strip>;
+    }, {
+        columns: ColumnWithTasks[];
+        id: string;
+        name: string;
+        slug: string;
+        description?: string;
+        ownerId?: string;
+        organizationId?: string;
+        createdAt: Date;
+        updatedAt: Date;
+    }>;
+    readonly updateBoard: better_call.StrictEndpoint<"/boards/:id", {
+        method: "PUT";
+        body: z.ZodObject<{
+            description: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+            slug: z.ZodOptional<z.ZodString>;
+            ownerId: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+            organizationId: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+            createdAt: z.ZodOptional<z.ZodOptional<z.ZodCoercedDate<unknown>>>;
+            updatedAt: z.ZodOptional<z.ZodOptional<z.ZodCoercedDate<unknown>>>;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, Board>;
+    readonly deleteBoard: better_call.StrictEndpoint<"/boards/:id", {
+        method: "DELETE";
+    }, {
+        success: boolean;
+    }>;
+    readonly createColumn: better_call.StrictEndpoint<"/columns", {
+        method: "POST";
+        body: z.ZodObject<{
+            title: z.ZodString;
+            createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+            updatedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+            order: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+            boardId: z.ZodString;
+        }, z.core.$strip>;
+    }, Column>;
+    readonly updateColumn: better_call.StrictEndpoint<"/columns/:id", {
+        method: "PUT";
+        body: z.ZodObject<{
+            title: z.ZodOptional<z.ZodString>;
+            createdAt: z.ZodOptional<z.ZodOptional<z.ZodCoercedDate<unknown>>>;
+            updatedAt: z.ZodOptional<z.ZodOptional<z.ZodCoercedDate<unknown>>>;
+            order: z.ZodOptional<z.ZodDefault<z.ZodOptional<z.ZodNumber>>>;
+            boardId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, Column>;
+    readonly deleteColumn: better_call.StrictEndpoint<"/columns/:id", {
+        method: "DELETE";
+    }, {
+        success: boolean;
+    }>;
+    readonly reorderColumns: better_call.StrictEndpoint<"/columns/reorder", {
+        method: "POST";
+        body: z.ZodObject<{
+            boardId: z.ZodString;
+            columnIds: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>;
+    }, {
+        success: boolean;
+    }>;
+    readonly createTask: better_call.StrictEndpoint<"/tasks", {
+        method: "POST";
+        body: z.ZodObject<{
+            title: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+            updatedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+            order: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+            completedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+            priority: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+                LOW: "LOW";
+                MEDIUM: "MEDIUM";
+                HIGH: "HIGH";
+                URGENT: "URGENT";
+            }>>>;
+            columnId: z.ZodString;
+            assigneeId: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+            isArchived: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        }, z.core.$strip>;
+    }, Task>;
+    readonly updateTask: better_call.StrictEndpoint<"/tasks/:id", {
+        method: "PUT";
+        body: z.ZodObject<{
+            title: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+            createdAt: z.ZodOptional<z.ZodOptional<z.ZodCoercedDate<unknown>>>;
+            updatedAt: z.ZodOptional<z.ZodOptional<z.ZodCoercedDate<unknown>>>;
+            order: z.ZodOptional<z.ZodDefault<z.ZodOptional<z.ZodNumber>>>;
+            completedAt: z.ZodOptional<z.ZodOptional<z.ZodCoercedDate<unknown>>>;
+            priority: z.ZodOptional<z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+                LOW: "LOW";
+                MEDIUM: "MEDIUM";
+                HIGH: "HIGH";
+                URGENT: "URGENT";
+            }>>>>;
+            columnId: z.ZodOptional<z.ZodString>;
+            assigneeId: z.ZodOptional<z.ZodNullable<z.ZodOptional<z.ZodString>>>;
+            isArchived: z.ZodOptional<z.ZodDefault<z.ZodOptional<z.ZodBoolean>>>;
+        }, z.core.$strip>;
+    }, Task>;
+    readonly deleteTask: better_call.StrictEndpoint<"/tasks/:id", {
+        method: "DELETE";
+    }, {
+        success: boolean;
+    }>;
+    readonly moveTask: better_call.StrictEndpoint<"/tasks/move", {
+        method: "POST";
+        body: z.ZodObject<{
+            taskId: z.ZodString;
+            targetColumnId: z.ZodString;
+            targetOrder: z.ZodNumber;
+        }, z.core.$strip>;
+    }, Task>;
+    readonly reorderTasks: better_call.StrictEndpoint<"/tasks/reorder", {
+        method: "POST";
+        body: z.ZodObject<{
+            columnId: z.ZodString;
+            taskIds: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>;
+    }, {
+        success: boolean;
+    }>;
+}, {
+    getAllBoards: (params?: Parameters<typeof getAllBoards>[1]) => Promise<BoardListResult>;
+    getBoardById: (id: string) => Promise<BoardWithColumns | null>;
+    prefetchForRoute: KanbanPrefetchForRoute;
+    createTask: (input: Parameters<typeof createKanbanTask>[1]) => Promise<Task>;
+    findOrCreateBoard: (slug: string, name: string, columnTitles: string[]) => Promise<Board>;
+    getColumnsByBoardId: (boardId: string) => Promise<Column[]>;
+}>;
+type KanbanApiRouter = ReturnType<ReturnType<typeof kanbanBackendPlugin>["routes"]>;
+
+/**
+ * Internal query key constants for the Kanban plugin.
+ * Shared between query-keys.ts (HTTP path) and prefetchForRoute (DB path)
+ * to prevent key drift between SSR loaders and SSG prefetching.
+ */
+interface BoardsListDiscriminator {
+    slug: string | undefined;
+    ownerId: string | undefined;
+    organizationId: string | undefined;
+    limit: number;
+    offset: number;
+}
+/** Full query key builders — use these with queryClient.setQueryData() */
+declare const KANBAN_QUERY_KEYS: {
+    /**
+     * Key for boards.list(params) query.
+     * Full key: ["boards", "list", { slug, ownerId, organizationId, limit, offset }]
+     */
+    boardsList: (params?: {
+        slug?: string;
+        ownerId?: string;
+        organizationId?: string;
+        limit?: number;
+        offset?: number;
+    }) => readonly ["boards", "list", BoardsListDiscriminator];
+    /**
+     * Key for boards.detail(boardId) query.
+     * Full key: ["boards", "detail", boardId]
+     */
+    boardDetail: (boardId: string) => readonly ["boards", "detail", string];
+};
+
+export { getBoardById as d, createKanbanTask as e, findOrCreateKanbanBoard as f, getAllBoards as g, getKanbanColumnsByBoardId as h, KANBAN_QUERY_KEYS as i, kanbanBackendPlugin as k };
+export type { BoardListResult as B, CreateKanbanTaskInput as C, KanbanApiRouter as K, KanbanRouteKey as a, KanbanApiContext as b, KanbanBackendHooks as c, BoardsListDiscriminator as j };