pepr 0.1.44 → 0.1.45

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import k8s from "@kubernetes/client-node";
 import utils from "ramda";
 import { Capability } from "./src/lib/capability";
 import { fetch, fetchRaw } from "./src/lib/fetch";
-import { a } from "./src/lib/k8s";
+import { RegisterKind, a } from "./src/lib/k8s";
 import Log from "./src/lib/logger";
 import { PeprModule } from "./src/lib/module";
 import { PeprRequest } from "./src/lib/request";
@@ -10,4 +10,4 @@ import type * as KubernetesClientNode from "@kubernetes/client-node";
 import type * as RamdaUtils from "ramda";
 export { a, 
 /** PeprModule is used to setup a complete Pepr Module: `new PeprModule(cfg, {...capabilities})` */
-PeprModule, PeprRequest, Capability, Log, utils, fetch, fetchRaw, k8s, RamdaUtils, KubernetesClientNode, };
+PeprModule, PeprRequest, RegisterKind, Capability, Log, utils, fetch, fetchRaw, k8s, RamdaUtils, KubernetesClientNode, };

package/dist/index.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.k8s = exports.fetchRaw = exports.fetch = exports.utils = exports.Log = exports.Capability = exports.PeprRequest = exports.PeprModule = exports.a = void 0;
+exports.k8s = exports.fetchRaw = exports.fetch = exports.utils = exports.Log = exports.Capability = exports.RegisterKind = exports.PeprRequest = exports.PeprModule = exports.a = void 0;
 const client_node_1 = __importDefault(require("@kubernetes/client-node"));
 exports.k8s = client_node_1.default;
 const ramda_1 = __importDefault(require("ramda"));
@@ -14,6 +14,7 @@ const fetch_1 = require("./src/lib/fetch");
 Object.defineProperty(exports, "fetch", { enumerable: true, get: function () { return fetch_1.fetch; } });
 Object.defineProperty(exports, "fetchRaw", { enumerable: true, get: function () { return fetch_1.fetchRaw; } });
 const k8s_1 = require("./src/lib/k8s");
+Object.defineProperty(exports, "RegisterKind", { enumerable: true, get: function () { return k8s_1.RegisterKind; } });
 Object.defineProperty(exports, "a", { enumerable: true, get: function () { return k8s_1.a; } });
 const logger_1 = __importDefault(require("./src/lib/logger"));
 exports.Log = logger_1.default;

package/dist/package.json

@@ -9,7 +9,7 @@
     "engines": {
         "node": ">=18.0.0"
     },
