@tryvitris/website-admin-contracts 1.4.0 → 1.6.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Vitris contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Vitris contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,7 @@
 # Website Admin Contracts
 
 Validated installation manifests, roles, permissions and module contracts for `@tryvitris/website-admin-harness`. Node.js 24+. MIT licensed.
+
+The maintenance contract exports the stable admin package family and typed installed/locked/published-version reports and preparation plans. Its policy is prepare-and-test under existing publication permissions. It does not execute updates or create schedules; use the runtime maintenance CLI and its agent guide.
+
+The `./email-campaigns` entry exports validated contacts, evidence and preferences, bounded audience rules, structured templates, communication purposes, guided workflow steps, website events, account cost calculations, and workspace types. Explicit email permissions remain excluded from existing non-owner role defaults.

package/dist/email-campaigns.d.ts

@@ -0,0 +1,209 @@
+/** Cloudflare-only customer communications. Newsletter content is draft-only. */
+export declare const emailCampaignPermissions: readonly ["email-campaigns:read", "email-reports:read", "email-contacts:read", "email-contacts:write", "email-contacts:export", "email-content:write", "email-campaigns:send", "email-automations:manage", "email-settings:manage"];
+export type EmailPermission = typeof emailCampaignPermissions[number];
+export declare const emailPurposes: readonly ["customer-report", "service-update", "enquiry-response", "newsletter-draft"];
+export type EmailPurpose = typeof emailPurposes[number];
+export type EmailTopic = 'reports' | 'service' | 'newsletter';
+export interface EmailModuleConfig {
+    feedbackQueue: string;
+    accountId?: string;
+    zoneId?: string;
+    sendingDomain?: string;
+    eventSubscriptionId?: string;
+    dailyLimit?: number;
+}
+export interface EmailSettings {
+    enabled: boolean;
+    mode: 'capture' | 'send';
+    senderName: string;
+    logoUrl: string;
+    replyTo: string;
+    postalAddress: string;
+    accent: string;
+    timezone: string;
+    perMinute: number;
+    dailyLimit: number;
+    monthlyLimit: number;
+    recipientCap: number;
+    spacingHours: number;
+    otherAccountEmails: number;
+    reservedDaily: number;
+    clickTracking: boolean;
+}
+export declare const defaultEmailSettings: () => EmailSettings;
+export interface EmailContact {
+    id: string;
+    revision: number;
+    email: string;
+    name: string;
+    company: string;
+    stage: string;
+    tags: string[];
+    fields: Record<string, string>;
+    source: string;
+    interactionRef: string;
+    serviceRef: string;
+    topics: Partial<Record<EmailTopic, boolean>>;
+    evidence: string;
+    deleted?: boolean;
+}
+export interface EmailRule {
+    field: string;
+    op: 'eq' | 'neq' | 'contains' | 'exists' | 'not_exists';
+    value: string;
+}
+export interface EmailSegment {
+    id: string;
+    revision: number;
+    name: string;
+    match: 'all' | 'any';
+    rules: EmailRule[];
+}
+export interface EmailBlock {
+    type: 'heading' | 'paragraph' | 'button' | 'image' | 'divider';
+    text: string;
+    url?: string;
+    alt?: string;
+}
+export interface EmailTemplate {
+    id: string;
+    revision: number;
+    name: string;
+    layout: 'letter' | 'newsletter' | 'report' | 'update';
+    subject: string;
+    preheader: string;
+    blocks: EmailBlock[];
+}
+export interface EmailCampaign {
+    id: string;
+    revision: number;
+    name: string;
+    purpose: EmailPurpose;
+    templateId: string;
+    segmentId: string;
+    excludeIds: string[];
+    scheduledAt: string;
+    status: 'draft' | 'preparing' | 'scheduled' | 'running' | 'paused' | 'cancelled' | 'completed';
+    snapshot?: EmailTemplate;
+    audienceCutoff?: number;
+    cursor?: string;
+    approvedBy?: string;
+    approvalRevision?: number;
+    recurrenceDays?: number;
+    nextIssueAt?: number;
+    sourceArticle?: string;
+}
+export type EmailStep = {
+    type: 'wait';
+    minutes: number;
+} | {
+    type: 'send';
+    templateId: string;
+} | {
+    type: 'condition';
+    rule: EmailRule;
+    skip: number;
+} | {
+    type: 'tag';
+    value: string;
+} | {
+    type: 'stage';
+    value: string;
+} | {
+    type: 'task';
+    title: string;
+} | {
+    type: 'exit';
+};
+export interface EmailAutomation {
+    id: string;
+    revision: number;
+    name: string;
+    trigger: 'lead.created' | 'service.updated' | 'report.ready' | 'manual' | 'subscription.confirmed';
+    purpose: EmailPurpose;
+    status: 'draft' | 'active' | 'paused';
+    steps: EmailStep[];
+    version?: number;
+    publisherId?: string;
+    hasDraft?: boolean;
+}
+export interface EmailWebsiteEvent {
+    version: 1;
+    mode: 'production' | 'test';
+    id: string;
+    installationId: string;
+    siteId: string;
+    type: 'lead.created' | 'service.updated' | 'report.ready' | 'customer.converted' | 'enquiry.resolved' | 'subscription.confirmed';
+    occurredAt: string;
+    /** Optional campaign attribution, verified against an actual live message to this contact. */
+    campaignId?: string;
+    contact: {
+        email: string;
+        name: string;
+        company?: string;
+        interactionRef?: string;
+        serviceRef?: string;
+    };
+    report?: {
+        title: string;
+        period: string;
+        summary: string;
+        url?: string;
+    };
+}
+export interface EmailRecord<T> {
+    id: string;
+    revision: number;
+    data: T;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface EmailJob {
+    id: string;
+    campaignId: string;
+    contactId: string;
+    state: string;
+    reason: string | null;
+    mode: 'capture' | 'send';
+    dueAt: number;
+    createdAt: number;
+    providerMessageId: string | null;
+}
+export interface EmailWorkspace {
+    settings: EmailRecord<EmailSettings>;
+    readiness: {
+        schemaReady: boolean;
+        keysReady: boolean;
+        senderReady: boolean;
+        liveReady: boolean;
+        feedbackReady: boolean;
+        websiteReady: boolean;
+        deliveryPaused: boolean;
+        deliveryReason: string;
+        from: string;
+        issues: string[];
+    };
+    permissions: EmailPermission[];
+    counts: Record<string, number>;
+    monthly: {
+        counted: number;
+        estimatedOverage: number;
+        included: number;
+    };
+    templates: EmailTemplate[];
+}
+export declare class EmailInputError extends Error {
+    constructor(message: string);
+}
+export declare const validEmail: (v: unknown) => v is string;
+export declare const emailId: (v: unknown) => v is string;
+export declare function safeEmailUrl(v: unknown): string;
+export declare function parseEmailRule(v: unknown): EmailRule;
+export declare function parseEmailContact(v: unknown): EmailContact;
+export declare function parseEmailSegment(v: unknown): EmailSegment;
+export declare function parseEmailTemplate(v: unknown): EmailTemplate;
+export declare function parseEmailCampaign(v: unknown): EmailCampaign;
+export declare function parseEmailAutomation(v: unknown): EmailAutomation;
+export declare function parseEmailSettings(v: unknown): EmailSettings;
+export declare function emailOverage(count: number): number;
+export declare function starterEmailTemplates(): EmailTemplate[];

package/dist/email-campaigns.js

@@ -0,0 +1,166 @@
+// packages/contracts/src/email-campaigns.ts
+var emailCampaignPermissions = ["email-campaigns:read", "email-reports:read", "email-contacts:read", "email-contacts:write", "email-contacts:export", "email-content:write", "email-campaigns:send", "email-automations:manage", "email-settings:manage"];
+var emailPurposes = ["customer-report", "service-update", "enquiry-response", "newsletter-draft"];
+var defaultEmailSettings = () => ({ enabled: false, mode: "capture", senderName: "", logoUrl: "", replyTo: "", postalAddress: "", accent: "#245c50", timezone: "America/New_York", perMinute: 50, dailyLimit: 500, monthlyLimit: 3e3, recipientCap: 5e3, spacingHours: 24, otherAccountEmails: 0, reservedDaily: 50, clickTracking: false });
+var EmailInputError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "EmailInputError";
+  }
+};
+var object = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+var validEmail = (v) => typeof v === "string" && v.length <= 254 && /^[^\s@<>]+@[^\s@<>]+\.[^\s@<>]+$/.test(v) && !/[\u0000-\u001f\u007f]/.test(v);
+var emailId = (v) => typeof v === "string" && /^[a-zA-Z0-9_-]{1,100}$/.test(v);
+function string(v, max, empty = true) {
+  if (typeof v !== "string" || v.length > max || !empty && !v.trim() || /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(v))
+    throw new EmailInputError("Enter a valid text value.");
+  return v.trim();
+}
+function integer(v, min, max) {
+  if (!Number.isInteger(v) || Number(v) < min || Number(v) > max)
+    throw new EmailInputError(`Use a whole number from ${min} to ${max}.`);
+  return Number(v);
+}
+function choice(v, values) {
+  if (!values.includes(v))
+    throw new EmailInputError("Choose a supported option.");
+  return v;
+}
+function common(v) {
+  return { id: v.id === void 0 ? "" : v.id === "" ? "" : emailId(v.id) ? v.id : (() => {
+    throw new EmailInputError("Invalid record ID.");
+  })(), revision: integer(v.revision ?? 0, 0, 1e8) };
+}
+function safeEmailUrl(v) {
+  const value = string(v, 2e3, false);
+  try {
+    const u = new URL(value);
+    if (u.protocol !== "https:" && !(u.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(u.hostname)) || u.username || u.password)
+      throw Error();
+    return u.href;
+  } catch {
+    throw new EmailInputError("Use an absolute HTTPS link.");
+  }
+}
+function parseEmailRule(v) {
+  if (!object(v) || typeof v.field !== "string" || !/^((stage|tag|source|company|service|interaction|topic|event)|custom\.[a-zA-Z][a-zA-Z0-9_-]{0,30})$/.test(v.field))
+    throw new EmailInputError("Choose a supported segment field.");
+  return { field: v.field, op: choice(v.op, ["eq", "neq", "contains", "exists", "not_exists"]), value: string(v.value ?? "", 300) };
+}
+function parseEmailContact(v) {
+  if (!object(v) || !validEmail(v.email))
+    throw new EmailInputError("Enter a valid contact email.");
+  if (!Array.isArray(v.tags) || v.tags.length > 30 || !object(v.fields) || Object.keys(v.fields).length > 20 || !object(v.topics))
+    throw new EmailInputError("Use at most 30 tags and 20 custom fields.");
+  const fields = {};
+  for (const [key, value] of Object.entries(v.fields)) {
+    if (!/^[a-zA-Z][a-zA-Z0-9_-]{0,30}$/.test(key))
+      throw new EmailInputError("Invalid custom field name.");
+    fields[key] = string(value, 500);
+  }
+  const topics = {};
+  for (const [key, value] of Object.entries(v.topics)) {
+    if (!["reports", "service", "newsletter"].includes(key) || typeof value !== "boolean")
+      throw new EmailInputError("Invalid topic preference.");
+    topics[key] = value;
+  }
+  return { ...common(v), email: v.email.trim(), name: string(v.name ?? "", 150), company: string(v.company ?? "", 150), stage: string(v.stage ?? "lead", 50, false), tags: [...new Set(v.tags.map((t) => string(t, 60, false)))], fields, source: string(v.source ?? "manual", 100), interactionRef: string(v.interactionRef ?? "", 200), serviceRef: string(v.serviceRef ?? "", 200), topics, evidence: string(v.evidence ?? "", 1e3) };
+}
+function parseEmailSegment(v) {
+  if (!object(v) || !Array.isArray(v.rules) || v.rules.length > 16)
+    throw new EmailInputError("Use at most 16 segment rules.");
+  return { ...common(v), name: string(v.name, 150, false), match: choice(v.match, ["all", "any"]), rules: v.rules.map(parseEmailRule) };
+}
+function parseEmailTemplate(v) {
+  if (!object(v) || !Array.isArray(v.blocks) || v.blocks.length < 1 || v.blocks.length > 40)
+    throw new EmailInputError("Use 1 to 40 content sections.");
+  const subject = string(v.subject, 250, false);
+  if (/[\r\n]/.test(subject))
+    throw new EmailInputError("Subject must be one line.");
+  return { ...common(v), name: string(v.name, 150, false), layout: choice(v.layout, ["letter", "newsletter", "report", "update"]), subject, preheader: string(v.preheader ?? "", 250), blocks: v.blocks.map((b) => {
+    if (!object(b))
+      throw new EmailInputError("Invalid content section.");
+    const type = choice(b.type, ["heading", "paragraph", "button", "image", "divider"]);
+    const url = b.url ? safeEmailUrl(b.url) : void 0;
+    if ((type === "button" || type === "image") && !url)
+      throw new EmailInputError("Buttons and images need an HTTPS link.");
+    return { type, text: string(b.text ?? "", 5e3), ...url ? { url } : {}, ...type === "image" ? { alt: string(b.alt ?? "", 300, false) } : {} };
+  }) };
+}
+function parseEmailCampaign(v) {
+  if (!object(v) || !emailId(v.templateId) || v.segmentId !== "" && !emailId(v.segmentId) || !Array.isArray(v.excludeIds) || v.excludeIds.length > 500 || v.excludeIds.some((x) => !emailId(x)))
+    throw new EmailInputError("Choose a template, audience, and valid exclusions.");
+  let scheduledAt = string(v.scheduledAt ?? "", 40);
+  if (scheduledAt && (!/Z$/.test(scheduledAt) || !Number.isFinite(Date.parse(scheduledAt))))
+    throw new EmailInputError("Schedule with an absolute UTC date.");
+  return { ...common(v), name: string(v.name, 150, false), purpose: choice(v.purpose, emailPurposes), templateId: v.templateId, segmentId: v.segmentId, excludeIds: v.excludeIds, scheduledAt, status: "draft", recurrenceDays: integer(v.recurrenceDays ?? 0, 0, 365), ...v.sourceArticle ? { sourceArticle: safeEmailUrl(v.sourceArticle) } : {} };
+}
+function parseEmailAutomation(v) {
+  if (!object(v) || !Array.isArray(v.steps) || !v.steps.length || v.steps.length > 12)
+    throw new EmailInputError("Use 1 to 12 forward-only steps.");
+  const steps = v.steps.map((s, index) => {
+    if (!object(s))
+      throw new EmailInputError("Invalid automation step.");
+    switch (s.type) {
+      case "wait":
+        return { type: s.type, minutes: integer(s.minutes, 1, 43200) };
+      case "send":
+        if (!emailId(s.templateId))
+          throw new EmailInputError("Choose a send template.");
+        return { type: s.type, templateId: s.templateId };
+      case "condition":
+        return { type: s.type, rule: parseEmailRule(s.rule), skip: integer(s.skip, 1, 12 - index) };
+      case "tag":
+      case "stage":
+        return { type: s.type, value: string(s.value, 60, false) };
+      case "task":
+        return { type: s.type, title: string(s.title, 180, false) };
+      case "exit":
+        return { type: s.type };
+      default:
+        throw new EmailInputError("Unsupported automation step.");
+    }
+  });
+  return { ...common(v), name: string(v.name, 150, false), trigger: choice(v.trigger, ["lead.created", "service.updated", "report.ready", "manual", "subscription.confirmed"]), purpose: choice(v.purpose, emailPurposes), status: "draft", steps };
+}
+function parseEmailSettings(v) {
+  if (!object(v) || typeof v.enabled !== "boolean" || typeof v.clickTracking !== "boolean" || typeof v.accent !== "string" || !/^#[\da-f]{6}$/i.test(v.accent) || v.replyTo && !validEmail(v.replyTo))
+    throw new EmailInputError("Check email settings and reply address.");
+  if (typeof v.senderName === "string" && /[\r\n]/.test(v.senderName)) throw new EmailInputError("Use a single line for the sender name.");
+  const timezone = string(v.timezone, 100, false);
+  try {
+    new Intl.DateTimeFormat("en", { timeZone: timezone });
+  } catch {
+    throw new EmailInputError("Choose a valid timezone.");
+  }
+  return { enabled: v.enabled, mode: choice(v.mode, ["capture", "send"]), senderName: string(v.senderName, 150), logoUrl: v.logoUrl ? safeEmailUrl(v.logoUrl) : "", replyTo: string(v.replyTo ?? "", 254), postalAddress: string(v.postalAddress ?? "", 500), accent: v.accent, timezone, perMinute: integer(v.perMinute, 1, 100), dailyLimit: integer(v.dailyLimit, 1, 1e5), monthlyLimit: integer(v.monthlyLimit, 1, 1e6), recipientCap: integer(v.recipientCap, 1, 1e4), spacingHours: integer(v.spacingHours, 0, 720), otherAccountEmails: integer(v.otherAccountEmails, 0, 1e7), reservedDaily: integer(v.reservedDaily, 0, 1e5), clickTracking: v.clickTracking };
+}
+function emailOverage(count) {
+  return Math.round(Math.max(0, count - 3e3) * 0.035) / 100;
+}
+function starterEmailTemplates() {
+  return [
+    { id: "starter-report", revision: 0, name: "Customer report", layout: "report", subject: "Your {{report.period|latest}} report", preheader: "An update on your agreed service.", blocks: [{ type: "heading", text: "{{report.title|Your service report}}" }, { type: "paragraph", text: "Hello {{firstName|there}},\n\n{{report.summary|Your requested report is ready.}}" }] },
+    { id: "starter-response", revision: 0, name: "Personal response", layout: "letter", subject: "We received your enquiry", preheader: "Your enquiry has reached our team.", blocks: [{ type: "paragraph", text: "Hello {{firstName|there}},\n\nThank you for contacting us. Our team has received your request and will respond with the information you asked for." }] },
+    { id: "starter-update", revision: 0, name: "Service update", layout: "update", subject: "An update on your service", preheader: "The latest status of your agreed service.", blocks: [{ type: "heading", text: "Your service update" }, { type: "paragraph", text: "Hello {{firstName|there}},\n\n{{report.summary|We have an update about your agreed service.}}" }] },
+    { id: "starter-newsletter", revision: 0, name: "Newsletter draft", layout: "newsletter", subject: "This month\u2019s notes", preheader: "Stories and updates.", blocks: [{ type: "heading", text: "This month\u2019s notes" }, { type: "paragraph", text: "Write your opening note here." }] }
+  ];
+}
+export {
+  EmailInputError,
+  defaultEmailSettings,
+  emailCampaignPermissions,
+  emailId,
+  emailOverage,
+  emailPurposes,
+  parseEmailAutomation,
+  parseEmailCampaign,
+  parseEmailContact,
+  parseEmailRule,
+  parseEmailSegment,
+  parseEmailSettings,
+  parseEmailTemplate,
+  safeEmailUrl,
+  starterEmailTemplates,
+  validEmail
+};

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export * from './email-campaigns.js';
 export * from './billing.js';
 export * from './stripe-billing.js';
 export * from './client-portfolio.js';
@@ -8,7 +9,7 @@ export * from './pairing.js';
 export * from './signon.js';
 export declare const contractVersion = 1;
 export declare const coreSections: readonly ["overview", "leads", "analytics", "settings", "access", "activity"];
-export declare const permissions: readonly ["leads:read", "leads:write", "analytics:read", "settings:write", "access:read", "access:write", "activity:read", "tasks:read", "tasks:write", "appointments:read", "appointments:write", "availability:write", "scheduling:configure", "calendar-connections:manage", "clients:read", "client-changes:request", "client-releases:publish", "prospects:read", "prospects:write", "billing:read", "billing:customers:write", "billing:catalog:read", "billing:subscriptions:write", "billing:invoices:write", "billing:collect", "billing:connection:manage", "account-billing:read", "account-billing:manage"];
+export declare const permissions: readonly ["leads:read", "leads:write", "analytics:read", "settings:write", "access:read", "access:write", "activity:read", "tasks:read", "tasks:write", "appointments:read", "appointments:write", "availability:write", "scheduling:configure", "calendar-connections:manage", "clients:read", "client-changes:request", "client-releases:publish", "prospects:read", "prospects:write", "billing:read", "billing:customers:write", "billing:catalog:read", "billing:subscriptions:write", "billing:invoices:write", "billing:collect", "billing:connection:manage", "account-billing:read", "account-billing:manage", "email-campaigns:read", "email-reports:read", "email-contacts:read", "email-contacts:write", "email-contacts:export", "email-content:write", "email-campaigns:send", "email-automations:manage", "email-settings:manage"];
 export type Permission = typeof permissions[number];
 export type Role = 'owner' | 'administrator' | 'editor' | 'analyst';
 export declare const roles: Record<Role, readonly Permission[]>;
@@ -41,7 +42,7 @@ export type WebsiteTheme = Partial<Record<typeof websiteColorKeys[number], strin
 export declare function isThemeColor(value: unknown): value is string;
 export declare function isWebsiteTheme(value: unknown): value is WebsiteTheme;
 export interface ModuleDefinition {
-    ui?: 'stripe-billing' | 'stripe-account';
+    ui?: 'stripe-billing' | 'stripe-account' | 'email-campaigns';
     id: string;
     version: number;
     label: string;
@@ -214,3 +215,4 @@ export declare const workQueueModule: ModuleDefinition;
 export declare function isLoopback(origin: string): boolean;
 export declare function parseManifest(value: unknown): AdminManifest;
 export declare function validateModules(manifest: AdminManifest, modules: ModuleDefinition[]): void;
+export * from './maintenance.js';

package/dist/index.js

@@ -2,6 +2,8 @@ import { schedulingPermissions } from "./scheduling.js";
 import { clientPortfolioPermissions } from "./client-portfolio.js";
 import { clientOnboardingPermissions } from "./client-onboarding.js";
 import { billingPermissions } from "./billing.js";
+import { emailCampaignPermissions } from "./email-campaigns.js";
+export * from "./email-campaigns.js";
 export * from "./billing.js";
 export * from "./stripe-billing.js";
 export * from "./client-portfolio.js";
@@ -12,10 +14,10 @@ export * from "./pairing.js";
 export * from "./signon.js";
 const contractVersion = 1;
 const coreSections = ["overview", "leads", "analytics", "settings", "access", "activity"];
-const permissions = ["leads:read", "leads:write", "analytics:read", "settings:write", "access:read", "access:write", "activity:read", "tasks:read", "tasks:write", ...schedulingPermissions, ...clientPortfolioPermissions, ...clientOnboardingPermissions, ...billingPermissions];
+const permissions = ["leads:read", "leads:write", "analytics:read", "settings:write", "access:read", "access:write", "activity:read", "tasks:read", "tasks:write", ...schedulingPermissions, ...clientPortfolioPermissions, ...clientOnboardingPermissions, ...billingPermissions, ...emailCampaignPermissions];
 const roles = {
   owner: permissions,
-  administrator: permissions.filter((p) => p !== "access:write" && !clientPortfolioPermissions.includes(p) && !clientOnboardingPermissions.includes(p) && !billingPermissions.includes(p)),
+  administrator: permissions.filter((p) => p !== "access:write" && !clientPortfolioPermissions.includes(p) && !clientOnboardingPermissions.includes(p) && !billingPermissions.includes(p) && !emailCampaignPermissions.includes(p)),
   editor: ["leads:read", "leads:write", "activity:read", "tasks:read", "tasks:write"],
   analyst: ["analytics:read", "activity:read"]
 };
@@ -166,6 +168,7 @@ function validateModules(manifest, modules) {
   }
   for (const enabled of manifest.modules) if (!ids.has(enabled)) throw new Error(`Module ${enabled} is not installed`);
 }
+export * from "./maintenance.js";
 export {
   analyticsBreakdownKeys,
   analyticsMetricKeys,

package/dist/maintenance.d.ts

@@ -0,0 +1,47 @@
+/** Package maintenance is an agent workflow; this contract grants no deployment authority. */
+export declare const maintenanceVersion = 1;
+export declare const adminMaintenancePackages: readonly ["@tryvitris/website-admin-harness", "@tryvitris/website-admin-contracts", "@tryvitris/create-website-admin-harness"];
+export declare const maintenancePackages: readonly ["@tryvitris/website-admin-harness", "@tryvitris/website-admin-contracts", "@tryvitris/create-website-admin-harness", "@tryvitris/website-harness"];
+export type MaintenancePackage = typeof maintenancePackages[number];
+export type MaintenanceStatus = 'not-declared' | 'current' | 'update-available' | 'ahead' | 'unmanaged' | 'drift' | 'unavailable';
+export interface MaintenanceRelease {
+    name: MaintenancePackage;
+    version: string;
+    integrity: string;
+    tarball: string;
+}
+export interface MaintenanceEntry {
+    name: MaintenancePackage;
+    declared: string | null;
+    installed: string | null;
+    locked: string | null;
+    status: MaintenanceStatus;
+    change: 'none' | 'patch' | 'minor' | 'major' | 'unknown';
+    latest: MaintenanceRelease | null;
+}
+export interface MaintenanceReport {
+    schemaVersion: 1;
+    checkedAt: string;
+    policy: 'prepare-and-test';
+    adminRelease: {
+        version: string | null;
+        complete: boolean;
+    };
+    packages: MaintenanceEntry[];
+    baseline: Record<string, string>;
+    deployment: 'not-checked';
+}
+export interface MaintenancePlan {
+    schemaVersion: 1;
+    policy: 'prepare-and-test';
+    baseline: Record<string, string>;
+    ready: boolean;
+    held: MaintenancePackage[];
+    updates: MaintenanceRelease[];
+    install: {
+        command: 'npm';
+        args: string[];
+    } | null;
+    requiredChecks: string[];
+    deployment: 'follow-existing-permissions';
+}

package/dist/maintenance.js

@@ -0,0 +1,9 @@
+// packages/contracts/src/maintenance.ts
+var maintenanceVersion = 1;
+var adminMaintenancePackages = ["@tryvitris/website-admin-harness", "@tryvitris/website-admin-contracts", "@tryvitris/create-website-admin-harness"];
+var maintenancePackages = ["@tryvitris/website-admin-harness", "@tryvitris/website-admin-contracts", "@tryvitris/create-website-admin-harness", "@tryvitris/website-harness"];
+export {
+  adminMaintenancePackages,
+  maintenancePackages,
+  maintenanceVersion
+};

package/package.json

@@ -1,37 +1,50 @@
-{
-  "name": "@tryvitris/website-admin-contracts",
-  "version": "1.4.0",
-  "type": "module",
-  "license": "MIT",
-  "description": "Validated installation and module contracts for Cloudflare business admin apps",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    },
-    "./scheduling": {
-      "types": "./dist/scheduling.d.ts",
-      "default": "./dist/scheduling.js"
-    }
-  },
-  "files": [
-    "dist",
-    "vitris-release.json"
-  ],
-  "publishConfig": {
-    "access": "public",
-    "tag": "latest"
-  },
-  "engines": {
-    "node": ">=24"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/jackperrotta/website-admin-harness.git",
-    "directory": "packages/contracts"
-  },
-  "homepage": "https://github.com/jackperrotta/website-admin-harness#readme",
-  "bugs": {
-    "url": "https://github.com/jackperrotta/website-admin-harness/issues"
-  }
-}
+{
+  "name": "@tryvitris/website-admin-contracts",
+  "version": "1.6.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "Validated installation and module contracts for Cloudflare business admin apps",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./scheduling": {
+      "types": "./dist/scheduling.d.ts",
+      "default": "./dist/scheduling.js"
+    },
+    "./email-campaigns": {
+      "types": "./dist/email-campaigns.d.ts",
+      "default": "./dist/email-campaigns.js"
+    }
+  },
+  "files": [
+    "dist",
+    "vitris-release.json"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jackperrotta/website-admin-harness.git",
+    "directory": "packages/contracts"
+  },
+  "homepage": "https://github.com/jackperrotta/website-admin-harness#readme",
+  "bugs": {
+    "url": "https://github.com/jackperrotta/website-admin-harness/issues"
+  },
+  "vitris": {
+    "maintenance": {
+      "version": 1,
+      "policy": "prepare-and-test",
+      "stableChannel": "latest",
+      "command": "vitris-admin updates check --dir . --json",
+      "schedule": "reuse-existing-daily-care"
+    }
+  }
+}

