@yottagraph-app/aether-instructions 1.1.17 → 1.1.18

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@yottagraph-app/aether-instructions",
-    "version": "1.1.17",
+    "version": "1.1.18",
     "description": "Cursor rules, commands, and skills for Aether development",
     "files": [
         "rules",

package/rules/api.mdc

@@ -26,6 +26,52 @@ the directory is missing, run `/update_instructions` to install it.
 
 For Lovelace **entity types, properties, relationships, and per-source schemas** (EDGAR, FRED, FDIC, etc.), read the **data-model skill** in `.cursor/skills/data-model/`. Start with `SKILL.md`, then `overview.md` and the source-specific folders. Both skills are distributed via `@yottagraph-app/aether-instructions` and installed during project init.
 
+## Test Before You Build
+
+**Before writing app code that calls the Query Server, test the actual API
+call first and verify the response shape.** This avoids wasted iteration from incorrect
+assumptions about response shapes.
+
+### How to test
+
+The gateway proxy authenticates on your behalf — no Auth0 tokens needed.
+Read `broadchurch.yaml` for the three values you need:
+
+| YAML path | Purpose |
+|---|---|
+| `gateway.url` | Portal Gateway base URL |
+| `tenant.org_id` | Your tenant ID (path segment) |
+| `gateway.qs_api_key` | API key (sent as `X-Api-Key` header) |
+
+Build the request URL as `{gateway.url}/api/qs/{tenant.org_id}/{endpoint}`
+and include the header `X-Api-Key: {gateway.qs_api_key}`.
+
+### Example calls
+
+```bash
+# Variables — read these from broadchurch.yaml
+GW="https://broadchurch-portal-194773164895.us-central1.run.app"
+ORG="org_abc123"
+KEY="qs_..."
+
+# Search for an entity by name
+curl -s "$GW/api/qs/$ORG/entities/search" \
+  -X POST -H "Content-Type: application/json" \
+  -H "X-Api-Key: $KEY" \
+  -d '{"queries":[{"queryId":1,"query":"Microsoft"}],"maxResults":3}'
+
+# Get entity properties (form-encoded)
+curl -s -X POST "$GW/api/qs/$ORG/elemental/entities/properties" \
+  -H "X-Api-Key: $KEY" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  --data-urlencode 'eids=["00416400910670863867"]' \
+  --data-urlencode 'pids=[8,313]' | jq .
+```
+
+`/elemental/find` and `/elemental/entities/properties` require
+`application/x-www-form-urlencoded` with JSON-stringified parameter values.
+All other endpoints accept `application/json`.
+
 ## Client Usage
 
 All API calls go through `useElementalClient()` from `@yottagraph-app/elemental-api/client`.
@@ -78,18 +124,6 @@ All methods return data directly and throw on non-2xx responses.
 | `getNeighborhood` | `(centerNeid, params?)` | Neighboring entities |
 | `getGraphLayout` | `(centerNeid, params?)` | Graph layout for visualization |
 
-**News, events, and sentiment:**
-
-| Method | Signature | Purpose |
-|---|---|---|
-| `getArticle` | `(artid: string)` | Article by ID |
-| `getArticleText` | `(artid: string)` | Article full text |
-| `getEvent` | `(eveid: string)` | Event by ID |
-| `getEventsForEntity` | `(params: { neid, startTime?, endTime? })` | Events involving an entity |
-| `getMentions` | `(params: { neid, startTime?, endTime? })` | Mention codes for entities |
-| `getMentionCounts` | `(params: { neid, ... })` | Bucketed mention counts |
-| `getNamedEntitySentiment` | `(neid: string)` | Sentiment for an entity |
-
 **Other:**
 
 | Method | Signature | Purpose |
@@ -216,7 +250,7 @@ const res = await client.getPropertyValues({
     eids: JSON.stringify([orgNeid]),
     pids: JSON.stringify([filedPid]),
 });
-const docNeids = res.values.map((v) => String(v.value).padStart(20, '0'));
+const docNeids = (res.values ?? []).map((v) => String(v.value).padStart(20, '0'));
 ```
 
 See the **cookbook** rule for a full "Get filings for a company" recipe.
@@ -263,7 +297,7 @@ const res = await client.getPropertyValues({
 });
 
 // 3. Pad IDs to 20 chars to form valid NEIDs
-const docNeids = res.values.map((v: any) => String(v.value).padStart(20, '0'));
+const docNeids = (res.values ?? []).map((v: any) => String(v.value).padStart(20, '0'));
 
 // 4. Get details for each linked entity (response is nested under .report)
 const reports = await Promise.all(

package/rules/cookbook.mdc

@@ -459,7 +459,7 @@ NOT supported — use `getPropertyValues` with the relationship PID instead.
                 pids: JSON.stringify([filedPid]),
             });
 
-            const docNeids = res.values.map((v: any) =>
+            const docNeids = (res.values ?? []).map((v: any) =>
                 String(v.value).padStart(20, '0'),
             );
 

package/skills/test-api-queries/SKILL.md

@@ -1,63 +0,0 @@
----
-name: test-api-queries
-description: Test Elemental API queries before integrating into app code. Use when writing code that calls the query server.
----
-
-# Test API Queries
-
-**When writing code that calls the Query Server, test queries with this CLI tool before integrating them into app code.**
-
-This prevents wasted iteration cycles from incorrect assumptions about API responses.
-
-## Workflow
-
-1. **Test the query** using the CLI tool below
-2. **Verify the response** matches what you expect
-3. **Then write the app code** with confidence
-
-## CLI Tool
-
-Location: `~/.cursor/skills/test-api-queries/query-api.js`
-
-### Requirements
-
-The CLI reads these from the project's `.env` file or shell environment:
-
-- `AUTH0_M2M_DEV_TOKEN` - Auth0 M2M dev token for API access
-- `NUXT_PUBLIC_QUERY_SERVER_ADDRESS` - Query server URL
-
-**Before using this tool**, check that both variables are set in the project's `.env` file. If either is missing or empty, add them to `.env` (see `.env.example` for the format). Tell the user to ask the engineering team for the token value if they don't have it.
-
-### Usage
-
-```bash
-node ~/.cursor/skills/test-api-queries/query-api.js <METHOD> <ENDPOINT> [JSON_PARAMS]
-```
-
-### Examples
-
-```bash
-# Search for entities by name
-node ~/.cursor/skills/test-api-queries/query-api.js POST /entities/search \
-  '{"queries":[{"queryId":1,"query":"Apple"}],"maxResults":3}'
-
-# Get entity details by ID
-node ~/.cursor/skills/test-api-queries/query-api.js GET /entities/00416400910670863867
-
-# Find entities by type
-node ~/.cursor/skills/test-api-queries/query-api.js POST /elemental/find \
-  '{"expression":{"type":"is_type","is_type":{"fid":10}},"limit":5}'
-
-# Find entities with a specific property
-node ~/.cursor/skills/test-api-queries/query-api.js POST /elemental/find \
-  '{"expression":{"type":"comparison","comparison":{"operator":"has_value","pid":313}},"limit":10}'
-
-# Get entity properties
-node ~/.cursor/skills/test-api-queries/query-api.js POST /elemental/entities/properties \
-  '{"eids":["00416400910670863867"],"pids":[8,313]}'
-```
-
-### Notes
-
-- Run from the project directory so the `.env` file is found
-- `/elemental/find` and `/elemental/entities/properties` require form-encoded bodies—the tool handles this automatically

package/skills/test-api-queries/query-api.js

@@ -1,172 +0,0 @@
-#!/usr/bin/env node
-/**
- * Simple CLI tool to query the Elemental API.
- *
- * Auth: set AUTH0_M2M_DEV_TOKEN as an env var or in your .env file.
- * Server: set NUXT_PUBLIC_QUERY_SERVER_ADDRESS in your .env file.
- */
-
-const fs = require('fs');
-const path = require('path');
-
-const FORM_ENCODED_ENDPOINTS = ['/elemental/find', '/elemental/entities/properties'];
-
-function loadEnvFile() {
-    // Try current working directory first (project .env), then script directory
-    const envPaths = [path.join(process.cwd(), '.env'), path.join(__dirname, '.env')];
-
-    for (const envPath of envPaths) {
-        try {
-            const contents = fs.readFileSync(envPath, 'utf8');
-            for (const line of contents.split('\n')) {
-                const trimmed = line.trim();
-                if (!trimmed || trimmed.startsWith('#')) continue;
-                const eqIndex = trimmed.indexOf('=');
-                if (eqIndex === -1) continue;
-                const key = trimmed.slice(0, eqIndex).trim();
-                const value = trimmed.slice(eqIndex + 1).trim();
-                if (!process.env[key]) {
-                    process.env[key] = value;
-                }
-            }
-            return; // Stop after first successful load
-        } catch {
-            // Try next path
-        }
-    }
-}
-
-function requiresFormEncoding(endpoint) {
-    return FORM_ENCODED_ENDPOINTS.some((e) => endpoint.startsWith(e));
-}
-
-function buildFormBody(endpoint, params) {
-    const formParams = new URLSearchParams();
-    for (const [key, value] of Object.entries(params)) {
-        if (typeof value === 'object') {
-            formParams.append(key, JSON.stringify(value));
-        } else {
-            formParams.append(key, String(value));
-        }
-    }
-    return formParams.toString();
-}
-
-async function main() {
-    loadEnvFile();
-
-    const args = process.argv.slice(2);
-
-    if (args.length < 2 || args[0] === '--help' || args[0] === '-h') {
-        console.log(`
-Elemental API Query Tool
-
-Usage:
-  node query-api.js <METHOD> <ENDPOINT> [JSON_PARAMS]
-
-Examples:
-  # Search for entities (JSON body)
-  node query-api.js POST /entities/search '{"queries":[{"queryId":1,"query":"Apple"}],"maxResults":3}'
-
-  # Get entity details
-  node query-api.js GET /entities/00416400910670863867
-
-  # Find entities by expression (auto form-encoded)
-  node query-api.js POST /elemental/find '{"expression":{"type":"is_type","is_type":{"fid":10}},"limit":5}'
-
-  # Find entities with a property value
-  node query-api.js POST /elemental/find '{"expression":{"type":"comparison","comparison":{"operator":"has_value","pid":313}},"limit":10}'
-
-  # Get entity properties (auto form-encoded)
-  node query-api.js POST /elemental/entities/properties '{"eids":["00416400910670863867"],"pids":[8,313]}'
-
-Environment variables (required):
-  AUTH0_M2M_DEV_TOKEN                Bearer token for API auth
-  NUXT_PUBLIC_QUERY_SERVER_ADDRESS     Query server URL (e.g. https://query.news.prod.g.lovelace.ai)
-
-Setup:
-  1. Get a dev token from your team
-  2. Add AUTH0_M2M_DEV_TOKEN to your .env file or export in your shell
-     (NUXT_PUBLIC_QUERY_SERVER_ADDRESS should already be in your .env from project init)
-
-Note: /elemental/find and /elemental/entities/properties require form-encoded bodies.
-      This tool automatically handles the encoding for these endpoints.
-`);
-        process.exit(0);
-    }
-
-    const [method, endpoint, jsonParams] = args;
-
-    const token = process.env.AUTH0_M2M_DEV_TOKEN;
-    if (!token) {
-        console.error('Error: AUTH0_M2M_DEV_TOKEN is not set.');
-        console.error('Add it to your .env file or export it in your shell.');
-        console.error('Run: node query-api.js --help');
-        process.exit(1);
-    }
-
-    let params = {};
-    if (jsonParams) {
-        try {
-            params = JSON.parse(jsonParams);
-        } catch (err) {
-            console.error('Error: Invalid JSON parameters');
-            console.error(err.message);
-            process.exit(1);
-        }
-    }
-
-    const server = process.env.NUXT_PUBLIC_QUERY_SERVER_ADDRESS;
-    if (!server) {
-        console.error('Error: NUXT_PUBLIC_QUERY_SERVER_ADDRESS is not set.');
-        console.error('Add it to your .env file or export it in your shell.');
-        console.error('Run: node query-api.js --help');
-        process.exit(1);
-    }
-
-    const normalizedEndpoint = endpoint.startsWith('/') ? endpoint : '/' + endpoint;
-    let url = `${server}${normalizedEndpoint}`;
-
-    const useFormEncoding = requiresFormEncoding(normalizedEndpoint);
-    const fetchOptions = {
-        method: method.toUpperCase(),
-        headers: {
-            Authorization: `Bearer ${token}`,
-            'Content-Type': useFormEncoding
-                ? 'application/x-www-form-urlencoded'
-                : 'application/json',
-            Accept: 'application/json',
-        },
-    };
-
-    if (method.toUpperCase() === 'GET' && Object.keys(params).length > 0) {
-        const queryString = new URLSearchParams(params).toString();
-        url = `${url}?${queryString}`;
-    } else if (method.toUpperCase() !== 'GET' && Object.keys(params).length > 0) {
-        if (useFormEncoding) {
-            fetchOptions.body = buildFormBody(normalizedEndpoint, params);
-        } else {
-            fetchOptions.body = JSON.stringify(params);
-        }
-    }
-
-    console.error(`\n📡 ${method.toUpperCase()} ${url}\n`);
-
-    try {
-        const response = await fetch(url, fetchOptions);
-        const data = await response.json();
-
-        if (!response.ok) {
-            console.error(`❌ Error ${response.status}: ${response.statusText}`);
-        } else {
-            console.error(`✅ Success (${response.status})\n`);
-        }
-
-        console.log(JSON.stringify(data, null, 2));
-    } catch (err) {
-        console.error('❌ Request failed:', err.message);
-        process.exit(1);
-    }
-}
-
-main();