opsdex-observe-client

Shared TypeScript PostHog client for Opsdex products, with a first React adapter for Backstage and other React frontends.

Why this package exists

This package is not meant to replace posthog-js. It standardizes how Opsdex teams use it.

• shared event naming
• shared global properties
• shared environment and release tags
• consistent page and funnel tracking
• one reusable React integration path

Recommended package structure

src/
  core/
    client.ts
    events.ts
    types.ts
  react/
    context.tsx
    hooks.ts
    index.ts
  index.ts

Installation

npm install @maximumsoft/opsdex-observe-client

One-key quick start

import { createOpsdexAnalyticsClient } from '@maximumsoft/opsdex-observe-client';

const analytics = createOpsdexAnalyticsClient('phc_xxx');

analytics.capture('app_loaded');

The client now auto-fills safe defaults when you only pass a key:

• context.app: inferred from browser hostname when possible
• context.env: inferred from runtime
• disabled mode when no key is provided

Build

pnpm build

Test

pnpm test

Start Next.js UI

cp .env.example .env.local
pnpm dev

Open http://localhost:3000

To enable live dashboard data from PostHog Query API, also set:

POSTHOG_API_HOST=https://us.posthog.com
POSTHOG_PERSONAL_API_KEY=<personal-api-key-with-query:read>

Core usage

import { createOpsdexAnalyticsClient, OPSDEX_EVENTS } from '@maximumsoft/opsdex-observe-client';

const analytics = createOpsdexAnalyticsClient({
  apiKey: 'phc_xxx',
  host: 'https://us.i.posthog.com',
  context: {
    app: 'opsdex-portal',
    env: 'local',
    release: 'dev',
  },
  eventPrefix: 'opsdex-portal',
});

analytics.capture(OPSDEX_EVENTS.SCAFFOLD_STARTED, {
  templateName: 'opsdex-service-layered-bootstrap',
});

Security defaults

The SDK applies guardrails by default:

• sensitive keys such as password, token, secret, authorization, and apiKey are redacted
• URL-like properties (path, url, href, etc.) have query strings stripped
• long string values are truncated
• payload properties are capped to prevent oversized events
• honors Do Not Track by default (respectDoNotTrack: true)

You can override with privacy, consent, and eventPrefix in init options.

React usage

import { createOpsdexAnalyticsClient } from '@maximumsoft/opsdex-observe-client';
import { OpsdexAnalyticsProvider, usePageTracking, useTrackEvent } from '@maximumsoft/opsdex-observe-client/react';

const analytics = createOpsdexAnalyticsClient({
  apiKey: 'phc_xxx',
  host: 'https://us.i.posthog.com',
  context: {
    app: 'opsdex-portal',
    env: 'local',
  },
  eventPrefix: 'opsdex-portal',
});

function CreatePage() {
  usePageTracking('create-page');
  const trackTemplateSelected = useTrackEvent('template_selected');

  return (
    <button onClick={() => trackTemplateSelected({ templateName: 'opsdex-web-bootstrap' })}>
      Select template
    </button>
  );
}

export function App() {
  return (
    <OpsdexAnalyticsProvider client={analytics}>
      <CreatePage />
    </OpsdexAnalyticsProvider>
  );
}

Vue usage

import { createApp } from 'vue';
import { createOpsdexAnalyticsClient } from '@maximumsoft/opsdex-observe-client';
import { createOpsdexAnalyticsPlugin } from '@maximumsoft/opsdex-observe-client/vue';

const analytics = createOpsdexAnalyticsClient({
  apiKey: 'phc_xxx',
  context: { app: 'opsx-mcp', env: 'local' },
  eventPrefix: 'opsx-mcp',
});

const app = createApp(App);
app.use(createOpsdexAnalyticsPlugin(analytics));

Suggested initial event taxonomy

• page_view
• template_selected
• scaffold_started
• scaffold_completed
• scaffold_failed
• quality_summary_viewed
• sonar_dashboard_opened
• gitops_pr_opened
• gitops_repository_opened
• argocd_link_opened

OpsDex + PostHog event flow

1. User opens Backstage landing or /create

• capture page_view

2. User chooses a template

• capture template_selected

3. User submits the scaffolder form

• capture scaffold_started

4. Backstage completes or fails the scaffolder run

• capture scaffold_completed or scaffold_failed

5. User reviews finish-page artifacts

• capture quality_summary_viewed

6. User opens delivery handoff links

• capture sonar_dashboard_opened
• capture gitops_pr_opened
• capture gitops_repository_opened
• capture argocd_link_opened

What to enable first in PostHog for Backstage

Enable first:

1. Events

• verify event names and properties are correct

2. Funnels

• measure conversion from template_selected to scaffold_completed

3. Dashboards

• combine usage, success rate, and GitOps handoff metrics

4. Insights

• graph event trends over time

Enable later:

1. Session Replay

• useful for UX debugging, but only after masking/privacy rules are defined

2. Feature Flags

• useful when rollout and experiments need analytics feedback

3. Experiments

• only after the funnel baseline is trusted

Why Next.js base

This repository now uses Next.js + TypeScript as the base UI because:

• it gives a fast React application shell for demoing PostHog flows
• it aligns with common frontend documentation from PostHog
• it keeps the shared analytics wrapper reusable inside a real app structure
• it can later host dashboard views, admin helpers, or replay/debug pages

Live dashboard data

The dashboard page at /dashboard now reads from PostHog Query API when these env vars are set:

• NEXT_PUBLIC_POSTHOG_PROJECT_ID
• POSTHOG_API_HOST
• POSTHOG_PERSONAL_API_KEY

The current live queries read:

• top template usage from template_selected
• funnel counts for template_selected, scaffold_started, scaffold_completed, and gitops_pr_opened
• failure hotspots from scaffold_failed

If POSTHOG_PERSONAL_API_KEY is missing, the dashboard renders an explicit unconfigured state instead of mock data.

Suggested next steps

1. Integrate this package into opsdex-portal as the first consumer.
2. Add event property schemas for scaffolder funnel analytics.
3. Add privacy guidance before enabling session replay in production.