@ghcrawl/api-contract 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PwrDrvr LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@ghcrawl/api-contract",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "ghcrawl shared transport contracts and validation schemas",
+  "author": "PwrDrvr LLC <harold@pwrdrvr.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/pwrdrvr/ghcrawl",
+  "bugs": {
+    "url": "https://github.com/pwrdrvr/ghcrawl/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pwrdrvr/ghcrawl.git"
+  },
+  "keywords": [
+    "ghcrawl",
+    "api",
+    "contracts",
+    "zod"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "zod": "^3.24.1"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsx --test src/*.test.ts src/**/*.test.ts"
+  }
+}

package/src/client.ts

@@ -0,0 +1,135 @@
+import {
+  actionRequestSchema,
+  actionResponseSchema,
+  clusterDetailResponseSchema,
+  clusterSummariesResponseSchema,
+  clustersResponseSchema,
+  healthResponseSchema,
+  refreshRequestSchema,
+  refreshResponseSchema,
+  repositoriesResponseSchema,
+  searchResponseSchema,
+  threadsResponseSchema,
+  type ActionRequest,
+  type ActionResponse,
+  type ClusterDetailResponse,
+  type ClusterSummariesResponse,
+  type ClustersResponse,
+  type HealthResponse,
+  type RefreshRequest,
+  type RefreshResponse,
+  type RepositoriesResponse,
+  type SearchMode,
+  type SearchResponse,
+  type ThreadsResponse,
+} from './contracts.js';
+
+export type GitcrawlClient = {
+  health: () => Promise<HealthResponse>;
+  listRepositories: () => Promise<RepositoriesResponse>;
+  listThreads: (params: { owner: string; repo: string; kind?: 'issue' | 'pull_request' }) => Promise<ThreadsResponse>;
+  search: (params: { owner: string; repo: string; query: string; mode?: SearchMode }) => Promise<SearchResponse>;
+  listClusters: (params: { owner: string; repo: string }) => Promise<ClustersResponse>;
+  listClusterSummaries: (params: {
+    owner: string;
+    repo: string;
+    minSize?: number;
+    limit?: number;
+    sort?: 'recent' | 'size';
+    search?: string;
+  }) => Promise<ClusterSummariesResponse>;
+  getClusterDetail: (params: {
+    owner: string;
+    repo: string;
+    clusterId: number;
+    memberLimit?: number;
+    bodyChars?: number;
+  }) => Promise<ClusterDetailResponse>;
+  refresh: (request: RefreshRequest) => Promise<RefreshResponse>;
+  rerun: (request: ActionRequest) => Promise<ActionResponse>;
+};
+
+type FetchLike = typeof fetch;
+
+async function readJson<T>(res: Response, schema: { parse: (value: unknown) => T }): Promise<T> {
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new Error(`API request failed ${res.status} ${res.statusText}: ${text.slice(0, 2000)}`);
+  }
+  const value = (await res.json()) as unknown;
+  return schema.parse(value);
+}
+
+export function createGitcrawlClient(baseUrl: string, fetchImpl: FetchLike = fetch): GitcrawlClient {
+  const normalized = baseUrl.replace(/\/+$/, '');
+
+  return {
+    async health() {
+      const res = await fetchImpl(`${normalized}/health`);
+      return readJson(res, healthResponseSchema);
+    },
+    async listRepositories() {
+      const res = await fetchImpl(`${normalized}/repositories`);
+      return readJson(res, repositoriesResponseSchema);
+    },
+    async listThreads(params) {
+      const search = new URLSearchParams({ owner: params.owner, repo: params.repo });
+      if (params.kind) search.set('kind', params.kind);
+      const res = await fetchImpl(`${normalized}/threads?${search.toString()}`);
+      return readJson(res, threadsResponseSchema);
+    },
+    async search(params) {
+      const search = new URLSearchParams({
+        owner: params.owner,
+        repo: params.repo,
+        query: params.query,
+      });
+      if (params.mode) search.set('mode', params.mode);
+      const res = await fetchImpl(`${normalized}/search?${search.toString()}`);
+      return readJson(res, searchResponseSchema);
+    },
+    async listClusters(params) {
+      const search = new URLSearchParams({ owner: params.owner, repo: params.repo });
+      const res = await fetchImpl(`${normalized}/clusters?${search.toString()}`);
+      return readJson(res, clustersResponseSchema);
+    },
+    async listClusterSummaries(params) {
+      const search = new URLSearchParams({ owner: params.owner, repo: params.repo });
+      if (params.minSize !== undefined) search.set('minSize', String(params.minSize));
+      if (params.limit !== undefined) search.set('limit', String(params.limit));
+      if (params.sort) search.set('sort', params.sort);
+      if (params.search) search.set('search', params.search);
+      const res = await fetchImpl(`${normalized}/cluster-summaries?${search.toString()}`);
+      return readJson(res, clusterSummariesResponseSchema);
+    },
+    async getClusterDetail(params) {
+      const search = new URLSearchParams({
+        owner: params.owner,
+        repo: params.repo,
+        clusterId: String(params.clusterId),
+      });
+      if (params.memberLimit !== undefined) search.set('memberLimit', String(params.memberLimit));
+      if (params.bodyChars !== undefined) search.set('bodyChars', String(params.bodyChars));
+      const res = await fetchImpl(`${normalized}/cluster-detail?${search.toString()}`);
+      return readJson(res, clusterDetailResponseSchema);
+    },
+    async refresh(request) {
+      const body = refreshRequestSchema.parse(request);
+      const res = await fetchImpl(`${normalized}/actions/refresh`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+      });
+      return readJson(res, refreshResponseSchema);
+    },
+    async rerun(request) {
+      const body = actionRequestSchema.parse(request);
+      const res = await fetchImpl(`${normalized}/actions/rerun`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+      });
+      return readJson(res, actionResponseSchema);
+    },
+  };
+}

