Task #3: MVP API — payment-gated jobs + demo endpoint

OpenAPI spec (lib/api-spec/openapi.yaml) - Added POST /jobs, GET /jobs/{id}, GET /demo endpoints - Added schemas: CreateJobRequest, CreateJobResponse, JobStatusResponse, InvoiceInfo, JobState, DemoResponse, ErrorResponse - Ran codegen: generated CreateJobBody, GetJobResponse, RunDemoQueryParams etc. Jobs router (artifacts/api-server/src/routes/jobs.ts) - POST /jobs: validates body, creates LNbits eval invoice, inserts job + invoice in a DB transaction, returns { jobId, evalInvoice } - GET /jobs/🆔 fetches job, calls advanceJob() helper, returns state- appropriate payload (eval/work invoice, reason, result, errorMessage) - advanceJob() state machine: - awaiting_eval_payment: checks LNbits, atomically marks paid + advances state via optimistic WHERE state='awaiting_eval_payment'; runs AgentService.evaluateRequest, branches to awaiting_work_payment or rejected - awaiting_work_payment: same pattern for work invoice, runs AgentService.executeWork, advances to complete - Any agent/LNbits error transitions job to failed Demo router (artifacts/api-server/src/routes/demo.ts) - GET /demo?request=...: in-memory rate limiter (5 req/hour per IP) - Explicit guard for missing request param (coerce.string() workaround) - Calls AgentService.executeWork directly, returns { result } Dev router (artifacts/api-server/src/routes/dev.ts) - POST /dev/stub/pay/:paymentHash: marks stub invoice paid in-memory - Only mounted when NODE_ENV !== 'production' Route index updated to mount all three routers replit.md: documented full curl flow with all 6 steps, demo endpoint, and dev stub-pay trigger End-to-end verified with curl: - Full flow: create → eval pay → evaluating → work pay → executing → complete - Error cases: 400 on missing body/param, 404 on unknown job
2026-03-18 15:31:26 +00:00
parent 9ec5e20a10
commit 4e8adbcb93
19 changed files with 1050 additions and 6 deletions
--- a/lib/api-client-react/src/generated/api.schemas.ts
+++ b/lib/api-client-react/src/generated/api.schemas.ts
@@ -8,3 +8,52 @@
 export interface HealthStatus {
  status: string;
 }
+
+export interface ErrorResponse {
+  error: string;
+}
+
+export interface InvoiceInfo {
+  paymentRequest: string;
+  amountSats: number;
+}
+
+export interface CreateJobRequest {
+  /** @minLength 1 */
+  request: string;
+}
+
+export interface CreateJobResponse {
+  jobId: string;
+  evalInvoice: InvoiceInfo;
+}
+
+export type JobState = (typeof JobState)[keyof typeof JobState];
+
+export const JobState = {
+  awaiting_eval_payment: "awaiting_eval_payment",
+  evaluating: "evaluating",
+  rejected: "rejected",
+  awaiting_work_payment: "awaiting_work_payment",
+  executing: "executing",
+  complete: "complete",
+  failed: "failed",
+} as const;
+
+export interface JobStatusResponse {
+  jobId: string;
+  state: JobState;
+  evalInvoice?: InvoiceInfo;
+  workInvoice?: InvoiceInfo;
+  reason?: string;
+  result?: string;
+  errorMessage?: string;
+}
+
+export interface DemoResponse {
+  result: string;
+}
+
+export type RunDemoParams = {
+  request: string;
+};
--- a/lib/api-client-react/src/generated/api.ts
+++ b/lib/api-client-react/src/generated/api.ts
@@ -5,18 +5,29 @@
 * API specification
 * OpenAPI spec version: 0.1.0
 */
-import { useQuery } from "@tanstack/react-query";
+import { useMutation, useQuery } from "@tanstack/react-query";
 import type {
+  MutationFunction,
  QueryFunction,
  QueryKey,
+  UseMutationOptions,
+  UseMutationResult,
  UseQueryOptions,
  UseQueryResult,
 } from "@tanstack/react-query";

-import type { HealthStatus } from "./api.schemas";
+import type {
+  CreateJobRequest,
+  CreateJobResponse,
+  DemoResponse,
+  ErrorResponse,
+  HealthStatus,
+  JobStatusResponse,
+  RunDemoParams,
+} from "./api.schemas";

 import { customFetch } from "../custom-fetch";
