@blyp/core 0.1.2 → 0.1.22

package/README.md

@@ -14,25 +14,27 @@
 
 - **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, TanStack Start, SvelteKit, Cloudflare Workers
+- **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
+- **Connector delivery queue** — Optional server-side memory + SQLite retry queue for connector delivery without Redis
 - **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
+- **AI SDK tracing** — AI SDK middleware-based tracing for `generateText` and `streamText` flows
 
 ## Project structure
 
 ```
 blyp/
-├── exports/
-│   ├── client.js              # Public client entry shim
+├── dist/                      # Published JS and declaration output
 │   ├── connectors/
-│   │   └── posthog.js         # Public connector entry shims
+│   │   └── posthog.js         # Public connector build output
 │   └── frameworks/
-│       └── elysia.js          # Public framework entry shims
+│       └── elysia.js          # Public framework build output
 ├── index.ts                   # Main source export bridge
 ├── src/
 │   ├── core/                  # Logger runtime and file logging internals
@@ -45,12 +47,6 @@ blyp/
 │       │   └── 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
@@ -68,6 +64,10 @@ npx expo install expo-network
 
 Also: `npm install @blyp/core` | `yarn add @blyp/core` | `pnpm add @blyp/core`
 
+## Stability
+
+Blyp publishes a production stability contract in [STABILITY.md](./STABILITY.md). The core logger API, framework adapters, and connector APIs are Stable. Studio UI and CLI commands are Beta. Internal APIs and unexported symbols are Unstable.
+
 ## Usage
 
 ### Basic logger
@@ -138,6 +138,34 @@ const app = new Elysia()
 
 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.
 
+### Automatic redaction
+
+Blyp redacts sensitive values before they reach the console, files, database adapters, connectors, client ingestion, or framework request logs.
+
+Default redacted keys:
+
+`password`, `passwd`, `pwd`, `secret`, `token`, `api_key`, `apikey`, `api_secret`, `authorization`, `auth`, `x-api-key`, `private_key`, `privatekey`, `access_token`, `refresh_token`, `client_secret`, `session`, `cookie`, `set-cookie`, `ssn`, `credit_card`, `card_number`, `cvv`, `cvc`, `otp`, `pin`
+
+Blyp also scans string values for common secret patterns and replaces matches with typed markers such as `[REDACTED:bearer]`, `[REDACTED:jwt]`, `[REDACTED:api_key]`, and `[REDACTED:card]`.
+
+```ts
+export default {
+  redact: {
+    keys: ['my_custom_secret', 'internal_token'],
+    paths: ['user.ssn', 'payment.**.raw'],
+    patterns: [/MY_ORG_[A-Z0-9]{32}/],
+    disablePatternScanning: false,
+  },
+};
+```
+
+Notes:
+
+- `redact.paths` supports exact paths, `*`, and `**`
+- regex `patterns` require executable config such as `blyp.config.ts`
+- request headers such as `Authorization`, `Cookie`, `Set-Cookie`, `X-API-Key`, and `X-Auth-Token` are redacted by default
+- Blyp preserves keys and replaces values with `[REDACTED]` or a typed marker
+
 ### Errors
 
 ```typescript
