@btst/stack 3.0.0-rc.1 → 3.0.0-rc.3

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

@@ -0,0 +1,351 @@
+import { DeepReadonly } from '@btst/stack/plugins/api';
+import { PermissionFactsFor } from '@btst/stack/authorization';
+import { StackIdentity } from '@btst/stack/context';
+import { formBuilderPermissions } from '../plugins/form-builder/permissions.js';
+import { z } from 'zod';
+
+/**
+ * Schema for listing forms with pagination and free-text search
+ */
+declare const listFormsQuerySchema: z.ZodObject<{
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        inactive: "inactive";
+        archived: "archived";
+    }>>;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
+    offset: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
+    search: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Schema for creating a form
+ */
+declare const createFormSchema: z.ZodObject<{
+    name: z.ZodString;
+    slug: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    schema: z.ZodString;
+    successMessage: z.ZodOptional<z.ZodString>;
+    redirectUrl: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    status: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        inactive: "inactive";
+        archived: "archived";
+    }>>>;
+}, z.core.$strip>;
+/**
+ * Schema for updating a form
+ */
+declare const updateFormSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    slug: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    schema: z.ZodOptional<z.ZodString>;
+    successMessage: z.ZodOptional<z.ZodString>;
+    redirectUrl: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        inactive: "inactive";
+        archived: "archived";
+    }>>;
+}, z.core.$strip>;
+/**
+ * Schema for listing form submissions with pagination
+ */
+declare const listSubmissionsQuerySchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
+    offset: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
+}, z.core.$strip>;
+/**
+ * Schema for submitting a form (public)
+ */
+declare const submitFormSchema: z.ZodObject<{
+    data: z.ZodObject<{}, z.core.$loose>;
+}, z.core.$strip>;
+type ListFormsQuery = z.infer<typeof listFormsQuerySchema>;
+type CreateFormInput = z.infer<typeof createFormSchema>;
+type UpdateFormInput = z.infer<typeof updateFormSchema>;
+type ListSubmissionsQuery = z.infer<typeof listSubmissionsQuerySchema>;
+type SubmitFormInput = z.infer<typeof submitFormSchema>;
+
+/**
+ * Form Builder Plugin Types
+ *
+ * Key distinction from CMS Plugin:
+ * - CMS uses developer-defined Zod schemas in code
+ * - Form Builder allows non-technical admins to build forms via drag-and-drop UI
+ * - Forms are serialized to/from JSON Schema for storage
+ */
+
+/**
+ * Form stored in the database
+ */
+type Form = {
+    id: string;
+    /** Display name for the form */
+    name: string;
+    /** URL-friendly slug - unique identifier for public access */
+    slug: string;
+    /** Optional description for admin UI */
+    description?: string;
+    /** JSON Schema stored as string (includes steps, fieldType, stepGroup, etc.) */
+    schema: string;
+    /** Optional custom success message after submission */
+    successMessage?: string;
+    /** Optional redirect URL after submission */
+    redirectUrl?: string;
+    /** Form status: active, inactive, archived */
+    status: "active" | "inactive" | "archived";
+    /** User who created the form */
+    createdBy?: string;
+    createdAt: Date;
+    updatedAt: Date;
+};
+/**
+ * Form submission stored in the database
+ */
+type FormSubmission = {
+    id: string;
+    /** Reference to the form */
+    formId: string;
+    /** Submitted data as JSON string */
+    data: string;
+    /** Submission timestamp */
+    submittedAt: Date;
+    /** Optional user ID if authenticated */
+    submittedBy?: string;
+    /** Client IP address for rate limiting and spam protection */
+    ipAddress?: string;
+    /** User agent for analytics */
+    userAgent?: string;
+};
+/**
+ * Form submission with its parent form joined
+ */
+type FormSubmissionWithForm = FormSubmission & {
+    form?: Form;
+};
+/**
+ * Serialized form for API responses (dates as strings)
+ */
+interface SerializedForm extends Omit<Form, "createdAt" | "updatedAt" | "status"> {
+    status: Form["status"];
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Serialized form submission for API responses (dates as strings)
+ */
+interface SerializedFormSubmission extends Omit<FormSubmission, "submittedAt"> {
+    submittedAt: string;
+}
+/** Non-sensitive submission metadata returned by collection reads. */
+type SerializedFormSubmissionSummary = {
+    id: string;
+    formId: string;
+    submittedAt: string;
+    submittedBy?: string;
+};
+/**
+ * Serialized form submission with parsed data
+ */
+interface SerializedFormSubmissionWithData<TData = Record<string, unknown>> extends SerializedFormSubmission {
+    /** Parsed data object (JSON.parse of data field). Null when the stored JSON is corrupted. */
+    parsedData: TData | null;
+    /** Joined form */
+    form?: SerializedForm;
+}
+/**
+ * Paginated list response for forms
+ */
+interface PaginatedForms {
+    items: SerializedForm[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+/** Minimal form context carried by the submission-read response. */
+interface SubmissionListFormContext {
+    id: string;
+    name: string;
+    createdBy?: string;
+}
+/**
+ * Paginated list response for form submissions
+ */
+interface PaginatedFormSubmissions {
+    /** Authoritative form facts returned by the submission-read operation. */
+    form: SubmissionListFormContext | null;
+    /** Metadata only. Fetch an individual submission to read its contents. */
+    items: SerializedFormSubmissionSummary[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+/**
+ * Context passed to all backend hooks
+ */
+interface FormBuilderHookContext<TInput = unknown, TFacts = unknown> {
+    /** Validated operation input. */
+    readonly input: DeepReadonly<TInput>;
+    /** Trusted facts derived by the backend before authorization. */
+    readonly facts: DeepReadonly<TFacts>;
+    /** Authorized request identity, or `null` for anonymous/trusted execution. */
+    readonly identity: DeepReadonly<StackIdentity> | null;
+    /** Request when invoked through HTTP or `forRequest()`. */
+    readonly request?: Request;
+    /** User ID if authenticated */
+    readonly userId?: string;
+    /** Request headers */
+    readonly headers?: Headers;
+    /** Client IP address (for rate limiting) */
+    readonly ipAddress?: string;
+    /** User agent string */
+    readonly userAgent?: string;
+}
+/**
+ * Context for submission-specific hooks
+ */
+interface SubmissionHookContext<TInput = unknown, TFacts = unknown> extends FormBuilderHookContext<TInput, TFacts> {
+    /** Form slug being submitted */
+    readonly formSlug: string;
+    /** Form ID */
+    readonly formId: string;
+}
+type FormReadFacts = PermissionFactsFor<typeof formBuilderPermissions.form.read>;
+type FormRenderFacts = PermissionFactsFor<typeof formBuilderPermissions.form.render>;
+type FormCreateFacts = PermissionFactsFor<typeof formBuilderPermissions.form.create>;
+type FormUpdateFacts = PermissionFactsFor<typeof formBuilderPermissions.form.update>;
+type FormDeleteFacts = PermissionFactsFor<typeof formBuilderPermissions.form.delete>;
+type SubmissionCreateFacts = PermissionFactsFor<typeof formBuilderPermissions.submission.create>;
+type SubmissionReadFacts = PermissionFactsFor<typeof formBuilderPermissions.submission.read>;
+type SubmissionDeleteFacts = PermissionFactsFor<typeof formBuilderPermissions.submission.delete>;
+/** Authorized form-list lifecycle context. */
+type FormListOperationContext = FormBuilderHookContext<ListFormsQuery, FormReadFacts>;
+/** Authorized form-detail lifecycle context. */
+type FormGetOperationContext = FormBuilderHookContext<{
+    id: string;
+}, FormReadFacts> | FormBuilderHookContext<{
+    slug: string;
+}, FormRenderFacts>;
+/** Authorized editor-data lifecycle context. */
+type FormGetForUpdateOperationContext = FormBuilderHookContext<{
+    id: string;
+}, FormUpdateFacts>;
+/** Authorized form-create lifecycle context. */
+type FormCreateOperationContext = FormBuilderHookContext<CreateFormInput, FormCreateFacts>;
+/** Authorized form-update lifecycle context. */
+type FormUpdateOperationContext = FormBuilderHookContext<{
+    id: string;
+    data: UpdateFormInput;
+}, FormUpdateFacts>;
+/** Authorized form-delete lifecycle context. */
+type FormDeleteOperationContext = FormBuilderHookContext<{
+    id: string;
+}, FormDeleteFacts>;
+/** Authorized public submission lifecycle context. */
+type SubmissionCreateOperationContext = SubmissionHookContext<{
+    slug: string;
+} & SubmitFormInput, SubmissionCreateFacts>;
+/** Authorized submission-list lifecycle context. */
+type SubmissionListOperationContext = FormBuilderHookContext<{
+    formId: string;
+    query: ListSubmissionsQuery;
+}, SubmissionReadFacts>;
+/** Authorized submission-detail lifecycle context. */
+type SubmissionGetOperationContext = FormBuilderHookContext<{
+    formId: string;
+    submissionId: string;
+}, SubmissionReadFacts>;
+/** Authorized submission-delete lifecycle context. */
+type SubmissionDeleteOperationContext = FormBuilderHookContext<{
+    formId: string;
+    submissionId: string;
+}, SubmissionDeleteFacts>;
+/** Typed context union used by the cross-operation error hook. */
+type FormBuilderOperationHookContext = FormListOperationContext | FormGetOperationContext | FormGetForUpdateOperationContext | FormCreateOperationContext | FormUpdateOperationContext | FormDeleteOperationContext | SubmissionCreateOperationContext | SubmissionListOperationContext | SubmissionGetOperationContext | SubmissionDeleteOperationContext;
+/**
+ * Input data for creating a form
+ */
+interface FormInput {
+    name: string;
+    slug: string;
+    description?: string;
+    schema: string;
+    successMessage?: string;
+    redirectUrl?: string;
+    status?: "active" | "inactive" | "archived";
+    createdBy?: string;
+}
+/**
+ * Input data for updating a form
+ */
+interface FormUpdate {
+    name?: string;
+    slug?: string;
+    description?: string;
+    schema?: string;
+    successMessage?: string;
+    redirectUrl?: string;
+    status?: "active" | "inactive" | "archived";
+}
+/**
+ * Backend hooks for Form Builder plugin
+ *
+ * Authorization runs before these hooks. Hooks receive trusted typed operation
+ * context and can enforce domain invariants or perform lifecycle behavior.
+ */
+interface FormBuilderBackendHooks {
+    /** Called before listing forms to enforce domain preconditions. */
+    onBeforeListForms?: (ctx: FormListOperationContext) => Promise<void> | void;
+    /** Called before creating a form. Throw an error to deny, or return modified data. */
+    onBeforeCreateForm?: (data: FormInput, ctx: FormCreateOperationContext) => Promise<FormInput | void> | FormInput | void;
+    /** Called after a form is created */
+    onAfterCreateForm?: (form: SerializedForm, ctx: FormCreateOperationContext) => Promise<void> | void;
+    /** Called before getting a form by ID or slug. */
+    onBeforeGetForm?: (idOrSlug: string, ctx: FormGetOperationContext) => Promise<void> | void;
+    /** Called before loading editor data through the form update permission. */
+    onBeforeGetFormForUpdate?: (id: string, ctx: FormGetForUpdateOperationContext) => Promise<void> | void;
+    /** Called before updating a form. Throw an error to deny, or return modified data. */
+    onBeforeUpdateForm?: (id: string, data: FormUpdate, ctx: FormUpdateOperationContext) => Promise<FormUpdate | void> | FormUpdate | void;
+    /** Called after a form is updated */
+    onAfterUpdateForm?: (form: SerializedForm, ctx: FormUpdateOperationContext) => Promise<void> | void;
+    /** Called before deleting a form. Throw an error to deny. */
+    onBeforeDeleteForm?: (id: string, ctx: FormDeleteOperationContext) => Promise<void> | void;
+    /** Called after a form is deleted */
+    onAfterDeleteForm?: (id: string, ctx: FormDeleteOperationContext) => Promise<void> | void;
+    /**
+     * Called before processing a form submission.
+     * Use for: spam protection, rate limiting, data validation/enrichment.
+     *
+     * Throw an error to reject submission (400), or return modified data to continue.
+     */
+    onBeforeSubmission?: (formSlug: string, data: Record<string, unknown>, ctx: SubmissionCreateOperationContext) => Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
+    /**
+     * Called after a submission is saved.
+     * Use for: sending emails, storing in CRM, triggering workflows.
+     */
+    onAfterSubmission?: (submission: SerializedFormSubmission, form: SerializedForm, ctx: SubmissionCreateOperationContext) => Promise<void> | void;
+    /** Called when a submission fails */
+    onErrorSubmission?: (error: Error, formSlug: string, data: Record<string, unknown>, ctx: SubmissionCreateOperationContext) => Promise<void> | void;
+    /** Called before listing submissions to enforce domain preconditions. */
+    onBeforeListSubmissions?: (formId: string, ctx: SubmissionListOperationContext) => Promise<void> | void;
+    /** Called before getting a submission. Throw an error to deny access. */
+    onBeforeGetSubmission?: (submissionId: string, ctx: SubmissionGetOperationContext) => Promise<void> | void;
+    /** Called before deleting a submission. Throw an error to deny. */
+    onBeforeDeleteSubmission?: (submissionId: string, ctx: SubmissionDeleteOperationContext) => Promise<void> | void;
+    /** Called after a submission is deleted */
+    onAfterDeleteSubmission?: (submissionId: string, ctx: SubmissionDeleteOperationContext) => Promise<void> | void;
+    /** Called on any error */
+    onError?: (error: Error, operation: "list" | "get" | "create" | "update" | "delete" | "submit" | "listSubmissions" | "getSubmission" | "deleteSubmission", ctx: FormBuilderOperationHookContext) => Promise<void> | void;
+}
+/**
+ * Configuration for the Form Builder backend plugin
+ */
+interface FormBuilderBackendConfig {
+    /** Optional hooks for customizing behavior */
+    hooks?: FormBuilderBackendHooks;
+}
+
+export { listFormsQuerySchema as w, createFormSchema as x };
+export type { Form as F, PaginatedForms as P, SerializedForm as S, SerializedFormSubmission as a, SubmissionListFormContext as b, SerializedFormSubmissionSummary as c, SerializedFormSubmissionWithData as d, PaginatedFormSubmissions as e, FormSubmission as f, FormSubmissionWithForm as g, FormBuilderBackendConfig as h, FormBuilderBackendHooks as i, FormBuilderHookContext as j, FormBuilderOperationHookContext as k, FormCreateOperationContext as l, FormDeleteOperationContext as m, FormGetOperationContext as n, FormGetForUpdateOperationContext as o, FormListOperationContext as p, FormUpdateOperationContext as q, SubmissionCreateOperationContext as r, SubmissionDeleteOperationContext as s, SubmissionGetOperationContext as t, SubmissionListOperationContext as u, SubmissionHookContext as v };