@qawolf/api-contracts 0.1.0

package/README.md

@@ -0,0 +1,21 @@
+# @qawolf/api-contracts
+
+Versioned contracts for the QA Wolf public API.
+
+The package is the source of truth for public endpoints, and server implementations must derive their public input and output schemas from these contracts. Contract `name` values are exact tRPC route paths under the public namespace. Authorization and privileged request state stay in the owning server controller or policy.
+
+```ts
+import { publicContractsV1 } from "@qawolf/api-contracts/v1";
+
+const contract = publicContractsV1.run.create;
+```
+
+Contracts are built by a factory that takes the id schemas as input. External consumers use `publicContractsV1`, which validates ids loosely (the server is the source of truth for id formats). The server instantiates `makeContractsV1` with its own strict id schemas, so the contract shape can never drift between the two sides while validation strictness stays server-owned.
+
+This package must not depend on internal packages or expose internal concepts: it is published publicly.
+
+## Publishing
+
+This package is intended to be published to the public npm registry so external repositories such as `qawolf/cli` can consume the public contracts. It is not published yet.
+
+To publish a new version, bump `version` in `package.json` and run `npm publish` from this directory with an npm token authorized for the `@qawolf` scope (the build runs automatically via `prepublishOnly`).

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./v1/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "./v1/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC"}

package/dist/v1/definition.d.ts

@@ -0,0 +1,13 @@
+import type { z } from "zod";
+export type PublicApiContractKind = "read" | "write";
+type AnyZodSchema = z.ZodType;
+export type PublicApiContract<Name extends string, Kind extends PublicApiContractKind, Input extends AnyZodSchema, Output extends AnyZodSchema> = {
+    description: string;
+    input: Input;
+    kind: Kind;
+    name: Name;
+    output: Output;
+};
+export type AnyPublicApiContract = PublicApiContract<string, PublicApiContractKind, AnyZodSchema, AnyZodSchema>;
+export {};
+//# sourceMappingURL=definition.d.ts.map

package/dist/v1/definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../../src/v1/definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,OAAO,CAAC;AAErD,KAAK,YAAY,GAAG,CAAC,CAAC,OAAO,CAAC;AAE9B,MAAM,MAAM,iBAAiB,CAC3B,IAAI,SAAS,MAAM,EACnB,IAAI,SAAS,qBAAqB,EAClC,KAAK,SAAS,YAAY,EAC1B,MAAM,SAAS,YAAY,IACzB;IACF,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,KAAK,CAAC;IACb,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,IAAI,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,iBAAiB,CAClD,MAAM,EACN,qBAAqB,EACrB,YAAY,EACZ,YAAY,CACb,CAAC"}

package/dist/v1/definition.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=definition.js.map

package/dist/v1/definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.js","sourceRoot":"","sources":["../../src/v1/definition.ts"],"names":[],"mappings":""}

package/dist/v1/ids.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+export type PublicIdSchema = z.ZodType<string, string>;
+/**
+ * Id schemas injected into the contract factory, keyed by public API
+ * concept.
+ *
+ * The generic form exists because contract factories must stay generic over
+ * each schema individually: indexing a single generic record type loses the
+ * injected schema types (TypeScript resolves the indexed access to its
+ * constraint inside the factory body).
+ */
+export type PublicIdSchemasOf<EnvironmentId extends PublicIdSchema, FlowId extends PublicIdSchema, RunId extends PublicIdSchema> = {
+    environment: EnvironmentId;
+    flow: FlowId;
+    run: RunId;
+};
+export type PublicIdSchemas = PublicIdSchemasOf<PublicIdSchema, PublicIdSchema, PublicIdSchema>;
+/**
+ * The default schemas validate loosely: the server is the source of truth
+ * for id formats (including legacy formats), and encoding those rules here
+ * would leak internals. Server-side instantiations inject their own strict
+ * schemas instead.
+ */
+export declare const defaultIdSchemas: PublicIdSchemas;
+//# sourceMappingURL=ids.d.ts.map

package/dist/v1/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../src/v1/ids.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEvD;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,CAC3B,aAAa,SAAS,cAAc,EACpC,MAAM,SAAS,cAAc,EAC7B,KAAK,SAAS,cAAc,IAC1B;IACF,WAAW,EAAE,aAAa,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,KAAK,CAAC;CACZ,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,iBAAiB,CAC7C,cAAc,EACd,cAAc,EACd,cAAc,CACf,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,eAI9B,CAAC"}

package/dist/v1/ids.js