@@ -150,7 +178,7 @@ For the full error API (`HTTP_CODES`, `extend`, `create`), see [Full documentati
 
 ### Framework integrations
 
-Blyp supports **Elysia**, **Hono**, **Express**, **Fastify**, **NestJS**, **Next.js**, **TanStack Start**, **SvelteKit**, and **Cloudflare Workers**. Example with Elysia:
+Blyp supports **Elysia**, **Hono**, **Express**, **Fastify**, **NestJS**, **Next.js**, **React Router**, **Astro**, **Nitro**, **Nuxt**, **TanStack Start**, **SvelteKit**, and **Cloudflare Workers**. Example with Elysia:
 
 ```typescript
 import { Elysia } from 'elysia';
@@ -162,6 +190,19 @@ const app = new Elysia()
   .listen(3000);
 ```
 
+Framework HTTP loggers also support path filtering:
+
+```typescript
+import { createLogger } from '@blyp/core/express';
+
+app.use(createLogger({
+  includePaths: ['/api/**'],
+  ignorePaths: ['/api/internal/**'],
+}));
+```
+
+`includePaths` works as an allowlist for automatic `http_request` and `http_error` logs. It uses the same wildcard matching as `ignorePaths`. When both are configured, Blyp logs only included paths and then removes any path that also matches `ignorePaths`.
+
 For other frameworks, client logging, advanced configuration, and utilities, see [Full documentation](docs/README.md).
 
 ### Expo
@@ -178,6 +219,125 @@ 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.
 
+### Durable connector retries
+
+Server-side connector delivery can be queued and retried with an internal Blyp-managed SQLite file. This is opt-in, uses at-least-once delivery semantics, and currently applies to server connector log forwarding only.
+
+```typescript
+import { createStandaloneLogger } from '@blyp/core/standalone';
+
+const logger = createStandaloneLogger({
+  connectors: {
+    betterstack: {
+      enabled: true,
+      sourceToken: process.env.BETTERSTACK_TOKEN,
+      ingestingHost: 'https://in.logs.betterstack.com',
+    },
+    delivery: {
+      enabled: true,
+      durableQueuePath: '.blyp/connectors.sqlite',
+      retry: {
+        maxAttempts: 8,
+        initialBackoffMs: 500,
+        maxBackoffMs: 30000,
+      },
+    },
+  },
+});
+```
+
+Notes:
+
+- Blyp stores the durable queue in its own SQLite file, not your app database.
+- Blyp uses an in-memory hot buffer first, then persists retryable connector failures to SQLite.
+- Older runtimes without built-in SQLite support fall back to memory-only retries with a warning.
+- Exception capture remains best-effort direct delivery in this first version.
+
+### AI tracing
+
+Use `@blyp/core/ai/vercel` for Vercel AI SDK middleware, or the provider wrappers when you want direct SDK instrumentation without a universal LLM abstraction.
+
+Common case:
+
+```typescript
+import { streamText } from 'ai';
+import { anthropic } from '@ai-sdk/anthropic';
+import { blypModel } from '@blyp/core/ai/vercel';
+
+const model = blypModel(anthropic('claude-sonnet-4-5'), {
+  operation: 'support_chat',
+});
+
+const result = streamText({
+  model,
+  prompt: 'Write a refund reply for this customer',
+});
+```
+
+Advanced middleware usage:
+
+```typescript
+import { wrapLanguageModel } from 'ai';
+import { anthropic } from '@ai-sdk/anthropic';
+import { blypMiddleware } from '@blyp/core/ai/vercel';
+
+const model = wrapLanguageModel({
+  model: anthropic('claude-sonnet-4-5'),
+  middleware: blypMiddleware({
+    operation: 'support_chat',
+  }),
+});
+```
+
+By default Blyp logs one structured `ai_trace` record per AI SDK call with provider, model, operation, token usage, finish reason, timing, and best-effort tool events. Prompt, response, reasoning, tool input, tool output, and stream chunk capture are off by default. When Blyp request context is active, AI traces inherit the active request-scoped logger automatically.
+
+Direct provider wrappers:
+
+```typescript
+import OpenAI from 'openai';
+import Anthropic from '@anthropic-ai/sdk';
+import { wrapOpenAI } from '@blyp/core/ai/openai';
+import { wrapAnthropic } from '@blyp/core/ai/anthropic';
+
+const openai = wrapOpenAI(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }), {
+  operation: 'draft_blog_intro',
+});
+
+const anthropic = wrapAnthropic(new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY }), {
+  operation: 'summarize_ticket',
+});
+```
+
+OpenRouter is supported through the OpenAI-compatible path:
+
+```typescript
+import OpenAI from 'openai';
+import { wrapOpenAI } from '@blyp/core/ai/openai';
+
+const client = wrapOpenAI(
+  new OpenAI({
+    apiKey: process.env.OPENROUTER_API_KEY,
+    baseURL: 'https://openrouter.ai/api/v1',
+  }),
+  {
+    provider: 'openrouter',
+    operation: 'route_experiment',
+  }
+);
+```
+
+Optional transport tracing:
+
+```typescript
+import OpenAI from 'openai';
+import { blypFetch } from '@blyp/core/ai/fetch';
+
+const client = new OpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+  fetch: blypFetch(fetch),
+});
+```
+
 ### 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.
@@ -221,7 +381,7 @@ export default {
 };
 ```
 
-In database mode, Blyp keeps connectors working as usual and replaces only the primary local persistence backend. Promise-based framework integrations 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.
+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:
 
@@ -234,6 +394,12 @@ blyp logs init --adapter drizzle --dialect mysql
 
 Use `connectors.betterstack` when you want Blyp logs forwarded into Better Stack through `@logtail/node`:
 
+Install the optional peer dependencies for this connector when you enable it:
+
+```bash
+bun add @logtail/node @sentry/node
+```
+
 ```typescript
 export default {
   connectors: {
@@ -302,6 +468,12 @@ The browser and Expo connector flow still posts to Blyp first. Blyp forwards to
 
 Use `blyp.config.ts` when you want to read the PostHog project key from the environment:
 
+Install the optional peer dependencies for this connector when you enable it:
+
+```bash
+bun add posthog-node @opentelemetry/api-logs @opentelemetry/exporter-logs-otlp-http @opentelemetry/resources @opentelemetry/sdk-logs
+```
+
 ```typescript
 export default {
   connectors: {
@@ -354,10 +526,74 @@ Client `error` and `critical` logs requested through the PostHog connector are p
 
 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:
+
+Install the optional peer dependency for this connector when you enable it:
+
+```bash
+bun add @databuddy/sdk
+```
+
+```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:
 
+Install the optional peer dependency for this connector when you enable it:
+
+```bash
+bun add @sentry/node
+```
+
 ```typescript
 export default {
   connectors: {
@@ -412,6 +648,12 @@ The browser and Expo Sentry flow still posts to Blyp first. Blyp forwards to Sen
 
 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:
 
+Install the optional peer dependencies for this connector when you enable it:
+
+```bash
+bun add @opentelemetry/api-logs @opentelemetry/exporter-logs-otlp-http @opentelemetry/resources @opentelemetry/sdk-logs
+```
+
 ```typescript
 export default {
   connectors: {
@@ -507,7 +749,23 @@ 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.
+GitHub Actions publishes the package to npm when a GitHub Release is published. Add an `NPM_TOKEN` repository secret before using the workflow. The publish workflow uses npm provenance attestation, and maintainers should rotate `NPM_TOKEN` every 90 days.
+
+## Security
+
+Security issues should be reported through GitHub's private advisory flow for this repository. Public issue reports are not the right channel for suspected vulnerabilities. Security details and disclosure expectations are in [SECURITY.md](SECURITY.md).
+
+## Runtime dependencies
+
+Blyp keeps its shipped runtime dependency surface small and documents each direct dependency:
+
+- `pino`: core structured logger engine
+- `pino-pretty`: human-readable local and development console output when `pretty` mode is enabled
+- `jiti`: runtime loading for `blyp.config.*` files and optional first-party subpath modules
+- `fflate`: gzip compression and decompression for archived log files and log reading
+- `zod`: runtime validation for shared and client payloads
+
+Optional connectors stay in `peerDependencies` so regular installs do not pull large connector-specific transitive trees by default.
 
 ## Contributing
 
@@ -526,6 +784,7 @@ This project is licensed under the MIT License — see the [LICENSE](LICENSE) fi
 - [GitHub Repository](https://github.com/Blyphq/blyp)
 - [NPM Package](https://www.npmjs.com/package/@blyp/core)
 - [Documentation](docs/README.md)
+- [Security Policy](SECURITY.md)
 - [Issues](https://github.com/Blyphq/blyp/issues)
 
 ---

package/STABILITY.md

@@ -0,0 +1,56 @@
+# Stability
+
+This document is Blyp's canonical compatibility contract for production adopters.
+
+## Why this exists
+
+During Blyp's early releases, the npm package name changed from `blyp-js` to `@blyp/core`, the CLI executable changed from `blyphq` to `blyp`, and TypeScript subpath declaration shims were fixed after release. Those changes created uncertainty about what production users can rely on.
+
+This file defines the stability guarantees for Blyp's public surfaces going forward.
+
+## Stability tiers
+
+| Area | Tier | Guarantee |
+| --- | --- | --- |
+| Core logger API (`logger.*`, `createStructuredLog`, `createError`) | Stable | No breaking changes without a major version bump |
+| Framework adapters (`@blyp/core/hono`, `/nextjs`, etc.) | Stable | Same guarantee |
+| Connector APIs | Stable | Same guarantee |
+| Studio UI | Beta | May change between minor versions |
+| CLI commands | Beta | Commands may be added/changed with minor version |
+| Internal APIs / unexported symbols | Unstable | No guarantees |
+
+## Deprecation policy
+
+- Stable APIs are deprecated before removal.
+- Deprecations are called out in GitHub release notes and changelog entries.
+- Deprecated Stable APIs remain available for at least one minor release before removal.
+- Removing a Stable API is a breaking change and therefore requires a major version bump.
+- Beta surfaces may change in a minor release without a deprecation window.
+- Unstable and internal surfaces may change at any time.
+
+## How breaking changes are communicated
+
+Blyp communicates breaking changes through these channels:
+
+- GitHub Releases in `Blyphq/blyp` are the authoritative release-note channel for package changes.
+- Changelog entries, including the docs changelog, provide the human-readable running history.
+- Migration notes are included when a release changes common adoption paths or requires user action.
+
+## Bun vs Node support
+
+"Blyp-first" means Blyp is designed around Bun as the primary optimization target while maintaining feature parity for Stable documented APIs on Bun and supported Node versions.
+
+- Stable documented APIs are intended to work on Bun and supported Node versions.
+- Bun may receive earlier runtime-specific optimizations or validation when runtime behavior differs.
+- Node support is not best effort for Stable surfaces.
+- If a documented capability cannot ship with Stable parity on Node, it must be documented as Beta or explicitly scoped to Bun before release.
+
+## Out of scope
+
+This contract does not cover:
+
+- private helpers
+- unexported symbols
+- internal file layout
+- undocumented implementation details
+- behavior that is present in source but not documented as part of a public API

package/dist/ai/anthropic/index.d.ts

@@ -0,0 +1,3 @@
+export { wrapAnthropic } from './wrap';
+export { blypFetch } from '../shared/fetch';
+export type { AIToolCallRecord, BlypLLMEventPart, BlypLLMTrace, BlypProviderOptions, BlypSDKContext, } from '../shared/types';

package/dist/ai/anthropic/normalize.d.ts

@@ -0,0 +1,9 @@
+import { normalizeTokenUsage } from '../shared/normalize';
+import type { AIToolCallRecord } from '../shared/types';
+export declare function normalizeAnthropicResponse(response: unknown): {
+    model?: string;
+    usage?: ReturnType<typeof normalizeTokenUsage>;
+    finishReason?: string;
+    output?: unknown;
+    toolCalls: AIToolCallRecord[];
+};

package/dist/ai/anthropic/stream.d.ts

@@ -0,0 +1,3 @@
+import { markSDKFirstChunk } from '../shared/trace';
+import type { BlypSDKContext } from '../shared/types';
+export declare function consumeAnthropicStreamChunk(state: Parameters<typeof markSDKFirstChunk>[0], context: BlypSDKContext, chunk: unknown): Promise<void>;

package/dist/ai/anthropic/wrap.d.ts

@@ -0,0 +1,13 @@
+import type { BlypProviderOptions } from '../shared/types';
+type AnthropicMessagesCreateParams = {
+    model?: string;
+    messages?: unknown;
+    stream?: boolean;
+};
+type WrappedAnthropicClient = {
+    messages?: {
+        create?: (params: AnthropicMessagesCreateParams, ...rest: unknown[]) => Promise<unknown>;
+    };
+};
+export declare function wrapAnthropic<TClient extends WrappedAnthropicClient>(client: TClient, options?: BlypProviderOptions): TClient;
+export {};