@wolfcola/devtools-types

Shared Effect Schema definitions and TypeScript types for WolfCola 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 @wolfcola/devtools-types

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 '@wolfcola/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;
  }
}

Event types

| type | source | Description | | ------------------- | --------- | ------------------------------------- | | network:request | network | Outbound HTTP request captured by HAR | | network:response | network | HTTP response with status + headers | | network:cors-flag | network | Detected CORS policy violation | | sdk:node-change | sdk | DaVinci node status transition | | sdk:config | sdk | SDK client configuration snapshot | | sdk:journey-step | sdk | AM authentication tree step result | | sdk:oidc-state | sdk | OIDC/OAuth endpoint outcome | | dom:form-submit | dom | Form submission detected in the page | | dom:redirect | dom | Client-side redirect detected | | session:cookie | session | document.cookie changed | | session:storage | session | localStorage key changed |

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;
}

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)
}

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;
}

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
}

SessionData

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

SdkConfigData

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

DomData

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

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 '@wolfcola/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
}

Exported symbols

| Export | Kind | Description | | ------------------------ | ------ | ------------------------------------ | | AuthEventSchema | Schema | Full envelope validator | | AuthEventTypeSchema | Schema | Union of all event type literals | | AuthEventFlagsSchema | Schema | { isCors, isError, isAuthRelated } | | NetworkDataSchema | Schema | Network event data | | SdkDataSchema | Schema | DaVinci SDK node data | | SdkConfigDataSchema | Schema | SDK config snapshot | | JourneyDataSchema | Schema | AM journey step data | | OidcDataSchema | Schema | OIDC/OAuth phase data | | SessionDataSchema | Schema | Cookie / localStorage diff | | DomDataSchema | Schema | DOM event data | | SdkErrorSchema | Schema | Error object sub-schema | | SdkAuthorizationSchema | Schema | Authorization code/state sub-schema | | AuthEvent | Type | Inferred from AuthEventSchema | | AuthEventType | Type | Inferred from AuthEventTypeSchema | | AuthEventFlags | Type | Inferred from AuthEventFlagsSchema | | NetworkData | Type | Inferred from NetworkDataSchema | | SdkData | Type | Inferred from SdkDataSchema | | JourneyData | Type | Inferred from JourneyDataSchema | | OidcData | Type | Inferred from OidcDataSchema | | SessionData | Type | Inferred from SessionDataSchema | | SdkConfigData | Type | Inferred from SdkConfigDataSchema | | DomData | Type | Inferred from DomDataSchema | | FlowStateSchema | Schema | Aggregated event collection | | FlowState | Type | Inferred from FlowStateSchema | | FlowExportSchema | Schema | Versioned export envelope | | FlowExport | Type | Inferred from FlowExportSchema | | OidcSemanticsSchema | Schema | OIDC phase annotation | | OidcSemantics | Type | Inferred from OidcSemanticsSchema | | CorsFlagSchema | Schema | CORS violation data | | CorsFlag | Type | Inferred from CorsFlagSchema |

Consumers

This package is used by all other packages in the monorepo:

• devtools-core — annotators and diagnosis engine operate on these types
• devtools-extension — browser extension
• vscode-extension — VS Code extension
• devtools-bridge — SDK adapter emits AuthEvents