@btst/stack 5.1.0 → 5.2.0

package/src/plugins/crm/query-keys.ts

@@ -0,0 +1,321 @@
+import {
+	createResourceQueryKeys,
+	type ResourceClient,
+	type ResourcesDeclaration,
+} from "@btst/stack/plugins/client";
+import type { StackIdentity } from "@btst/stack/context";
+import type { Contact, Company, Deal, Activity, Pipeline } from "./types";
+
+/** Identity scope for protected CRM queries. */
+export type CrmIdentityPartition =
+	| StackIdentity
+	| `pending:${number}`
+	| `error:${number}`;
+/** Search and pagination for CRM collections. */
+export interface CrmListParams {
+	search?: string;
+	tag?: string;
+	companyId?: string;
+	contactId?: string;
+	dealId?: string;
+	pipelineId?: string;
+	status?: string;
+	limit?: number;
+	offset?: number;
+}
+/** Contact fields accepted by the CRM editor. */
+export interface ContactInput {
+	firstName: string;
+	lastName?: string;
+	email?: string | null;
+	phone?: string;
+	company?: string;
+	companyId?: string | null;
+	title?: string;
+	tags?: string[];
+	customFields?: Record<string, string>;
+	notes?: string;
+}
+/** Company details. */
+export interface CompanyInput {
+	name: string;
+	domain?: string;
+	phone?: string;
+	notes?: string;
+}
+/** Deal details and its Kanban stage. */
+export interface DealInput {
+	title: string;
+	value?: number | null;
+	currency?: string;
+	pipelineId: string;
+	stage: string;
+	contactId?: string | null;
+	companyId?: string | null;
+	closeDate?: string | null;
+	status?: "open" | "won" | "lost";
+}
+/** Editable deal metadata; use the move mutation to change its Kanban stage. */
+export type DealUpdateInput = Partial<Omit<DealInput, "pipelineId" | "stage">>;
+/** A logged interaction or follow-up. */
+export interface ActivityInput {
+	type: "note" | "call" | "email" | "meeting";
+	body: string;
+	contactId?: string;
+	dealId?: string;
+	dueAt?: string | null;
+}
+/** Editable activity details and follow-up completion. */
+export type ActivityUpdateInput = Partial<
+	Pick<ActivityInput, "body" | "dueAt">
+> & {
+	completedAt?: string | null;
+};
+/** A pipeline backed by a Kanban board. */
+export interface PipelineInput {
+	name: string;
+	slug?: string;
+	stages?: string[];
+}
+
+export const crmResources = {
+	crmContacts: {
+		queries: {
+			list: {
+				path: "/crm/contacts",
+				query: (
+					params: CrmListParams = {},
+					_identity?: CrmIdentityPartition,
+				) => ({ ...params }),
+				select: (data: unknown): { items: Contact[]; total: number } =>
+					data as { items: Contact[]; total: number },
+			},
+			detail: {
+				path: "/crm/contacts/:id",
+				params: (id: string, _identity?: CrmIdentityPartition) => ({ id }),
+				select: (data: unknown): Contact => data as Contact,
+			},
+		},
+		mutations: {
+			create: {
+				path: "@post/crm/contacts",
+				method: "POST",
+				input: (body: ContactInput) => ({ body }),
+				select: (data: unknown): Contact => data as Contact,
+				invalidates: ["crmContacts", "crmPipelines"],
+				refresh: false,
+			},
+			update: {
+				path: "@put/crm/contacts/:id",
+				method: "PUT",
+				input: ({ id, data }: { id: string; data: Partial<ContactInput> }) => ({
+					params: { id },
+					body: data,
+				}),
+				select: (data: unknown): Contact => data as Contact,
+				invalidates: ["crmContacts", "crmPipelines"],
+				refresh: false,
+			},
+			delete: {
+				path: "@delete/crm/contacts/:id",
+				method: "DELETE",
+				input: (id: string) => ({ params: { id } }),
+				invalidates: [
+					"crmContacts",
+					"crmDeals",
+					"crmActivities",
+					"crmPipelines",
+				],
+				refresh: false,
+			},
+		},
+	},
+	crmCompanies: {
+		queries: {
+			list: {
+				path: "/crm/companies",
+				query: (
+					params: CrmListParams = {},
+					_identity?: CrmIdentityPartition,
+				) => ({ ...params }),
+				select: (data: unknown): { items: Company[]; total: number } =>
+					data as { items: Company[]; total: number },
+			},
+			detail: {
+				path: "/crm/companies/:id",
+				params: (id: string, _identity?: CrmIdentityPartition) => ({ id }),
+				select: (data: unknown): Company => data as Company,
+			},
+		},
+		mutations: {
+			create: {
+				path: "@post/crm/companies",
+				method: "POST",
+				input: (body: CompanyInput) => ({ body }),
+				select: (data: unknown): Company => data as Company,
+				invalidates: ["crmCompanies", "crmPipelines"],
+				refresh: false,
+			},
+			update: {
+				path: "@put/crm/companies/:id",
+				method: "PUT",
+				input: ({ id, data }: { id: string; data: Partial<CompanyInput> }) => ({
+					params: { id },
+					body: data,
+				}),
+				select: (data: unknown): Company => data as Company,
+				invalidates: ["crmCompanies", "crmContacts.list", "crmPipelines"],
+				refresh: false,
+			},
+			delete: {
+				path: "@delete/crm/companies/:id",
+				method: "DELETE",
+				input: (id: string) => ({ params: { id } }),
+				invalidates: [
+					"crmCompanies",
+					"crmContacts",
+					"crmDeals",
+					"crmPipelines",
+				],
+				refresh: false,
+			},
+		},
+	},
+	crmDeals: {
+		queries: {
+			list: {
+				path: "/crm/deals",
+				query: (
+					params: CrmListParams = {},
+					_identity?: CrmIdentityPartition,
+				) => ({ ...params }),
+				select: (data: unknown): { items: Deal[]; total: number } =>
+					data as { items: Deal[]; total: number },
+			},
+			detail: {
+				path: "/crm/deals/:id",
+				params: (id: string, _identity?: CrmIdentityPartition) => ({ id }),
+				select: (data: unknown): Deal => data as Deal,
+			},
+		},
+		mutations: {
+			create: {
+				path: "@post/crm/deals",
+				method: "POST",
+				input: (body: DealInput) => ({ body }),
+				select: (data: unknown): Deal => data as Deal,
+				invalidates: ["crmDeals", "crmPipelines"],
+				refresh: false,
+			},
+			update: {
+				path: "@put/crm/deals/:id",
+				method: "PUT",
+				input: ({ id, data }: { id: string; data: DealUpdateInput }) => ({
+					params: { id },
+					body: data,
+				}),
+				select: (data: unknown): Deal => data as Deal,
+				invalidates: ["crmDeals", "crmPipelines"],
+				refresh: false,
+			},
+			delete: {
+				path: "@delete/crm/deals/:id",
+				method: "DELETE",
+				input: (id: string) => ({ params: { id } }),
+				invalidates: ["crmDeals", "crmActivities", "crmPipelines"],
+				refresh: false,
+			},
+			move: {
+				path: "@post/crm/deals/:id/move",
+				method: "POST",
+				input: ({
+					id,
+					stage,
+					order,
+				}: {
+					id: string;
+					stage: string;
+					order?: number;
+				}) => ({ params: { id }, body: { stage, order } }),
+				invalidates: ["crmDeals", "crmPipelines"],
+				refresh: false,
+			},
+		},
+	},
+	crmActivities: {
+		queries: {
+			list: {
+				path: "/crm/activities",
+				query: (
+					params: CrmListParams = {},
+					_identity?: CrmIdentityPartition,
+				) => ({ ...params }),
+				select: (data: unknown): { items: Activity[]; total: number } =>
+					data as { items: Activity[]; total: number },
+			},
+		},
+		mutations: {
+			create: {
+				path: "@post/crm/activities",
+				method: "POST",
+				input: (body: ActivityInput) => ({ body }),
+				select: (data: unknown): Activity => data as Activity,
+				invalidates: ["crmActivities", "crmPipelines"],
+				refresh: false,
+			},
+			update: {
+				path: "@put/crm/activities/:id",
+				method: "PUT",
+				input: ({ id, data }: { id: string; data: ActivityUpdateInput }) => ({
+					params: { id },
+					body: data,
+				}),
+				select: (data: unknown): Activity => data as Activity,
+				invalidates: ["crmActivities", "crmPipelines"],
+				refresh: false,
+			},
+			delete: {
+				path: "@delete/crm/activities/:id",
+				method: "DELETE",
+				input: (id: string) => ({ params: { id } }),
+				invalidates: ["crmActivities", "crmPipelines"],
+				refresh: false,
+			},
+		},
+	},
+	crmPipelines: {
+		queries: {
+			list: {
+				path: "/crm/pipelines",
+				query: (
+					params: CrmListParams = {},
+					_identity?: CrmIdentityPartition,
+				) => ({ ...params }),
+				select: (data: unknown): { items: Pipeline[]; total: number } =>
+					data as { items: Pipeline[]; total: number },
+			},
+			detail: {
+				path: "/crm/pipelines/:id",
+				params: (id: string, _identity?: CrmIdentityPartition) => ({ id }),
+				select: (data: unknown): Pipeline => data as Pipeline,
+			},
+		},
+		mutations: {
+			create: {
+				path: "@post/crm/pipelines",
+				method: "POST",
+				input: (body: PipelineInput) => ({ body }),
+				select: (data: unknown): Pipeline => data as Pipeline,
+				invalidates: ["crmPipelines", "crmPipelines"],
+				refresh: false,
+			},
+		},
+	},
+} satisfies ResourcesDeclaration;
+/** Build query keys shared by request loaders and client hooks. */
+export function createCrmQueryKeys(
+	client: ResourceClient,
+	headers?: HeadersInit,
+) {
+	return createResourceQueryKeys(client, crmResources, headers);
+}

