@griffin-app/griffin-ts 0.1.0

package/src/secrets.ts

@@ -0,0 +1,112 @@
+/**
+ * Secret reference types and utilities for griffin DSL.
+ *
+ * Secrets are referenced by provider and path, and resolved at runtime
+ * by the plan executor using configured secret providers.
+ */
+
+export interface SecretRefData {
+  provider: string;
+  ref: string;
+  version?: string;
+  field?: string;
+}
+
+export interface SecretRef {
+  $secret: SecretRefData;
+}
+
+export interface SecretOptions {
+  /** Pin to a specific version (provider-dependent) */
+  version?: string;
+  /** Extract a specific field from a JSON secret */
+  field?: string;
+}
+
+/**
+ * Create a secret reference for use in endpoint headers or body.
+ *
+ * @param path - Provider-qualified path in format "provider:path"
+ *   Examples:
+ *   - "env:API_KEY" - Environment variable
+ *   - "aws:prod/api-key" - AWS Secrets Manager
+ *   - "vault:secret/data/api" - HashiCorp Vault
+ *   - "doppler:backend/prod/API_KEY" - Doppler
+ *
+ * @param options - Optional version pinning or field extraction
+ *
+ * @example
+ * ```typescript
+ * builder.addEndpoint("call", {
+ *   method: GET,
+ *   path: "/api/data",
+ *   headers: {
+ *     "Authorization": secret("aws:prod/api-key"),
+ *     "X-API-Key": secret("env:LOCAL_API_KEY"),
+ *   },
+ * })
+ * ```
+ */
+export function secret(path: string, options?: SecretOptions): SecretRef {
+  const colonIndex = path.indexOf(":");
+
+  if (colonIndex === -1) {
+    throw new Error(
+      `Secret path must include provider: "provider:path" (e.g., "aws:my-secret", "env:API_KEY"). Got: "${path}"`,
+    );
+  }
+
+  if (colonIndex === 0) {
+    throw new Error(
+      `Secret path must have a provider name before the colon. Got: "${path}"`,
+    );
+  }
+
+  if (colonIndex === path.length - 1) {
+    throw new Error(
+      `Secret path must have a reference after the colon. Got: "${path}"`,
+    );
+  }
+
+  const provider = path.slice(0, colonIndex);
+  const ref = path.slice(colonIndex + 1);
+
+  return {
+    $secret: {
+      provider,
+      ref,
+      ...(options?.version !== undefined && { version: options.version }),
+      ...(options?.field !== undefined && { field: options.field }),
+    },
+  };
+}
+
+/**
+ * Type guard to check if a value is a secret reference.
+ */
+export function isSecretRef(value: unknown): value is SecretRef {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+
+  const obj = value as Record<string, unknown>;
+  if (
+    !("$secret" in obj) ||
+    typeof obj.$secret !== "object" ||
+    obj.$secret === null
+  ) {
+    return false;
+  }
+
+  const secretData = obj.$secret as Record<string, unknown>;
+  return (
+    typeof secretData.provider === "string" &&
+    typeof secretData.ref === "string"
+  );
+}
+
+/**
+ * Type that allows either a literal value or a secret reference.
+ * Used for headers and other fields that may contain secrets.
+ */
+export type SecretOrValue<T> = T | SecretRef;

package/src/sequential-builder.ts