package/src/contracts.test.ts

@@ -0,0 +1,85 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { actionRequestSchema, healthResponseSchema, neighborsResponseSchema, searchResponseSchema } from './contracts.js';
+
+test('health schema accepts configured status payload', () => {
+  const parsed = healthResponseSchema.parse({
+    ok: true,
+    configPath: '/Users/example/.config/ghcrawl/config.json',
+    configFileExists: true,
+    dbPath: 'data/ghcrawl.db',
+    apiPort: 5179,
+    githubConfigured: true,
+    openaiConfigured: false,
+  });
+
+  assert.equal(parsed.apiPort, 5179);
+});
+
+test('search schema rejects invalid mode', () => {
+  assert.throws(() =>
+    searchResponseSchema.parse({
+      repository: {
+        id: 1,
+        owner: 'openclaw',
+        name: 'openclaw',
+        fullName: 'openclaw/openclaw',
+        githubRepoId: null,
+        updatedAt: new Date().toISOString(),
+      },
+      query: 'panic',
+      mode: 'invalid',
+      hits: [],
+    }),
+  );
+});
+
+test('action request accepts optional thread number', () => {
+  const parsed = actionRequestSchema.parse({
+    owner: 'openclaw',
+    repo: 'openclaw',
+    action: 'summarize',
+    threadNumber: 42,
+  });
+
+  assert.equal(parsed.threadNumber, 42);
+});
+
+test('neighbors schema accepts repository, source thread, and neighbor list', () => {
+  const parsed = neighborsResponseSchema.parse({
+    repository: {
+      id: 1,
+      owner: 'openclaw',
+      name: 'openclaw',
+      fullName: 'openclaw/openclaw',
+      githubRepoId: null,
+      updatedAt: new Date().toISOString(),
+    },
+    thread: {
+      id: 10,
+      repoId: 1,
+      number: 42,
+      kind: 'issue',
+      state: 'open',
+      title: 'Downloader hangs',
+      body: 'The transfer never finishes.',
+      authorLogin: 'alice',
+      htmlUrl: 'https://github.com/openclaw/openclaw/issues/42',
+      labels: ['bug'],
+      updatedAtGh: new Date().toISOString(),
+      clusterId: null,
+    },
+    neighbors: [
+      {
+        threadId: 11,
+        number: 43,
+        kind: 'pull_request',
+        title: 'Fix downloader hang',
+        score: 0.93,
+      },
+    ],
+  });
+
+  assert.equal(parsed.neighbors[0].number, 43);
+});

package/src/contracts.ts

