@satakedev/yatagarasu

Yatagarasu (八咫烏) — the three-legged crow of Japanese myth, a guide and messenger. This SDK is the crow that gathers your app's logs and carries them home, without ever getting in your way.

A tiny, dependency-free log collector SDK. It batches log records in memory and ships them to a Yatagarasu ingestion endpoint in the background — fire-and-forget, safe by design: logging never blocks your code and never throws into it.

Install

npm install @satakedev/yatagarasu
# or: pnpm add @satakedev/yatagarasu

Requires Node.js >= 18 (uses the global fetch and AbortController). Ships dual ESM + CJS builds with type definitions.

Usage

import { createLogger } from '@satakedev/yatagarasu'

const log = createLogger({
  apiKey: process.env.YATAGARASU_KEY!,
  project: 'my-app',
})

log.info('user logged in', { userId: 42 })
log.warn('payment retry', { attempt: 1 })
log.error('payment failed', { orderId, trace_id: 'abc-123' })
log.debug('received payload', { body })

// Before shutting down (also runs automatically on beforeExit/SIGTERM/SIGINT):
await log.flush()
await log.close()

trace_id can be passed inside meta — it is lifted to the top-level field expected by the ingestion API; the rest of meta is sent as-is.

Options

| Option | Default | Description | | ----------------- | --------------------------------------------- | -------------------------------------------- | | apiKey | — | Project API key (Authorization: Bearer). | | project | — | Project identifier. | | endpoint | https://yatagarasu.satake.dev/api/ingest | Ingestion URL. | | flushIntervalMs | 5000 | Flush at least this often. | | flushSize | 50 | Flush as soon as this many records buffer. | | maxBufferSize | 1000 | Hard cap; oldest records dropped past it. | | requestTimeoutMs| 10000 | Per-request timeout (via AbortController). | | maxRetries | 5 | Retry attempts for a failing batch. | | fetch | global fetch | Injectable fetch (tests / custom transport). | | onError | — | Observability hook; errors never reach you. |

Robustness contract

| Aspect | Behavior | | --------------- | -------------------------------------------------------------------- | | Logging methods | Never block, never throw — they only enqueue. | | Flush | By time (flushIntervalMs) or size (flushSize). | | Transport | POST { logs: [...] } with Authorization: Bearer <apiKey>. | | Network / 5xx | Exponential backoff with jitter, up to maxRetries. | | 429 | Honors Retry-After when present. | | 4xx (not 429) | Not retried (bad payload / auth); batch is dropped, onError fired. | | Buffer full | Drops the oldest records (FIFO) — never grows unbounded. | | Failed batch | Returned to the buffer (respecting the cap) for a later retry. | | Shutdown | Auto-flush on beforeExit / SIGTERM / SIGINT (Node only). | | Errors | Routed to onError; never propagated to the caller. |

License

MIT