@doctreen/cloud

Official doctreen cloud store. Plugs into drift.store and batches drift events, heartbeats and route inventories to DocTreen Cloud, where they become coverage, drift signatures and alerts per service and environment.

const { createCloudStore } = require('@doctreen/cloud');

// in your doctreen adapter config:
drift: {
  store: createCloudStore({
    apiKey: process.env.DOCTREEN_API_KEY,
    service: 'billing-api',
  }),
}

The store is fail-open by design: it never throws into the host application, batches in the background, drops to local-only aggregation when no apiKey is configured, and keeps <docsPath>/drift.json working (local: true, the default) so the OSS experience is unchanged.

Options

| Option | Default | Meaning | | --- | --- | --- | | apiKey | — | Service-scoped ingest key from the dashboard. Missing key = local-only mode. | | service | — | Service slug this process reports as. | | environment | DOCTREEN_ENV → NODE_ENV → development | Environment label. | | release | 'auto' | Release label, or auto-detected (git SHA / platform env). | | endpoint | DOCTREEN_ENDPOINT → https://cloud.doctreen.dev | Ingest deployment. | | flushIntervalMs | 10000 | Background flush period (floor 1000). | | maxBatchEvents | 100 | Entries per envelope, clamped to [1, 500]. | | local | true | Keep aggregating locally for <docsPath>/drift.json. | | debug | false | Print problems with console.warn; silence is the contract. |

Requires doctreen >= 1.17 (optional peer — the store also works standalone against the wire protocol).

Reporting flow runs

DocTreen Cloud does not execute flows — your CI and post-deploy jobs already do, and they hold the secrets and the network reach. This package reports the result, so a flow's history, the step that broke it and the release it broke on end up next to the drift data for the same service.

npx doctreen-cloud-flow run flows/checkout.json \
  --service billing-api \
  --base-url https://staging.example.com \
  --env staging \
  --input token=$TOKEN --secret $TOKEN

The exit code is the flow's own: 0 when it passed, 1 when it did not. Reporting never changes it — an unreachable cloud prints a warning and leaves a green deploy green. Without DOCTREEN_API_KEY the flow still runs and simply is not reported.

Request and response content IS stored for flow runs, unlike drift events, because synthetic traffic is the team's own and the exchange is what makes a broken step readable. Credential headers (authorization, cookie, set-cookie, proxy-authorization, x-api-key, x-auth-token) are redacted before sending, bodies are truncated at 8 KB, and every --secret value is scrubbed wherever it appears. Add more header names with --redact-header.

Running flows through your own harness instead? reportFlowRun(result, options) takes any runFlow result:

const { reportFlowRun } = require('@doctreen/cloud');

const result = await runFlow(flow, { baseUrl });
await reportFlowRun(result, { apiKey: process.env.DOCTREEN_API_KEY, service: 'billing-api' });