package/src/plugins/crm/schemas.ts

@@ -0,0 +1,111 @@
+import { z } from "zod";
+const text = z.string().trim().max(500);
+const optionalText = text.nullable().optional();
+const relation = z.string().min(1).max(200).nullable().optional();
+const date = z.iso.datetime({ offset: true }).nullable().optional();
+export const idSchema = z.object({ id: z.string().min(1).max(200) });
+export const paginationSchema = z.object({
+	limit: z.coerce.number().int().min(1).max(200).default(50),
+	offset: z.coerce.number().int().min(0).default(0),
+});
+export const createContactSchema = z.object({
+	firstName: text.min(1),
+	lastName: optionalText,
+	email: z.email().max(320).nullable().optional(),
+	phone: optionalText,
+	company: optionalText,
+	companyId: relation,
+	title: optionalText,
+	notes: z.string().max(20000).nullable().optional(),
+	tags: z.array(z.string().trim().min(1).max(100)).max(100).default([]),
+	customFields: z
+		.record(z.string().min(1).max(100), z.string().max(2000))
+		.refine((v) => Object.keys(v).length <= 100, "At most 100 custom fields")
+		.default({}),
+});
+export const updateContactSchema = createContactSchema.partial().extend({
+	tags: createContactSchema.shape.tags.removeDefault().optional(),
+	customFields: createContactSchema.shape.customFields
+		.removeDefault()
+		.optional(),
+});
+export const listContactsSchema = paginationSchema.extend({
+	search: text.optional(),
+	tag: text.optional(),
+	companyId: z.string().optional(),
+});
+export const createCompanySchema = z.object({
+	name: text.min(1),
+	domain: optionalText,
+	phone: optionalText,
+	notes: z.string().max(20000).nullable().optional(),
+});
+export const updateCompanySchema = createCompanySchema.partial();
+export const listCompaniesSchema = paginationSchema.extend({
+	search: text.optional(),
+});
+export const createPipelineSchema = z.object({
+	name: text.min(1),
+	slug: z
+		.string()
+		.regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)
+		.max(200)
+		.optional(),
+	stages: z
+		.array(text.min(1))
+		.min(1)
+		.max(30)
+		.default(["Lead", "Qualified", "Proposal", "Closed"]),
+});
+export const createDealSchema = z.object({
+	title: text.min(1),
+	value: z.number().finite().min(0).nullable().optional(),
+	currency: z
+		.string()
+		.regex(/^[A-Z]{3}$/)
+		.default("USD"),
+	stage: z.string().min(1),
+	pipelineId: z.string().min(1),
+	contactId: relation,
+	companyId: relation,
+	closeDate: date,
+	status: z.enum(["open", "won", "lost"]).default("open"),
+});
+export const updateDealSchema = createDealSchema
+	.omit({ stage: true, pipelineId: true })
+	.partial()
+	.extend({
+		currency: createDealSchema.shape.currency.removeDefault().optional(),
+		status: createDealSchema.shape.status.removeDefault().optional(),
+	});
+export const moveDealSchema = z.object({
+	stage: z.string().min(1),
+	order: z.number().finite().min(0).optional(),
+});
+export const listDealsSchema = paginationSchema.extend({
+	pipelineId: z.string().optional(),
+	contactId: z.string().optional(),
+	companyId: z.string().optional(),
+	status: z.enum(["open", "won", "lost"]).optional(),
+});
+export const createActivitySchema = z
+	.object({
+		type: z.enum(["note", "call", "email", "meeting"]),
+		body: z.string().trim().min(1).max(20000),
+		contactId: relation,
+		dealId: relation,
+		dueAt: date,
+	})
+	.refine(
+		(v) => !!(v.contactId || v.dealId),
+		"An activity needs a contact or deal",
+	);
+export const updateActivitySchema = z.object({
+	body: z.string().trim().min(1).max(20000).optional(),
+	dueAt: date,
+	completedAt: date,
+});
+export const listActivitiesSchema = paginationSchema.extend({
+	contactId: z.string().optional(),
+	dealId: z.string().optional(),
+});

