{"_id":"@beeverlabs/auralogger","_rev":"3-3baceab7e1155da649b6e06d06890104","name":"@beeverlabs/auralogger","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@beeverlabs/auralogger","version":"1.0.0","keywords":["logger","logs","auralogger"],"author":{"name":"Bhanu Vardhan Reddy Nanavala"},"license":"ISC","_id":"@beeverlabs/auralogger@1.0.0","maintainers":[{"name":"hustlingbeever","email":"nbhanuvardhanreddy@gmail.com"}],"homepage":"https://auralogger.com","bugs":{"url":"https://github.com/Beever-Labs/auralogger-node/issues"},"bin":{"auralogger":"dist/bin/auralogger.js"},"dist":{"shasum":"23ec62f78c825ef7d36da783302881ac92cb1ad7","tarball":"https://registry.npmjs.org/@beeverlabs/auralogger/-/auralogger-1.0.0.tgz","fileCount":62,"integrity":"sha512-arZk+BpKwx82oDBJ6iaUQiP/IW3m3RUXGt4elpavCIsIBt8zNYZBVRY06BqPyl9clAqVSdpVwDJ0X8f0tMLiWQ==","signatures":[{"sig":"MEYCIQCnilFIYfKSb8Q2YPEXG0546gRPeiipyoI7jy/YYAxioAIhALSeNPBQv6JRZs1fiK04zLTjHNyMfK7Q36PrDek5Ymnu","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":95141},"main":"dist/index.js","type":"commonjs","types":"dist/index.d.ts","engines":{"node":">=18"},"gitHead":"28f6be05d3489c1ec97a48a624ba720e0baf2c46","scripts":{"test":"npm run build && node dist/test-logger.js","build":"tsc","prepare":"npm run build"},"_npmUser":{"name":"hustlingbeever","email":"nbhanuvardhanreddy@gmail.com"},"repository":{"url":"git+https://github.com/Beever-Labs/auralogger-node.git","type":"git"},"_npmVersion":"11.6.2","description":"advanced logger for Agents and an experience for devs","directories":{"doc":"docs"},"_nodeVersion":"24.13.0","dependencies":{"ws":"^8.20.0","chalk":"^4.1.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/ws":"^8.18.1","typescript":"^5.9.3","@types/node":"^25.5.0"},"_npmOperationalInternal":{"tmp":"tmp/auralogger_1.0.0_1774679040484_0.13040971874297536","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Package moved to auralogger"},"1.0.1":{"name":"@beeverlabs/auralogger","version":"1.0.1","keywords":["logger","logs","auralogger"],"author":{"name":"Bhanu Vardhan Reddy Nanavala"},"license":"ISC","_id":"@beeverlabs/auralogger@1.0.1","maintainers":[{"name":"hustlingbeever","email":"nbhanuvardhanreddy@gmail.com"}],"homepage":"https://auralogger.com","bugs":{"url":"https://github.com/Beever-Labs/auralogger-node/issues"},"bin":{"auralogger":"dist/bin/auralogger.js"},"dist":{"shasum":"a32526d76581b08a2c59b9ed3c18301dcfda7f28","tarball":"https://registry.npmjs.org/@beeverlabs/auralogger/-/auralogger-1.0.1.tgz","fileCount":62,"integrity":"sha512-uK512nqd7OfEaLrbIKBYM+u9myYv+Ou13Vwlh2mlS4mu6LxvhLmyP6NTirT9WqFVZSb63gIu7lCanF8ADqg2+Q==","signatures":[{"sig":"MEQCICxPMYGpyvpQnryA3YwDCvMZ3Py6lWU8ikalKjBwNt6JAiAy7jvxBKDY0CHnU1i0+gZGP3K/kiLzMvzE5Byk2+0JOA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":102808},"main":"dist/index.js","type":"commonjs","types":"dist/index.d.ts","engines":{"node":">=18"},"gitHead":"799f7b858f87890bf6dd73aa3e4436208e2872bf","scripts":{"test":"npm run build && node dist/test-logger.js","build":"tsc","prepare":"npm run build"},"_npmUser":{"name":"hustlingbeever","email":"nbhanuvardhanreddy@gmail.com"},"repository":{"url":"git+https://github.com/Beever-Labs/auralogger-node.git","type":"git"},"_npmVersion":"11.6.2","description":"Auralogger SDK and CLI for Node: terminal logs, websocket ingest, and filtered get-logs for agents.","directories":{},"_nodeVersion":"24.13.0","dependencies":{"ws":"^8.20.0","chalk":"^4.1.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/ws":"^8.18.1","typescript":"^5.9.3","@types/node":"^25.5.0"},"_npmOperationalInternal":{"tmp":"tmp/auralogger_1.0.1_1774679560184_0.21748792605116996","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Package moved to auralogger"}},"time":{"created":"2026-03-28T06:24:00.413Z","modified":"2026-03-28T06:45:03.702Z","1.0.0":"2026-03-28T06:24:00.658Z","1.0.1":"2026-03-28T06:32:40.325Z"},"bugs":{"url":"https://github.com/Beever-Labs/auralogger-node/issues"},"author":{"name":"Bhanu Vardhan Reddy Nanavala"},"license":"ISC","homepage":"https://auralogger.com","keywords":["logger","logs","auralogger"],"repository":{"url":"git+https://github.com/Beever-Labs/auralogger-node.git","type":"git"},"description":"Auralogger SDK and CLI for Node: terminal logs, websocket ingest, and filtered get-logs for agents.","maintainers":[{"name":"hustlingbeever","email":"nbhanuvardhanreddy@gmail.com"}],"readme":"# @beeverlabs/auralogger\r\n\r\nTerminal-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).\r\n\r\n---\r\n\r\n## At a glance\r\n\r\n```mermaid\r\nflowchart TB\r\n  subgraph install [1. Your machine]\r\n    PKG[\"npm install @beeverlabs/auralogger\"]\r\n    APP[Your Node app]\r\n    PKG --> APP\r\n  end\r\n  subgraph cloud [2. Auralogger]\r\n    WEB[auralogger.com]\r\n    PROJ[Project + API secret]\r\n    WEB --> PROJ\r\n  end\r\n  subgraph local [3. Project folder]\r\n    INIT[\"auralogger init\"]\r\n    CFG[\"auralogger.config.json\"]\r\n    INIT --> CFG\r\n  end\r\n  PROJ -->|\"copy secret\"| INIT\r\n  CFG -->|\"auraLog() + websocket\"| cloud\r\n```\r\n\r\n| You want to… | Do this |\r\n|--------------|---------|\r\n| Send logs from code | `import { auraLog } from '@beeverlabs/auralogger'` (after `init`) |\r\n| Set up this repo folder | Run `auralogger init` in the project root |\r\n| Fetch logs in the terminal | `auralogger get-logs` with filters (see below) |\r\n\r\n---\r\n\r\n## Getting started\r\n\r\n### 1. Install\r\n\r\nRequires **Node.js 18+**.\r\n\r\n```bash\r\nnpm install @beeverlabs/auralogger\r\n```\r\n\r\nOptional global CLI (same binary name):\r\n\r\n```bash\r\nnpm install -g @beeverlabs/auralogger\r\n```\r\n\r\nYou can also run one-off commands with `npx`:\r\n\r\n```bash\r\nnpx @beeverlabs/auralogger init\r\n```\r\n\r\n### 2. Create a project on Auralogger\r\n\r\n1. Open **[auralogger.com](https://auralogger.com)** and sign in.\r\n2. Create a **project** (or open an existing one).  \r\n   This is the workspace your logs and API secret belong to.\r\n\r\n### 3. Get your secret API key\r\n\r\nIn the Auralogger UI, open your project and copy the **secret / API key** (the credential the CLI and runtime use to authenticate).\r\n\r\nUse it in either of these ways:\r\n\r\n| Approach | When to use |\r\n|----------|-------------|\r\n| **Environment variable** | Set `AURALOGGER_SECRET_KEY` in your shell or `.env` (recommended for CI and teams). |\r\n| **`auralogger init` prompt** | Run `init` in a terminal; paste the key when asked (no env var required). |\r\n\r\nThe CLI also accepts a key already stored in `auralogger.config.json` if you run `init` again to refresh config.\r\n\r\n### 4. Connect this folder: `auralogger init`\r\n\r\nEvery command uses your **current working directory** as the project root.\r\n\r\n```bash\r\ncd /path/to/your-app\r\nauralogger init\r\n```\r\n\r\n`init` talks to Auralogger, then writes **`auralogger.config.json`** in that folder (and tries to add it to `.gitignore`).\r\n\r\n### 5. About `auralogger.config.json`\r\n\r\nAfter 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).\r\n\r\n- **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.\r\n- **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.\r\n\r\n---\r\n\r\n## Log from your Node app\r\n\r\nThe 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).\r\n\r\n**`auraLog(type, message, location?, data?)`**\r\n\r\n- **`type`**: string, e.g. `\"info\"`, `\"error\"`, `\"warn\"`.\r\n- **`message`**: string.\r\n- **`location`** (optional): string, e.g. file or module name.\r\n- **`data`** (optional): plain object (serialized to JSON for the wire format).\r\n\r\n**CommonJS**\r\n\r\n```js\r\nconst { auraLog } = require(\"@beeverlabs/auralogger\");\r\n\r\nauraLog(\"info\", \"Server listening\", \"server.js\", { port: 3000 });\r\n```\r\n\r\n**ESM**\r\n\r\n```js\r\nimport { auraLog } from \"@beeverlabs/auralogger\";\r\n\r\nauraLog(\"error\", \"Payment failed\", \"checkout.js\", { orderId: \"42\" });\r\n```\r\n\r\nLogs are printed in the terminal (styled using your config) and sent to Auralogger over WebSocket. Failures are reported to stderr; your app keeps running.\r\n\r\n---\r\n\r\n## CLI commands\r\n\r\nGeneral form:\r\n\r\n```bash\r\nauralogger <command> [arguments...]\r\n```\r\n\r\nThere are **no subcommand flags** (`--verbose`, etc.) on `init`, `reset`, or `server-check`. Only `get-logs` takes structured filter arguments.\r\n\r\n### `auralogger init`\r\n\r\n| | |\r\n|--|--|\r\n| **Purpose** | Authenticate with your secret, fetch project config from Auralogger, write `auralogger.config.json`. |\r\n| **Arguments** | None. |\r\n| **Secret source** | `AURALOGGER_SECRET_KEY`, or existing `secret_key` in config, or interactive prompt. |\r\n\r\n```bash\r\nauralogger init\r\n```\r\n\r\n### `auralogger reset`\r\n\r\n| | |\r\n|--|--|\r\n| **Purpose** | Delete `auralogger.config.json` in the current directory. |\r\n| **Arguments** | None. |\r\n\r\n```bash\r\nauralogger reset\r\n```\r\n\r\nIf the file is already missing, the CLI says there is nothing to remove.\r\n\r\n### `auralogger server-check`\r\n\r\n| | |\r\n|--|--|\r\n| **Purpose** | Verify that the WebSocket endpoint is reachable using your current `project_id` and secret. |\r\n| **Arguments** | None. |\r\n| **Requires** | Valid `auralogger.config.json` with `project_id` and a resolvable secret (`AURALOGGER_SECRET_KEY` or `secret_key` in config). |\r\n\r\n```bash\r\nauralogger server-check\r\n```\r\n\r\n### `auralogger get-logs`\r\n\r\n| | |\r\n|--|--|\r\n| **Purpose** | Query the Auralogger API and print matching logs in the terminal. |\r\n| **Arguments** | Zero or more **filters** (see below). |\r\n| **Requires** | Valid config in the current directory (same secret story as above). |\r\n\r\n#### Filter grammar\r\n\r\nEach filter is a triple:\r\n\r\n```text\r\n-<field> [--<operator>] <json-value>\r\n```\r\n\r\nRules:\r\n\r\n- **`<field>`** starts with `-` (e.g. `-type`, `-message`, `-data.userId`).\r\n- **`--<operator>`** is optional; if omitted, a default operator applies per field.\r\n- **`<json-value>`** must be valid JSON:\r\n  - For **`maxcount`** and **`skip`**: a JSON **number**.\r\n  - For all other fields: a JSON **array** (even for a single value).\r\n\r\n#### Fields and operators\r\n\r\n| Field | Operators | Default operator | Value |\r\n|-------|-----------|------------------|--------|\r\n| `type` | `in`, `not-in` | `in` | JSON array of strings |\r\n| `message` | `contains`, `not-contains` | `contains` | JSON array of strings |\r\n| `location` | `in`, `not-in` | `in` | JSON array |\r\n| `time` | `since`, `from-to` | `since` | JSON array (e.g. relative like `\"10m\"`) |\r\n| `order` | `eq` | `eq` | JSON array: `[\"newest-first\"]` or `[\"oldest-first\"]` |\r\n| `maxcount` | `eq` | `eq` | JSON number (`0`–`100`) |\r\n| `skip` | `eq` | `eq` | JSON number (≥ `0`) |\r\n| `data.<path>` | `eq` | `eq` | JSON array |\r\n\r\n#### Examples\r\n\r\n```bash\r\n# Latest errors and warnings, up to 50 rows\r\nauralogger get-logs -type '[\"error\",\"warn\"]' -maxcount 50\r\n\r\n# Message contains \"timeout\", skip first 20 rows\r\nauralogger get-logs -message '[\"timeout\"]' -skip 20 -maxcount 30\r\n\r\n# Exclude info/debug; only logs since 10 minutes ago\r\nauralogger get-logs -type --not-in '[\"info\",\"debug\"]' -time --since '[\"10m\"]'\r\n\r\n# Match nested data field\r\nauralogger get-logs -data.userId '[\"06431f39-55e2-4289-80c8-5d0340a8b66e\"]'\r\n```\r\n\r\n#### Typical parse errors (what they mean)\r\n\r\n| Message | Meaning |\r\n|---------|---------|\r\n| `Expected 'get-logs'` | Arguments before the first filter are wrong; the first token after `get-logs` should start a filter. |\r\n| `Expected field at position N` | Missing `-field` where a filter was expected. |\r\n| `Missing value for field 'x'` | Operator or field without a JSON value. |\r\n| `Invalid JSON for field 'x'` | Value is not valid JSON. |\r\n| `Field 'x' expects a JSON array token` | That field requires an array value. |\r\n| `Field 'maxcount' expects a JSON number token` | `maxcount` / `skip` need a number, not an array. |\r\n| `Invalid op 'x' for field 'y'` | Operator not allowed for that field. |\r\n| `Unknown filter field: x` | Field name not recognized. |\r\n\r\n---\r\n\r\n## Optional environment variable (users)\r\n\r\n| Variable | Purpose |\r\n|----------|---------|\r\n| `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`. |\r\n\r\nProduction traffic uses Auralogger’s default HTTP and WebSocket endpoints. You do not need to set base URLs for normal use.\r\n\r\n---\r\n\r\n## First-time checklist\r\n\r\n```bash\r\ncd your-project\r\nnpm install @beeverlabs/auralogger\r\n# set AURALOGGER_SECRET_KEY or be ready to paste at prompt\r\nauralogger init\r\nauralogger server-check\r\nauralogger get-logs -maxcount 20\r\n```\r\n\r\n---\r\n\r\n## Contributing and advanced topics\r\n\r\n**End-user documentation ends above.**\r\n\r\nContributor 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.\r\n\r\n- **Repository:** [github.com/Beever-Labs/auralogger-node](https://github.com/Beever-Labs/auralogger-node)  \r\n- **Issues:** [github.com/Beever-Labs/auralogger-node/issues](https://github.com/Beever-Labs/auralogger-node/issues)  \r\n- **Product:** [auralogger.com](https://auralogger.com)\r\n","readmeFilename":"readme.md"}