@@ -0,0 +1,254 @@
+import {
+  Endpoint,
+  Wait,
+  Assertion,
+  type EndpointConfig,
+  type WaitDuration,
+} from "./builder";
+import { START, END } from "./constants";
+import { TEST_PLAN_VERSION, Edge, Node, Frequency, TestPlanV1 } from "./schema";
+import {
+  createStateProxy,
+  type SerializedAssertion,
+  type StateProxy,
+} from "./assertions";
+
+type RawPlan = Omit<TestPlanV1, "id" | "environment">;
+
+/**
+ * Callback type for building assertions with type-safe state access
+ */
+export type AssertionCallback<NodeNames extends string> = (
+  state: StateProxy<NodeNames>,
+) => SerializedAssertion[];
+
+/**
+ * SequentialTestBuilder provides a simplified DSL for creating linear test flows.
+ * Edges are automatically created based on the order nodes are added.
+ * No manual edge management required - just add steps in sequence.
+ *
+ * @template NodeNames - Union of all registered node names for type-safe state access
+ */
+export interface SequentialTestBuilder<NodeNames extends string = never> {
+  /**
+   * Adds an endpoint request to the sequence.
+   *
+   * @param name - Unique name for this node
+   * @param config - Endpoint configuration
+   * @returns Updated builder with node name registered
+   *
+   * @example
+   * ```typescript
+   * builder.request("create_user", {
+   *   method: POST,
+   *   path: "/api/v1/users",
+   *   response_format: Json,
+   *   body: { name: "Test User" }
+   * })
+   * ```
+   */
+  request<Name extends string>(
+    name: Name,
+    config: EndpointConfig,
+  ): SequentialTestBuilder<NodeNames | Name>;
+
+  /**
+   * Adds a wait/delay to the sequence.
+   *
+   * @param name - Unique name for this node
+   * @param duration - How long to wait
+   * @returns Updated builder with node name registered
+   *
+   * @example
+   * ```typescript
+   * builder.wait("pause", Wait.seconds(5))
+   * // or with raw milliseconds:
+   * builder.wait("pause", 5000)
+   * ```
+   */
+  wait<Name extends string>(
+    name: Name,
+    duration: WaitDuration,
+  ): SequentialTestBuilder<NodeNames | Name>;
+
+  /**
+   * Adds assertions to the sequence using a callback with type-safe state access.
+   *
+   * The callback receives a state proxy that provides autocomplete for all registered
+   * node names and allows building rich JsonPath-based assertions.
+   *
+   * @param callback - Function that receives state proxy and returns assertions
+   * @returns Updated builder (no new node name registered - uses auto-generated name)
+   *
+   * @example
+   * ```typescript
+   * builder.assert((state) => [
+   *   Assert(state["create_user"].status).equals(201),
+   *   Assert(state["create_user"].body["data"]["id"]).not.isNull(),
+   *   Assert(state["create_user"].headers["content-type"]).contains("application/json"),
+   * ])
+   * ```
+   */
+  assert(
+    callback: AssertionCallback<NodeNames>,
+  ): SequentialTestBuilder<NodeNames>;
+
+  /**
+   * Builds the final test plan.
+   * Automatically connects all nodes in sequence: START → node1 → node2 → ... → END
+   *
+   * @returns The completed TestPlan
+   */
+  build(): RawPlan;
+}
+
+/**
+ * Internal implementation class for SequentialTestBuilder.
+ */
+class SequentialTestBuilderImpl<
+  NodeNames extends string = never,
+> implements SequentialTestBuilder<NodeNames> {
+  private nodes: Node[] = [];
+  private nodeNames: string[] = [];
+  private nodeCounter = 0;
+
+  constructor(
+    private config: {
+      name: string;
+      frequency?: Frequency;
+      locations?: string[];
+    },
+  ) {}
+
+  /**
+   * Generates a unique auto-generated node name
+   */
+  private generateNodeName(): string {
+    return `step_${this.nodeCounter++}`;
+  }
+
+  request<Name extends string>(
+    name: Name,
+    config: EndpointConfig,
+  ): SequentialTestBuilder<NodeNames | Name> {
+    const node = Endpoint(config);
+    this.nodes.push({ ...node, id: name } as Node);
+    this.nodeNames.push(name);
+    return this as unknown as SequentialTestBuilder<NodeNames | Name>;
+  }
+
+  wait<Name extends string>(
+    name: Name,
+    duration: WaitDuration,
+  ): SequentialTestBuilder<NodeNames | Name> {
+    const node = Wait(duration);
+    this.nodes.push({ ...node, id: name } as Node);
+    this.nodeNames.push(name);
+    return this as unknown as SequentialTestBuilder<NodeNames | Name>;
+  }
+
+  assert(
+    callback: AssertionCallback<NodeNames>,
+  ): SequentialTestBuilder<NodeNames> {
+    const stateProxy = createStateProxy(this.nodeNames as NodeNames[]);
+    const serializedAssertions = callback(stateProxy);
+
+    const nodeName = this.generateNodeName();
+    const node = Assertion(serializedAssertions);
+    this.nodes.push({ ...node, id: nodeName } as Node);
+    this.nodeNames.push(nodeName);
+    return this as unknown as SequentialTestBuilder<NodeNames>;
+  }
+
+  build(): RawPlan {
+    const { name, frequency, locations } = this.config;
+    const edges: Edge[] = [];
+
+    // If no nodes, return empty plan with just START->END
+    if (this.nodes.length === 0) {
+      return {
+        name,
+        frequency,
+        locations,
+        version: TEST_PLAN_VERSION,
+        nodes: [],
+        edges: [{ from: START, to: END }],
+      };
+    }
+
+    // Connect START to first node
+    edges.push({ from: START, to: this.nodes[0].id });
+
+    // Connect consecutive nodes
+    for (let i = 0; i < this.nodes.length - 1; i++) {
+      edges.push({
+        from: this.nodes[i].id,
+        to: this.nodes[i + 1].id,
+      });
+    }
+
+    // Connect last node to END
+    edges.push({ from: this.nodes[this.nodes.length - 1].id, to: END });
+
+    return {
+      name,
+      version: TEST_PLAN_VERSION,
+      frequency,
+      locations,
+      nodes: this.nodes,
+      edges,
+    };
+  }
+}
+
+/**
+ * Creates a sequential test builder for simple linear test flows.
+ *
+ * Unlike createGraphBuilder, this builder automatically manages edges
+ * based on the order in which nodes are added. Perfect for straightforward
+ * sequential tests where you don't need complex branching logic.
+ *
+ * @param config - Test configuration
+ * @param config.name - Name of the test
+ * @param config.frequency - Optional frequency for scheduled execution
+ * @param config.locations - Optional array of location identifiers where this test should run
+ * @returns A new SequentialTestBuilder instance
+ *
+ * @example
+ * ```typescript
+ * import { createTestBuilder, POST, GET, Json, Frequency, Assert } from "griffin-ts";
+ *
+ * const plan = createTestBuilder({
+ *   name: "create-and-verify-user",
+ *   frequency: Frequency.every(5).minute(),
+ *   locations: ["us-east-1", "eu-west-1"]
+ * })
+ *   .request("create_user", {
+ *     method: POST,
+ *     path: "/api/v1/users",
+ *     response_format: Json,
+ *     body: { name: "Test User", email: "test@example.com" }
+ *   })
+ *   .assert((state) => [
+ *     Assert(state["create_user"].status).equals(201),
+ *     Assert(state["create_user"].body["data"]["id"]).not.isNull(),
+ *   ])
+ *   .request("get_user", {
+ *     method: GET,
+ *     path: "/api/v1/users/123",
+ *     response_format: Json
+ *   })
+ *   .assert((state) => [
+ *     Assert(state["get_user"].status).equals(200),
+ *     Assert(state["get_user"].body["data"]["name"]).equals("Test User"),
+ *   ])
+ *   .build();
+ * ```
+ */
+export function createTestBuilder(config: {
+  name: string;
+  frequency?: Frequency;
+  locations?: string[];
+}): SequentialTestBuilder {
+  return new SequentialTestBuilderImpl(config);
+}

