API Reference

Installation

npm install @creed-space/vcp

Core Types

VCPContext

The main context object containing all user preferences and settings.

interface VCPContext {
  vcp_version: string;           // Protocol version
  profile_id: string;            // Unique identifier
  created?: string;              // ISO date
  updated?: string;              // ISO date

  constitution: ConstitutionReference;
  public_profile: PublicProfile;
  portable_preferences?: PortablePreferences;
  current_skills?: CurrentSkills;
  constraints?: ConstraintFlags;
  availability?: Availability;
  sharing_settings?: SharingSettings;
  private_context?: PrivateContext;
}

ConstitutionReference

interface ConstitutionReference {
  id: string;              // Constitution identifier
  version: string;         // Version string
  persona?: PersonaType;   // Interaction style
  adherence?: number;      // 1-5, how strictly to follow
  scopes?: ScopeType[];    // Applicable domains
}

PublicProfile

interface PublicProfile {
  display_name?: string;
  goal?: string;
  experience?: ExperienceLevel;  // beginner | intermediate | advanced | expert
  learning_style?: LearningStyle; // visual | auditory | hands_on | reading | mixed
  pace?: Pace;                   // intensive | steady | relaxed
  motivation?: Motivation;       // career | stress_relief | social | achievement | curiosity

  // Professional fields
  role?: string;
  team?: string;
  tenure_years?: number;
  career_goal?: string;
  career_timeline?: string;
}

PortablePreferences

interface PortablePreferences {
  noise_mode?: NoiseMode;           // normal | quiet_preferred | silent_required
  session_length?: SessionLength;   // 15_minutes | 30_minutes | 60_minutes | flexible
  pressure_tolerance?: PressureTolerance; // high | medium | low
  budget_range?: BudgetRange;       // unlimited | high | medium | low | free_only
  feedback_style?: FeedbackStyle;   // direct | encouraging | detailed | minimal
}

ConstraintFlags

interface ConstraintFlags {
  time_limited?: boolean;
  budget_limited?: boolean;
  noise_restricted?: boolean;
  energy_variable?: boolean;
  schedule_irregular?: boolean;
  mobility_limited?: boolean;
  health_considerations?: boolean;
}

PrivateContext

interface PrivateContext {
  _note?: string;        // Internal documentation
  [key: string]: unknown; // Any private values
}

Encoding Functions

encodeContextToCSM1

Encodes a VCP context into CSM-1 token format.

import { encodeContextToCSM1 } from '@creed-space/vcp';

const token = encodeContextToCSM1(context);
// Returns:
// VCP:1.0:user_001
// C:learning-assistant@1.0
// P:godparent:3
// ...

Parameters

Returns

string — CSM-1 formatted token

formatTokenForDisplay

Wraps a CSM-1 token in a box for visual display.

import { formatTokenForDisplay } from '@creed-space/vcp';

const boxed = formatTokenForDisplay(token);
// Returns:
// ┌────────────────────────────────────────┐
// │ VCP:1.0:user_001                       │
// │ ...                                    │
// └────────────────────────────────────────┘

parseCSM1Token

Parses a CSM-1 token back into key-value components.

import { parseCSM1Token } from '@creed-space/vcp';

const parsed = parseCSM1Token(token);
// Returns:
// {
//   VCP: "1.0:user_001",
//   C: "learning-assistant@1.0",
//   P: "muse:3",
//   ...
// }

Utility Functions

getEmojiLegend

Returns an array of emoji shortcodes and their meanings.

import { getEmojiLegend } from '@creed-space/vcp';

const legend = getEmojiLegend();
// Returns:
// [
//   { emoji: '<i class="fa-solid fa-volume-xmark" aria-hidden="true"></i>', meaning: 'quiet mode' },
//   { emoji: '<i class="fa-solid fa-coins" aria-hidden="true"></i>', meaning: 'budget tier' },
//   ...
// ]

getTransmissionSummary

Analyzes a context and returns what would be transmitted vs withheld.

import { getTransmissionSummary } from '@creed-space/vcp';

const summary = getTransmissionSummary(context);
// Returns:
// {
//   transmitted: ['goal', 'experience', 'learning_style'],
//   withheld: ['work_situation', 'housing_situation'],
//   influencing: ['budget_limited', 'time_limited']
// }

Constants

CONSTRAINT_EMOJI

Mapping of constraint flags to emoji shortcodes.

const CONSTRAINT_EMOJI = {
  noise_restricted: '<i class="fa-solid fa-volume-xmark" aria-hidden="true"></i>',
  budget_limited: '<i class="fa-solid fa-coins" aria-hidden="true"></i>',
  energy_variable: '<i class="fa-solid fa-bolt" aria-hidden="true"></i>',
  time_limited: '⏰',
  schedule_irregular: '<i class="fa-solid fa-calendar" aria-hidden="true"></i>',
  mobility_limited: '<i class="fa-solid fa-person-walking" aria-hidden="true"></i>',
  health_considerations: '<i class="fa-solid fa-pills" aria-hidden="true"></i>'
}

PRIVATE_MARKER / SHARED_MARKER

const PRIVATE_MARKER = '<i class="fa-solid fa-lock" aria-hidden="true"></i>';
const SHARED_MARKER = '<i class="fa-solid fa-check" aria-hidden="true"></i>';

Enums

PersonaType

type PersonaType = 'godparent' | 'sentinel' | 'ambassador' | 'anchor' | 'nanny';

ExperienceLevel

type ExperienceLevel = 'beginner' | 'intermediate' | 'advanced' | 'expert';

LearningStyle

type LearningStyle = 'visual' | 'auditory' | 'hands_on' | 'reading' | 'mixed';

NoiseMode

type NoiseMode = 'normal' | 'quiet_preferred' | 'silent_required';

SessionLength

type SessionLength = '15_minutes' | '30_minutes' | '60_minutes' | 'flexible';

BudgetRange

type BudgetRange = 'unlimited' | 'high' | 'medium' | 'low' | 'free_only';

ScopeType

type ScopeType = 'work' | 'education' | 'creativity' | 'health' | 'privacy'
  | 'family' | 'finance' | 'social' | 'legal' | 'safety';

Audit Types

AuditEntry

interface AuditEntry {
  id: string;
  timestamp: string;              // ISO date
  event_type: AuditEventType;
  platform_id?: string;
  data_shared?: string[];         // Fields that were shared
  data_withheld?: string[];       // Fields that were withheld
  private_fields_influenced?: number; // Count of private fields that shaped output
  private_fields_exposed?: number;    // Always 0 in valid VCP
  details?: Record<string, unknown>;
}

AuditEventType

type AuditEventType =
  | 'context_shared'
  | 'context_withheld'
  | 'consent_granted'
  | 'consent_revoked'
  | 'progress_synced'
  | 'recommendation_generated'
  | 'skip_requested'
  | 'adjustment_recorded';

Platform Types

PlatformManifest

interface PlatformManifest {
  platform_id: string;
  platform_name: string;
  platform_type: 'learning' | 'community' | 'commerce' | 'coaching';
  version: string;
  context_requirements: {
    required: string[];
    optional: string[];
  };
  capabilities: string[];
  branding?: {
    primary_color: string;
    logo?: string;
  };
}

FilteredContext

The context as seen by a specific stakeholder after privacy filtering.

interface FilteredContext {
  public: Partial<PublicProfile>;
  preferences: Partial<PortablePreferences>;
  constraints: ConstraintFlags;
  skills?: Partial<CurrentSkills>;
}

Next Steps

• Playground — Test the API interactively
• Core Concepts — Understand the architecture
• Demos — See real-world examples