@checkstack/notification-backend 0.0.4 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,88 @@
 # @checkstack/notification-backend
 
+## 0.1.0
+
+### Minor Changes
+
+- 9faec1f: # Unified AccessRule Terminology Refactoring
+
+  This release completes a comprehensive terminology refactoring from "permission" to "accessRule" across the entire codebase, establishing a consistent and modern access control vocabulary.
+
+  ## Changes
+
+  ### Core Infrastructure (`@checkstack/common`)
+
+  - Introduced `AccessRule` interface as the primary access control type
+  - Added `accessPair()` helper for creating read/manage access rule pairs
+  - Added `access()` builder for individual access rules
+  - Replaced `Permission` type with `AccessRule` throughout
+
+  ### API Changes
+
+  - `env.registerPermissions()` → `env.registerAccessRules()`
+  - `meta.permissions` → `meta.access` in RPC contracts
+  - `usePermission()` → `useAccess()` in frontend hooks
+  - Route `permission:` field → `accessRule:` field
+
+  ### UI Changes
+
+  - "Roles & Permissions" tab → "Roles & Access Rules"
+  - "You don't have permission..." → "You don't have access..."
+  - All permission-related UI text updated
+
+  ### Documentation & Templates
+
+  - Updated 18 documentation files with AccessRule terminology
+  - Updated 7 scaffolding templates with `accessPair()` pattern
+  - All code examples use new AccessRule API
+
+  ## Migration Guide
+
+  ### Backend Plugins
+
+  ```diff
+  - import { permissionList } from "./permissions";
+  - env.registerPermissions(permissionList);
+  + import { accessRules } from "./access";
+  + env.registerAccessRules(accessRules);
+  ```
+
+  ### RPC Contracts
+
+  ```diff
+  - .meta({ userType: "user", permissions: [permissions.read.id] })
+  + .meta({ userType: "user", access: [access.read] })
+  ```
+
+  ### Frontend Hooks
+
+  ```diff
+  - const canRead = accessApi.usePermission(permissions.read.id);
+  + const canRead = accessApi.useAccess(access.read);
+  ```
+
+  ### Routes
+
+  ```diff
+  - permission: permissions.entityRead.id,
+  + accessRule: access.read,
+  ```
+
+### Patch Changes
+
+- Updated dependencies [9faec1f]
+- Updated dependencies [827b286]
+- Updated dependencies [95eeec7]
+- Updated dependencies [f533141]
+- Updated dependencies [aa4a8ab]
+  - @checkstack/auth-backend@0.2.0
+  - @checkstack/auth-common@0.2.0
+  - @checkstack/backend-api@0.3.0
+  - @checkstack/common@0.2.0
+  - @checkstack/notification-common@0.1.0
+  - @checkstack/signal-common@0.1.0
+  - @checkstack/queue-api@0.0.5
+
 ## 0.0.4
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/notification-backend",
-  "version": "0.0.4",
+  "version": "0.1.0",
   "type": "module",
   "main": "src/index.ts",
   "checkstack": {

package/src/index.ts

@@ -8,11 +8,15 @@ import {
   type NotificationStrategyRegistry,
 } from "@checkstack/backend-api";
 import {
-  permissionList,
+  notificationAccessRules,
   pluginMetadata,
   notificationContract,
 } from "@checkstack/notification-common";
-import type { PluginMetadata } from "@checkstack/common";
+import {
+  access,
+  type PluginMetadata,
+  type AccessRule,
+} from "@checkstack/common";
 import { eq } from "drizzle-orm";
 
 import * as schema from "./schema";
@@ -49,9 +53,8 @@ export const notificationStrategyExtensionPoint =
  * Create a new notification strategy registry instance.
  */
 function createNotificationStrategyRegistry(): NotificationStrategyRegistry & {
-  getNewPermissions: () => Array<{
-    id: string;
-    description: string;
+  getNewAccessRules: () => Array<{
+    accessRule: AccessRule;
     ownerPluginId: string;
   }>;
 } {
@@ -59,9 +62,8 @@ function createNotificationStrategyRegistry(): NotificationStrategyRegistry & {
     string,
     RegisteredNotificationStrategy<unknown, unknown, unknown>
   >();
-  const newPermissions: Array<{
-    id: string;
-    description: string;
+  const newAccessRules: Array<{
+    accessRule: AccessRule;
     ownerPluginId: string;
   }> = [];
 
@@ -71,7 +73,7 @@ function createNotificationStrategyRegistry(): NotificationStrategyRegistry & {
       metadata: PluginMetadata
     ): void {
       const qualifiedId = `${metadata.pluginId}.${strategy.id}`;
-      const permissionId = `${metadata.pluginId}.strategy.${strategy.id}.use`;
+      const accessRuleId = `${metadata.pluginId}.strategy.${strategy.id}.use`;
 
       // Cast to unknown for storage - registry stores heterogeneous strategies
       const registered: RegisteredNotificationStrategy<
@@ -82,15 +84,18 @@ function createNotificationStrategyRegistry(): NotificationStrategyRegistry & {
         ...(strategy as NotificationStrategy<unknown, unknown, unknown>),
         qualifiedId,
         ownerPluginId: metadata.pluginId,
-        permissionId,
+        accessRuleId,
       };
 
       strategies.set(qualifiedId, registered);
 
-      // Track new permission for later registration
-      newPermissions.push({
-        id: permissionId,
-        description: `Use ${strategy.displayName} notification channel`,
+      // Track new access rule for later registration
+      newAccessRules.push({
+        accessRule: access(
+          `strategy.${strategy.id}`,
+          "manage",
+          `Use ${strategy.displayName} notification channel`
+        ),
         ownerPluginId: metadata.pluginId,
       });
     },
@@ -110,15 +115,15 @@ function createNotificationStrategyRegistry(): NotificationStrategyRegistry & {
     },
 
     getStrategiesForUser(
-      userPermissions: Set<string>
+      userAccessRules: Set<string>
     ): RegisteredNotificationStrategy<unknown, unknown, unknown>[] {
       return [...strategies.values()].filter((s) =>
-        userPermissions.has(s.permissionId)
+        userAccessRules.has(s.accessRuleId)
       );
     },
 
-    getNewPermissions() {
-      return newPermissions;
+    getNewAccessRules() {
+      return newAccessRules;
     },
   };
 }
@@ -134,8 +139,8 @@ export default createBackendPlugin({
     // Create the strategy registry
     const strategyRegistry = createNotificationStrategyRegistry();
 
-    // Register static permissions
-    env.registerPermissions(permissionList);
+    // Register static access rules
+    env.registerAccessRules(notificationAccessRules);
 
     // Register the extension point
     env.registerExtensionPoint(notificationStrategyExtensionPoint, {
@@ -214,32 +219,26 @@ export default createBackendPlugin({
             .join(", ")}`
         );
 
-        // Emit dynamic permissions for strategies
-        const newPermissions = strategyRegistry.getNewPermissions();
-        if (newPermissions.length > 0) {
+        // Emit dynamic access rules for strategies
+        const newAccessRules = strategyRegistry.getNewAccessRules();
+        if (newAccessRules.length > 0) {
           logger.debug(
-            `🔐 Registering ${newPermissions.length} dynamic strategy permissions`
+            `🔐 Registering ${newAccessRules.length} dynamic strategy access rules`
           );
 
-          // Group permissions by owner plugin and emit hooks
-          const byPlugin = new Map<
-            string,
-            Array<{ id: string; description: string }>
-          >();
-          for (const perm of newPermissions) {
-            const existing = byPlugin.get(perm.ownerPluginId) ?? [];
-            existing.push({ id: perm.id, description: perm.description });
-            byPlugin.set(perm.ownerPluginId, existing);
+          // Group access rules by owner plugin and emit hooks
+          const byPlugin = new Map<string, AccessRule[]>();
+          for (const item of newAccessRules) {
+            const existing = byPlugin.get(item.ownerPluginId) ?? [];
+            existing.push(item.accessRule);
+            byPlugin.set(item.ownerPluginId, existing);
           }
 
-          // Emit permissions registered hook for each plugin's permissions
-          for (const [ownerPluginId, permissions] of byPlugin) {
-            await emitHook(coreHooks.permissionsRegistered, {
+          // Emit access rules registered hook for each plugin's rules
+          for (const [ownerPluginId, accessRules] of byPlugin) {
+            await emitHook(coreHooks.accessRulesRegistered, {
               pluginId: ownerPluginId,
-              permissions: permissions.map((p) => ({
-                id: p.id,
-                description: p.description,
-              })),
+              accessRules,
             });
           }
         }

package/src/router.ts

@@ -85,8 +85,8 @@ function resolveContact({
 /**
  * Creates the notification router using contract-based implementation.
  *
- * Auth and permissions are automatically enforced via autoAuthMiddleware
- * based on the contract's meta.userType and meta.permissions.
+ * Auth and access rules are automatically enforced via autoAuthMiddleware
+ * based on the contract's meta.userType and meta.access.
  */
 export const createNotificationRouter = (
   database: NodePgDatabase<typeof schema>,
@@ -260,7 +260,7 @@ export const createNotificationRouter = (
   return os.router({
     // ==========================================================================
     // USER NOTIFICATION ENDPOINTS
-    // Contract meta: userType: "user", permissions: [notificationRead]
+    // Contract meta: userType: "user", accessRules: [notificationRead]
     // ==========================================================================
 
     getNotifications: os.getNotifications.handler(
@@ -364,7 +364,7 @@ export const createNotificationRouter = (
 
     // ==========================================================================
     // ADMIN SETTINGS ENDPOINTS
-    // Contract meta: userType: "user", permissions: [notificationAdmin]
+    // Contract meta: userType: "user", accessRules: [notificationAdmin]
     // ==========================================================================
 
     getRetentionSchema: os.getRetentionSchema.handler(() => {

package/src/strategy-service.test.ts

@@ -85,7 +85,7 @@ function createMockRegistry(): NotificationStrategyRegistry & {
     id: "smtp",
     qualifiedId: "test-plugin.smtp",
     ownerPluginId: "test-plugin",
-    permissionId: "test-plugin.strategy.smtp.use",
+    accessRuleId: "test-plugin.strategy.smtp.use",
     displayName: "SMTP Email",
     description: "Send emails via SMTP",
     contactResolution: { type: "auth-email" },
@@ -97,7 +97,7 @@ function createMockRegistry(): NotificationStrategyRegistry & {
     id: "sms",
     qualifiedId: "test-plugin.sms",
     ownerPluginId: "test-plugin",
-    permissionId: "test-plugin.strategy.sms.use",
+    accessRuleId: "test-plugin.strategy.sms.use",
     displayName: "SMS",
     description: "Send SMS messages",
     contactResolution: { type: "user-config", field: "phoneNumber" },