package/src/plugins/crm/style.css

@@ -0,0 +1,3 @@
+@import "./client.css";
+@source "../../../src/**/*.{ts,tsx}";
+@source "../../packages/ui/src";

package/src/plugins/crm/types.ts

@@ -0,0 +1,171 @@
+import type { DeepReadonly } from "@btst/stack/plugins/api";
+import type { z } from "zod";
+import type {
+	createContactSchema,
+	createCompanySchema,
+	createDealSchema,
+} from "./schemas";
+
+/** Contact with arbitrary string custom fields and normalized tags. */
+export type Contact = {
+	id: string;
+	firstName: string;
+	lastName?: string | null;
+	email?: string | null;
+	phone?: string | null;
+	company?: string | null;
+	companyId?: string | null;
+	title?: string | null;
+	notes?: string | null;
+	tags: string[];
+	customFields: Record<string, string>;
+	createdAt: string;
+	updatedAt: string;
+};
+/** A company shared by contacts and deals. */
+export type Company = {
+	id: string;
+	name: string;
+	domain?: string | null;
+	phone?: string | null;
+	notes?: string | null;
+	createdAt: string;
+	updatedAt: string;
+};
+/** A deal's title and stage are projected from its Kanban task, avoiding duplicate state. */
+export type Deal = {
+	id: string;
+	taskId: string;
+	title: string;
+	value?: number | null;
+	currency: string;
+	stage: string;
+	pipelineId: string;
+	contactId?: string | null;
+	companyId?: string | null;
+	closeDate?: string | null;
+	status: "open" | "won" | "lost";
+	createdAt: string;
+	updatedAt: string;
+};
+/** A logged interaction or scheduled follow-up. */
+export type Activity = {
+	id: string;
+	type: "note" | "call" | "email" | "meeting";
+	body: string;
+	contactId?: string | null;
+	dealId?: string | null;
+	dueAt?: string | null;
+	completedAt?: string | null;
+	remindedAt?: string | null;
+	createdAt: string;
+};
+/** A CRM pipeline is an ordinary Kanban board. */
+export type Pipeline = {
+	deals: Deal[];
+	id: string;
+	name: string;
+	slug: string;
+	description?: string;
+	ownerId?: string;
+	organizationId?: string;
+	createdAt: string;
+	updatedAt: string;
+	columns: {
+		id: string;
+		title: string;
+		order: number;
+		boardId: string;
+		createdAt: string;
+		updatedAt: string;
+		tasks: {
+			id: string;
+			title: string;
+			description?: string;
+			priority: "LOW" | "MEDIUM" | "HIGH" | "URGENT";
+			order: number;
+			columnId: string;
+			assigneeId?: string | null;
+			completedAt?: string;
+			isArchived: boolean;
+			createdAt: string;
+			updatedAt: string;
+		}[];
+	}[];
+};
+/** Hook context is supplied only after operation authorization. */
+export interface CrmHookContext {
+	readonly request?: Request;
+}
+type Hook<T> = (
+	value: DeepReadonly<T>,
+	context: CrmHookContext,
+) => Promise<void> | void;
+/** Lifecycle callbacks; reminder delivery is triggered by sendDueReminders in your scheduler. */
+export interface CrmPluginHooks {
+	onBeforeCreateContact?: Hook<z.output<typeof createContactSchema>>;
+	onAfterCreateContact?: Hook<Contact>;
+	onBeforeUpdateContact?: Hook<{
+		id: string;
+		data: Partial<z.output<typeof createContactSchema>>;
+	}>;
+	onAfterUpdateContact?: Hook<Contact>;
+	onBeforeDeleteContact?: Hook<Contact>;
+	onAfterDeleteContact?: Hook<{ id: string }>;
+	onBeforeCreateCompany?: Hook<z.output<typeof createCompanySchema>>;
+	onAfterCreateCompany?: Hook<Company>;
+	onBeforeUpdateCompany?: Hook<{
+		id: string;
+		data: Partial<z.output<typeof createCompanySchema>>;
+	}>;
+	onAfterUpdateCompany?: Hook<Company>;
+	onBeforeDeleteCompany?: Hook<Company>;
+	onAfterDeleteCompany?: Hook<{ id: string }>;
+	onBeforeCreateDeal?: Hook<z.output<typeof createDealSchema>>;
+	onAfterCreateDeal?: Hook<Deal>;
+	onBeforeUpdateDeal?: Hook<{
+		id: string;
+		data: Partial<z.output<typeof createDealSchema>>;
+	}>;
+	onAfterUpdateDeal?: Hook<Deal>;
+	onBeforeDeleteDeal?: Hook<Deal>;
+	onAfterDeleteDeal?: Hook<{ id: string }>;
+	onBeforeLogActivity?: Hook<Omit<Activity, "id" | "createdAt">>;
+	onAfterLogActivity?: Hook<Activity>;
+	onAfterUpdateActivity?: Hook<Activity>;
+	onAfterMoveDeal?: Hook<Deal>;
+	/** Deliver the follow-up notification. Successful delivery is recorded to avoid repeat runs. */
+	onActivityReminder?: Hook<Activity>;
+}
+/** Internal storage types; use operations rather than direct database access in requests. */
+export interface ContactRecord
+	extends Omit<Contact, "tags" | "customFields" | "createdAt" | "updatedAt"> {
+	tags: string;
+	customFields: string;
+	createdAt: Date;
+	updatedAt: Date;
+}
+/** Internal company storage. */
+export interface CompanyRecord
+	extends Omit<Company, "createdAt" | "updatedAt"> {
+	createdAt: Date;
+	updatedAt: Date;
+}
+/** Internal metadata for a Kanban-backed deal. */
+export interface DealRecord
+	extends Omit<
+		Deal,
+		"title" | "stage" | "pipelineId" | "createdAt" | "updatedAt" | "closeDate"
+	> {
+	closeDate?: Date | null;
+	createdAt: Date;
+	updatedAt: Date;
+}
+/** Internal activity storage. */
+export interface ActivityRecord
+	extends Omit<Activity, "dueAt" | "completedAt" | "remindedAt" | "createdAt"> {
+	dueAt?: Date | null;
+	completedAt?: Date | null;
+	remindedAt?: Date | null;
+	createdAt: Date;
+}