@checkstack/integration-common 0.0.4 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,140 @@
 # @checkstack/integration-common
 
+## 0.2.0
+
+### Minor Changes
+
+- 7a23261: ## TanStack Query Integration
+
+  Migrated all frontend components to use `usePluginClient` hook with TanStack Query integration, replacing the legacy `forPlugin()` pattern.
+
+  ### New Features
+
+  - **`usePluginClient` hook**: Provides type-safe access to plugin APIs with `.useQuery()` and `.useMutation()` methods
+  - **Automatic request deduplication**: Multiple components requesting the same data share a single network request
+  - **Built-in caching**: Configurable stale time and cache duration per query
+  - **Loading/error states**: TanStack Query provides `isLoading`, `error`, `isRefetching` states automatically
+  - **Background refetching**: Stale data is automatically refreshed when components mount
+
+  ### Contract Changes
+
+  All RPC contracts now require `operationType: "query"` or `operationType: "mutation"` metadata:
+
+  ```typescript
+  const getItems = proc()
+    .meta({ operationType: "query", access: [access.read] })
+    .output(z.array(itemSchema))
+    .query();
+
+  const createItem = proc()
+    .meta({ operationType: "mutation", access: [access.manage] })
+    .input(createItemSchema)
+    .output(itemSchema)
+    .mutation();
+  ```
+
+  ### Migration
+
+  ```typescript
+  // Before (forPlugin pattern)
+  const api = useApi(myPluginApiRef);
+  const [items, setItems] = useState<Item[]>([]);
+  useEffect(() => {
+    api.getItems().then(setItems);
+  }, [api]);
+
+  // After (usePluginClient pattern)
+  const client = usePluginClient(MyPluginApi);
+  const { data: items, isLoading } = client.getItems.useQuery({});
+  ```
+
+  ### Bug Fixes
+
+  - Fixed `rpc.test.ts` test setup for middleware type inference
+  - Fixed `SearchDialog` to use `setQuery` instead of deprecated `search` method
+  - Fixed null→undefined warnings in notification and queue frontends
+
+### Patch Changes
+
+- Updated dependencies [7a23261]
+  - @checkstack/common@0.3.0
+  - @checkstack/signal-common@0.1.1
+
+## 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 [f533141]
+  - @checkstack/common@0.2.0
+  - @checkstack/signal-common@0.1.0
+
 ## 0.0.4
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/integration-common",
-  "version": "0.0.4",
+  "version": "0.2.0",
   "type": "module",
   "exports": {
     ".": {

package/src/access.ts

@@ -0,0 +1,20 @@
+import { access } from "@checkstack/common";
+
+/**
+ * Access rules for the Integration plugin.
+ */
+export const integrationAccess = {
+  /**
+   * Manage webhook integrations and view delivery logs.
+   */
+  manage: access(
+    "integration",
+    "manage",
+    "Manage webhook integrations and view delivery logs"
+  ),
+};
+
+/**
+ * All access rules for registration with the plugin system.
+ */
+export const integrationAccessRules = [integrationAccess.manage];

package/src/index.ts

@@ -48,8 +48,8 @@ export {
 // are defined in @checkstack/integration-backend/provider-types.
 // Frontend code should only use the Zod schemas above for API contracts.
 
-// Permissions
-export * from "./permissions";
+// Access rules
+export * from "./access";
 
 // RPC Contract
 export * from "./rpc-contract";

package/src/rpc-contract.ts

@@ -1,11 +1,7 @@
-import { oc } from "@orpc/contract";
 import { z } from "zod";
-import { permissions } from "./permissions";
+import { integrationAccess } from "./access";
 import { pluginMetadata } from "./plugin-metadata";
-import {
-  createClientDefinition,
-  type ProcedureMetadata,
-} from "@checkstack/common";
+import { createClientDefinition, proc } from "@checkstack/common";
 import {
   WebhookSubscriptionSchema,
   CreateSubscriptionInputSchema,
@@ -23,9 +19,6 @@ import {
   EventPayloadSchemaOutputSchema,
 } from "./schemas";
 
-// Base builder with full metadata support (userType + permissions)
-const _base = oc.$meta<ProcedureMetadata>({});
-
 // Integration RPC Contract
 export const integrationContract = {
   // ==========================================================================
@@ -33,11 +26,11 @@ export const integrationContract = {
   // ==========================================================================
 
   /** List all webhook subscriptions */
-  listSubscriptions: _base
-    .meta({
-      userType: "authenticated",
-      permissions: [permissions.integrationManage.id],
-    })
+  listSubscriptions: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [integrationAccess.manage],
+  })
     .input(
       z.object({
         page: z.number().min(1).default(1),
@@ -55,47 +48,47 @@ export const integrationContract = {
     ),
 
   /** Get a single subscription by ID */
-  getSubscription: _base
-    .meta({
-      userType: "authenticated",
-      permissions: [permissions.integrationManage.id],
-    })
+  getSubscription: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [integrationAccess.manage],
+  })
     .input(z.object({ id: z.string() }))
     .output(WebhookSubscriptionSchema),
 
   /** Create a new webhook subscription */
-  createSubscription: _base
-    .meta({
-      userType: "authenticated",
-      permissions: [permissions.integrationManage.id],
-    })
+  createSubscription: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [integrationAccess.manage],
+  })
     .input(CreateSubscriptionInputSchema)
     .output(WebhookSubscriptionSchema),
 
   /** Update an existing subscription */
-  updateSubscription: _base
-    .meta({
-      userType: "authenticated",
-      permissions: [permissions.integrationManage.id],
-    })
+  updateSubscription: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [integrationAccess.manage],
+  })
     .input(UpdateSubscriptionInputSchema)
     .output(WebhookSubscriptionSchema),
 
   /** Delete a subscription */
-  deleteSubscription: _base
-    .meta({
-      userType: "authenticated",
-      permissions: [permissions.integrationManage.id],
-    })
+  deleteSubscription: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [integrationAccess.manage],
+  })
     .input(z.object({ id: z.string() }))
     .output(z.object({ success: z.boolean() })),
 
   /** Toggle subscription enabled state */
