@tryvitris/website-admin-contracts 1.0.0 → 1.2.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,3 @@
-# Website Admin Contracts
-
-Validated installation manifests, roles, permissions and module contracts for `@tryvitris/website-admin-harness`. Node.js 24+. MIT licensed.
+# Website Admin Contracts
+
+Validated installation manifests, roles, permissions and module contracts for `@tryvitris/website-admin-harness`. Node.js 24+. MIT licensed.

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export * from './stripe-billing.js';
 export * from './client-portfolio.js';
 export * from './client-onboarding.js';
 export * from './scheduling.js';
+export * from './webmaster.js';
+export * from './pairing.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"];
@@ -11,6 +13,7 @@ export type Role = 'owner' | 'administrator' | 'editor' | 'analyst';
 export declare const roles: Record<Role, readonly Permission[]>;
 export declare function can(role: Role, permission: Permission): boolean;
 export interface AdminManifest {
+    reportingPairing?: import('./pairing.js').PairingConfiguration;
     schemaVersion: 1;
     installationId: string;
     business: {
@@ -47,7 +50,14 @@ export interface User {
     id: string;
     email: string;
     role: Role;
+    webmaster?: {
+        organizationId: string;
+        organizationName: string;
+        permissions: Permission[];
+        revision: number;
+    };
 }
+export declare function userCan(user: User, permission: Permission): boolean;
 export interface BootstrapResponse {
     manifest: AdminManifest;
     user: User | null;
@@ -61,6 +71,7 @@ export interface BootstrapResponse {
     accountAuth?: AccountCapabilities;
     emailLoginConfigured?: boolean;
     privateLocalSignIn?: boolean;
+    webmasterEnabled?: boolean;
 }
 export type DataSource = 'synthetic' | 'connected' | 'not-connected';
 export interface LeadRow {
@@ -169,6 +180,9 @@ export interface ActivityRow {
     actor: string;
     action: string;
     created_at: string;
+    person_id?: string | null;
+    organization_id?: string | null;
+    organization_name?: string | null;
 }
 export interface TaskRow {
     id: string;

package/dist/index.js

@@ -7,6 +7,8 @@ export * from "./stripe-billing.js";
 export * from "./client-portfolio.js";
 export * from "./client-onboarding.js";
 export * from "./scheduling.js";
+export * from "./webmaster.js";
+export * from "./pairing.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];
@@ -34,6 +36,9 @@ function isThemeColor(value) {
 function isWebsiteTheme(value) {
   return isObject(value) && Object.keys(value).length > 0 && Object.entries(value).every(([key, color]) => websiteColorKeys.includes(key) && isThemeColor(color));
 }
+function userCan(user, permission) {
+  return user.webmaster ? user.webmaster.permissions.includes(permission) : can(user.role, permission);
+}
 function isLeadFollowUp(value) {
   if (!isObject(value)) return false;
   return (value.assignedTo === null || typeof value.assignedTo === "string" && value.assignedTo.length > 0 && value.assignedTo.length <= 100) && (value.dueDate === null || typeof value.dueDate === "string" && /^\d{4}-\d{2}-\d{2}$/.test(value.dueDate) && Number.isFinite(Date.parse(value.dueDate + "T00:00:00Z")) && (/* @__PURE__ */ new Date(value.dueDate + "T00:00:00Z")).toISOString().slice(0, 10) === value.dueDate) && typeof value.notes === "string" && value.notes.length <= 3e3 && typeof value.completed === "boolean" && Number.isSafeInteger(value.revision) && Number(value.revision) >= 0 && (value.updatedAt === null || typeof value.updatedAt === "string");
@@ -114,6 +119,18 @@ function parseManifest(value) {
     backend = { provider: "vitris-harness", origin: origin(b.origin, "backend origin"), tenantId };
     if (isLoopback(backend.origin) && !isLoopback(String(v.adminOrigin))) throw new Error("Production admin cannot connect to a local backend");
   }
+  let reportingPairing;
+  if (v.reportingPairing !== void 0) {
+    const config = object(v.reportingPairing);
+    if (!Array.isArray(config.trustedWebmasters) || config.trustedWebmasters.length < 1 || config.trustedWebmasters.length > 10) throw new Error("Configure trusted webmaster installations explicitly");
+    const trustedWebmasters = config.trustedWebmasters.map((raw) => {
+      const p = object(raw), adminOrigin = origin(p.adminOrigin, "trusted webmaster origin");
+      if (isLoopback(adminOrigin) && !isLoopback(String(v.adminOrigin))) throw new Error("A production issuer cannot trust a local webmaster");
+      return { installationId: id(p.installationId, "webmaster installation ID"), siteId: id(p.siteId, "webmaster site ID"), adminOrigin, organizationId: id(p.organizationId, "webmaster organization ID"), organizationName: text(p.organizationName, "webmaster organization name") };
+    });
+    if (new Set(trustedWebmasters.map((p) => p.adminOrigin)).size !== trustedWebmasters.length) throw new Error("Duplicate trusted webmaster origin");
+    reportingPairing = { trustedWebmasters };
+  }
   return {
     schemaVersion: 1,
     installationId: id(v.installationId, "installation ID"),
@@ -122,7 +139,8 @@ function parseManifest(value) {
     adminOrigin: origin(v.adminOrigin, "admin origin"),
     modules,
     ...backend ? { backend } : {},
-    ...v.theme ? { theme: v.theme } : {}
+    ...v.theme ? { theme: v.theme } : {},
+    ...reportingPairing ? { reportingPairing } : {}
   };
 }
 function validateModules(manifest, modules) {
@@ -152,6 +170,7 @@ export {
   parseManifest,
   permissions,
   roles,
+  userCan,
   validateModules,
   websiteColorKeys,
   workQueueModule

package/dist/pairing.d.ts

@@ -0,0 +1,94 @@
+export declare const reportingPairingVersion = 1;
+export declare const pairingBase = "/api/webmaster-reporting/v1";
+export declare const pairingMachineActions: readonly ["request", "poll", "exchange", "report", "rotate", "revoke"];
+export type PairingMachineAction = typeof pairingMachineActions[number];
+export declare const pairingPaths: Record<"capabilities" | "approval" | "approve" | "reject" | "grants" | "revoke-grant" | PairingMachineAction, string>;
+export declare const pairingPolicy: {
+    requestLifetimeSeconds: number;
+    receiptLifetimeSeconds: number;
+    signatureSkewSeconds: number;
+    analyticsDays: readonly [14, 30];
+};
+export interface PairingStart {
+    requestId: string;
+    challenge: string;
+}
+export interface PairingExchange {
+    requestId: string;
+    code: string;
+    verifier: string;
+}
+export interface PairingReportRequest {
+    grantId: string;
+    operation: 'status' | 'analytics';
+    days?: 14 | 30;
+}
+export interface PairingMutation {
+    grantId: string;
+    operationId: string;
+}
+export declare const reportingOperations: readonly ["status", "analytics"];
+export interface PairingIdentity {
+    installationId: string;
+    siteId: string;
+    adminOrigin: string;
+}
+export interface PairingPeer extends PairingIdentity {
+    organizationId: string;
+    organizationName: string;
+}
+export interface PairingConfiguration {
+    trustedWebmasters: PairingPeer[];
+}
+export interface PairingCapabilities {
+    version: 1;
+    issuer: PairingIdentity;
+    siteOrigin: string;
+    operations: readonly ['status', 'analytics'];
+    scope: 'analytics:read';
+    requestPath: string;
+    approvalPath: string;
+}
+export interface PairingEnvelope {
+    version: 1;
+    identity: PairingIdentity;
+    target: string;
+    path: string;
+    time: number;
+    nonce: string;
+    tokenHash: string;
+    request: Record<string, unknown>;
+}
+export interface PairingCredential {
+    version: 1;
+    issuer: PairingIdentity;
+    consumer: PairingIdentity;
+    siteOrigin: string;
+    grantId: string;
+    token: string;
+    keyId: string;
+    scope: 'analytics:read';
+    operations: readonly ['status', 'analytics'];
+}
+export interface PairingGrantView {
+    id: string;
+    organizationId: string;
+    organizationName: string;
+    consumer: PairingIdentity;
+    createdAt: number;
+    lastUsedAt: number | null;
+    revokedAt: number | null;
+    revision: number;
+}
+export interface PairingRequestView {
+    id: string;
+    organizationName: string;
+    consumer: PairingIdentity;
+    issuer: PairingIdentity;
+    expiresAt: number;
+    status: 'pending' | 'approved' | 'revoked' | 'expired';
+    scope: 'analytics:read';
+    createsRelationship: boolean;
+}
+export type PairingErrorCode = 'invalid_request' | 'unauthorized' | 'forbidden' | 'expired' | 'replay' | 'conflict' | 'unavailable' | 'unsupported';
+export declare function samePairingIdentity(a: PairingIdentity, b: PairingIdentity): boolean;

package/dist/pairing.js

@@ -0,0 +1,19 @@
+// packages/contracts/src/pairing.ts
+var reportingPairingVersion = 1;
+var pairingBase = "/api/webmaster-reporting/v1";
+var pairingMachineActions = ["request", "poll", "exchange", "report", "rotate", "revoke"];
+var pairingPaths = Object.fromEntries(["capabilities", "approval", "approve", "reject", "grants", "revoke-grant", ...pairingMachineActions].map((action) => [action, pairingBase + "/" + action]));
+var pairingPolicy = { requestLifetimeSeconds: 600, receiptLifetimeSeconds: 600, signatureSkewSeconds: 90, analyticsDays: [14, 30] };
+var reportingOperations = ["status", "analytics"];
+function samePairingIdentity(a, b) {
+  return a.installationId === b.installationId && a.siteId === b.siteId && a.adminOrigin === b.adminOrigin;
+}
+export {
+  pairingBase,
+  pairingMachineActions,
+  pairingPaths,
+  pairingPolicy,
+  reportingOperations,
+  reportingPairingVersion,
+  samePairingIdentity
+};

package/dist/webmaster.d.ts

@@ -0,0 +1,25 @@
+/** Operational access never includes ownership, access administration or billing. */
+export declare const webmasterScopes: readonly ["analytics:read", "settings:write", "tasks:read", "tasks:write", "leads:read", "leads:write"];
+export type WebmasterScope = typeof webmasterScopes[number];
+export interface WebmasterMember {
+    userId: string;
+    permissions: WebmasterScope[];
+}
+export interface WebmasterConnection {
+    organizationId: string;
+    organizationName: string;
+    billingProvider: boolean;
+    status: 'connected' | 'disconnected';
+    revision: number;
+    members: WebmasterMember[];
+    permissions: WebmasterScope[];
+}
+export interface WebmasterResponse {
+    connection: WebmasterConnection | null;
+    canManage: boolean;
+    eligibleUsers: Array<{
+        id: string;
+        email: string;
+    }>;
+}
+export declare function validWebmasterScopes(value: unknown): value is WebmasterScope[];

package/dist/webmaster.js

@@ -0,0 +1,9 @@
+// packages/contracts/src/webmaster.ts
+var webmasterScopes = ["analytics:read", "settings:write", "tasks:read", "tasks:write", "leads:read", "leads:write"];
+function validWebmasterScopes(value) {
+  return Array.isArray(value) && value.length <= webmasterScopes.length && new Set(value).size === value.length && value.every((p) => webmasterScopes.includes(p)) && (!value.includes("leads:write") || value.includes("leads:read")) && (!value.includes("tasks:write") || value.includes("tasks:read"));
+}
+export {
+  validWebmasterScopes,
+  webmasterScopes
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryvitris/website-admin-contracts",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "type": "module",
   "license": "MIT",
   "description": "Validated installation and module contracts for Cloudflare business admin apps",