feat: add documentation to access response

api/libraries/auth/access.ts

@@ -4,12 +4,81 @@ import { Resource } from "./resources.ts";
 
 export function access(principal: Principal) {
   return {
+    /**
+     * Check if a principal is allowed to perform an action on a resource.
+     *
+     * @param resource - Resource which we are validating.
+     * @param action   - Action which we are validating.
+     *
+     * @example
+     *
+     * await access.isAllowed(
+     *   {
+     *     kind: "document",
+     *     id: "1",
+     *     attr: { owner: "user@example.com" },
+     *   },
+     *   "view"
+     * ); // => true
+     */
     isAllowed(resource: Resource, action: string) {
       return cerbos.isAllowed({ principal, resource, action });
     },
+
+    /**
+     * Check a principal's permissions on a resource.
+     *
+     * @param resource - Resource which we are validating.
+     * @param actions  - Actions which we are validating.
+     *
+     * @example
+     *
+     * const decision = await access.checkResource(
+     *   {
+     *     kind: "document",
+     *     id: "1",
+     *     attr: { owner: "user@example.com" },
+     *   },
+     *   ["view", "edit"],
+     * );
+     *
+     * decision.isAllowed("view"); // => true
+     */
     checkResource(resource: Resource, actions: string[]) {
       return cerbos.checkResource({ principal, resource, actions });
     },
+
+    /**
+     * Check a principal's permissions on a set of resources.
+     *
+     * @param resources - Resources which we are validating.
+     *
+     * @example
+     *
+     * const decision = await access.checkResources([
+     *   {
+     *     resource: {
+     *       kind: "document",
+     *       id: "1",
+     *       attr: { owner: "user@example.com" },
+     *     },
+     *     actions: ["view", "edit"],
+     *   },
+     *   {
+     *     resource: {
+     *       kind: "image",
+     *       id: "1",
+     *       attr: { owner: "user@example.com" },
+     *     },
+     *     actions: ["delete"],
+     *   },
+     * ]);
+     *
+     * decision.isAllowed({
+     *   resource: { kind: "document", id: "1" },
+     *   action: "view",
+     * }); // => true
+     */
     checkResources(resources: { resource: Resource; actions: string[] }[]) {
       return cerbos.checkResources({ principal, resources });
     },

api/libraries/auth/resources.ts

@@ -3,7 +3,7 @@ import { ResourceRegistry } from "@valkyr/auth";
 export const resources = new ResourceRegistry([
   {
     kind: "account",
-    attributes: {},
+    attr: {},
   },
 ] as const);
 

api/package.json

@@ -5,7 +5,6 @@
     "migrate": "deno run --allow-all .tasks/migrate.ts"
   },
   "dependencies": {
-    "@cerbos/grpc": "0.23.1",
     "@cerbos/http": "0.23.1",
     "@felix/bcrypt": "npm:@jsr/felix__bcrypt@1.0.5",
     "@spec/modules": "workspace:*",
@@ -15,7 +14,7 @@
     "@std/dotenv": "npm:@jsr/std__dotenv@0.225.5",
     "@std/fs": "npm:@jsr/std__fs@1.0.19",
     "@std/path": "npm:@jsr/std__path@1.1.2",
-    "@valkyr/auth": "npm:@jsr/valkyr__auth@2.1.3",
+    "@valkyr/auth": "npm:@jsr/valkyr__auth@2.1.4",
     "@valkyr/event-store": "npm:@jsr/valkyr__event-store@2",
     "@valkyr/inverse": "npm:@jsr/valkyr__inverse@1.0.1",
     "@valkyr/json-rpc": "npm:@jsr/valkyr__json-rpc@1.1.0",