-  toggleSubscription: _base
-    .meta({
-      userType: "authenticated",
-      permissions: [permissions.integrationManage.id],
-    })
+  toggleSubscription: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [integrationAccess.manage],
+  })
     .input(z.object({ id: z.string(), enabled: z.boolean() }))
     .output(z.object({ success: z.boolean() })),
 
@@ -104,19 +97,18 @@ export const integrationContract = {
   // ==========================================================================
 
   /** List all registered integration providers */
-  listProviders: _base
-    .meta({
-      userType: "authenticated",
-      permissions: [permissions.integrationManage.id],
-    })
-    .output(z.array(IntegrationProviderInfoSchema)),
+  listProviders: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [integrationAccess.manage],
+  }).output(z.array(IntegrationProviderInfoSchema)),
 
   /** Test a provider connection with given config */
-  testProviderConnection: _base
-    .meta({
-      userType: "authenticated",
-      permissions: [permissions.integrationManage.id],
-    })
+  testProviderConnection: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [integrationAccess.manage],
+  })
     .input(
       z.object({
         providerId: z.string(),
@@ -131,65 +123,65 @@ export const integrationContract = {
   // ==========================================================================
 
   /** List all connections for a provider */
-  listConnections: _base
-    .meta({
-      userType: "authenticated",
-      permissions: [permissions.integrationManage.id],
-    })
+  listConnections: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [integrationAccess.manage],
+  })
     .input(z.object({ providerId: z.string() }))
     .output(z.array(ProviderConnectionRedactedSchema)),
 
   /** Get a single connection (redacted) */
-  getConnection: _base
-    .meta({
-      userType: "authenticated",
-      permissions: [permissions.integrationManage.id],
-    })
+  getConnection: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [integrationAccess.manage],
+  })
     .input(z.object({ connectionId: z.string() }))
     .output(ProviderConnectionRedactedSchema),
 
   /** Create a new provider connection */
-  createConnection: _base
-    .meta({
-      userType: "authenticated",
-      permissions: [permissions.integrationManage.id],
-    })
+  createConnection: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [integrationAccess.manage],
+  })
     .input(CreateConnectionInputSchema)
     .output(ProviderConnectionRedactedSchema),
 
   /** Update a provider connection */
-  updateConnection: _base
-    .meta({
-      userType: "authenticated",
-      permissions: [permissions.integrationManage.id],
-    })
+  updateConnection: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [integrationAccess.manage],
+  })
     .input(UpdateConnectionInputSchema)
     .output(ProviderConnectionRedactedSchema),
 
   /** Delete a provider connection */