package/src/shared.ts

@@ -0,0 +1,46 @@
+import {
+  TSchema,
+  TSchemaOptions,
+  TUnsafe,
+  Static,
+  Unsafe,
+  Type,
+} from "typebox";
+import { Value } from "typebox/value";
+import { Memory } from "typebox/system";
+
+export function Ref<T extends TSchema>(
+  t: T,
+  options: TSchemaOptions = {},
+): TUnsafe<Static<T>> {
+  const id = (t as unknown as Record<string, string | undefined>).$id;
+  if (!id) {
+    throw new Error("missing ID on schema");
+  }
+  return Unsafe<Static<T>>({ ...t, $ref: id, $id: undefined, ...options });
+}
+
+export class TUnionOneOf<Types extends TSchema[] = TSchema[]> extends Type.Base<
+  TSchema[]
+> {
+  public oneOf: Types;
+  constructor(oneOf: Types) {
+    super();
+    this.oneOf = oneOf;
+  }
+}
+export function UnionOneOf(oneOf: TSchema[]): TUnionOneOf {
+  return new TUnionOneOf(oneOf);
+}
+
+//export interface TUnionOneOf<Types extends TSchema[] = TSchema[]> extends TSchema {
+//  '~kind': 'UnionOneOf'
+//  //static: { [K in keyof Types]: Static<Types[K]> }[number]
+//  oneOf: Types
+//}
+//
+//export function UnionOneOf<Types extends TSchema[]>(oneOf: [...Types], options: TSchemaOptions = {}) {
+//  return { ...options, ["~kind"]: 'UnionOneOf', oneOf } as TUnionOneOf<Types>
+//
+//  ///return Memory.Create({ '~kind': 'UnionOneOf' }, { oneOf }, options) as never
+//}

