@beeverlabs/auralogger 1.0.0 → 1.0.1

package/dist/bin/auralogger.js

@@ -12,7 +12,7 @@ function printUsage() {
     console.log("  auralogger server-check");
     console.log("  auralogger get-logs [filters...]");
     console.log("");
-    console.log("See docs/infra/bin/get_logs.md for filter syntax.");
+    console.log("Docs: https://www.npmjs.com/package/@beeverlabs/auralogger (get-logs filters)");
 }
 async function main() {
     const args = process.argv.slice(2);

package/dist/bin/auralogger.js.map

@@ -1 +1 @@
-{"version":3,"file":"auralogger.js","sourceRoot":"","sources":["../../src/bin/auralogger.ts"],"names":[],"mappings":";;;AAEA,0CAAyC;AACzC,kCAAkC;AAClC,oCAAoC;AACpC,kDAAiD;AAEjD,SAAS,UAAU;IACjB,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACtB,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;IACjC,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;IAClC,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;IACzC,OAAO,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAC;IAClD,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAChB,OAAO,CAAC,GAAG,CAAC,mDAAmD,CAAC,CAAC;AACnE,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAExB,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,UAAU,EAAE,CAAC;QACb,OAAO;IACT,CAAC;IAED,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACvB,MAAM,IAAA,cAAO,GAAE,CAAC;QAChB,OAAO;IACT,CAAC;IAED,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;QACxB,MAAM,IAAA,gBAAQ,GAAE,CAAC;QACjB,OAAO;IACT,CAAC;IAED,IAAI,OAAO,KAAK,UAAU,EAAE,CAAC;QAC3B,MAAM,IAAA,qBAAU,EAAC,IAAI,CAAC,CAAC;QACvB,OAAO;IACT,CAAC;IAED,IAAI,OAAO,KAAK,cAAc,EAAE,CAAC;QAC/B,MAAM,IAAA,6BAAc,GAAE,CAAC;QACvB,OAAO;IACT,CAAC;IAED,OAAO,CAAC,KAAK,CAAC,oBAAoB,OAAO,EAAE,CAAC,CAAC;IAC7C,UAAU,EAAE,CAAC;IACb,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,CAAC,KAAK,CAAC,eAAe,OAAO,EAAE,CAAC,CAAC;IACxC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"auralogger.js","sourceRoot":"","sources":["../../src/bin/auralogger.ts"],"names":[],"mappings":";;;AAEA,0CAAyC;AACzC,kCAAkC;AAClC,oCAAoC;AACpC,kDAAiD;AAEjD,SAAS,UAAU;IACjB,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACtB,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;IACjC,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;IAClC,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;IACzC,OAAO,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAC;IAClD,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAChB,OAAO,CAAC,GAAG,CAAC,+EAA+E,CAAC,CAAC;AAC/F,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAExB,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,UAAU,EAAE,CAAC;QACb,OAAO;IACT,CAAC;IAED,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACvB,MAAM,IAAA,cAAO,GAAE,CAAC;QAChB,OAAO;IACT,CAAC;IAED,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;QACxB,MAAM,IAAA,gBAAQ,GAAE,CAAC;QACjB,OAAO;IACT,CAAC;IAED,IAAI,OAAO,KAAK,UAAU,EAAE,CAAC;QAC3B,MAAM,IAAA,qBAAU,EAAC,IAAI,CAAC,CAAC;QACvB,OAAO;IACT,CAAC;IAED,IAAI,OAAO,KAAK,cAAc,EAAE,CAAC;QAC/B,MAAM,IAAA,6BAAc,GAAE,CAAC;QACvB,OAAO;IACT,CAAC;IAED,OAAO,CAAC,KAAK,CAAC,oBAAoB,OAAO,EAAE,CAAC,CAAC;IAC7C,UAAU,EAAE,CAAC;IACb,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,CAAC,KAAK,CAAC,eAAe,OAAO,EAAE,CAAC,CAAC;IACxC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beeverlabs/auralogger",
-  "version": "1.0.0",
-  "description": "advanced logger for Agents and an experience for devs",
+  "version": "1.0.1",
+  "description": "Auralogger SDK and CLI for Node: terminal logs, websocket ingest, and filtered get-logs for agents.",
   "keywords": [
     "logger",
     "logs",
@@ -23,9 +23,6 @@
   "bin": {
     "auralogger": "dist/bin/auralogger.js"
   },
-  "directories": {
-    "doc": "docs"
-  },
   "files": [
     "dist"
   ],

package/readme.md

@@ -1,19 +1,276 @@
-This is the **auralogger** Node package. It lets users add logging to their projects: logs appear in the terminal and are sent to Auralogger’s backend over websocket. CLI commands fetch filtered logs for tools and agents.
+# @beeverlabs/auralogger
+
+Terminal-first logging for Node.js: pretty logs locally and the same events streamed to **[Auralogger](https://auralogger.com)**. Includes a small CLI for setup and for pulling filtered logs (great for agents and scripts).
+
+---
+
+## At a glance
+
+```mermaid
+flowchart TB
+  subgraph install [1. Your machine]
+    PKG["npm install @beeverlabs/auralogger"]
+    APP[Your Node app]
+    PKG --> APP
+  end
+  subgraph cloud [2. Auralogger]
+    WEB[auralogger.com]
+    PROJ[Project + API secret]
+    WEB --> PROJ
+  end
+  subgraph local [3. Project folder]
+    INIT["auralogger init"]
+    CFG["auralogger.config.json"]
+    INIT --> CFG
+  end
+  PROJ -->|"copy secret"| INIT
+  CFG -->|"auraLog() + websocket"| cloud
+```
+
+| You want to… | Do this |
+|--------------|---------|
+| Send logs from code | `import { auraLog } from '@beeverlabs/auralogger'` (after `init`) |
+| Set up this repo folder | Run `auralogger init` in the project root |
+| Fetch logs in the terminal | `auralogger get-logs` with filters (see below) |
+
+---
+
+## Getting started
+
+### 1. Install
+
+Requires **Node.js 18+**.
+
+```bash
+npm install @beeverlabs/auralogger
+```
+
+Optional global CLI (same binary name):
+
+```bash
+npm install -g @beeverlabs/auralogger
+```
+
+You can also run one-off commands with `npx`:
+
+```bash
+npx @beeverlabs/auralogger init
+```
+
+### 2. Create a project on Auralogger
+
+1. Open **[auralogger.com](https://auralogger.com)** and sign in.
+2. Create a **project** (or open an existing one).  
+   This is the workspace your logs and API secret belong to.
+
+### 3. Get your secret API key
+
+In the Auralogger UI, open your project and copy the **secret / API key** (the credential the CLI and runtime use to authenticate).
+
+Use it in either of these ways:
+
+| Approach | When to use |
+|----------|-------------|
+| **Environment variable** | Set `AURALOGGER_SECRET_KEY` in your shell or `.env` (recommended for CI and teams). |
+| **`auralogger init` prompt** | Run `init` in a terminal; paste the key when asked (no env var required). |
+
+The CLI also accepts a key already stored in `auralogger.config.json` if you run `init` again to refresh config.
+
+### 4. Connect this folder: `auralogger init`
+
+Every command uses your **current working directory** as the project root.
+
+```bash
+cd /path/to/your-app
+auralogger init
+```
+
+`init` talks to Auralogger, then writes **`auralogger.config.json`** in that folder (and tries to add it to `.gitignore`).
+
+### 5. About `auralogger.config.json`
+
+After a successful `init` you will have a file like `auralogger.config.json` in the project root. It holds **auth and project metadata** the SDK and CLI rely on (including `project_id`, `secret_key`, `session`, and styling info from the server).
+
+- **Do not delete or hand-edit this file** unless you know what you are doing. If it is wrong or missing, run `auralogger init` again from the same folder.
+- **Do not commit secrets.** Keep the file out of git (the CLI attempts to append it to `.gitignore`). Prefer `AURALOGGER_SECRET_KEY` in environment when you want the secret outside the file.
+
+---
+
+## Log from your Node app
+
+The package reads **`auralogger.config.json` from `process.cwd()`**, so run your app from the same directory where you ran `init` (or `cd` there in your process).
+
+**`auraLog(type, message, location?, data?)`**
+
+- **`type`**: string, e.g. `"info"`, `"error"`, `"warn"`.
+- **`message`**: string.
+- **`location`** (optional): string, e.g. file or module name.
+- **`data`** (optional): plain object (serialized to JSON for the wire format).
+
+**CommonJS**
+
+```js
+const { auraLog } = require("@beeverlabs/auralogger");
+
+auraLog("info", "Server listening", "server.js", { port: 3000 });
+```
+
+**ESM**
+
+```js
+import { auraLog } from "@beeverlabs/auralogger";
+
+auraLog("error", "Payment failed", "checkout.js", { orderId: "42" });
+```
+
+Logs are printed in the terminal (styled using your config) and sent to Auralogger over WebSocket. Failures are reported to stderr; your app keeps running.
 
 ---
 
-**User flow**
+## CLI commands
+
+General form:
+
+```bash
+auralogger <command> [arguments...]
+```
+
+There are **no subcommand flags** (`--verbose`, etc.) on `init`, `reset`, or `server-check`. Only `get-logs` takes structured filter arguments.
+
+### `auralogger init`
+
+| | |
+|--|--|
+| **Purpose** | Authenticate with your secret, fetch project config from Auralogger, write `auralogger.config.json`. |
+| **Arguments** | None. |
+| **Secret source** | `AURALOGGER_SECRET_KEY`, or existing `secret_key` in config, or interactive prompt. |
+
+```bash
+auralogger init
+```
+
+### `auralogger reset`
+
+| | |
+|--|--|
+| **Purpose** | Delete `auralogger.config.json` in the current directory. |
+| **Arguments** | None. |
+
+```bash
+auralogger reset
+```
+
+If the file is already missing, the CLI says there is nothing to remove.
+
+### `auralogger server-check`
+
+| | |
+|--|--|
+| **Purpose** | Verify that the WebSocket endpoint is reachable using your current `project_id` and secret. |
+| **Arguments** | None. |
+| **Requires** | Valid `auralogger.config.json` with `project_id` and a resolvable secret (`AURALOGGER_SECRET_KEY` or `secret_key` in config). |
+
+```bash
+auralogger server-check
+```
+
+### `auralogger get-logs`
+
+| | |
+|--|--|
+| **Purpose** | Query the Auralogger API and print matching logs in the terminal. |
+| **Arguments** | Zero or more **filters** (see below). |
+| **Requires** | Valid config in the current directory (same secret story as above). |
+
+#### Filter grammar
+
+Each filter is a triple:
+
+```text
+-<field> [--<operator>] <json-value>
+```
+
+Rules:
 
-1. **Install** — User adds the package. They provide an API token via **`AURALOGGER_SECRET_KEY`** in `.env` or a one-time CLI prompt during **`auralogger init`**. The secret stays in the environment only; it is **not** saved to disk.
-2. **Init** — The CLI calls **`POST /api/proj_auth`** and writes **`auralogger.config.json`** with **`project_id`**, **`name`**, **`role`**, **`profile_id`**, **`styles`**, etc. There is no separate **`sync`** command; re-run **`init`** if you need to refresh config.
-3. **Runtime** — Each log is shown in the terminal (styled from config) and sent over websocket to **`/{project_id}/create_log`**. Failures are logged without crashing the app.
-4. **CLI** — Commands such as **`auralogger get-logs`** call the backend with the same **`secret`** header and print results for agents.
+- **`<field>`** starts with `-` (e.g. `-type`, `-message`, `-data.userId`).
+- **`--<operator>`** is optional; if omitted, a default operator applies per field.
+- **`<json-value>`** must be valid JSON:
+  - For **`maxcount`** and **`skip`**: a JSON **number**.
+  - For all other fields: a JSON **array** (even for a single value).
+
+#### Fields and operators
+
+| Field | Operators | Default operator | Value |
+|-------|-----------|------------------|--------|
+| `type` | `in`, `not-in` | `in` | JSON array of strings |
+| `message` | `contains`, `not-contains` | `contains` | JSON array of strings |
+| `location` | `in`, `not-in` | `in` | JSON array |
+| `time` | `since`, `from-to` | `since` | JSON array (e.g. relative like `"10m"`) |
+| `order` | `eq` | `eq` | JSON array: `["newest-first"]` or `["oldest-first"]` |
+| `maxcount` | `eq` | `eq` | JSON number (`0`–`100`) |
+| `skip` | `eq` | `eq` | JSON number (≥ `0`) |
+| `data.<path>` | `eq` | `eq` | JSON array |
+
+#### Examples
+
+```bash
+# Latest errors and warnings, up to 50 rows
+auralogger get-logs -type '["error","warn"]' -maxcount 50
+
+# Message contains "timeout", skip first 20 rows
+auralogger get-logs -message '["timeout"]' -skip 20 -maxcount 30
+
+# Exclude info/debug; only logs since 10 minutes ago
+auralogger get-logs -type --not-in '["info","debug"]' -time --since '["10m"]'
+
+# Match nested data field
+auralogger get-logs -data.userId '["06431f39-55e2-4289-80c8-5d0340a8b66e"]'
+```
+
+#### Typical parse errors (what they mean)
+
+| Message | Meaning |
+|---------|---------|
+| `Expected 'get-logs'` | Arguments before the first filter are wrong; the first token after `get-logs` should start a filter. |
+| `Expected field at position N` | Missing `-field` where a filter was expected. |
+| `Missing value for field 'x'` | Operator or field without a JSON value. |
+| `Invalid JSON for field 'x'` | Value is not valid JSON. |
+| `Field 'x' expects a JSON array token` | That field requires an array value. |
+| `Field 'maxcount' expects a JSON number token` | `maxcount` / `skip` need a number, not an array. |
+| `Invalid op 'x' for field 'y'` | Operator not allowed for that field. |
+| `Unknown filter field: x` | Field name not recognized. |
+
+---
+
+## Optional environment variable (users)
+
+| Variable | Purpose |
+|----------|---------|
+| `AURALOGGER_SECRET_KEY` | Your project secret, used by `init`, `server-check`, runtime logging, and `get-logs` when you do not rely only on `secret_key` inside `auralogger.config.json`. |
+
+Production traffic uses Auralogger’s default HTTP and WebSocket endpoints. You do not need to set base URLs for normal use.
+
+---
+
+## First-time checklist
+
+```bash
+cd your-project
+npm install @beeverlabs/auralogger
+# set AURALOGGER_SECRET_KEY or be ready to paste at prompt
+auralogger init
+auralogger server-check
+auralogger get-logs -maxcount 20
+```
+
+---
 
-**Base URL:** production defaults to **`https://auralogger.com`** (and the API/WebSocket origins used by the client). For local development, override with env vars such as **`AURALOGGER_API_URL`** / **`AURALOGGER_WS_URL`** (see **`dev-docs/routes.md`**).
+## Contributing and advanced topics
 
-**Docs in this repo**
+**End-user documentation ends above.**
 
-- End users: **`user-docs/commands.md`**
-- Contributors: **`dev-docs/`** (`README.md`, `file-map.md`, `routes.md`)
+Contributor notes (file map, HTTP/WebSocket route reference, local base URL overrides) live **only in the GitHub repository**, under **`dev-docs/`**. Those files are **not** part of the published npm package tarball.
 
-**Source:** [github.com/Beever-Labs/auralogger-node](https://github.com/Beever-Labs/auralogger-node)
+- **Repository:** [github.com/Beever-Labs/auralogger-node](https://github.com/Beever-Labs/auralogger-node)  
+- **Issues:** [github.com/Beever-Labs/auralogger-node/issues](https://github.com/Beever-Labs/auralogger-node/issues)  
+- **Product:** [auralogger.com](https://auralogger.com)