PapertrailStore — Papertrail hosted log management

PapertrailStore — Papertrail hosted log management Overview Papertrail (by SolarWinds) is a hosted log-management service. Logs are ingested over syslog or an HTTP log destination, and searched via the REST events API. There is no SQL-shaped query surface, no row-level UPDATE/DELETE, and no identifier escaping, so Papertrail does not fit the SQL Dialect interface (src/dialects/dialect.ts). PapertrailStore therefore implements the minimal NoSqlStore marker interface (src/nosql/store.ts) — connection lifecycle plus a getClient() escape hatch — and exposes Papertrail's HTTP log-destination ingest and its REST events-search API (plus group/system metadata) directly. Identity: Property | Value | --------- | --------------- | name | 'papertrail' | library | 'fetch' | Two hosts — ingest vs API Search targets the REST API (apiURL); ingest targets the configured HTTP log destination (ingestURL). The internal fetch client resolves absolute URLs verbatim, so push() posts to the full ingest URL while the search/metadata methods use relative API paths against apiURL. No canonical driver — HTTP over fetch Papertrail has no single canonical npm client; it is an HTTP/JSON API (X-Papertrail-Token auth). This store talks to it with the global fetch (so library is 'fetch'). When no client is injected, an internal client over fetch + apiURL is built at connect() time by createFetchClient(apiURL, headers) (its GET sends Accept: application/json). Injected client PapertrailStoreOptions accepts a pre-built client implementing the PapertrailHttpClient interface. When provided it is used verbatim and apiURL is ignored — this is how the test suite injects a mock (no network). Connection Option | Type | Purpose | ----------- | -------------------------- | ----------------------------------------------------------------------------- | apiURL | string | Base URL of the Papertrail REST API. Defaults to https://papertrailapp.com. | ingestURL | string | Full HTTP log-destination URL that push() ingests to (required for push). | token | string | API token, merged into headers as X-Papertrail-Token. | client | PapertrailHttpClient | Pre-built HTTP client. When set, apiURL is ignored. | headers | Record<string, string> | Extra HTTP headers sent with every request. | Injected-client form Methods Read methods route through an internal doGet, which wraps any client failure in a DatabaseError. Calling a method before connect() (or after disconnect()) throws a ConnectionError. Lifecycle Method | Signature | Behavior | ------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------- | connect | connect(): Promise<void> | Uses an injected client if provided, otherwise builds a fetch client from apiURL. Idempotent. | disconnect | disconnect(): Promise<void> | Clears the client and connection state. | isConnected | isConnected(): boolean | true only when connected and a client is present. | getClient | getClient(): PapertrailHttpClient | Returns the underlying (internal or injected) client. Throws ConnectionError if not connected. | Ingest / search / metadata Method | Signature | Endpoint | Behavior | --------- | ------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------- | push | push(lines: string \| string[]): Promise<any> | POST <ingestURL> (text/plain) | Ingests raw log lines (a single string, or an array joined with newlines) to the configured HTTP log destination. Throws DatabaseError if no ingestURL was configured. | query | query(q: string, options?: PapertrailQueryOptions): Promise<any> | GET /api/v1/events/search.json | Searches log events. Returns the parsed response ({ events, minid, maxid, reachedbeginning, ... }). | labels | labels(): Promise<any> | GET /api/v1/groups.json | Lists the configured log groups. | streams | streams(): Promise<any> | GET /api/v1/systems.json | Lists the configured systems (log senders). | Option shape Example Verification status Unit / mock-verified only. The tests in tests/nosql/papertrail.test.ts are fully mock-driven: an in-memory PapertrailHttpClient that records every request and returns canned responses is injected via PapertrailStoreOptions.client. There is no live Papertrail account and no network in the test run. What this proves: push posts newline-joined lines as text/plain to the exact ingestURL, and throws DatabaseError when no ingestURL is configured. query GETs /api/v1/events/search.json with q and the stringified systemid/mintime/limit filters (unset filters left undefined). labels/streams route to the groups/systems .json endpoints. Lifecycle: idempotent connect(), getClient() returning the injected client, and ConnectionError before connect(). Error handling: client failures wrapped in DatabaseError. What this does not prove: live execution against a real Papertrail account. Request/response shapes are verified against Papertrail's documented HTTP-destination / events-API contract, but end-to-end execution over the wire has not been exercised here. Related reading All data stores — the full catalogue, grouped by purpose Database types — where this sits among the 22 categories