-    "version": "0.1.44",
+    "version": "0.1.45",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "pepr": {

package/dist/src/cli/init/templates/data.json

@@ -1 +1 @@
-{ "gitignore": "# Ignore node_modules and Pepr build artifacts\nnode_modules\ndist\ninsecure*\n", "readme": "# Pepr Module\n\nThis is a Pepr Module. [Pepr](https://github.com/defenseunicorns/pepr) is a Kubernetes transformation system\nwritten in Typescript.\n\nThe `capabilities` directory contains all the capabilities for this module. By default,\na capability is a single typescript file in the format of `capability-name.ts` that is\nimported in the root `pepr.ts` file as `import { HelloPepr } from \"./capabilities/hello-pepr\";`.\nBecause this is typescript, you can organize this however you choose, e.g. creating a sub-folder\nper-capability or common logic in shared files or folders.\n\nExample Structure:\n\n```\nModule Root\n├── package.json\n├── pepr.ts\n└── capabilities\n    ├── example-one.ts\n    ├── example-three.ts\n    └── example-two.ts\n```\n", "peprTS": "import { PeprModule } from \"pepr\";\nimport { HelloPepr } from \"./capabilities/hello-pepr\";\nimport cfg from \"./package.json\";\n\n/**\n * This is the main entrypoint for the Pepr module. It is the file that is run when the module is started.\n * This is where you register your configurations and capabilities with the module.\n */\nnew PeprModule(cfg, [\n  // \"HelloPepr\" is a demo capability that is included with Pepr. You can remove it if you want.\n  HelloPepr,\n\n  // Your additional capabilities go here\n]);\n", "helloPeprTS": "import { Capability, PeprRequest, a, fetch } from \"pepr\";\n\n/**\n *  The HelloPepr Capability is an example capability to demonstrate some general concepts of Pepr.\n *  To test this capability you can run `pepr dev` or `npm start` and then run the following command:\n *  `kubectl apply -f capabilities/hello-pepr.samples.yaml`\n */\nexport const HelloPepr = new Capability({\n  name: \"hello-pepr\",\n  description: \"A simple example capability to show how things work.\",\n  namespaces: [\"pepr-demo\"],\n});\n\n// Use the 'When' function to create a new Capability Action\nconst { When } = HelloPepr;\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   CAPABILITY ACTION                                               *\n * ---------------------------------------------------------------------------------------------------\n *\n * This Capability Action removes the label `remove-me` when a Namespace is created.\n * Note we don't need to specify the namespace here, because we've already specified\n * it in the Capability definition above.\n */\nWhen(a.Namespace)\n  .IsCreated()\n  .Then(ns => ns.RemoveLabel(\"remove-me\"));\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   CAPABILITY ACTION                                               *\n * ---------------------------------------------------------------------------------------------------\n *\n * This is a single Capability Action. They can be in the same file or put imported from other files.\n * In this exmaple, when a ConfigMap is created with the name `example-1`, then add a label and annotation.\n *\n * Equivelant to manually running:\n * `kubectl label configmap example-1 pepr=was-here`\n * `kubectl annotate configmap example-1 pepr.dev=annotations-work-too`\n */\nWhen(a.ConfigMap)\n  .IsCreated()\n  .WithName(\"example-1\")\n  .Then(request =>\n    request\n      .SetLabel(\"pepr\", \"was-here\")\n      .SetAnnotation(\"pepr.dev\", \"annotations-work-too\")\n  );\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   CAPABILITY ACTION                                               *\n * ---------------------------------------------------------------------------------------------------\n *\n * This Capabiility Action does the exact same changes for example-2, except this time it uses\n * the `.ThenSet()` feature. You can stack multiple `.Then()` calls, but only a single `.ThenSet()`\n */\nWhen(a.ConfigMap)\n  .IsCreated()\n  .WithName(\"example-2\")\n  .ThenSet({\n    metadata: {\n      labels: {\n        pepr: \"was-here\",\n      },\n      annotations: {\n        \"pepr.dev\": \"annotations-work-too\",\n      },\n    },\n  });\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   CAPABILITY ACTION                                               *\n * ---------------------------------------------------------------------------------------------------\n *\n * This Capability Action combines different styles. Unlike the previous actions, this one will look\n * for any ConfigMap in the `pepr-demo` namespace that has the label `change=by-label` during either\n * CREATE or UPDATE. Note that all conditions added such as `WithName()`, `WithLabel()`, `InNamespace()`,\n * are ANDs so all conditions must be true for the request to be procssed.\n */\nWhen(a.ConfigMap)\n  .IsCreatedOrUpdated()\n  .WithLabel(\"change\", \"by-label\")\n  .Then(request => {\n    // The K8s object e are going to mutate\n    const cm = request.Raw;\n\n    // Get the username and uid of the K8s reuest\n    const { username, uid } = request.Request.userInfo;\n\n    // Store some data about the request in the configmap\n    cm.data[\"username\"] = username;\n    cm.data[\"uid\"] = uid;\n\n    // You can still mix other ways of making changes too\n    request.SetAnnotation(\"pepr.dev\", \"making-waves\");\n  });\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   CAPABILITY ACTION                                               *\n * ---------------------------------------------------------------------------------------------------\n *\n * This Capability Action show how you can use the `Then()` function to make multiple changes to the\n * same object from different functions. This is useful if you want to keep your Capability Actions\n * small and focused on a single task, or if you want to reuse the same function in multiple\n * Capability Actions.\n *\n * Note that the order of the `.Then()` calls matters. The first call will be executed first,\n * then the second, and so on. Also note the functions are not called until the Capability Action\n * is triggered.\n */\nWhen(a.ConfigMap)\n  .IsCreated()\n  .WithName(\"example-5\")\n  .Then(cm => cm.SetLabel(\"pepr.dev/first\", \"true\"))\n  .Then(addSecond)\n  .Then(addThird);\n\n//This function uses the complete type definition, but is not required.\nfunction addSecond(cm: PeprRequest<a.ConfigMap>) {\n  cm.SetLabel(\"pepr.dev/second\", \"true\");\n}\n\n// This function has no type definition, so you won't have intelisense in the function body.\nfunction addThird(cm) {\n  cm.SetLabel(\"pepr.dev/third\", \"true\");\n}\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   CAPABILITY ACTION                                               *\n * ---------------------------------------------------------------------------------------------------\n *\n * This Capability Action is a bit more complex. It will look for any ConfigMap in the `pepr-demo`\n * namespace that has the label `chuck-norris` during CREATE. When it finds one, it will fetch a\n * random Chuck Norris joke from the API and add it to the ConfigMap. This is a great example of how\n * you can use Pepr to make changes to your K8s objects based on external data.\n *\n * Note the use of the `async` keyword. This is required for any Capability Action that uses `await` or `fetch()`.\n *\n * Also note we are passing a type to the `fetch()` function. This is optional, but it will help you\n * avoid mistakes when working with the data returned from the API. You can also use the `as` keyword to\n * cast the data returned from the API.\n *\n * These are equivelant:\n * ```ts\n * const joke = await fetch<TheChuckNorrisJoke>(\"https://api.chucknorris.io/jokes/random?category=dev\");\n * const joke = await fetch(\"https://api.chucknorris.io/jokes/random?category=dev\") as TheChuckNorrisJoke;\n * ```\n *\n * Alternatively, you can drop the type completely:\n *\n * ```ts\n * fetch(\"https://api.chucknorris.io/jokes/random?category=dev\")\n * ```\n */\ninterface TheChuckNorrisJoke {\n  icon_url: string;\n  id: string;\n  url: string;\n  value: string;\n}\n\nWhen(a.ConfigMap)\n  .IsCreated()\n  .WithLabel(\"chuck-norris\")\n  .Then(async change => {\n    const joke = await fetch<TheChuckNorrisJoke>(\n      \"https://api.chucknorris.io/jokes/random?category=dev\"\n    );\n\n    // Add the Chuck Norris joke to the configmap\n    change.Raw.data[\"chuck-says\"] = joke.value;\n  });\n" }
+{ "gitignore": "# Ignore node_modules and Pepr build artifacts\nnode_modules\ndist\ninsecure*\n", "readme": "# Pepr Module\n\nThis is a Pepr Module. [Pepr](https://github.com/defenseunicorns/pepr) is a Kubernetes transformation system\nwritten in Typescript.\n\nThe `capabilities` directory contains all the capabilities for this module. By default,\na capability is a single typescript file in the format of `capability-name.ts` that is\nimported in the root `pepr.ts` file as `import { HelloPepr } from \"./capabilities/hello-pepr\";`.\nBecause this is typescript, you can organize this however you choose, e.g. creating a sub-folder\nper-capability or common logic in shared files or folders.\n\nExample Structure:\n\n```\nModule Root\n├── package.json\n├── pepr.ts\n└── capabilities\n    ├── example-one.ts\n    ├── example-three.ts\n    └── example-two.ts\n```\n", "peprTS": "import { PeprModule } from \"pepr\";\nimport { HelloPepr } from \"./capabilities/hello-pepr\";\nimport cfg from \"./package.json\";\n\n/**\n * This is the main entrypoint for the Pepr module. It is the file that is run when the module is started.\n * This is where you register your configurations and capabilities with the module.\n */\nnew PeprModule(cfg, [\n  // \"HelloPepr\" is a demo capability that is included with Pepr. You can remove it if you want.\n  HelloPepr,\n\n  // Your additional capabilities go here\n]);\n", "helloPeprTS": "import { Capability, PeprRequest, RegisterKind, a, fetch } from \"pepr\";\n\n/**\n *  The HelloPepr Capability is an example capability to demonstrate some general concepts of Pepr.\n *  To test this capability you can run `pepr dev` or `npm start` and then run the following command:\n *  `kubectl apply -f capabilities/hello-pepr.samples.yaml`\n */\nexport const HelloPepr = new Capability({\n  name: \"hello-pepr\",\n  description: \"A simple example capability to show how things work.\",\n  namespaces: [\"pepr-demo\"],\n});\n\n// Use the 'When' function to create a new Capability Action\nconst { When } = HelloPepr;\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   CAPABILITY ACTION                                               *\n * ---------------------------------------------------------------------------------------------------\n *\n * This Capability Action removes the label `remove-me` when a Namespace is created.\n * Note we don't need to specify the namespace here, because we've already specified\n * it in the Capability definition above.\n */\nWhen(a.Namespace)\n  .IsCreated()\n  .Then(ns => ns.RemoveLabel(\"remove-me\"));\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   CAPABILITY ACTION                                               *\n * ---------------------------------------------------------------------------------------------------\n *\n * This is a single Capability Action. They can be in the same file or put imported from other files.\n * In this exmaple, when a ConfigMap is created with the name `example-1`, then add a label and annotation.\n *\n * Equivelant to manually running:\n * `kubectl label configmap example-1 pepr=was-here`\n * `kubectl annotate configmap example-1 pepr.dev=annotations-work-too`\n */\nWhen(a.ConfigMap)\n  .IsCreated()\n  .WithName(\"example-1\")\n  .Then(request =>\n    request\n      .SetLabel(\"pepr\", \"was-here\")\n      .SetAnnotation(\"pepr.dev\", \"annotations-work-too\")\n  );\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   CAPABILITY ACTION                                               *\n * ---------------------------------------------------------------------------------------------------\n *\n * This Capabiility Action does the exact same changes for example-2, except this time it uses\n * the `.ThenSet()` feature. You can stack multiple `.Then()` calls, but only a single `.ThenSet()`\n */\nWhen(a.ConfigMap)\n  .IsCreated()\n  .WithName(\"example-2\")\n  .ThenSet({\n    metadata: {\n      labels: {\n        pepr: \"was-here\",\n      },\n      annotations: {\n        \"pepr.dev\": \"annotations-work-too\",\n      },\n    },\n  });\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   CAPABILITY ACTION                                               *\n * ---------------------------------------------------------------------------------------------------\n *\n * This Capability Action combines different styles. Unlike the previous actions, this one will look\n * for any ConfigMap in the `pepr-demo` namespace that has the label `change=by-label` during either\n * CREATE or UPDATE. Note that all conditions added such as `WithName()`, `WithLabel()`, `InNamespace()`,\n * are ANDs so all conditions must be true for the request to be procssed.\n */\nWhen(a.ConfigMap)\n  .IsCreatedOrUpdated()\n  .WithLabel(\"change\", \"by-label\")\n  .Then(request => {\n    // The K8s object e are going to mutate\n    const cm = request.Raw;\n\n    // Get the username and uid of the K8s reuest\n    const { username, uid } = request.Request.userInfo;\n\n    // Store some data about the request in the configmap\n    cm.data[\"username\"] = username;\n    cm.data[\"uid\"] = uid;\n\n    // You can still mix other ways of making changes too\n    request.SetAnnotation(\"pepr.dev\", \"making-waves\");\n  });\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   CAPABILITY ACTION                                               *\n * ---------------------------------------------------------------------------------------------------\n *\n * This Capability Action show how you can use the `Then()` function to make multiple changes to the\n * same object from different functions. This is useful if you want to keep your Capability Actions\n * small and focused on a single task, or if you want to reuse the same function in multiple\n * Capability Actions.\n *\n * Note that the order of the `.Then()` calls matters. The first call will be executed first,\n * then the second, and so on. Also note the functions are not called until the Capability Action\n * is triggered.\n */\nWhen(a.ConfigMap)\n  .IsCreated()\n  .WithName(\"example-5\")\n  .Then(cm => cm.SetLabel(\"pepr.dev/first\", \"true\"))\n  .Then(addSecond)\n  .Then(addThird);\n\n//This function uses the complete type definition, but is not required.\nfunction addSecond(cm: PeprRequest<a.ConfigMap>) {\n  cm.SetLabel(\"pepr.dev/second\", \"true\");\n}\n\n// This function has no type definition, so you won't have intelisense in the function body.\nfunction addThird(cm) {\n  cm.SetLabel(\"pepr.dev/third\", \"true\");\n}\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   CAPABILITY ACTION                                               *\n * ---------------------------------------------------------------------------------------------------\n *\n * This Capability Action is a bit more complex. It will look for any ConfigMap in the `pepr-demo`\n * namespace that has the label `chuck-norris` during CREATE. When it finds one, it will fetch a\n * random Chuck Norris joke from the API and add it to the ConfigMap. This is a great example of how\n * you can use Pepr to make changes to your K8s objects based on external data.\n *\n * Note the use of the `async` keyword. This is required for any Capability Action that uses `await` or `fetch()`.\n *\n * Also note we are passing a type to the `fetch()` function. This is optional, but it will help you\n * avoid mistakes when working with the data returned from the API. You can also use the `as` keyword to\n * cast the data returned from the API.\n *\n * These are equivelant:\n * ```ts\n * const joke = await fetch<TheChuckNorrisJoke>(\"https://api.chucknorris.io/jokes/random?category=dev\");\n * const joke = await fetch(\"https://api.chucknorris.io/jokes/random?category=dev\") as TheChuckNorrisJoke;\n * ```\n *\n * Alternatively, you can drop the type completely:\n *\n * ```ts\n * fetch(\"https://api.chucknorris.io/jokes/random?category=dev\")\n * ```\n */\ninterface TheChuckNorrisJoke {\n  icon_url: string;\n  id: string;\n  url: string;\n  value: string;\n}\n\nWhen(a.ConfigMap)\n  .IsCreated()\n  .WithLabel(\"chuck-norris\")\n  .Then(async change => {\n    const joke = await fetch<TheChuckNorrisJoke>(\n      \"https://api.chucknorris.io/jokes/random?category=dev\"\n    );\n\n    // Add the Chuck Norris joke to the configmap\n    change.Raw.data[\"chuck-says\"] = joke.value;\n  });\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   CAPABILITY ACTION                                               *\n * ---------------------------------------------------------------------------------------------------\n *\n * Out of the box, Pepr supports all the standard Kubernetes objects. However, you can also create\n * your own types. This is useful if you are working with an Operator that creates custom resources.\n * There are two ways to do this, the first is to use the `When()` function with a `GenericKind`,\n * the second is to create a new class that extends `GenericKind` and use the `RegisterKind()` function.\n *\n * This example shows how to use the `When()` function with a `GenericKind`. Note that you\n * must specify the `group`, `version`, and `kind` of the object (if applicable). This is how Pepr knows\n * if the Capability Action should be triggered or not. Since we are using a `GenericKind`,\n * Pepr will not be able to provide any intelisense for the object, so you will need to refer to the\n * Kubernetes API documentation for the object you are working with.\n *\n * You will need ot wait for the CRD in `hello-pepr.samples.yaml` to be created, then you can apply\n *\n * ```yaml\n * apiVersion: pepr.dev/v1\n * kind: Unicorn\n * metadata:\n *   name: example-1\n *   namespace: pepr-demo\n * spec:\n *   message: replace-me\n *   counter: 0\n * ```\n */\nWhen(a.GenericKind, {\n  group: \"pepr.dev\",\n  version: \"v1\",\n  kind: \"Unicorn\",\n})\n  .IsCreated()\n  .WithName(\"example-1\")\n  .ThenSet({\n    spec: {\n      message: \"Hello Pepr without type data!\",\n      counter: Math.random(),\n    },\n  });\n\n/**\n * ---------------------------------------------------------------------------------------------------\n *                                   CAPABILITY ACTION                                               *\n * ---------------------------------------------------------------------------------------------------\n *\n * This example shows how to use the `RegisterKind()` function to create a new type. This is useful\n * if you are working with an Operator that creates custom resources and you want to have intelisense\n * for the object. Note that you must specify the `group`, `version`, and `kind` of the object (if applicable)\n * as this is how Pepr knows if the Capability Action should be triggered or not.\n *\n * Once you register a new Kind with Pepr, you can use the `When()` function with the new Kind. Ideally,\n * you should register custom Kinds at the top of your Capability file or Pepr Module so they are available\n * to all Capability Actions, but we are putting it here for demonstration purposes.\n *\n * You will need ot wait for the CRD in `hello-pepr.samples.yaml` to be created, then you can apply\n *\n * ```yaml\n * apiVersion: pepr.dev/v1\n * kind: Unicorn\n * metadata:\n *   name: example-2\n *   namespace: pepr-demo\n * spec:\n *   message: replace-me\n *   counter: 0\n * ```*\n */\nclass UnicornKind extends a.GenericKind {\n  spec: {\n    /**\n     * JSDoc comments can be added to explain more details about the field.\n     *\n     * @example\n     * ```ts\n     * request.Raw.spec.message = \"Hello Pepr!\";\n     * ```\n     * */\n    message: string;\n    counter: number;\n  };\n}\n\nRegisterKind(UnicornKind, {\n  group: \"pepr.dev\",\n  version: \"v1\",\n  kind: \"Unicorn\",\n});\n\nWhen(UnicornKind)\n  .IsCreated()\n  .WithName(\"example-2\")\n  .ThenSet({\n    spec: {\n      message: \"Hello Pepr now with type data!\",\n      counter: Math.random(),\n    },\n  });\n" }

package/dist/src/cli/init/templates/samples.json

@@ -67,5 +67,46 @@
             "name": "example-5",
             "namespace": "pepr-demo"
         }