package/src/target.ts

@@ -0,0 +1,55 @@
+/**
+ * Target reference utilities for griffin DSL.
+ *
+ * Targets are resolved at runtime by the runner based on the execution environment.
+ * This allows the same test to run against different environments (staging, production, etc.)
+ * without changing the test code.
+ */
+
+import { TargetRef } from "./schema.js";
+
+/**
+ * Create a target reference for endpoint base URLs.
+ *
+ * The runner will resolve this to the appropriate base URL based on the
+ * execution environment (passed as a per-run parameter).
+ *
+ * @param key - The target identifier (e.g., "billing-service", "api-gateway")
+ * @returns A target reference object
+ *
+ * @example
+ * ```typescript
+ * builder.addNode("billing", Endpoint({
+ *   method: GET,
+ *   path: "/invoices",
+ *   base: target("billing-service"),
+ *   response_format: JSON
+ * }));
+ * ```
+ */
+export function target(key: string): TargetRef {
+  if (!key || typeof key !== "string") {
+    throw new Error(`Target key must be a non-empty string. Got: ${key}`);
+  }
+
+  if (key.trim() === "") {
+    throw new Error("Target key cannot be empty or whitespace only");
+  }
+
+  return {
+    type: "target",
+    key: key.trim(),
+  };
+}
+
+/**
+ * Type guard to check if a value is a target reference.
+ */
+export function isTargetRef(value: unknown): value is TargetRef {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+
+  const obj = value as Record<string, unknown>;
+  return obj.type === "target" && typeof obj.key === "string";
+}

package/src/type-exports.ts

@@ -0,0 +1,20 @@
+/**
+ * Static types derived from TypeBox schemas.
+ * Import from "griffin/types" for TypeScript type checking.
+ */
+
+export type {
+  TargetRef,
+  Endpoint,
+  Frequency,
+  Wait,
+  BinaryPredicate,
+  JSONAssertion,
+  XMLAssertion,
+  TextAssertion,
+  Assertion,
+  Assertions,
+  Node,
+  Edge,
+  TestPlanV1,
+} from "./schema.js";

package/src/wait.ts

@@ -0,0 +1,4 @@
+export const WaitDuration = {
+  minutes: (value: number) => ({ minutes: value }),
+  seconds: (value: number) => ({ seconds: value }),
+};

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "node"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}