@@ -0,0 +1,13 @@
+import { z } from "zod";
+/**
+ * The default schemas validate loosely: the server is the source of truth
+ * for id formats (including legacy formats), and encoding those rules here
+ * would leak internals. Server-side instantiations inject their own strict
+ * schemas instead.
+ */
+export const defaultIdSchemas = {
+    environment: z.string().min(1).describe("The id of the environment."),
+    flow: z.string().min(1).describe("The id of the flow."),
+    run: z.string().min(1).describe("The id of the run."),
+};
+//# sourceMappingURL=ids.js.map

package/dist/v1/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../src/v1/ids.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA6BxB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAoB;IAC/C,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,4BAA4B,CAAC;IACrE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,qBAAqB,CAAC;IACvD,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,oBAAoB,CAAC;CACtD,CAAC"}

package/dist/v1/index.d.ts

@@ -0,0 +1,51 @@
+import type { z } from "zod";
+export type { AnyPublicApiContract, PublicApiContract, PublicApiContractKind, } from "./definition.js";
+export { type PublicIdSchema, type PublicIdSchemas, defaultIdSchemas, } from "./ids.js";
+import type { AnyPublicApiContract } from "./definition.js";
+import { type PublicIdSchema, type PublicIdSchemasOf } from "./ids.js";
+export type PublicApiInput<Api extends AnyPublicApiContract> = z.input<Api["input"]>;
+export type PublicApiOutput<Api extends AnyPublicApiContract> = z.infer<Api["output"]>;
+/**
+ * Builds the v1 contract catalog from a set of id schemas.
+ *
+ * External consumers use {@link publicContractsV1}. The server instantiates
+ * the same factory with its own strict id schemas, so the contract shape can
+ * never drift between the two while validation strictness stays server-owned.
+ */
+export declare const makeContractsV1: <EnvironmentId extends PublicIdSchema, FlowId extends PublicIdSchema, RunId extends PublicIdSchema>(ids: PublicIdSchemasOf<EnvironmentId, FlowId, RunId>) => {
+    run: {
+        create: {
+            readonly description: "Create a run for selected flows in an environment.";
+            readonly input: z.ZodObject<{
+                environmentId: EnvironmentId;
+                environmentVariables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                flowIds: z.ZodArray<FlowId>;
+                ignoreRules: z.ZodDefault<z.ZodBoolean>;
+            }, z.core.$strip>;
+            readonly kind: "write";
+            readonly name: "run.create";
+            readonly output: z.ZodObject<{
+                runId: RunId;
+            }, z.core.$strip>;
+        };
+    };
+};
+export declare const publicContractsV1: {
+    run: {
+        create: {
+            readonly description: "Create a run for selected flows in an environment.";
+            readonly input: z.ZodObject<{
+                environmentId: PublicIdSchema;
+                environmentVariables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                flowIds: z.ZodArray<PublicIdSchema>;
+                ignoreRules: z.ZodDefault<z.ZodBoolean>;
+            }, z.core.$strip>;
+            readonly kind: "write";
+            readonly name: "run.create";
+            readonly output: z.ZodObject<{
+                runId: PublicIdSchema;
+            }, z.core.$strip>;
+        };
+    };
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/v1/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/v1/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,YAAY,EACV,oBAAoB,EACpB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,gBAAgB,GACjB,MAAM,UAAU,CAAC;AAElB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,iBAAiB,EAEvB,MAAM,UAAU,CAAC;AAGlB,MAAM,MAAM,cAAc,CAAC,GAAG,SAAS,oBAAoB,IAAI,CAAC,CAAC,KAAK,CACpE,GAAG,CAAC,OAAO,CAAC,CACb,CAAC;AAEF,MAAM,MAAM,eAAe,CAAC,GAAG,SAAS,oBAAoB,IAAI,CAAC,CAAC,KAAK,CACrE,GAAG,CAAC,QAAQ,CAAC,CACd,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAC1B,aAAa,SAAS,cAAc,EACpC,MAAM,SAAS,cAAc,EAC7B,KAAK,SAAS,cAAc,EAE5B,KAAK,iBAAiB,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,CAAC;;;;;;;;;;;;;;;;;CAKpD,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;CAAoC,CAAC"}

package/dist/v1/index.js

@@ -0,0 +1,17 @@
+export { defaultIdSchemas, } from "./ids.js";
+import { defaultIdSchemas, } from "./ids.js";
+import { makeCreateRunContract } from "./run/index.js";
+/**
+ * Builds the v1 contract catalog from a set of id schemas.
+ *
+ * External consumers use {@link publicContractsV1}. The server instantiates
+ * the same factory with its own strict id schemas, so the contract shape can
+ * never drift between the two while validation strictness stays server-owned.
+ */
+export const makeContractsV1 = (ids) => ({
+    run: {
+        create: makeCreateRunContract(ids),
+    },
+});
+export const publicContractsV1 = makeContractsV1(defaultIdSchemas);
+//# sourceMappingURL=index.js.map

package/dist/v1/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/v1/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAGL,gBAAgB,GACjB,MAAM,UAAU,CAAC;AAGlB,OAAO,EAGL,gBAAgB,GACjB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAUvD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAK7B,GAAoD,EACpD,EAAE,CAAC,CAAC;IACJ,GAAG,EAAE;QACH,MAAM,EAAE,qBAAqB,CAAC,GAAG,CAAC;KACnC;CACF,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAG,eAAe,CAAC,gBAAgB,CAAC,CAAC"}

package/dist/v1/run/index.d.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import type { PublicIdSchema, PublicIdSchemasOf } from "../ids.js";
+export declare const makeCreateRunContract: <EnvironmentId extends PublicIdSchema, FlowId extends PublicIdSchema, RunId extends PublicIdSchema>(ids: PublicIdSchemasOf<EnvironmentId, FlowId, RunId>) => {
+    readonly description: "Create a run for selected flows in an environment.";
+    readonly input: z.ZodObject<{
+        environmentId: EnvironmentId;
+        environmentVariables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        flowIds: z.ZodArray<FlowId>;
+        ignoreRules: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>;
+    readonly kind: "write";
+    readonly name: "run.create";
+    readonly output: z.ZodObject<{
+        runId: RunId;
+    }, z.core.$strip>;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/v1/run/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/v1/run/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAEnE,eAAO,MAAM,qBAAqB,GAChC,aAAa,SAAS,cAAc,EACpC,MAAM,SAAS,cAAc,EAC7B,KAAK,SAAS,cAAc,EAE5B,KAAK,iBAAiB,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,CAAC;;;;;;;;;;;;;CAsBrD,CAAC"}

package/dist/v1/run/index.js

@@ -0,0 +1,18 @@
+import { z } from "zod";
+export const makeCreateRunContract = (ids) => {
+    const input = z.object({
+        environmentId: ids.environment,
+        environmentVariables: z.record(z.string(), z.string()).optional(),
+        flowIds: z.array(ids.flow).min(1),
+        ignoreRules: z.boolean().default(false),
+    });
+    const output = z.object({ runId: ids.run });
+    return {
+        description: "Create a run for selected flows in an environment.",
+        input,
+        kind: "write",
+        name: "run.create",
+        output,
+    };
+};
+//# sourceMappingURL=index.js.map

package/dist/v1/run/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/v1/run/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAKnC,GAAoD,EACpD,EAAE;IACF,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC;QACrB,aAAa,EAAE,GAAG,CAAC,WAAW;QAC9B,oBAAoB,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;QACjE,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACjC,WAAW,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;KACxC,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC;IAE5C,OAAO;QACL,WAAW,EAAE,oDAAoD;QACjE,KAAK;QACL,IAAI,EAAE,OAAO;QACb,IAAI,EAAE,YAAY;QAClB,MAAM;KAMP,CAAC;AACJ,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@qawolf/api-contracts",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Versioned contracts for the QA Wolf public API",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/qawolf/platform.git"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./v1": {
+      "types": "./dist/v1/index.d.ts",
+      "import": "./dist/v1/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rm -rf ./dist && tsc -p tsconfig.build.json",
+    "lint:ci": "npm run lint:non-fixable; NON_FIXABLE_EXIT=$?; npm run lint:fixable && exit $NON_FIXABLE_EXIT",
+    "lint:dev": "npm run lint:fixable",
+    "lint:fixable": "eslint . --ext cjs,cts,js,jsx,mjs,ts,tsx --fix --quiet && prettier --log-level=warn --write .",
+    "lint:non-fixable": "dpdm --exit-code circular:1 --no-tree --no-warning --transform --include='.*' --exclude='/(dist|node_modules)/' '**/*'",
+    "prepublishOnly": "npm run build",
+    "test": "NODE_OPTIONS=\"--experimental-vm-modules\" NODE_NO_WARNINGS=1 jest",
+    "tsc:check": "tsgo --noEmit -p tsconfig.typecheck.json"
+  },
+  "dependencies": {
+    "tslib": "^2.5.3"
+  },
+  "devDependencies": {
+    "@typescript/native-preview": "^7.0.0-dev.20260416.1",
+    "typescript": "^5.9.2",
+    "zod": "^4.1.11"
+  },
+  "peerDependencies": {
+    "zod": "^4.1.11"
+  },
+  "engines": {
+    "node": ">=22.22.0 <25"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}