@tryvitris/website-admin-contracts 0.0.0-stage → 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -1,3 +1,3 @@
-# Temporary Holding Version
+# Website Admin Contracts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Validated installation manifests, roles, permissions and module contracts for `@tryvitris/website-admin-harness`. Node.js 24+. MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+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", "activity:read", "tasks:read", "tasks:write"];
+export type Permission = typeof permissions[number];
+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 {
+    schemaVersion: 1;
+    installationId: string;
+    business: {
+        name: string;
+        initials: string;
+    };
+    site: {
+        id: string;
+        name: string;
+        origin: string;
+    };
+    adminOrigin: string;
+    modules: string[];
+    backend?: {
+        provider: 'vitris-harness';
+        origin: string;
+        tenantId: string;
+    };
+}
+export interface ModuleDefinition {
+    id: string;
+    version: number;
+    label: string;
+    permission: Permission;
+    description: string;
+}
+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;

package/dist/index.js

@@ -0,0 +1,91 @@
+// packages/contracts/src/index.ts
+var contractVersion = 1;
+var coreSections = ["overview", "leads", "analytics", "settings", "access", "activity"];
+var permissions = ["leads:read", "leads:write", "analytics:read", "settings:write", "access:read", "activity:read", "tasks:read", "tasks:write"];
+var roles = {
+  owner: permissions,
+  administrator: permissions,
+  editor: ["leads:read", "leads:write", "activity:read", "tasks:read", "tasks:write"],
+  analyst: ["analytics:read", "activity:read"]
+};
+function can(role, permission) {
+  return roles[role]?.includes(permission) ?? false;
+}
+var workQueueModule = {
+  id: "work-queue",
+  version: 1,
+  label: "Work queue",
+  permission: "tasks:read",
+  description: "An example business module for tracking follow-up work."
+};
+function object(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Expected an object");
+  return value;
+}
+function text(value, name, limit = 100) {
+  if (typeof value !== "string" || !value.trim() || value.length > limit) throw new Error(`Invalid ${name}`);
+  return value.trim();
+}
+function id(value, name) {
+  const result = text(value, name, 64);
+  if (!/^[a-z][a-z0-9-]*$/.test(result)) throw new Error(`Invalid ${name}`);
+  return result;
+}
+function isLoopback(origin2) {
+  const url = new URL(origin2);
+  return ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+}
+function origin(value, name) {
+  const raw = text(value, name, 250);
+  const url = new URL(raw);
+  if (raw !== url.origin || url.username || url.password || url.protocol !== "https:" && !(url.protocol === "http:" && isLoopback(raw))) throw new Error(`Invalid ${name}: use an exact HTTPS origin (HTTP is local only)`);
+  return raw;
+}
+function parseManifest(value) {
+  const v = object(value);
+  const business = object(v.business);
+  const site = object(v.site);
+  if (v.schemaVersion !== 1) throw new Error("Unsupported admin contract version");
+  if (!Array.isArray(v.modules) || v.modules.length > 20) throw new Error("Invalid modules");
+  const modules = v.modules.map((x) => id(x, "module ID"));
+  if (new Set(modules).size !== modules.length) throw new Error("Duplicate module");
+  let backend;
+  if (v.backend !== void 0) {
+    const b = object(v.backend);
+    if (b.provider !== "vitris-harness") throw new Error("Unsupported backend provider");
+    const tenantId = text(b.tenantId, "tenant ID", 100);
+    if (!/^[a-zA-Z0-9_-]+$/.test(tenantId)) throw new Error("Invalid tenant ID");
+    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");
+  }
+  return {
+    schemaVersion: 1,
+    installationId: id(v.installationId, "installation ID"),
+    business: { name: text(business.name, "business name"), initials: text(business.initials, "initials", 3) },
+    site: { id: id(site.id, "site ID"), name: text(site.name, "site name"), origin: origin(site.origin, "website origin") },
+    adminOrigin: origin(v.adminOrigin, "admin origin"),
+    modules,
+    ...backend ? { backend } : {}
+  };
+}
+function validateModules(manifest, modules) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const module of modules) {
+    id(module.id, "module ID");
+    if (ids.has(module.id) || coreSections.includes(module.id)) throw new Error("Duplicate or reserved module ID");
+    if (!permissions.includes(module.permission)) throw new Error("Unknown module permission");
+    ids.add(module.id);
+  }
+  for (const enabled of manifest.modules) if (!ids.has(enabled)) throw new Error(`Module ${enabled} is not installed`);
+}
+export {
+  can,
+  contractVersion,
+  coreSections,
+  isLoopback,
+  parseManifest,
+  permissions,
+  roles,
+  validateModules,
+  workQueueModule
+};

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@tryvitris/website-admin-contracts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-alpha.1",
+  "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"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
+  },
+  "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"
+  }
+}