-import type { ErrorType } from "../custom-fetch";
+import type { ErrorType, BodyType } from "../custom-fetch";

 type AwaitedInput<T> = PromiseLike<T> | T;

@@ -99,3 +110,253 @@ export function useHealthCheck<

  return { ...query, queryKey: queryOptions.queryKey };
 }
+
+/**
+ * Accepts a request, creates a job row, and issues an eval fee Lightning invoice.
+ * @summary Create a new agent job
+ */
+export const getCreateJobUrl = () => {
+  return `/api/jobs`;
+};
+
+export const createJob = async (
+  createJobRequest: CreateJobRequest,
+  options?: RequestInit,
+): Promise<CreateJobResponse> => {
+  return customFetch<CreateJobResponse>(getCreateJobUrl(), {
+    ...options,
+    method: "POST",
+    headers: { "Content-Type": "application/json", ...options?.headers },
+    body: JSON.stringify(createJobRequest),
+  });
+};
+
+export const getCreateJobMutationOptions = <
+  TError = ErrorType<ErrorResponse>,
+  TContext = unknown,
+>(options?: {
+  mutation?: UseMutationOptions<
+    Awaited<ReturnType<typeof createJob>>,
+    TError,
+    { data: BodyType<CreateJobRequest> },
+    TContext
+  >;
+  request?: SecondParameter<typeof customFetch>;
+}): UseMutationOptions<
+  Awaited<ReturnType<typeof createJob>>,
+  TError,
+  { data: BodyType<CreateJobRequest> },
+  TContext
+> => {
+  const mutationKey = ["createJob"];
+  const { mutation: mutationOptions, request: requestOptions } = options
+    ? options.mutation &&
+      "mutationKey" in options.mutation &&
+      options.mutation.mutationKey
+      ? options
+      : { ...options, mutation: { ...options.mutation, mutationKey } }
+    : { mutation: { mutationKey }, request: undefined };
+
+  const mutationFn: MutationFunction<
+    Awaited<ReturnType<typeof createJob>>,
+    { data: BodyType<CreateJobRequest> }
+  > = (props) => {
+    const { data } = props ?? {};
+
+    return createJob(data, requestOptions);
+  };
+
+  return { mutationFn, ...mutationOptions };
+};
+
+export type CreateJobMutationResult = NonNullable<
+  Awaited<ReturnType<typeof createJob>>
+>;
+export type CreateJobMutationBody = BodyType<CreateJobRequest>;
+export type CreateJobMutationError = ErrorType<ErrorResponse>;
+
+/**
+ * @summary Create a new agent job
+ */
+export const useCreateJob = <
+  TError = ErrorType<ErrorResponse>,
+  TContext = unknown,
+>(options?: {
+  mutation?: UseMutationOptions<
+    Awaited<ReturnType<typeof createJob>>,
+    TError,
+    { data: BodyType<CreateJobRequest> },
+    TContext
+  >;
+  request?: SecondParameter<typeof customFetch>;
+}): UseMutationResult<
+  Awaited<ReturnType<typeof createJob>>,
+  TError,
+  { data: BodyType<CreateJobRequest> },
+  TContext
+> => {
+  return useMutation(getCreateJobMutationOptions(options));
+};
+
+/**
+ * Returns current job state. Automatically advances the state machine when a pending invoice is found to be paid.
+ * @summary Get job status
+ */
+export const getGetJobUrl = (id: string) => {
+  return `/api/jobs/${id}`;
+};
+
+export const getJob = async (
+  id: string,
+  options?: RequestInit,
+): Promise<JobStatusResponse> => {
+  return customFetch<JobStatusResponse>(getGetJobUrl(id), {
+    ...options,
+    method: "GET",
+  });
+};
+
+export const getGetJobQueryKey = (id: string) => {
+  return [`/api/jobs/${id}`] as const;
+};
+
+export const getGetJobQueryOptions = <
+  TData = Awaited<ReturnType<typeof getJob>>,
+  TError = ErrorType<ErrorResponse>,
+>(
+  id: string,
+  options?: {
+    query?: UseQueryOptions<Awaited<ReturnType<typeof getJob>>, TError, TData>;
+    request?: SecondParameter<typeof customFetch>;
+  },
+) => {
+  const { query: queryOptions, request: requestOptions } = options ?? {};
+
+  const queryKey = queryOptions?.queryKey ?? getGetJobQueryKey(id);
+
+  const queryFn: QueryFunction<Awaited<ReturnType<typeof getJob>>> = ({
+    signal,
+  }) => getJob(id, { signal, ...requestOptions });
+
+  return {
+    queryKey,
+    queryFn,
+    enabled: !!id,
+    ...queryOptions,
+  } as UseQueryOptions<Awaited<ReturnType<typeof getJob>>, TError, TData> & {
+    queryKey: QueryKey;
+  };
+};
+
+export type GetJobQueryResult = NonNullable<Awaited<ReturnType<typeof getJob>>>;
+export type GetJobQueryError = ErrorType<ErrorResponse>;
+
+/**
+ * @summary Get job status
+ */
+
+export function useGetJob<
+  TData = Awaited<ReturnType<typeof getJob>>,
+  TError = ErrorType<ErrorResponse>,
+>(
+  id: string,
+  options?: {
+    query?: UseQueryOptions<Awaited<ReturnType<typeof getJob>>, TError, TData>;
+    request?: SecondParameter<typeof customFetch>;
+  },
+): UseQueryResult<TData, TError> & { queryKey: QueryKey } {
+  const queryOptions = getGetJobQueryOptions(id, options);
+
+  const query = useQuery(queryOptions) as UseQueryResult<TData, TError> & {
+    queryKey: QueryKey;
+  };
+
+  return { ...query, queryKey: queryOptions.queryKey };
+}
+
+/**
+ * Runs the agent without payment. Limited to 5 requests per IP per hour.
+ * @summary Free demo (rate-limited)
+ */
+export const getRunDemoUrl = (params: RunDemoParams) => {
+  const normalizedParams = new URLSearchParams();
+
+  Object.entries(params || {}).forEach(([key, value]) => {
+    if (value !== undefined) {
+      normalizedParams.append(key, value === null ? "null" : value.toString());
+    }
+  });
+
+  const stringifiedParams = normalizedParams.toString();
+
+  return stringifiedParams.length > 0
+    ? `/api/demo?${stringifiedParams}`
+    : `/api/demo`;
+};
+
+export const runDemo = async (
+  params: RunDemoParams,
+  options?: RequestInit,
+): Promise<DemoResponse> => {
+  return customFetch<DemoResponse>(getRunDemoUrl(params), {
+    ...options,
+    method: "GET",
+  });
+};
+
+export const getRunDemoQueryKey = (params?: RunDemoParams) => {
+  return [`/api/demo`, ...(params ? [params] : [])] as const;
+};
+
+export const getRunDemoQueryOptions = <
+  TData = Awaited<ReturnType<typeof runDemo>>,
+  TError = ErrorType<ErrorResponse>,
+>(
+  params: RunDemoParams,
+  options?: {
+    query?: UseQueryOptions<Awaited<ReturnType<typeof runDemo>>, TError, TData>;
+    request?: SecondParameter<typeof customFetch>;
+  },
+) => {
+  const { query: queryOptions, request: requestOptions } = options ?? {};
+
+  const queryKey = queryOptions?.queryKey ?? getRunDemoQueryKey(params);
+
+  const queryFn: QueryFunction<Awaited<ReturnType<typeof runDemo>>> = ({
+    signal,
+  }) => runDemo(params, { signal, ...requestOptions });
+
+  return { queryKey, queryFn, ...queryOptions } as UseQueryOptions<
+    Awaited<ReturnType<typeof runDemo>>,
+    TError,
+    TData
+  > & { queryKey: QueryKey };
+};
+
+export type RunDemoQueryResult = NonNullable<
+  Awaited<ReturnType<typeof runDemo>>
+>;
+export type RunDemoQueryError = ErrorType<ErrorResponse>;
+
+/**
+ * @summary Free demo (rate-limited)
+ */
+
+export function useRunDemo<
+  TData = Awaited<ReturnType<typeof runDemo>>,
+  TError = ErrorType<ErrorResponse>,
+>(
+  params: RunDemoParams,
+  options?: {
+    query?: UseQueryOptions<Awaited<ReturnType<typeof runDemo>>, TError, TData>;
+    request?: SecondParameter<typeof customFetch>;
+  },
+): UseQueryResult<TData, TError> & { queryKey: QueryKey } {
+  const queryOptions = getRunDemoQueryOptions(params, options);
+
+  const query = useQuery(queryOptions) as UseQueryResult<TData, TError> & {
+    queryKey: QueryKey;
+  };
+
+  return { ...query, queryKey: queryOptions.queryKey };
+}