-  deleteConnection: _base
-    .meta({
-      userType: "authenticated",
-      permissions: [permissions.integrationManage.id],
-    })
+  deleteConnection: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [integrationAccess.manage],
+  })
     .input(z.object({ connectionId: z.string() }))
     .output(z.object({ success: z.boolean() })),
 
   /** Test a saved connection */
-  testConnection: _base
-    .meta({
-      userType: "authenticated",
-      permissions: [permissions.integrationManage.id],
-    })
+  testConnection: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [integrationAccess.manage],
+  })
     .input(z.object({ connectionId: z.string() }))
     .output(TestConnectionResultSchema),
 
   /** Get dynamic options for cascading dropdowns */
-  getConnectionOptions: _base
-    .meta({
-      userType: "authenticated",
-      permissions: [permissions.integrationManage.id],
-    })
+  getConnectionOptions: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [integrationAccess.manage],
+  })
     .input(GetConnectionOptionsInputSchema)
     .output(z.array(ConnectionOptionSchema)),
 
@@ -198,34 +190,32 @@ export const integrationContract = {
   // ==========================================================================
 
   /** List all registered integration events */
-  listEventTypes: _base
-    .meta({
-      userType: "authenticated",
-      permissions: [permissions.integrationManage.id],
-    })
-    .output(z.array(IntegrationEventInfoSchema)),
+  listEventTypes: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [integrationAccess.manage],
+  }).output(z.array(IntegrationEventInfoSchema)),
 
   /** Get events grouped by category */
-  getEventsByCategory: _base
-    .meta({
-      userType: "authenticated",
-      permissions: [permissions.integrationManage.id],
-    })
-    .output(
-      z.array(
-        z.object({
-          category: z.string(),
-          events: z.array(IntegrationEventInfoSchema),
-        })
-      )
-    ),
+  getEventsByCategory: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [integrationAccess.manage],
+  }).output(
+    z.array(
+      z.object({
+        category: z.string(),
+        events: z.array(IntegrationEventInfoSchema),
+      })
+    )
+  ),
 
   /** Get payload schema for a specific event with flattened property list for template hints */
-  getEventPayloadSchema: _base
-    .meta({
-      userType: "authenticated",
-      permissions: [permissions.integrationManage.id],
-    })
+  getEventPayloadSchema: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [integrationAccess.manage],
+  })
     .input(z.object({ eventId: z.string() }))
     .output(EventPayloadSchemaOutputSchema),
 
@@ -234,11 +224,11 @@ export const integrationContract = {
   // ==========================================================================
 
   /** Get delivery logs with filtering */
-  getDeliveryLogs: _base
-    .meta({
-      userType: "authenticated",
-      permissions: [permissions.integrationManage.id],
-    })
+  getDeliveryLogs: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [integrationAccess.manage],
+  })
     .input(DeliveryLogQueryInputSchema)
     .output(
       z.object({
@@ -248,29 +238,29 @@ export const integrationContract = {
     ),
 
   /** Get a single delivery log entry */
-  getDeliveryLog: _base
-    .meta({
-      userType: "authenticated",
-      permissions: [permissions.integrationManage.id],
-    })
+  getDeliveryLog: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [integrationAccess.manage],
+  })
     .input(z.object({ id: z.string() }))
     .output(DeliveryLogSchema),
 
   /** Retry a failed delivery */
-  retryDelivery: _base
-    .meta({
-      userType: "authenticated",
-      permissions: [permissions.integrationManage.id],
-    })
+  retryDelivery: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [integrationAccess.manage],
+  })
     .input(z.object({ logId: z.string() }))
     .output(z.object({ success: z.boolean(), message: z.string().optional() })),
 
   /** Get delivery statistics for dashboard */
-  getDeliveryStats: _base
-    .meta({
-      userType: "authenticated",
-      permissions: [permissions.integrationManage.id],
-    })
+  getDeliveryStats: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [integrationAccess.manage],
+  })
     .input(
       z.object({
         /** Time range in hours (default: 24) */

package/src/permissions.ts

@@ -1,12 +0,0 @@
-import { createPermission } from "@checkstack/common";
-
-export const permissions = {
-  /** Manage webhook integrations and view delivery logs */
-  integrationManage: createPermission(
-    "integration",
-    "manage",
-    "Manage webhook integrations and view delivery logs"
-  ),
-};
-
-export const permissionList = Object.values(permissions);