@tryvitris/website-admin-contracts 1.5.0 → 1.7.0

package/README.md

@@ -3,3 +3,7 @@
 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.
+
+Google Search Console contracts include performance requests, report provenance/pagination, connection status, supported types/dimensions and `search-console:manage` for connection and sitemap changes.

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,5 @@
+export * from './email-campaigns.js';
+export * from './search-console.js';
 export * from './billing.js';
 export * from './stripe-billing.js';
 export * from './client-portfolio.js';
@@ -8,7 +10,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", "search-console:manage", "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 +43,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;
@@ -74,6 +76,7 @@ export interface BootstrapResponse {
     emailLoginConfigured?: boolean;
     privateLocalSignIn?: boolean;
     webmasterEnabled?: boolean;
+    searchConsoleEnabled?: boolean;
 }
 export type DataSource = 'synthetic' | 'connected' | 'not-connected';
 export interface LeadRow {

package/dist/index.js

@@ -2,6 +2,9 @@ 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 "./search-console.js";
 export * from "./billing.js";
 export * from "./stripe-billing.js";
 export * from "./client-portfolio.js";
@@ -12,10 +15,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", "search-console:manage", "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"]
 };

package/dist/search-console.d.ts

@@ -0,0 +1,58 @@
+export declare const searchTypes: readonly ["web", "image", "video", "news", "discover", "googleNews"];
+export declare const searchDimensions: readonly ["date", "hour", "query", "page", "country", "device", "searchAppearance"];
+export type SearchType = typeof searchTypes[number];
+export interface SearchQuery {
+    startDate: string;
+    endDate: string;
+    type: SearchType;
+    dimensions: string[];
+    rowLimit: number;
+    startRow: number;
+    dataState: 'final' | 'all' | 'hourly_all';
+    dimensionFilterGroups?: {
+        groupType: 'and';
+        filters: {
+            dimension: string;
+            operator: string;
+            expression: string;
+        }[];
+    }[];
+}
+export interface SearchRow {
+    keys?: string[];
+    clicks: number;
+    impressions: number;
+    ctr: number;
+    position?: number;
+}
+export interface SearchReport {
+    source: 'google-search-console';
+    property: string;
+    timezone: 'America/Los_Angeles';
+    request: SearchQuery;
+    rows: SearchRow[];
+    fetchedAt: string;
+    nextStartRow: number | null;
+    responseAggregationType?: string;
+    metadata?: unknown;
+    persisted: boolean;
+    limitations: string[];
+}
+export interface SearchConsoleStatus {
+    configured: boolean;
+    connected: boolean;
+    property: string | null;
+    revision: number;
+    canSubmitSitemaps: boolean;
+    lastSyncedAt: string | null;
+    error: string | null;
+}
+export interface SearchConsoleAppSettings {
+    revision: number;
+    clientId: string;
+    clientSecretSet: boolean;
+    encryptionReady: boolean;
+    redirectUri: string;
+    source: 'admin' | 'environment' | 'not-configured';
+}
+export declare const searchLimitations: string[];

package/dist/search-console.js

@@ -0,0 +1,13 @@
+// packages/contracts/src/search-console.ts
+var searchTypes = ["web", "image", "video", "news", "discover", "googleNews"];
+var searchDimensions = ["date", "hour", "query", "page", "country", "device", "searchAppearance"];
+var searchLimitations = [
+  "Google returns available top rows and omits anonymized queries. Query and page breakdowns need not add up to property totals.",
+  "Daily reports use Pacific time. Final data can lag; fresh and hourly data can be incomplete.",
+  "Search clicks and impressions are separate from website visits and enquiries. The API does not expose every Search Console report."
+];
+export {
+  searchDimensions,
+  searchLimitations,
+  searchTypes
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryvitris/website-admin-contracts",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "type": "module",
   "license": "MIT",
   "description": "Validated installation and module contracts for Cloudflare business admin apps",
@@ -12,6 +12,10 @@
     "./scheduling": {
       "types": "./dist/scheduling.d.ts",
       "default": "./dist/scheduling.js"
+    },
+    "./email-campaigns": {
+      "types": "./dist/email-campaigns.d.ts",
+      "default": "./dist/email-campaigns.js"
     }
   },
   "files": [

package/vitris-release.json

@@ -1,15 +1,17 @@
 {
   "schemaVersion": 1,
   "name": "@tryvitris/website-admin-contracts",
-  "version": "1.5.0",
-  "title": "Typed agent maintenance reports and plans",
+  "version": "1.7.0",
+  "title": "Typed Google search reports and scoped connection management",
   "notesScope": "package",
   "notes": [
-    "Adds the shared package-family, status, release identity and prepare-and-test plan contract used by the admin and website daily maintenance tooling."
+    "Adds Search Console query/report/status types, supported search dimensions and types, provenance, Pacific timezone, Google partial-data metadata, pagination and source-limit disclosures.",
+    "Adds search-console:manage to owner and administrator role defaults, retains analyst read-only access through analytics:read, and identifies the optional connection separately from business navigation.",
+    "Adds the redacted owner application-settings response for in-admin OAuth setup, including revision, callback URL, credential presence and configuration source."
   ],
   "repository": "https://github.com/jackperrotta/website-admin-harness",
   "readmePath": "packages/contracts/README.md",
-  "ref": "v1.5.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",
-  "documentationSha256": "53077ee5624185df808524801143734e7d9786aab747834e83a8603de06a1ee8"
+  "ref": "v1.7.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\r\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.\r\n\r\nGoogle Search Console contracts include performance requests, report provenance/pagination, connection status, supported types/dimensions and `search-console:manage` for connection and sitemap changes.\r\n",
+  "documentationSha256": "9202d8eb80f8553185603d394b7790c26c1d5ab2de424d59640f4227b55e9a17"
 }