@checkstack/common 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # @checkstack/common
 
+## 0.3.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
+
 ## 0.2.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/common",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/access-utils.ts

@@ -26,6 +26,13 @@ export interface InstanceAccessConfig {
    * Example: "systems" for response { systems: [...] }
    */
   listKey?: string;
+
+  /**
+   * For bulk record endpoints: key in response containing a Record<resourceId, data>.
+   * When set, post-filters the record keys based on team grants.
+   * Example: "statuses" for response { statuses: { [systemId]: {...} } }
+   */
+  recordKey?: string;
 }
 
 /**
@@ -154,11 +161,13 @@ export function access(
   options?: {
     idParam?: string;
     listKey?: string;
+    recordKey?: string;
     isDefault?: boolean;
     isPublic?: boolean;
   }
 ): AccessRule {
-  const hasInstanceAccess = options?.idParam || options?.listKey;
+  const hasInstanceAccess =
+    options?.idParam || options?.listKey || options?.recordKey;
 
   return {
     id: `${resource}.${level}`,
@@ -171,6 +180,7 @@ export function access(
       ? {
           idParam: options?.idParam,
           listKey: options?.listKey,
+          recordKey: options?.recordKey,
         }
       : undefined,
   };
@@ -208,6 +218,7 @@ export function accessPair(
   options?: {
     idParam?: string;
     listKey?: string;
+    recordKey?: string;
     readIsDefault?: boolean;
     readIsPublic?: boolean;
   }
@@ -216,6 +227,7 @@ export function accessPair(
     read: access(resource, "read", descriptions.read, {
       idParam: options?.idParam,
       listKey: options?.listKey,
+      recordKey: options?.recordKey,
       isDefault: options?.readIsDefault,
       isPublic: options?.readIsPublic,
     }),

package/src/client-definition.ts

@@ -1,23 +1,26 @@
 import type { ContractRouterClient, AnyContractRouter } from "@orpc/contract";
 import type { PluginMetadata } from "./plugin-metadata";
+import type { ProcedureMetadata } from "./types";
 
 /**
- * A client definition that bundles an RPC contract type with its plugin metadata.
- * Used for type-safe plugin RPC consumption.
+ * A client definition that bundles an RPC contract with its plugin metadata.
+ * Used for type-safe plugin RPC consumption and TanStack Query integration.
  *
  * @example
  * ```typescript
  * // Define in auth-common
  * export const AuthApi = createClientDefinition(authContract, pluginMetadata);
  *
- * // Use in frontend/backend
- * const authClient = rpcApi.forPlugin(AuthApi);  // Fully typed!
+ * // Use in frontend with TanStack Query hooks
+ * const authClient = usePluginClient(AuthApi);
+ * const { data } = authClient.getUser.useQuery({ id });
  * ```
  */
 export interface ClientDefinition<
   TContract extends AnyContractRouter = AnyContractRouter
 > {
   readonly pluginId: string;
+  readonly contract: TContract;
   /**
    * Phantom type for contract type inference.
    * This property doesn't exist at runtime - it's only used by TypeScript
@@ -38,15 +41,37 @@ export interface ClientDefinition<
 export type InferClient<T extends ClientDefinition> =
   T extends ClientDefinition<infer C> ? ContractRouterClient<C> : never;
 
+/**
+ * Type helper to extract operationType from a procedure's metadata.
+ */
+export type ExtractOperationType<TProcedure> = TProcedure extends {
+  "~orpc": { meta: { operationType: infer T } };
+}
+  ? T
+  : "query"; // Default to query if not specified
+
+/**
+ * Extracts the contract's metadata for a specific procedure path.
+ */
+export type InferProcedureMetadata<
+  TContract extends AnyContractRouter,
+  TPath extends keyof TContract
+> = TContract[TPath] extends { "~orpc": { meta: infer M } }
+  ? M extends ProcedureMetadata
+    ? M
+    : never
+  : never;
+
 /**
  * Create a typed client definition for a plugin's RPC contract.
  *
- * This bundles the contract type with the plugin metadata, enabling type-safe
- * forPlugin() calls without manual type annotations.
+ * This bundles the contract with the plugin metadata, enabling type-safe
+ * TanStack Query hooks that expose only .useQuery() or .useMutation() based
+ * on the procedure's operationType.
  *
- * @param _contract - The RPC contract object (used only for type inference)
+ * @param contract - The RPC contract object
  * @param metadata - The plugin metadata from the plugin's plugin-metadata.ts
- * @returns A ClientDefinition object that can be passed to forPlugin()
+ * @returns A ClientDefinition object that can be passed to usePluginClient()
  *
  * @example
  * ```typescript
@@ -56,16 +81,18 @@ export type InferClient<T extends ClientDefinition> =
  *
  * export const AuthApi = createClientDefinition(authContract, pluginMetadata);
  *
- * // In consumer (frontend or backend)
- * const authClient = rpcApi.forPlugin(AuthApi);
- * await authClient.getUsers(); // Fully typed!
+ * // In consumer (frontend)
+ * const authClient = usePluginClient(AuthApi);
+ * const { data } = authClient.getUsers.useQuery({}); // Type-safe!
+ * const mutation = authClient.deleteUser.useMutation(); // Type-safe!
  * ```
  */
 export function createClientDefinition<TContract extends AnyContractRouter>(
-  _contract: TContract,
+  contract: TContract,
   metadata: PluginMetadata
 ): ClientDefinition<TContract> {
   return {
     pluginId: metadata.pluginId,
+    contract,
   } as ClientDefinition<TContract>;
 }

package/src/index.ts

@@ -8,3 +8,4 @@ export * from "./icons";
 export * from "./transport-client";
 export * from "./json-schema";
 export * from "./chart-types";
+export * from "./procedure-builder";

package/src/procedure-builder.ts

@@ -0,0 +1,52 @@
+import { oc } from "@orpc/contract";
+import type { ContractProcedureBuilder } from "@orpc/contract";
+import type { Schema, ErrorMap } from "@orpc/contract";
+import type { ProcedureMetadata } from "./types";
+
+/**
+ * Return type of proc() that preserves the operationType in the type system.
+ * This extends ContractProcedureBuilder but with our specific ProcedureMetadata.
+ */
+export type TypedContractProcedureBuilder<TMeta extends ProcedureMetadata> =
+  ContractProcedureBuilder<
+    Schema<unknown, unknown>,
+    Schema<unknown, unknown>,
+    ErrorMap,
+    TMeta
+  >;
+
+/**
+ * Creates an oRPC procedure builder with required metadata.
+ * All procedures MUST provide userType, operationType, and access.
+ *
+ * The return type preserves the operationType in the generic parameter,
+ * enabling type-safe hook selection (useQuery vs useMutation) in usePluginClient.
+ *
+ * @example
+ * ```typescript
+ * import { proc } from "@checkstack/common";
+ *
+ * export const myContract = {
+ *   // Returns TypedContractProcedureBuilder<{ operationType: "query", ... }>
+ *   getItems: proc({
+ *     operationType: "query",
+ *     userType: "public",
+ *     access: [myAccess.items.read],
+ *   }).output(z.array(ItemSchema)),
+ *
+ *   // Returns TypedContractProcedureBuilder<{ operationType: "mutation", ... }>
+ *   createItem: proc({
+ *     operationType: "mutation",
+ *     userType: "authenticated",
+ *     access: [myAccess.items.manage],
+ *   })
+ *     .input(CreateItemSchema)
+ *     .output(ItemSchema),
+ * };
+ * ```
+ */
+export function proc<TMeta extends ProcedureMetadata>(
+  meta: TMeta
+): TypedContractProcedureBuilder<TMeta> {
+  return oc.$meta<TMeta>(meta) as TypedContractProcedureBuilder<TMeta>;
+}

package/src/types.ts

@@ -42,7 +42,16 @@ export interface ProcedureMetadata {
    * - "service": Only services (backend-to-backend)
    * - "authenticated": Either users or services, but must be authenticated (default)
    */
-  userType?: "anonymous" | "public" | "user" | "service" | "authenticated";
+  userType: "anonymous" | "public" | "user" | "service" | "authenticated";
+
+  /**
+   * Operation type for TanStack Query integration.
+   * - "query": Read-only operation, uses useQuery hook
+   * - "mutation": Write operation, uses useMutation hook
+   *
+   * This is REQUIRED for all procedures to enable type-safe frontend hooks.
+   */
+  operationType: "query" | "mutation";
 
   /**
    * Unified access rules combining access rules and resource-level access control.
@@ -57,5 +66,5 @@ export interface ProcedureMetadata {
    * access: [catalogAccess.groups.manage, catalogAccess.systems.manage] // Both required
    * ```
    */
-  access?: AccessRule[];
+  access: AccessRule[];
 }