@@ -0,0 +1,229 @@
+import { z } from 'zod';
+
+export const threadKindSchema = z.enum(['issue', 'pull_request']);
+export type ThreadKind = z.infer<typeof threadKindSchema>;
+
+export const searchModeSchema = z.enum(['keyword', 'semantic', 'hybrid']);
+export type SearchMode = z.infer<typeof searchModeSchema>;
+
+export const repositorySchema = z.object({
+  id: z.number().int().positive(),
+  owner: z.string(),
+  name: z.string(),
+  fullName: z.string(),
+  githubRepoId: z.string().nullable(),
+  updatedAt: z.string(),
+});
+export type RepositoryDto = z.infer<typeof repositorySchema>;
+
+export const threadSchema = z.object({
+  id: z.number().int().positive(),
+  repoId: z.number().int().positive(),
+  number: z.number().int().positive(),
+  kind: threadKindSchema,
+  state: z.string(),
+  title: z.string(),
+  body: z.string().nullable(),
+  authorLogin: z.string().nullable(),
+  htmlUrl: z.string().url(),
+  labels: z.array(z.string()),
+  updatedAtGh: z.string().nullable(),
+  clusterId: z.number().int().positive().nullable().optional(),
+});
+export type ThreadDto = z.infer<typeof threadSchema>;
+
+export const healthResponseSchema = z.object({
+  ok: z.boolean(),
+  configPath: z.string(),
+  configFileExists: z.boolean(),
+  dbPath: z.string(),
+  apiPort: z.number().int().positive(),
+  githubConfigured: z.boolean(),
+  openaiConfigured: z.boolean(),
+});
+export type HealthResponse = z.infer<typeof healthResponseSchema>;
+
+export const repositoriesResponseSchema = z.object({
+  repositories: z.array(repositorySchema),
+});
+export type RepositoriesResponse = z.infer<typeof repositoriesResponseSchema>;
+
+export const threadsResponseSchema = z.object({
+  repository: repositorySchema,
+  threads: z.array(threadSchema),
+});
+export type ThreadsResponse = z.infer<typeof threadsResponseSchema>;
+
+export const neighborSchema = z.object({
+  threadId: z.number().int().positive(),
+  number: z.number().int().positive(),
+  kind: threadKindSchema,
+  title: z.string(),
+  score: z.number(),
+});
+export type NeighborDto = z.infer<typeof neighborSchema>;
+
+export const searchHitSchema = z.object({
+  thread: threadSchema,
+  keywordScore: z.number().nullable(),
+  semanticScore: z.number().nullable(),
+  hybridScore: z.number(),
+  neighbors: z.array(neighborSchema).default([]),
+});
+export type SearchHitDto = z.infer<typeof searchHitSchema>;
+
+export const searchResponseSchema = z.object({
+  repository: repositorySchema,
+  query: z.string(),
+  mode: searchModeSchema,
+  hits: z.array(searchHitSchema),
+});
+export type SearchResponse = z.infer<typeof searchResponseSchema>;
+
+export const neighborsResponseSchema = z.object({
+  repository: repositorySchema,
+  thread: threadSchema,
+  neighbors: z.array(neighborSchema),
+});
+export type NeighborsResponse = z.infer<typeof neighborsResponseSchema>;
+
+export const clusterMemberSchema = z.object({
+  threadId: z.number().int().positive(),
+  number: z.number().int().positive(),
+  kind: threadKindSchema,
+  title: z.string(),
+  scoreToRepresentative: z.number().nullable(),
+});
+export type ClusterMemberDto = z.infer<typeof clusterMemberSchema>;
+
+export const clusterSchema = z.object({
+  id: z.number().int().positive(),
+  repoId: z.number().int().positive(),
+  representativeThreadId: z.number().int().positive().nullable(),
+  memberCount: z.number().int().nonnegative(),
+  members: z.array(clusterMemberSchema),
+});
+export type ClusterDto = z.infer<typeof clusterSchema>;
+
+export const clustersResponseSchema = z.object({
+  repository: repositorySchema,
+  clusters: z.array(clusterSchema),
+});
+export type ClustersResponse = z.infer<typeof clustersResponseSchema>;
+
+export const repoStatsSchema = z.object({
+  openIssueCount: z.number().int().nonnegative(),
+  openPullRequestCount: z.number().int().nonnegative(),
+  lastGithubReconciliationAt: z.string().nullable(),
+  lastEmbedRefreshAt: z.string().nullable(),
+  staleEmbedThreadCount: z.number().int().nonnegative(),
+  staleEmbedSourceCount: z.number().int().nonnegative(),
+  latestClusterRunId: z.number().int().positive().nullable(),
+  latestClusterRunFinishedAt: z.string().nullable(),
+});
+export type RepoStatsDto = z.infer<typeof repoStatsSchema>;
+
+export const clusterSummarySchema = z.object({
+  clusterId: z.number().int().positive(),
+  displayTitle: z.string(),
+  totalCount: z.number().int().nonnegative(),
+  issueCount: z.number().int().nonnegative(),
+  pullRequestCount: z.number().int().nonnegative(),
+  latestUpdatedAt: z.string().nullable(),
+  representativeThreadId: z.number().int().positive().nullable(),
+  representativeNumber: z.number().int().positive().nullable(),
+  representativeKind: threadKindSchema.nullable(),
+});
+export type ClusterSummaryDto = z.infer<typeof clusterSummarySchema>;
+
+export const clusterSummariesResponseSchema = z.object({
+  repository: repositorySchema,
+  stats: repoStatsSchema,
+  clusters: z.array(clusterSummarySchema),
+});
+export type ClusterSummariesResponse = z.infer<typeof clusterSummariesResponseSchema>;
+
+export const threadSummariesSchema = z.object({
+  problem_summary: z.string().optional(),
+  solution_summary: z.string().optional(),
+  maintainer_signal_summary: z.string().optional(),
+  dedupe_summary: z.string().optional(),
+});
+export type ThreadSummariesDto = z.infer<typeof threadSummariesSchema>;
+
+export const clusterThreadDumpSchema = z.object({
+  thread: threadSchema,
+  bodySnippet: z.string().nullable(),
+  summaries: threadSummariesSchema,
+});
+export type ClusterThreadDumpDto = z.infer<typeof clusterThreadDumpSchema>;
+
+export const clusterDetailResponseSchema = z.object({
+  repository: repositorySchema,
+  stats: repoStatsSchema,
+  cluster: clusterSummarySchema,
+  members: z.array(clusterThreadDumpSchema),
+});
+export type ClusterDetailResponse = z.infer<typeof clusterDetailResponseSchema>;
+
+export const syncResultSchema = z.object({
+  runId: z.number().int().positive(),
+  threadsSynced: z.number().int().nonnegative(),
+  commentsSynced: z.number().int().nonnegative(),
+  threadsClosed: z.number().int().nonnegative(),
+});
+export type SyncResultDto = z.infer<typeof syncResultSchema>;
+
+export const embedResultSchema = z.object({
+  runId: z.number().int().positive(),
+  embedded: z.number().int().nonnegative(),
+});
+export type EmbedResultDto = z.infer<typeof embedResultSchema>;
+
+export const clusterResultSchema = z.object({
+  runId: z.number().int().positive(),
+  edges: z.number().int().nonnegative(),
+  clusters: z.number().int().nonnegative(),
+});
+export type ClusterResultDto = z.infer<typeof clusterResultSchema>;
+
+export const refreshRequestSchema = z.object({
+  owner: z.string(),
+  repo: z.string(),
+  sync: z.boolean().optional(),
+  embed: z.boolean().optional(),
+  cluster: z.boolean().optional(),
+});
+export type RefreshRequest = z.infer<typeof refreshRequestSchema>;
+
+export const refreshResponseSchema = z.object({
+  repository: repositorySchema,
+  selected: z.object({
+    sync: z.boolean(),
+    embed: z.boolean(),
+    cluster: z.boolean(),
+  }),
+  sync: syncResultSchema.nullable(),
+  embed: embedResultSchema.nullable(),
+  cluster: clusterResultSchema.nullable(),
+});
+export type RefreshResponse = z.infer<typeof refreshResponseSchema>;
+
+export const rerunActionSchema = z.enum(['summarize', 'embed', 'cluster']);
+export type RerunAction = z.infer<typeof rerunActionSchema>;
+
+export const actionRequestSchema = z.object({
+  owner: z.string(),
+  repo: z.string(),
+  action: rerunActionSchema,
+  threadNumber: z.number().int().positive().optional(),
+});
+export type ActionRequest = z.infer<typeof actionRequestSchema>;
+
+export const actionResponseSchema = z.object({
+  ok: z.boolean(),
+  action: rerunActionSchema,
+  runId: z.number().int().positive().nullable(),
+  message: z.string(),
+});
+export type ActionResponse = z.infer<typeof actionResponseSchema>;

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './client.js';
+export * from './contracts.js';