DUCKGRAPH® LOG INGESTION UNIT
SYS.OK REV 1.0

/// SDK — TYPESCRIPT

TypeScript SDK STABLE

Zero-dependency ESM client — Node 18+ and edge runtimes (fetch + CompressionStream). All sends serialize through an internal promise chain; tail is an async generator. Pass a custom fetchFn if your platform differs.

SHELLINSTALL
npm install ./sdks/typescript   # from the repo — package name "duckgraph"
npm run build                   # tsc → dist/
npm test                        # build + node --test — 17 tests
TYPESCRIPTQUICKSTART
import { Client, DuckgraphLogger } from "duckgraph";

const client = new Client("http://localhost:8080", {
  apiKey: "dgk_…",
  gzip: true,
  batchSize: 512,
});

client.log("info", "myapp", "started", { attrs: { port: 8080 } }); // buffered
await client.send([{ service: "myapp", message: "now" }]);          // direct

const rows = await client.query({ minLevel: "error",
                                  attrs: { env: "prod" } });
await client.close();   // flushes remaining entries

Client

new Client(baseUrl, opts?) arms the flush timer immediately. Client.login(baseUrl, user, pass, opts?) authenticates first and holds the dgs_ session token.

ClientOptionsDefaultPurpose
apiKey—dgk_ API key — recommended for shippers
token—dgs_ session token
batchSize512Max entries per POST
flushIntervalMs2000Buffer flush cadence
queueSize8192Local buffer capacity
gzipfalseCompress request bodies (CompressionStream)
retries3Attempts on 429/5xx/network errors
timeoutMs30000Per-request timeout
onError—Async send-failure callback
fetchFnfetchCustom fetch — edge runtimes, proxies

Ingest

MethodBehaviour
enqueue(entry)Buffer one entry. Throws QueueFullError when full, ClientClosedError after close.
log(level, service, message, {host, attrs, ts})Enqueue sugar.
send(entries) → Promise<number>POST immediately (chunks at 50k). Returns count accepted.
flush() → Promise<void>Drain the queue through the send chain.
droppedEntries rejected by a full queue.
close() → Promise<void>Stop the timer and flush — idempotent.

Entry fields: ts (Date | RFC3339 | epoch s/ms, default server-now), level, service (required), host, message (required), attrs.

DuckgraphLogger

TYPESCRIPTLOGGER
const log = new DuckgraphLogger(client, {
  service: "myapp",
  attrs: { env: "prod" },
});
log.info("request done", { ms: 3200 });
log.error("failed", { err: String(e) });
await log.close();

Level methods: debug, info, warn, error, fatal. Base attrs merge with per-call attrs — the counterpart of the Go SDK's slog handler.

Query & read

MethodEndpointReturns
query(q?)GET /v1/logsPromise<Row[]> newest-first
queryPost(q?)POST /v1/querySame — better for large attr filters
stats(window?, bucket="1m")GET /v1/statsStats — window in seconds or "1h"
services()GET /v1/servicesstring[]
metrics()GET /v1/metricsIngestMetrics (reader+)
system()GET /v1/systemSystemInfo
health() → Promise<boolean>GET /healthzLiveness — no auth
me()GET /v1/auth/mePrincipal
logout()POST /v1/auth/logoutRevoke session
tail(q?)GET /v1/logs/tailAsyncGenerator<Row> — break to close
TYPESCRIPTTAIL
for await (const row of client.tail({ minLevel: "warn" })) {
  console.log(row.level, row.service, row.message, rowAttrs(row));
}

Query fields: from/to (Date | RFC3339 | epoch), levels, minLevel, services, hosts, search, attrs, orderAsc, limit, offset. Row.attrs is the raw JSON string — rowAttrs(row) parses it.

Admin ADMIN ROLE

MethodEndpoint
listUsers()GET /v1/users
createUser(name, password, role)POST /v1/users
updateUser(name, {role, disabled, password})PATCH /v1/users/{name}
deleteUser(name)DELETE /v1/users/{name}
listApiKeys()GET /v1/apikeys
createApiKey(name, role) → APIKeyPOST /v1/apikeys — key.secret shown once
revokeApiKey(id)DELETE /v1/apikeys/{id}
sql(statement) → SQLResultPOST /v1/sql — read-only

Errors: APIError (.status) for non-2xx, QueueFullError / ClientClosedError for local state.