Files
persionalBrand/packages/api-client/src/index.ts
T

861 lines
26 KiB
TypeScript

import type {
BookingRequestType,
BookingStatus,
ContactPreference,
FulfillmentType,
PublicOffering,
BrandTemplateKey,
} from "@personal-brand/types";
export type { PublicOffering } from "@personal-brand/types";
export type { BookingStatus } from "@personal-brand/types";
export type { BrandTemplateKey } from "@personal-brand/types";
export interface BrandProfile {
id: string;
slug?: string;
name: string;
templateKey: BrandTemplateKey;
tagline: string | null;
description: string | null;
avatarUrl: string | null;
coverUrl: string | null;
hours: string | null;
address: string | null;
deliveryNote: string | null;
contactPhone: string | null;
contactWechat: string | null;
config?: Record<string, unknown> | null;
}
export interface AdminBrandMembership {
id: string;
role: string;
brand: Pick<BrandProfile, "id" | "name" | "templateKey"> & { slug?: string };
}
export interface AdminBrandMember {
id: string;
role: string;
isEnabled: boolean;
adminUser: {
id: string;
username: string;
displayName: string;
isEnabled: boolean;
};
}
export type BrandUpdate = Partial<Omit<BrandProfile, "id">>;
export interface BrandReleaseSummary {
id: string;
version: number;
status: string;
note: string | null;
actorId: string;
createdAt: string;
revokedAt: string | null;
revokedBy?: string | null;
}
export type BrandPresentationUpdate = Partial<
Record<
"identity" | "home" | "offerings" | "detail" | "profile" | "inquiry" | "success" | "records",
Record<string, string>
>
>;
export interface TemplateAdminField {
key: string;
binding: string;
label: string;
help?: string;
input: "text" | "textarea" | "phone" | "image" | "number";
required?: boolean;
maxLength?: number;
placeholder?: string;
}
export interface TemplateAdminSection {
key: string;
title: string;
description: string;
target: "brand" | "offering" | "trust" | "inquiry";
fields: TemplateAdminField[];
}
export interface AdminTemplateContent {
displayName: string;
admin: { sections: TemplateAdminSection[] };
assetSlots: Array<{
key: string;
binding: string;
target: "brand" | "offering" | "trust";
label: string;
help: string;
required: boolean;
kind: "image" | "logo" | "portrait" | "texture";
aspectRatio?: string;
}>;
}
export interface OfferingUpdate {
name?: string;
description?: string;
coverUrl?: string;
priceText?: string;
priceAmount?: number;
sortOrder?: number;
bookingEnabled?: boolean;
isEnabled?: boolean;
categoryKey?: string;
config?: Record<string, unknown>;
}
export interface TrustContent {
id: string;
type: string;
title: string;
summary?: string | null;
content: string;
coverUrl?: string | null;
sortOrder: number;
isPublished: boolean;
config?: Record<string, unknown> | null;
}
export interface TrustContentInput {
type: string;
title: string;
summary?: string;
content: string;
coverUrl?: string;
sortOrder?: number;
isPublished?: boolean;
config?: Record<string, unknown>;
}
export interface BookingItemInput {
offeringId: string;
quantity: number;
}
export interface CreateBookingInput {
requestType: BookingRequestType;
customerName: string;
phone?: string;
wechatId?: string;
contactPreference: ContactPreference;
fulfillmentType?: FulfillmentType;
offeringId?: string;
requestedDate?: string;
requestedTime?: string;
deliveryAddress?: string;
note?: string;
extraData?: Record<string, unknown>;
items: BookingItemInput[];
}
export interface BookingSummary {
bookingNo: string;
status: BookingStatus;
estimatedAmount: number | null;
createdAt: string;
}
export interface Booking extends BookingSummary {
id: string;
customerName: string;
adminNote?: string | null;
}
export interface BookingTag {
id: string;
name: string;
isPreset: boolean;
isEnabled: boolean;
}
export interface AdminBooking extends Booking {
tags?: Array<{ tag: BookingTag }>;
}
export interface ApiErrorBody {
data: null;
error: { code: string; message: string };
requestId: string | null;
}
export interface BrandTemplateDefinition {
key: "personal" | "food" | "doors";
version: string;
name: string;
description: string;
serviceCategories: string[];
trustContentTypes: string[];
modules: Array<{
key: string;
type: string;
title: string;
required: boolean;
}>;
fields: Array<{
scope: string;
key: string;
label: string;
type: string;
required: boolean;
}>;
capabilities: string[];
runtimeCapabilities: Array<{
key: string;
version: string;
workflowKey?: string;
}>;
}
export interface OfferingSection {
type: "text" | "image-list" | "timeline" | "faq";
title: string;
content?: string;
items?: unknown[];
}
export interface OfferingMedia {
url: string;
alt?: string;
type?: "image" | "video";
}
export interface OfferingCta {
type: "inquiry" | "booking" | "contact" | "external-link";
label: string;
config?: Record<string, unknown>;
}
export interface BrandModule {
id: string;
type: string;
title: string;
isEnabled: boolean;
sortOrder: number;
source: string;
config?: Record<string, unknown> | null;
}
export interface BrandFieldDefinition {
id: string;
scope: string;
key: string;
label: string;
type: string;
required: boolean;
isVisible: boolean;
sortOrder: number;
source: string;
}
export interface InquiryForm {
id: string;
name: string;
offeringId?: string | null;
version: number;
isEnabled: boolean;
fieldsSnapshot: unknown[];
purpose: "inquiry" | "booking" | "quote-request";
targetType: "brand" | "offering";
submissionAction: "create-inquiry" | "create-booking" | "create-quote";
}
export interface InquirySubmission {
id: string;
inquiryFormId: string;
formVersion: number;
fieldsSnapshot: unknown[];
values: Record<string, unknown>;
activeFields: Record<string, boolean>;
createdAt: string;
status: "new" | "reviewing" | "replied" | "qualified" | "converted" | "closed";
adminNote?: string | null;
inquiryForm?: { name: string };
offering?: { id: string; name: string } | null;
statusHistory?: Array<{
fromStatus?: string | null;
toStatus: string;
createdAt: string;
}>;
}
export interface CapabilityInstallation {
id: string | null;
capabilityKey: string;
capabilityVersion: string;
status: "enabled" | "disabled" | "degraded";
config?: Record<string, unknown> | null;
updatedAt: string | null;
source?: "template" | "brand";
}
export interface PublicWorkspace {
schemaVersion?: string;
navigation?: { tabs: Array<{ key: string; label: string; page: string }> };
theme?: {
colors: Record<string, string>;
typography?: Record<string, string>;
spacing?: Record<string, string>;
radius?: Record<string, string>;
};
layout?: { home: string[]; offerings: string[]; detail: string[]; profile: string[] };
contractVersion: string;
brand: BrandProfile | null;
template: { key: BrandTemplateKey; version: string; name: string } | null;
visualTemplate?: {
key: string;
version: string;
name: string;
supportedIndustryTemplates: BrandTemplateKey[];
variants: Record<string, string>;
} | null;
visualTemplateManifest?: {
schemaVersion: "1.0";
key: string;
version: string;
name: string;
brandFirst: true;
tokens: {
colors: Record<string, string>;
spacing: Record<string, string>;
typography: Record<string, string>;
radius: Record<string, string>;
shadows?: Record<string, string>;
};
pages: Array<{
key: string;
title: string;
modules: Array<{
key: string;
type: string;
variant: string;
required: boolean;
dataSlots?: string[];
assetSlots?: string[];
capability?: string;
}>;
}>;
assets: Array<Record<string, unknown>>;
dataSlots: Array<Record<string, unknown>>;
capabilities: string[];
};
capabilities: string[];
modules: BrandModule[];
runtimeModules: Array<{
key: string;
type: string;
version?: string;
propsSchema?: string;
dataSource?: string;
source?: string;
title?: string;
schemaVersion?: string;
sortOrder?: number;
config?: Record<string, unknown> | null;
}>;
fields: BrandFieldDefinition[];
offerings: Offering[];
inquiryForm: InquiryForm | null;
runtimeOfferings?: Array<Record<string, unknown>>;
inquiryForms?: Array<Record<string, unknown>>;
trustPresentation?: Record<string, unknown>;
runtimeCapabilities?: Array<{ key: string; version: string; status?: string }>;
plugins?: Array<{
key: string;
version: string;
displayName: string;
purpose: string;
requiredModules: string[];
apiContract: string;
configSchema: string;
status: string;
}>;
}
export interface Offering {
id: string;
brandId?: string;
kind: "service" | "product" | "package" | "subscription";
name: string;
summary?: string | null;
description?: string | null;
coverUrl?: string | null;
priceText?: string | null;
priceAmount?: number | null;
isEnabled: boolean;
sortOrder: number;
config?: Record<string, unknown> | null;
sections?: OfferingSection[];
media?: OfferingMedia[];
cta?: OfferingCta;
inquiryForms?: Array<Pick<InquiryForm, "id" | "name" | "purpose" | "targetType" | "version">>;
}
export class ApiClientError extends Error {
constructor(
readonly status: number,
readonly body: ApiErrorBody,
) {
super(body.error.message);
this.name = "ApiClientError";
}
get code(): string {
return this.body.error.code;
}
get requestId(): string | null {
return this.body.requestId;
}
}
export interface FetchResponse {
readonly status: number;
readonly ok: boolean;
json(): Promise<unknown>;
}
export type FetchLike = (
input: string,
init?: { method?: string; headers?: Record<string, string>; body?: string },
) => Promise<FetchResponse>;
export interface ApiClientOptions {
baseUrl: string;
fetcher: FetchLike;
token?: string;
}
export class ApiClient {
private readonly baseUrl: string;
private readonly fetcher: FetchLike;
private token: string | undefined;
constructor(options: ApiClientOptions) {
this.baseUrl = options.baseUrl.replace(/\/$/, "");
this.fetcher = options.fetcher;
this.token = options.token;
}
setToken(token: string | undefined): void {
this.token = token;
}
getBrand(): Promise<BrandProfile> {
return this.request("/public/brand");
}
listOfferings(): Promise<PublicOffering[]> {
return this.request("/public/offerings");
}
getPublicWorkspace(): Promise<PublicWorkspace> {
return this.request("/public/workspace");
}
getPublicInquiryForm(id: string): Promise<InquiryForm> {
return this.request(`/public/inquiry-forms/${encodeURIComponent(id)}`);
}
createCustomerInquirySubmission(
formId: string,
values: Record<string, unknown>,
): Promise<InquirySubmission> {
return this.request("/customer/inquiry-submissions", {
method: "POST",
body: { formId, values },
});
}
listCustomerInquirySubmissions(): Promise<InquirySubmission[]> {
return this.request("/customer/inquiry-submissions");
}
getCustomerInquirySubmission(id: string): Promise<InquirySubmission> {
return this.request(`/customer/inquiry-submissions/${encodeURIComponent(id)}`);
}
createCustomerSession(code: string): Promise<{ token: string }> {
return this.request("/customer/session/wechat", { method: "POST", body: { code } });
}
listCustomerBookings(): Promise<Booking[]> {
return this.request("/customer/bookings");
}
createCustomerBooking(input: CreateBookingInput): Promise<BookingSummary> {
return this.request("/customer/bookings", { method: "POST", body: input });
}
cancelCustomerBooking(id: string): Promise<Booking> {
return this.request(`/customer/bookings/${encodeURIComponent(id)}/cancel`, { method: "POST" });
}
loginAdmin(
username: string,
password: string,
): Promise<{
token: string;
displayName: string;
mustChangePassword: boolean;
role: string;
}> {
return this.request("/admin/session/login", { method: "POST", body: { username, password } });
}
changeAdminPassword(currentPassword: string, newPassword: string): Promise<{ changed: true }> {
return this.request("/admin/session/change-password", {
method: "POST",
body: { currentPassword, newPassword },
});
}
listAdminBookings(
filters: { status?: BookingStatus; unreadOnly?: boolean; tagId?: string } = {},
): Promise<AdminBooking[]> {
const params: string[] = [];
if (filters.status) params.push(`status=${encodeURIComponent(filters.status)}`);
if (filters.unreadOnly !== undefined) params.push(`unreadOnly=${filters.unreadOnly}`);
if (filters.tagId) params.push(`tagId=${encodeURIComponent(filters.tagId)}`);
const query = params.join("&");
return this.request(`/admin/bookings${query ? `?${query}` : ""}`);
}
getAdminBooking(id: string): Promise<AdminBooking> {
return this.request(`/admin/bookings/${encodeURIComponent(id)}`);
}
getAdminUnreadCount(): Promise<{ count: number }> {
return this.request("/admin/bookings/unread-count");
}
updateAdminBookingStatus(
id: string,
status: BookingStatus,
adminNote?: string,
): Promise<Booking> {
return this.request(`/admin/bookings/${encodeURIComponent(id)}/status`, {
method: "POST",
body: { status, ...(adminNote === undefined ? {} : { adminNote }) },
});
}
markAdminBookingRead(id: string): Promise<Booking> {
return this.request(`/admin/bookings/${encodeURIComponent(id)}/read`, { method: "POST" });
}
listAdminTags(): Promise<BookingTag[]> {
return this.request("/admin/bookings/tags");
}
createAdminTag(name: string): Promise<BookingTag> {
return this.request("/admin/bookings/tags", { method: "POST", body: { name } });
}
getAdminBrand(): Promise<BrandProfile> {
return this.request("/admin/config/brand");
}
listAdminBrands(): Promise<AdminBrandMembership[]> {
return this.request("/admin/brands");
}
switchAdminBrand(
brandId: string,
): Promise<{ token: string; brand: AdminBrandMembership["brand"] }> {
return this.request(`/admin/brands/${encodeURIComponent(brandId)}/switch`, { method: "POST" });
}
listAdminMembers(): Promise<AdminBrandMember[]> {
return this.request("/admin/brands/members");
}
createAdminMember(body: {
username: string;
displayName: string;
password: string;
role: "owner" | "editor";
}): Promise<AdminBrandMember> {
return this.request("/admin/brands/members", { method: "POST", body });
}
updateAdminMember(
id: string,
body: Partial<Pick<AdminBrandMember, "role" | "isEnabled">>,
): Promise<AdminBrandMember> {
return this.request(`/admin/brands/members/${encodeURIComponent(id)}`, {
method: "PATCH",
body,
});
}
getAdminVisualTemplatePreview(): Promise<{
current: {
key: string;
version: string;
name: string;
theme: { colors: Record<string, string> };
variants: Record<string, string>;
} | null;
available: string[];
}> {
return this.request("/admin/config/visual-template/preview");
}
getAdminVisualTemplateHistory(): Promise<{
history: Array<{ visualTemplateKey: string; savedAt: string }>;
}> {
return this.request("/admin/config/visual-template/history");
}
rollbackAdminVisualTemplate(): Promise<{ visualTemplateKey: string; rolledBack: boolean }> {
return this.request("/admin/config/visual-template/rollback", { method: "POST" });
}
updateAdminBrand(body: BrandUpdate): Promise<BrandProfile> {
return this.request("/admin/config/brand", { method: "PATCH", body });
}
updateAdminBrandPresentation(body: BrandPresentationUpdate): Promise<{
visualPresentation: Record<string, Record<string, string>>;
}> {
return this.request("/admin/config/presentation", { method: "PATCH", body });
}
getPublicTemplate(key: BrandTemplateKey): Promise<BrandTemplateDefinition> {
return this.request(`/public/templates/${key}`);
}
listPublicTemplates(): Promise<{
industries: BrandTemplateDefinition[];
visuals: Array<{
key: string;
version: string;
name: string;
description: string;
supportedIndustryTemplates: BrandTemplateKey[];
variants: Record<string, string>;
theme: { colors: Record<string, string> };
}>;
}> {
return this.request<{
industries: BrandTemplateDefinition[];
visuals: Array<{
key: string;
version: string;
name: string;
description: string;
supportedIndustryTemplates?: unknown;
variants?: unknown;
theme?: unknown;
}>;
}>("/public/templates").then((catalog) => ({
industries: Array.isArray(catalog.industries) ? catalog.industries : [],
visuals: Array.isArray(catalog.visuals)
? catalog.visuals.map((visual) => ({
key: String(visual.key ?? ""),
version: String(visual.version ?? ""),
name: String(visual.name ?? "未命名视觉模板"),
description: String(visual.description ?? ""),
supportedIndustryTemplates: Array.isArray(visual.supportedIndustryTemplates)
? visual.supportedIndustryTemplates.filter(
(item): item is BrandTemplateKey =>
item === "personal" || item === "food" || item === "doors",
)
: [],
variants:
visual.variants && typeof visual.variants === "object"
? (visual.variants as Record<string, string>)
: {},
theme:
visual.theme && typeof visual.theme === "object"
? (visual.theme as { colors: Record<string, string> })
: { colors: {} },
}))
: [],
}));
}
previewPublicTemplateCombination(
industry: string,
visual: string,
): Promise<{
industry: BrandTemplateDefinition;
visual: {
key: string;
version: string;
name: string;
description: string;
supportedIndustryTemplates: BrandTemplateKey[];
variants: Record<string, string>;
theme: { colors: Record<string, string> };
};
runtime: {
schemaVersion: string;
modules: Array<{ key: string; type: string; title: string; variant: string }>;
capabilities: Array<{ key: string; version: string }>;
theme: unknown;
};
}> {
return this.request(
`/public/templates/preview?industry=${encodeURIComponent(industry)}&visual=${encodeURIComponent(visual)}`,
);
}
getPublicOffering(id: string): Promise<Offering> {
return this.request(`/public/offerings/${encodeURIComponent(id)}`);
}
listPublicOfferings(): Promise<Offering[]> {
return this.request("/public/offerings");
}
getAdminWorkspace(): Promise<{
brand: BrandProfile;
visualTemplate?: {
key: string;
version: string;
name: string;
supportedIndustryTemplates: BrandTemplateKey[];
variants: Record<string, string>;
} | null;
installations: Array<{ id: string; templateKey: BrandTemplateKey; templateVersion: string }>;
modules: BrandModule[];
fields: BrandFieldDefinition[];
offerings: Offering[];
forms: unknown[];
templateContent: AdminTemplateContent | null;
}> {
return this.request("/admin/workspace");
}
listAdminReleases(): Promise<BrandReleaseSummary[]> {
return this.request("/admin/releases");
}
getAdminReleaseReadiness(): Promise<{
ready: boolean;
checks: Array<{
key: string;
label: string;
passed: boolean;
help?: string;
destination?: string;
}>;
}> {
return this.request("/admin/releases/readiness");
}
publishAdminRelease(note?: string): Promise<BrandReleaseSummary> {
return this.request("/admin/releases/publish", {
method: "POST",
body: note === undefined ? {} : { note },
});
}
rollbackAdminRelease(version: number, note?: string): Promise<BrandReleaseSummary> {
return this.request(`/admin/releases/${version}/rollback`, {
method: "POST",
body: note === undefined ? {} : { note },
});
}
revokeAdminRelease(): Promise<
Pick<BrandReleaseSummary, "id" | "version" | "status" | "revokedAt">
> {
return this.request("/admin/releases/revoke", { method: "POST" });
}
installAdminTemplate(templateKey: "personal" | "food" | "doors"): Promise<unknown> {
return this.request("/admin/workspace/install", { method: "POST", body: { templateKey } });
}
listAdminCapabilities(): Promise<CapabilityInstallation[]> {
return this.request("/admin/workspace/capabilities");
}
updateAdminCapability(
key: string,
body: {
capabilityVersion: string;
status: CapabilityInstallation["status"];
config?: Record<string, unknown>;
},
): Promise<CapabilityInstallation> {
return this.request(`/admin/workspace/capabilities/${encodeURIComponent(key)}`, {
method: "PATCH",
body,
});
}
previewAdminSampleContent(): Promise<{
templateKey: string;
alreadyImported: boolean;
counts: Record<string, number>;
}> {
return this.request("/admin/workspace/sample-content/preview");
}
importAdminSampleContent(): Promise<{ imported: boolean; counts: Record<string, number> }> {
return this.request("/admin/workspace/sample-content/import", { method: "POST" });
}
getAdminTemplateUpgradePreview(): Promise<{
currentVersion: string;
latestVersion: string;
canUpgrade: boolean;
canRollback: boolean;
missingModules: unknown[];
missingFields: unknown[];
}> {
return this.request("/admin/workspace/template/preview");
}
upgradeAdminTemplate(): Promise<unknown> {
return this.request("/admin/workspace/template/upgrade", { method: "POST" });
}
rollbackAdminTemplate(): Promise<unknown> {
return this.request("/admin/workspace/template/rollback", { method: "POST" });
}
updateAdminModule(id: string, body: Partial<BrandModule>): Promise<BrandModule> {
return this.request(`/admin/workspace/modules/${encodeURIComponent(id)}`, {
method: "PATCH",
body,
});
}
createAdminField(
body: Omit<BrandFieldDefinition, "id" | "source">,
): Promise<BrandFieldDefinition> {
return this.request("/admin/workspace/fields", { method: "POST", body });
}
deleteAdminField(id: string): Promise<{ deleted: boolean }> {
return this.request(`/admin/workspace/fields/${encodeURIComponent(id)}`, { method: "DELETE" });
}
listAdminInquiryForms(): Promise<InquiryForm[]> {
return this.request("/admin/workspace/forms");
}
listAdminInquirySubmissions(): Promise<InquirySubmission[]> {
return this.request("/admin/workspace/submissions");
}
updateAdminInquirySubmission(
id: string,
body: { status: InquirySubmission["status"]; adminNote?: string },
): Promise<InquirySubmission> {
return this.request(`/admin/workspace/submissions/${encodeURIComponent(id)}`, {
method: "PATCH",
body,
});
}
createAdminInquiryForm(body: {
name: string;
offeringId?: string;
fieldsSnapshot: unknown[];
isEnabled?: boolean;
purpose?: InquiryForm["purpose"];
targetType?: InquiryForm["targetType"];
submissionAction?: InquiryForm["submissionAction"];
}): Promise<InquiryForm> {
return this.request("/admin/workspace/forms", { method: "POST", body });
}
updateAdminInquiryForm(
id: string,
body: Partial<{
name: string;
offeringId: string;
fieldsSnapshot: unknown[];
isEnabled: boolean;
purpose?: InquiryForm["purpose"];
targetType?: InquiryForm["targetType"];
submissionAction?: InquiryForm["submissionAction"];
}>,
): Promise<InquiryForm> {
return this.request(`/admin/workspace/forms/${encodeURIComponent(id)}`, {
method: "PATCH",
body,
});
}
listAdminOfferings(): Promise<Offering[]> {
return this.request("/admin/workspace/offerings");
}
createAdminOffering(body: Omit<Offering, "id" | "brandId">): Promise<Offering> {
return this.request("/admin/workspace/offerings", { method: "POST", body });
}
updateAdminOffering(
id: string,
body: Partial<Omit<Offering, "id" | "brandId">>,
): Promise<Offering> {
return this.request(`/admin/workspace/offerings/${encodeURIComponent(id)}`, {
method: "PATCH",
body,
});
}
deleteAdminOffering(id: string): Promise<{ deleted: boolean }> {
return this.request(`/admin/workspace/offerings/${encodeURIComponent(id)}`, {
method: "DELETE",
});
}
listAdminTrustContent(): Promise<TrustContent[]> {
return this.request("/admin/config/trust-content");
}
createAdminTrustContent(body: TrustContentInput): Promise<TrustContent> {
return this.request("/admin/config/trust-content", { method: "POST", body });
}
updateAdminTrustContent(id: string, body: Partial<TrustContentInput>): Promise<TrustContent> {
return this.request(`/admin/config/trust-content/${encodeURIComponent(id)}`, {
method: "PATCH",
body,
});
}
deleteAdminTrustContent(id: string): Promise<{ deleted: boolean }> {
return this.request(`/admin/config/trust-content/${encodeURIComponent(id)}`, {
method: "DELETE",
});
}
private async request<T>(
path: string,
options: { method?: string; body?: unknown } = {},
): Promise<T> {
const headers: Record<string, string> = { accept: "application/json" };
if (options.body !== undefined) headers["content-type"] = "application/json";
if (this.token) headers.authorization = `Bearer ${this.token}`;
const response = await this.fetcher(`${this.baseUrl}${path}`, {
method: options.method ?? "GET",
headers,
...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
});
const body = await response.json();
if (!response.ok) throw new ApiClientError(response.status, body as ApiErrorBody);
return body as T;
}
}
export const apiClientName = "personal-brand-api-client";