package/vitris-release.json

@@ -1,15 +1,16 @@
 {
   "schemaVersion": 1,
   "name": "@tryvitris/website-admin-contracts",
-  "version": "1.4.0",
-  "title": "Optional combined connection approval contract",
+  "version": "1.6.0",
+  "title": "Customer email purposes audiences and workflows",
   "notesScope": "package",
   "notes": [
-    "Adds versioned combined-setup capability discovery, optional named-subject intent, owner-selected existing-account approval and explicit sign-on result metadata. Legacy reporting-only requests remain supported."
+    "Adds typed, validated Cloudflare email settings, contact and permission evidence, segment rules, structured templates, campaign purposes, guided automation steps, website events, workspace responses, and per-account cost calculations.",
+    "Adds explicit email permissions excluded from existing non-owner role defaults and identifies the optional compiled email workspace without exposing handlers or credentials in bootstrap metadata."
   ],
   "repository": "https://github.com/jackperrotta/website-admin-harness",
   "readmePath": "packages/contracts/README.md",
-  "ref": "v1.4.0",
-  "documentation": "# Website Admin Contracts\r\n\r\nValidated installation manifests, roles, permissions and module contracts for `@tryvitris/website-admin-harness`. Node.js 24+. MIT licensed.\r\n",
-  "documentationSha256": "dc7fd3ba89b1a0a49046735adc8963115551a0d8cc7a4e64e8fba70c79ca9389"
+  "ref": "v1.6.0",
+  "documentation": "# Website Admin Contracts\r\n\r\nValidated installation manifests, roles, permissions and module contracts for `@tryvitris/website-admin-harness`. Node.js 24+. MIT licensed.\r\n\r\nThe maintenance contract exports the stable admin package family and typed installed/locked/published-version reports and preparation plans. Its policy is prepare-and-test under existing publication permissions. It does not execute updates or create schedules; use the runtime maintenance CLI and its agent guide.\r\n\nThe `./email-campaigns` entry exports validated contacts, evidence and preferences, bounded audience rules, structured templates, communication purposes, guided workflow steps, website events, account cost calculations, and workspace types. Explicit email permissions remain excluded from existing non-owner role defaults.\n",
+  "documentationSha256": "091ba91c28394499ae091ca75665e8e60b8b47fd07e71bb8fabc4a36fbae2073"
 }