uptic-sdk

Report errors and structured logs to Uptic from Node, Bun, Deno or the browser.

Isomorphic — the only platform API it needs is fetch.

Install

npm install uptic-sdk

Inside an Uptic script

The script runner injects credentials, so there is nothing to configure:

const { uptic } = require('uptic-sdk');

async function fetch(payload, context) {
  const client = uptic();

  client.info('starting', { trigger: context.type });

  return client.wrap(async () => {
    const result = await doTheWork(payload);
    client.info('done', { count: result.length });
    return result;
  });
}

wrap() reports whatever throws and then rethrows, so the execution is still recorded as failed.

In a browser or mobile app

There is no environment to inject into, so pass a public ingest key (pk_…, created under Settings → API Keys → Public Ingest Keys). Never ship an sk_ API key to a client — it carries full workspace permissions.

import { uptic, installGlobalHandlers } from 'uptic-sdk';

const client = uptic({
  baseUrl: 'https://app.uptic.run',
  ingestKey: 'pk_your_public_key',
  service: 'web',
  release: __COMMIT_SHA__,
});

installGlobalHandlers(client); // uncaught errors + unhandled rejections

Restrict the key to your own origins in the same settings page.

API

| Method | What it does | | --- | --- | | uptic(config?) | Get (and configure) the shared client | | captureError(error, options?) | Report one error. Resolves true if accepted | | captureBatch(events) | Report several in one request | | wrap(fn, options?) | Run fn, report anything it throws, rethrow | | log(level, message, meta?) | One JSON line to stdout/stderr, and ship it to the Logs page | | info / warn / error / debug | Shorthands for log | | flush() | Send buffered log lines now | | config(name, fallback?) | Read an injected env value | | installGlobalHandlers(client?) | Browser: catch uncaught errors |

Config

Every field falls back to an environment variable, which is what the script runner sets:

| Option | Env var | | --- | --- | | baseUrl | UPTIC_BASE_URL | | ingestKey | UPTIC_INGEST_KEY | | service | UPTIC_WORKER_ID (else "default") | | environment | UPTIC_ENVIRONMENT | | release | UPTIC_RELEASE |

Two guarantees

Reporting never throws. captureError resolves false on a network failure rather than rejecting. A monitoring call that takes down the thing it monitors is worse than a missing data point.

Logging never blocks. log() writes one JSON line to stdout/stderr synchronously, so the script runner captures it and it works offline. When a baseUrl and ingestKey are configured the line is also buffered and posted to the Logs page, once a second or every 50 lines, under sourceName = service. The timer never keeps a process alive, so call flush() before a short-lived process exits; wrap() does this for you.