Skip to content

[integrations] REST API gateway#12

Open
alanshurafa wants to merge 6 commits intomainfrom
contrib/alanshurafa/rest-api-gateway
Open

[integrations] REST API gateway#12
alanshurafa wants to merge 6 commits intomainfrom
contrib/alanshurafa/rest-api-gateway

Conversation

@alanshurafa
Copy link
Copy Markdown
Owner

Summary

  • REST API gateway with 20 endpoints for non-MCP clients (dashboards, webhooks, ChatGPT Actions, Gemini)
  • Ported from ExoCortex open-brain-rest with OB1 adaptations
  • Full CRUD, semantic + text search, capture with enrichment, stats, ingest proxy, duplicate resolution, knowledge graph entity browsing

Key Features

  • CORS support — wildcard * for browser and Electron clients
  • Three auth methods — query param, header, or Bearer token
  • Sensitivity filtering — restricted content blocked at capture and hidden from queries
  • Smart ingest proxy/ingest and /ingestion-jobs endpoints proxy to the smart-ingest function
  • Knowledge graph/entities endpoints query the graph (optional, requires schema)
  • Duplicate management — find and resolve near-duplicate thought pairs with metadata merging

Files

File Lines Purpose
index.ts 933 REST server with 20 route handlers
_shared/helpers.ts 770 Shared utilities (from enhanced-mcp)
_shared/config.ts 204 Constants and types
README.md 155 Setup guide with endpoint table, auth docs, troubleshooting
metadata.json 18 OB1 contribution metadata
deno.json 5 Deno import map

Test plan

  • Verify gate checks pass
  • Deploy and test /health endpoint
  • Test /search (semantic + text modes)
  • Test /capture with and without skip_classification
  • Test CRUD operations on /thought/:id
  • Test /stats endpoint

🤖 Generated with Claude Code

Documented REST gateway for non-MCP clients providing 20 endpoints
covering search, capture, CRUD, stats, ingest proxy, duplicate
resolution, and knowledge graph entity browsing with CORS support.

Ported from ExoCortex open-brain-rest with OB1 adaptations:
OpenRouter-first provider order, wildcard CORS, thoughts table
(not brain_thoughts), removed applyEvergreenTag dependency.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4046b5fce3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +146 to +148
const thoughtMatch = path.match(/^\/thought\/(\d+)$/);
if (thoughtMatch) {
const id = Number(thoughtMatch[1]);
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Accept UUID thought IDs in route matching

The thought routes currently only match numeric IDs (/^(\\d+)$/), but this repository’s default schema uses UUID thought IDs (docs/01-getting-started.md shows thoughts.id uuid, and schemas/enhanced-thoughts/schema.sql defines get_thought_connections(p_thought_id UUID)). With the current regex and Number(...) coercion, valid UUID URLs like /thought/<uuid> never match and these endpoints return 404 instead of operating on existing thoughts.

Useful? React with 👍 / 👎.

Comment on lines +295 to +296
const result = data as { thought_id: number; action: string; content_fingerprint: string } | null;
if (!result?.thought_id) throw new Error("upsert_thought returned no result");
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Parse upsert_thought response using returned id field

The capture handler assumes upsert_thought returns { thought_id, action, content_fingerprint }, then throws when thought_id is missing. In this repo’s documented setup, upsert_thought returns JSON with id (see docs/01-getting-started.md), and existing server code reads upsertResult?.id; with that standard function, /capture will fail with upsert_thought returned no result even when insert/update succeeded.

Useful? React with 👍 / 👎.

Comment on lines +214 to +217
const filter: Record<string, unknown> = {};
if (excludeRestricted) filter.exclude_restricted = true;
const { data, error } = await supabase.rpc("search_thoughts_text", {
p_query: query, p_limit: limit, p_filter: filter, p_offset: offset,
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Remove exclude flag from metadata filter in text search

In text mode, exclude_restricted is encoded as p_filter.exclude_restricted, but search_thoughts_text applies p_filter as t.metadata @> p_filter (see schemas/enhanced-thoughts/schema.sql) and does not interpret that key as a sensitivity predicate. This means default requests (exclude_restricted true) effectively require each thought’s metadata to contain { "exclude_restricted": true }, causing most text searches to return empty results rather than excluding restricted rows.

Useful? React with 👍 / 👎.

alanshurafa and others added 2 commits April 6, 2026 13:34
Add blank lines around headings (MD022), fenced code blocks (MD031),
and between adjacent blockquotes (MD028). Fix broken link fragment
(MD051) and remove extra blank line (MD012). No content changes.

These errors were blocking CI on all open PRs since the lint check
runs repo-wide.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Each section's numbered list now restarts at 1 instead of continuing
the global count (3-14), satisfying markdownlint MD029/ol-prefix rule.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@github-actions github-actions bot added documentation Improvements or additions to documentation recipe labels Apr 6, 2026
alanshurafa and others added 3 commits April 6, 2026 13:53
… variants

JavaScript Number loses precision beyond 2^53. All ID parsing now uses
string validation instead of Number(). Added extractThoughtId() to
handle all upsert_thought RPC response shapes (scalar, {id}, {thought_id}).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation integration recipe

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant