@forgerock/devtools-types

Shared Effect Schema definitions and TypeScript types for Ping DevTools. This package is the single source of truth for the shape of every event that flows between the SDK bridges and the DevTools extension.

Contents

• Installation
• AuthEvent
• Data variants
  • NetworkData
  • SdkData — DaVinci
  • JourneyData — AM trees
  • OidcData — OIDC/OAuth
  • SessionData
  • SdkConfigData
  • DomData
• Runtime validation
• Exported symbols

Installation

pnpm add @forgerock/devtools-types
Copy

effect is a peer dependency — add it to your project if it isn't already present.

AuthEvent

Every event, regardless of source, conforms to the AuthEvent envelope:

import type { AuthEvent } from '@forgerock/devtools-types';

// Shape
{
  id: string; // crypto.randomUUID()
  timestamp: number; // performance.now()
  type: AuthEventType; // e.g. 'sdk:node-change', 'network:response'
  source: 'network' | 'sdk' | 'dom' | 'session';
  flowId: string | null;
  causedBy: string | null;
  data: NetworkData | SdkData | JourneyData | OidcData | SessionData | SdkConfigData | DomData;
  flags: {
    isCors: boolean;
    isError: boolean;
    isAuthRelated: boolean;
  }
}
Copy

Event types

Data variants

The data field is a discriminated union — use _tag to narrow it.

NetworkData

{
  _tag: 'network';
  url: string;
  method: string;
  status: number;
  requestHeaders: Record<string, string>;
  responseHeaders: Record<string, string>;
  duration: number;
  corsFlag?: CorsFlag;
  requestBody?: unknown;
  responseBody?: unknown;
}
Copy

CorsFlag carries the reason ('status-zero' | 'missing-allow-origin' | 'credentials-mismatch' | 'wildcard-with-credentials' | 'preflight-failed') plus optional preflight details.

SdkData — DaVinci

Emitted on every DaVinci node status transition by attachDevToolsBridge.

{
  _tag: 'sdk';
  nodeStatus: string;         // 'next' | 'error' | 'success' | ...
  previousStatus?: string;
  interactionId?: string;
  interactionToken?: string;
  nodeId?: string;
  requestId?: string;         // DaVinci cache key (maps to raw HTTP response)
  nodeName?: string;
  nodeDescription?: string;
  eventName?: string;
  httpStatus?: number;
  collectors?: unknown[];     // Form fields / UI descriptors
  error?: SdkError;
  authorization?: SdkAuthorization;
  session?: string;
  responseBody?: unknown;     // Full DaVinci server response (from cache)
}
Copy

JourneyData — AM trees

Emitted by attachJourneyBridge for each RTK Query mutation that settles.

{
  _tag: 'journey';
  stepType: 'Step' | 'LoginSuccess' | 'LoginFailure';
  callbacks?: unknown[];    // Full AM callback objects (with input/output arrays)
  authId?: string;          // Present on Step
  tokenId?: string;         // Present on LoginSuccess (session token)
  successUrl?: string;      // Present on LoginSuccess
  realm?: string;
  stage?: string;
  header?: string;
  description?: string;
  errorCode?: number;       // Present on LoginFailure
  errorMessage?: string;
  errorReason?: string;
}
Copy

OidcData — OIDC/OAuth

Emitted by attachOidcBridge for each RTK Query mutation that settles.

{
  _tag: 'oidc';
  phase: 'authorize' | 'exchange' | 'revoke' | 'userinfo' | 'logout';
  status: 'success' | 'error';
  clientId?: string;
  errorCode?: string;     // OAuth error code (e.g. 'invalid_grant')
  errorMessage?: string;  // Human-readable error description
}
Copy

SessionData

{
  _tag: 'session';
  key: string;      // localStorage key or 'document.cookie'
  before?: string;
  after?: string;
}
Copy

SdkConfigData

{
  _tag: 'sdk-config';
  config: unknown; // The raw config object passed to attachDevToolsBridge
}
Copy

DomData

{
  _tag: 'dom';
  element?: string;   // CSS selector of the form element
  url?: string;       // Redirect target URL
}
Copy

Runtime validation

All schemas are Effect Schema definitions — use them directly for decoding untrusted data at message boundaries.

import { Schema } from 'effect';
import { AuthEventSchema } from '@forgerock/devtools-types';

const decode = Schema.decodeUnknownEither(AuthEventSchema);

// In a service worker or message handler:
const result = decode(rawMessage);
if (Either.isLeft(result)) {
  // validation failed — result.left carries detailed parse errors
} else {
  const event = result.right; // AuthEvent, fully typed
}
Copy

Exported symbols