@blyp/core 0.1.21 → 0.1.23

package/README.md

@@ -1,159 +1,73 @@
 # Blyp Logger
 
-> **Blyp HQ** (`Blyphq`) is the GitHub org behind the Blyp project.
-
-> *The silent observer for your applications*
-
-**Blyp** is a high-performance, runtime-adaptive logger for standalone apps and modern TypeScript web frameworks. It combines Bun-friendly runtime detection, structured NDJSON file logging, browser-to-server log ingestion, and framework-specific HTTP logging helpers.
+**Blyp** is a TypeScript logger for standalone apps and modern web frameworks.
+It gives you structured logging, framework adapters, client-to-server log ingestion, and optional connectors without turning the root README into a full manual.
 
 [![Bun](https://img.shields.io/badge/Bun-1.2+-000000?style=flat&logo=bun)](https://bun.sh)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178C6?style=flat&logo=typescript)](https://www.typescriptlang.org)
 [![Elysia](https://img.shields.io/badge/Elysia-1.4+-00D8FF?style=flat)](https://elysiajs.com)
 
-## Features
-
-- **Runtime detection** — Automatically optimizes for Bun vs Node.js
-- **TypeScript** — Full type safety throughout
-- **Framework integrations** — Elysia, Hono, Express, Fastify, NestJS, Next.js App Router, React Router, Astro, Nitro, Nuxt, TanStack Start, SvelteKit, Cloudflare Workers
-- **Expo integration** — Mobile client logging for Expo apps with structured backend sync
-- **PostHog connector** — Automatic or manual PostHog log forwarding for server, browser, and Expo flows
-- **Databuddy connector** — Automatic or manual Databuddy log forwarding and handled-error tracking for server, browser, and Expo flows
-- **OTLP connector** — Automatic or manual OpenTelemetry log forwarding for Grafana, Datadog, Honeycomb, and any OTLP-compatible backend
-- **Standalone usage** — Use without any framework
-- **Structured file logging** — NDJSON with size-based rotation and gzip archives
-- **Database logging** — Serverless-friendly persistence with Prisma and Drizzle adapters for Postgres and MySQL
-- **Client log sync** — Browser logs ingested into your backend stream
+## Highlights
 
-## Project structure
-
-```
-blyp/
-├── exports/
-│   ├── client.js              # Public client entry shim
-│   ├── connectors/
-│   │   └── posthog.js         # Public connector entry shims
-│   └── frameworks/
-│       └── elysia.js          # Public framework entry shims
-├── index.ts                   # Main source export bridge
-├── src/
-│   ├── core/                  # Logger runtime and file logging internals
-│   ├── connectors/            # Connector implementations
-│   ├── frameworks/            # Framework implementations
-│   ├── shared/                # Shared runtime/error utilities
-│   └── types/
-│       ├── framework.types.ts # Shared public contracts
-│       ├── connectors/
-│       │   └── posthog.ts     # Connector-specific source types
-│       └── frameworks/
-│           └── elysia.ts      # Framework-specific source types
-├── types/
-│   ├── index.d.ts             # Public type entry shim
-│   ├── connectors/
-│   │   └── posthog.d.ts       # Public connector type shims
-│   └── frameworks/
-│       └── elysia.d.ts        # Public framework type shims
-├── tests/
-│   ├── frameworks/            # One test file per server integration
-│   ├── helpers/               # Shared test utilities
-│   ├── *.test.ts              # Focused core tests
-│   └── README.md              # Test documentation
-└── README.md
-```
+- Use it in standalone apps or with framework adapters.
+- Create structured, request-scoped logs with `createStructuredLog`.
+- Redact common secrets before logs reach output or downstream sinks.
+- Ingest logs from browser and Expo apps into your backend flow.
+- Forward logs to optional connectors such as PostHog, Better Stack, Sentry, Databuddy, and OTLP targets.
+- Built for Bun-first setups with support for supported Node runtimes.
+- Full TypeScript support across the main package and subpath exports.
 
 ## Installation
 
 ```bash
 bun add @blyp/core
-npx expo install expo-network
 ```
 
-Also: `npm install @blyp/core` | `yarn add @blyp/core` | `pnpm add @blyp/core`
+`npm install @blyp/core` | `pnpm add @blyp/core` | `yarn add @blyp/core`
+
+If you use the Expo logger, also install `expo-network`.
 
-## Usage
+```bash
+npx expo install expo-network
+```
 
-### Basic logger
+## Quick start
 
-```typescript
+```ts
 import { logger } from '@blyp/core';
 
-logger.info('Hello world');
-logger.success('Operation completed');
-logger.error('Something went wrong');
-logger.warning('Warning message');
+logger.info('Server started', { port: 3000 });
+logger.success('Connected to database');
+logger.error('Payment failed', { orderId: 'ord_123' });
 ```
 
-### Structured request batches
-
-Standalone usage:
+## Structured logs
 
-```typescript
+```ts
 import { createStructuredLog } from '@blyp/core';
 
-const structuredLog = createStructuredLog('checkout', {
+const log = createStructuredLog('checkout', {
   service: 'web-api',
   level: 'info',
   timestamp: new Date().toISOString(),
 });
 
-structuredLog.set({
+log.set({
   user: { id: 1, plan: 'pro' },
   cart: { items: 3, total: 9999 },
 });
 
-structuredLog.info('user logged in');
-structuredLog.info('item added to cart');
-structuredLog.emit({ status: 200 });
-```
-
-Framework usage with Elysia:
-
-```typescript
-import { createStructuredLog } from '@blyp/core';
-import { Elysia } from 'elysia';
-import { createLogger } from '@blyp/core/elysia';
-
-const app = new Elysia()
-  .use(createLogger({ level: 'info' }))
-  .post('/hello', ({ set }) => {
-    const structuredLog = createStructuredLog<{
-      message: string;
-      level: string;
-      timestamp: string;
-      hostname?: string;
-      port?: number;
-    }>('test', {
-      message: 'Hello Elysia',
-      level: 'info',
-      timestamp: new Date().toISOString(),
-      hostname: app.server?.hostname,
-      port: app.server?.port,
-    });
-
-    structuredLog.info('route started');
-    structuredLog.emit({ status: 200 });
-
-    set.status = 200;
-    return 'ok';
-  });
-```
-
-Inside framework handlers, the imported `createStructuredLog(...)` automatically binds to the active request-scoped logger. Structured logs are emitted only when you call `.emit()`. In framework request loggers, a structured emit replaces that request's normal auto request log. If you mix a request-scoped structured logger with the root `logger` in the same request, Blyp warns once and ignores the root logger call.
-
-### Errors
-
-```typescript
-import { createError } from '@blyp/core';
-
-throw createError({ status: 404, message: 'Not found' });
+log.info('checkout started');
+log.emit({ status: 200 });
 ```
 
-For the full error API (`HTTP_CODES`, `extend`, `create`), see [Full documentation](docs/README.md#errors).
+Inside framework handlers, `createStructuredLog(...)` binds to the active request logger automatically. The final structured record is written when you call `.emit()`.
 
-### Framework integrations
+## Framework example
 
-Blyp supports **Elysia**, **Hono**, **Express**, **Fastify**, **NestJS**, **Next.js**, **React Router**, **Astro**, **Nitro**, **Nuxt**, **TanStack Start**, **SvelteKit**, and **Cloudflare Workers**. Example with Elysia:
+Blyp supports Elysia, Hono, Express, Fastify, NestJS, Next.js App Router, React Router, Astro, Nitro, Nuxt, TanStack Start, SvelteKit, and Cloudflare Workers.
 
-```typescript
+```ts
 import { Elysia } from 'elysia';
 import { createLogger } from '@blyp/core/elysia';
 
@@ -163,424 +77,42 @@ const app = new Elysia()
   .listen(3000);
 ```
 
-For other frameworks, client logging, advanced configuration, and utilities, see [Full documentation](docs/README.md).
-
-### Expo
-
-```typescript
-import { createExpoLogger } from '@blyp/core/expo';
-
-const logger = createExpoLogger({
-  endpoint: 'https://api.example.com/inngest',
-});
-
-logger.info('app mounted');
-```
-
-Expo uses the runtime `fetch` implementation for delivery and `expo-network` for connectivity metadata. Install `expo-network` in your app and use an absolute ingestion URL.
-
-### Database logging
-
-Use `destination: 'database'` when you cannot rely on filesystem writes, such as serverless deployments. Database mode requires an executable config file like `blyp.config.ts` because Prisma and Drizzle adapters are runtime objects.
-
-Prisma:
-
-```typescript
-import { PrismaClient } from '@prisma/client';
-import { createPrismaDatabaseAdapter } from '@blyp/core/database';
-
-const prisma = new PrismaClient();
-
-export default {
-  destination: 'database',
-  database: {
-    dialect: 'postgres',
-    adapter: createPrismaDatabaseAdapter({
-      client: prisma,
-      model: 'blypLog',
-    }),
-  },
-};
-```
-
-Drizzle:
-
-```typescript
-import { createDrizzleDatabaseAdapter } from '@blyp/core/database';
-import { db } from './db';
-import { blypLogs } from './db/schema/blyp';
-
-export default {
-  destination: 'database',
-  database: {
-    dialect: 'mysql',
-    adapter: createDrizzleDatabaseAdapter({
-      db,
-      table: blypLogs,
-    }),
-  },
-};
-```
-
-In database mode, Blyp keeps connectors working as usual and replaces only the primary local persistence backend. Promise-based and hook-driven framework integrations such as Hono, Elysia, Next.js, React Router, Astro, Nitro, Nuxt, SvelteKit, and TanStack Start flush database writes before the request finishes. In callback-style servers, call `await logger.flush()` at your own boundary when you need a hard durability point.
-
-Use the Blyp CLI to scaffold the schema and migrations:
-
-```bash
-blyp logs init --adapter prisma --dialect postgres
-blyp logs init --adapter drizzle --dialect mysql
-```
-
-### Better Stack
-
-Use `connectors.betterstack` when you want Blyp logs forwarded into Better Stack through `@logtail/node`:
-
-```typescript
-export default {
-  connectors: {
-    betterstack: {
-      enabled: true,
-      mode: 'auto',
-      sourceToken: process.env.SOURCE_TOKEN,
-      ingestingHost: process.env.INGESTING_HOST,
-      errorTracking: {
-        dsn: process.env.BETTERSTACK_ERROR_TRACKING_DSN,
-        tracesSampleRate: 1.0,
-      },
-    },
-  },
-};
-```
-
-`INGESTING_HOST` must be a full absolute `http://` or `https://` URL. Blyp does not auto-read `SOURCE_TOKEN` or `INGESTING_HOST`; wire them through your config explicitly.
-
-In `auto` mode, the normal Blyp server loggers forward to Better Stack automatically. In `manual` mode, use `@blyp/core/betterstack`:
-
-```typescript
-import {
-  captureBetterStackException,
-  createBetterStackErrorTracker,
-  createBetterStackLogger,
-  createStructuredBetterStackLogger,
-} from '@blyp/core/betterstack';
-
-createBetterStackLogger().info('manual better stack log');
-createBetterStackErrorTracker().capture(new Error('manual better stack exception'));
-captureBetterStackException(new Error('wrapped better stack exception'));
-
-const structured = createStructuredBetterStackLogger('checkout', {
-  orderId: 'ord_123',
-});
-structured.info('manual start');
-structured.emit({ status: 200 });
-```
-
-When `connectors.betterstack.errorTracking.dsn` is configured, Blyp captures handled server errors into Better Stack error tracking using the Sentry SDK. Client `error` and `critical` logs requested through the Better Stack connector are promoted to exceptions as well.
-
-Browser and Expo loggers can request server-side Better Stack forwarding through the existing ingestion endpoint:
-
-```typescript
-import { createClientLogger } from '@blyp/core/client';
-
-const logger = createClientLogger({
-  endpoint: '/inngest',
-  connector: 'betterstack',
-});
-```
-
-```typescript
-import { createExpoLogger } from '@blyp/core/expo';
-
-const logger = createExpoLogger({
-  endpoint: 'https://api.example.com/inngest',
-  connector: 'betterstack',
-});
-```
-
-The browser and Expo connector flow still posts to Blyp first. Blyp forwards to Better Stack only when the server connector is configured. Browser and Expo apps do not use `@logtail/browser` directly. Workers remain out of scope for this connector.
-
-### PostHog
-
-Use `blyp.config.ts` when you want to read the PostHog project key from the environment:
-
-```typescript
-export default {
-  connectors: {
-    posthog: {
-      enabled: true,
-      mode: 'auto',
-      projectKey: process.env.POSTHOG_PROJECT_KEY,
-      errorTracking: {
-        enabled: true,
-        mode: 'auto',
-      },
-    },
-  },
-};
-```
-
-In `auto` mode, the normal Blyp server loggers forward to PostHog automatically. In `manual` mode, use `@blyp/core/posthog`:
-
-```typescript
-import {
-  capturePosthogException,
-  createPosthogErrorTracker,
-  createPosthogLogger,
-  createStructuredPosthogLogger,
-} from '@blyp/core/posthog';
+See the [framework integration docs](docs/README.md#framework-integrations) for the full adapter matrix and framework-specific examples.
 
-createPosthogLogger().info('manual posthog log');
-createPosthogErrorTracker().capture(new Error('manual posthog exception'));
-capturePosthogException(new Error('wrapped posthog exception'));
-
-const structured = createStructuredPosthogLogger('checkout', { orderId: 'ord_123' });
-structured.info('manual start');
-structured.emit({ status: 200 });
-```
+## More features
 
-`connectors.posthog.errorTracking.mode: 'auto'` also captures Blyp handled server errors and can enable uncaught exception / unhandled rejection autocapture through `enableExceptionAutocapture`.
+- [Automatic redaction](docs/README.md#automatic-redaction) for common secrets, headers, and custom patterns.
+- [Client and Expo logging](docs/README.md#client) for browser and mobile apps that send logs through your backend.
+- [AI tracing](docs/README.md#ai-sdk-tracing) for Vercel AI SDK, Better Agent, OpenAI, Anthropic, and compatible transports.
+- [Database logging](docs/README.md#database-logging) when file persistence is not the right fit.
+- Connector forwarding for [PostHog](docs/README.md#posthog-connector), [Databuddy](docs/README.md#databuddy-connector), [Better Stack](docs/README.md#better-stack-connector), [Sentry](docs/README.md#sentry-connector), and [OTLP](docs/README.md#otlp-connector).
 
-Browser and Expo loggers can request server-side PostHog forwarding through the existing ingestion endpoint:
+## Documentation
 
-```typescript
-import { createClientLogger } from '@blyp/core/client';
-
-const logger = createClientLogger({
-  endpoint: '/inngest',
-  connector: 'posthog',
-});
-```
-
-Client `error` and `critical` logs requested through the PostHog connector are promoted to PostHog exceptions only when server-side PostHog error tracking is enabled in `auto` mode.
-
-The client and Expo connector flow still posts to Blyp first. Blyp forwards to PostHog only when the server connector is configured, and browser or Expo apps do not use `posthog-node` directly. Workers remain out of scope for this connector.
-
-### Databuddy
-
-Use `connectors.databuddy` when you want Blyp logs and handled errors forwarded into Databuddy:
-
-```typescript
-export default {
-  connectors: {
-    databuddy: {
-      enabled: true,
-      mode: 'auto',
-      apiKey: process.env.DATABUDDY_API_KEY,
-      websiteId: process.env.DATABUDDY_WEBSITE_ID,
-      enableBatching: true,
-    },
-  },
-};
-```
-
-Databuddy requires both `apiKey` and `websiteId`. Blyp treats the connector as unavailable until both are configured.
-
-In `auto` mode, normal Blyp server loggers forward to Databuddy automatically and handled errors are captured as Databuddy `error` events. In `manual` mode, use `@blyp/core/databuddy`:
-
-```typescript
-import {
-  captureDatabuddyException,
-  createDatabuddyErrorTracker,
-  createDatabuddyLogger,
-  createStructuredDatabuddyLogger,
-} from '@blyp/core/databuddy';
-
-createDatabuddyLogger().info('manual databuddy log');
-createDatabuddyErrorTracker().capture(new Error('manual databuddy exception'));
-captureDatabuddyException(new Error('wrapped databuddy exception'));
-
-const structured = createStructuredDatabuddyLogger('checkout', { orderId: 'ord_123' });
-structured.info('manual start');
-structured.emit({ status: 200 });
-```
-
-Browser and Expo loggers can request server-side Databuddy forwarding through the existing ingestion endpoint:
-
-```typescript
-import { createClientLogger } from '@blyp/core/client';
-
-const logger = createClientLogger({
-  endpoint: '/inngest',
-  connector: 'databuddy',
-});
-```
-
-Client `error` and `critical` logs requested through the Databuddy connector are promoted to Databuddy `error` events only when server-side Databuddy is enabled in `auto` mode. The client and Expo connector flow still posts to Blyp first. Blyp forwards to Databuddy only when the server connector is configured.
-
-### Sentry
-
-Use `connectors.sentry` when you want Blyp logs forwarded into Sentry Logs:
-
-```typescript
-export default {
-  connectors: {
-    sentry: {
-      enabled: true,
-      mode: 'auto',
-      dsn: process.env.SENTRY_DSN,
-      environment: process.env.SENTRY_ENVIRONMENT,
-      release: process.env.SENTRY_RELEASE,
-    },
-  },
-};
-```
-
-In `auto` mode, normal Blyp server loggers forward to Sentry automatically. In `manual` mode, use `@blyp/core/sentry`:
-
-```typescript
-import { createSentryLogger, createStructuredSentryLogger } from '@blyp/core/sentry';
-
-createSentryLogger().info('manual sentry log');
-
-const structured = createStructuredSentryLogger('checkout', {
-  orderId: 'ord_123',
-});
-structured.info('manual start');
-structured.emit({ status: 200 });
-```
-
-Browser and Expo loggers can request server-side forwarding through Blyp's ingestion endpoint:
-
-```typescript
-import { createClientLogger } from '@blyp/core/client';
-
-const logger = createClientLogger({
-  endpoint: '/inngest',
-  connector: 'sentry',
-});
-```
-
-```typescript
-import { createExpoLogger } from '@blyp/core/expo';
-
-const logger = createExpoLogger({
-  endpoint: 'https://api.example.com/inngest',
-  connector: 'sentry',
-});
-```
-
-The browser and Expo Sentry flow still posts to Blyp first. Blyp forwards to Sentry only when the server connector is configured. If Sentry was already initialized by the app, Blyp reuses that client instead of replacing it.
-
-### OTLP
-
-Use `connectors.otlp` when you want to send logs to named OTLP-compatible backends such as Grafana Cloud, Datadog, Honeycomb, or a self-hosted OpenTelemetry Collector:
-
-```typescript
-export default {
-  connectors: {
-    otlp: [
-      {
-        name: 'grafana',
-        enabled: true,
-        mode: 'auto',
-        endpoint: 'http://localhost:4318',
-        headers: {
-          'x-scope-orgid': process.env.GRAFANA_SCOPE_ID!,
-        },
-        auth: process.env.GRAFANA_AUTH,
-      },
-      {
-        name: 'honeycomb',
-        enabled: true,
-        mode: 'manual',
-        endpoint: 'https://api.honeycomb.io',
-        headers: {
-          'x-honeycomb-team': process.env.HONEYCOMB_API_KEY!,
-        },
-      },
-    ],
-  },
-};
-```
-
-In `auto` mode, normal Blyp server loggers forward to every ready OTLP target automatically. In `manual` mode, use `@blyp/core/otlp` and select a named target:
-
-```typescript
-import { createOtlpLogger, createStructuredOtlpLogger } from '@blyp/core/otlp';
-
-createOtlpLogger({
-  name: 'grafana',
-}).info('manual otlp log');
-
-const structured = createStructuredOtlpLogger(
-  'checkout',
-  { orderId: 'ord_123' },
-  { name: 'honeycomb' }
-);
-structured.info('manual start');
-structured.emit({ status: 200 });
-```
-
-Browser and Expo loggers can request server-side forwarding to a named OTLP target through the existing ingestion endpoint:
-
-```typescript
-import { createClientLogger } from '@blyp/core/client';
-
-const logger = createClientLogger({
-  endpoint: '/inngest',
-  connector: { type: 'otlp', name: 'grafana' },
-});
-```
-
-```typescript
-import { createExpoLogger } from '@blyp/core/expo';
-
-const logger = createExpoLogger({
-  endpoint: 'https://api.example.com/inngest',
-  connector: { type: 'otlp', name: 'grafana' },
-});
-```
-
-The browser and Expo OTLP flows still post to Blyp first. Blyp forwards to the named OTLP target only when that server connector is configured and ready.
-
-Log levels, HTTP request logging, and file logging (rotation, archives, reading stored logs) are documented in [docs](docs/README.md#file-logging).
-
-## Testing
-
-Run tests:
-
-```bash
-bun run test
-```
-
-The suite covers runtime detection, standalone and client logger, file logging, and all framework integrations. For more commands and previews, see [tests/README.md](tests/README.md).
+- [Full documentation](docs/README.md)
+- [Framework integrations](docs/README.md#framework-integrations)
+- [Client and Expo logging](docs/README.md#client)
+- [AI tracing](docs/README.md#ai-sdk-tracing)
+- [Database logging](docs/README.md#database-logging)
+- [PostHog connector](docs/README.md#posthog-connector)
+- [Databuddy connector](docs/README.md#databuddy-connector)
+- [Better Stack connector](docs/README.md#better-stack-connector)
+- [Sentry connector](docs/README.md#sentry-connector)
+- [OTLP connector](docs/README.md#otlp-connector)
+- [Stability policy](STABILITY.md)
+- [Security policy](SECURITY.md)
+- [Contributing](CONTRIBUTING.md)
+- [Test docs](tests/README.md)
 
 ## Development
 
-**Prerequisites:** [Bun](https://bun.sh) 1.2+ (or [Node.js](https://nodejs.org) 18+), [TypeScript](https://www.typescriptlang.org) 5.0+
-
 ```bash
-git clone https://github.com/Blyphq/blyp.git
-cd blyp
 bun install
 bun run test
 bun run build
 bun run type-check
 ```
 
-## Publishing
-
-GitHub Actions publishes the package to npm when a GitHub Release is published. Add an `NPM_TOKEN` repository secret before using the workflow.
-
-## Contributing
-
-Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for how to get set up and submit changes.
-
 ## License
 
-This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.
-
-## Acknowledgments
-
-[Winston](https://github.com/winstonjs/winston) · [Elysia](https://elysiajs.com) · [Chalk](https://github.com/chalk/chalk) · [Bun](https://bun.sh)
-
-## Links
-
-- [GitHub Repository](https://github.com/Blyphq/blyp)
-- [NPM Package](https://www.npmjs.com/package/@blyp/core)
-- [Documentation](docs/README.md)
-- [Issues](https://github.com/Blyphq/blyp/issues)
-
----
-
-*Blyp silently watches over your applications, logging everything that happens under its watchful gaze.*
+MIT