@breadstone/archipel-mcp 0.0.53 → 0.0.55

package/data/packages/platform-analytics/index.md

@@ -1,209 +0,0 @@
----
-title: platform-analytics
-description: Provider-agnostic analytics and error tracking with pluggable clients.
-order: 14
-tags: [analytics, error-tracking, sentry, application-insights, datadog, observability, providers, health]
-package: '@breadstone/archipel-platform-analytics'
----
-
-# platform-analytics
-
-Provider-agnostic analytics and error tracking module supporting multiple backends. Ships with Sentry, Azure Application Insights, and Datadog clients out of the box, plus a no-op fallback for environments where analytics is disabled.
-
-**Package:** `@breadstone/archipel-platform-analytics`
-
-<InstallTabs />
-
-## Quick Start
-
-```typescript
-import { Module } from '@nestjs/common';
-import { AnalyticsModule } from '@breadstone/archipel-platform-analytics';
-import { SentryAnalyticsClient, SENTRY_CONFIG_ENTRIES } from '@breadstone/archipel-platform-analytics/sentry';
-
-@Module({
-  imports: [
-    AnalyticsModule.register({
-      analyticsClient: SentryAnalyticsClient,
-      configEntries: SENTRY_CONFIG_ENTRIES,
-      isGlobal: true,
-    }),
-  ],
-})
-export class AppModule {}
-```
-
----
-
-## Module Configuration
-
-### IAnalyticsModuleOptions
-
-| Property          | Type                                  | Required | Default | Description                              |
-| ----------------- | ------------------------------------- | -------- | ------- | ---------------------------------------- |
-| `analyticsClient` | `Type<AnalyticsClientPort>`           | Yes      | —       | Concrete analytics client implementation |
-| `configEntries`   | `ReadonlyArray<IConfigRegistryEntry>` | No       | `[]`    | Provider-specific configuration entries  |
-| `isGlobal`        | `boolean`                             | No       | `false` | Register as a global module              |
-
----
-
-## AnalyticsClientPort API
-
-The abstract port that all analytics clients implement. Inject it anywhere:
-
-```typescript
-import { AnalyticsClientPort } from '@breadstone/archipel-platform-analytics';
-
-@Injectable()
-export class PaymentService {
-  constructor(private readonly _analytics: AnalyticsClientPort) {}
-
-  public async processPayment(): Promise<void> {
-    try {
-      // ... payment logic
-    } catch (error) {
-      this._analytics.captureException(error as Error, { feature: 'payments' });
-    }
-  }
-}
-```
-
-### Methods
-
-| Method             | Signature                                                                             | Description                             |
-| ------------------ | ------------------------------------------------------------------------------------- | --------------------------------------- |
-| `captureException` | `(error: Error, context?: Record<string, unknown>) => void`                           | Capture an error with optional context  |
-| `captureMessage`   | `(message: string, level: AnalyticsLevel, context?: Record<string, unknown>) => void` | Capture a message at a severity level   |
-| `setUser`          | `(user: IAnalyticsUser) => void`                                                      | Set the current user context            |
-| `clearUser`        | `() => void`                                                                          | Clear the current user context          |
-| `addBreadcrumb`    | `(breadcrumb: IAnalyticsBreadcrumb) => void`                                          | Add a breadcrumb to the analytics trail |
-
----
-
-## Built-in Providers
-
-### SentryAnalyticsClient
-
-Error tracking and performance monitoring via Sentry.
-
-```typescript
-import { SentryAnalyticsClient, SENTRY_CONFIG_ENTRIES } from '@breadstone/archipel-platform-analytics/sentry';
-
-AnalyticsModule.register({
-  analyticsClient: SentryAnalyticsClient,
-  configEntries: SENTRY_CONFIG_ENTRIES,
-});
-```
-
-**Environment variables:** `SENTRY_DSN`, `SENTRY_ENVIRONMENT`
-
-### AppInsightsAnalyticsClient
-
-Azure Application Insights integration.
-
-```typescript
-import {
-  AppInsightsAnalyticsClient,
-  APPINSIGHTS_CONFIG_ENTRIES,
-} from '@breadstone/archipel-platform-analytics/appinsights';
-
-AnalyticsModule.register({
-  analyticsClient: AppInsightsAnalyticsClient,
-  configEntries: APPINSIGHTS_CONFIG_ENTRIES,
-});
-```
-
-**Environment variables:** `APPLICATIONINSIGHTS_CONNECTION_STRING`
-
-### DatadogAnalyticsClient
-
-Datadog APM and error tracking.
-
-```typescript
-import { DatadogAnalyticsClient, DATADOG_CONFIG_ENTRIES } from '@breadstone/archipel-platform-analytics/datadog';
-
-AnalyticsModule.register({
-  analyticsClient: DatadogAnalyticsClient,
-  configEntries: DATADOG_CONFIG_ENTRIES,
-});
-```
-
-**Environment variables:** `DD_SERVICE`, `DD_ENV`
-
-### NoopAnalyticsClient
-
-Silent no-op client for environments where analytics is disabled:
-
-```typescript
-import { NoopAnalyticsClient } from '@breadstone/archipel-platform-analytics';
-
-AnalyticsModule.register({
-  analyticsClient: NoopAnalyticsClient,
-});
-```
-
----
-
-## Sub-path Imports
-
-Each provider is tree-shakeable via sub-path imports:
-
-| Import Path                                           | Contents                                               |
-| ----------------------------------------------------- | ------------------------------------------------------ |
-| `@breadstone/archipel-platform-analytics`             | Core module, port, models, NoopAnalyticsClient         |
-| `@breadstone/archipel-platform-analytics/sentry`      | SentryAnalyticsClient, SENTRY_CONFIG_ENTRIES           |
-| `@breadstone/archipel-platform-analytics/appinsights` | AppInsightsAnalyticsClient, APPINSIGHTS_CONFIG_ENTRIES |
-| `@breadstone/archipel-platform-analytics/datadog`     | DatadogAnalyticsClient, DATADOG_CONFIG_ENTRIES         |
-
----
-
-## Lifecycle & Shutdown
-
-All built-in clients implement `OnModuleInit` and `OnModuleDestroy`:
-
-| Phase       | Behavior                                                                    |
-| ----------- | --------------------------------------------------------------------------- |
-| **Init**    | SDK initialization is deferred to `onModuleInit()` — no constructor I/O     |
-| **Destroy** | Pending events are flushed and the SDK is closed with a 5-second timeout    |
-
-This ensures no events are lost during application shutdown and prevents hanging processes if the analytics backend is unreachable.
-
----
-
-## Health Check
-
-The `AnalyticsHealthIndicator` verifies that an `AnalyticsClientPort` is injected. If no analytics client is registered, it reports `disabled: true`. Import it from the `/health` subpath:
-
-```typescript
-import { AnalyticsHealthIndicator } from '@breadstone/archipel-platform-analytics/health';
-import { HealthModule } from '@breadstone/archipel-platform-health';
-
-@Module({
-  imports: [
-    AnalyticsModule.register({ /* ... */ }),
-    HealthModule.withIndicators([AnalyticsHealthIndicator]),
-  ],
-})
-export class AppModule {}
-```
-
-| Key | Check | Dependencies |
-| --- | ----- | ------------ |
-| `analytics` | `up` if `AnalyticsClientPort` injected, else `disabled` | `@Optional() AnalyticsClientPort` |
-
----
-
-## Exports Summary
-
-| Export                       | Type          | Description                                    |
-| ---------------------------- | ------------- | ---------------------------------------------- |
-| `AnalyticsModule`            | NestJS Module | Main module with `register()`                  |
-| `AnalyticsClientPort`        | Port          | Abstract analytics contract                    |
-| `NoopAnalyticsClient`        | Client        | No-op fallback implementation                  |
-| `SentryAnalyticsClient`      | Client        | Sentry provider (sub-path)                     |
-| `AppInsightsAnalyticsClient` | Client        | Azure Application Insights provider (sub-path) |
-| `DatadogAnalyticsClient`     | Client        | Datadog provider (sub-path)                    |
-| `AnalyticsLevel`             | Type          | Severity level union                           |
-| `IAnalyticsBreadcrumb`       | Interface     | Breadcrumb entry model                         |
-| `IAnalyticsUser`             | Interface     | User context model                             |
-| `AnalyticsHealthIndicator`   | Health        | Analytics readiness check (`/health` subpath)  |