+    },
+    {
+        "apiVersion": "apiextensions.k8s.io/v1",
+        "kind": "CustomResourceDefinition",
+        "metadata": {
+            "name": "unicorns.pepr.dev"
+        },
+        "spec": {
+            "group": "pepr.dev",
+            "versions": [
+                {
+                    "name": "v1",
+                    "served": true,
+                    "storage": true,
+                    "schema": {
+                        "openAPIV3Schema": {
+                            "type": "object",
+                            "properties": {
+                                "spec": {
+                                    "type": "object",
+                                    "properties": {
+                                        "message": {
+                                            "type": "string"
+                                        },
+                                        "counter": {
+                                            "type": "number"
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            ],
+            "scope": "Namespaced",
+            "names": {
+                "plural": "unicorns",
+                "singular": "unicorn",
+                "kind": "Unicorn"
+            }
+        }
     }
 ]

package/dist/src/lib/capability.d.ts

@@ -1,3 +1,4 @@
+import { GroupVersionKind } from "./k8s";
 import { Binding, CapabilityCfg, GenericClass, HookPhase, WhenSelector } from "./types";
 /**
  * A capability is a unit of functionality that can be registered with the Pepr runtime.
@@ -19,8 +20,9 @@ export declare class Capability implements CapabilityCfg {
      * processed by Pepr. The action will be executed if the resource matches the specified kind and any
      * filters that are applied.
      *
-     * @param model if using a custom KubernetesObject not available in `a.*`, specify the GroupVersionKind
+     * @param model the KubernetesObject model to match
+     * @param kind if using a custom KubernetesObject not available in `a.*`, specify the GroupVersionKind
      * @returns
      */
-    When: <T extends GenericClass>(model: T) => WhenSelector<T>;
+    When: <T extends GenericClass>(model: T, kind?: GroupVersionKind) => WhenSelector<T>;
 }

package/dist/src/lib/capability.js

@@ -37,13 +37,19 @@ class Capability {
          * processed by Pepr. The action will be executed if the resource matches the specified kind and any
          * filters that are applied.
          *
-         * @param model if using a custom KubernetesObject not available in `a.*`, specify the GroupVersionKind
+         * @param model the KubernetesObject model to match
+         * @param kind if using a custom KubernetesObject not available in `a.*`, specify the GroupVersionKind
          * @returns
          */
-        this.When = (model) => {
+        this.When = (model, kind) => {
+            const matchedKind = (0, k8s_1.modelToGroupVersionKind)(model.name);
+            // If the kind is not specified and the model is not a KubernetesObject, throw an error
+            if (!matchedKind && !kind) {
+                throw new Error(`Kind not specified for ${model.name}`);
+            }
             const binding = {
-                // If the kind is not specified, use the default KubernetesObject
-                kind: (0, k8s_1.modelToGroupVersionKind)(model.name),
+                // If the kind is not specified, use the matched kind from the model
+                kind: kind || matchedKind,
                 filters: {
                     name: "",
                     namespaces: [],

package/dist/src/lib/k8s/index.d.ts

@@ -1,5 +1,5 @@
 import * as kind from "./upstream";
 /** a is a colleciton of K8s types to be used within a CapabilityAction: `When(a.Configmap)` */
 export { kind as a };
-export { modelToGroupVersionKind, gvkMap } from "./kinds";
+export { modelToGroupVersionKind, gvkMap, RegisterKind } from "./kinds";
 export * from "./types";

package/dist/src/lib/k8s/index.js

@@ -28,11 +28,12 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.gvkMap = exports.modelToGroupVersionKind = exports.a = void 0;
+exports.RegisterKind = exports.gvkMap = exports.modelToGroupVersionKind = exports.a = void 0;
 // Export kinds as a single object
 const kind = __importStar(require("./upstream"));
 exports.a = kind;
 var kinds_1 = require("./kinds");
 Object.defineProperty(exports, "modelToGroupVersionKind", { enumerable: true, get: function () { return kinds_1.modelToGroupVersionKind; } });
 Object.defineProperty(exports, "gvkMap", { enumerable: true, get: function () { return kinds_1.gvkMap; } });
+Object.defineProperty(exports, "RegisterKind", { enumerable: true, get: function () { return kinds_1.RegisterKind; } });
 __exportStar(require("./types"), exports);

package/dist/src/lib/k8s/kinds.d.ts

@@ -1,3 +1,11 @@
+import { GenericClass } from "../types";
 import { GroupVersionKind } from "./types";
 export declare const gvkMap: Record<string, GroupVersionKind>;
 export declare function modelToGroupVersionKind(key: string): GroupVersionKind;
+/**
+ * Registers a new model and GroupVersionKind with Pepr for use with `When(a.<Kind>)`
+ *
+ * @param model Used to match the GroupVersionKind and define the type-data for the request
+ * @param groupVersionKind Contains the match paramaters to determine the request should be handled
+ */
+export declare const RegisterKind: (model: GenericClass, groupVersionKind: GroupVersionKind) => void;

package/dist/src/lib/k8s/kinds.js

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2023-Present The Pepr Authors
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.modelToGroupVersionKind = exports.gvkMap = void 0;
+exports.RegisterKind = exports.modelToGroupVersionKind = exports.gvkMap = void 0;
 exports.gvkMap = {
     /**
      * Represents a K8s ConfigMap resource.
@@ -429,3 +429,19 @@ function modelToGroupVersionKind(key) {
     return exports.gvkMap[key];
 }
 exports.modelToGroupVersionKind = modelToGroupVersionKind;
+/**
+ * Registers a new model and GroupVersionKind with Pepr for use with `When(a.<Kind>)`
+ *
+ * @param model Used to match the GroupVersionKind and define the type-data for the request
+ * @param groupVersionKind Contains the match paramaters to determine the request should be handled
+ */
+const RegisterKind = (model, groupVersionKind) => {
+    const name = model.name;
+    // Do not allow overwriting existing GVKs
+    if (exports.gvkMap[name]) {
+        throw new Error(`GVK ${name} already registered`);
+    }
+    // Set the GVK
+    exports.gvkMap[name] = groupVersionKind;
+};
+exports.RegisterKind = RegisterKind;

package/dist/src/lib/k8s/types.d.ts

@@ -16,6 +16,17 @@ export interface KubernetesListObject<T extends KubernetesObject> {
     metadata?: V1ListMeta;
     items: T[];
 }
+/**
+ * GenericKind is a generic Kubernetes object that can be used to represent any Kubernetes object
+ * that is not explicitly supported by Pepr. This can be used on its own or as a base class for
+ * other types. See the examples in `HelloPepr.ts` for more information.
+ */
+export declare class GenericKind {
+    apiVersion?: string;
+    kind?: string;
+    metadata?: V1ObjectMeta;
+    [key: string]: any;
+}
 /**
  *  GroupVersionKind unambiguously identifies a kind.  It doesn't anonymously include GroupVersion
  * to avoid automatic coercion.  It doesn't use a GroupVersion to avoid custom marshalling

package/dist/src/lib/k8s/types.js

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2023-Present The Pepr Authors
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Operation = void 0;
+exports.GenericKind = exports.Operation = void 0;
 var Operation;
 (function (Operation) {
     Operation["CREATE"] = "CREATE";
@@ -10,3 +10,11 @@ var Operation;
     Operation["DELETE"] = "DELETE";
     Operation["CONNECT"] = "CONNECT";
 })(Operation = exports.Operation || (exports.Operation = {}));
+/**
+ * GenericKind is a generic Kubernetes object that can be used to represent any Kubernetes object
+ * that is not explicitly supported by Pepr. This can be used on its own or as a base class for
+ * other types. See the examples in `HelloPepr.ts` for more information.
+ */
+class GenericKind {
+}
+exports.GenericKind = GenericKind;

package/dist/src/lib/k8s/upstream.d.ts

@@ -1,2 +1,3 @@
 /** a is a colleciton of K8s types to be used within a CapabilityAction: `When(a.Configmap)` */
 export { V1APIService as APIService, V1CertificateSigningRequest as CertificateSigningRequest, V1ConfigMap as ConfigMap, V1ControllerRevision as ControllerRevision, V1CronJob as CronJob, V1CSIDriver as CSIDriver, V1CSIStorageCapacity as CSIStorageCapacity, V1CustomResourceDefinition as CustomResourceDefinition, V1DaemonSet as DaemonSet, V1Deployment as Deployment, V1EndpointSlice as EndpointSlice, V1HorizontalPodAutoscaler as HorizontalPodAutoscaler, V1Ingress as Ingress, V1IngressClass as IngressClass, V1Job as Job, V1LimitRange as LimitRange, V1LocalSubjectAccessReview as LocalSubjectAccessReview, V1MutatingWebhookConfiguration as MutatingWebhookConfiguration, V1Namespace as Namespace, V1NetworkPolicy as NetworkPolicy, V1Node as Node, V1PersistentVolume as PersistentVolume, V1PersistentVolumeClaim as PersistentVolumeClaim, V1Pod as Pod, V1PodDisruptionBudget as PodDisruptionBudget, V1PodTemplate as PodTemplate, V1ReplicaSet as ReplicaSet, V1ReplicationController as ReplicationController, V1ResourceQuota as ResourceQuota, V1RuntimeClass as RuntimeClass, V1Secret as Secret, V1SelfSubjectAccessReview as SelfSubjectAccessReview, V1SelfSubjectRulesReview as SelfSubjectRulesReview, V1Service as Service, V1ServiceAccount as ServiceAccount, V1StatefulSet as StatefulSet, V1StorageClass as StorageClass, V1SubjectAccessReview as SubjectAccessReview, V1TokenReview as TokenReview, V1ValidatingWebhookConfiguration as ValidatingWebhookConfiguration, V1VolumeAttachment as VolumeAttachment, } from "@kubernetes/client-node/dist";
+export { GenericKind } from "./types";

package/dist/src/lib/k8s/upstream.js

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2023-Present The Pepr Authors
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VolumeAttachment = exports.ValidatingWebhookConfiguration = exports.TokenReview = exports.SubjectAccessReview = exports.StorageClass = exports.StatefulSet = exports.ServiceAccount = exports.Service = exports.SelfSubjectRulesReview = exports.SelfSubjectAccessReview = exports.Secret = exports.RuntimeClass = exports.ResourceQuota = exports.ReplicationController = exports.ReplicaSet = exports.PodTemplate = exports.PodDisruptionBudget = exports.Pod = exports.PersistentVolumeClaim = exports.PersistentVolume = exports.Node = exports.NetworkPolicy = exports.Namespace = exports.MutatingWebhookConfiguration = exports.LocalSubjectAccessReview = exports.LimitRange = exports.Job = exports.IngressClass = exports.Ingress = exports.HorizontalPodAutoscaler = exports.EndpointSlice = exports.Deployment = exports.DaemonSet = exports.CustomResourceDefinition = exports.CSIStorageCapacity = exports.CSIDriver = exports.CronJob = exports.ControllerRevision = exports.ConfigMap = exports.CertificateSigningRequest = exports.APIService = void 0;
+exports.GenericKind = exports.VolumeAttachment = exports.ValidatingWebhookConfiguration = exports.TokenReview = exports.SubjectAccessReview = exports.StorageClass = exports.StatefulSet = exports.ServiceAccount = exports.Service = exports.SelfSubjectRulesReview = exports.SelfSubjectAccessReview = exports.Secret = exports.RuntimeClass = exports.ResourceQuota = exports.ReplicationController = exports.ReplicaSet = exports.PodTemplate = exports.PodDisruptionBudget = exports.Pod = exports.PersistentVolumeClaim = exports.PersistentVolume = exports.Node = exports.NetworkPolicy = exports.Namespace = exports.MutatingWebhookConfiguration = exports.LocalSubjectAccessReview = exports.LimitRange = exports.Job = exports.IngressClass = exports.Ingress = exports.HorizontalPodAutoscaler = exports.EndpointSlice = exports.Deployment = exports.DaemonSet = exports.CustomResourceDefinition = exports.CSIStorageCapacity = exports.CSIDriver = exports.CronJob = exports.ControllerRevision = exports.ConfigMap = exports.CertificateSigningRequest = exports.APIService = void 0;
 /** a is a colleciton of K8s types to be used within a CapabilityAction: `When(a.Configmap)` */
 var dist_1 = require("@kubernetes/client-node/dist");
 Object.defineProperty(exports, "APIService", { enumerable: true, get: function () { return dist_1.V1APIService; } });
@@ -46,3 +46,5 @@ Object.defineProperty(exports, "SubjectAccessReview", { enumerable: true, get: f
 Object.defineProperty(exports, "TokenReview", { enumerable: true, get: function () { return dist_1.V1TokenReview; } });
 Object.defineProperty(exports, "ValidatingWebhookConfiguration", { enumerable: true, get: function () { return dist_1.V1ValidatingWebhookConfiguration; } });
 Object.defineProperty(exports, "VolumeAttachment", { enumerable: true, get: function () { return dist_1.V1VolumeAttachment; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "GenericKind", { enumerable: true, get: function () { return types_1.GenericKind; } });

package/package.json

@@ -9,7 +9,7 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "version": "0.1.44",
+  "version": "0.1.45",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "pepr": {